cua-driver 浏览器工具实现实录：精确绑定、结构化拒绝与跨平台验证体系

cua-driver 浏览器工具实现实录：精确绑定、结构化拒绝与跨平台验证体系

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

导读

本文是 cua-driver 仓库内第一等公民浏览器工具（browser tools）的完整实现与验证记录，核心回答一个难题：如何让计算机使用（computer-use）智能体在真实浏览器上执行点击、输入、导航等变更操作，却绝不"猜"目标——要么给出可证明的精确绑定（exact binding），要么以机器可读的结构化拒绝（structured refusal）收场。读完本文，你将掌握 cua-driver 的 native 窗口↔CDP target 相关性模型、16 个稳定拒绝码的语义、会话作用域设计、跨 macOS/Windows/Linux X11/Wayland 的验证矩阵，以及browser_prepare的隔离启动与现有 profile 附加两种安全路径的完整边界。

背景：为什么浏览器自动化需要"精确或拒绝"

通用 GUI 自动化工具常见的做法是"按坐标点击"或"按标题猜窗口"，这在脚本演示场景够用，但在面向 Agent 的一等公民 API 中会埋下隐患：窗口标题重复、浏览器窗口边界重叠、标签页与原生窗口并非一一对应，任何一次"猜中"都可能导致输入落到错误的页面。cua-driver 为此定下的验收标准（definition of done）非常明确（见 browser-tool-implementation-journal.md）：

• 提供能力感知的浏览器 API，其类型化工具共享同一套精确的 target、tab、frame 与 ref 模型；
• 保持get_browser_state严格只读，所有 setup 都必须是显式调用；
• 将原生(pid, window_id)目标与浏览器标签页精确绑定，否则拒绝一切变更操作；绝不允许把启发式匹配升级为动作路由；
• 浏览器 target、标签页、页面引用全部限定在具名 driver 会话内；
• 用单元/协议测试、源码构建的 Web harness、本机 macOS、交互式 Windows 桌面、以及代表性 X11 与 Wayland 环境完成验证；
• 在新型浏览器路由积累足够发布证据之前，保持旧page工具的兼容性。

这套"exact-or-refused"契约是整个浏览器工具面的基石，也是后文所有设计与证据围绕的核心。

架构分层：共享引擎 + 平台适配器

实现沿用了既有的PageBackend反转结构（inversion），被明确拆分到两层（见 browser-tool-implementation-journal.md 的 2026-07-14 条目）：

• cua-driver-core负责共享部分：类型化工具 schema、CDP 传输、浏览器 target 存储、结构化拒绝词表、会话清理、快照作用域 ref、变更操作串行化；
• 各平台 crate 负责操作系统身份部分：进程指纹（process fingerprint）、原生窗口元数据、浏览器产品分类、loopback 端点所有权证明、显式端点 setup。

平台适配器的边界契约定义在 platform.rs 中：core 拥有 schema、语义、CDP 处理、target/ref 存储、生命周期清理与相关性计算；平台 crate 实现BrowserPlatformtrait，提供进程指纹、原生窗口信息、浏览器分类、loopback 端点所有权与显式 setup——"core 从不伸手进入平台 crate"。

各平台已有的原生证据决定了相关性的可行程度：

• macOS：可拿到精确的 CGWindow owner、标题与边界；
• Windows：精确的 HWND owner 加 DWM 边界；
• Linux X11：几何信息加客户端声明的_NET_WM_PID，但必须与端点所有权独立印证后才能视为精确；
• Sway：合成器直接提供 pid 与矩形；
• 通用 GNOME/KDE Wayland：不存在通用的"pid+几何"精确相关性，只能报告只读能力并拒绝变更。

精确绑定模型：从不猜测，从不静默降级

相关性算法

get_browser_state的唯一入口是pid + window_id。CDP 侧，每个页面 target（标签页）可通过Browser.getWindowForTarget+Browser.getWindowBounds映射到 CDP window 及其几何信息。相关性算法（见 binding.rs）分五步：

