cua-driver 跨版本兼容性夹具：以 0.12.6 冻结基线守护 Rust / Python / TypeScript SDK 的向后兼容

cua-driver 跨版本兼容性夹具以 0.12.6 冻结基线守护 Rust / Python / TypeScript SDK 的向后兼容【免费下载链接】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/cuacua-driver 通过libs/cua-driver/compat-fixtures/apps/目录维护一组上一版本发布态的最小示例应用previous-release application fixtures。这些应用被冻结在cua-driver-rs-v0.12.6发布标签上CI 会用它们去编译/运行每一个候选版本的 Rust、Python 与 TypeScript 包从而在发布新版本前验证连接构造器、端点访问器等稳定 API 没有被破坏。本文以该目录的 README.md 为主线结合 compat-fixtures 的 JSON 契约快照、三种语言的冻结源码以及对应契约测试完整说明这套兼容性保障机制的构成、原理与维护规则。一、背景为什么需要上一版本发布态夹具cua-driver 是一个跨平台macOS / Linux / Windows的 computer-use 自动化驱动其 SDK 通过 UniFFI 从共享 Rust 核心生成 Python 与 TypeScript 绑定见 contract/README.md。当项目迭代到新的候选版本时一个核心风险是新版本是否还兼容旧版本已发布的公开 API如果用户在升级驱动后现有应用代码无法编译或运行将直接破坏下游使用方。上一版本发布态应用夹具正是为此设计的回归防线它们以cua-driver-rs-v0.12.6提交9eb1f481b8a12cd6ffda2ad5af21653a9e5aa9e5为冻结基线这些应用故意只使用已发布版本提供的连接构造函数、端点访问器和语言特有的清理操作不引入任何新增 APICI 会用这些未改动过的源码去编译或运行候选版本的 Rust、Python、TypeScript 包。只要任一候选版本破坏这些 APICI 立即失败。也就是说这些应用是旧世界消费者的活体样本它们忠实模拟了一个只依赖 0.12.6 稳定面的下游应用任何新版本都必须继续让它跑起来。二、冻结基线的内容与边界与apps/同级的 compat-fixtures/README.md 完整描述了这组夹具的构成。整个compat-fixtures/目录锁定了cua-driver-rs-v0.12.6发布标签上的稳定公开契约字段快照快照来源于发布标签对应的包源码、生成绑定、cua-driver --help、cua-driver manifest以及 MCP JSON-RPC 响应。具体包括夹具文件锁定的内容python-package.jsonPython 包根导出package-root exports与可调用签名typescript-package.jsonTypeScript 包子路径导出、声明导出、生成的CuaDriver声明方法cli.jsonCLI--help头部/子命令目录以及manifest的部分字段mcp.jsonMCPinitialize、tools/list信封与工具字段、method-not-found 错误类别apps/针对上述基线编写的、保持不变的 Rust / Python / TypeScript 应用这里有一个关键设计决策测试对比的是语义字段而不是整个进程输出。正如 compat-fixtures/README.md 所述对比刻意排除了可执行文件路径、socket 路径、PID、会话标识符、平台相关的自然语言文案等易变值volatile values。同时发布版本号字段只校验其文档化形态semver而不是冻结为0.12.6——因为一个兼容的后继版本必然要改变版本号。兼容策略只允许增量夹具对后续版本施加了明确的演进边界允许新增 manifest 字段、新增工具、新增包元数据additive changes禁止删除或修改任何已记录的项目除非经过一次显式的兼容性决策explicit compatibility decision并有意识地更新夹具。这条规则保证了 SDK 可以持续丰富能力同时绝不让既有调用方静默失效。三、三种语言的冻结应用完整源码与 API 面apps/下三个应用分别展示了 cua-driver 在 Rust、Python、TypeScript 中最小的兼容客户端写法三个文件的头部都明确标注Frozen cua-driver-rs-v0.12.6 application source.。Pythonapps/python/app.pyFrozen 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 路径随后通过socket_path()读取被选中的端点并断言其非空。这正是 python-package.json 中锁定的connect(cls, socket_path: typing.Optional[str]) - CuaDriver与socket_path(self) - str的调用面。Rustapps/rust/src/main.rsuse 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}); }Rust 版本与 Python 版本结构完全一致CuaDriver::connect(None)构造兼容客户端socket_path()读取端点assert!校验非空。其依赖通过 apps/rust/Cargo.toml 的路径依赖指向仓库内 SDK 源码[dependencies] cua-driver-sdk { path ../../../rust/crates/cua-driver-sdk }TypeScriptapps/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();TypeScript 版本额外演示了 README 中提到的语言特有清理操作driver.uniffiDestroy()显式销毁 UniFFI 生成的对象释放底层资源。这与 typescript-package.json 锁定的static connect(socketPath: string | undefined): CuaDriverLike;声明一一对应。为什么不需要运行中的 daemonREADME 特别强调这些应用不需要一个正在运行的驱动守护进程。构造一个兼容客户端并读取它选中的端点这一操作是本地、无副作用的local and side-effect free。从 SDK 实现看rust/crates/cua-driver-sdk/src/lib.rs#L1008-L1017 中的socket_path()是一个兼容性访问器对于 daemon 后端返回 socket 路径对于 embedded / private-worker / remote 后端返回空字符串并注明新代码应改用execution_mode()分支判断。冻结应用正是利用了这一稳定访问器无需拉起任何后台进程即可在 CI 中完成验证。四、CI 验证机制契约测试如何消费夹具夹具不是静态摆设它被三套语言测试直接引用。PythonAST 级签名比对python/tests/test_compatibility_contract.py 通过 Pythonast模块解析候选包的源码将函数签名含async前缀、参数注解、默认值、返回类型渲染成字符串与compat-fixtures/python-package.json中的cua_driver_methods逐一对比。这种方式不执行任何进程直接在语法树层面锁定导出与签名形状。Rust运行真实二进制断言rust/crates/cua-driver/tests/compatibility_contract_test.rs 则直接include_str!引入cli.json与mcp.json随后运行cua-driver --help断言输出包含cli.json中锁定的每一行帮助文本如Usage: cua-driver [SUBCOMMAND] [OPTIONS]与完整子命令目录mcp, list-tools, describe, call, serve, stop, revoke, status, config, telemetry, recording, update, check-update, doctor, diagnose, permissions, autostart, skills, manifest运行cua-driver manifest断言schema_version、binary_version须为可解析的 semver、mcp_invocation.args须为[mcp]等字段与cli.json一致逐一核对 manifest 中每个子命令的参数列表例如mcp的--socket、--grant、--claude-code-computer-use-compat、--embedded、--host-bundle-id以及serve的--permission-mode、--grant、--dangerously-bypass-approvals、--capability-manifest、--session-policy、--no-permissions-gate等选项。MCP 侧则锁定initialize响应协议版本2025-06-18、server_name: cua-driver、tools/list的必需工具集合list_apps、list_windows、get_window_state、launch_app、click、type_text、press_key以及click工具的字段子集还有未知方法错误的 JSON-RPC 错误码-32601。TypeScript 侧对应的compatibility-contract.test.mjs位于 typescript/test/与上述两套测试共同构成语言 × 契约边界的完整矩阵。五、基线冻结后的演进实例契约如何被有意更新夹具维护规则是冻结但不僵化。compat-fixtures/README.md 记录了两次发生在冻结之后的真实演进展示了 additive 与 breaking 变更分别如何处理RFC 3682 的破坏性 click 变更ClickInput现在必须携带ActionTarget、ClickPosition坐标或元素 token以及显式的 background/foregroundInputDeliveryModeclick直接返回ActionResult工具拒绝时抛出DriverError.Tool。对应地Python 的 click 签名被更新而 TypeScript 基线当初就没有冻结该方法因此无需改动。其余冻结的包签名、CLI/MCP 夹具与基线应用夹具均保持不变。RFC 2549 的增量 CLI 变更新增cua-driver mcp --direct标志。裸mcp行为保持平台定义Windows/Linux 上为 directmacOS 上为签名应用服务--socket继续用于选择显式服务。语义兼容性测试允许该增量标志存在而无须重写已冻结的cli.json基线。这两个案例印证了夹具的核心设计哲学新增能力永远自由破坏稳定面必须显式决策并同步更新夹具。六、维护规则什么时候才能修改这些应用回到 apps/README.md 的最终约束Do not update these sources for additive SDK features. Change them only after an explicit compatibility decision establishes a new frozen baseline.即不要为了让这些应用使用新 SDK 特性而更新它们这会让上一版本消费者失去代表性只有一次显式的兼容性决策确立了新的冻结基线之后才允许修改。同理compat-fixtures/README.md 也要求任何删除或修改已记录项目的行为都必须先有兼容性决策和有意为之的夹具更新。对维护者而言这套机制意味着发布候选版本前只需让 CI 编译/运行apps/下三个未改动的冻结应用即可获得0.12.6 用户升级到新版本这一最坏情形的直接证据对使用者而言只需遵守冻结面中的connectsocket_path 语言清理操作即可确保自己的代码长期处于官方兼容保障的覆盖范围内。【免费下载链接】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），仅供参考