feat: add official Codex skill and harden task execution
Install and update artemis-use with task diagnostics and plugin guidance. Preserve cross-device file receipts, review canonical reports, guard stage transitions and reduce small history summaries. Improve exploration lifecycle, request recovery and browser live connections.
This commit is contained in:
chenmingxuan committed
1 parent
2328a4df0c
commit
e1ea099592
128 files changed
+4944
-700
No files matched your search
+25
-9
@@ -1,12 +1,14 @@
|
||||
# 使用 AI 完成 Android 自动化
|
||||
|
||||
源码内的 `skills/artemis-automation/` 是可分发 Skill，不依赖本机 Codex 的私有能力。将整个目录复制到宿主支持的 Skill 目录即可；Codex 为 `$CODEX_HOME/skills/`（未配置时 `~/.codex/skills/`）。仓库包含 Skill，启动程序不会修改用户的全局 Skill 目录。
|
||||
官方 `skills/artemis-use/` 随源码和 wheel 分发，包含执行、探索、诊断复盘及插件开发规范、模板和校验脚本。启动脚本、直接 `artemis ui` / `artemis-admin` 启动服务、显式 `artemis mcp --install codex` 共用同步逻辑；MCP 桥连接/握手不安装、不启动主程序。
|
||||
|
||||
目前仅支持 Codex MCP 配置。Windows 一键脚本检测并同步 Codex；未检测到配置目录时，在项目目录执行 `uv run artemis mcp --install codex`。配置模板使用 `uv run artemis mcp --generate-config codex` 查看；其他名称和 `all` 不再支持。更新后重新加载 Codex MCP；复制 Skill 后重新加载技能。
|
||||
默认安装到 `~/.agents/skills/artemis-use`；已有 `~/.codex/skills/artemis-use` 时复用该目录，显式设置 `CODEX_HOME` 时使用 `$CODEX_HOME/skills/artemis-use`。官方同名目录直接覆盖，不保留用户定制、不弹冲突提示；其他 Skill 不受影响。复制和内容校验成功后替换目录，内容未变不重写；同步失败保留旧版并告警，网页仍启动。记录版本与来源，较旧 ARTEMIS 不覆盖已安装的较新版官方 Skill；默认路径中的重复 artemis-use 合并为一份。Skill 成功安装后备份并移除 Codex 全局 AGENTS 文件内带 ARTEMIS 标记的旧规则块，保留其他内容。
|
||||
|
||||
目前只支持 Codex。源码环境执行 `uv run artemis mcp --install codex` 可手动修复集成，`--generate-config codex` 查看配置模板。安装器保留 MCP 启用/禁用、工具 allowlist/denylist 和审批策略；配置变化后重载 MCP，Skill 未显示时重启 Codex。`-SkipMcpSync` 跳过该次启动的 MCP 和 Skill 同步；直接启动可设置 `ARTEMIS_SKIP_CODEX_SYNC=1`。
|
||||
|
||||
可以向 AI 这样下达任务：
|
||||
|
||||
> 使用 artemis-automation。在我指定的模拟器上验证系统设置首页能打开，不修改设置，输出 Word 和 Excel 报告。
|
||||
> 使用 artemis-use。在我指定的模拟器上验证系统设置首页能打开，不修改设置，输出 Word 和 Excel 报告。
|
||||
|
||||
> 校验这份 Excel 的测试用例，指出所有错误；先不执行。
|
||||
|
||||
@@ -27,14 +29,14 @@ Flash 和 Pro 都支持任务内的安卓文件工具 `android_file`：保存原
|
||||
| 工具 | 功能 |
|
||||
| --- | --- |
|
||||
| `mobile_diagnose` | 环境、凭据、设备诊断和自带修复 |
|
||||
| `mobile_workspace` | 设备列表、统一队列、插件配置和资源保护状态 |
|
||||
| `mobile_workspace` | 设备列表、统一队列、插件状态及按需连接诊断；include_development 返回插件开发环境 |
|
||||
| `mobile_config` | 读取或明确保存非敏感模型、功能、报告默认设置 |
|
||||
| `mobile_run_task` | 单任务执行；`model=flash/pro` 表示执行模式 |
|
||||
| `mobile_manage_task` | 单任务状态、安全暂停、排队恢复、指导提交/领取记录和停止 |
|
||||
| `mobile_run_task` | 单任务执行（request_id 去重）；`model=flash/pro` 表示执行模式 |
|
||||
| `mobile_manage_task` | 单任务状态、提交反查、暂停/继续、指导和停止；删除预览及删除、代录用户人工复验 |
|
||||
| `mobile_get_device_state` | 设备截图、界面层级 |
|
||||
| `mobile_task_file` | XLSX 模板与导入校验 |
|
||||
| `mobile_batch` | JSON 用例建批次、开始、暂停、继续、复制失败项、删除非活跃批次 |
|
||||
| `mobile_search_history` | 全库搜索、日期/状态筛选和分页 |
|
||||
| `mobile_search_history` | 全库搜索、日期/状态/批次筛选和分页 |
|
||||
| `mobile_inspect_trace` | 只读步骤、截图和执行证据 |
|
||||
| `mobile_export_report` | Word、Excel、步骤截图、录屏片段、单任务资料及批次 ZIP，返回本地绝对路径 |
|
||||
| `mobile_exploration` | 探索对话、指导、人工示范、暂停续跑、用例版本、Flash/Pro 复跑和批次草稿 |
|
||||
@@ -49,9 +51,9 @@ Python 按 `uv.lock` 同步缺失/变化的依赖；前端依据源码、资源
|
||||
|
||||
scrcpy 固定版本的国内下载采用多个来源，失败或 SHA256 不符时自动尝试下一来源，全部失败会显示 HTTP 状态、超时或校验原因。`config/downloads.json` 的 `overrides.scrcpy_url` 指定首选 HTTPS 地址，`overrides.scrcpy_fallback_urls` 指定备用地址数组；`null` 使用默认备用源，`[]` 禁用备用源。国内模式不自动回退到 GitHub 直连。
|
||||
|
||||
MCP 同步仅检查 `$CODEX_HOME/config.toml`；未设置或为空时使用当前用户的 `~/.codex/config.toml`。日志会显示实际路径，以及新装、更新、已是最新、未检测到或自定义跳过的结果。检测到目录但缺少 ARTEMIS 条目时安装当前源码的标准配置；已有标准配置即使指向旧解压目录，也会更新解释器、项目目录、环境路径和工具清单。保留用户额外环境变量、禁用状态、`tools` 下的工具审批策略及其他服务；不会重建权限表、添加 `eager` 或删除旧工具策略。自定义启动包装器保持原样并提示。其他客户端的配置和规则文件不读取、不修改，其格式错误不会阻止启动。Codex 原配置无法解析，或同步程序生成的更新未通过校验时，均停止启动且不覆盖原文件；日志会区分这两种原因，不把同步生成错误归因于用户配置。遇到后者请更新 ARTEMIS，不要删除有效的 `config.toml`；可使用 `-SkipMcpSync` 临时仅启动网页。首次修改保留备份。同步后需在 Codex 中重新加载 MCP 或重启 Codex，脚本无法替宿主重启已加载的 MCP 进程。
|
||||
MCP 同步仅检查 `$CODEX_HOME/config.toml`；未设置或为空时使用当前用户的 `~/.codex/config.toml`。日志会显示实际路径，以及新装、更新、已是最新、未检测到或自定义跳过的结果。检测到目录但缺少 ARTEMIS 条目时安装当前源码的标准配置；已有标准配置即使指向旧解压目录，也会更新解释器、项目目录和环境路径，保留已有工具白名单。保留用户额外环境变量、禁用状态、`tools` 下的工具审批策略及其他服务；不会重建权限表、添加 `eager` 或删除旧工具策略。自定义启动包装器保持原样并提示。其他客户端的配置和规则文件不读取、不修改，其格式错误不会阻止启动。Codex 原配置无法解析，或同步程序生成的更新未通过校验时，均告警且不覆盖原文件，继续启动网页；日志会区分这两种原因，不把同步生成错误归因于用户配置。遇到后者请更新 ARTEMIS，不要删除有效的 `config.toml`；可使用 `-SkipMcpSync` 临时仅启动网页。首次修改保留备份。同步后需在 Codex 中重新加载 MCP 或重启 Codex，脚本无法替宿主重启已加载的 MCP 进程。
|
||||
|
||||
创建批次时必须提供唯一 `request_id`；请求超时后可以按编号查询或用相同内容重发，避免重复用例。创建只保存草稿，`start` 才执行。AI 无需先制造 Excel，也可直接提交 JSON；字段与示例见 [Skill 批量任务参考](../skills/artemis-automation/references/batches.md)。
|
||||
创建批次时必须提供唯一 `request_id`；请求超时后可以按编号查询或用相同内容重发，避免重复用例。创建只保存草稿，`start` 才执行。AI 无需先制造 Excel，也可直接提交 JSON；字段与示例见 [Skill 批量任务参考](../skills/artemis-use/references/batches.md)。
|
||||
|
||||
报告按任务或批次归档到 `artifacts/mcp_exports/`，包含本地路径及服务下载链接；删除批次时会清理对应导出副本。运行中导出是快照；执行完成不等于验证通过，报告会保留未验证、失败、跳过与中断状态。
|
||||
|
||||
@@ -106,3 +108,17 @@ Flash、Pro（启用 transcript）和探索共用分阶段上下文。一个阶
|
||||
有请求诊断的调用同时发送 `X-Client-Request-Id`，默认与 trace 内的 `request_id` 一致，便于对照 API 日志。`request_sent_at` 表示实际发送时间；`routing_header_fingerprints` 只记录发送的会话头的哈希，`client_request_id_matches` 表示关联 ID 是否一致。不记录认证头或其他请求头正文。稳定标识提供路由亲和条件，实际命中仍取决于前缀和上游缓存。
|
||||
|
||||
辅助摘要继续独立处理各自片段，避免为了提高命中比例累积不相关的历史。视觉摘要中完全重复的插件执行结果与控件树只发送一份；独立错误、状态、不同观察及原始 trace 均保留。
|
||||
|
||||
## 指定任务诊断、复盘与管理
|
||||
|
||||
流式请求中的 `click`、`long_press`、`swipe`、`press_key`、`manage_app`、`wait_for_delay` 每次调用参数超过 16,384 字符时，会立即关闭该请求并丢弃未完成输出，避免持续生成异常参数直到超时。该保护只针对小型设备动作，不限制输入文本、笔记、报告或插件参数，也不改变模型思考强度与输出 token 配置。异常最多额外尝试一次（配置为不重试时不重试）；仍异常时进入现有备用模型或暂停恢复流程。诊断记录保留 `invalid_output` 分类及 `stream_guard` 中的工具名、实际字符数和保护上限，不保存参数正文；无法据此断定异常来自模型生成还是 API 中转。
|
||||
|
||||
`mobile_inspect_trace` 增加 `view_report`、`view_usage`、`view_requests`、`view_logs`、`view_evidence`。这些动作复用 HTTP `/api/sessions/{id}/inspection`，不生成下载文件、不执行设备动作；`offset/limit` 控制分页。日志只读取有限尾部并脱敏，正文超限明确 text_truncated。用量展示缓存输入/总输入、角色及已记录的模型分组；未记录模型显示 unknown。
|
||||
|
||||
`mobile_run_task(request_id=...)` 在既有自动化存储中登记提交回执。同一个 ID/相同内容只派发一次；内容不同拒绝。连接断开先用 `mobile_manage_task(action="lookup", request_id=...)` 找 trace_id，查实际状态，未知结果不自动重跑。普通状态与报告统一读取人工复验结果，保留 AI 原判。
|
||||
|
||||
`mobile_manage_task(deletion_preview/delete)` 可预览和删除非活动任务；探索也有对应动作，并保留独立复跑。`delete` 需要 user_confirmed=true，表明用户明确要求删除，不强制重复确认。`review` 只代录用户明确给出的 review_status=passed/failed 和 review_reason，需 user_confirmed=true；Agent 自己的推断不能标成人工结论。
|
||||
|
||||
## 插件开发
|
||||
|
||||
使用官方 Skill 的 [插件开发参考](../skills/artemis-use/references/plugin-development.md)，从自带模板开始。通过 `mobile_workspace(include_devices=false, include_development=true)` 找到当前服务的 Python；在任意目录均可调用 Skill 自带校验脚本。静态检查、MCP 握手与真实操作验收分别报告。市场发布需用户明确要求，验证未覆盖场景必须注明。
|
||||
@@ -2,6 +2,12 @@
|
||||
|
||||
工作区右侧或顶部的 **报告与自动化** 入口包含结论报告、批量任务。历史任务在任务队列中按浏览器本地日期分组，支持名称、目标、编号和标签搜索，以及日期、状态筛选和分页。
|
||||
|
||||
## 多页面与加载排查
|
||||
|
||||
同一浏览器、同一服务地址的可见页面共享一条任务实时连接；持有连接的页面关闭后，其他页面自动接管。后台页面暂停实时订阅和设备画面预览，返回前台时重新读取任务状态、步骤和结论，不影响后台任务执行或录屏。旧浏览器不支持共享连接时，仍会释放后台页面的实时连接。
|
||||
|
||||
配置读取、状态和队列轮询有 15 秒的网页请求时限，重复轮询不会堆积；它与模型执行超时无关。若升级后旧页面一直显示“正在读取配置”，而后端诊断正常，请先保存尚未提交的输入，关闭旧 ARTEMIS 标签页，再重新打开网页。重启后台不会替换已打开页面中的旧脚本，旧版页面的长连接可能占满浏览器连接额度，拖慢其他页面。
|
||||
|
||||
## 导出结论报告
|
||||
|
||||
选择已有任务，在“报告与质量”中下载 Word、Excel、按步骤排序的截图 ZIP、录屏分段 ZIP，或一键下载包含上述文件和清单的资料 ZIP。只有启用并成功保存录屏的任务才有录屏可下载。默认报告格式为 Word 和 Excel；勾选所需格式并保存，后续提交使用新的默认值。
|
||||
@@ -28,6 +34,12 @@
|
||||
|
||||
探索模式将固定规则放在上下文前部，用户指导变更追加到历史末尾；AI 进度消息计数不再改写前缀。同一次探索恢复后沿用按探索、角色与模型生成的 `prompt_cache_key`，该哈希值也写入请求诊断，便于核对路由。缓存仍取决于服务端的支持和实际命中，不能视为已节省的 token。输入总量包含缓存输入，不能重复相加；结构化调用也按原始响应的 usage 计量一次，旧任务中漏计的用量不会自动回填。300k 是单次上下文限制，并非整个任务累计预算。
|
||||
|
||||
Flash 跨端任务由模型通过内部 `update_task_progress` 记录短阶段清单（`notes/task_progress.md`），仅在阶段边界或重新规划时更新，可与下一动作一起提交。执行器允许其他资源的只读预检，但会暂缓不属于当前阶段的操作，避免预检顺势变成整段跨端执行。阶段顺序来自任务要求；确实需要交替操作时，同一阶段可以包含多个资源。完成检查与产品通过仍是两回事。
|
||||
|
||||
若最终报告已由 `save_note` 保存，Flash 用 `report_task_status.report_note_key` 引用该正文，界面结论与 `notes/output.md` 使用相同内容。最终 Checker 可在同次验收中提出有步骤/截图/回执依据的局部事实纠正；只有唯一匹配原文的修改才应用，原稿保留为 `notes/output_before_review.md`，修改依据记入 `run_outcome.json` 的 `report_review`。这不会改写操作历史或抹除真实测试失败。
|
||||
|
||||
插件工具的运行时文件回执独立于可截断的观察文本，并在历史压缩后保留路径和校验信息；相同的界面树不在文本与结构化结果中重复发送。历史分段默认至少积累 6 个可压缩回合、源文本目标 6000 token，再结合现有大小/压力条件准备摘要；阶段结束和紧急压缩可提前触发。普通回合仍保持只追加历史。这个调整减少过细的摘要请求，不改变执行模型、思考强度或最终检查；实际 token 和缓存改善需以新任务用量为准。
|
||||
|
||||
## Excel 批量导入
|
||||
|
||||
1. 点击“下载 Excel 模板”，保留“任务”工作表及表头顺序。
|
||||
|
||||
@@ -32,6 +32,18 @@
|
||||
|
||||
主区域的用例卡可复制提示词，点击「查看 / 编辑」展开编辑器并保存新版本，旧版本不可变。选择已保存版本和 Flash/Pro 模式，可以指定复跑模型，也可使用普通默认模型。复跑固定版本与配置，结果与探索验收分开显示。前置条件会纳入探索用例的复跑提示词。
|
||||
|
||||
自动提炼的提示词使用已确认的实际 URL、包名和业务输入，设备/电脑使用本次任务绑定；未指定输出位置时，报告与证据默认保存在本次任务 trace。不会生成需要另行替换的 `${名称}` 参数，也不把旧任务的窗口 ID 或证据路径当成本轮环境。生成器遇到占位符会修订一次，仍无法生成可执行提示词时保留原版本并提示重新提炼，不改变探索的实际验收结果。旧版或手动草稿中尚有占位符时，复跑/加入批次会在执行前列出未填参数；可编辑保存新版本或重新提炼。
|
||||
|
||||
Flash、Pro 和探索共用的验收会直接收到精简文件回执，包括来源步骤、保存位置、大小和校验信息；回执只证明对应位置的文件操作，报告内容及页面结论仍须核对证据。布局问题需要结合前后画面、可阅读/操作性及用户标准；内容随滚动经过固定导航后方不单独构成缺陷。证据不足保留「未验证」，不会自动改判为通过。
|
||||
|
||||
复跑用例保留业务操作、报告要求和通过标准，不继承探索阶段的提问、人工示范、提炼下一份用例等收尾工作；如果文档生成本身就是被测产品的功能，则保留该业务验收。旧版用例不会自动改写，可重新提炼或编辑保存新版本。
|
||||
|
||||
Flash 的最终答复会在验收前保存到当前任务的 `notes/output.md`；需要额外交付文本文件时，可用 `save_note` 保存到同一任务的 `notes/`，返回实际路径、大小、SHA-256 和读回校验结果。`output` 保留给最终答复，独立文件使用其他名称。写入失败会明确传给验收，不虚构文件已保存，也不额外调用模型生成同一份报告。
|
||||
|
||||
文本保存调用也记录为任务步骤，供验收与历史检索读取回执，不为此操作手机或抓取无关画面。验收收到完整 JSON 结论时优先在本地校验；可无损转换逐项结论的 `verdict` 字段别名和证据文本列表，避免仅因格式差异再次请求模型。冲突状态、非法值、截断输出或缺少检查项仍不能当作有效结论。
|
||||
|
||||
步骤截图本身已是保存的证据。前后两次截图内容相同时可能共用一个文件，验收仍保留两次采集记录；除非任务明确要求独立命名或指定导出位置，不要求另存一份图片。执行者遗漏步骤或报告未交付，按实际情况判为阻塞或未验证；只有证据反驳业务预期时才判测试失败。
|
||||
|
||||
「加入新批次草稿」只创建批次，在「报告与批量」确认后启动。结束后仍可在对话中讨论与修订；需要再次操作设备时点击「继续探索」，它会重新排队并观察。新指导不会改写旧任务报告。
|
||||
|
||||
单任务和批次「全部资料」包含对话、用例版本和关联运行索引、当前任务的示范录像及原有截图/附件。其他关联任务的媒体需从对应任务导出，索引不会假称包含它们。
|
||||
@@ -81,6 +93,7 @@ mobile_exploration(
|
||||
|
||||
- 探索助手提问后会暂停，主区域和输入框显示“等待你回答”。回答前不进行最终验收，也不生成用例。
|
||||
- 新指导优先于已完成的旧计划。最终检查期间收到指导会返回执行；例如“先回到主页，再结束”需要实际完成返回操作后再验收。
|
||||
- 勾完计划不会直接结束探索。执行模型在已有上下文中交付最终报告，正文保存到任务的 `notes/output.md` 和 `result.json`，并完整写入探索对话后才进入独立验收。默认不再额外调用报告模型；报告内容仍须与实际证据核对，不能凭报告自述判为通过。报告生成期间收到新指导会继续执行并重新生成报告。
|
||||
- 设备操作及最终验收结束后进入“正在提炼用例”，此时不再接收设备指导。未发送文字会保留，提炼完成后可点击“继续探索”。用例卡片只在探索结束时展示。
|
||||
- 进入只读最终验收前停止保存录屏，模型等待、重试与用例提炼不录入视频；如需补做操作，再录制后续片段。
|
||||
- 首页探索设置使用滑块调整思考强度与时限。复跑任务显示已保存的用例名称及版本，完整提示词仍保存在任务中。
|
||||
+9
-2
@@ -76,7 +76,7 @@ SDK：先 `await agent.init(execution_target="computer")`，然后 `agent.new_ta
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"schema_version": 2,
|
||||
"id": "lab-control",
|
||||
"name": "实验室控制",
|
||||
"version": "1.0.0",
|
||||
@@ -92,7 +92,14 @@ SDK：先 `await agent.init(execution_target="computer")`，然后 `agent.new_ta
|
||||
},
|
||||
"skill": "SKILL.md",
|
||||
"config": {"token": {"label": "连接密钥", "secret": true, "required": true}},
|
||||
"resources": ["router:lab"]
|
||||
"resources": ["router:lab"],
|
||||
"capabilities": {
|
||||
"kind": "api", "recording": "none", "required_tools": ["read_status"],
|
||||
"tools": {"read_status": {
|
||||
"effect": "read", "observation": false, "idempotent": true,
|
||||
"cancellation": "confirmed", "evidence": ["state", "text"]
|
||||
}}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user