1. 将页面 target 按"可证明的 CDP window"折叠为每个窗口一个代表（reprepresentative），标签页本身不构成独立原生窗口候选；
2. 过滤出 CDP 窗口边界与原生边界在容差（device pixels）内匹配的候选；
3. 恰好一个边界匹配 →Exact绑定；
4. 多个不同 CDP 窗口共享最大化边界时（常见于最大化窗口），唯一的活动标签页标题匹配可消解歧义；重复或缺失标题仍保持歧义；
5. 无边界匹配时，唯一标题匹配降级为Heuristic（只读），否则None。

标题匹配采用"包含"语义而非相等：浏览器原生窗口标题通常是"<tab title> - <product>"形态，空标签页标题永不参与匹配。BindingOutcome只携带候选计数而非原始 CDP target id，保证原生 CDP target id 不泄漏到 core 之外。

嵌入式浏览器的有界回退

真实场景中，Electron 39 对 CDPBrowser.getWindowForTarget返回方法错误-32601。实现没有靠猜测兜底，而是增加了一个有界的embedded_single_page路由：仅当端点只暴露一个页面、且请求进程只拥有一个原生窗口时，该回退才算精确；这两个事实在每次变更前都会重新核查，一旦出现第二个页面或第二个原生窗口，立即产生结构化拒绝。标准 Chromium 则走更强的native_cdp_window路由（基于浏览器 window id 与 native/CDP 几何一致性）。从源码看，这一逻辑落在embedded_single_page_candidate与cardinality_exact_candidate两个纯函数中：前者要求单页面 + 单原生窗口 + 无 CDP window id；后者在平台独立证明"端点 owner 只有一个原生窗口"时，允许平铺合成器（tiling compositor）覆盖 Chromium 请求边界的情形下保持一对一精确映射。

独立评审加固的两处信任链修复

2026-07-15 的一次独立只读评审发现两个信任链阻塞，并全部修复：

• WebSocket 端口可漂移：一个被验证的 HTTP 监听器可能返回另一个 loopback 端口上的 WebSocket URL。现在每个平台适配器都要求返回的 WebSocket URL 使用操作系统认证过的确切监听端口，回归测试同时固定了 loopback-only 解析和基于 token 的浏览器产品分类。
• 同边界窗口可被标题错误消歧：两个最大化且边界相同的浏览器窗口可能在不同 CDP window id 之间被标题 tie-break 误判。现在边界 tie-break 只在同一个已证明的 CDP window id 内部合法；不同 window id 的同边界窗口保持歧义；没有 CDP window id 的几何信息不能铸造精确绑定；瞬态或畸形 CDP 窗口枚举响应会令整个证明失败，而不是把候选集缩小成"假唯一匹配"。

结构化拒绝词表：可分支的机器语义

exact-or-refused 契约的另一个关键设计是：大多数失败路径不是协议错误，而是故意的、机器可读的拒绝。拒绝会序列化为structuredContent中的{"status":"refused","refusal":{code,...}}，并带一个稳定的 snake_case 代码，Agent 可以据此分支处理。拒绝不是 MCP 协议错误：调用本身执行正确，其结果是拒绝，所以isError不置位。完整实现见 refusal.rs，其闭合词表如下（词表只允许增补，重命名或删除对按码分支的消费者都是破坏性变更）：

拒绝码同时携带人类可读 message 与可选机器 detail（如提示"run browser_prepare"）。源码单元测试同时断言 serde 序列化与as_str完全一致，且is_error保持未置位，确保文本客户端也能从纯文本行读到拒绝码。

会话作用域与工具面

会话即命名空间

浏览器 target、tab、快照与 ref 都是会话作用域能力。require_explicit_session强制要求调用方通过start_session声明显式会话并传递其 id——"default"或空会话直接报错，因为能力命名空间必须有一个真实 owner，其 end 事件负责清理。ref 采用p<snapshot>:<index>命名空间，会被导航和同一标签页的新快照失效。公开的session参数是权威的，同时保留 daemon 的隐藏会话镜像以兼容 MCP 传输。

