21 KiB
使用 AI 完成 Android 自动化
官方 skills/artemis-use/ 随源码和 wheel 分发，包含执行、探索、诊断复盘及插件开发规范、模板和校验脚本。启动脚本、直接 artemis ui / artemis-admin 启动服务、显式 artemis mcp --install codex 共用同步逻辑；MCP 桥连接/握手不安装、不启动主程序。
默认安装到 ~/.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-use。在我指定的模拟器上验证系统设置首页能打开，不修改设置，输出 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 |
设备列表、统一队列、插件状态及按需连接诊断；include_development 返回插件开发环境 |
mobile_config |
读取或明确保存非敏感模型、功能、报告默认设置 |
mobile_run_task |
单任务执行（request_id 去重）；model=flash/pro 表示执行模式 |
mobile_manage_task |
单任务状态、提交反查、暂停/继续、指导和停止；删除预览及删除、代录用户人工复验 |
mobile_get_device_state |
设备截图、界面层级 |
mobile_task_file |
XLSX 模板与导入校验 |
mobile_favorites |
收藏独立任务/用例/批次模板、调整默认配置、按原配置复跑；run 使用稳定 request_id |
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 批量任务参考。
报告按任务或批次归档到 artifacts/mcp_exports/，包含本地路径及服务下载链接；删除批次时会清理对应导出副本。运行中导出是快照；执行完成不等于验证通过，报告会保留未验证、失败、跳过与中断状态。
新安装模型默认使用 gpt-6-luna，预设 gpt-6-luna、gpt-6.1-sol、gpt-6-astra、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 插件协议与可运行示例见 开发规则。单任务和批次全部资料包含各来源截图/录像、插件附件及包内证据索引。
Flash、Pro 与探索沿用现有执行上下文跟踪用户明确要求的前置条件、检查项和交付物，跨端及收尾时只补缺失证据。电脑操作或留存截图前核对窗口与页面身份；坐标以同一张最新插件截图及其编号为准，不使用手机归一化坐标或自行叠加 DPI。视觉与历史摘要保留来源、关键原文和待核实项，模糊文字或冲突读数不能直接成为已验证事实；需要时回查原图/控件树。本规则不新增规划、验收或摘要模型调用，不改变现有思考强度和输出预算。
通过 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，也不承诺固定命中率。
执行模型、视觉摘要和历史摘要的 Responses 请求均按“探索会话（普通任务用任务 ID）＋角色＋模型”生成稳定的匿名 prompt_cache_key，并在 Thread-Id、Session-Id 请求头中发送相同值。标识符合 ^[-0-9A-Za-z._:]{1,128}$；暂停继续时保持稳定，不同任务或角色隔离。网关可从头部或 JSON 字段提取路由键，不依赖特定 User-Agent，也不会伪装为 Codex。标识在每次调用时设置，不写入共享 HTTP 客户端，避免并发任务互相覆盖。显式传入的缓存键及会话请求头优先。
有请求诊断的调用同时发送 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 的 插件开发参考，从自带模板开始。通过 mobile_workspace(include_devices=false, include_development=true) 找到当前服务的 Python；在任意目录均可调用 Skill 自带校验脚本。静态检查、MCP 握手与真实操作验收分别报告。市场发布需用户明确要求，验证未覆盖场景必须注明。