CUA Driver 版本兼容性保障解析 Qwen Code 的 Previous-Release Application Fixtures 冻结基线机制【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeQwen Code 在 packages/cua-driver/compat-fixtures/apps 目录下维护了一套上一版本应用夹具Previous-release application fixtures将一组仅依赖cua-driver-rs-v0.12.6稳定公共 API 的 Rust、Python、TypeScript 小型应用原样冻结由 CI 持续对新候选包编译与运行以守护 SDK 的向后兼容性。本文以该目录的 README.md 为核心骨架结合上层快照体系与三套兼容性测试源码完整讲解这套机制的冻结基线、三语言示例、CI 校验逻辑与变更纪律帮助你理解如何在不破坏既有用户代码的前提下演进一个跨语言驱动 SDK。背景为什么要冻结上一版本的应用Cua Driver 是 Qwen Code 内置的跨平台桌面与浏览器自动化运行时提供 MCP 服务、一次性 CLI 以及进程内 Python / TypeScript SDK见 packages/cua-driver/README.md。SDK 面向的是外部开发者的应用代码一旦发布cua_driverPython、qwen-code/cua-sdkTypeScript和cua-driver-sdkRust crate就会被大量既有程序引用。如果某个新版本悄悄改变了构造函数签名、endpoint 访问器语义或清理操作的行为用户升级后就会在运行时崩溃。传统做法是用单元测试覆盖当前代码而compat-fixtures/apps的做法更进一步直接冻结一组针对已发布旧版本的、几乎不可能被顺手改坏的真实应用源码作为 CI 中独立于 SDK 内部单测的验收样本。由于这些源码自冻结之日起就不再随 SDK 演进任何破坏性变更都会立刻暴露为旧应用无法在候选包上编译/运行从而把兼容性判断从开发者自觉变成机器强制。冻结基线版本、提交与 API 使用约束apps/README.md 明确了这套夹具的锚点冻结目标cua-driver-rs-v0.12.6发布版冻结提交9eb1f481b8a12cd6ffda2ad5af21653a9e5aa9e5API 使用范围只允许使用三类已发布接口——连接构造函数connection constructor、endpoint 访问器endpoint accessor、各语言专属的清理操作language-specific cleanup operation。这意味着每个示例应用都刻意保持最小可运行构造一个兼容性客户端 → 读取其选中的 endpoint → 打印输出。apps/README.md特别强调这类操作是本地且无副作用的local and side-effect free不需要启动任何 daemon、不需要屏幕捕获、不需要权限授权因此 CI 可以在完全无头、无图形环境的安全沙箱中执行既验证了包的可用性又不触碰操作系统敏感能力。三语言示例应用逐行解读夹具目录 apps 下按语言分为python/、rust/、typescript/三个子目录各自对应 SDK 的一种官方绑定。Rustcua-driver-sdk的连接与断言rust/src/main.rs 是全部三个示例中逻辑最直白的一个use cua_driver_sdk::CuaDriver; fn main() { let driver CuaDriver::connect(None).expect(create compatibility client); let endpoint driver.socket_path(); assert!(!endpoint.trim().is_empty(), default endpoint must be selected); println!({endpoint}); }关键点CuaDriver::connect(None)使用默认连接参数None对应上一版本应用只依赖发布构造函数的约束driver.socket_path()读取所选 endpoint并用assert!强制其非空——若候选包在无 daemon 时不再能选出默认 endpoint此断言会直接让测试失败其工程配置见 rust/Cargo.toml依赖通过相对路径指向仓库内的cua-driver-sdkcratepublish false表明它仅作为本地校验样本存在绝不会被发布到 crates.io。Pythoncua_driver的异常式校验python/app.py 与 Rust 版本一一对应只是把assert换成显式异常Frozen cua-driver-rs-v0.12.6 application source. from cua_driver import CuaDriver driver CuaDriver.connect(None) endpoint driver.socket_path() if not endpoint.strip(): raise RuntimeError(default endpoint must be selected) print(endpoint)这里使用的CuaDriver.connect(None)、socket_path()与 python-package.json 中锁定的connect(cls, socket_path: typing.Optional[str]) - CuaDriver与socket_path(self) - str签名完全吻合说明夹具应用正是针对锁定签名书写的真实消费者代码。TypeScript显式销毁的清理操作typescript/app.mjs 是唯一显式演示语言专属清理操作的示例// Frozen cua-driver-rs-v0.12.6 application source. import { CuaDriver } from trycua/cua-driver; const driver CuaDriver.connect(undefined); const endpoint driver.socketPath(); if (!endpoint.trim()) throw new Error(default endpoint must be selected); console.log(endpoint); driver.uniffiDestroy();与前两者不同它在打印 endpoint 之后调用了driver.uniffiDestroy()。这是因为 TypeScript SDK 基于 UniFFI 生成绑定持有原生运行时的句柄应用退出前需要显式销毁以避免资源泄漏。注意冻结时点的包名是trycua/cua-driver而当前 Qwen 发行版面向 TypeScript 应用的导入名已是 Qwen 自有的qwen-code/cua-sdk见 packages/cua-driver/README.md——这正体现了夹具的价值即使包名与版本演进这段旧代码依然必须能被新包解析并正常运行。上层快照体系四个 JSON 基线文件apps/并非孤立存在它与 packages/cua-driver/compat-fixtures 根目录下的四个 JSON 快照共同构成完整的兼容性锁。根据 compat-fixtures/README.md快照文件锁定内容python-package.jsonPython 包根导出package_root_exports、构造函数签名package_constructor_signatures、wrapper 函数签名、CuaDriver全部公开方法签名typescript-package.json包子路径导出.、./embedded、./electron、声明导出、生成的CuaDriver声明方法、入口声明cli.jsonCLI--help头部与子命令目录、manifest关键字段mcp.jsonMCPinitialize、tools/list信封与工具字段、未知方法错误的类别这些快照不是整进程输出的逐字拷贝。如 compat-fixtures/README.md 所述快照是从发布标签的包源码、生成绑定、cua-driver --help、cua-driver manifest和 MCP JSON-RPC 响应中推导而来测试比较的是语义字段而非整段输出从而有意排除了可执行文件路径、socket 路径、PID、会话标识符、平台相关文案等易变值。另一个刻意设计是版本号字段只校验其文档化的形态如 semver而不冻结为0.12.6因为一个兼容的后继版本必然要更改版本号。以 cli.json 为例它锁定了help 前几行cross-platform computer-use automation driver、Usage: ...、子命令列表mcp, list-tools, describe, call, serve, stop, revoke, status, config, telemetry, recording, update, check-update, doctor, diagnose, permissions, autostart, skills, manifestmanifest的schema_version: 1、binary_version_format: semver、mcp_args: [mcp]各子命令的参数清单类型化校验例如serve必须保留--socket、--permission-mode、--grant、--dangerously-bypass-approvals、--capability-manifest等参数名与类型call必须保留toolpositional-string与json-argspositional-json等。CI 校验链路测试源码如何消费这些夹具三层语言各自有对应的兼容性测试直接消费compat-fixtures下的文件构成快照对比 应用编译运行的双重防线。Rust 侧CLI 与 MCP 契约测试rust/crates/cua-driver/tests/compatibility_contract_test.rs 通过include_str!直接内嵌cli.json与mcp.json并启动真实构建出的qwen-cua-driver可执行文件做黑盒校验released_cli_help_and_manifest_fields_remain_compatible运行--help断言快照中的 help 行仍然存在注意测试把Usage: cua-driver前缀替换为Usage: qwen-cua-driver兼容 Qwen 自有可执行名运行manifest后对比schema_version、校验binary_version是合法 semver、断言 MCP 调用参数为[mcp]、遍历快照中每个子命令的参数清单做类型比对released_mcp_initialize_tools_list_and_error_fields_remain_compatible通过RawDriver::spawn()启动驱动发送标准 JSON-RPC 请求验证initialize的protocolVersion、serverInfo、能力键tools/list的schema_version、capability_version、必需工具与选定工具字段以及未知方法错误的 code/message此外还包含 macOS 专属的--direct语义测试explicit_direct_mcp_is_read_only_for_permissions_and_refuses_overlay_tools与 Prime Agent 连接指引测试。Python 侧AST 级签名比对python/tests/test_compatibility_contract.py 采用了一个更轻量但同样严格的策略用ast模块解析当前包的__init__.py、wrapper.py和_native.py将函数签名渲染为规范化字符串再与python-package.json中锁定的签名集合做精确相等/包含比对。它校验__all__导出集合必须包含快照中的全部根导出CuaDriver、ToolResult、DriverOptions、CaptureScope等数十个符号_connect_python_sdk、_create_python_sdk的签名与快照完全一致get_binary_path() - Path、run_cua_driver(args: Optional[list[str]] None) - int签名一致CuaDriver类中所有非下划线方法的签名必须覆盖快照中的cua_driver_methods清单从connect、create到socket_path、shutdown共二十余个方法。由于比对发生在 AST 层而非运行时该测试无需启动任何进程速度极快可以在每次提交时廉价运行。TypeScript 侧与整体执行TypeScript 侧对应测试位于 typescript/test/compatibility-contract.test.mjs用于核对typescript-package.json锁定的子路径导出与声明。整体上CI 会对候选的 Rust、Python、TypeScript 包分别执行编译/运行未修改的apps/源码与语义字段快照比对两类检查见 apps/README.md 与 compat-fixtures/README.md。由于夹具应用不依赖运行中的 daemon这些步骤可以在标准 CI runner 上安全地完成。变更纪律什么情况下才允许触碰这些夹具apps/README.md 给出了两条硬性约束这也是整套机制的灵魂禁止为新增 SDK 功能更新这些源码Do not update these sources for additive SDK features。新增工具、新增 manifest 字段、新增包元数据都属于附加性变更只会反映到上层 JSON 快照中快照同样允许附加项存在见 compat-fixtures/README.md而应用源码必须保持冻结以确保它们始终代表上一版本用户的真实代码。只有显式的兼容性决策建立新的冻结基线后才允许整体替换Change them only after an explicit compatibility decision establishes a new frozen baseline。换言之任何对apps/的改动都等同于声明旧的 0.12.6 基线正式退役这是一个需要跨团队评审的流程事件而不是顺手为之的日常修改。一个值得注意的例外被记录在 compat-fixtures/README.mdRFC 2549 独立接受了一项附加 CLI 变更cua-driver mcp --direct。裸 MCP 行为保持平台定义Windows/Linux 为 directmacOS 为签名应用服务--socket继续选择显式服务语义兼容测试允许该附加 flag 存在而无需重写冻结的cli.json基线——这展示了附加允许、删除/修改必须显式决策原则的具体运作方式。延伸阅读compat-fixtures/README.md整套夹具体系的总体说明与四个 JSON 快照的职责划分cli.json、python-package.json、typescript-package.json、mcp.json可直接查看的冻结快照compatibility_contract_test.rs 与 test_compatibility_contract.pyRust / Python 两侧的兼容性测试实现packages/cua-driver/README.mdCua Driver 的安装、MCP 集成、权限模式与仓库布局总览。这套冻结上一版本应用 语义快照 三语言 CI 执行的组合为多语言 SDK 的长期演进提供了一条可机械执行的兼容性底线它把不能破坏用户的承诺从口头规范转化为每次构建都会强制校验的硬约束值得所有面向外部开发者的跨语言驱动项目借鉴。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
