99 lines
7.4 KiB
Markdown
99 lines
7.4 KiB
Markdown
# 插件与跨端任务（2.0.0 开发版）
|
||
|
||
ARTEMIS 可通过插件连接 stdio 或 Streamable HTTP MCP 服务，并按需加载插件内的 Skill。Flash、Pro、网页任务和批次复用同一套插件执行层。版本仍在开发验证中，市场只收录完成实际验证的安装包。
|
||
|
||
## 安装和配置
|
||
|
||
打开网页导航中的「插件」。可以从市场安装，或在「高级接入」导入包含 `plugin.json` 的目录/ZIP，也可以填写自定义 MCP 清单。安装不执行安装钩子，新装或升级后默认未启用。
|
||
|
||
普通使用只需「安装 → 启用」。电脑控制插件无需填写参数；首次启用时确认允许 ARTEMIS 操作电脑，授权保存在本机，以后无需重复确认。只有插件声明了必填参数时，才会打开设置表单，填写后勾选允许并「保存并启用」。
|
||
|
||
需要切换不同设备、账号或限制操作范围时，再展开「高级设置 · 多套参数与控制范围」，管理多套参数、默认设置、工具白名单、允许的参数值和共享资源。密码留空保留已保存的值；页面和 MCP 查询只返回已配置的密钥名称。不要把密钥写进清单、提示词或任务 JSON。
|
||
|
||
新装插件已有默认设置，无需创建或命名。安卓任务默认可使用支持手机扩展（targets 含 android 或 mixed）、已启用且默认设置已授权的插件。AI 先读取能力简介，需要外部操作时才加载对应工具和 Skill。任务中也可以明确选择插件；只有存在多套已授权设置时，才显示设置选择框。空列表表示不使用插件。
|
||
|
||
正在排队、暂停和执行中的任务会固定插件版本，并阻止修改配置、启停、升级或卸载。操作结束后再修改。卸载会移除插件安装文件与连接配置，历史证据仍保留。
|
||
|
||
## 执行任务
|
||
|
||
任务输入区和批次导入区保持安卓测试入口，无需选择“手机 + 电脑”。照常描述任务，例如“电脑修改路由器参数，再在手机验证并恢复”。默认收起的「扩展插件 · 自动」可展开指定插件，或取消自动选择且不勾选插件，以仅使用手机能力。
|
||
|
||
高级 JSON、CLI 和 SDK 保留以下执行目标参数：
|
||
|
||
| 目标 | 含义 |
|
||
| --- | --- |
|
||
| `android` | 默认手机任务，AI 按需调用已授权扩展插件 |
|
||
| `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`。当前采用保守调度：任务启动时统一预留所有可用插件声明的共享资源，避免执行中跨端加锁死锁；工具与进程仍按需加载。需要独立并行的手机任务可设置 plugins: []，不占插件资源。资源名不区分大小写。不同插件操作同一路由器时也要使用相同资源名。无资源声明的 MCP 插件按插件与配置名称保守互斥。
|
||
|
||
暂停会先取消调用并关闭插件连接，再释放任务资源；恢复排队后重新观察。插件取消/超时的写操作可能已经生效，不能盲目重放。如果远程服务未确认动作停止，页面会显示资源保护及原因，用户核对后点击「已核对，解除保护」。这只解除 ARTEMIS 的保护，不会替用户终止远程操作。
|
||
|
||
工具返回成功表示调用完成，业务是否通过仍需实际证据。图片、工具文本、插件版本和动作结果进入任务记录；已有报告、截图下载和人工复验入口继续使用。Word 的「扩展插件操作」与 Excel 的「插件操作」保留来源及实际结果，资料包截图名称含插件 ID。同一截图被多个任务引用时，删除最后一个任务后才清理。插件画面与手机截图属于不同来源，不能相互替代。电脑持续录屏目前尚未实现，已纳入[步骤、录像与插件开发规范设计](plans/2.0.0-plugin-evidence.md)；该设计不是当前版本的能力声明。
|
||
|
||
## 插件清单
|
||
|
||
```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`，以及 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 |
|
||
|
||
修改环境参数后重启开发版服务。任务总时限仍由现有执行保护控制，插件不会自行无限重试。
|