Artemis-Eapil/docs/ai-automation.md

使用 AI 完成 Android 自动化

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

先完成项目环境和模型配置，然后在项目目录执行 uv run artemis mcp --install codex 安装/更新 MCP 配置。其他客户端将 codex 换成对应客户端；uv run artemis mcp --help 可查看支持列表。更新后重新加载宿主 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 时会检查当前分支的 Git 上游，仅做快进更新；拉取后重新加载新版启动脚本。1.1.1 及更新版本的发布 ZIP 是精简的 Git 工作树，解压后也能在后续运行时检查更新。1.1.0 及更早 ZIP 缺少 .git，需手动下载新版源码包一次。没有 Git、网络/认证失败、有本地修改或分支分叉时保留现有源码并给出提示，不重置或覆盖。-SkipUpdate 可跳过源码更新检查。

Python 每次按 uv.lock 检查并同步缺失/变化的依赖；前端依据源码、资源及包锁文件指纹决定是否重新执行 npm ci 和构建，成功后才记录指纹。国内镜像选项继续生效。检测到正在执行/排队的任务时，自动更新启动会停止，让原任务继续。

MCP 自动刷新只处理已存在且指向当前项目的标准 Python 模块配置，更新解释器路径和已有工具白名单。保留用户环境变量、禁用状态、禁用工具及其他服务；JSON/TOML 无法安全解析、其他项目和自定义启动包装器保持原样。首次修改保留备份，未接入的客户端不会自动安装。源码更新后需在 AI 客户端重新加载 MCP 连接以使用新实现；脚本不会强制重启你的 IDE。

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

报告导出到 artifacts/mcp_exports/，包含本地路径及服务下载链接。运行中导出是快照；执行完成不等于验证通过，报告会保留未验证、失败、跳过与中断状态。

模型默认使用 mimo-v2.6-flash，也预设 gpt-5.6-luna 并支持自定义。思考强度最高支持 max，默认 high，选“由模型默认”不发送该参数；接口不支持时明确报错。单次请求 300 秒，首次失败后最多再试 5 次，每次等待 10 秒，SDK 不叠加重试。耗尽后沿用任务暂停/恢复机制，鉴权或非法参数立即失败。视频分析与录屏是独立开关，默认均关闭。每项批量用例可覆盖模式、模型、设备、录屏和超时等配置，不影响其他任务。暂停先返回 pausing，确认状态为 task_paused 才表示设备已释放；Pro 等待模型回复或只读诊断时可及时中断，恢复后重新观察设备。AI 可用 mobile_manage_task(action="inject_instruction") 提交指导并恢复，用 guidance_history 核对是否领取，或用 resume 单独恢复。

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