Cua Driver SDK 的 Rust Source-of-Truth 架构与 UniFFI 评估决策以单一 Rust 契约消除多语言绑定漂移【免费下载链接】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/cua 仓库中 Cua Driver 关于SDK 绑定架构的核心决策记录sdk-rust-source-of-truth-and-uniffi-evaluation-plan.md。它回答了三个环环相扣的问题为什么类型化 Rust 契约contract必须成为 Python/TypeScript SDK 的唯一事实来源source of truth、为什么 Agent 集成必须保持 MCP/CLI 而非依赖生成客户端、以及UniFFI 绑定在什么条件下才值得被采纳。读完本文你将掌握该项目的工具契约分层模型、schema 子集校验subset-and-existence的验证思路、可复现代码生成的 CI 门槛以及最终Python/TypeScript 均保留 typed MCP 客户端这一落地方案的完整证据链。一、先分清两个产品边界Agent 集成与导入型 SDKCua Driver 此前把两个不同的问题混为一谈而该计划的起点就是将它们拆开。配套文档 why-cua-driver-uses-mcp-instead-of-uniffi.md 给出了精确的产品区分表面Surface消费者公开形态运行时可移植性由谁提供Cua 作为 Agent 的 MCP/CLICodex、Claude Code、其他 Agent、Shellcua-driver mcp与cua-driver callMCP 与可执行协议本身已跨运行时可用Cua 作为导入型 SDKPython、TypeScript、Swift、Kotlin 等应用cua_driver或trycua/cua-driverPython/Node 通过 UniFFI 绑定调用共享的 Rust daemon-client 实现这两个边界的本质区别在于MCP 回答的是Agent 或进程如何跨越服务边界调用一个工具——MCP 已经定义了工具发现、调用、结果与错误协议一个 Python Agent 和一个 TypeScript Agent 可以消费同一个 MCP server无需 Cua 为它们各自生成协议客户端。UniFFI 回答的是多种语言的应用程序代码如何调用同一个 Rust 库实现——它解决的是一份实现分发到 N 个运行时的问题而不是跨进程协议问题。因此MCP 与 UniFFI 是正交的它们解决不同边界上的问题并非互相竞争的协议选择。这也是全文反复出现的一条主线MCP 永远是 Agent 边界UniFFI 只是导入型 SDK 的候选分发方式。二、核心决策Rust 作为事实来源MCP/CLI 作为 Agent 基线计划文档给出了明确的执行决策Executive decision继续推进 Rust source-of-truth 工作同时把 Agent 边界与导入型 SDK 边界分离。MCP/CLI 是基线 Agent 架构UniFFI 仍是分发 Rust SDK/server 实现的候选。推荐的执行序列共 7 步立即证明 PR #2341 的十个可移植桌面契约是每个活跃平台 schema 的有效子集建立一个无传输层transport-free的 Rust 规范 crate成为类型化输入、结构化输出、元数据、能力capabilities、平台在场信息platform presence与可移植投影的唯一所有者增量地把活跃平台实现迁移到这些共享类型上先从四个已是规范形态的会话工具开始再迁移一个真正分叉的桌面切片保持 MCP 与 CLI 作为规范的 Agent 集成方式——MCP 兼容的 Agent不需要生成的 Cua 客户端用 Python Claude Agent SDK 与 TypeScript Codex SDK 示例证明这一点把生成的 Python/TypeScript 包保留为面向应用代码的类型化 MCP 客户端 SDK但不声称它们增加了运行时可移植性为想要共享 Rust 实现的消费者尤其是 server-hosting 或嵌入式 SDK 消费者运行一次有时间盒、按语言拆分的 UniFFI spike把 Python 当作成熟目标、TypeScript 当作独立第三方工具链评估只有当某门语言的 UniFFI 方案可复现、集中了有意义的 Rust 行为、且通过下述打包与运行时门槛时才为它采纳 UniFFI。一个重要边界被明确排除在当前工作之外直接把 GUI 引擎嵌入宿主进程不属于本次客户端生成工作。现有运行时假设共享 daemon、进程级全局状态、OS 专属的主线程与权限行为宿主进程库无法安全继承这些假设除非另行设计。因此UniFFI 封装共享 Rust daemon 客户端与UniFFI 嵌入式/server SDK是两个不同的候选方案。三、被确认的现状Confirmed current state3.1 PR #2341 的契约面cua-driver-contract声明了14 个类型化工具4 个会话生命周期工具 10 个可移植桌面循环工具manifest、Python 参数类/方法、TypeScript 接口/方法都由该 Rust 契约 crate 生成Python 与 TypeScript SDK 通过 stdio 与cua-driver mcp通信两个 SDK 都保留了通用调用与tools/list访问供运行时发现与平台专属工具使用生成文件具备**所有权清单ownership inventory**与真实的--check漂移检测模式语言包的公开类Python 为CuaDriver与AsyncCuaDriverTypeScript 为CuaDriver。对照 contract/README.md当前生成 manifest 位于 contract/manifest.json契约源码位于 cua-driver-contract/src/lib.rs其 crate 文档明确写道本 crate 刻意不包含任何传输层或平台实现……原生 driver 仍是唯一的执行引擎本包拥有类型化输入/结果以及版本化声明供活跃运行时使用并用于生成实验性客户端 SDK。3.2 今天的奇偶性parity到底证明到了哪一步现状盘点非常诚实它区分了元数据奇偶性与行为/输出奇偶性四个会话工具通过ToolDef::from_contract从规范契约构建活跃ToolDef元数据但调用逻辑仍是手写的——这只能证明元数据一致不能证明行为或输出一致十个桌面契约是单独编写的portable_subset声明平台 crate并不消费这些输入类型而是各自维护更丰富的ToolDefschema 与逐字段的ArgsExt解析当前没有任何测试证明每个可移植输入 schema 被对应的活跃平台 schema 接受Capabilities 存在两处声明运行时 capability map 与每个ToolContract。现有测试只比较二者并未消除重复所有权。3.3 平台名单与运行时形态按注册统计各平台工具数约为macOS48 个工具Windows49 个工具Linux52 个工具。文档特别强调这些数字必须在各 OS 上用真实的tools/list核实后才能作为发布证据且不能固化为全局断言——各平台名单有意不同且在演进例如 Windows 注册了debug_window_info而 Linux 注册了四个额外的底层指针原语。运行时约束是传输决策的核心daemon 通过一个共享 registry 与工具状态服务并发连接核心会话钩子、activity、元素令牌等设施使用进程级全局单例在 macOS 上 AppKit 表面要求主线程权限身份与可执行文件绑定。这些约束直接决定了为什么不能直接嵌入引擎。3.4 Fleet 项目对 UniFFI 的证明力与不证明力同仓库的 fleet 项目为 UniFFI 提供了强先例它对 Python、Kotlin、Swift、Ruby 等官方 UniFFI 目标有 checked-in 生成器使用固定的 Rust 依赖并支持重新生成检查generate-sdk-bindings.sh。Fleet 还包含生成的 TypeScript 示例Node N-API 路径使用uniffi-bindgen-react-native、ubjs/core、ubjs/node加载原生cdylib与浏览器/WASM 路径。但该计划的措辞非常谨慎这些 TypeScript 产物证明的是可行性不是生产级生成流水线。在被检视的树中TypeScript 不在 Fleet 主生成/检查脚本内React Native 生成器未在 Rust workspace 中固定版本示例ubjs/*依赖使用latest浏览器 WASM 胶水依赖未 checked-in 的配置与生成。因此得出的三条结论是不要把 Fleet 的 TypeScript 路径描述为可复现模板要以 Cua Driver 已有的确定性--check流程作为 TypeScript UniFFI spike 必须达到的标准Python 与 TypeScript 的 UniFFI 采纳要独立评估。四、目标架构与公开表面计划给出了清晰的架构图原样继承Transport-free Rust ToolSpec typed inputs/results | -- live ToolDef and tools/list metadata -- runtime typed input parsing -- structured-result validation -- portable and platform-rich projections -- contract manifest -- optional typed MCP-client generation -- optional UniFFI implementation exports Agent surface: Codex / Claude / other agent ---- MCP stdio ---- native daemon ---- OS APIs Shell automation ---------------- CLI call ----- native daemon ---- OS APIs Imported application SDK surface: Python/TS typed client ----------- MCP stdio ---- native daemon ---- OS APIs or Language binding ---------------- UniFFI ------- Rust daemon client ---- daemon or, after a separate host-runtime design Language binding ---------------- UniFFI ------- embedded Rust engine ---- OS APIs无传输层的规范应放在现有cua-driver-contractcrate 或一个窄范围的兄弟rlib中所有平台 crate 都必须能依赖这些类型而不引入 MCP framing 或公开 SDK 运行时。类型化层必须区分四类东西类型化命令输入typed command input类型化成功structuredContent载荷存在时稳定的类型化拒绝/错误stable typed refusals/errors可包含文本、图像与诊断信息的 MCP content envelope。计划明确警告不能用一刀切的 adapter 假装每个工具结果都是单一可序列化的成功对象Agent 示例必须直接使用现有 Agent SDK 的 MCP 客户端否则会掩盖本计划依赖的关键区分。五、十条必要不变量Required invariantsRust 是 GUI 执行、权限、策略、会话状态与平台集成的唯一所有者Python 与 TypeScript不得重新实现 OS 自动化行为每个已发布的类型化方法都映射到被活跃实现消费的 Rust 输入/结果类型无论绑定决策如何MCP 始终可用实验性、运行时专属工具在有意晋升之前始终可通过通用调用访问传输层绝不能自动重发状态变更型工具调用单次平台实现内的有界重试仅在属于该次调用且保持其语义时允许生成文件必须确定性、所有权限定、原子替换、并在 CI 中做漂移检查平台可用性必须在工具、变体、字段三个粒度上显式声明Capabilities 与风险元数据只能有一个权威声明处混合 MCP 内容只是传输信封类型化结构化结果不得抹掉文本、图像、拒绝、降级结果或诊断信息。对照源码第 9 条在 cua-driver-contract/src/lib.rs 已有实现tool_capabilities(name)通过缓存工具索引tool_index()返回能力令牌避免每次活跃tools/list都重建 schemavalidate_success_output则把每个工具的成功结构化载荷绑定到同一个生成 SDK schema 的 Rust 输出类型上。六、Workstream A0先关闭 PR #2341 的即时奇偶性缺口在大规模重构前先为十个桌面契约增加一个机械化子集-存在性测试subset-and-existence。对每个声明的平台与可移植桌面工具测试必须证明六件事活跃 registry 中存在该工具每个可移植属性都存在于活跃输入 schema 中可移植必填字段在活跃 schema 中仍是必填可移植类型、enum/const 值、边界与闭对象closed-object行为不宽于活跃 schema 允许的范围可移植注解与能力令牌与活跃工具兼容故意引入不兼容字段变更时测试必须失败即测试本身要防呆。实现方式是编写一个小型schema 子集检查器只覆盖十个契约用到的 schema 结构不要声称通用 JSON Schema 蕴含implication遇到不支持的 keyword 要显式失败以免测试默默放行未经证明的情况。A0 验收门槛十个可移植契约在 macOS、Windows、Linux registry 上全部通过契约、平台ToolDef、registry 或 capability map 变更时工作流自动运行PR #2341 的描述如实说明这证明的是可移植输入/元数据兼容性而非完整运行时行为。最终实现2026-07-21 落地版正是如此十个可移植 schema 在 Linux、macOS、Windows 上被作为每个活跃平台 schema 的逻辑子集检查未知 schema keyword 会使蕴含检查器闭失败fail closed。七、Workstream A让 Rust 成为真正的事实来源A1. 建立无传输层规范模型ToolSpecToolSpec模型必须包含规范名称与描述类型化输入类型化成功结构化载荷如适用稳定的拒绝/错误形态注解与风险元数据唯一的能力声明逐平台工具在场信息可移植 vs 富暴露元数据schema 与契约版本。macOS/Windows/Linux 三个平台 crate 向规范 crate 增加依赖依赖方向保持无环、无传输层。一个值得注意的技术决策不要一开始就承诺schemars。先在一个会话输入与一个复杂桌面输入上跑 schema 方言 spike必须能复现现有 required/optional、闭对象、enum/const、可空性、默认值与边界语义且只留有限 override 表面。如果做不到就保留现有 schema builder同时仍让类型化 Rust 输入保持权威。落地结果恰恰是选择了 Schemarscua-driver-contract源码中的输入类型如 inputs.rs 的ClickInput、ScrollInput等与输出类型同时派生serde::Serialize/Deserialize、schemars::JsonSchema与uniffi::Enum见 lib.rs 中的 Platform 枚举Schemars 派生的 Rust 输入与结构化输出类型确定性地生成 checked-in manifest 与 Python/TypeScript 源码。A2. 添加类型化运行时适配层引入一个 adapter职责是把 MCP 参数反序列化为共享类型化输入用该输入调用平台实现在声明了结构化输出时校验/序列化稳定结构化输出保留现有 MCP 文本/图像/诊断信封规范化稳定错误且不抹掉平台诊断。迁移完成的工具其活跃ToolDef必须从 spec 派生平台实现不得再保留第二份 schema 字面量或逐字段ArgsExt解析器。起步对象是四个会话工具——因为它们的活跃元数据已来自规范契约能用最低平台风险验证 adapter 与输出模型。A3. 一次性建模平台在场与富变体模型必须同时覆盖字段级丰富度与工具集分叉可移植桌面坐标 vs 窗口/元素定位平台专属字段与 enum 变体Windows 专属工具如debug_window_infoLinux 专属底层指针原语。关键原则可移植 SDK 输入必须是更丰富类型化声明的派生投影而不是并行手写的 schema。如果单个公开 union 会误导就定义独立的类型化命令如DesktopClickInput与WindowClickInput但路由到同一实现族。A4. 证明一条分叉的垂直切片迁移范围start_session与end_session生命周期与结构化输出get_desktop_state图像 结构化元数据click可移植 vs 富定位 破坏性注解get_window_state窗口聚焦的丰富度至少一个在部分平台缺失的工具以证明在场建模。切片完成的判定条件是所有参与平台实现消费共享输入活跃tools/list元数据由 spec 派生代表性结构化结果通过其声明 schema 校验MCP 信封保留文本与图像生成的 Python/TypeScript 方法通过可执行 fixture 测试。A5 与 A6迁移当前 14 工具 SDK 面再按族扩展切片稳定后迁移 PR #2341 当前生成的全部 14 个方法移除重复 schema 与临时解析兼容别名只留在 dispatch 层且对tools/list与 SDK 隐藏。随后按可独立评审的族迁移稳定工具剩余感知与桌面输入窗口与应用生命周期浏览器录制与回放光标、配置与诊断其余平台专属稳定工具。每个运行时 roster 条目必须分类为稳定类型化 / 实验性仅通用 / 兼容别名 / 内部隐藏文档明确要求不要编码单一全局工具数。八、Workstream B分离 Agent 集成与 SDK 分发Agent 集成直接 MCP/CLI 是基线推荐为每个 Agent 运行时的现有 MCP 客户端配置cua-driver mcp或让面向 shell 的 Agent 使用cua-driver call。此路径不要求生成 Cua 语言客户端并必须维护可运行的 Python Claude Agent SDK 与 TypeScript Codex SDK 示例作为证明。这就是O(1) 的 Agent 协议表面一个 MCP server 可被 N 个 MCP 兼容运行时消费生成客户端为应用增加的是人体工学而不是这些 Agent 的互操作性。仓库中 examples/agent-sdks/README.md 印证了这一结论Codex SDK 不暴露直接的自定义工具回调其 Cua Driver 示例因此走 MCPClaude Agent SDK 则同时示范 native进程内回调与 MCPcua-driver mcp发现完整工具面两条路由且两个脚本都配置一个长生命周期cua-driver mcptransport其首个被接纳的状态调用创建隐式会话后续匿名调用复用transport 关闭执行与显式end_session相同的清理。SDK 选项 1薄生成式 MCP 客户端继续生成 Python/TypeScript 类型与方法小原生传输直接讲 MCP stdio。它保留daemon 的权限身份与主线程所有权进程与崩溃隔离当前通用tools/list/tools/call逃生舱无需额外客户端cdylib的小语言包Cua Driver 已可复现的 TypeScript 生成/检查流水线。剩余手写语言代码只是几个小传输、结果与 facade 模块。这是一个类型化远程客户端 SDK不是原生实现绑定要对照实际应用 SDK 需求来衡量它。SDK 选项 2UniFFI 封装 Rust daemon 客户端——有门的 spike构建一个平台无关的 Rust 客户端负责 MCP framing 与结果规范化同时仍启动或连接原生 driver daemon只通过 UniFFI 导出垂直切片 API。运行两个独立实验Python 走官方 UniFFI 支持Node TypeScript 走uniffi-bindgen-react-nativeubjs/node。TypeScript 实验必须从绿地可复现性假设出发而非 Fleet 的手工产物必须补齐精确固定的生成器与运行时版本、仓库内生成命令、确定性自有输出与--check模式、lockfile 与可发布包定义、从 Cargo 编译器产物解析宿主cdylib、以及每个受支持平台/架构的隔离包测试。本次 spike 不做浏览器/WASM 打包。该选项的目的是在 Rust 里实现一次应用客户端行为分发到 N 个运行时。文档强调仅仅把 JSON-RPC framing 移进 Rust 是不够的spike 必须识别出它拥有的共享生命周期、规范化、策略或 server 组合行为。SDK 选项 3UniFFI 嵌入式/server 实现——独立提案这是想创建或嵌入 Cua server 的应用开发者的路径不是回退传输变更。独立提案必须先消除或显式托管进程级会话与元素令牌状态单 registry 假设与并发会话清理隐患macOS AppKit 主线程所有权与权限身份Windows 交互会话、UIAccess、前台与 overlay 行为Linux 合成器、X11/Wayland 与会话总线集成宿主崩溃、运行时与取消耦合。B1测量 SDK 候选对选项 1 与每个语言专属的选项 2 spike记录生成与手写维护的源码行数按平台/架构的 wheel/npm 产物大小冷启动、首次调用与稳态只读调用延迟Python 同步/异步行为与 TypeScript 异步行为错误、拒绝、图像与结构化结果保真度通用运行时专属工具访问安装与原生加载器失败模式发布矩阵与 CI 时长变化当前超时/截止时间行为不暗示工具取消。B2按语言拆分的 SDK 决策门Python 与 TypeScript独立决策——UniFFI 可以 Python 通过而 TypeScript 不通过。仅当满足以下全部条件才为某语言采纳选项 2实质上减少了维护的 SDK 行为生成输出可复现且仓库内做漂移检查所有生成器/运行时依赖固定版本安装、启动、通用访问与错误保真度不回归完整受支持产物矩阵通过MCP 仍作为公开边界可用。对 TypeScript 而言无法提供固定版本、确定性的生成与 CI 检查将自动否决无论运行时基准结果如何。否则保留选项 1。无论该决策如何直接 MCP/CLI 始终是推荐的 Agent 集成且 source-of-truth 工作本身完整而有价值。九、Workstream D取消与超时语义现状是取消目前不是运行时能力——dispatch 直接 await 工具serve 层截止时间不会取消正在运行的动作各工具自带其有界重试/轮询行为。计划明确不要让 A0 或初始类型化迁移阻塞在发明取消机制上。在声称取消奇偶性或采纳 UniFFI 传输之前必须做一次显式决策实现调用方取消把 token/deadline 穿过Tooltrait 与类型化 adapter定义安全中断点与动作完成语义或文档化尽力而为的客户端截止时间停止等待但不取消飞行中的工具。无论哪种传输层都绝不能自动重发模糊的状态变更请求测试必须区分传输重发、调用方取消与单次工具调用内的有界重试。十、验证计划、CI 与发布接线测试矩阵契约与源码测试A0 全 10 契约子集/存在性奇偶每个生成稳定方法精确映射一个 Rust spec每个迁移平台工具消费其共享输入类型迁移工具无第二份ToolDefschema 或ArgsExt解析器capabilities 单一声明处逐平台在场与可移植投影机械化派生生成 manifest 与 SDK 输出确定性且无漂移。运行时行为测试最小有效输入与 MCP 走同一类型化 adapter非法类型、缺字段、未知字段、边界与 enum 产生稳定错误代表性结构化结果通过成功 schema文本/图像/拒绝/验证元数据/降级结果/平台诊断原样保留兼容别名调用规范实现但保持隐藏deadline/取消测试只断言 Workstream D 实际实现的语义。平台测试macOS/Windows/Linux 编译并运行 registry/schema 奇偶测试活跃 roster 证据来自确切源码修订fixture 支撑的调用覆盖会话生命周期、桌面感知、指针、键盘与窗口状态不触发不受控 CI 动作平台专属工具/字段只出现在声明处会话捕获范围auto、window、desktop在通用调用与每个生成绑定选项上执行相同策略。包测试构建隔离 Python wheel 与 npm tarball安装进空消费者且无仓库相对 import验证确切原生产物来源与加载路径用同一套 MCP fixture 套件跑每个候选断言公开类名并拒绝过时Client导出断言包内容无过时生成/平台产物。CI 触发与任务工作流必须在规范 crate 与生成 manifest、平台ToolDef/registry/迁移实现、共享结果/内容信封与能力声明、生成器与所有权清单、Python/TypeScript/原生产物/打包代码变更时触发。必需任务Rust 格式化与契约/单元测试三个平台 registry 的 A0 子集/存在性检查迁移工具的类型化运行时与结构化输出测试确定性生成检查模式Python 同步/异步测试与隔离 wheel 消费TypeScript typecheck/测试与隔离 npm 消费UniFFI 生成/产物任务仅在 spike 或已采纳绑定存在时运行。比较期间不发布任一绑定选项。十一、交付序列与完成标准交付序列每步独立可评审test(cua-driver): prove portable desktop contracts match live schemasrefactor(cua-driver): collapse tool capability ownershiprefactor(cua-driver): introduce transport-free typed tool specsrefactor(cua-driver): route session tools through typed runtime adapterrefactor(cua-driver): migrate divergent desktop vertical slicerefactor(cua-driver): migrate current portable desktop SDK toolstest(cua-driver): spike UniFFI Python Rust daemon clienttest(cua-driver): evaluate reproducible UniFFI Node bindings决策提交移除每个被否决的 spike 或采纳其生产接线后续 PR迁移稳定工具族完成标准PR #2341 奇偶性缺口关闭每个可移植契约被证明存在于各声明平台 schema 且被接受CI 对每次相关契约/运行时变更重跑该证明PR 描述区分子集兼容性与行为奇偶性。当前 SDK 的类型化 Rust source-of-truth 完成全部 14 个生成方法使用被活跃实现消费的 Rust 输入/结果迁移工具无重复 schema 或临时字段解析活跃元数据与代表性结构化输出通过奇偶测试capabilities 单一所有者三个 registry 通过声明支持检查改动一个 Rust 字段会导致每个消费者编译失败或确定性生成 diff。UniFFI 评估完成目标产物明确类型化 daemon 客户端或嵌入式/server SDK直接 Agent MCP 示例独立于每个生成客户端薄类型化客户端与各语言 UniFFI 原型对选定 SDK 目标通过等价行为与产物测试记录测量与平台矩阵Python 与 TypeScript 决策独立文档化任何被采纳的 TypeScript 流水线固定、可复现、CI 检查所有被否决 spike 代码被移除。更广类型化 SDK 覆盖完成每个公开运行时工具要么是带显式平台支持的类型化工具要么被有意分类为仅通用任何受支持 OS 上无未分类tools/list条目。十二、主要风险与缓解风险缓解可移植声明在重构完成前漂移先落地 A0 并在平台/运行时变更时触发它派生 schema 方言与现有契约不同用方言复现 spike 给schemars设门必要时保留有界显式 builder平台丰富度造成不可用的公开 union从单一 spec 族建模独立类型化命令与显式逐平台在场混合 MCP 结果无法适配单一类型化输出只类型化结构化载荷与稳定错误保留内容信封迁移范围扩到大型平台文件从会话工具起步证明一条分叉切片再按族迁移TypeScript UniFFI 继承不成熟工具链视为绿地固定一切要求确定性生成与 CI 检查原生客户端库使分发复杂化测量完整矩阵若无实质性收益则保留薄 MCP声称了取消但未实现完成 Workstream D 或文档化非取消的截止时间语义直接嵌入破坏权限或全局状态假设留在计划之外要求独立的 OS 专属证明非目标在 Python/TypeScript 中重实现 GUI 动作移除 MCP server 或 CLI比较期间发布实验包承诺通过 WASM 做浏览器本地桌面自动化作为 SDK 生成工作的一部分直接嵌入 GUI 引擎在类型化基础与决策门稳定前迁移每个运行时工具。十三、最终实现结果与绑定决策2026-07-21 落地版计划文档末尾记录了已实现的最终状态——这是本文最重要的落点实现保留了 MCP/CLI 作为公开 Agent 边界并让类型化 Rust 成为当前 14 工具类型化客户端 SDK 面的事实来源。Schemars 派生的 Rust 输入与结构化输出类型确定性地生成 checked-in manifest 与 Python/TypeScript 源码四个会话工具直接消费这些类型各 OS 桌面分支在动作前反序列化共享可移植投影而其更丰富的窗口/元素路径仍对通用 MCP 调用者可用SDK 路径的成功结构化载荷在活跃 registry 中通过共享 Rust 输出类型反序列化MCP content envelope图像、文本、诊断、错误保持不变十个可移植 schema 在 Linux/macOS/Windows 上被检查为各活跃平台 schema 的逻辑子集未知 schema keyword 使蕴含检查器闭失败全部 14 个工具的能力令牌从契约解析遗留运行时 capability map 现在只覆盖非 SDK 工具。实测的类型化 MCP 客户端基线版本 0.10.0包发布前候选维护源码生成源码通用包Python MCP SDK676 行331 行10,666 字节纯 Python wheelTypeScript MCP SDK278 行275 行4,923 字节 npm tarball解包 19,506 字节两个客户端都保留通用call_tool访问与完整 MCP 内容/结果信封其可执行 fixture 套件覆盖初始化、类型化调用、错误、图像与通用运行时专属调用。UniFFI 仓库 spikeFleet 先例 c2ba0b5e94d0f2c06d0c7efb0913803ca0a616afFleet 证明官方 UniFFI Python 绑定可以生成、漂移检查并对宿主原生 cdylib 执行Fleet 也证明 Node 与浏览器 TypeScript 生成通过uniffi-bindgen-react-native在技术上可行不只是 WASMchecked-in Fleet TypeScript 根约 4,777 行生成代码220 KiB依赖ubjs/core、ubjs/node与同置原生 cdylib且不在 Fleet 固定的四语言生成/检查脚本内可运行示例把这些运行时/构建依赖声明为latestFleet Python 生成根约 5,675 行228 KiB对应更大 API这些源码尺寸是工具链证据不是同口径 API 规模基准。当前 PR 的包决策Python本 PR 保留类型化 MCP 客户端。UniFFI 本身通过了可行性与可复现性门槛但 Cua Driver 还没有一个含实质应用行为的共享 Rust daemon 客户端。在当前传输上做 facade等于给一个 10.4 KiB 通用 wheel 增加逐平台、逐架构 cdylib 与原生加载器失败模式而它最终仍要跟现有 daemon 说话。TypeScript本 PR 保留类型化 MCP 客户端。当前先例未通过计划的自动采纳门槛生成在固定漂移检查脚本之外、运行时包未固定版本、消费者必须自行定位宿主原生库。技术可行性尚未构成可复现的 npm 发布流水线。这一包决策不否决 UniFFI 嵌入式/server SDK也不声称生成客户端提升了 MCP 互操作性——MCP 兼容 Agent 应直接连接Agent 示例已示范。后续 SDK 提案必须首先决定其消费者需要的是共享 Rust daemon 客户端还是嵌入式/server 实现再针对该目标评估 UniFFI。所有被否决的 UniFFI spike 代码均已移除冷启动与稳态对比刻意不做声明——两个原生候选都没通过证明值得制作发布矩阵原型的打包/可复现性预门槛。文档给出的再评估条件是Python 在出现可复用 Rust daemon 客户端或受支持嵌入式宿主时重新考虑TypeScript 在仓库落地固定版本生成、确定性 CI 检查与原生包加载后重新考虑。十四、给读者的可操作要点Agent 集成永远走cua-driver mcp/cua-driver call参考 examples/agent-sdks/README.md 中 Claude/Codex 的两种路由配置CUA_DRIVER_BIN环境变量、隐式会话生命周期、传输关闭清理应用导入 SDKPythoncua_driver、TypeScripttrycua/cua-driver当前为 Rust 后端 UniFFI 绑定公开类是CuaDrivercreate()进程内执行 /connect()走共享 Rust socket 客户端另有通用call_tool逃生舱验证契约与生成物的命令集中在 contract/README.mdcargo run -p cua-driver-contract --bin cua-contract-gen -- all、all --check、cargo test -p cua-driver-core --test contract_parity以及portable_desktop_contracts_are_accepted_by_active_backend这一 A0 奇偶测试学习判据任何新的多语言 SDK 方案都要以确定性生成、固定依赖、仓库内漂移检查、全平台产物矩阵、保留 MCP 公开边界为采纳门槛——这正是本文档以及配套的 action-result-contract.md、native-window-sdk-migration.md沉淀下的工程纪律。【免费下载链接】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），仅供参考
Cua Driver SDK 的 Rust Source-of-Truth 架构与 UniFFI 评估决策：以单一 Rust 契约消除多语言绑定漂移
Cua Driver SDK 的 Rust Source-of-Truth 架构与 UniFFI 评估决策以单一 Rust 契约消除多语言绑定漂移【免费下载链接】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/cua 仓库中 Cua Driver 关于SDK 绑定架构的核心决策记录sdk-rust-source-of-truth-and-uniffi-evaluation-plan.md。它回答了三个环环相扣的问题为什么类型化 Rust 契约contract必须成为 Python/TypeScript SDK 的唯一事实来源source of truth、为什么 Agent 集成必须保持 MCP/CLI 而非依赖生成客户端、以及UniFFI 绑定在什么条件下才值得被采纳。读完本文你将掌握该项目的工具契约分层模型、schema 子集校验subset-and-existence的验证思路、可复现代码生成的 CI 门槛以及最终Python/TypeScript 均保留 typed MCP 客户端这一落地方案的完整证据链。一、先分清两个产品边界Agent 集成与导入型 SDKCua Driver 此前把两个不同的问题混为一谈而该计划的起点就是将它们拆开。配套文档 why-cua-driver-uses-mcp-instead-of-uniffi.md 给出了精确的产品区分表面Surface消费者公开形态运行时可移植性由谁提供Cua 作为 Agent 的 MCP/CLICodex、Claude Code、其他 Agent、Shellcua-driver mcp与cua-driver callMCP 与可执行协议本身已跨运行时可用Cua 作为导入型 SDKPython、TypeScript、Swift、Kotlin 等应用cua_driver或trycua/cua-driverPython/Node 通过 UniFFI 绑定调用共享的 Rust daemon-client 实现这两个边界的本质区别在于MCP 回答的是Agent 或进程如何跨越服务边界调用一个工具——MCP 已经定义了工具发现、调用、结果与错误协议一个 Python Agent 和一个 TypeScript Agent 可以消费同一个 MCP server无需 Cua 为它们各自生成协议客户端。UniFFI 回答的是多种语言的应用程序代码如何调用同一个 Rust 库实现——它解决的是一份实现分发到 N 个运行时的问题而不是跨进程协议问题。因此MCP 与 UniFFI 是正交的它们解决不同边界上的问题并非互相竞争的协议选择。这也是全文反复出现的一条主线MCP 永远是 Agent 边界UniFFI 只是导入型 SDK 的候选分发方式。二、核心决策Rust 作为事实来源MCP/CLI 作为 Agent 基线计划文档给出了明确的执行决策Executive decision继续推进 Rust source-of-truth 工作同时把 Agent 边界与导入型 SDK 边界分离。MCP/CLI 是基线 Agent 架构UniFFI 仍是分发 Rust SDK/server 实现的候选。推荐的执行序列共 7 步立即证明 PR #2341 的十个可移植桌面契约是每个活跃平台 schema 的有效子集建立一个无传输层transport-free的 Rust 规范 crate成为类型化输入、结构化输出、元数据、能力capabilities、平台在场信息platform presence与可移植投影的唯一所有者增量地把活跃平台实现迁移到这些共享类型上先从四个已是规范形态的会话工具开始再迁移一个真正分叉的桌面切片保持 MCP 与 CLI 作为规范的 Agent 集成方式——MCP 兼容的 Agent不需要生成的 Cua 客户端用 Python Claude Agent SDK 与 TypeScript Codex SDK 示例证明这一点把生成的 Python/TypeScript 包保留为面向应用代码的类型化 MCP 客户端 SDK但不声称它们增加了运行时可移植性为想要共享 Rust 实现的消费者尤其是 server-hosting 或嵌入式 SDK 消费者运行一次有时间盒、按语言拆分的 UniFFI spike把 Python 当作成熟目标、TypeScript 当作独立第三方工具链评估只有当某门语言的 UniFFI 方案可复现、集中了有意义的 Rust 行为、且通过下述打包与运行时门槛时才为它采纳 UniFFI。一个重要边界被明确排除在当前工作之外直接把 GUI 引擎嵌入宿主进程不属于本次客户端生成工作。现有运行时假设共享 daemon、进程级全局状态、OS 专属的主线程与权限行为宿主进程库无法安全继承这些假设除非另行设计。因此UniFFI 封装共享 Rust daemon 客户端与UniFFI 嵌入式/server SDK是两个不同的候选方案。三、被确认的现状Confirmed current state3.1 PR #2341 的契约面cua-driver-contract声明了14 个类型化工具4 个会话生命周期工具 10 个可移植桌面循环工具manifest、Python 参数类/方法、TypeScript 接口/方法都由该 Rust 契约 crate 生成Python 与 TypeScript SDK 通过 stdio 与cua-driver mcp通信两个 SDK 都保留了通用调用与tools/list访问供运行时发现与平台专属工具使用生成文件具备**所有权清单ownership inventory**与真实的--check漂移检测模式语言包的公开类Python 为CuaDriver与AsyncCuaDriverTypeScript 为CuaDriver。对照 contract/README.md当前生成 manifest 位于 contract/manifest.json契约源码位于 cua-driver-contract/src/lib.rs其 crate 文档明确写道本 crate 刻意不包含任何传输层或平台实现……原生 driver 仍是唯一的执行引擎本包拥有类型化输入/结果以及版本化声明供活跃运行时使用并用于生成实验性客户端 SDK。3.2 今天的奇偶性parity到底证明到了哪一步现状盘点非常诚实它区分了元数据奇偶性与行为/输出奇偶性四个会话工具通过ToolDef::from_contract从规范契约构建活跃ToolDef元数据但调用逻辑仍是手写的——这只能证明元数据一致不能证明行为或输出一致十个桌面契约是单独编写的portable_subset声明平台 crate并不消费这些输入类型而是各自维护更丰富的ToolDefschema 与逐字段的ArgsExt解析当前没有任何测试证明每个可移植输入 schema 被对应的活跃平台 schema 接受Capabilities 存在两处声明运行时 capability map 与每个ToolContract。现有测试只比较二者并未消除重复所有权。3.3 平台名单与运行时形态按注册统计各平台工具数约为macOS48 个工具Windows49 个工具Linux52 个工具。文档特别强调这些数字必须在各 OS 上用真实的tools/list核实后才能作为发布证据且不能固化为全局断言——各平台名单有意不同且在演进例如 Windows 注册了debug_window_info而 Linux 注册了四个额外的底层指针原语。运行时约束是传输决策的核心daemon 通过一个共享 registry 与工具状态服务并发连接核心会话钩子、activity、元素令牌等设施使用进程级全局单例在 macOS 上 AppKit 表面要求主线程权限身份与可执行文件绑定。这些约束直接决定了为什么不能直接嵌入引擎。3.4 Fleet 项目对 UniFFI 的证明力与不证明力同仓库的 fleet 项目为 UniFFI 提供了强先例它对 Python、Kotlin、Swift、Ruby 等官方 UniFFI 目标有 checked-in 生成器使用固定的 Rust 依赖并支持重新生成检查generate-sdk-bindings.sh。Fleet 还包含生成的 TypeScript 示例Node N-API 路径使用uniffi-bindgen-react-native、ubjs/core、ubjs/node加载原生cdylib与浏览器/WASM 路径。但该计划的措辞非常谨慎这些 TypeScript 产物证明的是可行性不是生产级生成流水线。在被检视的树中TypeScript 不在 Fleet 主生成/检查脚本内React Native 生成器未在 Rust workspace 中固定版本示例ubjs/*依赖使用latest浏览器 WASM 胶水依赖未 checked-in 的配置与生成。因此得出的三条结论是不要把 Fleet 的 TypeScript 路径描述为可复现模板要以 Cua Driver 已有的确定性--check流程作为 TypeScript UniFFI spike 必须达到的标准Python 与 TypeScript 的 UniFFI 采纳要独立评估。四、目标架构与公开表面计划给出了清晰的架构图原样继承Transport-free Rust ToolSpec typed inputs/results | -- live ToolDef and tools/list metadata -- runtime typed input parsing -- structured-result validation -- portable and platform-rich projections -- contract manifest -- optional typed MCP-client generation -- optional UniFFI implementation exports Agent surface: Codex / Claude / other agent ---- MCP stdio ---- native daemon ---- OS APIs Shell automation ---------------- CLI call ----- native daemon ---- OS APIs Imported application SDK surface: Python/TS typed client ----------- MCP stdio ---- native daemon ---- OS APIs or Language binding ---------------- UniFFI ------- Rust daemon client ---- daemon or, after a separate host-runtime design Language binding ---------------- UniFFI ------- embedded Rust engine ---- OS APIs无传输层的规范应放在现有cua-driver-contractcrate 或一个窄范围的兄弟rlib中所有平台 crate 都必须能依赖这些类型而不引入 MCP framing 或公开 SDK 运行时。类型化层必须区分四类东西类型化命令输入typed command input类型化成功structuredContent载荷存在时稳定的类型化拒绝/错误stable typed refusals/errors可包含文本、图像与诊断信息的 MCP content envelope。计划明确警告不能用一刀切的 adapter 假装每个工具结果都是单一可序列化的成功对象Agent 示例必须直接使用现有 Agent SDK 的 MCP 客户端否则会掩盖本计划依赖的关键区分。五、十条必要不变量Required invariantsRust 是 GUI 执行、权限、策略、会话状态与平台集成的唯一所有者Python 与 TypeScript不得重新实现 OS 自动化行为每个已发布的类型化方法都映射到被活跃实现消费的 Rust 输入/结果类型无论绑定决策如何MCP 始终可用实验性、运行时专属工具在有意晋升之前始终可通过通用调用访问传输层绝不能自动重发状态变更型工具调用单次平台实现内的有界重试仅在属于该次调用且保持其语义时允许生成文件必须确定性、所有权限定、原子替换、并在 CI 中做漂移检查平台可用性必须在工具、变体、字段三个粒度上显式声明Capabilities 与风险元数据只能有一个权威声明处混合 MCP 内容只是传输信封类型化结构化结果不得抹掉文本、图像、拒绝、降级结果或诊断信息。对照源码第 9 条在 cua-driver-contract/src/lib.rs 已有实现tool_capabilities(name)通过缓存工具索引tool_index()返回能力令牌避免每次活跃tools/list都重建 schemavalidate_success_output则把每个工具的成功结构化载荷绑定到同一个生成 SDK schema 的 Rust 输出类型上。六、Workstream A0先关闭 PR #2341 的即时奇偶性缺口在大规模重构前先为十个桌面契约增加一个机械化子集-存在性测试subset-and-existence。对每个声明的平台与可移植桌面工具测试必须证明六件事活跃 registry 中存在该工具每个可移植属性都存在于活跃输入 schema 中可移植必填字段在活跃 schema 中仍是必填可移植类型、enum/const 值、边界与闭对象closed-object行为不宽于活跃 schema 允许的范围可移植注解与能力令牌与活跃工具兼容故意引入不兼容字段变更时测试必须失败即测试本身要防呆。实现方式是编写一个小型schema 子集检查器只覆盖十个契约用到的 schema 结构不要声称通用 JSON Schema 蕴含implication遇到不支持的 keyword 要显式失败以免测试默默放行未经证明的情况。A0 验收门槛十个可移植契约在 macOS、Windows、Linux registry 上全部通过契约、平台ToolDef、registry 或 capability map 变更时工作流自动运行PR #2341 的描述如实说明这证明的是可移植输入/元数据兼容性而非完整运行时行为。最终实现2026-07-21 落地版正是如此十个可移植 schema 在 Linux、macOS、Windows 上被作为每个活跃平台 schema 的逻辑子集检查未知 schema keyword 会使蕴含检查器闭失败fail closed。七、Workstream A让 Rust 成为真正的事实来源A1. 建立无传输层规范模型ToolSpecToolSpec模型必须包含规范名称与描述类型化输入类型化成功结构化载荷如适用稳定的拒绝/错误形态注解与风险元数据唯一的能力声明逐平台工具在场信息可移植 vs 富暴露元数据schema 与契约版本。macOS/Windows/Linux 三个平台 crate 向规范 crate 增加依赖依赖方向保持无环、无传输层。一个值得注意的技术决策不要一开始就承诺schemars。先在一个会话输入与一个复杂桌面输入上跑 schema 方言 spike必须能复现现有 required/optional、闭对象、enum/const、可空性、默认值与边界语义且只留有限 override 表面。如果做不到就保留现有 schema builder同时仍让类型化 Rust 输入保持权威。落地结果恰恰是选择了 Schemarscua-driver-contract源码中的输入类型如 inputs.rs 的ClickInput、ScrollInput等与输出类型同时派生serde::Serialize/Deserialize、schemars::JsonSchema与uniffi::Enum见 lib.rs 中的 Platform 枚举Schemars 派生的 Rust 输入与结构化输出类型确定性地生成 checked-in manifest 与 Python/TypeScript 源码。A2. 添加类型化运行时适配层引入一个 adapter职责是把 MCP 参数反序列化为共享类型化输入用该输入调用平台实现在声明了结构化输出时校验/序列化稳定结构化输出保留现有 MCP 文本/图像/诊断信封规范化稳定错误且不抹掉平台诊断。迁移完成的工具其活跃ToolDef必须从 spec 派生平台实现不得再保留第二份 schema 字面量或逐字段ArgsExt解析器。起步对象是四个会话工具——因为它们的活跃元数据已来自规范契约能用最低平台风险验证 adapter 与输出模型。A3. 一次性建模平台在场与富变体模型必须同时覆盖字段级丰富度与工具集分叉可移植桌面坐标 vs 窗口/元素定位平台专属字段与 enum 变体Windows 专属工具如debug_window_infoLinux 专属底层指针原语。关键原则可移植 SDK 输入必须是更丰富类型化声明的派生投影而不是并行手写的 schema。如果单个公开 union 会误导就定义独立的类型化命令如DesktopClickInput与WindowClickInput但路由到同一实现族。A4. 证明一条分叉的垂直切片迁移范围start_session与end_session生命周期与结构化输出get_desktop_state图像 结构化元数据click可移植 vs 富定位 破坏性注解get_window_state窗口聚焦的丰富度至少一个在部分平台缺失的工具以证明在场建模。切片完成的判定条件是所有参与平台实现消费共享输入活跃tools/list元数据由 spec 派生代表性结构化结果通过其声明 schema 校验MCP 信封保留文本与图像生成的 Python/TypeScript 方法通过可执行 fixture 测试。A5 与 A6迁移当前 14 工具 SDK 面再按族扩展切片稳定后迁移 PR #2341 当前生成的全部 14 个方法移除重复 schema 与临时解析兼容别名只留在 dispatch 层且对tools/list与 SDK 隐藏。随后按可独立评审的族迁移稳定工具剩余感知与桌面输入窗口与应用生命周期浏览器录制与回放光标、配置与诊断其余平台专属稳定工具。每个运行时 roster 条目必须分类为稳定类型化 / 实验性仅通用 / 兼容别名 / 内部隐藏文档明确要求不要编码单一全局工具数。八、Workstream B分离 Agent 集成与 SDK 分发Agent 集成直接 MCP/CLI 是基线推荐为每个 Agent 运行时的现有 MCP 客户端配置cua-driver mcp或让面向 shell 的 Agent 使用cua-driver call。此路径不要求生成 Cua 语言客户端并必须维护可运行的 Python Claude Agent SDK 与 TypeScript Codex SDK 示例作为证明。这就是O(1) 的 Agent 协议表面一个 MCP server 可被 N 个 MCP 兼容运行时消费生成客户端为应用增加的是人体工学而不是这些 Agent 的互操作性。仓库中 examples/agent-sdks/README.md 印证了这一结论Codex SDK 不暴露直接的自定义工具回调其 Cua Driver 示例因此走 MCPClaude Agent SDK 则同时示范 native进程内回调与 MCPcua-driver mcp发现完整工具面两条路由且两个脚本都配置一个长生命周期cua-driver mcptransport其首个被接纳的状态调用创建隐式会话后续匿名调用复用transport 关闭执行与显式end_session相同的清理。SDK 选项 1薄生成式 MCP 客户端继续生成 Python/TypeScript 类型与方法小原生传输直接讲 MCP stdio。它保留daemon 的权限身份与主线程所有权进程与崩溃隔离当前通用tools/list/tools/call逃生舱无需额外客户端cdylib的小语言包Cua Driver 已可复现的 TypeScript 生成/检查流水线。剩余手写语言代码只是几个小传输、结果与 facade 模块。这是一个类型化远程客户端 SDK不是原生实现绑定要对照实际应用 SDK 需求来衡量它。SDK 选项 2UniFFI 封装 Rust daemon 客户端——有门的 spike构建一个平台无关的 Rust 客户端负责 MCP framing 与结果规范化同时仍启动或连接原生 driver daemon只通过 UniFFI 导出垂直切片 API。运行两个独立实验Python 走官方 UniFFI 支持Node TypeScript 走uniffi-bindgen-react-nativeubjs/node。TypeScript 实验必须从绿地可复现性假设出发而非 Fleet 的手工产物必须补齐精确固定的生成器与运行时版本、仓库内生成命令、确定性自有输出与--check模式、lockfile 与可发布包定义、从 Cargo 编译器产物解析宿主cdylib、以及每个受支持平台/架构的隔离包测试。本次 spike 不做浏览器/WASM 打包。该选项的目的是在 Rust 里实现一次应用客户端行为分发到 N 个运行时。文档强调仅仅把 JSON-RPC framing 移进 Rust 是不够的spike 必须识别出它拥有的共享生命周期、规范化、策略或 server 组合行为。SDK 选项 3UniFFI 嵌入式/server 实现——独立提案这是想创建或嵌入 Cua server 的应用开发者的路径不是回退传输变更。独立提案必须先消除或显式托管进程级会话与元素令牌状态单 registry 假设与并发会话清理隐患macOS AppKit 主线程所有权与权限身份Windows 交互会话、UIAccess、前台与 overlay 行为Linux 合成器、X11/Wayland 与会话总线集成宿主崩溃、运行时与取消耦合。B1测量 SDK 候选对选项 1 与每个语言专属的选项 2 spike记录生成与手写维护的源码行数按平台/架构的 wheel/npm 产物大小冷启动、首次调用与稳态只读调用延迟Python 同步/异步行为与 TypeScript 异步行为错误、拒绝、图像与结构化结果保真度通用运行时专属工具访问安装与原生加载器失败模式发布矩阵与 CI 时长变化当前超时/截止时间行为不暗示工具取消。B2按语言拆分的 SDK 决策门Python 与 TypeScript独立决策——UniFFI 可以 Python 通过而 TypeScript 不通过。仅当满足以下全部条件才为某语言采纳选项 2实质上减少了维护的 SDK 行为生成输出可复现且仓库内做漂移检查所有生成器/运行时依赖固定版本安装、启动、通用访问与错误保真度不回归完整受支持产物矩阵通过MCP 仍作为公开边界可用。对 TypeScript 而言无法提供固定版本、确定性的生成与 CI 检查将自动否决无论运行时基准结果如何。否则保留选项 1。无论该决策如何直接 MCP/CLI 始终是推荐的 Agent 集成且 source-of-truth 工作本身完整而有价值。九、Workstream D取消与超时语义现状是取消目前不是运行时能力——dispatch 直接 await 工具serve 层截止时间不会取消正在运行的动作各工具自带其有界重试/轮询行为。计划明确不要让 A0 或初始类型化迁移阻塞在发明取消机制上。在声称取消奇偶性或采纳 UniFFI 传输之前必须做一次显式决策实现调用方取消把 token/deadline 穿过Tooltrait 与类型化 adapter定义安全中断点与动作完成语义或文档化尽力而为的客户端截止时间停止等待但不取消飞行中的工具。无论哪种传输层都绝不能自动重发模糊的状态变更请求测试必须区分传输重发、调用方取消与单次工具调用内的有界重试。十、验证计划、CI 与发布接线测试矩阵契约与源码测试A0 全 10 契约子集/存在性奇偶每个生成稳定方法精确映射一个 Rust spec每个迁移平台工具消费其共享输入类型迁移工具无第二份ToolDefschema 或ArgsExt解析器capabilities 单一声明处逐平台在场与可移植投影机械化派生生成 manifest 与 SDK 输出确定性且无漂移。运行时行为测试最小有效输入与 MCP 走同一类型化 adapter非法类型、缺字段、未知字段、边界与 enum 产生稳定错误代表性结构化结果通过成功 schema文本/图像/拒绝/验证元数据/降级结果/平台诊断原样保留兼容别名调用规范实现但保持隐藏deadline/取消测试只断言 Workstream D 实际实现的语义。平台测试macOS/Windows/Linux 编译并运行 registry/schema 奇偶测试活跃 roster 证据来自确切源码修订fixture 支撑的调用覆盖会话生命周期、桌面感知、指针、键盘与窗口状态不触发不受控 CI 动作平台专属工具/字段只出现在声明处会话捕获范围auto、window、desktop在通用调用与每个生成绑定选项上执行相同策略。包测试构建隔离 Python wheel 与 npm tarball安装进空消费者且无仓库相对 import验证确切原生产物来源与加载路径用同一套 MCP fixture 套件跑每个候选断言公开类名并拒绝过时Client导出断言包内容无过时生成/平台产物。CI 触发与任务工作流必须在规范 crate 与生成 manifest、平台ToolDef/registry/迁移实现、共享结果/内容信封与能力声明、生成器与所有权清单、Python/TypeScript/原生产物/打包代码变更时触发。必需任务Rust 格式化与契约/单元测试三个平台 registry 的 A0 子集/存在性检查迁移工具的类型化运行时与结构化输出测试确定性生成检查模式Python 同步/异步测试与隔离 wheel 消费TypeScript typecheck/测试与隔离 npm 消费UniFFI 生成/产物任务仅在 spike 或已采纳绑定存在时运行。比较期间不发布任一绑定选项。十一、交付序列与完成标准交付序列每步独立可评审test(cua-driver): prove portable desktop contracts match live schemasrefactor(cua-driver): collapse tool capability ownershiprefactor(cua-driver): introduce transport-free typed tool specsrefactor(cua-driver): route session tools through typed runtime adapterrefactor(cua-driver): migrate divergent desktop vertical slicerefactor(cua-driver): migrate current portable desktop SDK toolstest(cua-driver): spike UniFFI Python Rust daemon clienttest(cua-driver): evaluate reproducible UniFFI Node bindings决策提交移除每个被否决的 spike 或采纳其生产接线后续 PR迁移稳定工具族完成标准PR #2341 奇偶性缺口关闭每个可移植契约被证明存在于各声明平台 schema 且被接受CI 对每次相关契约/运行时变更重跑该证明PR 描述区分子集兼容性与行为奇偶性。当前 SDK 的类型化 Rust source-of-truth 完成全部 14 个生成方法使用被活跃实现消费的 Rust 输入/结果迁移工具无重复 schema 或临时字段解析活跃元数据与代表性结构化输出通过奇偶测试capabilities 单一所有者三个 registry 通过声明支持检查改动一个 Rust 字段会导致每个消费者编译失败或确定性生成 diff。UniFFI 评估完成目标产物明确类型化 daemon 客户端或嵌入式/server SDK直接 Agent MCP 示例独立于每个生成客户端薄类型化客户端与各语言 UniFFI 原型对选定 SDK 目标通过等价行为与产物测试记录测量与平台矩阵Python 与 TypeScript 决策独立文档化任何被采纳的 TypeScript 流水线固定、可复现、CI 检查所有被否决 spike 代码被移除。更广类型化 SDK 覆盖完成每个公开运行时工具要么是带显式平台支持的类型化工具要么被有意分类为仅通用任何受支持 OS 上无未分类tools/list条目。十二、主要风险与缓解风险缓解可移植声明在重构完成前漂移先落地 A0 并在平台/运行时变更时触发它派生 schema 方言与现有契约不同用方言复现 spike 给schemars设门必要时保留有界显式 builder平台丰富度造成不可用的公开 union从单一 spec 族建模独立类型化命令与显式逐平台在场混合 MCP 结果无法适配单一类型化输出只类型化结构化载荷与稳定错误保留内容信封迁移范围扩到大型平台文件从会话工具起步证明一条分叉切片再按族迁移TypeScript UniFFI 继承不成熟工具链视为绿地固定一切要求确定性生成与 CI 检查原生客户端库使分发复杂化测量完整矩阵若无实质性收益则保留薄 MCP声称了取消但未实现完成 Workstream D 或文档化非取消的截止时间语义直接嵌入破坏权限或全局状态假设留在计划之外要求独立的 OS 专属证明非目标在 Python/TypeScript 中重实现 GUI 动作移除 MCP server 或 CLI比较期间发布实验包承诺通过 WASM 做浏览器本地桌面自动化作为 SDK 生成工作的一部分直接嵌入 GUI 引擎在类型化基础与决策门稳定前迁移每个运行时工具。十三、最终实现结果与绑定决策2026-07-21 落地版计划文档末尾记录了已实现的最终状态——这是本文最重要的落点实现保留了 MCP/CLI 作为公开 Agent 边界并让类型化 Rust 成为当前 14 工具类型化客户端 SDK 面的事实来源。Schemars 派生的 Rust 输入与结构化输出类型确定性地生成 checked-in manifest 与 Python/TypeScript 源码四个会话工具直接消费这些类型各 OS 桌面分支在动作前反序列化共享可移植投影而其更丰富的窗口/元素路径仍对通用 MCP 调用者可用SDK 路径的成功结构化载荷在活跃 registry 中通过共享 Rust 输出类型反序列化MCP content envelope图像、文本、诊断、错误保持不变十个可移植 schema 在 Linux/macOS/Windows 上被检查为各活跃平台 schema 的逻辑子集未知 schema keyword 使蕴含检查器闭失败全部 14 个工具的能力令牌从契约解析遗留运行时 capability map 现在只覆盖非 SDK 工具。实测的类型化 MCP 客户端基线版本 0.10.0包发布前候选维护源码生成源码通用包Python MCP SDK676 行331 行10,666 字节纯 Python wheelTypeScript MCP SDK278 行275 行4,923 字节 npm tarball解包 19,506 字节两个客户端都保留通用call_tool访问与完整 MCP 内容/结果信封其可执行 fixture 套件覆盖初始化、类型化调用、错误、图像与通用运行时专属调用。UniFFI 仓库 spikeFleet 先例 c2ba0b5e94d0f2c06d0c7efb0913803ca0a616afFleet 证明官方 UniFFI Python 绑定可以生成、漂移检查并对宿主原生 cdylib 执行Fleet 也证明 Node 与浏览器 TypeScript 生成通过uniffi-bindgen-react-native在技术上可行不只是 WASMchecked-in Fleet TypeScript 根约 4,777 行生成代码220 KiB依赖ubjs/core、ubjs/node与同置原生 cdylib且不在 Fleet 固定的四语言生成/检查脚本内可运行示例把这些运行时/构建依赖声明为latestFleet Python 生成根约 5,675 行228 KiB对应更大 API这些源码尺寸是工具链证据不是同口径 API 规模基准。当前 PR 的包决策Python本 PR 保留类型化 MCP 客户端。UniFFI 本身通过了可行性与可复现性门槛但 Cua Driver 还没有一个含实质应用行为的共享 Rust daemon 客户端。在当前传输上做 facade等于给一个 10.4 KiB 通用 wheel 增加逐平台、逐架构 cdylib 与原生加载器失败模式而它最终仍要跟现有 daemon 说话。TypeScript本 PR 保留类型化 MCP 客户端。当前先例未通过计划的自动采纳门槛生成在固定漂移检查脚本之外、运行时包未固定版本、消费者必须自行定位宿主原生库。技术可行性尚未构成可复现的 npm 发布流水线。这一包决策不否决 UniFFI 嵌入式/server SDK也不声称生成客户端提升了 MCP 互操作性——MCP 兼容 Agent 应直接连接Agent 示例已示范。后续 SDK 提案必须首先决定其消费者需要的是共享 Rust daemon 客户端还是嵌入式/server 实现再针对该目标评估 UniFFI。所有被否决的 UniFFI spike 代码均已移除冷启动与稳态对比刻意不做声明——两个原生候选都没通过证明值得制作发布矩阵原型的打包/可复现性预门槛。文档给出的再评估条件是Python 在出现可复用 Rust daemon 客户端或受支持嵌入式宿主时重新考虑TypeScript 在仓库落地固定版本生成、确定性 CI 检查与原生包加载后重新考虑。十四、给读者的可操作要点Agent 集成永远走cua-driver mcp/cua-driver call参考 examples/agent-sdks/README.md 中 Claude/Codex 的两种路由配置CUA_DRIVER_BIN环境变量、隐式会话生命周期、传输关闭清理应用导入 SDKPythoncua_driver、TypeScripttrycua/cua-driver当前为 Rust 后端 UniFFI 绑定公开类是CuaDrivercreate()进程内执行 /connect()走共享 Rust socket 客户端另有通用call_tool逃生舱验证契约与生成物的命令集中在 contract/README.mdcargo run -p cua-driver-contract --bin cua-contract-gen -- all、all --check、cargo test -p cua-driver-core --test contract_parity以及portable_desktop_contracts_are_accepted_by_active_backend这一 A0 奇偶测试学习判据任何新的多语言 SDK 方案都要以确定性生成、固定依赖、仓库内漂移检查、全平台产物矩阵、保留 MCP 公开边界为采纳门槛——这正是本文档以及配套的 action-result-contract.md、native-window-sdk-migration.md沉淀下的工程纪律。【免费下载链接】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），仅供参考