---
name: artemis-automation
description: 使用 ARTEMIS MCP 完成 Android 与已授权插件支持的电脑或跨端测试、批量执行、失败诊断、历史检索与报告交付。适用于用户希望 AI 通过 ARTEMIS 执行测试或分析其结果。
---

# ARTEMIS 自动化

当前仅提供 Codex MCP 配置安装与更新：`uv run artemis mcp --install codex`；模板使用 `uv run artemis mcp --generate-config codex` 查看。启动日志会打印实际 Codex 配置路径，更新后重载 MCP。

Windows 启动脚本只提示源码更新。升级使用 `update.bat`（国内镜像 `update-cn.bat`），会终止该项目的 ARTEMIS 服务、MCP 和运行任务；仅在用户授权升级或终止任务后执行，先告知任务将中断。升级会同步依赖、网页及 Codex MCP，保留配置和历史；完成后启动 ARTEMIS 并重载 Codex MCP。不要通过启动脚本拉取源码或强行覆盖本地修改。

ARTEMIS 主程序必须由用户启动。MCP 只负责连接，不自动启动后台或独立执行；主程序离线时工具提示先启动网页，此时不反复调用诊断或重提任务。

使用项目提供的 MCP 工具发起任务，Android 及已启用插件由 ARTEMIS 自己编排。报告由 ARTEMIS 生成，不要求宿主 AI 具备 Codex 私有工具、Word 或 Excel 插件。电脑/浏览器能力取决于实际安装并授权的插件，不提供历史动作脚本回放。

## 插件与跨端任务

先用 `mobile_workspace` 查看实际插件、连接配置与资源保护状态。插件安装、凭据与授权在网页「插件」页完成；MCP 只引用已保存的配置，不接收密钥。网页显示已启用不等于插件已经通过真实场景验证。

单任务 `runtime_overrides` 和每条批次用例的 `task_config` 支持 `execution_target`（`android`、`computer`、`mixed`）及 `plugins`（如 `[{"id":"open-computer-use","profile":"default"}]`）。普通安卓任务无需设置 execution_target，AI 可按需调用支持 mixed 的扩展插件。省略 plugins 使用已启用、已授权的默认配置；`[]` 禁用插件。纯电脑任务不要求 Android，也不传 device_serial；混合任务仍需选择手机。完整参数与清单见 [插件任务参数](references/plugins.md)。

同一桌面或路由器上的任务串行。暂停要等插件取消并确认停止后才释放资源；恢复时先观察当前状态。远程操作超时或中断可能已经生效，不自动重试写操作；资源处于保护状态时告知用户核对远程动作后从插件页面解除。插件配置和版本在排队、暂停、运行期间固定，变更范围需结束任务后修改配置。

将电脑与手机证据分别说明。插件调用成功不等于预期效果达成；截图被遮挡、窗口隐藏或观察只有文字时，不假设具备有效像素证据。任务的通过/不通过及人工复验继续沿用现有规则。

## 从需求到执行

粗略或复杂流程需要与用户共同探索时，使用 `mobile_exploration`，参见 [探索模式](../../../docs/exploration-mode.md)。它与网页共用队列和对话；默认独立 `gpt-6.1-sol/high`（也可选 `gpt-6-astra`）。主动预算 1800 秒，到时保存并暂停而不是失败；等待用户和人工示范不计时。人工示范必须等真实 `recording` 状态才让用户操作，结束后分析已保存片段，不能把示范当作自动复跑通过。一次只产出一个用例，按不可变版本复跑或加入批次草稿。结束后消息只用于讨论；继续设备操作需显式 `continue`。查询不启动任务，写操作使用稳定 request_id，运行结果看 test_result。

1. 明确目标、预期结果、目标应用和必要前置条件。用户已授权执行且信息足够时直接开展，不逐步索要批准；缺少会改变业务操作的条件时再询问。用例起点按实际需求安排，不默认清数据、重装、重启应用或退出登录。
2. 用 `mobile_workspace` 查看设备和队列。沿用用户已指定的设备；多台可用设备且没有选择时先询问，不擅自挑选实体手机。任务参数显式传入 `device_serial`。同设备串行，不同设备可并行；本 Skill 不要求创建其他 AI 子代理。
3. 首次使用、工具出错、任务拒绝或设备异常，先 `mobile_diagnose`。按 `next_steps` 的依赖顺序处理；`attempt_fix=true` 可尝试工具自带修复。只有凭据相关故障才使用 `verify_credentials=true`，观察异常才使用 `probe_device=true`。不要盲目重发任务。MCP 不可用时在项目目录运行 `uv run artemis doctor` 并检查宿主 MCP 日志。
4. 选择执行模式：Flash 适合路径明确的界面操作；Pro 适合动态分支、持续计划、ADB/日志诊断或需要 Checker 明确校验的任务。**`mobile_run_task.model` 的 `flash`/`pro` 是执行模式，不是 API 模型名称**。步数长不自动等于需要 Pro；视频能力只有显式启用后才可用。
5. 单任务用 `mobile_run_task`；批量任务用 `mobile_batch`，读 [批量任务与交付](references/batches.md)。AI 可直接提交结构化用例，不必先创建 Excel。用户提供 Excel 时先 `mobile_task_file(action="preview", path=绝对路径)`，修正所有行错误后提交。提示词列原样作为目标，前置约束列只作元数据。
6. 单任务返回 `trace_id` 后，用 `mobile_manage_task(action="status", trace_id=...)` 跟踪；网页任务也可用其任务编号。批次用 `mobile_batch(action="get", batch_id=...)`。需要人工补充时用 `pause`，其返回的 `pausing` 只表示请求已接收；轮询到 `task_paused` 才表示设备已释放。`inject_instruction` 会立即取消进行中的模型回复或只读诊断并重新观察手机，已开始的设备动作会先安全结束；暂停中提交则恢复。`guidance_history` 的 `pending/consumed` 区分提交和执行端领取，无新指导用 `resume`。恢复进入设备 FIFO 队尾并重新观察手机状态。尊重工具建议的等待周期，避免连续高频轮询；停滞或失败先诊断，不把同一业务任务自动重提。