从 5 个 v1 工具到 9 个工具的完整表面

v1 在 core 中登记了五个类型化工具，并在所有平台注册相同 schema。随着实现演进，当前浏览器工具面（见 tools.rs 的register_browser_tools）已扩展为九个：

1. get_browser_state——严格只读：绑定、快照、读状态，绝不执行 setup 或变更；
2. browser_prepare——显式准备：识别已属主端点，或返回明确的 setup/同意限制；不会静默重启或修改 profile；
3. browser_navigate——导航；
4. browser_click——可信或显式合成（synthetic）点击；
5. browser_type——ref 绑定的可编辑输入，要求当前 ref 且先证明焦点节点可编辑，否则拒绝而非在未证明页面焦点下谎报成功；
6. browser_dialog——页面属主 JavaScript 对话框检查与解决；
7. browser_set_input_files——精确的文件输入赋值；
8. browser_download——批准作用域内的下载；
9. browser_pointer——扩展指针动作（hover/右键/双击/滚动/拖拽）。

所有变更工具在分发前都会做变更时重校验（mutation-time revalidation）：进程指纹与原生窗口所有权检查确保浏览器重启、pid 复用、窗口关闭、标签移动或端点变更都会 fail-closed。合成指针动作是显式的dom_event请求；可信指针动作在被拒绝后绝不静默回退。browser_type会报告精确的"请求字符数 vs 已交付字符数"，部分前缀交付返回browser_input_incomplete。下载操作串行化 Chromium 浏览器级设置、先订阅后触发、关联精确 frame 与不透明 id 事件、在每种结局都恢复默认设置，失败时仅删除可证明的直接部分文件。

跨平台验证矩阵

规范 harness 行

实现没有另起炉灶建测试框架，而是把<platform>-electron-browser-tool-roundtrip加入既有的共享 Web 行为矩阵。该行执行的完整流程是：启动具名会话 → 绑定精确的原生 Electron 窗口 → 证明browser_prepare识别已属主端点 → 断言有界embedded_single_page路由 → 页面快照 → 可信 ref 点击 → 校验外部 fixture 日志 → 再次快照 → 通过新可编辑 ref 输入 → 证明旧 ref 返回browser_ref_stale且状态未变 → 导航到about:blank验证新 URL → 证明导航使最新 ref 失效。必需证据包括：fixture 状态、前台焦点、z-order、无泄漏输入、可观测处的光标保持，以及可播放视频。

各平台基线结果（日志记录的最终修订版本）：

• 共享与 macOS：cargo test -p cua-driver-core -p platform-macos通过 170 个 core 测试、3 个会话生命周期测试、126 个 macOS 平台测试；协议套件 1 schema + 1 consistency + 6 session 测试通过。初始权限版 macOS 因 WindowServer 报告 Electron 的若干无标题 layer-0 辅助表面而 fail-closed，修订0cf2dd9e将 macOS 回退基数检查收窄到"有标题、非空"的浏览器表面，随后规范 Electron 行 1 交付 / 0 拒绝 / 0 失败 / 0 跳过。
• Windows 交互式桌面：三个聚焦的解析/分类/端点认证测试通过；规范 Electron 行同样 1/0/0/0，全部证据在真实交互式用户桌面通过。
• Linux X11/Openbox：三个聚焦测试加全部 53 个 Linux testkit 测试通过；规范 Electron 行 1/0/0/0。
• Linux 原生 Wayland（Sway）：六个聚焦 sentinel 回归测试通过；原生 preflight 通过"刻意失焦 + 全屏恢复"canary；在禁用 Xwayland 的原生 Ozone Wayland 上规范 Electron 行 1/0/0/0。全局光标保持被省略，因为标准 Wayland 无法读取全局指针位置。

独立 Chromium 覆盖与对抗性测试

