# 使用 AI 完成 Android 自动化

源码内的 `skills/artemis-automation/` 是可分发 Skill，不依赖本机 Codex 的私有能力。将整个目录复制到宿主支持的 Skill 目录即可；Codex 为 `$CODEX_HOME/skills/`（未配置时 `~/.codex/skills/`）。仓库包含 Skill，启动程序不会修改用户的全局 Skill 目录。

目前仅支持 Codex MCP 配置。Windows 一键脚本检测并同步 Codex；未检测到配置目录时，在项目目录执行 `uv run artemis mcp --install codex`。配置模板使用 `uv run artemis mcp --generate-config codex` 查看；其他名称和 `all` 不再支持。更新后重新加载 Codex MCP；复制 Skill 后重新加载技能。

可以向 AI 这样下达任务：

> 使用 artemis-automation。在我指定的模拟器上验证系统设置首页能打开，不修改设置，输出 Word 和 Excel 报告。

> 校验这份 Excel 的测试用例，指出所有错误；先不执行。

> 在 emulator-5554 执行已校验用例，失败继续，完成后交付批次报告 ZIP。

> 搜索昨天包含“登录”的失败任务，根据截图与步骤说明失败原因，不重跑。

> 把当前安卓屏幕保存成 PNG 到本次任务的 trace 目录，并再保存一份到电脑桌面，返回实际文件路径。

Flash 和 Pro 都支持任务内的安卓文件工具 `android_file`：保存原生截图、列目录、读写 UTF-8 文本、在手机与任务目录/桌面之间传输文件。默认保存位置为 `traces/<trace_id>/artifacts/android/`，指定桌面时保留 trace 副本；Windows 会识别重定向的真实桌面。文本上限 64 KiB，单文件传输上限 64 MiB，每次 ADB 操作最多 60 秒，取消或超时会回收子进程。默认不覆盖已有文件，也不绕过 Android 文件访问权限。保存和传输会校验实际内容，返回文件路径、大小与 SHA-256；用例是否通过仍需结合画面和预期判断。

新保存的截图及下载文件会进入单任务“全部资料”和批次 ZIP 的 `任务文件/安卓/`。原有自动步骤截图仍位于 `traces/images/`，按步骤截图下载；二者用途不同，历史截图不能作为当前画面的新截图。

文件操作结果会进入任务执行记录，Flash 中也逐项记录操作步骤及校验结果，供终检和报告引用；不会只留下模型自行撰写的“已完成”说明。

## MCP 能力

| 工具 | 功能 |
| --- | --- |
| `mobile_diagnose` | 环境、凭据、设备诊断和自带修复 |
| `mobile_workspace` | 设备列表、统一队列、插件配置和资源保护状态 |
| `mobile_config` | 读取或明确保存非敏感模型、功能、报告默认设置 |
| `mobile_run_task` | 单任务执行；`model=flash/pro` 表示执行模式 |
| `mobile_manage_task` | 单任务状态、安全暂停、排队恢复、指导提交/领取记录和停止 |
| `mobile_get_device_state` | 设备截图、界面层级 |
| `mobile_task_file` | XLSX 模板与导入校验 |
| `mobile_batch` | JSON 用例建批次、开始、暂停、继续、复制失败项、删除非活跃批次 |
| `mobile_search_history` | 全库搜索、日期/状态筛选和分页 |
| `mobile_inspect_trace` | 只读步骤、截图和执行证据 |
| `mobile_export_report` | Word、Excel、步骤截图、录屏片段、单任务资料及批次 ZIP，返回本地绝对路径 |
| `mobile_exploration` | 探索对话、指导、人工示范、暂停续跑、用例版本、Flash/Pro 复跑和批次草稿 |

全部 MCP 工具连接用户手动启动的 ARTEMIS 网页主程序，共用配置、队列、历史、设备连接和报告。MCP 只运行轻量 stdio 连接进程，不启动后台、不独立执行任务，`ARTEMIS_STANDALONE` 不改变这一规则。主程序离线时 MCP 仍可握手并列出工具，调用时提示启动；启动网页后下一次调用会自动连接。调用断线不自动重放，避免重复提交。

使用前先运行 `start.bat` / `start-cn.bat` 或 `uv run artemis ui`。默认自动发现同一安装目录的唯一主程序（包括非默认端口）；有多个数据空间时，在 MCP 环境变量中设置 `ARTEMIS_DAEMON_PORT` 选择。显式 `ARTEMIS_APP_DIR` / `ARTEMIS_TRACES_DIR` 必须匹配。升级后重启网页并重载旧 MCP，已运行的旧进程不会自动替换。标准 Codex 配置使用 `required = false`，避免 ARTEMIS 异常阻断整个 AI 会话，更新保留用户的禁用状态。

