用途
cua-driver 用于驱动原生 GUI 应用，支持 macOS、Windows 和 Linux。当用户要求你操作、驱动、自动化或在一个真实的主机应用中执行 GUI 任务，或要求继续、恢复、回忆最近的 Cua 活动时，使用本技能。
它会编排跨平台的应用自动化。只要用户要求驱动原生应用，就应遵循本技能规定的循环，而不是临时调用工具——“先快照后操作”的不变式不是可选项，跳过它会静默失效。
主要能力
- 通过辅助功能树（AX/UIA/AT-SPI）快照定位界面元素。
- 通过快照绑定的元素令牌、原生菜单路径、精确窗口几何信息或像素坐标执行操作。
- 从新状态进行结果验证。
- 提供 CLI 与 MCP 服务器两种使用方式。
- 平台专属能力记录在同目录的伴生文件中：macOS 见
MACOS.md，Windows 见WINDOWS.md，Linux 见LINUX.md；浏览器与录制分别见BROWSER.md、RECORDING.md。 - 提供代理光标叠加层（agent cursor overlay），用于演示和屏幕录制，包含 idle、observe、click、drag、scroll、text、key、navigation、app、transfer、recording、system 等动画。
- 提供历史活动查询工具：
history_status与history_query。
使用方式
默认传输方式是 cua-driver CLI 用于一次性调用：Bash shell 调用 cua-driver <tool-name> '<JSON-args>'。每次 CLI 调用拥有一个一次性传输会话，在响应后清理。对于需要共享光标、录制、浏览器或命名会话状态的多调用 GUI 工作流，使用一个持久的 cua-driver mcp 连接。
工具名为 snake_case，管理子命令为 kebab-case。管理子命令包括：
cua-driver serve— 启动显式持久服务。cua-driver stop/statuscua-driver list-tools、describe <tool>cua-driver recording start|stop|statuscua-driver check-update [--json] [--no-cache]— 只读检查是否有新版本。
如需 Claude Code 的视觉/计算机使用风格流程，可注册：
cua-driver mcp-config --client claude # then paste + run the printed line
持久 MCP 连接内的典型多步工作流示例：
launch_app({"bundle_id":"..."})
# → {pid: 844, windows: [{window_id: 10725, ...}]}
get_window_state({"pid":844,"window_id":10725})
# Use the returned structuredContent.elements[].element_token:
click({"pid":844,"element_token":"s0000002a:14"})
verify_state({"pid":844,"window_id":10725,"expect":[{"element":{"selector":{"label_contains":"Saved"},"exists":true}}]})
对于 Chromium 页面内容，保持相同的原生窗口选择，但切换到浏览器能力循环：使用一个生命周期会话，用 get_browser_state 绑定 (pid, window_id)，对返回的标签页做快照，然后使用 browser_click、browser_type 或 browser_navigate。浏览器目标 id、标签页 id 和 ref 均为会话作用域，过期 ref 必须用新的快照替换。
语义路由优先级
在打开或操作应用之前，先明确期望的后置条件，并使用以下第一个适用的路径，在同一域中验证结果后再停止或前进：
- 调用方提供的无头/后台操作，用于非 GUI 结果。优先使用精确的应用 API/SDK、服务或数据库客户端、CLI 或文件系统操作，而不是模仿用户。
- 针对应用或窗口结果的类型化 Cua 操作。使用
set_window_frame设置精确几何，使用invoke_menu导航已知原生应用菜单路径，使用类型化浏览器工具处理支持的页面内容，使用剪贴板工具处理剪贴板状态。 - 后台辅助功能操作。使用新的 AX/UIA/AT-SPI 目标。
- 后台像素操作。使用同一状态快照的像素。
- 前台交付。仅重试证据表明无法在后台落地的操作。
- 桌面回退。仅对该次调用选择精确的桌面目标。
无前台原则（窗口阶段）
在面向窗口的后台操作期间，用户最前台的应用不得改变。每个平台都有自己的禁止命令列表：
- macOS：任何
open调用、任何修改 GUI 状态的osascript、cliclick、针对其他应用窗口的cghidEventTap写入。完整列表见MACOS.md。 - Windows：任何会触发对目标
ShowWindow/SetForegroundWindow的Start-Process、WScript.Shell.AppActivate、为输入转发而附加到前台线程。完整列表见WINDOWS.md。
delivery_mode:"foreground" 是用户可见的接管边界，不是自动重试。仅当用户已授权该工作流的前台控制，或在请求批准后使用。
代理光标叠加层
视觉光标叠加层用于演示和屏幕录制。它在第一个携带光标的动作（包括 move_cursor）时初始化，并跟随传输的隐式或命名生命周期会话。使用 set_agent_cursor_enabled 切换命名光标的显示与隐藏。内置 cua.default 主题在会话颜色的指针上叠加同会话颜色的更大光标形状光晕。
当代理正在控制指针或键盘输入时，保持该叠加层启用。携带光标和键盘的动作会自动重新显示其会话光标，即使它空闲时被隐藏。在 Linux 上，普通的 move_cursor({x,y}) 只移动这个合成光标；move_cursor({x,y,scope:"desktop"}) 是移动用户合成器光标的显式逃生通道，除非用户要求桌面指针控制，否则不得使用。
每个 MCP 会话自动拥有自己的光标，以会话 id 为键。每个命名会话从内置调色板获得稳定的填充色。仅使用 set_agent_cursor_theme 选择预装主题；主题源路径和内联动画数据从不通过代理工具接受。使用受信任的本地 cua-driver cursor-theme 工作流来验证、编译、预览、安装、列出或移除自定义主题。
AX 运行的可见性说明
在纯辅助功能操作运行（通过 element_index 点击）中，第一个动作会在屏幕上目标的附近短距离处播种光标，并播放短暂的滑行 + 脉冲，而不是光标已在屏幕上时从上一位置描出的长贝塞尔扫过。这很微妙，在录制中容易被忽略。如果要为演示或屏幕录制获得清晰的滑行光标，先做像素点击（click({pid,x,y})）或 move_cursor 把光标放到屏幕上；后续 AX 动作随后会正常滑行完整路径。
像素 click 已经会滑行叠加层。不要在同一目标上紧接 click 之前调用 move_cursor，那会播放两次滑行。
历史活动查询
仅当同时提供 history_status 和 history_query，且用户要求继续、恢复或回忆先前的 Cua 工作时，才先调用 history_status。如果历史健康且访问被允许，在广泛的应用或窗口发现之前，先做一次有界的初始 history_query。将返回的元数据仅视为线索，并通过最不具侵入性的适当来源验证当前状态。
当任一工具缺失、访问被拒绝、查询为空或历史不健康时，不使用历史继续。不要仅仅因为工具被提供就为无关任务查询历史，并且永远不要修改历史生命周期或设置。
适用场景与限制
适用场景：结果位于应用的 UI 或窗口状态中，或用户明确要求操作该 GUI。一旦任务跨越该边界，就不要用会改动应用 UI 的 shell 脚本替代 Cua 的目标化、经验证的操作。
限制：shell 是调用代理的能力，不是 Cua Driver MCP 服务器的能力；仅 MCP 客户端不得假定存在 shell。文件系统结果和剪贴板结果应尽量走语义路径，GUI 回退需保持窄范围并逐步验证。当背景交付不可用且前台控制未获授权时，应以驱动的拒绝停止，而不是静默升级。
关于具体平台的启动语义、点击分发、禁止调用等细节，需阅读对应平台的伴生文件；有疑问时运行 cua-driver doctor，它会报告平台和正确的入口点。