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 适合直接设置输入框；不支持时可明确聚焦后 type_text。观察控件支持的动作，不猜元素编号。press_key 传单键及 modifiers 数组。
4. 每个动作后插件自动返回一次新截图和控件树，新 snapshot 替换旧 token。接着用新 token，无需重复获取相同状态。仅当画面确实还在变化或需要核验时再次观察。一次调用只执行一次动作，超时不自动重发。
5. 默认后台操作。effect=unverifiable/suspected_noop 仅代表投递/效果未确认，必须检查返回画面和读回值；refused 是未执行。后台无效时，可在任务授权范围内显式 delivery_mode=foreground 后再次检查。不要仅凭工具成功声称测试通过。
6. scroll 需要最新窗口/滚动区域，使用 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 为准。