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。若操作打开原生菜单、托盘或把焦点切到任务栏，检查 observation_target.observed 和 artemis.source.target_id，后续使用实际观察目标的 PID/HWND 与新 token；旧窗口编号不代表当前焦点。keyboard_focus 与 post_action_focus 记录真实焦点。归属不明或取证失败时先只读核对，不重复业务动作。原生菜单可向其拥有者窗口发送 Escape 关闭。仅在画面变化或需要核验时再次观察。
5. 默认后台操作；明确指定 foreground 时，适配器先使用 Cua 自带 bring_to_front 激活并核实目标，随后保持目标在前台，供页面渲染和连续观察；不会每次动作后切回原应用，也不能承诺不影响用户前台工作。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。检查新页面再继续。只读观察/保存截图不会抢焦点；若正文灰屏或控件树缺少网页正文，检查 capture_focus，调用同一 pid/window_id 的 bring_to_front，再观察页面；不要靠重复刷新或业务点击恢复。用户切换窗口后需要重新确认前台，不能拿灰屏判网站失败。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.38.0，另含有明确来源记录的无标题 Shell 窗口兼容补丁，构建方式见 BUILD.md，实测范围见 VERIFICATION.md。

截图坐标与证据

• click_at、scroll、drag 都携带最新返回截图的 capture_id，坐标取自同一张图的实际宽高。动作返回的新截图可能改变分辨率；旧编号、旧坐标不可沿用。窗口移动、缩放或坐标越界被拒绝后重新观察，不反复重试原参数。
• 缩放转换由 Cua Driver 处理，适配器校验截图绑定与范围，不自行乘 DPI 或加窗口偏移。优先用最新 element_token 点击可访问控件；UIA 的屏幕 frame 不能作为截图坐标。
• 操作及保存截图前，从已有观察核对应用、窗口标题和页面身份（浏览器结合地址栏、选中标签及页面内容）。身份不符时定位正确页面再操作。无位移的滚动不能证明到底；先检查遮挡、焦点和滚动容器，再决定补一次边界验证或换路径。