computer

用途

这是一个桌面控制技能，用于操作用户真实电脑上的原生应用、操作系统界面和 Superset 之外的浏览器窗口。它并不直接绑定某一个具体驱动，而是定义了一套由驱动无关的操作契约：预检查、按任务创建会话、快照、执行、验证、优先语义化操作、保守处理失败、清理会话。

适用与不适用

• 适用：打开或驱动原生应用、在桌面应用内点击或输入、操作系统 UI、控制 Superset 之外的浏览器窗口。
• 不适用或应优先替代：Superset 内置浏览器面板应使用 superset:browser；若任务无需 GUI 交互，应优先使用应用 API、专用 CLI 或直接文件系统操作。

驱动选择

• 用户指定驱动时，使用用户指定的驱动。
• 未指定时，使用已安装的受支持驱动：Cua Driver（cua-driver，跨平台，默认）或 Peekaboo（peekaboo，仅 macOS）。两者都已安装时，使用 Cua Driver，并提一次替代方案。
• 两者都未安装时，先询问用户安装哪一个再安装；除非用户仅使用 macOS 且偏好 Peekaboo，否则推荐 Cua Driver。
• 使用非 Cua Driver 时，通过该驱动自己的帮助输出与文档发现命令界面，而不是假定使用下文 Cua 命令形态。

安装与检查 Cua Driver

确认可执行文件：macOS/Linux 用 command -v cua-driver，Windows PowerShell 用 Get-Command cua-driver，然后检查 cua-driver --version。不要静默安装或升级。缺失时，请用户授权从安装指南运行安装器。

macOS/Linux：

/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

Windows PowerShell：

irm https://cua.ai/driver/install.ps1 | iex
cua-driver autostart enable
cua-driver autostart kick

运行 cua-driver doctor 与 cua-driver status。macOS 上还需运行 cua-driver permissions status；如果缺少辅助功能或屏幕录制权限，请用户运行 cua-driver permissions grant 并完成系统提示。不要用 AppleScript、合成 shell 输入或其他 GUI 驱动绕过缺失的系统权限。保留已运行守护进程的权限模式，不要仅为扩大权限而重启它。若环境需要显式服务设置，按 doctor 报告的平台指引处理。

用 cua-driver list-tools、cua-driver describe get_window_state、cua-driver describe click 查看已安装工具面，不要假定版本特定 schema。工具调用形式为 cua-driver call <tool> '<json>'，参数不确定时使用 describe。

任务会话

第一次 GUI 观察前创建唯一会话：

cua-driver call start_session '{"session":"superset-computer-<unique>"}'

将同一会话传给所有接受该参数的工具。它管理本次运行的智能体光标与生命周期清理，但不选择捕获模式，也不会授予超出守护进程固定权限模式的访问权。

快照、执行、验证循环

每次 GUI 动作遵循以下循环：

1. 明确后置条件，例如“设置中显示已选择深色模式”。
2. 用 get_accessibility_tree 或其他语义工具发现目标，然后针对确切 PID 和窗口获取新鲜 get_window_state 快照。
3. 优先使用快照中的 element_token，其次 element_index，再次像素坐标。令牌标识控件，并在快照过期时失败关闭。
4. 执行一个动作。默认后台投递；仅在新鲜证据表明后台动作未落地时才用前台投递。
5. 重新快照并验证后置条件，再继续。成功的工具响应只证明投递，不证明结果 UI 状态。

最小形态示例：

cua-driver call get_accessibility_tree '{}'
cua-driver call get_window_state '{"pid":844,"window_id":10725,"session":"superset-computer-<unique>"}'
cua-driver call click '{"pid":844,"element_token":"s0000002a:14","session":"superset-computer-<unique>"}'
cua-driver call verify_state '{"pid":844,"window_id":10725,"session":"superset-computer-<unique>","expect":[{"element":{"selector":{"label_contains":"Saved"},"exists":true}}]}'

每次后续动作前重新快照。同一窗口快照、导航、模态切换或大幅重绘之后，绝不复用令牌。

优先语义化操作

• 原生应用菜单路径使用 invoke_menu。
• 可访问字段使用 set_value 或 type_text；非文本按键使用 press_key 或 hotkey。
• 窗口几何使用 set_window_frame，并用 list_windows 验证。
• Chromium 或 Electron 页面内容：先发现确切浏览器 PID 与窗口 ID，再调用 get_browser_state。若返回 browser_requires_setup，按批准规则调用 browser_prepare；准备后用返回的 PID 重新发现窗口并再次调用 get_browser_state。用返回的 target_id 与 tab_id 配合 browser_click、browser_type、browser_navigate、browser_pointer，每次后续浏览器动作前刷新页面快照。
• 浏览器像素动作：browser_click 与 browser_pointer 坐标必须来自最新 get_browser_state 页面快照的视口 CSS 像素。原生像素动作只用于无障碍树中缺失的 canvas、视频、WebGL 或自绘控件，坐标取自本次动作所用的同一份新鲜 get_window_state 快照。

保守处理失败

• 控件缺失时，刷新快照并检查对话框、工作表和应用菜单，再升级处理。
• 动作无验证效果时，只重试最窄的失败步骤：先后台无障碍，再后台像素输入，再前台输入。
• 仅在语义、无障碍、像素、前台窗口路径都耗尽后，才升级到全桌面控制，且只能通过已安装驱动版本所公布机制。
• 目标或结果状态不明确时停止并报告可见内容。不要点击未知对话框或重试破坏性动作。
• 除非请求本身要求，保持用户窗口、焦点、标签页和剪贴板原样。

清理

最后做一次新鲜快照或语义回读，报告可观察结果，然后只结束本任务创建的会话：

cua-driver call end_session '{"session":"superset-computer-<unique>"}'

任务结束时不要停止共享驱动守护进程，也不要关闭无关窗口。

截图证据与发布

当截图本身就是目的，或需要他人阅读验证运行时，应发布截图而非在磁盘留下路径列表。将截图收集到目录中，旁边放一个 index.html 排版展示，发布该目录，使图片按相对路径随附：

superset pages publish ./evidence/ --workspace <id> --title "Export dialog: verified"

桌面截图会拍到屏幕上其他内容，如邮件、消息、密码管理器、其他客户数据。逐张检查，删除或裁剪报告不需要的部分，除非组织需要，否则传 --visibility just_me。发布属于下方安全规则要求先确认的动作之一。

安全

该技能触及真实应用与已登录会话。检查与动作限于用户请求；绝不提取凭据、cookie、令牌或无关私密数据。在发送消息、提交产生外部承诺的表单、发布、购买、删除数据、更改账户、接受法律条款或其他重大外部动作前，立即获取确认。认证提示、通行密钥、密码和 MFA 始终由用户处理。