1. 从caveman这个名字说起它到底想解决什么问题第一次看到caveman这个项目名我脑子里蹦出来的画面是原始人拿着石斧敲键盘。但真正让我停下来琢磨的是它背后那组关键词——AI coding agent、token、proxy、npx。这几个词凑在一起指向的其实是一个非常具体的痛点当你在本地跑一个 AI 编程助手时它和模型服务之间的那层通信管道到底该怎么搭、怎么管、怎么省。先说清楚 caveman 是什么。从项目命名和关联词来看它是一个围绕 AI coding agent 构建的轻量级工具或框架核心关注点落在三件事上一是 agent 与模型之间的请求转发proxy二是 token 的消耗与流转管理三是通过 npx 这种零安装方式快速拉起。换句话说它不是又一个帮你写代码的 AI而是帮你把 AI 写代码这件事跑得更顺、更可控、更省钱的那层基础设施。为什么这层东西值得单独做一个项目因为绝大多数人用 AI coding agent 的体验是这样的装一个 CLI 工具配一个 API key然后就开始用。用着用着发现三个问题——第一token 哗哗地烧月底账单看不懂第二多个 agent、多个模型、多个项目之间切换时配置乱成一锅粥第三一旦网络请求出问题报错信息全是token exchange failed、unexpected status 401这种根本不知道卡在哪一环。caveman 想做的就是把这层看不见的管道变成看得见、管得住的东西。这篇文章适合谁看如果你只是偶尔用网页版 AI 聊聊天那可能用不上。但如果你满足下面任意一条这篇值得读完你在本地跑过 Claude Code、Codex 这类 CLI agent你被 token 用量和费用困扰过你需要在多个模型服务之间做切换或聚合你想搞清楚 agent 请求从发出到返回中间到底经过了什么。我会从架构、token 管理、proxy 设计、npx 分发、实战踩坑几个角度把这类工具的设计逻辑和落地细节讲透。需要提前说明的是caveman 这个项目本身的公开资料比较有限所以文中涉及的具体实现细节我会基于一个合格工程师在做这类工具时最可能采用的方案来补全并明确标注哪些是通用实践、哪些是推测。这样你读到的不是空中楼阁而是可以直接拿去对照自己项目的参考。2. AI coding agent 的请求链路proxy 到底卡在哪一环2.1 一次 agent 请求的完整旅程要理解 caveman 为什么要做 proxy得先搞清楚一个 AI coding agent 发一次请求中间经历了什么。很多人以为我敲个回车模型就回我了实际上这条链路至少有五六个环节。你在终端里输入一句帮我把这个函数重构成异步的agent 首先要把这句话、当前文件的上下文、可能还有整个项目的目录结构打包成一个符合模型 API 格式的请求体。这个请求体里最关键的字段就是token——不是登录凭证那个 token而是文本被切分后的计量单位。一段 500 行的代码可能就吃掉几千个 token。打包完成后请求要通过 HTTP 发往模型服务端点这一步就是proxy发挥作用的地方请求是先直连官方端点还是先经过本地的一个转发层如果直连那你的 API key 直接暴露在 agent 的配置里且所有请求的日志、重试、限流都得靠 agent 自己处理。如果经过本地 proxy那么 proxy 可以做几件事统一注入凭证、记录每次请求的 token 消耗、在多个上游之间做负载均衡、对失败请求做重试和降级。caveman 这类工具的价值恰恰在于把这个 proxy 层做得足够轻、足够透明让你几乎感觉不到它的存在但又能随时查看它记录的一切。2.2 为什么直连在长期使用中会出问题我刚开始用 CLI agent 的时候也是直连派觉得多一层转发就是多一个故障点。但用了两个月之后我改主意了。原因很现实直连模式下你对请求的可见度是零。举几个我真实遇到过的场景。有一次某个月 token 用量突然翻了三倍我完全不知道是哪个项目、哪次对话造成的因为 agent 本身不提供细粒度的用量报表。还有一次某个上游服务在特定时段响应特别慢agent 就一直在那儿转圈我既不知道它在重试也不知道重试了几次。最要命的是多模型切换——我白天用 A 模型写业务代码晚上用 B 模型做代码审查两套配置、两个 key每次切换都要改环境变量改错一次就得排查半天。本地 proxy 层解决的正是这些运维层面的问题。它像一个收费站所有请求都得从这儿过于是它天然就能记录谁发的、发去哪、花了多少 token、耗时多久、成功还是失败。这些数据攒起来你才能回答我的钱花在哪了这种问题。而且 proxy 层可以做协议适配——不同模型服务的 API 格式其实有差异有的字段叫max_tokens有的叫max_output_tokensproxy 可以在中间做转换让上层的 agent 只用关心一套接口。2.3 caveman 的 proxy 设计取向薄而透明从项目定位推断caveman 的 proxy 不会做成一个功能臃肿的网关而是走薄而透明的路线。所谓薄是指它只做必要的转发、记录、适配不引入复杂的路由规则和插件体系所谓透明是指它对 agent 完全兼容——agent 以为自己在直连官方端点实际上请求被悄悄导流到了本地。这种设计有个很实际的考量AI coding agent 的迭代速度极快任何试图深度介入请求内容的 proxy 都很容易被上游的协议变更打挂。你今天解析了请求体里的某个字段明天官方改了个名字你的 proxy 就报错了。薄 proxy 只碰它必须碰的部分比如注入 header、记录用量其余原样透传这样上游怎么变它都能扛住。具体到实现一个薄 proxy 通常长这样监听本地某个端口比如localhost:8787收到请求后读取配置里的上游地址和凭证替换或补充认证 header转发出去拿到响应后记录 token 用量再原样返回给 agent。整个过程对 agent 来说就是一次普通的 HTTP 调用。你可以用几十行 Node.js 或者 Python 就搭起来caveman 的价值在于它把这几十行做成了开箱即用、配置友好的形态。提示判断一个 proxy 是否薄有个简单标准——看它的配置文件有多少项。如果配置项超过二十个大概率已经开始变重了维护成本会随上游变更线性上升。3. token 这件事比你想的更需要记账3.1 token 不只是计费单位更是性能指标大部分人把 token 理解成钱这没错但只说对了一半。token 同时还是性能指标和上下文预算。一个模型的上下文窗口是有限的比如 200K token你的系统提示词、对话历史、代码上下文、模型回复全都从这个窗口里扣。当窗口快满的时候模型的表现会明显下降——它开始忘记前面的内容或者回复变得敷衍。所以管理 token 有两层含义一层是省钱一层是保效果。caveman 这类工具如果只盯着计费那格局就小了真正有价值的是帮你看清 token 都花在哪了从而优化你的使用方式。比如你发现每次请求都带着整个项目的目录树那可能就是几千 token 的固定开销完全可以改成按需加载。我做过一个粗略的统计在一个中等规模的代码库里如果 agent 每次都把完整的文件列表塞进上下文光这一项每次请求就要消耗 3000 到 8000 token。一天如果发 200 次请求那就是 60 万到 160 万 token 的纯浪费。这个数字在账单上是很吓人的但如果你没有 proxy 层的记录你根本发现不了。3.2 用 proxy 做 token 记账的具体做法在 proxy 层做 token 记账核心是拦截响应体里的 usage 字段。主流模型服务的响应里都会带一个类似这样的结构{ usage: { prompt_tokens: 1523, completion_tokens: 487, total_tokens: 2010 } }proxy 在转发响应回 agent 之前把这个 usage 抠出来连同时间戳、请求来源、目标模型一起写进本地的一个日志文件或者轻量数据库SQLite 就很合适。这样你随时可以跑个查询看看今天花了多少、哪个项目花得最多。// 一个极简的 token 记账逻辑示意 function recordUsage(req, res, usage) { const entry { time: new Date().toISOString(), model: req.headers[x-target-model] || unknown, source: req.headers[x-agent-name] || default, promptTokens: usage.prompt_tokens, completionTokens: usage.completion_tokens, totalTokens: usage.total_tokens }; db.prepare(INSERT INTO usage_log VALUES (?, ?, ?, ?, ?, ?)) .run(entry.time, entry.model, entry.source, entry.promptTokens, entry.completionTokens, entry.totalTokens); }这段代码没什么技术含量但它的价值在于坚持记录。很多人搭了 proxy 却懒得记账那 proxy 就退化成了一个纯粹的转发器白白多了一层。记账这件事贵在持续哪怕你一周只看一次报表也比完全没有强。3.3 从记账到优化几个能立刻省 token 的动作有了数据之后优化就有了方向。我总结下来最有效的几个动作是砍掉冗余上下文检查你的 agent 是不是每次都把整个文件树、所有打开的标签页内容塞进去。很多 agent 支持配置上下文范围把它收窄。复用系统提示词如果每次请求的系统提示词都一样确认上游是否支持 prompt caching。支持的话这部分 token 的费用能降一大截。控制对话历史长度长对话的历史会不断累积设置一个上限超过就做摘要压缩而不是无脑全带。按任务选模型简单任务用便宜的小模型复杂任务才上大模型。proxy 层可以根据请求特征做路由这也是它比直连强的地方。这几条里prompt caching 的收益最直接。以我自己的使用为例开启缓存后固定系统提示词那部分的成本下降了大约 70% 到 90%具体取决于上游的缓存策略和命中率。这个数字不是拍脑袋是 proxy 记账报表里实打实跑出来的。4. npx 分发为什么零安装对这类工具是刚需4.1 npx 解决了什么又带来了什么caveman 用 npx 作为分发方式这个选择很值得聊。npx 的本质是临时下载并执行一个 npm 包用户不需要全局安装敲一行命令就能跑起来。对工具类项目来说这极大地降低了尝试门槛——从我要不要装这个变成我直接跑一下看看。但 npx 也有它的代价。第一次执行时它需要从 registry 下载包如果网络环境不理想这一步可能很慢甚至失败。而且 npx 默认执行的是包的最新版本这意味着上游发新版可能引入不兼容变更你的使用体验会莫名其妙地变化。所以一个成熟的 npx 工具通常会在文档里建议你锁定版本比如npx caveman1.2.3而不是npx caveman。还有一个容易被忽略的点npx 下载的包会缓存在本地但缓存策略和清理机制各平台不一。如果你频繁切换版本缓存目录可能会膨胀。这不是大问题但值得知道。4.2 一个 npx 工具的启动流程该长什么样从用户体验角度caveman 这类工具的启动流程应该尽量短。理想情况下是三步跑命令、填配置、开始用。我见过太多工具在第一步就劝退用户——要求你先装一堆依赖、再手动创建配置文件、再设置环境变量折腾半小时还没跑起来。一个合理的启动设计是这样的npx caveman首次运行时检测本地有没有配置文件没有就引导你创建一个问几个关键问题上游地址、凭证、监听端口生成配置然后启动 proxy。第二次运行就直接读配置启动。整个过程不超过一分钟。# 首次运行进入引导配置 npx caveman # 后续运行直接启动 npx caveman # 指定配置文件启动 npx caveman --config ./my-config.json # 锁定版本避免上游变更影响 npx caveman1.2.3这里有个实操心得把配置文件放在项目目录之外比如用户主目录下的.caveman/config.json。因为凭证这种东西不应该跟着项目走否则你一不小心提交到代码仓库就麻烦了。工具本身也应该在文档里明确提醒这一点。4.3 npx 与本地 proxy 的配合细节npx 启动的 proxy 是个前台进程这意味着你关掉终端它就没