v2 增加了仓库属主的独立 Chromium harness：26c177d9统一了各平台的引擎分类与路由限制（不支持的引擎可被发现但绝不宣传变更能力）；0295b881加入独立 Chromium 覆盖；3287b44e加入对抗性多标签与同边界多窗口用例——面对歧义时 driver 拒绝，而不是选第一个页面或用跨 CDP window id 的标题 tie-break。macOS 独立套件一次性通过：精确 roundtrip、隔离准备、stale refs、组合 frame、多标签、同边界多窗口拒绝。

组合文档与事件感知 CDP

c8fb38ef让 ref 可以穿透开放 shadow root 与同进程 iframe；跨进程 iframe（OOPIF）仅在运行时暴露可证明的 CDP session 时才附加，事件消息从命令响应中解复用。快照 ref 保留 frame 身份，缺失的 frame 路由报告为限制，绝不扁平化进主文档。独立组合文档行在真实 Chromium 上通过，覆盖 shadow DOM、同进程 iframe 与能力测试的 OOPIF 行为。

harness 进程隔离与确定性

a6e4c6b8让每个 Unix 测试属主浏览器处于独立进程组并在每行结束后收割整棵树，杜绝晚到的 Chrome 子进程污染下一个精确绑定测试；产品动作绝不重试，更长的就绪预算和 macOS 启动沉降只发生在独立属主的 harness 进程之间。4fc4e00b修复了一个关键 Unix 收割 bug：向外部kill工具传-1曾被解析为宽泛的kill(-1, SIGKILL)系统调用，可能终止测试用户可信号的所有进程；现在改为受保护的libc::kill(-pgid, SIGKILL)直接调用，并拒绝进程 id 0、1 或越界值。

browser_prepare：两种安全的准备路径

驱动属主隔离启动

browser_prepare的隔离路径（见 prepare.rs 与 platform.rs 的PrepareRequest/PrepareProfile）被明确标记为破坏性且非幂等：

• 通过browser-approve交互命令铸造五分钟、单次使用、绑定 pid+profile 请求的 token；
• 启动独立 Chromium 进程，使用驱动属主的isolated_new或isolated_namedprofile（profile.name限 1-64 个 ASCII 字母/数字/-/_；isolated_new不接受 name）；绝不复制、修改、重启或终止所选用户 profile；
• 端点通过私有 profile 的DevToolsActivePort与 socket 所有权证明；临时 profile 与进程在所属会话结束时被收割；
• 所有平台上launch_app透传的 remote-debugging 参数都会被拒绝，防止 setup 绕过边界。

现有 profile 附加（existing-profile attachment）

对于用户已运行的浏览器，实现了受评审的附加策略，但不改变驱动属主隔离 profile 契约：

• 仅当请求同时携带精确 pid、原生窗口、具名会话和browser-approveCLI 铸造的五分钟单次使用工件时才接受strategy:{kind:"existing_profile"}；普通 MCP host 标记无权授权此路由；
• 授权只存在于 daemon 内存中，作用域覆盖公开/传输会话、进程指纹、原生窗口、浏览器产品、端点与连接代数（generation）；空闲/绝对过期、同意撤销、身份变更、重连耗尽、会话结束与 daemon 重启都会吊销授权并释放其声明的 socket；
• 每个代数只属主一个浏览器级 CDP 连接；重连按浏览器单飞（single-flight）、三次尝试、单一有界截止时间，重新证明端点/进程身份，并使所有旧 target、tab、快照、frame 与 ref 失效；
• 变更按"进程指纹 + 真实 CDP target"串行化，两个会话不能在同一标签页交错动作，独立标签页保持并行；
• 带同意的录制仅持久化脱敏元数据与结果，浏览器截图、AX 快照、批准 token、端点地址端口、profile 数据与已认证页面内容一律抑制。

macOS 的 Chrome 适配器发现唯一 PID 属主的 loopback 监听器，使用有界原生 AX 适配器，只作用于一个浏览器属主的 modal sheet（有 remote-debugging 佐证）与一个宣传 AXPress 的语义 Allow 按钮；物理主机验证中发现 Chrome 通过 AXChildren 与 AXWindows 以不同代理指针暴露同一顶层窗口，因此顶层去重改用 Core Foundation 对象相等，防止单个 sheet 变成假歧义匹配。

