@qwen-code/cua-sdk 原生运行时来源解析：cua_driver_node_runtime.node 的构建、分发与 MPL-2.0 许可合规指南

@qwen-code/cua-sdk 原生运行时来源解析：cua_driver_node_runtime.node 的构建、分发与 MPL-2.0 许可合规指南

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

@qwen-code/cua-sdk是 Qwen Code（cua-driver 仓库）中面向 Node.js 的 Rust 后端驱动 SDK，其核心能力依赖一个随包下载的原生运行时cua_driver_node_runtime.node。本文基于 packages/cua-driver/typescript/NOTICE.md 展开，说明该原生运行时"从哪来、怎么构建、怎么分发、怎么授权"，并结合仓库源码（安装脚本、原生资源解析、构建脚本）给出可核验的实现细节，帮助你在二次开发、合规审计或排障时快速定位依据。读完本文，你将掌握该 SDK 的原生加载机制、构建配方（recipe）与许可证边界。

一、NOTICE 文档说了什么

仓库中@qwen-code/cua-sdk包根目录下的 NOTICE.md 是一份面向下游使用者的"原生运行时声明"，内容可以归纳为三点：

1. 运行时随版本分发：@qwen-code/cua-sdk会从与自身版本号完全对应的 Qwen CUA Driver GitHub Release 下载cua_driver_node_runtime.node和配套的 Cua Driver SDK 库。
2. 运行时是派生构建：cua_driver_node_runtime.node是一个"兼容性构建"（compatibility build），派生自uniffi-bindgen-react-native0.31.0-3 中的 N-API runtime，版权归其贡献者所有，遵循Mozilla Public License 2.0（MPL-2.0）。
3. 源码可追溯：该运行时对应的源码 = 固定锁定（pinned）的开发依赖 +packages/cua-driver/scripts/build-node-runtime.mjs中的确定性变换，二者都在与包版本匹配的 release tag 上可得。

这份 NOTICE 的价值在于：它明确划清了许可证边界——SDK 的 TypeScript 层是 MIT（见 LICENSE.md），而内嵌的原生 N-API 运行时继承上游 MPL-2.0，两者不能混为一谈。任何再分发、修改或静态分析该原生模块的使用者，都需要同时遵守这两套许可。

二、为什么 SDK 需要"原生运行时"

@qwen-code/cua-sdk的包描述是 "Typed CUA Driver SDK and Computer Use API for Node.js"，其底层是 Rust 实现的 Cua Driver（见 package.json）。TypeScript 层通过uniffi生成的绑定与 Rust 库交互，而 JS 与 Rust 之间的桥接需要一个 N-API 运行时：

• cua_driver_node_runtime.node：N-API 运行时模块（即 uniffi N-API runtime 的兼容构建），负责RustBuffer分配/释放、函数派发等底层机制。
• libcua_driver_sdk.dylib/libcua_driver_sdk.so/cua_driver_sdk.dll：Cua Driver SDK 的 Rust 编译产物。

这两个文件必须同时存在且匹配同一版本。源码层的对应关系体现在 src/native-assets.ts 的nativeTarget()：它按platform与arch返回包含archive、library、runtime、companions的目标描述，例如：

• macOS（arm64/x64）：cua-driver-rs-<version>-darwin-universal-binary.tar.gz，库文件为libcua_driver_sdk.dylib；
• Linux（glibc，arm64/x64）：cua-driver-rs-<version>-linux-<arch>-binary.tar.gz，库文件为libcua_driver_sdk.so；
• Windows（arm64/x64）：cua-driver-rs-<version>-windows-<arch>-binary.zip，库文件为cua_driver_sdk.dll，并附带 companion 文件qwen-cua-driver-uia.exe。

其中 Linux 分支会通过process.report.getReport()检查glibcVersionRuntime，缺失时直接抛错——也就是说该 SDK 目前要求 glibc 环境，musl 等非 glibc Linux 不在支持范围（可从 native-assets.ts 的检查逻辑确认）。

三、运行时如何被下载与校验：install-native.mjs 全流程

NOTICE 中"从同版本 GitHub Release 下载"并不是一句口号，而是由包的postinstall钩子真实执行的。包脚本声明为"postinstall": "node scripts/install-native.mjs"（见 package.json），整个流程在 scripts/install-native.mjs 中实现，关键环节如下：

1. 确定 Release 基地址与版本标签

