feat: add official Codex skill and harden task execution

Install and update artemis-use with task diagnostics and plugin guidance. Preserve cross-device file receipts, review canonical reports, guard stage transitions and reduce small history summaries. Improve exploration lifecycle, request recovery and browser live connections.

skills/artemis-use/references/batches.md

@@ -0,0 +1,68 @@
+# 批量任务与报告交付
+
+## 直接提交用例
+
+用户要求执行明确的测试集合时，将每个独立提示词转成一个 case。`goal` 是唯一发送给 ARTEMIS 的任务正文；`case_id`、`category`、`subcategory`、`name`、`preconditions` 只作元数据。`task_config` 可覆盖该项执行配置，不影响其他项。
+
+先生成唯一 `request_id`（例如 UUID），保存在当前任务记录中，然后调用：
+
+```json
+{
+  "action": "create",
+  "request_id": "52c3e95d-7e31-4e41-b42d-27aa3774fb2d",
+  "batch": {
+    "name": "系统设置冒烟测试",
+    "device_serial": "用户已选择的设备编号",
+    "profile": "pro",
+    "formats": ["docx", "xlsx"],
+    "stop_on_failure": false,
+    "timeout_seconds": 1800,
+    "repeat_count": 1,
+    "cases": [
+      {
+        "case_id": "DEMO-001",
+        "category": "系统设置",
+        "subcategory": "首页",
+        "name": "设置首页可达",
+        "preconditions": "设备已解锁。",
+        "goal": "打开系统设置，确认设置首页可见，不修改任何设置；记录实际文字与截图证据。",
+        "task_config": {
+          "profile": "pro",
+          "model": "mimo-v2.6-flash",
+          "reasoning_effort": "high",
+          "locked_app_package": "com.android.settings",
+          "record_video": true,
+          "analyze_video": false,
+          "request_timeout_seconds": 300
+        }
+      }
+    ]
+  }
+}
+```
+
+`create` 只保存已校验的草稿。检查返回批次编号和范围，用户已经授权执行时接着 `mobile_batch(action="start", batch_id=...)`；用户只要求准备方案时留在草稿，不启动。保存 `batch_id`，用 `get` 跟踪各项状态。
+
+用户要求压测时，在 `batch.repeat_count` 设置正整数循环次数（默认 1），只向 `batch.cases` 提交用户选择的用例。每轮按原顺序执行整批，再进入下一轮；各次执行独立保存编号和报告，`get` 中的 job 包含 `iteration`、`repeat_count`。总执行数为用例数乘以轮数，默认上限 10000，由服务的 `ARTEMIS_BATCH_MAX_EXECUTIONS` 控制。不要重复调用 `start` 来实现循环，也不要将循环次数写入每项 `task_config`。失败即停止会跳过后续全部轮次；复制失败项时各失败执行只重跑一次，新的批次循环次数为 1。
+
+创建请求超时可能已经落库。先 `lookup(request_id=...)`；需要重发时保留**相同 request_id 和相同内容**。服务会返回原批次，内容不同会拒绝。不要通过换编号“修复超时”，否则会形成重复批次。
+
+## Excel 导入
+
+`mobile_task_file(action="template")` 返回空白模板的本地路径。“任务”页七列依次为：用例编号、检测项目、测试子项、测试用例、前置约束提取、Artemis提示词、任务配置(JSON)。仅提示词必填；说明页有一条示例，不会导入执行。JSON 支持 `profile`、`model`、`reasoning_effort`、`device_serial`、`verification_level`、`explorer_mode`、`locked_app_package`、`record_video`、`analyze_video`、`request_timeout_seconds`、`max_retries`、`retry_interval_seconds`、`timeout_seconds`。未知字段或密钥被拒绝。每行独立，不支持公式、宏、外部链接。
+
+`preview` 返回 `valid/tasks/errors`，不会执行。网页默认全选，可取消用例；AI 也应按用户指定范围筛选 `tasks`。所有错误处理完后，将所选项的预览字段 `row` 去掉，作为 `batch.cases` 提交，并说明实际选中数量。不要跳过错误行却声称全部导入成功。
+
+## 状态与异常
+
+- 批次 `draft` 等待开始；`running` 调度中；`paused` 等待处理；`completed` 表示所有项进入终态，不代表全部通过。
+- 单项 `pending/queued/running/pausing/task_paused/resuming/finalizing` 尚未结束，`completed/failed/cancelled/interrupted/skipped` 是终态。`pausing` 是请求已发出而设备仍被占用，`task_paused` 才表示设备已释放；`finalizing` 在生成报告，不能提前宣称报告已完成。
+- 批次 `pause` 保留当前执行，只暂停后续派发；单项 `mobile_manage_task(pause)` 会在安全边界释放设备，Pro 的模型等待与只读诊断可中断。恢复后重新观察画面，并排到设备队尾，不阻塞后续项。`mobile_manage_task(guidance_history)` 可核对指导是否从 `pending` 变为 `consumed`，但仍需检查后续操作是否符合指导。设备断开、模型持续失败或任务达到批次时限会暂停后续派发；用诊断确认恢复后再响应用户的继续指令。
+- `resume` 只继续未开始项；`retry_failed` 复制失败、取消和中断项为新草稿，不修改原结果。必须来自用户的明确重跑请求。该动作不提供创建去重，响应不确定时先 `list` 查找新批次，不自动重复调用。
+- 用户明确要求删除批次记录时，先 `get` 核对批次编号与状态，再 `delete`；正在执行、排队或等待指导的批次不能删除。删除会同时移除该批次任务历史、报告和文件，无法撤销。
+
+## 报告
+
+`mobile_export_report(batch_id=...)` 下载批次 ZIP，包含汇总、各项报告和有序步骤截图；任务保存了录屏时，还包含对应录屏片段。报告格式由创建批次时的设置决定。单任务传 `session_id`（单任务 MCP 的 `trace_id`）以及可选 `formats=["docx"]`、`["screenshots"]`、`["video"]` 或 `["all"]`。默认格式通过 `mobile_config(section="reports")` 查看。录屏与 AI 视频分析独立，只有保存了录屏才可下载片段。
+
+结果文件在 MCP 主机的 `artifacts/mcp_exports/`。不要把 Office 文件内容当作文本塞入上下文；先检查工具返回的结构化结论，需要进一步审阅时再用宿主具备的文档工具打开文件。失败和未验证项也必须交付，保持原始证据。

