# 插件开发 SDK 与证据协议（ARTEMIS 2.3.0）

新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；执行插件使用版本 2，并声明 `capabilities`。工作区面板和人工表单使用版本 3，详见[工作区插件接口](workspace-plugins.md)。纯工作区插件不加入任务执行选择，不向模型开放人工评审写入工具。模型执行、任务队列、资源锁、超时和报告由 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，不覆盖同一版本的不同内容。未测平台和场景须明示。