199 lines
33 KiB
Markdown
199 lines
33 KiB
Markdown
# 使用 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 中也逐项记录操作步骤及校验结果，供终检和报告引用；不会只留下模型自行撰写的“已完成”说明。
|
||
|
||
## 短时安卓控件与精确拖动
|
||
|
||
Flash 和普通 Pro 都支持任务内原生 `action_sequence` 与 `drag`，外层 MCP 工具不变。
|
||
这是通用的安卓短动作组合器，不限于时间轴。短时面板每次操作优先使用 `[ensure_visible, click/drag]`：
|
||
AI 指定已观察到的面板内 target、入口 opener 资源 ID 和 target_description，工具现场判断是否已经显示；
|
||
需要时只点击入口一次，并在本机等目标出现（timeout_ms 默认 1500，上限 3000），再执行后续成员。
|
||
已显示时跳过打开，缺失、不唯一、层级不可用或超时则停止并保留回执，不重试已输入的动作。
|
||
它只准备界面，不用于业务提交；无原生 ID 时仍可组合已观察坐标的 click/wait/drag。
|
||
序列与校准拖动沿用小型动作的 16,384 字符参数流保护：异常膨胀时在执行前断流，
|
||
丢弃不完整参数，按已有的无效输出策略有限重试，不把截断内容派发到设备。
|
||
任务可以要求“先观察缩放弹层的真实滑块位置，恢复同布局后用一个连续动作打开、等待、拖动，
|
||
再检查刻度是否改变”。动作之间不再等待下一轮模型，适用于数秒后消失的控件。
|
||
序列使用 `pro.execution.max_burst_actions` 的数量限制（默认 4，等待也算一项），
|
||
Flash/Pro 的工具声明显示实际上限。每次反向调整也保持完整的打开、等待、操作组。
|
||
序列内 click 的 target 可直接使用观察列表中的完整资源 ID；执行时重新定位，缺失或不唯一时拒绝点击，
|
||
避免模型反复将原图像素换算成归一化坐标。
|
||
click 的 times 支持 1–10 次连点，delay_ms 默认 100；连点仍占一个成员，按资源 ID 定位时每次都重新确认目标。
|
||
普通元素索引点击也核对原资源 ID 是否仍覆盖记录的点击位置，控件消失或移位时不点击旧坐标。
|
||
安卓现场检查只读取实时 UI 层级，不等待截图稳定；目标在连点途中消失时停止，并保留 completed_taps。
|
||
该计数仅表示已派发且返回无错误的点击次数，不代表业务验证通过。Flash 在连续动作末尾立即保留截图，
|
||
避免多轮稳定截图将短时面板消失后的画面覆盖为唯一证据；即时截图的稳定状态为未知，不能据此宣称画面已稳定。
|
||
普通 Pro 同样在完整连续组结束后保存截图，供立即进行的检查点验收使用；即使图片哈希与操作前相同，
|
||
也保留这次真实采集对应的动作后证据，不将图片去重当作没有采集。
|
||
元素列表中的真实 `resource_id` 可用于 click 的 `unless_visible`（面板已显示时跳过打开按钮，不能加在实际操作按钮上）
|
||
及 drag 的 `require_visible`（面板消失时不拖动），现场检查不增加模型轮次；层级不可用时拒绝操作。
|
||
成员回执区分完成、跳过、结果不明和未执行；部分失败后不能将已成功或结果不明的输入整组重发。
|
||
“最大/最小”优先通过原生加减按钮调整，并核对继续同向调整后滑块、刻度是否停止变化，或读取明确的原生极值。
|
||
仅接近端点、变成分钟级、关闭面板或选中录像卡片均不能证明已到最大或最小；录像卡片时间也不是固定指针对应时间。
|
||
|
||
时间轴可使用原图像素和当前两个刻度校准拖动，避免细刻度被整数归一化坐标量化。
|
||
它仍受截图分辨率、刻度线性、应用吸附及实际拖动响应影响；应先放大、短距离拖动，
|
||
再读取同名刻度或选中时间作修正。工具成功和计算误差不等于业务时间已准确选中。
|
||
若松手后时间轴继续滑动，应减慢 pan 并等待刻度停止后复核；拖动浮层的时间可能只反映松手瞬间，
|
||
与固定指针对应刻度冲突时不能用来验收。常驻时间轴的拖动不依赖缩放弹层保持打开。
|
||
量化验收可对停稳后截图的真实刻度与指针位置作线性插值，并计入读图不确定性；
|
||
目标误差加不确定性不超过用户容差时才能确认，不强制要求秒级文字读数。
|
||
|
||
## MCP 能力
|
||
|
||
Android 原生控件读写、条件等待、限定容器滚动及同步多指缩放/旋转见 [原生动作说明](android-native-actions.md)。Flash、普通 Pro 和探索共用实现；工具完成与 APP 结果、最终业务验收分别记录。
|
||
|
||
仅 PC 测试与网页“仅 PC”勾选项使用同一任务目标。先用 `mobile_workspace(include_devices=false)` 查看实际电脑插件，再提交 `mobile_run_task(task_desc="在电脑浏览器检查指定页面", model="Flash", request_id="本次提交唯一编号", runtime_overrides={"execution_target":"computer"})`。无需手机或模拟器在线；仍需可用模型和已启用并授权的电脑观察插件。`model="Pro"` 与 `mobile_exploration` 的 `task_config.execution_target="computer"` 同样适用。每项批量用例的 `task_config` 使用相同字段；插件参数见 [插件任务参数](../skills/artemis-use/references/plugins.md)。
|
||
|
||
| 工具 | 功能 |
|
||
| --- | --- |
|
||
| `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 批量任务参考](../skills/artemis-use/references/batches.md)。
|
||
|
||
报告按任务或批次归档到 `artifacts/mcp_exports/`，包含本地路径及服务下载链接；删除批次时会清理对应导出副本。运行中导出是快照；执行完成不等于验证通过，报告会保留未验证、失败、跳过与中断状态。
|
||
|
||
新安装模型默认使用 `gpt-6-luna`，预设 `gpt-6-luna`、`gpt-6.1-terra`、`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)` 保存，对后续任务生效，不接受密钥。
|
||
|
||
Flash 最终 AI 判定与分析默认关闭。读取 `mobile_config(section="capabilities")` 的 `flash_final_check_enabled`；用户要求保存全局设置时，可用 `changes={"flash_final_check_enabled":true}` 和 `persist_defaults=true` 开启。它影响尚未开始的所有 Flash 任务，运行中的任务、Pro 和主动探索不变；不作为单任务或精选模板的覆盖项。关闭时 `test_result.status="inconclusive"`、`verification_skipped=true`、`source="system"`，表示未做 AI 判定，不是测试通过；执行异常仍按原失败状态记录。人工复验可随后给出独立结论。
|
||
|
||
任务已经产生最终结果，但 SDK 线程或资源清理仍卡住时，默认最多再等待 30 秒后回收工作进程，避免继续占用队列。全局可用 `ARTEMIS_WORKER_CLEANUP_TIMEOUT_SECONDS` 或功能配置的 `worker_cleanup_timeout_seconds` 调整，任务 JSON 同名字段可覆盖。原有结果与截图保留，未完成保存的录屏尽力恢复。
|
||
|
||
MCP 工具和单任务 HTTP 提交均拒绝未知顶层字段，在执行前返回错误。`mobile_run_task` 使用 `task_desc`，HTTP `/api/run` 使用 `goal`；两者不能混用来静默替换任务。结构化 JSON 工具结果同步保留 `structuredContent` 和原文本内容。`view_summary` 的文本保持 Markdown，结构化结果提供 `summary` 与 `steps={items,total,offset,limit,next_offset}`；按 `next_offset` 翻页，值为 null 才表示没有下一页，`items` 保留存储中的 `step_id/step_number`。
|
||
|
||
跨端阶段工具 `update_task_progress` 首次使用完整 `stages`；之后可提供 `stage_updates=[{id,status,evidence?}]` 和 `reason`。补丁只更新已存在的阶段，保留其顺序、范围、资源与未提及阶段；完整阶段和补丁只能选择一种。完成或阻塞仍需事实依据，校验或保存失败时不更新进度。来源清单与阶段完成都不能替代正式验收。
|
||
|
||
报告和证据索引的 `evidence_sources` 从已记录的插件来源汇总，区分安卓/电脑界面与接口、终端、文件等辅助来源，并保留实际步骤和调用编号。缺失来源显示未知，不按业务后台名称或网址推断执行平台；界面截图不能单独证明后端持久状态。该清单不改变 `test_result`、AI 原判或人工复验。
|
||
|
||
## 插件证据与留档参数
|
||
|
||
2.0.0 插件协议与可运行示例见 [开发规则](plugin-development.md)。单任务和批次全部资料包含各来源截图/录像、插件附件及包内证据索引。
|
||
|
||
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 客户端，避免并发任务互相覆盖。显式传入的缓存键及会话请求头优先。仅指定会话请求头时，正文中缺省的缓存键依次沿用有效的 `thread-id`、`thread_id`、`session-id` 或 `session_id`（头名称不区分大小写）；补齐缺少的另一种会话头，但不添加同义别名。调用方同时显式指定不同的键时保留原值，应自行保证一致。
|
||
|
||
#### 网关亲和规则
|
||
|
||
网关透传 `Thread-Id` / `Thread_id`、`Session-Id` / `Session_id`，并从这些请求头或 JSON 的 `prompt_cache_key` 提取亲和键，即可覆盖 ARTEMIS 默认请求。默认这三个值相同，无需重复添加下划线头或 `X-Codex-Window-Id`。`pass_headers` 只负责透传，选中渠道和模型前缀缓存是否命中仍取决于服务端实现；不能仅凭头部存在宣称命中。
|
||
|
||
`X-Client-Request-Id` 是每次尝试独立的诊断编号，可继续透传，但不要加入缓存亲和键来源。`User-Agent`、`Originator` 和 Codex 专用头也不应替代 ARTEMIS 的会话键。保留其他客户端需要的透传项即可；本版不修改生产网关规则。
|
||
|
||
执行模式弹窗显示本任务所有已记录模型调用的缓存 Token 和加权命中率：`累计 cached_tokens ÷ 累计 prompt_tokens`。缓存输入已包含在输入总量中，不能再相加；不平均每次调用的百分比，也不把命中请求数当成 token 命中率。打开弹窗后运行中每 3 秒更新，历史任务读取已保存统计；没有有效输入用量时显示 `—`，请求失败有明确提示。统计以服务端上报为准，未上报的缓存量按 0 汇总，旧任务漏记的数据不会回填。
|
||
|
||
模型缓存还要求可复用的上下文前缀，路由稳定不能保证命中或节费。参考 [OpenAI 官方缓存说明](https://developers.openai.com/api/docs/guides/prompt-caching)。
|
||
|
||
有请求诊断的调用同时发送 `X-Client-Request-Id`，默认与 trace 内的 `request_id` 一致，便于对照 API 日志。`request_sent_at` 表示实际发送时间；`routing_header_fingerprints` 只记录发送的会话头的哈希，`client_request_id_matches` 表示关联 ID 是否一致。不记录认证头或其他请求头正文。稳定标识提供路由亲和条件，实际命中仍取决于前缀和上游缓存。
|
||
|
||
辅助摘要继续独立处理各自片段，避免为了提高命中比例累积不相关的历史。视觉摘要中完全重复的插件执行结果与控件树只发送一份；独立错误、状态、不同观察及原始 trace 均保留。
|
||
|
||
## Responses WebSocket 增量传输
|
||
|
||
模型传输默认 `websocket`。首次启动时，未带迁移标记的全局配置（包括已保存的 `OPENAI_TRANSPORT=http`）统一切换为 WebSocket，并在安装模式对应的 `.env` 原子写入 `ARTEMIS_TRANSPORT_DEFAULT_VERSION=1`。迁移只调整协议及此内部标记，保留凭据、接口地址、其他设置和注释；跨进程文件锁避免启动与网页保存相互覆盖。保存失败保留原文件、明确告警，本次进程仍使用 WebSocket，下次启动重试。
|
||
|
||
之后可在“模型配置 → 传输协议”手动切回 `HTTP（兼容模式）`；保存会保留迁移标记，不会在重启时再次改成 WebSocket。直接编辑 `.env` 时保留 `ARTEMIS_TRANSPORT_DEFAULT_VERSION=1`，设置 `OPENAI_TRANSPORT=http` 后重启即可切回。网页保存对新任务生效；升级迁移不会改动正在运行的任务。JSON 模型/节点配置仍可用 `transport` 单独覆盖。MCP 使用 `mobile_config(section="model", changes={"transport":"websocket"}, persist_defaults=true)` 保存，仍须用户明确要求修改默认值。
|
||
|
||
异步任务请求在现有 SDK 序列化与完整性保护之下接入 `/v1/responses` WebSocket。首轮发送完整上下文；同一任务（或探索）、角色、模型、路由头及凭据范围内复用连接。只在当前输入严格包含上一轮输入和完整输出、生成选项一致时，发送 `previous_response_id` 与新增输入。仅忽略消息 ID、状态、输出概率等不影响历史语义的响应字段，不按文本相似度截取。工具结果保留 `call_id`，文本、图片、结构化输出与 usage 继续走原有解析和安全检查。同步底层模型调用仍使用 HTTP；Flash、Pro、探索和辅助模型运行路径均为异步。
|
||
|
||
本地历史、截图替换或压缩后重新发送当前完整上下文；不会为了续传保留已经移除的旧界面索引。连接重建或服务端明确返回 `previous_response_not_found` 时，从本地完整历史恢复，后者最多补发一次且必须尚未出现输出。连接在输出中途断开时，不在传输层盲目重发，交给现有模型重试预算；取消关闭未完成连接，不采纳半截工具参数或结论。不同会话并行、同一连接串行；连接池最多保留 32 个会话，空闲 60 秒释放，连接满 55 分钟主动重建。`store=false` 保持不变。
|
||
|
||
网关必须支持 WebSocket Upgrade、双向长连接、`response.create` 与响应 ID 续接；只透传会话头不能证明支持。握手传递现有授权和路由头，保持 TLS/自定义 CA 验证与 `OPENAI_USE_SYSTEM_PROXY` 策略，拒绝携带凭据跨地址重定向。不支持升级时明确报错，可在网页改回 HTTP，不会静默改成 HTTP 全量请求。
|
||
|
||
请求诊断的 `transport` 记录 `full_request_bytes`、`sent_payload_bytes`、`received_payload_bytes`、`payload_bytes_saved`、`incremental`、`reused_input_items`、`connection_reused`、`create_events` 和重建原因。字节数衡量 JSON 应用载荷，不包含 TLS/WebSocket 帧和压缩开销；SDK 内部兼容 SSE 的字节不冒充网络流量或 HTTP 200。握手上的请求标识属于建连尝试，后续轮次以本地请求诊断及响应 ID 关联。减少上传不等于减少模型上下文 token，也不等于缓存命中，usage 仍以服务端实报为准。协议见 [OpenAI 官方说明](https://developers.openai.com/api/docs/guides/websocket-mode)。
|
||
|
||
## 指定任务诊断、复盘与管理
|
||
|
||
流式请求中的 `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 的 [插件开发参考](../skills/artemis-use/references/plugin-development.md)，从自带模板开始。通过 `mobile_workspace(include_devices=false, include_development=true)` 找到当前服务的 Python；在任意目录均可调用 Skill 自带校验脚本。静态检查、MCP 握手与真实操作验收分别报告。市场发布需用户明确要求，验证未覆盖场景必须注明。
|