skills/artemis-use/references/diagnostics.md

@@ -0,0 +1,43 @@
+# 任务排查与复盘
+
+用户给了任务编号就先针对该编号取证，不重跑业务，不停止其正在运行的任务，不把最新失败任务替换成用户指定任务。
+
+## 定位顺序
+
+1. `mobile_manage_task(action="status", trace_id=...)`，区分排队、执行、等待指导、暂停、收尾与终态。`current_step` 是动作步号，不等于模型请求数。
+2. `mobile_inspect_trace(action="view_report", trace_id=..., offset=0, limit=20)` 读取统一结果与有限步骤。`test_result.source=human` 时同时展示 AI 原判，不能用旧 AI 结论覆盖人工复验。
+3. 根据问题只读相应资料：
+
+| 问题 | inspect action | 要核对的证据 |
+| --- | --- | --- |
+| 长时间没动、API 超时、no tool call | view_requests | 请求开始/结束、模型、阶段、请求ID、重试、是否终止；HTTP 200 不表示输出结束 |
+| token 特别多、缓存是否生效 | view_usage，再按需 view_requests | prompt/completion/cached、调用数、角色/模型分组；未记录字段不能补猜 |
+| Python、ADB、插件错误 | view_logs | 该任务 stdout/stderr 有限尾部；脱敏文本和实际错误链 |
+| 点错、未验证、与结论矛盾 | search → view_step_details / view_step_screenshots | 动作前后画面、工具参数与实际回执、窗口和坐标尺寸 |
+| PC 黑屏、录像空洞、文件没保存 | view_evidence | 来源、时间、录屏片段、调用回执及附件，不用手机画面代替电脑画面 |
+
+`offset/limit` 分页，使用返回的 next_offset；view_logs 的 offset 从最新行向前计数，返回每页仍按时间正序，超过尾部读取窗口的旧字节会注明。text_truncated=true 时缩小范围或读取指定步骤，不把截断当成内容缺失。
+
+`search` 使用 query 或 step_range，不会执行历史动作。`view_summary` 也有分页，不用它一次加载整条长任务。
+
+## 缓存与耗时
+
+- 缓存命中率 = cached_tokens / prompt_tokens，分母不是总 token，也不是缓存命中的请求数。
+- 输入 token 包括缓存部分。报告输入总量、缓存量、未缓存输入、输出、调用数，保留缺少统计的限制。没有用量记录不等于零费用；没有价格信息不臆算账单。
+- 按角色/模型分组判断消耗来源，不能把 Checker、视频分析和执行模型混为一个请求。旧数据未记录模型时注明 unknown。
+- 请求阶段和重试用于解释等待，时间戳 Unix 秒及 UTC 转成用户当地时区；注明时区。无终止事件或 unknown 不能当成功。
+- 区分模型生成耗时、设备/插件操作耗时、排队及用户等待。先找实际重复观测、工具参数膨胀、无进展循环，再建议优化。
+
+## 环境与插件
+
+工具报连接/设备异常时用 `mobile_diagnose`。服务未启动时让用户先启动 ARTEMIS，不经 MCP 拉起另一个副本。一般检查先不启用付费凭据验证或真实设备探测；需要确认凭据或观测链路时再用 verify_credentials / probe_device。设备自愈用 attempt_fix，仅按返回的 next_steps 处理。
+
+`mobile_workspace` 可见插件及 blocked_resources。只对相关已安装插件做 probe_plugin 连接检查；它会启动插件进程。结果不确定的写动作不能自动再点一次，资源保护解除由用户在网页确认。
+
+## 结果与交付
+
+给出具体结论、支持它的任务/步骤/请求编号、影响与缺失证据。执行失败不必然是被测产品缺陷；验收失败也不必然是工具故障。
+
+用户只问复盘时不重新执行、不改验证结果。用户明确给出人工复验结论时，使用 mobile_manage_task(action="review", trace_id=..., review_status="passed"或"failed", review_reason=用户理由, user_confirmed=true)。AI 自己的分析不能使用这个入口冒充人工判定。
+
+用户需要资料时再 mobile_export_report；已有 report/evidence 查看不会生成 ZIP。交付真实路径或链接，并说明未验证项。

skills/artemis-use/references/exploration.md

