5.1 KiB
5.1 KiB
Artemis Plugins 协作指南
Scope
- 本文件适用于本仓库，当前用户指令优先。主程序
artemis是独立仓库，两者分别提交、验证和推送。 - 本仓库负责插件适配、工具契约、构建和市场索引；主程序负责模型、调度、资源锁、录屏、证据、任务与最终验收。
- 修改适配器、工具、包或市场前，读 DESIGN.md；具体调用规则见插件包内的 SKILL.md，验证结论见对应 VERIFICATION.md。
- 先区分本地源码、远端发布引用和机器已安装版本。遇到旧 OCU/Cua 候选现场与市场文档不一致时，先查分叉和实际版本，不覆盖本地改动，不把旧候选文档直接当作当前市场状态。
- 已有未发布提交或脏文件不属于本次任务时，隔离检出最新目标分支，只移植本次提交；不使用重置、清理、强推或整仓暂存来跳过比较。
Commands and Evidence
以下是原生命令；宿主要求 RTK 时按宿主规则包装，不把本机工具路径写成项目依赖。
| 用途 | 工作目录 | 命令或入口 |
|---|---|---|
| 比较当前状态 | 仓库根目录 | git status --short --branch、git log --left-right --oneline HEAD...origin/main |
| Cua 确定性回归 | plugins/cua-driver |
go test ./...、go vet ./...；Go 1.22+，Windows 适配 |
| 构建参数 | 仓库根目录 | python scripts/build_cua_driver.py --help；固定上游 ZIP 和 Go 路径的用法见 README |
| Windows 实测 | 仓库根目录 | 按对应验证记录运行 tests/cua_smoke.py、tests/cua_fixture_validation.py；使用已有 ARTEMIS 依赖和正确的 PYTHONPATH |
| 提交前 | 仓库根目录 | git diff --check、git diff --cached --check，核对精确暂存路径 |
浏览器及前台实测先读 Cua 验证记录，确认脚本会操作的测试窗口、应用及桌面资源。执行涉及用户应用的交互任务时，沿用主程序的 ARTEMIS 探索和资源锁，不为文档验证启动业务任务。
Adapter Contracts
- 当前市场使用 Cua，旧 OCU 的源码、附件、用户安装和历史证据继续保留。版本以目标提交的
catalog.json、清单与发行说明核对，不能由本地未发布文件推定。 - 复用宿主
desktop:local、任务固定版本、步骤与录像。插件不新增模型循环、业务队列、独立录屏器、自动回放或默认业务回滚流程。 - 工具的 schema、
plugins/cua-driver/tools.json、清单能力声明、实现和包内 Skill 同步更新。参数互斥、类型、窗口范围和错误语义在发送动作前校验。 pid、window_id标识实际目标；应用名与 PID 筛选不能悄悄扩大范围。发现空结果和驱动错误分别处理，未知 PID 不使用 0。- 控件使用最新
snapshot_id派生的 token；像素动作使用最新capture_id及同图坐标。窗口移动、缩放、尺寸或编号失效时重新观察，坐标映射不能重复缩放。 - 浏览器前台输入先激活并核对准确 HWND，随后保持目标前台；只读观察不抢焦点。激活未确认不发送输入，前台操作会占用用户桌面，不承诺无干扰后台执行。
- 每次调用只执行一次动作。明确未执行、部分执行、结果不明和已验证分别返回；结果未知的写操作不自动重发，投递成功不等于业务成功。
- 操作后返回真实观察与来源；截图保存到任务 trace，拒绝覆盖和路径逃逸，附件有真实文件与 SHA256。灰屏或只有浏览器外壳不能当作有效业务观察。
- 会话关闭、取消和宿主退出要回收适配器、Driver/UIA 子进程；原有 Windows Job Object 生命周期保持有效。
Packaging and Release
- 固定上游版本、提交与 ZIP SHA256，保留许可证和包内来源记录；仅分发所需运行依赖，不执行全局安装器，不包含云环境或模型服务。
- 包版本、MCP 握手版本、构建来源信息、发行标签和市场索引一致。只改适配层时按既有 +artemis.N 修订后缀约定发布新的不可变包，不覆盖旧版本附件。
- 发布包、校验值、发行说明和实际验证结果齐全后再更新市场。主程序升级不自动升级或授权用户插件；任务结束后由用户操作更新。
- 文档变更检查链接、命令与实际源码；代码变更运行相应 Go 回归和静态检查，必要时完成隔离窗口实测。契约检查、窗口烟测和完整业务验收分别报告。
- Windows x64 预览及未测范围如实保留。候选阶段小样本、约 26.1% token 差异或 PNG 保存成功不能外推为稳定成功率、费用或跨端验证通过。
- 只暂存本次具体路径；不提交
artifacts/、可执行文件、上游下载包、执行记录、凭据或个人目录。推送后读取远端分支并核对发布提交。