# 插件与跨端任务（2.0.0 开发版）

插件开发请阅读 [能力、证据协议与验收规则](plugin-development.md)，可运行模板位于 `examples/plugins/evidence-demo`。新插件使用清单版本 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 |

修改环境参数后重启开发版服务。任务总时限仍由现有执行保护控制，插件不会自行无限重试。