## 结果、证据与交付

- 执行状态与业务判定分开：`completed` 只说明执行结束，不等于测试通过。Flash 和 Pro 默认根据任务提示词、用户指导、执行结论和实际证据进行只读终检，不需要另填预期结果。读取 `test_result.status`（`passed` 通过、`failed` 不通过、`inconclusive` 未验证、`blocked` 阻塞）、`reason` 与 `evidence`，结合验证摘要和 `mobile_inspect_trace` 的步骤/截图交付结果。执行失败不能直接认定产品缺陷；已确认的断言失败不得被后续成功覆盖。终检关闭、出错或证据不足时不得宣称通过。
- 用 `mobile_export_report(session_id=...)` 获取单任务报告；`formats=["screenshots"]` 获取排序截图，`["video"]` 获取保存的录屏分段，`["all"]` 获取 Word、Excel 和所有可用资料的 ZIP。批次传 `batch_id` 获取汇总、各项任务报告、步骤截图及已有录屏的 ZIP。未指定格式时使用保存的 Word/Excel 偏好。执行中的导出只是当前快照。
- 工具返回 MCP 主机上的绝对文件路径和下载 URL。向用户交付真实生成的文件链接，并说明完成、失败、未验证、跳过数量及重要限制。不要只说“报告已生成”而不交付文件。

### 安卓截图和文件

- Flash/Pro 任务内部均提供 `android_file`，由任务已分配的 Android 设备执行。外层 MCP 使用现有 `mobile_run_task` 提交目标，不直接绕过任务队列传文件。
- 保存当前手机画面使用 `action="screenshot"`；原生 PNG 默认位于 `traces/<trace_id>/artifacts/android/`。明确要求保存电脑桌面时用 `destination="desktop"`，同时保留 trace 副本；无需电脑插件或截图快捷键。自动步骤截图原本保存在 `traces/images/`，不能把旧截图当作新的截屏结果。
- `list`、`read_text`、`write_text` 的 `device_path` 是 Android 绝对路径；文本使用 UTF-8，单次不超过 64 KiB。`pull` 下载手机文件，`push` 将 trace 中的文件或用户指定的桌面文件上传手机，单文件不超过 64 MiB。`filename` 仅是文件名，不能传 Windows 路径；目录由 `destination` 选择。不能绕过 Android 的应用私有目录权限。
- 保存、上传和下载会校验内容，已有文件默认不覆盖。只有工具成功并返回真实路径/校验结果后才可宣称保存成功；截图内容是否符合测试预期仍需核对。单任务“全部资料”及批次 ZIP 包含这些文件，位于 `任务文件/安卓/`。
- 用 `mobile_search_history` 按名称、目标、编号或标签搜索全部历史；日期先按用户时区转换为 Unix 秒，`start` 含边界、`end` 不含边界。按返回的 `total/page/size` 翻页，不能把第一页当作全部历史。
- `mobile_inspect_trace` 是只读步骤证据查看；其中历史上下文的 replay 术语不表示重新执行设备动作。

## 配置和恢复边界

- 插件步骤按实际来源区分，截图不能跨手机/电脑或跨目标窗口作为证据。`mobile_export_report(formats=["all"])` 和批次导出包含插件文件、各来源录像及 `证据索引.json`，索引中的路径相对于任务资料目录。
- 录像默认关闭。保存录屏后，使用到的支持录制来源自动留档；电脑视频分析尚未提供，单开视频分析不会留下电脑录像。留档默认长边 1280、15 fps、H.265 1000 kbps / H.264 1500 kbps；模型截图参数独立。`mobile_config(section="capabilities")` 的 `recording` 对象或单任务 `runtime_overrides.recording`、批次 `task_config.recording` 可覆盖 `codec`（auto/h264/h265）、`computer_scope`（screen/window）、尺寸、帧率和码率。全局保存仍需用户授权。
- 电脑屏幕录像包含当前控制屏幕的其他可见内容。任务暂停停止录像，恢复追加片段；查看真实时间轴的无覆盖区间时结合截图/日志，不把旧帧或其他来源当作证据。除任务提示词要求，不自动恢复业务配置。

