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.getWindowForTargetBrowser.getWindowBounds映射到 CDP window 及其几何信息。相关性算法见 binding.rs分五步将页面 target 按可证明的 CDP window折叠为每个窗口一个代表reprepresentative标签页本身不构成独立原生窗口候选过滤出 CDP 窗口边界与原生边界在容差device pixels内匹配的候选恰好一个边界匹配 →Exact绑定多个不同 CDP 窗口共享最大化边界时常见于最大化窗口唯一的活动标签页标题匹配可消解歧义重复或缺失标题仍保持歧义无边界匹配时唯一标题匹配降级为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其闭合词表如下词表只允许增补重命名或删除对按码分支的消费者都是破坏性变更拒绝码语义browser_route_unavailable该进程无 CDP 路由非浏览器或引擎族在 v1 不支持 CDPbrowser_requires_setup支持 CDP 但没有已属主端点需显式运行browser_preparebrowser_binding_ambiguous多个 CDP 候选匹配同一原生窗口标题 tie-break 无法选出唯一项browser_binding_stale先前铸造的绑定不再指向同一进程/端点指纹漂移、端点变更、未知或跨会话 target idbrowser_wrong_target_refused重校验无法证明 CDP target 仍对应所绑定的原生窗口或对非精确绑定执行了变更browser_tab_required操作需要显式tab_id但未提供browser_tab_not_found该tab_id在本会话中未知或其 CDP target 已消失browser_ref_stale页面 ref 在标签页活动快照命名空间中无法解析畸形、跨命名空间或被导航失效browser_input_trust_unavailable可信 Input 域路由不可用且调用方未显式请求dom_event路由browser_endpoint_owner_mismatch发现的端点其所有权证明不能归属到目标进程browser_consent_required平台适配器在准备端点前要求显式用户/调用方同意browser_consent_revoked用户显式关闭或拒绝了浏览器属主同意 UIbrowser_reconnect_exhausted固定重连尝试/截止策略耗尽browser_input_incomplete输入操作只交付了请求文本的可证明前缀browser_action_unavailable语义 ref 存活但未声明所请求的类型化浏览器动作browser_origin_outside_scope活动顶层文档离开了能力清单中批准的原点集合浏览器输入被暂停拒绝码同时携带人类可读 message 与可选机器 detail如提示run browser_prepare。源码单元测试同时断言 serde 序列化与as_str完全一致且is_error保持未置位确保文本客户端也能从纯文本行读到拒绝码。会话作用域与工具面会话即命名空间浏览器 target、tab、快照与 ref 都是会话作用域能力。require_explicit_session强制要求调用方通过start_session声明显式会话并传递其 id——default或空会话直接报错因为能力命名空间必须有一个真实 owner其 end 事件负责清理。ref 采用psnapshot:index命名空间会被导航和同一标签页的新快照失效。公开的session参数是权威的同时保留 daemon 的隐藏会话镜像以兼容 MCP 传输。从 5 个 v1 工具到 9 个工具的完整表面v1 在 core 中登记了五个类型化工具并在所有平台注册相同 schema。随着实现演进当前浏览器工具面见 tools.rs 的register_browser_tools已扩展为九个get_browser_state——严格只读绑定、快照、读状态绝不执行 setup 或变更browser_prepare——显式准备识别已属主端点或返回明确的 setup/同意限制不会静默重启或修改 profilebrowser_navigate——导航browser_click——可信或显式合成synthetic点击browser_type——ref 绑定的可编辑输入要求当前 ref 且先证明焦点节点可编辑否则拒绝而非在未证明页面焦点下谎报成功browser_dialog——页面属主 JavaScript 对话框检查与解决browser_set_input_files——精确的文件输入赋值browser_download——批准作用域内的下载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、无泄漏输入、可观测处的光标保持以及可播放视频。各平台基线结果日志记录的最终修订版本共享与 macOScargo 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 原生 WaylandSway六个聚焦 sentinel 回归测试通过原生 preflight 通过刻意失焦 全屏恢复canary在禁用 Xwayland 的原生 Ozone Wayland 上规范 Electron 行 1/0/0/0。全局光标保持被省略因为标准 Wayland 无法读取全局指针位置。独立 Chromium 覆盖与对抗性测试v2 增加了仓库属主的独立 Chromium harness26c177d9统一了各平台的引擎分类与路由限制不支持的引擎可被发现但绝不宣传变更能力0295b881加入独立 Chromium 覆盖3287b44e加入对抗性多标签与同边界多窗口用例——面对歧义时 driver 拒绝而不是选第一个页面或用跨 CDP window id 的标题 tie-break。macOS 独立套件一次性通过精确 roundtrip、隔离准备、stale refs、组合 frame、多标签、同边界多窗口拒绝。组合文档与事件感知 CDPc8fb38ef让 ref 可以穿透开放 shadow root 与同进程 iframe跨进程 iframeOOPIF仅在运行时暴露可证明的 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交互命令铸造五分钟、单次使用、绑定 pidprofile 请求的 token启动独立 Chromium 进程使用驱动属主的isolated_new或isolated_namedprofileprofile.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 与 EdgeLinux 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_v22026-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与不透明单次使用 continuationcontinuation 存于会话能力存储被使用、更新快照、导航、重连、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 跨平台验收最终验收回放使用精确源 SHA7fa6c80f5c433a7d4dadef75e4873af89de0cd3fWindows/Linux 发布检查点则为32c77f775bd16d50507fbedb54a9682b9ab5599d。全部 60 行声明全部执行每个结果test_statuspass60 个 MP4 全部独立下载并验证正时长平台代表产品行数交付预期拒绝失败跳过可播放视频Windows/Win32Chrome, Edge201820020macOS/QuartzChrome, Edge201640020Linux/X11Chrome10820010Linux/WaylandChromium on Sway10820010合计6050100060预期拒绝是产品信号而非环境跳过每平台都在两个原生浏览器窗口同边界且无唯一标题 tie-break 时拒绝browser_binding_ambiguousmacOS 与 Linux 还因 Chromium 的可信 CDP Input 点击会激活独立 target 而拒绝browser_input_trust_unavailableref 定向的dom_event路由仍是合成全后台点击的替代Windows 为 Chrome/Edge 均交付可信点击且不改变 sentinel 姿态。Windows 车道在真实 RDP 用户桌面而非 Session 0 运行Linux 车道分别用 Openbox/X11 与原生 Sway/WaylandmacOS 在 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全程传 sessiontarget/tab/ref 都是会话作用域能力必须在start_session后携带显式 session id 调用psnapshot:indexref 会被导航与新快照失效重绑定是常态而非异常。精确绑定不等于坐标点击变更前 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考