@@ -0,0 +1,90 @@
+# 探索模式：把粗略流程变成一个可复用用例
+
+在「新任务 / 首页」选择 Flash、Pro 或「探索」，描述要验证的大概流程，再点击「开始探索」。ARTEMIS 使用 Pro 的计划、工具和验收机制推进任务；遇到关键预期不明或需要选择时，在任务主区域提问。底部输入框用于回答问题、补充信息和纠正方向；探索还提供人工示范、暂停与继续。
+
+工作区底部始终指导当前选中的任务：Flash/Pro 不会因此创建新任务；探索消息与操作步骤按时间排列。同一次探索在任务队列/历史中保留一张卡，内部执行轮次可展开查看，当前步骤对应所选轮次。通过「任务范围 → 探索任务」筛选。Flash/Pro 复跑各自保留普通任务卡，可点击「查看来源探索」返回；不会自动切换成探索对话。
+
+## 模型与超时
+
+探索独立保存模型配置，默认 `gpt-6.1-sol / high`，预设也提供 `gpt-6-astra`，允许自定义模型。执行、人工示范分析、用例提炼和结束后的讨论使用这套配置。修改默认值仅影响新探索；已创建会话保留配置快照，Flash/Pro 默认值不变。
+
+默认每段主动执行 1800 秒。模型调用、设备动作、录像分析计入；排队、等待回答和人工示范不计入。到时保存进度并暂停，可点击「继续探索」开启下一段；不会仅因超时把测试判成失败，累计主动耗时仍保留。
+
+普通暂停/等待回答会释放执行资源；继续后重新排队并观察设备。服务或执行进程中断后，已保存对话、证据和用例仍可用；继续会新建关联运行，不能恢复已经丢失的内存状态。
+
+执行过程中获取设备画面超时或连接中断时，探索会保留尚未执行的指导并暂停，释放设备。确认设备恢复响应后点击「继续探索」，重新观察成功后才交给模型执行；等待期间不自动重试、不调用模型。此类暂停不等于测试失败。若设备仍不可用，会再次明确提示并暂停。
+
+队列和历史任务以等高徽标显示「探索 / Flash / Pro」。用例复跑显示实际执行模式并另标版本；尚可继续的探索只展示当前执行状态，具体轮次的阻塞原因可在执行记录查看，结束后再展示测试结论。旧任务未保存模式时显示「模式未记录」。
+
+## 我来操作
+
+1. 点击「我来操作」，选择安卓、电脑或双来源，再点击「开始示范」。电脑来源要求任务已启用支持录制的插件。
+2. 等界面显示「录制中」后再操作。ARTEMIS 会先让当前动作安全结束、停止 AI 操作，保留相应设备与插件资源，避免其他任务抢占。
+3. 操作完成后点击「操作完成，开始分析」。ARTEMIS 停止并保存录像，分析实际画面，再显示摘要。证据明确时重新观察并继续；关键步骤或预期不清楚时再提问。
+
+即使普通录屏关闭，人工示范仍单独录制。默认 15 分钟，最后 60 秒提醒，可以延长；到时保存录像并暂停，释放资源，不能自动视为示范完成。取消或分析失败也保留已取得的媒体，可发送文字说明继续。
+
+录像不录音，沿用留档尺寸、帧率和编码配置。安卓与电脑分别保存并按任务时间对齐；示范分析只使用指定的已保存片段，不用手机截图代替电脑证据。画面不可见的输入和动作不能推测，用户示范不等于模型独立复跑通过。
+
+## 用例版本与复跑
+
+探索验收通过后提炼一个用例，包含目标、前置条件、可验证路径、等待条件和预期结果。长任务会分段提炼完整路径，原始记录保留。提炼失败不改写实际测试结论，可单独重试；未通过的探索不能自动提炼成「已验证路径」，但可以手动保存草稿。
+
+主区域的用例卡可复制提示词，点击「查看 / 编辑」展开编辑器并保存新版本，旧版本不可变。选择已保存版本和 Flash/Pro 模式，可以指定复跑模型，也可使用普通默认模型。复跑固定版本与配置，结果与探索验收分开显示。前置条件会纳入探索用例的复跑提示词。
+
+「加入新批次草稿」只创建批次，在「报告与批量」确认后启动。结束后仍可在对话中讨论与修订；需要再次操作设备时点击「继续探索」，它会重新排队并观察。新指导不会改写旧任务报告。
+
+单任务和批次「全部资料」包含对话、用例版本和关联运行索引、当前任务的示范录像及原有截图/附件。其他关联任务的媒体需从对应任务导出，索引不会假称包含它们。
+
+## MCP 与 Python SDK
+
+更新 MCP 配置并重载后，使用 `mobile_exploration`。它与网页共用接口、队列和存储；`list/get/case` 都是只读操作。
+
+```python
+mobile_exploration(
+    action="create",
+    request_id="case-search-create",
+    payload={
+        "goal": "探索设置搜索流程；关键预期不清楚时询问我",
+        "task_config": {"device_serial": "用户指定的设备编号"},
+    },
+)
+# 以下 exploration_id 使用 create 返回的 id。
+mobile_exploration(action="start", exploration_id="会话编号", request_id="case-search-start")
+mobile_exploration(action="get", exploration_id="会话编号", after=0)
+mobile_exploration(
+    action="message",
+    exploration_id="会话编号",
+    request_id="guide-1",
+    payload={"text": "只验证能打开搜索页，不修改设置"},
+)
+```
+
+写操作除 `pause/stop/delete` 外均需稳定的 `request_id`；传输失败时原样重试，不生成新编号。消息 `after` 为已读最大序号；读取返回下一页，不会启动执行。运行结束看 `runs[].test_result`，不能把 `completed` 当作测试通过。
+
+| 操作 | 参数/行为 |
+| --- | --- |
+| `pause/continue/stop` | 暂停/继续/明确取消当前执行 |
+| `demonstrate` | `payload={source:"android"/"computer"/"both"}`；等 `demonstrations[].status=recording` 再操作 |
+| `demo_finish/demo_cancel` | 传 `demonstration_id`；结束分析/取消保留媒体 |
+| `demo_extend` | 另传 `payload={seconds:900}`，同一请求不会重复延长 |
+| `case` | 可传 `version` 获取旧版本 |
+| `save_case` | `payload={expected_version,case:{name,goal,preconditions,evidence}}`；版本冲突返回 409 |
+| `generate` | `payload={source_run_id,expected_version}`；返回生成任务，轮询 `get.generations` |
+| `validate` | `payload={version,profile:"flash"/"pro",task_config:{...}}` |
+| `batch` | 与 validate 相同，可加 `name`；只建草稿 |
+
+`mobile_config(section="exploration")` 读取非敏感默认值；用户授权保存后才传 `changes` 与 `persist_defaults=true`。接口不接收 API Key，模型传输仍使用已配置的 Responses 网关。
+
+远程 SDK 的 `await client.exploration(action, exploration_id=..., request_id=..., payload=...)` 使用同样动作及参数，不创建第二套执行器。遵循当前服务返回的参数与状态。
+## 对话与结束行为
+
+- 探索助手提问后会暂停，主区域和输入框显示“等待你回答”。回答前不进行最终验收，也不生成用例。
+- 新指导优先于已完成的旧计划。最终检查期间收到指导会返回执行；例如“先回到主页，再结束”需要实际完成返回操作后再验收。
+- 设备操作及最终验收结束后进入“正在提炼用例”，此时不再接收设备指导。未发送文字会保留，提炼完成后可点击“继续探索”。用例卡片只在探索结束时展示。
+- 进入只读最终验收前停止保存录屏，模型等待、重试与用例提炼不录入视频；如需补做操作，再录制后续片段。
+- 首页探索设置使用滑块调整思考强度与时限。复跑任务显示已保存的用例名称及版本，完整提示词仍保存在任务中。
+
+## 删除探索
+
+用户明确要求删除时，先 `mobile_exploration(action="deletion_preview", exploration_id=...)` 查看影响；再 `delete` 并传 `user_confirmed=true`。删除整段对话及探索运行，独立 Flash/Pro 复跑保留。删除不需要 request_id；运行中或示范/提炼中不能删除。

skills/artemis-use/references/modes.md

@@ -0,0 +1,59 @@
+# 执行模式与单任务流程
+
+## 怎样选模式
+
+| 项目 | Flash | Pro | 探索 |
+| --- | --- | --- | --- |
+| 适合 | 目标清楚、路径明确、低分支流程；冒烟和已提炼用例复跑 | 复杂分支、持久计划、检查点、长程监控、ADB/日志、详细记录 | 流程尚未定型，用户参与纠正或示范的一个复杂用例 |
+| 执行方式 | 单执行模型观察→动作；需要时使用定位等辅助工具 | Planner 制订计划；Operator 执行；Checker 验收；按需生成报告 | 复用 Pro 工具和计划，加持续对话、提问等待、示范分析和用例提炼 |
+| 验收 | 默认结束时只读验收 | 默认结束验收，可配置检查点/strict | 先处理用户指导，再验收探索目标；不把示范当独立复跑通过 |
+| 中途输入 | `inject_instruction` 指导当前任务 | 同 Flash，还能记录计划及诊断信息 | `message` 持续交流；结束后消息仅讨论，再操作需 `continue` |
+| 入口 | `mobile_run_task(model="Flash")` | `mobile_run_task(model="Pro")` | `mobile_exploration(create/start/...)` |
+| 产物 | 步骤、证据、测试结果，按需导出报告 | 以上加计划、笔记和可选详细报告 | 对话、各轮执行和示范证据、一个用例的不可变版本 |
+| 时限 | 普通执行保护，按任务配置 | 同 Flash | 默认每段主动执行 1800 秒，达到后暂停而非判失败，可继续 |
+
+不是按步数多少机械选模式。Flash 没有默认步数上限，但不具备 Pro 的持久计划、ADB shell、过程中检查点。复杂稳定路径可以在探索确认后用 Flash 复跑；需系统诊断或检查点时用 Pro。探索不是一种更高的思考强度，Pro 的 `explorer_mode` 也不表示创建探索会话。
+
+## 模式、模型与配置
+
+- `mobile_run_task.model` 取 `Flash` / `Pro`。API 模型名放 `runtime_overrides.model`；思考强度放 `runtime_overrides.reasoning_effort`。批次使用 `task_config.profile` 选择模式，`task_config.model` 选择 API 模型。
+- 探索独立配置，默认 `gpt-6.1-sol/high`，支持 `gpt-6-astra` 及已配置网关支持的自定义模型。执行、示范分析、提炼共用该探索配置；不改变 Flash/Pro 默认值。
+- 默认 high、单次模型请求时限 300 秒。`default` 表示不发送思考强度，`none` 是显式关闭，不能混为一谈；接口不支持参数时如实报告，不擅自降级。
+- 请求时限与整任务主动执行时限不同。排队/用户暂停不计入任务主动执行；探索等待回答、人工示范也不计入。
+- 录屏 `record_video` 和 AI 视频分析 `analyze_video` 独立，默认关闭。需要可下载录像时明确启用录屏。
+- `mobile_config(section="model"/"capabilities"/"exploration"/"reports")` 可查看非敏感默认值。用户只要求运行本次任务时用临时覆盖；只有要求保存默认值才用 `changes` 和 `persist_defaults=true`。
+
+## Flash / Pro 提交
+
+```python
+mobile_run_task(
+    request_id="由调用方为本次提交生成的唯一编号",
+    task_desc="打开目标应用设置页，确认深色主题状态，保留证据；不要修改设置。",
+    model="Flash",
+    device_serial="用户指定的设备编号",
+    runtime_overrides={"reasoning_effort": "high", "record_video": True},
+)
+```
+
+- 任务提示词包含目标、必要前置条件和预期。不把业务约束仅写在批次元数据里。
+- `locked_app_package` 限定应用；跨应用流程不应锁定单个包。
+- Pro 的 `verification_level`：off 关闭检查、final 结束检查（默认）、checkpoints 检查点加结束检查、strict 更严格检查点。关闭检查后不能把执行完成视为有验收证据。
+- Pro 的 `explorer_mode`：flash 单次定位、pro 多轮定位、ultra 深度像素分析。只有明确需要时增加感知深度，避免无必要开销。
+- `expected_output_desc` 描述 Pro 需要生成的详细报告；Flash 仍可导出已有步骤/结果报告，不依赖这个参数。
+- 纯电脑任务 `runtime_overrides.execution_target="computer"`，不传手机编号；安卓为主且偶尔控制电脑时，通常保留默认目标并让 ARTEMIS 自行选择已授权插件，见 [插件参数](plugins.md)。
+
+返回后保存 `trace_id`。提交回复丢失时调用 `mobile_manage_task(action="lookup", request_id=原编号)`；得到 trace_id 后查状态。`submission_state=unknown/submitting` 不等于未执行，不能换编号自动重跑。
+
+## 跟踪、指导与结束
+
+- `mobile_manage_task(status, trace_id)` 查询当前状态。按工具建议或约 30–60 秒间隔查询，用户正在追问时可立即查看；不无休止紧密轮询，不承诺宿主未实现的后台通知。
+- `pause` 返回 pausing 只代表已接收；直到 task_paused 才能认为暂停完成。`resume` 继续原任务，恢复后重新观察并进入资源队列。
+- `inject_instruction` 传 `instruction` 指导现有任务；模型等待或只读诊断可取消，已经开始的设备动作先安全结束。暂停中发送指导会恢复，用户只希望暂存文字时不要误调用。
+- `guidance_history` 区分 pending/consumed，已领取仍不保证动作成功，需读后续步骤。
+- Pro 连续监控的 `[Loop:continuous]` 里程碑结束使用 `release_loop=true`；自然语言“结束”不能代替明确控制信号。`stop` 用于用户要求取消当前任务。
+- `completed/failed/cancelled/interrupted/skipped` 为执行终态；检查 test_result 再说明通过、失败、未验证或阻塞。人工判定附来源和原 AI 判定，不改写原始证据。
+- 实际耗时受模型、网络及设备影响，不能固定扣减 5/30 秒当作精确等待。最终外部测试脚本应使用明确等待条件。
+
+## 安卓文件
+
+任务内部支持 `android_file`，外层以任务目标交给 ARTEMIS，文件操作也走队列。截图原生 PNG 默认留存任务 trace；明确要求桌面时额外复制并校验，不需电脑插件。读写文本、列目录、pull/push 使用目标 Android 路径及任务文件边界，不能绕过应用私有目录权限。已有文件默认不覆盖。只有工具返回实际路径及校验结果才说明保存成功；「全部资料」导出包含任务文件。