跨平台现有 profile setup 对等

到 2026-07-16，现有 profile 路由在四个桌面环境都有产品专属 setup 描述符（Chrome/Chromium/Edge）与原生精确控制适配器：

• macOS：精确 AX 页面、复选框、标签清理与浏览器属主同意语义，一次性 Lume guest 通过 Chrome 与 Edge setup 并带视频；
• Windows：精确 HWND 所有权加 UIA 页面/复选框/清理/同意语义，在 Azure RDP 真实用户会话（非 Session 0）通过 Chrome 与 Edge；
• Linux X11：精确 X11 前台恢复用于固定 setup 导航，AT-SPI 用于复选框与同意动作；
• Linux 原生 Wayland：要求精确 Sway container 与浏览器完整渲染器无障碍树，URL 文本 + Enter 保持在一次虚拟键盘生命周期内，再调用唯一的 AT-SPI Remote debugging 导航控件；在另有一个 Chrome 进程打开的情况下仍通过，证明变化的标签标题与共享 app id 不会重定向动作。

所有 setup 路径仍要求操作绑定的一次性批准工件、证明批准 PID 属主的 loopback 监听器、附加一个浏览器级 socket、失效旧能力、报告每个可见副作用，并在 setup 失败后尝试精确回滚。Safari、Firefox、未识别产品/区域设置、歧义 setup 或同意控件一律拒绝。生产调用若缺少完整 AT-SPI 树（Linux Chromium 族需--force-renderer-accessibility）则返回缺失前置条件拒绝。

语义浏览器状态：semantic_v2

2026-07-17 新增可选的semantic_v2快照契约，同时保留dom_refs_v1作为兼容默认。语义采集器（见 semantic.rs）将 Chromium 无障碍树、被穿刺的作者 DOM、布局快照、视口度量与已证明的 frame 身份联合：紧凑可读内容与类型化动作 ref 分离，可见状态优先于屏外状态，CSS 隐藏的保留控件在预算前排除，被固定/绝对定位页面遮罩覆盖的控件被保守识别。

关键语义规则：

• 语义动作 ref 声明click和/或type；当语义 ref 未声明所请求动作时，变更工具在分发前返回browser_action_unavailable；
• 带活后端身份的静态节点作为只读content_refs单独返回，绝不变成可点击；
• 有界 DOM 补充在 AX 遗漏时恢复带显式交互证据的可见自定义控件；
• 读作用域支持 role/name/textquery、当前scope_ref与不透明单次使用 continuation；continuation 存于会话能力存储，被使用、更新快照、导航、重连、target 替换或会话结束失效；
• 原始 CDP target id、后端节点 id、object id、选择器与 continuation 偏移保持私有；
• 已知的全 DOM 大小/序列化失败使用渐进变浅的深度阶梯，用有界DOM.describeNode调用水合截断分支；时间、调用计数与扫描节点预算终止水合并保留complete:false，无关传输失败仍是硬错误。

确定性 fixture 含 320 个 CSS 隐藏保留控件、可见的 message/editor/actions，以及 300+ 屏外控件。聚焦测试覆盖可见优先状态、continuation、query、子树作用域、动作种类强制、modal 遮挡、DOM 补充、有界回退与水合，以及更新快照和带外导航后的 stale continuation。隐藏节点省略计数去重，icon-font 字形从语义文本中移除。

最终验收矩阵与诚实边界

精确-SHA 跨平台验收

最终验收回放使用精确源 SHA7fa6c80f5c433a7d4dadef75e4873af89de0cd3f（Windows/Linux 发布检查点则为32c77f775bd16d50507fbedb54a9682b9ab5599d）。全部 60 行声明全部执行，每个结果test_status=pass，60 个 MP4 全部独立下载并验证正时长：

