Cua TypeScript SDK 全解core、computer 与 fleet 三包架构、构建与测试工作流【免费下载链接】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本篇基于仓库中的 libs/typescript/README.md 展开系统讲解 Cua 项目 TypeScript 工具库的整体组织、pnpm 工作区配置、trycua/core/trycua/computer/trycua/fleet三个包各自的定位与依赖关系以及从安装依赖、按序构建、运行测试到 lint 与发布的完整开发工作流。读完后你应当能够在本地完成该 monorepo 的初始化、定向构建某个包、运行对应测试并理解各包的入口导出与底层实现来源。仓库总体定位与包结构Cua 项目面向 computer-use 2.0 场景提供跨操作系统的沙箱车队fleet、驱动与基准测试。其 TypeScript 侧代码集中在libs/typescript/目录是一个 pnpm 管理的多包工作区。README 给出的项目结构如下libs/typescript/ ├── computer/ # Computer-control compatibility package ├── core/ # Core functionality package ├── fleet/ # Fleet sandbox lifecycle package ├── package.json # Root package configuration └── pnpm-workspace.yaml # Workspace configuration三个包各自的定位trycua/core核心功能包提供遥测基于 PostHog 的集成与通用工具、类型trycua/fleet面向浏览器和 Node.js 的沙箱生命周期 SDK覆盖模板templates、池pools、申领claims以及对沙箱内服务的认证请求trycua/computer兼容旧有集成场景的计算机交互控制 SDK。从工作区声明 libs/typescript/pnpm-workspace.yaml 可以看到当前工作区实际纳入了 5 个包computer、core、agent、fleet与playground并配置了minimumReleaseAge: 46080即依赖需发布超过 46080 分钟才可被自动安装属于防范 supply-chain 新鲜依赖的策略。前置条件与安装构建开发环境要求来自 README 的 Prerequisites 一节Node.js v20 或更高版本pnpm v10 或更高版本。工作区根目录的 libs/typescript/package.json 中还通过packageManager字段锁定了pnpm10.12.3即推荐与仓库保持一致的 pnpm 版本。初始化与全量构建只需要两步# 安装所有包的依赖 pnpm install # 按正确的依赖顺序构建所有包 pnpm build:all依赖治理root package.json 中的 overrides从 libs/typescript/package.json 可以看到root 包名为cua-tslicense 为 MIT。它对子包依赖做了两层治理值得在本地复现构建时注意pnpm.onlyBuiltDependencies仅允许esbuild、protobufjs、sharp、unrs-resolver这几个含安装脚本的依赖执行 postinstall避免其他依赖携带的构建脚本被执行pnpm.overrides对defu、happy-dom、picomatch、postcss、rollup、uuid、vite、vitest、ws、yaml等传递依赖做了精确版本钉选例如vitest固定在4.1.0、ws固定在8.21.0保证整个工作区传递依赖版本一致、构建可复现。定向构建与按包测试构建命令README 提供了两种粒度的构建方式。构建全部包pnpm build:all构建指定包利用 pnpm 的--filter机制# Build core package pnpm --filter trycua/core build # Build Fleet package pnpm --filter trycua/fleet build # Build computer compatibility package pnpm --filter trycua/computer build从源码结构看构建顺序不是随意安排的。libs/typescript/computer/package.json 中 computer 包声明了prebuild钩子prebuild: pnpm --filter trycua/core build pnpm --filter trycua/fleet build即构建trycua/computer前会先构建其依赖的trycua/core和trycua/fleet同理pretest与pretypecheck也会先构建这两个上游包。这与 computer 包对trycua/core: workspace:^0.1.4和trycua/fleet: workspace:^的 workspace 依赖声明相互印证——三个包之间存在 core → fleet → computer 的依赖链pnpm build:all的意义正是在于保证这一顺序。三个包的构建工具也各不相同这从各自package.json的build脚本可以确认libs/typescript/core/package.json 与 libs/typescript/computer/package.json 使用tsdown一个基于现代 bundler 的 TS 构建器并配套devwatch 模式、typechecktsc --noEmit、releasebumpp pnpm publish脚本libs/typescript/fleet/package.json 的构建脚本是node ./scripts/build.mjs因为它不是普通的 TS 转译而是需要从 Rust SDK 编译 WebAssembly 产物的流水线见下文 fleet 一节。测试命令# Run tests for all packages pnpm test:all # Test core package pnpm --filter trycua/core test # Test computer package pnpm --filter trycua/computer test测试框架方面core 与 computer 包使用 Vitesttest: vitest测试文件位于各自tests/目录例如 libs/typescript/core/tests/telemetry.test.tscomputer 包的测试则按源码结构组织为 libs/typescript/computer/tests/computer/含cloud.test.ts、fleet.test.ts与 libs/typescript/computer/tests/interface/含factory.test.ts、linux.test.ts、macos.test.ts、windows.test.ts两组覆盖了 provider 与 interface 两大子系统。fleet 包则使用 Node 内置测试运行器node --test ./tests/*.test.mjs。Lint 与格式化# Lint all packages pnpm lint:all # Fix linting issues pnpm lint:fix:all从 root libs/typescript/package.json 的 scripts 可见lint 本质上是 Prettier 检查lint: prettier --check .lint:fix: prettier --write .并额外提供format/format:check两个等价脚本。也就是说该工作区的“lint”指代码格式一致性检查而非 ESLint 式的静态分析。三个包的源码级剖析trycua/core遥测与 HTTP 基础设施trycua/core的入口 libs/typescript/core/src/index.ts 只导出两个模块export * from ./telemetry; export * from ./http;其中遥测模块 libs/typescript/core/src/telemetry/index.ts 的注释明确了设计目标——“提供一种低开销方式采集匿名使用数据”并将 PostHog 客户端直接别名导出export { PostHogTelemetryClient as Telemetry } from ./clients;即上层包如 computer、agent无需关心具体厂商统一使用Telemetry这一名称。依赖上core 包引入pino日志、posthog-node遥测传输与uuid与包描述“包含 PostHog 集成的遥测、通用工具与类型”一致。trycua/computer兼容型计算机控制 SDKtrycua/computer当前版本 0.2.1是面向既有集成场景的兼容 SDK。从 libs/typescript/computer/src/ 的目录结构看其代码分为两大子系统Provider 系统src/computer/providers/包含base.ts、cloud.ts、fleet.ts三个文件。README 指出该包保留“Legacy VM provider system (Cloud)”而其 Fleet 兼容 provider 会把生命周期操作委托给trycua/fleet——这与cloud.ts/fleet.ts双 provider 的文件划分以及测试目录中cloud.test.ts/fleet.test.ts的对应关系相印证Interface 系统src/interface/包含factory.ts、linux.ts、macos.ts、windows.ts即按操作系统分派的交互接口工厂支撑 README 所说的“面向操作系统特定交互的 Interface 系统”截图、键鼠控制、命令执行等。README 同时给出了明确的方向性指引新的沙箱生命周期代码应直接使用trycua/fleet不要再通过trycua/computer实现第二套 Fleet 生命周期逻辑也不要再调用 legacy VM API。computer 包继续保留是为存量集成服务的兼容层。trycua/fleetWASM 构建的双入口 SDKtrycua/fleet是三个包中构建方式最特殊的一个。根据 libs/typescript/fleet/README.md 与 libs/typescript/fleet/package.json它是 Cua Fleet 控制平面的浏览器和 Node.js WebAssembly 绑定两个入口都暴露同一个生成的生命周期客户端用于创建模板、池、申领以及向沙箱内服务发起认证请求。条件导出conditional exportspackage.json 的exports字段定义了三个入口——根入口.browser条件指向./dist/browser.jsnode与import条件指向./dist/node.js、显式子路径./browser与./node并配有browser: ./dist/browser.js字段兜底。这意味着浏览器感知的打包器Vite 等会自动拿到 browser 入口Node 环境拿到 node 入口应用代码则推荐显式使用子路径导入行为更可预期。双入口示例均出自 fleet README浏览器端import { CyclopsClient, CyclopsTokenProviderConfigurationBuilder, uniffiInitAsync, } from trycua/fleet/browser; await uniffiInitAsync(); const configuration new CyclopsTokenProviderConfigurationBuilder() .baseUrl(https://run.cua.ai) .poolPollIntervalMs(5_000n) .poolPollLimit(120) .claimPollIntervalMs(5_000n) .claimPollLimit(120) .build(); const client CyclopsClient.connectBrowserWithAccessToken(configuration, accessToken);Node 端import { CyclopsTokenProviderConfigurationBuilder, createFleetClient } from trycua/fleet/node; const configuration new CyclopsTokenProviderConfigurationBuilder() .baseUrl(https://run.cua.ai) .poolPollIntervalMs(5_000n) .poolPollLimit(120) .claimPollIntervalMs(5_000n) .claimPollLimit(120) .build(); const client await createFleetClient(configuration, accessToken);从配置构建器的 API 可以读出 Fleet 客户端的核心参数语义baseUrl指定控制面地址poolPollIntervalMs/poolPollLimit控制池状态轮询的间隔毫秒BigInt 字面量与最大轮询次数claimPollIntervalMs/claimPollLimit对申领claim等待做同样的控制。Node 入口的额外优势在于它从磁盘加载同一份 WASM 产物并提供基于 fetch 的 UniFFI HTTP 传输因此不需要平台相关的原生libcyclops_sdk库。构建流水线fleet README 说明该包从本仓库的 libs/fleet 公共镜像构建——该镜像与规范的 Fleet 仓库保持同步使 npm 发布与公共 SDK 源码共享同一份发布历史。构建过程会重新生成浏览器 UniFFI 绑定、将钉选版本的 Rust SDK 编译为 WebAssembly并输出两个 ESM 入口及 TypeScript 声明文件。本地验证命令pnpm --dir libs/typescript/fleet build pnpm --dir libs/typescript/fleet pack:check其中pack:check实际是pnpm run build npm pack --dry-run即构建后做一次打包干跑确认发布产物内容正确由 libs/typescript/fleet/package.json 的 scripts 确认。发布流程README 的 Publishing 一节给出两步# 为发布准备构建所有包 pnpm -r build # 发布所有包 pnpm -r publish结合各子包的 scripts 可以补充两点细节core 与 computer 包都有prepublishOnly: pnpm run build钩子pnpm -r publish前会先重新构建保证 dist 是最新的两个包还各自提供了release: bumpp pnpm publish脚本bumpp负责版本号递增适合单包独立发版。需要注意 root libs/typescript/package.json 的build脚本pnpm build:core pnpm build:computer只覆盖 core 与 computer 两个包另有独立的build:fleet脚本而test脚本为pnpm -r test对全工作区递归执行。因此在涉及 fleet 的完整验证中建议显式补跑pnpm build:fleet与 fleet 目录下的test/pack:check。小结libs/typescript/是一个以 pnpm 工作区组织、依赖版本被集中钉选的 TypeScript monorepotrycua/core提供遥测与 HTTP 等共享基础设施trycua/fleet提供基于 UniFFI WebAssembly 构建、面向浏览器/Node 双环境的沙箱生命周期 SDKtrycua/computer作为兼容层保留旧式 VM provider 与按操作系统分派的 interface 系统并将新场景引导至 fleet 包。开发工作流为pnpm install→pnpm build:all→pnpm test:all→pnpm lint:all各包可用--filter定向构建与测试发布则通过pnpm -r build与pnpm -r publish辅以各包的prepublishOnly钩子完成。【免费下载链接】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），仅供参考