skills/artemis-use/references/plugin-development.md

@@ -0,0 +1,99 @@
+# 插件开发与证据协议（2.0.0）
+
+新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；新包使用版本 2，并声明 `capabilities`。模型执行、任务队列、资源锁、超时和报告由 ARTEMIS 管理，插件不另建任务调度器，也不替用户决定用例通过。
+
+## 从可运行模板开始
+
+模板见 [evidence-demo](../assets/evidence-demo/plugin.json)。先复制整个模板目录到用户指定开发目录；执行 `mobile_workspace(include_devices=false, include_development=true)` 获取当前 ARTEMIS 的 `development.python_executable`，将其作为 `<ARTEMIS_PYTHON>`（路径含空格时按 Shell 正确引用）。主程序未启动时也可使用用户指定 ARTEMIS 环境的 Python，先确认能 import artemis；不能假设当前工作目录是 ARTEMIS 仓库。运行：
+
+```sh
+<ARTEMIS_PYTHON> <本Skill目录>/scripts/check_plugin.py <插件目录>
+<ARTEMIS_PYTHON> <本Skill目录>/scripts/check_plugin.py <插件目录> --live
+```
+
+`--live` 启动 MCP、检查真实工具定义后关闭，不执行写操作。模板默认使用 PATH 中的 Python；需要指定解释器时传 `--values '{"python":"解释器绝对路径"}'`。
+
+网页「插件 → 高级接入」支持插件目录或 ZIP 文件的完整路径。开发时可直接填模板目录；分发时在用户指定输出目录执行以下命令，生成根层包含 `plugin.json` 的 `evidence-demo.zip`：
+
+```sh
+<ARTEMIS_PYTHON> -c "import shutil; shutil.make_archive('evidence-demo', 'zip', '用户的插件目录')"
+```
+
+模板只提供文件写入工具，没有视觉观察工具。空目录加 ARTEMIS Python 即可完成清单和握手检查；它不能独立承担纯电脑任务。完整任务验收还需已连接 Android 设备，或另一个已启用、已授权且提供观察能力的视觉插件。不要为通过检查伪造 observation 能力。
+
+具备上述条件后，在插件设置中确认 `python` 指向已安装 MCP 依赖的解释器，再启用并提交“调用文件证据示例保存一段文本”。在任务步骤查看工具结果，下载「全部资料」查看 `任务文件/插件/evidence-demo/` 和 `证据索引.json`，回读文件并核对 SHA-256。没有设备或视觉插件时，明确交付已完成的检查和未执行的完整任务验收。
+
+静态检查通过不等于市场准入，也不表示业务测试通过。需按下面清单提交实际验证记录。
+
+## 清单与工具能力
+
+`plugin.json` 的安装、版本约束、资源、权限设置沿用 [插件说明](plugin-manifest.md)。版本 2 增加：
+
+| 字段 | 规则 |
+| --- | --- |
+| `capabilities.kind` | `visual`、`terminal`、`api`、`file`、`other` |
+| `capabilities.recording` | `none` 或 `windows`；只有视觉插件可声明 Windows 屏幕录制 |
+| `capabilities.tools` | 按真实 MCP 工具名定义；未声明和缺失工具均拒绝加载 |
+| `effect` | `read` / `write`，必须如实声明 |
+| `observation` | 自动观察必须只读；MCP 的 `readOnlyHint` 也必须为 true |
+| `idempotent` | 重复调用是否产生额外效果，不授权自动重试未知结果的写操作 |
+| `target_argument` | 指明资源目标的顶层参数名，必须存在于工具 JSON Schema |
+| `cancellation` | `confirmed` / `unknown`，描述工具承诺；不能代替实际停止核对 |
+| `evidence` | `text` / `image` / `file` / `state` 列表 |
+| `required_tools` | Skill 依赖的工具名，加载时校验 |
+
+MCP 参数必须有类型及合理范围；普通插件不能用不受约束的 shell 代替业务能力。终端插件若声明命令能力，应明确主机、工作目录、权限和命令边界。资源作用域用已有 `resources` 和配置约束声明；这些不是操作系统沙箱。
+
+启动、调用、关闭分别受既有 30/60/15 秒默认预算约束，并服从任务总超时。每个写操作最多派发一次；超时、取消或部分执行后先观察真实结果。远端动作未确认停止时保持资源保护。
+
+## 结果回执
+
+MCP 保留标准 `content` 和 `isError`，在 `structuredContent.artemis` 返回版本 1 回执：
+
+```json
+{
+  "version": 1,
+  "execution": "completed",
+  "side_effect": "confirmed",
+  "retryable": false,
+  "source": {
+    "kind": "computer", "target_id": "真实窗口标识", "label": "控制台",
+    "captured_at": 1792000000.25, "width": 1280, "height": 720,
+    "window": {"left": 0, "top": 0, "width": 1280, "height": 720},
+    "screen": {"left": 0, "top": 0, "width": 1920, "height": 1080}
+  },
+  "attachments": []
+}
+```
+
+- `execution`：`not_started`、`completed`、`partial`、`unknown`；`side_effect`：`none`、`possible`、`confirmed`。错误提供稳定的 `error_code` 和实际原因。只有明确未执行的请求才可声明 `retryable`，宿主仍受预算约束。
+- 截图必须属于本次目标。尺寸和范围使用物理像素，时间为 Unix 秒；`target_id` 不能只是插件名。移动、缩放、换屏、换窗口后重新观察。平台结合目标和几何信息生成来源身份，避免拿旧图做动作前证据。
+- 视觉工具通过标准 MCP image 返回图像；无法截图明确返回原因，不混入其他屏幕或猜坐标。终端返回退出码、输出和工作目录，API 返回状态/业务结果，文件返回校验信息，无须伪造图片。
+- 平台生成 `call_id`、步骤关联、开始结束时间，并写入 trace。插件不能根据一次工具成功自行生成整条用例通过结论。
+
+## 文件、录像与生命周期
+
+stdio 宿主注入 `ARTEMIS_ARTIFACTS_DIR`，插件默认把生成文件写入该目录。附件回执包含普通 `name`、`media_type`、`sha256`，不接受任意宿主绝对路径；远端插件可附带 base64 `data`。单附件不超过 64 MiB，并同时受工具结果总大小限制。禁止路径穿越、符号链接和覆盖同名不同内容。
+
+要求另存桌面时先产生并验证任务副本，再复制用户指定位置，分别报告实际结果。任一写入失败不声称全部成功。平台校验回读字节和 SHA-256，保存到任务索引；单任务和批次下载包含原生附件及插件证据。
+
+录屏默认关闭。打开后，首次取得目标观察便启动已声明来源的录制，后续动作和等待持续录制；暂停收尾，恢复追加片段，任务结束关闭进程。电脑默认记录目标所在屏幕，可改为仅目标窗口。屏幕录像可能包含同屏其他可见内容；窗口截图仍只属于目标窗口，两者范围不同。
+
+留档参数独立于模型截图：默认长边 1280、15 fps、H.265 目标 1000 kbps / H.264 1500 kbps。自动模式只有网页播放能力确认支持 HEVC 才尝试硬件 H.265，否则 H.264；编码不可用则有界回退并保留原因。网页使用真实任务时间轴，缺口不会被拼接抹去。H.265 的实际网页支持取决于浏览器/系统，手动优先 H.265 后无法播放应下载或为后续任务选择 H.264，不在下载时整段转码。
+
+录制故障不能把成功动作改为失败，也不能把缺失证据推断为测试通过。录像文件只保留一套留档版本；磁盘不足停止采集并告警。不自动恢复路由器参数、电脑状态或用户文件；只有任务提示词提出恢复要求时才执行普通恢复步骤。连接关闭、进程回收和锁释放始终必要。
+
+## 提交市场前的验证
+
+- 公共：安装/升级兼容、真实工具与清单一致、参数限制、失败/部分执行、超时取消、版本固定、资源互斥、导出索引、卸载后历史可读、无凭据泄漏。
+- 视觉：截图来源、遮挡、DPI、窗口切换、坐标一致、无图时拒绝盲点；录屏启动/结束/暂停恢复、编码回退、磁盘不足、时间缺口、关键节点、播放状态、中文可读性及长程体积。
+- 文件：中文文件名、覆盖保护、校验失败；终端/API：退出码、业务结果和不确定副作用。
+- Skill 必须只描述真实存在且已适配的能力，不绕过权限、调度和证据协议。保留来源和必要许可证，版本与实测范围明确；未测平台/场景不能写成已通过。
+
+## 从第三方项目适配到市场
+
+先核对许可证、运行平台、工具 Schema 和实际结果结构，再实现 ARTEMIS 适配；不能只复制上游 Skill 就宣称兼容。上游版本与 ARTEMIS 适配修订分别记录，例如 Cua `0.36.0+artemis.3`。
+
+开发交付应包含 plugin.json、实现/依赖声明、插件自己的 Skill、许可证/来源、安装 ZIP 与 SHA-256、实际验证记录。静态检查和握手检查只验证对应层次，不能宣称实际操作、精度或录屏已通过。通过网页「插件 → 高级接入」导入，再经 ARTEMIS 正常任务验证时间线、暂停、证据与报告；不要绕过资源锁直接并行操作用户设备。
+
+市场仓库为 https://git.playones.com/chenmingxuan/Artemis-Plugins 。只有用户明确要求发布/提交时才推送或发起市场提交；开发授权本身不代表发布授权。市场包使用固定版本、HTTPS 下载和 SHA-256，不覆盖同一版本的不同内容。未测平台和场景须明示。

