Artemis-Plugins/DESIGN.md

Artemis Plugins 设计约定

Overview

ARTEMIS 3.x 测试分支使用独立 catalog-v5.json：Cua 0.38.0+artemis.2、task-review 1.1.1 与 artemis-device-test 0.5.0+artemis.7。旧索引和 <3.0.0 约束不变；测试包保留各自未测范围，不代替 Rust 业务验收。来源与边界见 3.0 测试市场说明。

本仓库维护 ARTEMIS 插件适配与市场分发。当前发布基线是 Cua Driver 0.38.0 的 Windows x64 适配，市场版本为 0.38.0+artemis.1，保留预览标识。后续版本以目标分支的清单、市场索引、来源记录和发行说明为准。

这是适配器架构与行为设计，插件没有独立产品网页或通用配色。主程序网页的视觉规则由其根目录 DESIGN.md 管理；包内 SKILL.md 指导调用方如何使用实际工具，不代替宿主权限或证据校验。

System architecture

层	职责
ARTEMIS 宿主	模型、任务准入、队列与资源互斥、插件安装授权和版本固定、录屏、步骤、附件、报告及最终验收
Go 适配器	通过 stdio MCP 暴露所需工具；校验工具参数、目标身份、截图几何与错误；转换真实观察、动作回执和附件
固定 Cua Driver	执行窗口发现、UIA、截图和输入；会话自有 Driver/UIA 子进程随宿主生命周期回收
市场与安装包	catalog.json 描述兼容平台、包地址、SHA256 与验证边界；构建产出自包含 ZIP、适配源码、许可证和 provenance.json

插件沿用宿主的 desktop:local 资源和任务版本固定，不增设业务调度、AI、录屏、环境恢复或远程云服务。主程序仍可在同一任务中按需使用安卓和电脑能力，最终裁定由对应来源的真实证据支持。

旧 OCU 从市场入口下架，但其源码、旧发行附件、已安装版本和历史证据保留。插件安装、授权、更新及切换由用户发起，不能在任务运行中静默更换实现。

Observation and action flow

1. 按应用名或已知 PID 发现目标窗口；同时给出筛选时取交集。未知 PID 省略或设 null，无效 PID 在驱动调用前拒绝，驱动错误不伪装成空列表。
2. 读取窗口截图与 UIA 树，保存实际 pid、window_id、snapshot_id、capture_id、尺寸、位置与焦点信息。
3. UIA 控件动作使用当前 token；像素动作只使用同一张截图上的窗口局部坐标，交给适配器完成所需映射。
4. 在输入前校验参数互斥、窗口身份、截图有效性、坐标范围和必要的前台激活。旧图、窗口移动或缩放后重新观察。
5. 一次调用只执行一次请求动作，随后返回真实观察与明确回执；新的 snapshot/token 和 capture 替代旧标识。
6. 需要留档时保存当前窗口 PNG，读回真实文件并返回哈希与附件；宿主负责关联任务步骤、来源和报告。

应用名、窗口标题、地址栏及页面内容共同帮助核对身份；不能把无关前台应用的 PID 当成目标，也不能只因同一插件返回过一张图就复用到另一窗口。

Input and coordinate contracts

工具	约束
click	使用最新控件 token；不与像素坐标混用
click_at、drag	使用最新 capture_id 和同图坐标；拖拽两端均需校验
scroll	最新截图中的滚动区域坐标与 capture_id，不用控件 token；刻度不是精确像素或固定页数，需确认实际位移
press_key、type_text	操作目标窗口当前焦点；不传控件 token 或 x/y，先用独立动作聚焦
set_value	必须给出当前可赋值控件 token，不能把同名文本标签当作输入框
save_screenshot	filename 只是文件名；保存到任务 trace，拒绝覆盖、路径逃逸和缺失真实文件的附件

UIA 的屏幕坐标不是截图局部像素。滚动映射、点击及拖拽的既有映射分别核对，避免重复缩放；旧 capture_id、越界、窗口几何变化或截图读取失败均在派发前拒绝。定位失败后刷新观察，不能原样重复同一错误动作。

Foreground and evidence

Chromium 浏览器点击、按键、输入和滚动使用明确的 foreground 路径。适配器先调用既有激活能力并核实准确 HWND，再发送一次输入，随后保持目标前台供渲染、后续观察和录像。激活未确认时不发送业务输入，输入结果不明时不重发。

