82 lines
8.6 KiB
Markdown
82 lines
8.6 KiB
Markdown
# 工作区插件：侧栏、人工字段与报告
|
||
|
||
工作区扩展使用 `plugin.json` 的 `schema_version: 3` 和 `workspace` 声明。旧版 1/2 执行插件继续兼容。纯工作区插件无需 MCP、Skill、模型、设备或任务资源，不出现在任务执行插件选择器中；安装后手动启用即可在历史任务上使用。此接口从 ARTEMIS 2.3.0 起提供；插件必须声明 `artemis_version: ">=2.3.0,<3.0.0"`，2.2.x 不支持。`original_case` 面板从 2.4.0 起提供，使用它的插件须声明 `>=2.4.0,<3.0.0`。
|
||
|
||
## 声明接口
|
||
|
||
清单仍要求 `capabilities`。纯界面插件填写 `{"kind":"other","tools":{}}`，可将 `targets` 设为空数组。工作区声明完全由宿主渲染，不加载任意 JavaScript、HTML 或后端执行钩子。
|
||
|
||
以下是可直接保存为 `plugin.json` 的完整最小清单：
|
||
|
||
```json
|
||
{
|
||
"schema_version": 3,
|
||
"id": "review-example",
|
||
"name": "评审扩展示例",
|
||
"version": "1.0.0",
|
||
"artemis_version": ">=2.4.0,<3.0.0",
|
||
"platforms": ["win32", "linux", "darwin"],
|
||
"targets": [],
|
||
"capabilities": {"kind": "other", "tools": {}},
|
||
"workspace": {
|
||
"panels": [
|
||
{"id":"requirements","title":"原始用例","side":"left","kind":"original_case","width":{"preferred":340,"minimum":240,"maximum":480}},
|
||
{"id":"review","title":"人工评审","side":"right","kind":"form","width":{"preferred":360,"minimum":260,"maximum":520}}
|
||
],
|
||
"fields": [
|
||
{"id":"execution_accuracy","label":"用例执行准确性","kind":"choice","options":["通过","失败"]},
|
||
{"id":"execution_note","label":"用例执行准确性备注","kind":"text","max_length":2000}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
- `panels`：最多两个，`id` 和 `kind` 各自唯一；`side` 为 left/right。`initial_prompt` 展示该次运行最初收到的任务需求提示词，复用宿主 Markdown 渲染及 HTML 清理；不展示模型拆解步骤或后续指导。`original_case` 以用例编号与标题为标题，依次展示导入表中的预置条件、操作步骤、预期结果；缺失时明确提示，不从提示词推测。`form` 渲染本插件声明的字段。
|
||
- `width`：CSS 像素，满足 minimum ≤ preferred ≤ maximum。minimum 范围 160–800，preferred 200–1000，maximum 200–1200。宿主优先采用首选宽度，并根据播放器、窗口空间调整；窄屏可低于 minimum 防止溢出。开关位于回放标题栏，以左右方向表示展开与收起。Flash/Pro/探索以及安卓、电脑、跨端任务的步骤、视频或实时视图均可使用；普通浮窗、影院均支持，默认收起；宽屏左右独立展开，窄屏一次展开一侧；单侧也始终位于回放左侧或右侧，不切换为上下排列。
|
||
- `fields`：最多 20 个，`id` 唯一；`kind` 为 choice/text。choice 声明非空、不重复的 options，显示为互斥分段按钮，再次点击已选项可清空；text 使用多行输入。description 可选。max_length 默认 2000、最高 10000；report 默认 true。所有字段均选填，空字符串表示未填写，用户可清空。
|
||
- 两项人工评审的标签和说明由插件提供；宿主不推断结果、不调用模型、不覆盖执行状态、AI 原判或既有人工复验。
|
||
|
||
## 任务数据接口
|
||
|
||
`GET /api/task-extensions/{session_id}` 返回 `session_id`、`initial_prompt`、`case_title`、`original_case`、`navigation`、`editable` 和已安装且启用的插件贡献列表。每项包含 plugin_id/name/version/workspace/revision/values/history。无插件时列表为空。
|
||
|
||
`original_case` 为 `{preconditions, steps, expected}` 或 null。只有安装并启用声明 `original_case` 面板的插件时，批量模板才附加“预置条件、操作步骤、预期结果”三列并接受十列表格；否则仍只提供和接受原七列。三列不进入模型提示词。启用时也兼容七列表格，历史缺失字段不补写。
|
||
|
||
批次任务的 `navigation` 含 scope=batch、position、total、previous、next，按执行顺序在同批次已结束任务之间切换；独立任务使用当前历史列表。上一条/下一条位于保存评审按钮下方。用户选择结果后立即自动保存，备注停止输入 600 毫秒后保存；连续编辑按修订串行写入，旧回执不覆盖新输入。切换前先保存，失败或冲突时留在当前任务并保留输入；手动保存可重试，使用原 request_id 防止重复。切换保留面板展开状态。打开任务或读取已有记录不触发写入。
|
||
|
||
`PUT /api/task-extensions/{session_id}/{plugin_id}` 接收：
|
||
|
||
```json
|
||
{"values":{"execution_accuracy":"通过","execution_note":"人工核对"},"expected_revision":0,"request_id":"00000000-0000-4000-8000-000000000001"}
|
||
```
|
||
|
||
values 是本次提交的字段；未提交的字段保持原值。保存仅允许终态任务（完成、失败、取消、中断、跳过），运行中只读。宿主校验声明、长度和选项；expected_revision 防止多个页面互相覆盖。网络重试复用 request_id 和相同内容，不追加重复历史；修改内容使用新 request_id。保存冲突返回 409，并保留页面输入。
|
||
|
||
数据复用宿主 automation_records，以 task_extensions/session_id 保存各插件独立记录；历史包含字段声明、插件版本、保存时间、revision 和当时值。按单次运行绑定，复跑不继承评审。禁用/卸载隐藏界面与新导出的字段，但保留历史；重新安装启用同一插件 ID 后恢复。删除任务/批次时同步清理对应评审。
|
||
|
||
## 导出
|
||
|
||
已安装且启用的插件声明 report=true 的字段，进入单任务 Word/Excel、批次 Word/Excel 汇总和 ZIP 内报告。未填字段留空，不阻止导出。未安装、禁用或卸载时无对应报告区块；已下载文件保持原内容。
|
||
|
||
单任务导出指纹包含扩展快照，批次缓存包含插件安装/启用声明与任务扩展修订。保存使用既有导出锁并使批次报告失效，防止下载旧评审。导出不需要运行插件进程或调用模型。
|
||
|
||
## 独立人工评审插件
|
||
|
||
插件源代码位于独立 Artemis-Plugins 仓库的 `plugins/task-review/`，包名 task-review，1.1.0 要求宿主 2.4.0，可从插件市场安装，或通过高级接入导入发行 ZIP。它声明原始用例面板，以及「用例执行准确性」「测试结果正确性」两个 通过/失败 字段和各自可选备注。
|
||
|
||
在已更新宿主的环境，用 `uv run python scripts/check_plugin.py <插件目录>` 检查清单，再在「插件 → 高级接入」导入目录或 ZIP。安装、启用、填写、清空、导出、禁用、卸载和重新安装均应通过确定性测试；只检查清单不代表界面和导出已验证。
|
||
|
||
## 开发与兼容边界
|
||
|
||
这里的 SDK 是声明式清单协议与宿主 HTTP 接口，不要求编写插件运行进程。当前不支持自定义 JavaScript、HTML、上传控件、跨任务统计或任意报告模板钩子。执行插件可以在版本 3 清单中同时保留 MCP/Skill 和 workspace；原有工具、资源和证据约束仍适用。
|
||
|
||
面板及字段 id 使用小写字母开头的字母、数字、下划线，最长 48 字符；稳定 id 是历史数据的键，不应为了改显示名称而更换。更改选项或删除字段不会迁移历史；当前导出按当前声明取值，发行不兼容字段变更前须验证旧数据。字段没有必填模式，不能以校验拦截用户的空项。
|
||
|
||
GET 成功返回完整贡献快照；PUT 成功返回同样结构和新 revision。404 表示任务不存在，422 表示请求结构、UUID 或参数格式无效；409 包含运行中只读、插件未启用、报告正在打包、修订冲突、无效字段值或幂等请求冲突。冲突时保留本地输入，刷新并由用户决定如何合并，不能自动覆盖。
|
||
|
||
人工结果只能由用户填写；AI 不自行调用 PUT 生成或推断评审。此接口未加入模型 MCP 工具或远程 Python SDK 的人工写入方法。插件没有设备目标时，无需为安装验证提交安卓/PC 测试任务；用隔离终态示例验证保存、清空、重装、导出与旧缓存失效即可。
|
||
|
||
市场发布时保持清单、ZIP、版本标签与 catalog-v4.json 内嵌清单一致；先上传不可变 ZIP 与 SHA256SUMS.txt 并回读验证，再更新索引。仅静态清单校验通过不能宣称全部平台已实测。
|
||
|
||
官方市场为 2.4.0+ 提供 catalog-v4.json，catalog-v3.json 保留给 2.3.x，catalog.json 保留给 2.2.x，避免旧宿主严格解析新面板类型时导致整个市场加载失败。2.4.0 读取原官方 catalog.json 或 catalog-v3.json 地址时自动选择新版索引，不改写用户配置；自定义市场地址不会被替换。
|