skills/artemis-use/references/plugin-manifest.md

@@ -0,0 +1,127 @@
+# 插件与跨端任务（2.0.0 开发版）
+
+插件开发请阅读 [能力、证据协议与验收规则](plugin-development.md)，可运行模板位于 [Skill 内的 evidence-demo](../assets/evidence-demo/plugin.json)。新插件使用清单版本 2；版本 1 仍兼容。
+
+步骤卡标明安卓、电脑等来源，可点击查看对应录像；同一步内保留实际工具调用。开启「保存录屏」后，已使用的安卓和电脑来源各自留档，通过播放器切换。电脑录屏需要插件提供版本 2 的来源回执和录像能力声明，当前市场使用 `cua-driver` 0.36.0；旧 `open-computer-use` 适配包从 1.1.0 起支持，但已从市场下架；仅更新 ARTEMIS 源码不会升级已安装插件。旧任务缺失的电脑录像无法补录，播放器会提示查看已有步骤截图。
+
+真实时间轴保留暂停和录制中断的缺口；连续播放自动进入下一段，拖动进度到缺口时跳到下一段，并提示跳过的时间。播放器单独显示实际录制时长及蓝色录像覆盖区间；从步骤定位到未录制时间时仍明确显示缺失，不以其他时间或来源的画面替代。录像默认 1280 长边、15 fps，编码参数在功能设置的「录像留档设置」调整；不会降低模型观察截图的分辨率。
+
+Windows x64 的窗口录像使用 Windows Graphics Capture，再交给现有 FFmpeg 编码，避免 GDI 抓取硬件加速浏览器窗口时只有黑屏。启动脚本同步 `windows-capture` 依赖；仍沿用 H.265 硬件编码与 H.264 兼容回退。窗口录制不会自动扩大为整个桌面。未取得可辨识首帧、窗口最小化/关闭或采集进程异常退出时明确记录失败原因，并保留已有片段；旧任务已经录成的黑帧无法恢复成真实视频，可查看原步骤截图。
+
+单任务「全部资料」和批次资料包含插件截图、录像、调用回执和生成文件，`证据索引.json` 使用包内路径关联附件。电脑截图默认保存任务 trace，明确要求桌面时额外复制并校验。工具执行完成与测试通过仍分别呈现，不自动恢复业务环境。
+
+ARTEMIS 可通过插件连接 stdio 或 Streamable HTTP MCP 服务，并按需加载插件内的 Skill。Flash、Pro、网页任务和批次复用同一套插件执行层。版本仍在开发验证中，市场只收录完成实际验证的安装包。
+
+## 安装和配置
+
+打开网页导航中的「插件」。可以从市场安装，或在「高级接入」导入包含 `plugin.json` 的目录/ZIP，也可以填写自定义 MCP 清单。安装不执行安装钩子，新装或升级后默认未启用。
+
+普通使用只需「安装 → 启用」。电脑控制插件无需填写参数；首次启用时确认允许 ARTEMIS 操作电脑，授权保存在本机，以后无需重复确认。只有插件声明了必填参数时，才会打开设置表单，填写后勾选允许并「保存并启用」。
+
+需要切换不同设备、账号或限制操作范围时，再展开「高级设置 · 多套参数与控制范围」，管理多套参数、默认设置、工具白名单、允许的参数值和共享资源。密码留空保留已保存的值；页面和 MCP 查询只返回已配置的密钥名称。不要把密钥写进清单、提示词或任务 JSON。
+
+新装插件已有默认设置，无需创建或命名。安卓任务默认可使用支持手机扩展（targets 含 android 或 mixed）、已启用且默认设置已授权的插件。AI 先读取能力简介，需要外部操作时才加载对应工具和 Skill。任务中也可以明确选择插件；只有存在多套已授权设置时，才显示设置选择框。空列表表示不使用插件。
+
+正在排队、暂停和执行中的任务会固定插件版本，并阻止修改配置、启停、升级或卸载。操作结束后再修改。卸载会移除插件安装文件与连接配置，历史证据仍保留。
+
+## 执行任务
+
+任务输入区和批次导入区保持安卓测试入口，无需选择“手机 + 电脑”。照常描述任务，例如“电脑修改路由器参数，再在手机验证并恢复”。默认收起的「扩展插件 · 自动」可展开指定插件，或取消自动选择且不勾选插件，以仅使用手机能力。
+
+探索、Pro 和 Flash 都将插件的实际文字结果与截图交给执行模型，并保留对应调用编号；手机观察保持独立。电脑操作的步骤摘要和历史截图读取使用该次插件证据，不能用手机画面替代。若一个步骤包含多个来源的操作，查看各工具调用的截图，不把它们拼成同一屏幕的前后对比。插件没有返回图片或图片读取失败时，会明确保留证据缺失状态。
+
+最终核验附带各来源最近两次记录的画面（最多预览八个来源，其余通过历史工具读取），标明步骤、目标和采集时间。相同前后截图保留两次观察记录并共用图片文件；画面不变只是证据，不能单凭它判定点击成功、已到页底或测试通过。核验结论按要求说明已确认、发现问题、待确认或受阻，缺证据时列出具体缺项。
+
+Flash 和探索在电脑操作后的正时长 `wait_for_delay` 只等待，不刷新手机；等待后通过插件观察工具核对电脑状态。单独调用 `wait_for_delay(time_in_ms=0)` 才主动切回手机并读取新画面，旧手机控件编号不能继续使用。完全相同的前后截图直接生成事实摘要，避免重复请求视觉模型；其他视觉摘要将固定规则和任务目标放在稳定前缀中，实际缓存命中由模型服务返回值统计。
+
+插件长文本默认向模型提供最多 12,000 字符的首尾节选，完整脱敏结果保存在当前任务的 `evidence/plugin-results/`。节选提示中的 `call_id` 可通过内部工具 `plugin_read_result(call_id, offset)` 分页读取，每页最多 12,000 字符；读取范围仅限本任务，不能传入任意文件路径。截图与错误状态独立保留，文本节选不代表证据缺失或验证通过。
+
+电脑动作返回的稳定截图和控件树可直接用于下一步，切换窗口、用户接管、画面变化或证据不够时再观察。成功的只读插件步骤使用本地工具回执摘要，不再额外调用视觉模型；写操作和错误步骤仍按原流程整理证据。视觉摘要中的插件文字限为 2,000 字符，完整证据不受影响。纯观察不计入要求更新计划的连续动作数；笔记记录新结论、阻塞和关键进度，避免机械地重复读写。
+
+Flash 在连续插件操作期间不再逐次抓取、发送无关的手机截图，电脑证据保留在对应工具返回中。切回安卓时先刷新手机画面，再由模型重新决定动作；同轮中根据旧手机编号或坐标发出的动作会暂缓执行。收到用户指导或从暂停恢复时也会重新观察，避免沿用人工操作前的画面。
+
+高级 JSON、CLI 和 SDK 保留以下执行目标参数：
+
+| 目标 | 含义 |
+| --- | --- |
+| `android` | 默认手机任务，AI 按需调用已授权扩展插件 |
+| `computer` | 纯电脑任务，无需 Android；必须选择提供观察能力的插件 |
+| `mixed` | 显式跨端任务；普通安卓任务无需设置此值 |
+
+单任务 `runtime_overrides`、批次每项 `task_config` 都支持：
+
+```json
+{
+  "execution_target": "computer",
+  "plugins": [{"id": "cua-driver", "profile": "default"}],
+  "timeout_seconds": 1800
+}
+```
+
+这只是配置引用示例，先安装并启用对应插件。不要从名字推断本机已安装它。`mobile_workspace` 返回实际插件状态和连接配置，纯电脑任务可传入 `include_devices=false` 跳过 ADB 查询；`mobile_run_task` 及 `mobile_batch` 使用现有队列。
+
+CLI：`uv run artemis run "观察目标窗口并验证结果" --target computer --profile flash`。`--plugins-json` 可指定上面的插件引用数组。电脑和混合任务不会在队列服务失败后自动重复提交到另一执行器；`--standalone` 是显式选择本地 SDK 执行。
+
+SDK：先 `await agent.init(execution_target="computer")`，然后 `agent.new_task(goal).with_plugins([...]).build()`。插件引用使用 `artemis.plugins.models.PluginSelection`。`for_target()` 可设置构造器目标，必须与 `Agent.init` 相符。
+
+## 共享资源与中断
+
+同一目标应使用同一个资源名，例如 `desktop:local` 或 `router:lab`。当前采用保守调度：任务启动时统一预留所有可用插件声明的共享资源，避免执行中跨端加锁死锁；工具与进程仍按需加载。需要独立并行的手机任务可设置 plugins: []，不占插件资源。资源名不区分大小写。不同插件操作同一路由器时也要使用相同资源名。无资源声明的 MCP 插件按插件与配置名称保守互斥。
+
+暂停会先取消调用并关闭插件连接，再释放任务资源；恢复排队后重新观察。插件取消/超时的写操作可能已经生效，不能盲目重放。如果远程服务未确认动作停止，页面会显示资源保护及原因，用户核对后点击「已核对，解除保护」。这只解除 ARTEMIS 的保护，不会替用户终止远程操作。
+
+工具返回成功表示调用完成，业务是否通过仍需实际证据。图片、工具文本、插件版本和动作结果进入任务记录；已有报告、截图下载和人工复验入口继续使用。Word 的「扩展插件操作」与 Excel 的「插件操作」保留来源及实际结果，资料包截图名称含插件 ID。同一截图被多个任务引用时，删除最后一个任务后才清理。插件画面与手机截图属于不同来源，不能相互替代。电脑录像从首次取得有效窗口画面开始，按实际来源留存；启动失败或中断会保留状态和原因。
+
+## 插件清单
+
+```json
+{
+  "schema_version": 2,
+  "id": "lab-control",
+  "name": "实验室控制",
+  "version": "1.0.0",
+  "artemis_version": ">=2.0.0,<3.0.0",
+  "platforms": ["win32"],
+  "architectures": ["amd64"],
+  "targets": ["mixed"],
+  "server": {
+    "transport": "stdio",
+    "command": "${plugin_dir}/bin/server.exe",
+    "args": [],
+    "env": {"TOKEN": "${secret.token}"}
+  },
+  "skill": "SKILL.md",
+  "config": {"token": {"label": "连接密钥", "secret": true, "required": true}},
+  "resources": ["router:lab"],
+  "capabilities": {
+    "kind": "api", "recording": "none", "required_tools": ["read_status"],
+    "tools": {"read_status": {
+      "effect": "read", "observation": false, "idempotent": true,
+      "cancellation": "confirmed", "evidence": ["state", "text"]
+    }}
+  }
+}
+```
+
+HTTP 服务使用 `{"transport":"streamable_http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer ${secret.token}"}}`。配置引用支持 `${config.字段}`、`${secret.字段}` 和 `${plugin_dir}`；参数直接以 argv 启动，不经 shell。纯 Skill 可省略 `server`。Skill 的引用文件必须在包内，按需读取支持不超过 256 KiB 的 Markdown、文本和 JSON。
+
+提供电脑画面观察的插件声明 `observation`，其中 `tool` 和 `arguments` 为初始观察调用，`refresh_tools` 为模型选择目标后可复用的只读观察工具名。例如初始列窗口，选择窗口后每步刷新该窗口。观察允许只返回文字；无图时不能伪造截图或推测像素坐标。
+
+清单提供的工具和参数范围检查不是操作系统沙箱；第三方进程以当前用户权限运行。市场包使用 HTTPS、SHA-256、平台/版本检查及安全解压，包内应保留许可证和来源记录。
+
+市场索引为 `{"schema_version":1,"plugins":[...]}`，每项包含 `manifest`、`archive_url`、`sha256`、`verification`，以及 release_stage（stable 或 preview，默认 stable）。开发预览在市场明确标注，并提供已验证范围和未覆盖场景。同一版本不可覆盖，先验证新包再使用新版本号。
+
+## 环境参数
+
+| 环境变量 | 默认值 |
+| --- | --- |
+| `ARTEMIS_PLUGIN_MARKETPLACE_URL` | Artemis-Plugins 仓库的 catalog.json |
+| `ARTEMIS_PLUGIN_START_TIMEOUT_SECONDS` | 30 秒 |
+| `ARTEMIS_PLUGIN_TOOL_TIMEOUT_SECONDS` | 60 秒 |
+| `ARTEMIS_PLUGIN_SHUTDOWN_TIMEOUT_SECONDS` | 15 秒 |
+| `ARTEMIS_PLUGIN_DOWNLOAD_TIMEOUT_SECONDS` | 300 秒 |
+| `ARTEMIS_PLUGIN_DOWNLOAD_MAX_BYTES` | 128 MiB |
+| `ARTEMIS_PLUGIN_EXTRACT_MAX_BYTES` | 512 MiB |
+| `ARTEMIS_PLUGIN_RESULT_MAX_BYTES` | 16 MiB |
+
+修改环境参数后重启开发版服务。任务总时限仍由现有执行保护控制，插件不会自行无限重试。