只读观察及截图保存不抢焦点，capture_focus 记录采集前后的前台状态。正文灰屏或只剩外壳时，先核对同一窗口的前台状态，再显式恢复目标并观察；不通过重复刷新、提交表单或业务点击来尝试恢复。

这条路径会占用用户前台。当前没有接入独立浏览器 DOM、已有登录会话的调试通道、隔离桌面或 Cua 云环境，不能承诺用户与模型互不干扰地操作同一桌面。

回执区分未执行、部分执行、无法确认及已验证。投递成功、PNG 保存或截图哈希一致只证明各自操作，不证明业务检查通过。安卓截图不能充当电脑证据，空白截图也不能充当网页缺陷证据。

Lifecycle and distribution

每个插件会话启动自己的适配器、Driver 和 UIA helper；Windows Job Object 负责取消、关闭和宿主退出后的进程回收。遥测设置只作用于该子进程环境，不修改用户全局设置。

构建固定上游 Cua Driver 的版本、提交和 ZIP SHA256，只打包所需可执行运行依赖及适配源码、工具描述、许可证、使用规则和验证记录。用户安装自包含 ZIP，不需要为此另装 Go、Python、Node 或另一套 Codex MCP。

插件清单、握手版本和包名保持一致；provenance.json 记录实际上游、校验值和适配修订。只修改适配时使用新的 +artemis.N 包，既有同版本包不可覆盖。市场变更引用已验证的 HTTPS 安装包和哈希。

Verification and change entrypoints

变更	主要入口与验证
窗口发现	适配器的窗口查找实现及对应 Go 回归；独立应用名发现脚本
输入与状态回执	main.go、tools.json、plugin.json、包内 Skill 共同维护；明确未执行与结果未知场景
坐标与前台	发布分支的 coordinates.go、foreground.go 及对应测试；覆盖缩放、旧图、越界、移动、激活失败和只读不抢焦点
包与市场	scripts/build_cua_driver.py、来源记录、catalog.json、发行说明及公开下载校验
真机联调	主程序调度与桌面资源锁内运行隔离窗口测试；真实业务、录像和最终裁定另外验收

具体 Go 与构建命令见 AGENTS.md。修改行为时同步工具声明、实现、文档及相应回归；只更新文档时检查命令、相对链接和所指版本，无需操作用户桌面或调用付费模型。

VERIFICATION.md 区分候选对照、应用名发现、输入、坐标和前台修订。候选的独立验收 3/3 与 AI 裁定 2 次通过、1 次未判定不能合并成“全部通过”；约 26.1% token 差异包含对照缺陷和重试成本。复杂浏览器控制台、多 DPI、多屏和长程混合任务继续按实际覆盖范围声明。

Working across divergent checkouts

本地目录可能保留 OCU 与早期 Cua 候选改动，而发布引用已经包含后续修订。先检查 Git 状态、分叉提交和具体文件，分别记录源码状态、发布状态及实际安装状态；旧候选文档的结论不能覆盖发布记录。

发布范围较窄时可在最新目标分支的隔离工作树中移植本次提交，推送后核对远端 SHA。原目录的未归并分支和用户改动继续保留，不能为了发布文档而顺带推送全部历史、覆盖文件或删除本地开发现场。

声明式工作区扩展

plugins/task-review 使用清单版本 3 的 workspace 接口。插件声明面板位置和宽度、字段标签/选项/报告属性；宿主负责安全渲染、响应式布局、任务绑定存储、并发保存与报告缓存。纯界面扩展不声明 MCP、Skill、设备资源或调度器，不参与模型执行插件选择。

评审由人工填写，使用「通过 / 失败」按钮，备注独立选填。未装或停用时不贡献界面与新报告字段；卸载保留任务内记录，重装后恢复；任务删除时清理。插件不可改写原任务执行状态或既有复验结论。

工作区扩展从 ARTEMIS 2.3.0 起提供。catalog-v4.json 服务 2.4.0+，catalog-v3.json 保留给 2.3.x，旧 catalog.json 保留给严格校验清单版本的 2.2.x。2.3.x 不能解析 original_case 面板，人工评审 1.1.0 仅加入 v4 索引；旧索引保留兼容版本。执行插件更新应同步兼容的索引。先发布并回读核验不可变附件，再提交包含新插件的市场索引。