CashClaw开发指南:从npm run dev到Vitest测试与tsup打包的完整工作流
CashClaw开发指南:从npm run dev到Vitest测试与tsup打包的完整工作流
CashClaw 是一个自主工作 Agent:接单、干活、收款、自我学习,全部由一个 Node.js 进程完成。这篇 CashClaw 开发指南面向刚接触项目的开发者,带你在 10 分钟内跑通它的完整开发工作流——从 npm run dev 热启动,到用 Vitest 编写单元测试,再到用 tsup 打包出可发布的 CLI 产物,并附上推荐的项目目录结构与调试技巧。
项目结构一览:先认识这份 TypeScript 项目
git clone https://gitcode.com/gh_mirrors/ca/cashclaw
cd cashclaw
npm install
CashClaw 采用 TypeScript + ESM 组织,核心源码都在 src/ 下:
| 目录/文件 | 职责 |
|---|---|
| src/index.ts | 入口:启动 HTTP 服务并自动打开浏览器 |
| src/agent.ts | 双模式服务器(设置向导 ↔ 仪表盘 API) |
| src/loop/ | 多轮 LLM Agent 循环、系统提示词、自学习 |
| src/tools/ | 13 个工具:市场交易、钱包、记忆搜索等 |
| src/memory/ | BM25 知识搜索、反馈、日志 |
| src/ui/ | React 仪表盘(Vite 构建) |
| test/ | Vitest 单元测试 |
所有常用命令都收敛在 package.json 的 scripts 字段中,这是理解整套工作流的关键:
"scripts": {
"build": "tsup",
"build:ui": "vite build",
"build:all": "tsup && vite build",
"dev": "tsx src/index.ts",
"typecheck": "tsc --noEmit",
"test": "vitest run"
}
一步启动:npm run dev 如何用 tsx 热跑 Agent
npm run dev 的本质是用 tsx 直接运行 src/index.ts:
npm run dev
入口做了三件事:调用 startAgent() 拉起监听 http://localhost:3777 的 HTTP 服务、按操作系统(open / start / xdg-open)自动打开浏览器、注册 SIGINT/SIGTERM 优雅退出钩子。启动后你会看到设置向导:钱包 → 注册 Agent → 连接 LLM → 配置参数,四步走完仪表盘即自动接管。
开发时的两个实用细节:
- 改动即生效:
tsx不需要预编译,改完 src/loop/ 或 src/config.ts 重启进程即可;配置本身支持热加载,多数参数无需重启。 - 单独调试 UI:
vite.config.ts为src/ui配置了代理,/api请求会转发到 3777 端口(见 vite.config.ts),因此前端可以独立起 dev server 联调。
Vitest 单元测试:不花一分钱测 Agent 循环
测试入口是 npm test(等价于 vitest run),用例集中在 test/loop.test.ts。vitest.config.ts 保持极简——include: ["test/**/*.test.ts"],根目录即项目根,零配置上手。
这套测试最值得学习的是隔离策略:Agent 循环依赖 LLM 和工具两层外部世界,测试用 vi.mock 把 src/tools/registry.ts 整个替换成假实现,再用 createMockLLM 按顺序回放预设响应,从而做到不发一次真实 API 请求就能断言全部行为:
| 测试场景 | 验证点 |
|---|---|
| 单轮 end_turn | 无工具调用时循环立即收敛(L74-L89) |
| 工具调用链 | quote_task 执行结果被正确收集、Token 用量累加(L91-L118) |
| 拒绝流程 | decline_task 分支走通(L120-L142) |
| 最大轮数 | maxLoopTurns: 2 时强制停止并标记 <a href="https://link.gitcode.com/i/f2cf7e6c5e97656d9d3bb8026f857258" target="_blank">max turns reached]([L144-L162) |
| 工具注入 | 确认工具定义真的传给了 LLM(L196-L212) |
补充一个配套的 npm run typecheck:它执行 tsc --noEmit,配合 tsconfig.json 的 strict: true 做全量类型检查。建议养成「typecheck → test → dev」的提交前三连习惯。
tsup 打包:一行命令产出可发布 CLI
npm run build 走的是 tsup.config.ts,几个关键选项各有讲究:
entry: ["src/index.ts"], // 与 dev 共用同一入口
format: ["esm"], target: "node20",
outDir: "dist", clean: true, // 每次构建先清空,避免残留
sourcemap: true, // 保留映射便于线上排错
banner: { js: "#!/usr/bin/env node" } // 注入 shebang,输出即可直接执行
由于 package.json 声明了 "bin": { "cashclaw": "./dist/index.js" },打包产物 dist/index.js 既是库也是命令行工具——npm install -g 后即可直接敲 cashclaw 启动 Agent。
前端走另一条链路:npm run build:ui 用 Vite 把 src/ui/ 打包到 dist/ui,由 Node 进程静态托管。发布前建议跑一次全量验证:
npm run typecheck # 类型零错误
npm test # Vitest 全绿
npm run build:all # tsup + vite,完整构建
推荐日常开发流程清单
- 改代码前:
npm run typecheck,先确认类型基线干净 - 写功能:在 test/ 里为 src/loop/index.ts 等核心模块补用例,mock 掉 LLM 与工具注册表
- 跑起来:
npm run dev观察 3777 端口仪表盘,确认行为符合预期 - 提交前:
npm test && npm run build:all,保证测试绿、产物可构建 - 发布:产物即
dist/index.js,通过bin字段全局安装
掌握以上五条链路,CashClaw 的 dev → test → build 闭环就算完整跑通了。这套「tsx 热跑 + Vitest 隔离测试 + tsup 单入口打包」的组合对任何 Node.js Agent 项目都有参考价值,动手改一个工具或加一条测试用例,就是最好的上手方式。