skills/artemis-use/references/plugins.md

@@ -0,0 +1,26 @@
+# 插件任务参数
+
+先调用 `mobile_workspace`，只选实际存在、已启用且配置已授权的插件。纯电脑任务使用 `include_devices=false`，避免不必要的 ADB 查询。通过现有 `mobile_run_task` 发起电脑任务：
+
+```json
+{
+  "request_id": "本次提交的唯一编号",
+  "task_desc": "观察已打开的测试控制台，确认参数值符合用户预期，并保留证据。",
+  "model": "Flash",
+  "runtime_overrides": {
+    "execution_target": "computer",
+    "plugins": [{"id": "cua-driver", "profile": "default"}],
+    "timeout_seconds": 1800
+  }
+}
+```
+
+示例中的插件必须已安装；不要为解决缺插件而调用宿主私有电脑工具代替 ARTEMIS 执行。`computer` 无需 `device_serial`，`mixed` 同时需要手机与插件资源。批次每个用例的 `task_config` 使用相同字段，可混合不同配置和执行目标。
+
+未提供 `plugins` 表示使用该目标下已启用插件的授权默认配置；空数组明确不用插件。只提供插件 ID 和配置名称，版本由服务在入队时固定。安装、授权、连接凭据和资源保护解除由用户在插件页面处理。
+
+插件超时/取消后先查任务状态和错误，不自动重放点击或配置写入。`mobile_workspace.blocked_resources` 非空时说明存在尚未确认停止的资源，不能声称暂停已安全完成。工具返回成功还需从后续画面或结构化读数验证业务结果。
+
+普通安卓测试无需指定 execution_target 或 mixed：省略 plugins 时，AI 可以按需加载已启用、默认配置已授权且支持 android/mixed 的插件。仅需手机能力或不希望预留桌面资源时使用 plugins: []。网页、MCP 和批次采用相同规则。
+
+连接失败可使用 `mobile_workspace(include_devices=false, plugin_id=实际插件ID, probe_plugin=true)`；它会启动已授权插件做连接和工具声明检查，不执行测试动作。读取清单不等于实测通过。