docs: document Cua adapter and marketplace development rules

DESIGN.md

@@ -0,0 +1,82 @@
+# Artemis Plugins 设计约定
+
+## Overview
+
+本仓库维护 ARTEMIS 插件适配与市场分发。当前发布基线是 Cua Driver 0.36.0 的 Windows x64 适配，市场版本为 `0.36.0+artemis.4`，保留预览标识。后续版本以目标分支的清单、市场索引、来源记录和发行说明为准。
+
+这是适配器架构与行为设计，插件没有独立产品网页或通用配色。主程序网页的视觉规则由其根目录 DESIGN.md 管理；包内 [SKILL.md](plugins/cua-driver/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](AGENTS.md)。修改行为时同步工具声明、实现、文档及相应回归；只更新文档时检查命令、相对链接和所指版本，无需操作用户桌面或调用付费模型。
+
+[VERIFICATION.md](plugins/cua-driver/VERIFICATION.md) 区分候选对照、应用名发现、输入、坐标和前台修订。候选的独立验收 3/3 与 AI 裁定 2 次通过、1 次未判定不能合并成“全部通过”；约 26.1% token 差异包含对照缺陷和重试成本。复杂浏览器控制台、多 DPI、多屏和长程混合任务继续按实际覆盖范围声明。
+
+## Working across divergent checkouts
+
+本地目录可能保留 OCU 与早期 Cua 候选改动，而发布引用已经包含后续修订。先检查 Git 状态、分叉提交和具体文件，分别记录源码状态、发布状态及实际安装状态；旧候选文档的结论不能覆盖发布记录。
+
+发布范围较窄时可在最新目标分支的隔离工作树中移植本次提交，推送后核对远端 SHA。原目录的未归并分支和用户改动继续保留，不能为了发布文档而顺带推送全部历史、覆盖文件或删除本地开发现场。