53 lines
5.1 KiB
Markdown
53 lines
5.1 KiB
Markdown
# Artemis Plugins 协作指南
|
||
|
||
## Scope
|
||
|
||
- 本文件适用于本仓库，当前用户指令优先。主程序 `artemis` 是独立仓库，两者分别提交、验证和推送。
|
||
- 本仓库负责插件适配、工具契约、构建和市场索引；主程序负责模型、调度、资源锁、录屏、证据、任务与最终验收。
|
||
- 修改适配器、工具、包或市场前，读 [DESIGN.md](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](README.md) |
|
||
| Windows 实测 | 仓库根目录 | 按对应验证记录运行 `tests/cua_smoke.py`、`tests/cua_fixture_validation.py`；使用已有 ARTEMIS 依赖和正确的 `PYTHONPATH` |
|
||
| 提交前 | 仓库根目录 | `git diff --check`、`git diff --cached --check`，核对精确暂存路径 |
|
||
|
||
浏览器及前台实测先读 [Cua 验证记录](plugins/cua-driver/VERIFICATION.md)，确认脚本会操作的测试窗口、应用及桌面资源。执行涉及用户应用的交互任务时，沿用主程序的 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/`、可执行文件、上游下载包、执行记录、凭据或个人目录。推送后读取远端分支并核对发布提交。
|
||
|
||
## References
|
||
|
||
- [适配与市场设计](DESIGN.md)
|
||
- [安装与构建](README.md)
|
||
- [Cua 调用规则](plugins/cua-driver/SKILL.md)
|
||
- [Cua 发行说明](plugins/cua-driver/RELEASE.md)
|
||
- [Cua 实测范围](plugins/cua-driver/VERIFICATION.md)
|