Windows 启动入口 `start.bat` / `start-cn.bat` 只检查并提示源码更新，`-SkipUpdate` 跳过提示。独立升级入口为 `update.bat` / `update-cn.bat`：先把升级程序复制到项目外的临时目录，检查本地修改，再终止本项目的 ARTEMIS 服务、MCP 和任务进程；之后仅做 Git 快进更新，并用新版启动程序准备环境，完成后由用户重新启动。其他项目、Codex、模拟器和共享 ADB 不受影响；运行中的任务会被中断，不会作为成功任务处理。1.1.1 及更新版本的发布 ZIP 含 Git 工作树，旧版无 `.git` 的 ZIP 需改用新版包或 Git 克隆。没有 Git、网络/认证失败、有本地修改或分支分叉时升级失败并保留现有源码，不重置或覆盖。

Python 按 `uv.lock` 同步缺失/变化的依赖；前端依据源码、资源及包锁指纹决定是否执行 `npm ci` 和构建，成功后才记录指纹。未运行过启动脚本的 Git 源码目录也可直接升级：先自动准备最小 Python 环境，快进源码后再安装新版依赖。国内升级入口继续使用镜像配置。升级与启动的环境准备互斥；升级失败不会自动启动服务或回滚用户配置，处理错误后可重试。双击升级失败时会保留原因并等待回车；自动化调用可设置 `ARTEMIS_NO_PAUSE=1`，输入重定向时也不会等待。

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 进程。

创建批次时必须提供唯一 `request_id`；请求超时后可以按编号查询或用相同内容重发，避免重复用例。创建只保存草稿，`start` 才执行。AI 无需先制造 Excel，也可直接提交 JSON；字段与示例见 [Skill 批量任务参考](../skills/artemis-automation/references/batches.md)。

报告按任务或批次归档到 `artifacts/mcp_exports/`，包含本地路径及服务下载链接；删除批次时会清理对应导出副本。运行中导出是快照；执行完成不等于验证通过，报告会保留未验证、失败、跳过与中断状态。

模型默认使用 `mimo-v2.6-flash`，预设 `gpt-5.6-luna`、`gpt-6-luna`、`mimo-v2.6-pro`，并支持自定义。思考强度最高支持 `max`，默认 `high`，选“由模型默认”不发送该参数；接口不支持时明确报错。单次请求 300 秒，首次失败后最多再试 5 次，普通错误每次等待 10 秒，429 每次等待 60 秒，SDK 不叠加重试。首选模型连续 3 次没有有效工具调用时，当前步骤改用 `gpt-6-luna`（high），最多再试 3 次；下一步重新使用首选模型。兜底模型及次数可通过 `.env.example` 中的 `OPENAI_TOOL_FALLBACK_*` 和 `ARTEMIS_TOOL_FALLBACK_MAX_NO_PROGRESS_ATTEMPTS` 配置。请求耗尽后沿用任务暂停/恢复机制，鉴权或非法参数立即失败。视频分析与录屏是独立开关，默认均关闭。每项批量用例可覆盖模式、模型、设备、录屏和超时等配置，不影响其他任务。暂停先返回 `pausing`，确认状态为 `task_paused` 才表示设备已释放；Pro 等待模型回复或只读诊断时可及时中断，恢复后重新观察设备。AI 可用 `mobile_manage_task(action="inject_instruction")` 提交指导并恢复；运行中的模型思考会中断并重新观察设备，已经开始的设备动作会安全结束。用 `guidance_history` 核对指导是否被领取、在任务流程中核对实际执行情况，或用 `resume` 单独恢复。

429 等待、兜底模型及次数也可在网页“模型配置 → 稳定性与兜底模型”或通过已授权的 `mobile_config(section="model")` 配置。批次 ZIP 还收录每项任务已保存的步骤截图和录屏。

批次任务在队列中使用“用例编号 + 用例名称”显示，提示词仍是模型实际收到的内容。任务历史展示失败原因、完成时间和总耗时；导出全部资料时以用例编号命名目录。删除非活跃批次会同步清理其任务记录、步骤、截图、录屏及生成的报告，删除后不能通过旧 `request_id` 重复执行。

保存全局配置要求用户明确指令；只读配置不包含密钥，MCP 不接收密钥。密钥仍在网页或 `.env` 中填写。设置对新任务生效，模型请求重试不会触发测试用例自动重跑。历史步骤证据保留，设备动作回放已移除。

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

