Artemis-Eapil/docs/ai-automation.md

使用 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。

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

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，返回本地绝对路径

新增工具通过统一后台服务运行，与网页共享配置、队列、历史和报告；不另外启动独立调度器。ARTEMIS_STANDALONE 模式不支持这些工作区工具。

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 和构建，成功后才记录指纹。国内升级入口继续使用镜像配置。升级与启动的环境准备互斥；升级失败不会自动启动服务或回滚用户配置，处理错误后可重试。

MCP 同步仅检查 $CODEX_HOME/config.toml；未设置或为空时使用当前用户的 ~/.codex/config.toml。日志会显示实际路径，以及新装、更新、已是最新、未检测到或自定义跳过的结果。检测到目录但缺少 ARTEMIS 条目时安装当前源码的标准配置；已有标准配置即使指向旧解压目录，也会更新解释器、项目目录、环境路径和工具清单。保留用户额外环境变量、禁用状态及其他服务；自定义启动包装器保持原样并提示。其他客户端的配置和规则文件不读取、不修改，其格式错误不会阻止启动。Codex 配置无法安全解析时停止启动，原文件不被覆盖；可使用 -SkipMcpSync 仅启动网页。首次修改保留备份。同步后需在 Codex 中重新加载 MCP 或重启 Codex，脚本无法替宿主重启已加载的 MCP 进程。

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

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

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