Qwen Code CUA Driver 浏览器引擎支持规划：从 CDP 原生边界到多引擎协议中立内核
【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code
本篇技术指南围绕 Qwen Code 仓库中 browser-engine-support-plan.md 展开，剖析 CUA Driver 浏览器自动化工具面当前"仅支持 Chromium 系 CDP"的边界设计、Firefox 与 Safari 各自协议路线的约束，以及面向未来多引擎支持提出的协议中立内核（BrowserTransport / BrowserContextId / 引擎适配器）演进蓝图。读完本文，你将理解为什么一个引擎必须先在"精确定位、审批与后台投递"三重保证上达标才能被纳入支持矩阵，也能掌握browser_route_unavailable结构化拒绝的完整字段语义与源码级实现依据。
文档定位：这是一份架构说明与实施路线图，而非支持矩阵
原文档开篇即明确了自己的性质：它记录的是"为什么类型化（typed）浏览器工具面只有在一个引擎能够保留精确定位（exact targeting）、审批（approval）与后台投递（background-delivery）保证之后，才支持该引擎"的架构理由与落地路线。它并不是一张支持矩阵——当前仓库中已被正式接受的浏览器与平台组合，仍以公开支持契约（public support contract）为准，例如 contract/README.md 与包内 docs/test-matrix.md 所维护的验收范围。
理解这一边界对读者至关重要：本文档描述的是"未来可以如何做"与"当前为什么不这样做"，而不是"当前支持哪些浏览器"。任何基于本文档推断 Firefox/Safari 已被支持的结论都是错误的——在源码实现中，这两个引擎族当前只通向一种确定性的结构化拒绝。
当前边界：CDP 原生（CDP-native）的浏览器工具面
核心架构：CdpConnection + BrowserPlatform
当前浏览器引擎实现完全以 CDP（Chrome DevTools Protocol）为根基。从源码结构看，其关键组件如下：
CdpConnection：位于 cdp_ws.rs，封装 WebSocket 连接、请求/响应通道与事件扇出（CdpConnection::subscribe），并配套CdpPool连接池管理复用与生命周期。BrowserEngine：位于 engine.rs，是五个浏览器工具背后的语义核心，持有 target/ref 存储、CDP 连接池与全部"精确或拒绝（exact-or-refused）"决策。BrowserPlatform：位于 platform.rs，是平台适配器契约。它抽象的是操作系统身份与端点所有权（进程指纹、原生窗口元数据、浏览器分类、回环端点归属、显式端点准备），而不是浏览器线协议——协议的差异不属于该 trait 的职责范围。
CUA Driver 核心持有CdpConnection，把一个原生窗口绑定到某个精确的 Chromium target，并且在任何变更（mutation）之前重新证明整条身份链：进程指纹 → 原生归属/边界 → 端点归属 → CDP target 类型/窗口（对应BrowserEngine::revalidate_for_mutation的实现注释，见 engine.rs）。窗口与 CDP 候选的关联允许 8 像素的设备像素容差（BOUNDS_TOLERANCE_PX），以吸收窗口阴影与 DIP 取整差异。
为什么"重命名 CDP 概念"不能如实表达 Firefox 或 Safari
文档指出：当前的边界对 Chromium 是恰当的，但通过给 CDP 概念换名字来假装它代表 Firefox 或 Safari，是不诚实的。BrowserPlatform只负责 OS 身份与端点所有权，它无法承载浏览器线协议的差异。
在 types.rs 中，平台适配器对某个 pid 的分类结果BrowserClassification包含：is_browser、engine（BrowserEngineFamily：chromium/gecko/webkit/unknown）、product_kind（BrowserProduct：Google Chrome、Chromium、Microsoft Edge、Brave、Vivaldi、Opera、Arc、Electron、Firefox、Safari 等）、product可读名、channel发布通道，以及supports_cdp布尔门。supports_cdp是整个 v1 浏览器工具路线的总闸——只有 Chromium 家族才为真。
因此，对于不支持的引擎，工具面在触碰原生窗口探测或端点探测之前，就会返回browser_route_unavailable结构化拒绝，并携带受限的engine_family、product、required_protocol、limitation明细字段。
结构化拒绝的源码级实现：browser_route_unavailable
拒绝机制的实现集中在 refusal.rs：
- 封闭的拒绝码词表
BrowserRefusalCode采用 snake_case 序列化（如browser_route_unavailable），词表只增不改——重命名或删除某个码对依赖它的调用方属于破坏性变更； - 拒绝结果序列化为
structuredContent：{"status":"refused","refusal":{code,...}}，并不是 MCP 协议错误（isError不置位），调用本身执行成功，其"结果"就是拒绝，Agent 应当对structuredContent.status分支处理； - 人类可读的文本行同样携带稳定码（
refused (<code>): <message>），保证纯文本客户端的可读性； - 词表测试
every_code_serializes_to_the_documented_snake_case_string与refusal_tool_result_shape_is_stable（refusal.rs）锁定了线上格式。
真正为不支持引擎生成拒绝的是 engine.rs 中的unsupported_engine_refusal。它对四种引擎族分别产出不同明细：
| engine_family | 拒绝消息要点 | required_protocol | limitation |
|---|---|---|---|
gecko（Firefox） | 需要 WebDriver BiDi 或 Remote Agent 路线；附加到普通运行中 profile 不受支持 | webdriver_bidi | remote_agent_requires_launch_time_enablement |
webkit（Safari） | 需要 WebKit 原生自动化路线；Safari 不对普通运行中 profile 暴露可附加的 CDP 端点 | webkit_automation | no_attachable_runtime_endpoint |
chromium | 该 Chromium 家族浏览器未暴露受支持的 CDP 路线 | cdp | cdp_unavailable |
unknown | 该浏览器引擎没有受支持的类型化浏览器路线 | unknown | engine_route_unavailable |
测试侧同样锁定了这一行为：v2 测试断言拒绝码为browser_route_unavailable且不产生截图副作用（见 v2_tests.rs），e2e 测试kit 也在浏览器拒绝码集合中收录了browser_route_unavailable（见 e2e.rs）。
Firefox：WebDriver BiDi 与 Remote Agent 的现实约束
Firefox 的官方自动化通道是Remote Agent 实现的 WebDriver BiDi。Mozilla 文档明确：它通过--remote-debugging-port启动、接受回环（loopback）连接，并且没有其他启用机制——一个普通方式启动、未携带该标志的 Firefox 进程，若不重启就无法变得可附加。
由此文档导出四条直接后果，这些后果在源码的unsupported_engine_refusal中均有对应：
- CUA Driver 不得修改 profile、不得重启 Firefox、不得把桌面输入回退（desktop-input fallback）声称成"类型化浏览器附加"。附加必须是协议级的，而不是输入级的。
- 对已运行普通 Firefox profile 的"现有 profile 附加"仍是有结构的拒绝（structured refusal）——即
browser_route_unavailable+webdriver_bidi+remote_agent_requires_launch_time_enablement。 - 未来可行的路线是 driver 自有的隔离 Firefox 进程（driver-owned isolated process），但它需要的是WebDriver BiDi 传输层 + 能力存储（capability store），而不是一个 CDP 适配器——这正是下文"协议中立核心"的动机之一。
- Firefox 能力必须把 BiDi 会话、浏览器进程代际（generation）、原生窗口、浏览上下文（browsing context）与 CUA 会话绑定在一起，并在重连后全部重新证明。这与当前 Chromium 路径"每次变更前重证整条链"的哲学一脉相承。
Safari：safaridriver 与 WebDriver 的隔离模型
Safari 的自动化使用safaridriver与标准 WebDriver。Apple 要求宿主机启用远程自动化，并描述了自动化会话与普通浏览数据之间额外的隔离。
关键事实与后果：
- Safari 不暴露当前绑定/授权模型所依赖的回环 CDP 端点——它根本没有可附加的 DevTools 端点，
supports_cdp为假，这是 WebKit 家族的硬性事实。 - CUA Driver 不得把一个新建的 WebDriver 自动化窗口呈现为对用户既有 Safari profile 的"附加"——自动化会话与正常浏览数据之间的隔离意味着两者身份上就不等价。
- 未来的 Safari 引擎需要显式的 WebDriver 会话契约、Safari 自有的审批状态（Safari-owned approval state）、原生窗口关联，以及会话级隐私规则。
- 现有 profile 附加保持结构化拒绝，直到一条真实的 Safari 路线能够在不复制、不重启 profile的前提下证明上述属性。
源码中 WebKit 族的拒绝明细（webkit_automation/no_attachable_runtime_endpoint）与文档表述完全对齐，见 engine.rs。
协议中立核心：在 CDP 之上引入协议边界
面向未来多引擎实现，文档给出了明确的架构立场：在 CDP 之上引入一条协议边界（protocol boundary），而不是继续扩展BrowserPlatform。理由清晰：BrowserPlatform的职责是 OS 身份与端点所有权，混入协议差异会破坏现有平台适配器的单一职责。
五个设计要点
BrowserTransport拥有连接、代际（generation）与重连行为——把当前CdpConnection/CdpPool承担的传输职责抽象为与具体协议无关的传输层。BrowserContextId取代公共能力存储中的 CDP target 与会话标识符——公共面不再泄漏 CDP 概念。- 引擎适配器提供快照、导航、键入、指针、对话框、上传、下载与生命周期操作，并带显式能力标志（capability flags）——每种引擎按其实际能力声明支持范围。
- 原生绑定仍是一个独立的证明（separate proof），在每次变更之前与引擎上下文（engine context）连接起来——多引擎时代，"窗口属于该进程"的 OS 级证明依然是不可跳过的前置条件。
- 审批工件（approval artifacts）必须指名引擎、精确的进程/窗口代际，以及请求的 profile 姿态（profile posture）——审批不再只是"给这个窗口放行"，而是绑定到引擎与代际，防止跨代复用。
不可打破的红线
任何适配器都不得用前台桌面输入（foreground desktop input）静默模拟缺失的引擎动作。它要么满足类型化动作契约，要么返回稳定的拒绝。
这条红线呼应了文档针对 Firefox 的第 1 条后果：类型化浏览器动作（typed browser action）的契约建立在协议级证据之上，"看起来像点击了"的输入级模拟不构成证据。它与 refusal.rs 中"大部分失败路径不是协议错误，而是有意为之、机器可读、供调用方分支的拒绝"的整体哲学一致。
发布验收：一个引擎怎样才能成为"受支持"
文档最后给出引擎进入支持矩阵的验收标准——只有在**有代表性的真实浏览器测试行（representative real-browser rows）**上逐项证明以下八项，一个引擎才算受支持：
- setup 或启动遵循已公布的 profile 契约——driver 不得偷偷修改 profile 或重启；
- 精确的窗口与浏览上下文绑定，包括歧义窗口（ambiguous-window）场景——对应拒绝码
browser_binding_ambiguous的覆盖要求； - 重连代际失效与陈旧能力拒绝——对应
browser_binding_stale与browser_wrong_target_refused； - 对每个已公布动作的外部页面状态变更（external page-state mutation）——动作必须真实改变页面状态，而非仅仅注入输入；
- 后台焦点、z-order/遮挡、光标与无泄漏输入（no-leaked-input）守卫——对应 platform.rs 中 OS 身份与窗口状态验证的职责，以及 v2 测试中对后台/遮挡场景的拒绝断言（e2e 拒绝码集合中的
background_occluded、background_uipi_blocked等）； - 对不可用动作与环境的非变更式结构化拒绝（non-mutating structured refusals）——拒绝发生不得产生副作用；
- 打码（redacted）的截图、轨迹、日志与遥测——隐私边界贯穿产物全链路；
- 在精确源码提交（exact source commit）上可播放的视频证据——验收必须可追溯、可复核。
这套验收标准实质上是在说：一个引擎只有完整满足"精确定位、审批、后台投递"三大保证，才配得上被列入支持契约——这也正是本文档标题"Browser Engine Support Plan"的落点。
总结与阅读建议
browser-engine-support-plan.md是一份"边界说明书 + 演进路线图"：它先澄清当前 CDP 原生边界的合理性，再以 Firefox（WebDriver BiDi）与 Safari（safaridriver/WebDriver）为例说明为何不能靠重命名概念来假装支持，随后给出协议中立内核的五点设计，最后用八项验收标准约束未来引擎的加入门槛。源码侧，engine.rs 的unsupported_engine_refusal、refusal.rs 的封闭拒绝词表、types.rs 的引擎分类与supports_cdp门、platform.rs 的平台适配器契约，以及 v2_tests.rs 与 e2e.rs 中的拒绝断言，共同构成了本文档的完整实现证据链。
建议进一步阅读同目录下的配套文档：browser-existing-profile-attachment-plan.md（现有 profile 附加的结构化拒绝与授予模型）、browser-tool-implementation-plan.md 与 browser-tool-implementation-journal.md（工具面实现与演进记录）、browser-cross-platform-hardening-journal.md（跨平台加固），以及 docs/test-matrix.md（当前真实支持矩阵）。
【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
