Artemis-Plugins/plugins/cua-driver/SKILL.md

Cua 电脑控制（Windows）

通过本地 Cua Driver 操作用户授权的 Windows 窗口。调度、资源互斥、模型、步骤、截图和录像由 ARTEMIS 提供；插件本身不运行 AI，不另起后台服务。

1. 先按应用名发现窗口，例如 list_windows({"app":"Brave","on_screen_only":true})；未知 pid 必须省略或填 null，不能填 0。app 与非空 pid 同时提供时会取交集，只有该应用实际返回的 PID 才能用于后续调用。空结果时先按 lookup.suggested_arguments 纠正筛选（去掉错误 PID 或检查最小化窗口），不能直接宣称浏览器不可用，也不能把无关前台进程号当成目标 PID。取得目标的 pid、window_id 后读取真实画面；只操作任务要求的窗口，不关闭其他应用。
2. get_window_state 同时读取截图和 UIA 控件树。最新 snapshot_id 加 :N 即控件 element_token。优先用 click 点击最新控件；视觉目标用 click_at，坐标仅取本次截图上的窗口局部像素，不能用屏幕坐标，需携带本次 capture_id。两种点击参数互斥，不混用。
3. 所有窗口操作明确传 pid、window_id。set_value 必须带最新 element_token，用于设置具有 set_value 动作的输入框；同名 Text 标签不能当成 Edit 输入框。press_key 和 type_text 只操作当前焦点，不能传 element_token、x、y（也不要补 0/null）。需要聚焦控件时先 click / click_at，再输入。press_key 传单键及 modifiers 数组。
4. 每个动作后插件自动返回一次新截图和控件树，新 snapshot 替换旧 token。接着用新 token，无需重复获取相同状态。仅当画面确实还在变化或需要核验时再次观察。一次调用只执行一次动作，超时不自动重发。
5. 默认后台操作；Brave/Chrome/Edge 等 Chromium 浏览器的点击（尤其滚动后）、快捷键、文字输入和滚动直接使用 delivery_mode=foreground。例如新标签页：press_key(key="t",modifiers=["ctrl"],delivery_mode="foreground")；地址导航：Ctrl+L → type_text(text=网址,delivery_mode="foreground") → Enter，各调用均带同一目标 pid/window_id。检查新页面再继续。effect=unverifiable/suspected_noop 仅代表投递/效果未确认，必须检查返回画面和读回值；refused 是未执行。其他应用后台无效时，可在任务授权范围内显式 foreground 后再次检查。不要仅凭工具成功声称测试通过。
6. scroll 必须带最新截图中滚动区域内的 x,y，不能传 element_token。使用 up/down/left/right、amount、by=line/page；滚轮刻度不保证固定像素或整页距离，根据返回画面确认实际位移再继续。get_window_state(since="latest") 可在同一窗口读取差异，但新 snapshot_id 仍替换旧 token。
7. save_screenshot 保存最新窗口 PNG 到当前任务 trace，filename 仅是文件名，不能传路径，不覆盖已有文件。实际成功返回 SHA256 和附件；不得把工具内存截图当成已保存文件。

不提供 Cua 自带调度、录屏、回放、配置修改、安装器、任意脚本或自动升级接口。浏览器本轮使用窗口视觉/UIA 通路；未接入 DOM 或已有登录浏览器调试权限。此包基于上游 0.36.0 预发布版，通过已列出的本机验证，其他场景的支持范围以 VERIFICATION.md 为准。