- 本机常见模拟器在设备刷新、启动及重启 ADB 后自动发现并连接，不必猜固定端口。USB 与 Android SDK 模拟器由 ADB 原生发现。首次连接其他 TCP 设备/无线手机时，在网页“无线 ADB”填写实际地址和端口，成功后程序保存地址并自动重连；无线调试的配对和授权仍由用户完成，端口变化后需重新连接。远程/转发 ADB 不执行本机发现。用 `mobile_workspace` 或 `mobile_diagnose` 检查自动连接结果；多设备时仍先确认用户要测试哪台。默认开关及扫描预算可由 `mobile_config(section="capabilities")` 的 `adb_auto_connect`、`adb_discovery_interval_seconds`（10）、`adb_discovery_timeout_seconds`（5）配置，修改全局默认需要用户授权。

- `mobile_config` 读取非敏感设置。只有用户明确要求保存或修改默认配置时，才传 `changes` 与 `persist_defaults=true`；这些设置影响后续任务，不能为一次临时需求擅自改变以后所有任务。
- 模型名称支持预设 `gpt-5.6-luna`、`gpt-6-luna`、`mimo-v2.6-flash`、`mimo-v2.6-pro` 和自定义名称，取决于用户配置的 Responses 网关。思考强度最高支持 `max`，默认 `high`、单次请求 300 秒、失败后最多重试 5 次；普通错误每次等待 10 秒，429 每次等待 60 秒。首选模型连续 3 次未形成有效工具调用时，当前步骤改用 `gpt-6-luna`（high），兜底最多再尝试 3 次；下一步恢复首选模型。默认关闭视频分析与录屏。不根据模型名称猜测网关能力。
- 强度选 `default` 表示不发送该参数，和 `none`（显式要求关闭）不同。接口拒绝强度参数时明确呈现失败，先询问用户是否改用 `default`，不能静默降级或换模型。
- API Key 只通过网页或 `.env` 配置。不要请求用户把 key 发到聊天中，不读取/回显已有 key。保存后新任务生效；直接编辑环境文件后需重启相应服务，运行中的任务保留自己的配置。
- 429 等待和兜底参数可在网页模型配置或经用户明确授权的 `mobile_config(section="model", persist_defaults=true)` 保存；当前任务不热切换。录屏与 AI 视频分析分别配置。批量任务的 `task_config` 可覆盖单项，不修改全局设置；只开视频分析时录制内容不作为可下载文件保存。暂停时停止录屏，恢复后按片段继续，不能把其他任务画面混入该任务资料。
- 请求重试是模型调用恢复，不是测试用例重跑。批次默认失败继续、不自动重跑；服务重启后保留状态并暂停，用户明确要求后才继续或复制失败项。
- 批次暂停只停止后续派发；当前任务等待指导时用 `mobile_manage_task(action="pause", trace_id=...)`，真正取消用 `stop`。用户明确要求删除批次记录时先 `mobile_batch(action="get")` 核对编号，再用 `delete`；执行中/排队中的批次不能删，删除会清除该批次的任务历史、报告和文件。服务重启后运行/暂停的任务标记中断，不自动重跑。停止可能保留已经产生的业务效果，不声称自动回滚。

需要编写外部可执行测试代码时，先通过 ARTEMIS 实际探索目标应用，确认页面、定位器和转换。优先动态定位，框架支持时才以已验证坐标兜底；在最终脚本中明确等待条件，不将 AI 思考耗时当作确定性等待。

执行保护默认总时限 1800 秒，单任务、批次和 MCP 都适用，排队及用户暂停不计时。设备观测默认 60 秒、最多 3 次，ADB 命令默认 10 秒；观测失败不会继续向模型发送占位图或旧元素索引。Flash 连续 3 次动作失败先重新观察再切换兜底，兜底仍失败则结束任务并保存原因。不能以提高步数或反复重提任务代替设备诊断。

`mobile_run_task(runtime_overrides={"timeout_seconds":1800,"observation_timeout_seconds":60,"observation_max_attempts":3,"device_command_timeout_seconds":10,"action_failure_attempts":3})` 可为单任务覆盖执行保护；其中 `model` 是 API 模型名，外层 `model` 仍是 Flash/Pro 模式。相同字段也支持批次的 `task_config`。全局默认通过网页功能配置或明确授权的 `mobile_config(section="capabilities", changes={"task_timeout_seconds":1800}, persist_defaults=true)` 保存，对后续任务生效，不接受密钥。

任务已经产生最终结果，但 SDK 线程或资源清理仍卡住时，默认最多再等待 30 秒后回收工作进程，避免继续占用队列。全局可用 `ARTEMIS_WORKER_CLEANUP_TIMEOUT_SECONDS` 或功能配置的 `worker_cleanup_timeout_seconds` 调整，任务 JSON 同名字段可覆盖。原有结果与截图保留，未完成保存的录屏尽力恢复。