预期拒绝是产品信号而非环境跳过：每平台都在两个原生浏览器窗口同边界且无唯一标题 tie-break 时拒绝browser_binding_ambiguous；macOS 与 Linux 还因 Chromium 的可信 CDP Input 点击会激活独立 target 而拒绝browser_input_trust_unavailable（ref 定向的dom_event路由仍是合成全后台点击的替代）；Windows 为 Chrome/Edge 均交付可信点击且不改变 sentinel 姿态。Windows 车道在真实 RDP 用户桌面而非 Session 0 运行；Linux 车道分别用 Openbox/X11 与原生 Sway/Wayland；macOS 在 TCC 授权的可弃置 Lume guest 中运行。

过程中的诚实修正

日志完整记录了三次自我推翻：macOS AX 截止期修正（原生 AX walk 曾包在 30 秒 Tokio 超时里，spawn_blocking的 drop 无法取消已阻塞在 ApplicationServices 的AXUIElementCopyAttributeValue；现对应用及每个后代 AX 对象应用 Apple 有限原生消息超时，driver 级 walk 截止 20 秒，低于公共客户端限制）；macOS Tauri fixture 导航修正（release 构建缺tauri/custom-protocol特性导致前端未被服务，共享 Tauri feature 现映射到tauri/custom-protocol且 Cargo 通过rerun-if-changed监听../web目录）；Tauri loopback fixture 修正（生产 custom scheme 在 macOS WebKit 运行时不可靠，fixture 改为在临时 loopback 端口服务同一份shared/web/index.html）。日志明确区分产品缺陷与环境限制——可弃置 macOS VM 中 Tauri/WKWebView 渲染空白被判定为 VM 镜像的 GPU 进程环境限制，没有把空白表面转换成通过或预期产品拒绝。

当前明确限制

• Safari/WKWebView/WebKitGTK 类型化变更延后，直到存在精确的 WebKit 引擎→原生窗口路由；遗留/原生读取仍可用；
• Firefox 已被分类，但没有 WebDriver BiDi 引擎或类型化变更；
• 无合成器精确 pid+几何的通用 Wayland 不能授权浏览器变更；已验证的 X11 与 Sway 配置可以，这不意味着任意裸后台 PX 投递；
• 常见 WebView2 host 把原生 WPF 窗口与 Edge 渲染器拆分到多进程，该路由在相关性可证明前拒绝；
• browser_prepare刻意不把 DevTools 附加到、复制或重启个人既有 profile；已认证 profile 自动化是产品/安全决策而非隐式 setup 捷径；
• MCP 批准只证明请求经过了 host 批准路径，不是针对本机其他进程的"同用户 OS 安全边界"；直接批准 token 保持终端内、短寿命、单次使用且请求绑定。

对 Agent 开发者的使用启示

• 把拒绝当结果而非错误：所有浏览器工具的结构化输出共享{"status":"ok"|"refused",...}形态，Agent 应按refusal.code分支（如遇到browser_requires_setup就显式调用browser_prepare，遇到browser_ref_stale就重新get_browser_state取新 ref）。
• 先 bind 后 action，全程传 session：target/tab/ref 都是会话作用域能力，必须在start_session后携带显式 session id 调用；p<snapshot>:<index>ref 会被导航与新快照失效，重绑定是常态而非异常。
• 精确绑定不等于坐标点击：变更前 driver 会重新证明进程指纹、原生窗口、CDP target 与 ref 身份；如果你想合成全后台点击，请显式使用dom_event路由，而不是期待可信指针静默降级。
• 需要独立浏览器时用隔离 profile：通过交互式browser-approve铸造的短寿命单次 token 授权browser_prepare启动驱动属主隔离 profile；它不会碰你的日常 profile，这是设计使然。

本文所有实现细节均可回到仓库源码进一步验证：拒绝词表与序列化契约见 refusal.rs，相关性算法见 binding.rs，平台适配器契约见 platform.rs，准备路径见 prepare.rs，语义快照见 semantic.rs；真实浏览器证据由 standalone_browser_behavior_test.rs 与 core 内的 v2_tests.rs 承载。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua