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

ARTEMIS 可通过插件连接 stdio 或 Streamable HTTP MCP 服务，并按需加载插件内的 Skill。Flash、Pro、网页任务和批次复用同一套插件执行层。版本仍在开发验证中，市场只收录完成实际验证的安装包。

## 安装和配置

打开网页导航中的「插件」。可以从市场安装，或在「高级接入」导入包含 `plugin.json` 的目录/ZIP，也可以填写自定义 MCP 清单。安装不执行安装钩子，新装或升级后默认未启用。

点击「配置」建立命名连接，例如 `lab-router`。填写字段、工具白名单、允许的参数值和共享资源，勾选授权后保存，再启用插件。密码留空保留已保存的值；页面和 MCP 查询只返回已配置的密钥名称。不要把密钥写进清单、提示词或任务 JSON。

每个插件可设置一套默认连接。自动选择只使用符合任务目标、已启用且默认连接已授权的插件。任务中也可以明确选择插件与连接；空列表表示不使用插件。

正在排队、暂停和执行中的任务会固定插件版本，并阻止修改配置、启停、升级或卸载。操作结束后再修改。卸载会移除插件安装文件与连接配置，历史证据仍保留。

## 执行任务

任务输入区和批次导入区有执行目标选项：

| 目标 | 含义 |
| --- | --- |
| `android` | 手机任务，默认不使用桌面插件 |
| `computer` | 纯电脑任务，无需 Android；必须选择提供观察能力的插件 |
| `mixed` | 手机和扩展插件组合任务 |

单任务 `runtime_overrides`、批次每项 `task_config` 都支持：

```json
{
  "execution_target": "computer",
  "plugins": [{"id": "open-computer-use", "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`。资源名不区分大小写。不同插件操作同一路由器时也要使用相同资源名。无资源声明的 MCP 插件按插件与配置名称保守互斥。

暂停会先取消调用并关闭插件连接，再释放任务资源；恢复排队后重新观察。插件取消/超时的写操作可能已经生效，不能盲目重放。如果远程服务未确认动作停止，页面会显示资源保护及原因，用户核对后点击「已核对，解除保护」。这只解除 ARTEMIS 的保护，不会替用户终止远程操作。

工具返回成功表示调用完成，业务是否通过仍需实际证据。图片、工具文本、插件版本和动作结果进入任务记录；已有报告、截图下载和人工复验入口继续使用。Word 的「扩展插件操作」与 Excel 的「插件操作」保留来源及实际结果，资料包截图名称含插件 ID。同一截图被多个任务引用时，删除最后一个任务后才清理。插件画面与手机截图属于不同来源，不能相互替代。电脑持续录屏不属于首版能力。

## 插件清单

```json
{
  "schema_version": 1,
  "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"]
}
```

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`。同一版本不可覆盖，先验证新包再使用新版本号。

## 环境参数

| 环境变量 | 默认值 |
| --- | --- |
| `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 |

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