releaseBases()将版本号映射为 release tagcua-driver-rs-v<version>，下载基地址默认是 GitHub Releases 下载根，并支持通过环境变量QWEN_CUA_SDK_RELEASE_BASE_URL覆盖（方便镜像或内网部署）。若显式配置了QWEN_CUA_SDK_NATIVE_DIR，则跳过下载，直接使用该目录下的原生文件。

2. 下载 checksums.txt 并解析

安装器先拉取checksums.txt，用正则^([0-9a-f]{64})\s+\*?(.+)$解析出每个归档文件的 SHA-256 期望值（parseChecksums()）。这一步是供应链校验的前提：归档文件的实际哈希必须与清单一致，否则抛checksum mismatch错误。

3. 流式下载并计算哈希

下载归档时通过Transform流边下载边累计 SHA-256（downloadArchive()），下载完成后与清单比对，防止下载被篡改或损坏。

4. 解压与原子安装

• .tar.gz用tar包解压；.zip则依次尝试tar -xf、tar --force-local，最后回退到 PowerShell 的Expand-Archive（兼容 Windows 环境差异）。
• installFiles()先将文件复制为带.tmp后缀的临时文件，再rename到位，最后写入complete.json元数据标记（含归档名、校验和、来源 URL、版本）——这种"先写临时、再原子改名、以 complete.json 收尾"的做法，保证了安装中断不会留下半成品缓存。

5. Windows UIAccess worker 的额外处理

Windows 目标还包含qwen-cua-driver-uia.execompanion。安装器会将其复制到%ProgramFiles%\Qwen\CuaDriver\<version>\下，并在安装前用 PowerShellGet-AuthenticodeSignature校验其 Authenticode 签名必须为Valid（requireValidAuthenticodeSignature()），已安装的同名文件也会被复检。这是对高权限辅助进程的一道安全防线。

6. 缓存目录策略

缓存根目录由 native-assets.ts 的nativeCacheRoot()决定：

• Windows：%LOCALAPPDATA%\Qwen\cua-sdk；
• 其他平台：$XDG_CACHE_HOME/qwen-code/cua-sdk或默认~/.cache/qwen-code/cua-sdk；
• 均可通过QWEN_CUA_SDK_CACHE_DIR覆盖。

具体缓存路径为<cacheRoot>/<version>/<cacheKey>，例如linux-x86_64、darwin-universal、windows-x86_64。hasCompletedNativePayload()通过"库文件+运行时+companion 齐全且存在 complete.json"来判断缓存是否可用，避免重复下载。

7. 运行时解析顺序

resolveNativeDirectory()的查找顺序是：QWEN_CUA_SDK_NATIVE_DIR显式指定目录 → 包内packages/cua-driver/typescript/.native/<cacheKey>（本地打包场景）→ 用户缓存目录。全部未命中时报错并提示"Reinstall without --ignore-scripts"——这正解释了为什么用npm install --ignore-scripts安装该包后运行会失败。

值得注意：NOTICE 强调下载的是 SDK 库与 Node 运行时"这两个文件"，安装器不会安装 driver 应用程序或 daemon。换句话说，@qwen-code/cua-sdk的 postinstall 是轻量的原生资源获取，不是整套驱动的安装程序。

四、兼容构建是怎么"变"出来的：build-node-runtime.mjs

NOTICE 中"确定性变换"（deterministic transformations）指向 scripts/build-node-runtime.mjs。该脚本以--output <path> [--target <triple>]方式调用，核心思路是：取出被锁定的uniffi-bindgen-react-native@0.31.0-3（见 typescript/package.json 的devDependencies）的 N-API runtime 源码，施加固定补丁后编译，产出cua_driver_node_runtime.node。

1. 版本强校验

脚本读取typescript/package.json中devDependencies["uniffi-bindgen-react-native"]的期望版本，再读取node_modules中该包的实际版本，二者不一致立即报错UBRN source mismatch。这保证了"pin 住源码"这一承诺在构建时是可执行、可验证的。

2. copy 模式 RustBuffer 边界（核心补丁）

脚本顶部注释解释了动机：Electron 20+ 会拒绝外部 ArrayBuffer，而 UBRN 0.31.0-3 默认用零拷贝优化把 RustBuffer 以外部 ArrayBuffer 形式暴露给 JS。由于生成的 SDK 在 lowering/lifting 时本就会复制 RustBuffer 内容，这个兼容构建改为在 N-API 边界使用 JS 拥有的Uint8Array，值语义与所有权都不变，只是去掉零拷贝。具体两个补丁：

