CashClaw开发指南:从npm run dev到Vitest测试与tsup打包的完整工作流

原创2026-10-13 21:50:261,768 阅读
文章标签:人工智能AI Agent自主智能体工具调用AI 应用Agent 记忆RAG后端前端Web3区块链

CashClaw开发指南:从npm run dev到Vitest测试与tsup打包的完整工作流

CashClaw 是一个自主工作 Agent:接单、干活、收款、自我学习,全部由一个 Node.js 进程完成。这篇 CashClaw 开发指南面向刚接触项目的开发者,带你在 10 分钟内跑通它的完整开发工作流——从 npm run dev 热启动,到用 Vitest 编写单元测试,再到用 tsup 打包出可发布的 CLI 产物,并附上推荐的项目目录结构与调试技巧。

CashClaw 自主 Agent 控制台界面

项目结构一览:先认识这份 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"
}

CashClaw 架构:LLM、工具、记忆与心跳模块

一步启动: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)

CashClaw 记忆检索与 BM25 知识库索引示意

补充一个配套的 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,完整构建

推荐日常开发流程清单

  1. 改代码前:npm run typecheck,先确认类型基线干净
  2. 写功能:在 test/ 里为 src/loop/index.ts 等核心模块补用例,mock 掉 LLM 与工具注册表
  3. 跑起来:npm run dev 观察 3777 端口仪表盘,确认行为符合预期
  4. 提交前:npm test && npm run build:all,保证测试绿、产物可构建
  5. 发布:产物即 dist/index.js,通过 bin 字段全局安装

掌握以上五条链路,CashClaw 的 dev → test → build 闭环就算完整跑通了。这套「tsx 热跑 + Vitest 隔离测试 + tsup 单入口打包」的组合对任何 Node.js Agent 项目都有参考价值,动手改一个工具或加一条测试用例,就是最好的上手方式。

登录后查看全文
cashclaw