UIAutomator2 启动失败时，先释放本次连接启动的服务，再按现有策略重试；最终错误保留设备编号、尝试次数和底层原因。初始化失败且没有操作步骤时，用例目标属于未执行、未验证，应先检查设备诊断和启动日志，不能据此认定被测功能失败。

Android 应用启动通过系统包管理器查找当前用户的桌面入口，再调用 `am start -W`，不依赖模拟器是否内置 `monkey`。检查命令退出码、错误输出和实际前台状态；应用未安装、没有桌面入口或权限拒绝等明确错误直接返回原因，不重复等待启动超时。ADB 通信异常沿用最多 3 次启动尝试；启动回执超时时先确认应用是否已进入前台，避免重复启动已成功打开的应用。

Flash 和 Pro 默认复用只读 Checker，以任务提示词和用户指导中的要求核对执行结论、步骤截图及探测证据，无需另填预期结果。`test_result` 包含 `status`（`passed`、`failed`、`inconclusive`、`blocked`）、中文 `reason` 和 `evidence`；任务列表、报告与 MCP 使用同一结论。`completed` 仍只代表执行结束，可同时存在测试不通过。Flash 只在退出时验收，不添加计划或中途检查；沿用 Checker 的超时和开关，关闭、超时或缺少证据时显示未验证，不重跑用例。

`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 同名字段可覆盖。原有结果与截图保留，未完成保存的录屏尽力恢复。

## 插件证据与留档参数

2.0.0 插件协议与可运行示例见 [开发规则](plugin-development.md)。单任务和批次全部资料包含各来源截图/录像、插件附件及包内证据索引。

通过 `mobile_config(section="capabilities")` 可读取 `recording` 参数；用户授权后可保存全局默认。单任务用 `runtime_overrides={"recording":{"codec":"h264","computer_scope":"window","max_long_edge":1280,"fps":15}}`，批次在 `task_config.recording` 提供同样对象。JSON 配置的 `agent.recording` 覆盖环境默认；不要把录像参数当作模型截图参数。录屏开关继续独立且默认关闭。

运行信息的上下文参照上限固定为 300,000 tokens，前后端使用相同口径。历史压缩预算默认 80,000，JSON 的 `agent.memory.transcript.context_budget_tokens` 可调但不能超过 300,000；这是压缩触发预算，不是单次生成的输出 token 数，也不是整项任务累计 token 的限额。


### 多轮上下文与缓存诊断

Flash、Pro（启用 transcript）和探索共用分阶段上下文。一个阶段内只追加新观察、工具结果和用户指导，保留此前发送的截图、元素列表和消息原文。行动只能使用同一来源的最新观察，旧画面不能证明当前状态。检查器和摘要模型保持独立职责，不混入执行模型的对话。

默认压缩预算为 80,000 tokens：估算占用达到 28,000 后开始后台准备摘要，56,000 后等待本批摘要齐备再一次性替换历史、清理旧观察，开始下一阶段；72,000 时可紧急折叠为带步骤索引的历史。摘要失败时原文保留至硬阈值，原始证据仍可经历史工具读取。触发估算包含本轮新消息和截图，不只看上一轮用量；没有上游 usage 时使用本地保守估算。该预算不是任务累计限额，也不改变 300k 上下文参照上限。

任务 trace 的 `llm_diagnostic` / `llm_request` 在原有 `usage`、耗时和 `prompt_cache_key` 外增加 `prefix_cache`：

- `append_only`、`shared_prefix_messages`：相对同任务、角色和端点上次调用，输入是否仅追加、共享多少完整消息。
- `first_changed_message`：首个变化消息的位置（从 1 开始）；`tools_or_format_changed` 表示工具或格式参数发生变化。
- `context_phase`、`last_compaction`：上下文阶段与上次压缩前后的估算 token 数。
- `cold_start`：该角色/端点在当前进程内没有比较基准；重启后首次请求会重新建立基准。

以上为适配后消息的本地指纹比较，不是网关最终序列化后的 token 前缀，也不是命中率。诊断仅持有哈希，不额外保存提示词、图片正文或凭据。实际缓存率按上游返回的 `cached_tokens / input_tokens` 加权统计，usage 缺失不能当作零命中。首次请求、阶段压缩、模型/工具切换可能降低缓存率；网关的路由、缓存保留时间和实现也会影响结果。该实现使用完整多轮消息，不依赖网关支持 `previous_response_id`，也不承诺固定命中率。