cua TypeScript CLI 的 Bun 运行时开发规范：从命令替换到 bun:sqlite 与前端 HTML 导入的源码级实践

cua TypeScript CLI 的 Bun 运行时开发规范从命令替换到 bun:sqlite 与前端 HTML 导入的源码级实践【免费下载链接】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/cua-cli/CLAUDE.md中为 cua-cliTypeScript 版编写的开发指南为主体完整覆盖其 Bun 运行时命令替换、内置 API 选型、bun test测试与 HTML 导入前端的全部规范并结合仓库中trycua/cli包的真实源码package.json、storage.ts、http.ts 等逐条印证这些指南在实际工程中的落地方式帮助读者掌握用 Bun 单一运行时构建、测试和分发 TypeScript CLI 的完整方案。一、cua-cli 的运行时定位为什么整包绑定 BunCLAUDE.md 是该目录下给 AI 辅助编码Claude与开发者约定的开发规范其第一原则只有一句话Default to using Bun instead of Node.js——在 cua-cli 包的日常开发中默认使用 Bun 而非 Node.js。这条约定不是抽象建议而是与包元数据强绑定的事实package.json 中声明了packageManager: bun1.1.38锁定包管理器为 Bun 1.1.38devDependencies中引入types/bun: latest提供类型支持而非types/nodebin字段直接指向源码./index.ts发布物里不需要编译步骤——index.ts 的第一行就是#! /usr/bin/env bunshebang由 Bun 直接解释执行 TypeScript发布脚本为bumpp bun publish且prepublishOnly只跑bun run typechecktsc --noEmit。需要说明的前提当前仓库中该包已标记 deprecatedREADMEREADME.md建议改用 Python 版cua-cliTypeScript SDKtrycua/computer、trycua/agent仍在维护。但作为一份Bun 单运行时构建完整 CLI MCP 服务的工程样本其源码结构对 TypeScript 开发者仍有很高的参考价值。二、运行时命令替换bun 对 Node 生态工具链的完整映射CLAUDE.md 开篇给出了六条一一对应的命令替换规则这是整份指南的骨架必须完整继承场景Bun 写法替代的传统工具执行脚本bun filenode file/ts-node file运行测试bun testjest/vitest构建产物bun build file.html\|file.ts\|file.csswebpack/esbuild安装依赖bun installnpm install/yarn install/pnpm install执行 package 脚本bun run scriptnpm run script/yarn run script/pnpm run script环境变量Bun 自动加载.env不要使用 dotenvdotenv这些规则在本包中都有实据可查直接执行 TypeScript 源文件。cua-cli 没有任何构建产物index.ts 作为bin入口被 Bun 直接运行内部只做一件事——调用src/cli.ts的runCli()并在失败时process.exit(1)。Bun 对.ts的原生执行省掉了 ts-node 或 tsc 编译环节。脚本统一走bun run。package.json 中scripts的release脚本写作bumpp bun publishprepublishOnly写作bun run typecheck与指南中bun run script的约定一致。不用 dotenv。config.ts 读取环境变量时直接使用Bun.env.CUA_WEBSITE_URL、Bun.env.CUA_API_BASE缺省回退到https://cua.ai/https://api.cua.ai没有任何 dotenv 依赖痕迹。bun build的定位本 CLI 是纯 Node/Bun 目标实际未用 bundlerbun build规则更适用于需要产物压缩/多入口打包的场景如 HTML/CSS 入口指南将其与 webpack/esbuild 对齐意在有构建需求时用 Bun 内置构建器不引入额外打包器。三、内置 API 选型清单及其在源码中的落点CLAUDE.md 的 APIs 小节给出八条选型规则。cua-cli 源码恰好是其中数条的活教材可以逐条对证1.Bun.serve()支持 WebSocket、HTTPS 与路由不要使用 express。cua-cli 本身是 stdio 型 CLI 而非 HTTP 服务因此未直接使用Bun.serve()详见下文前端示例该 API 是 Bun 生态 Web 侧的默认选择。2.bun:sqlite替代better-sqlite3。这是全仓库印证最完整的一条。storage.ts 的第一行即import { Database } from bun:sqlite实现了一个轻量 KV 存储function getDb(): Database { const db new Database(getDbPath()); db.exec(PRAGMA journal_mode WAL;); db.exec( CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL); ); return db; }API key 的读写围绕这张kv表展开setApiKey使用INSERT ... ON CONFLICT(k) DO UPDATE SET vexcluded.v做幂等 upsertgetApiKey通过db.query(...).get()取行clearApiKey直接删除记录。数据库文件路径来自 config.ts 的getDbPath()即${HOME}/.cua/cli.sqlitegetConfigDir()在首次访问时用Bun.spawnSync([mkdir, -p, dir])兜底建目录——同样是 Bun 内建能力替代第三方依赖的用法。3.Bun.redis替代ioredis4.Bun.sql替代pg/postgres.js5. 内置WebSocket替代ws。本 CLI 不涉及 Redis/Postgres 客户端这三条属于如需要则用内建模块的预防性约定。6. 优先使用Bun.file而非node:fs的 readFile/writeFile。源码中两处典型用法http.ts 在模块顶层用await Bun.file(new URL(../../package.json, import.meta.url)).json()读取版本号构造X-Cua-Client-Version: cli:version请求头让服务端可识别 CLI 客户端版本cli.ts 处理--version时读取${HOME}/.cua/bin/.versionconst version await Bun.file(path).text()读取失败则回退输出unknown。Bun.file的text()/json()链式 API 相比fs.readFileJSON.parse更简洁且是异步友好的。**7.Bun.$\ls替代 execa。**config.ts中对目录创建选择了更原生的Bun.spawnSync见上两者同属 Bun 对子进程能力的内建覆盖指南推荐模板字符串式的Bun.$ 是因为它自带 shell 语义与 Promise 化。8. 其余工程事实。cli.ts 的命令行框架仍是yargs负责子命令、动态 shell 补全与 epilogue 帮助文本说明 Bun 指南约束的是运行时/工具链层而非禁止一切第三方库——yargs、zod、modelcontextprotocol/sdk依旧正常出现在 package.json 的依赖中。四、测试规范bun test与bun:testCLAUDE.md 的 Testing 小节要求统一用bun test跑测试并给出最小示例完整保留原文import { test, expect } from bun:test; test(hello world, () { expect(1).toBe(1); });要点在于测试断言来自bun:test模块——这是 Bun 运行时内建的测试框架API 与 vitest/jest 的expect风格兼容但不需要在 devDependencies 中声明任何测试运行器。对 cua-cli 而言这意味着未来为其补充单元测试例如针对 storage.ts 的 upsert 逻辑、util.ts 的类型定义时直接编写*.test.ts并用bun test收集即可无需配置 test runner、transformer 或 jsdom 之类的配套设施。当前该包未包含测试文件package.json中也无test脚本——规范先于实践这正体现了该文档约定先行的定位。五、前端规范HTML 导入 Bun.serve()取代 ViteCLAUDE.md 的 Frontend 小节声明使用 HTML 导入配合Bun.serve()不要使用 viteHTML 导入完整支持 React、CSS、Tailwind。下面完整继承原文的三段代码。服务端index.ts——路由 API WebSocket HMRimport index from ./index.html Bun.serve({ routes: { /: index, /api/users/:id: { GET: (req) { return new Response(JSON.stringify({ id: req.params.id })); }, }, }, // optional websocket support websocket: { open: (ws) { ws.send(Hello, world!); }, message: (ws, message) { ws.send(message); }, close: (ws) { // handle close } }, development: { hmr: true, console: true, } })入口 HTMLindex.html——直接以模块脚本引用 TSXhtml body h1Hello, world!/h1 script typemodule src./frontend.tsx/script /body /html组件文件frontend.tsx——TSX 中直接importCSSimport React from react; // import .css files directly and it works import ./index.css; import { createRoot } from react-dom/client; const root createRoot(document.body); export default function Frontend() { return h1Hello, world!/h1; } root.render(Frontend /);Bun 的 bundler 会在运行时自动完成 TSX 转译与打包HTML 中的script typemodule可指向.tsx/.jsx/.js文件link指向的样式表由 CSS bundler 处理组件内import ./index.css也直接生效。开发时执行bun --hot ./index.ts--hot提供热重载配合development.hmr即构成一套无配置的前端开发体验——这正是不用 vite的底气路由、静态资源、WebSocket、HMR 全部收敛进Bun.serve()一个 API。对 cua-cli 的工程含义是若该 CLI 未来需要附带本地 Web 界面例如 skills 回放、沙箱状态面板按本指南的实现路径是一个Bun.serve()进程 HTML 导入而不需要单独拉起一个 vite dev server 或静态文件服务。六、收尾规范的适用边界与阅读指引综合来看CLAUDE.md 是一份运行时收敛清单它把 TypeScript 项目中最容易膨胀的四类依赖——包管理器脚本、测试框架、打包器、Web 服务框架——分别收敛到bun命令族、bun:test、bun build、Bun.serve()而 cua-cli 源码中 storage.ts 的bun:sqlite、config.ts 的Bun.env/Bun.spawnSync、http.ts 与 cli.ts 的Bun.file都验证了这一收敛是可以在生产级 CLI 中成立的。适用边界需要明确该规范仅约束libs/typescript/cua-cli包及同类 Bun 目标代码不影响仓库中其他使用 pnpm 工作区管理的 TypeScript 项目如 libs/typescript/playground本包已 deprecated新场景应使用 Python 版cua-cli见 README.md 的迁移对照表指南末尾提示更多 API 细节应查阅随types/bun分发的文档即安装依赖后的node_modules/bun-types/docs/**.md。想进一步验证时可直接对照四个文件index.tsBun 直接执行的入口、src/cli.tsyargs 命令树与动态补全、src/storage.tsbun:sqlite 凭证存储、src/serve-mcp.ts同一 Bun 运行时之上构建的 MCP 工具服务器含沙箱管理与computer_*系列计算机操作工具及权限位控制。【免费下载链接】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），仅供参考