• patchRegister()：重写register/mod.rs中的rustbuffer_alloc（改为创建长度非负、由 V8 拥有的 Uint8Array）与rustbuffer_free（copy 模式下 JS 拥有缓冲区，free 变为 no-op）；
• patchCall()：把返回路径从rust_buffer_to_js_uint8array_handoff（零拷贝移交）替换为rust_buffer_to_js_uint8array_copy（复制到 V8 拥有的 Uint8Array 后再释放 Rust 分配）。

补丁用replaceOnce做严格单点替换，任何一个锚点文本发生变化都会抛错，防止上游代码漂移后"静默修补错位置"。

3. 平台相关加固

• Windows 静态 CRT：cargoEnvironment()在构建 Windows MSVC 目标时追加RUSTFLAGS=-C target-feature=+crt-static，原因是上游 N-API runtime 含 C++ 对象，默认动态 CRT 会让干净安装的 Windows 缺少VCRUNTIME140.dll；
• macOS AppKit pump：脚本把 scripts/node-main-run-loop.rs 追加到 runtime 的lib.rs。该#[napi]函数在原生粘贴挂起时由 Node 主线程同步调用CFRunLoopRunInMode，并校验必须在主线程执行（pthread_main_np()），Worker 线程无法服务 AppKit 回调——这是 macOS 原生粘贴等场景可用性的关键细节。

构建产物从target/release下的libuniffi_runtime_napi.{dylib,so,dll}拷贝为cua_driver_node_runtime.node，最终与 SDK 库一起随同版本 Release 分发。仓库内 scripts/node-runtime-NOTICE.md 记录了同一份声明（描述对象为仓库脚本构建路径），两份 NOTICE 互相印证。

五、许可证边界与合规要点

对下游使用者而言，这份 NOTICE 的合规含义可以整理为一张对照表：

需要留意的实践点：

• MPL-2.0 是文件级弱 copyleft 许可：修改或再分发cua_driver_node_runtime.node对应的源码时，需要以 MPL-2.0 提供该文件对应源码的可获取性；而普通业务代码通过 SDK 的公开 API 使用该运行时，不构成对业务代码的传染。仓库的做法是"源码 = 锁定的 devDependency + 确定性变换脚本"，并随 release tag 公布，正是为了满足这一可追溯要求。
• NOTICE 文件本身随包发布：package.json的files数组明确包含NOTICE.md与LICENSE.md，安装@qwen-code/cua-sdk后可在包内直接查阅，无需联网。
• 不改动 NOTICE：再分发包含该原生模块的产物时，应保留这份 NOTICE 及其指向的 MPL-2.0 声明（许可证全文可在 Mozilla 官方 MPL-2.0 页面获取）。

六、源码检出场景下的本地构建与验证

如果你在 cua-driver 仓库源码检出环境中开发，而不是使用 npm 发布包，原生资源的处理路径会不同：

• postinstall脚本检测到源码检出（存在src/native-assets.ts）时会提示改用npm run stage:uniffi来准备本地原生资源（见 install-native.mjs 主入口分支）；
• 包脚本还提供generate:uniffi（重新生成 uniffi 绑定）、generate:uniffi:check（校验绑定与当前代码一致）与stage:uniffi（staging uniffi 库），对应 scripts/generate-uniffi-bindings.mjs 与 scripts/stage-uniffi-library.mjs；
• 想复现cua_driver_node_runtime.node本身，可在安装锁定的uniffi-bindgen-react-native@0.31.0-3后运行node packages/cua-driver/scripts/build-node-runtime.mjs --output <目标路径> [--target <triple>]，脚本会自动校验上游版本并应用第三节所述补丁。

仓库还提供了独立的驱动安装脚本（scripts/README.md 中列出install.sh/install.ps1、install-local.sh等），但它们安装的是qwen-cua-driver可执行程序，与 SDK 包的 postinstall 原生资源获取是两条独立路径，使用时注意区分。

七、常见问题与排查指引

结语

cua_driver_node_runtime.node并不是一个黑盒：它由锁定的uniffi-bindgen-react-native0.31.0-3 N-API runtime 经 build-node-runtime.mjs 的确定性补丁构建而来，经 postinstall 从同版本 Release 下载并通过 SHA-256 清单校验后落地到本地缓存。NOTICE.md 用三句话把"来源—构建配方—许可证"讲得清清楚楚，而仓库源码则把每一句话都落成了可执行、可验证的代码。理解这条链路，无论是对合规审计、镜像部署还是排查原生加载问题，都提供了完整的事实依据。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code