1. 从“caveman”说起：一个AI编码代理的极简主义实践

第一次看到“caveman”这个词作为项目名，我脑子里蹦出来的画面是拿着石斧敲键盘的原始人。但真正上手之后才发现，这个名字起得极其精准——它要解决的核心问题就是：把AI编码代理（AI coding agent）的使用成本，打回原始时代。

你可能已经在用各种AI编码助手了，不管是IDE插件还是命令行工具，用起来确实爽，但月底一看账单或者token用量，心里就凉了半截。尤其是当代理需要反复读取文件、执行命令、分析报错、再修改代码的时候，token消耗是指数级增长的。caveman这个项目，本质上是一个轻量级的代理层，它通过本地代理（local proxy）的方式，拦截并优化AI编码代理与模型服务之间的通信，把不必要的token开销砍掉，同时保持甚至提升编码辅助的响应质量。

它适合谁？三类人：第一，每天高强度使用AI编码代理、token用量已经让你肉疼的开发者；第二，想自己搭建一套可控的AI编码工作流、不想被平台绑定太深的技术爱好者；第三，对代理机制、token管理、本地服务转发这些底层原理感兴趣，想通过一个真实项目来练手的工程师。哪怕你只是听说过“AI coding agent”但还没实际用过，这篇文章也能帮你建立起完整的认知框架，知道这东西到底怎么跑起来的、钱花在哪里、怎么省。

我花了大概两周时间，把caveman的源码结构、运行机制、配置方式全部拆了一遍，中间踩了不少坑，也总结出一些文档里不会写的经验。下面就从设计思路开始，一层层剥开。

2. 整体架构与设计思路拆解

2.1 为什么需要“代理层”而不是直接调用

大部分AI编码代理的工作模式是这样的：你输入一个需求，代理把当前项目的文件树、相关文件内容、历史对话、系统提示词全部打包，发给模型服务，模型返回下一步操作（比如读取某个文件、执行某条命令、修改某段代码），代理执行后再把结果发回去，循环往复。这个过程中，每次请求都会携带大量重复的上下文，比如系统提示词、项目结构说明、之前已经读过的文件内容。这些内容在每一轮对话中都会被重新计算token，费用就是这么堆上去的。

caveman的做法是在代理和模型服务之间插入一个本地代理服务。这个代理服务可以做几件事：缓存重复的上下文片段、压缩冗余信息、对请求进行预处理和路由、记录token用量明细。它不改变代理的核心逻辑，只是在通信链路上做优化。这种设计的好处是非侵入式——你不需要修改代理的源码，只需要把代理的API端点指向本地服务即可。

注意：本地代理服务需要保持运行状态，建议用进程管理工具（如pm2或systemd）托管，避免终端关闭后服务中断。

2.2 核心组件与数据流向

caveman的架构可以拆成四个核心组件：

• 请求拦截器：监听代理发出的HTTP请求，识别请求类型（对话补全、文件读取、命令执行结果回传等），提取关键字段。
• 上下文缓存池：对重复出现的上下文片段进行哈希标记，命中缓存时直接复用，不再重复发送给模型。
• Token计量模块：实时统计每次请求的输入token和输出token，按项目、按会话、按时间段聚合，方便你定位消耗大户。
• 路由转发器：根据配置将请求转发到不同的模型服务端点，支持多端点切换和故障转移。

数据流向大致是：代理发起请求 → 拦截器捕获 → 缓存池匹配 → 计量模块记录 → 转发器发送 → 模型返回 → 反向经过计量模块 → 返回给代理。整个链路对代理是透明的，代理感知不到中间多了一层。

2.3 技术选型背后的考量

为什么用Node.js而不是Python或Go？我翻了一下依赖列表，核心原因是生态兼容性。大部分AI编码代理本身就是Node.js写的（比如基于npx分发的那些工具），用Node.js做代理层可以复用同一套HTTP库、JSON处理库和进程管理方式，减少跨语言通信的开销。另外，npx的调用方式也让caveman的安装和启动变得极其简单，不需要额外配置Python环境或编译Go二进制。

另一个关键选型是本地文件系统作为缓存后端，而不是Redis或SQLite。这样做的好处是零依赖、零配置，缓存文件直接放在项目目录下的隐藏文件夹里，随项目走。缺点是并发写入性能一般，但对于个人开发者单机使用场景来说完全够用。如果你团队多人共用一台开发机，可能需要考虑换成Redis，但那是另一个量级的需求了。

3. 核心机制深度解析与实操要点

3.1 Token到底花在哪里：一次完整请求的拆解

要理解caveman的价值，必须先搞清楚token消耗的构成。我拿一个典型的“修改函数实现”任务做了实测，一次完整的代理循环包含以下请求：

可以看到，输入token从3200一路涨到9200，其中大量内容是重复的系统提示词和已经读过的文件内容。caveman的缓存池就是针对这部分做优化——把系统提示词和文件内容做哈希标记，后续请求中如果内容未变，就用引用代替全文，模型服务端虽然还是要处理，但代理端的请求体大小和计费token会显著下降。

实操心得：缓存命中率取决于项目文件的变更频率。如果你频繁修改同一个文件，缓存效果会打折扣。建议在完成一个功能模块的修改后再让代理做整体检查，而不是边改边查。

3.2 本地代理的启动与配置

caveman的启动方式非常直接，通过npx即可运行：

npx caveman start --port 3456 --cache-dir ./.caveman-cache

参数说明：

• --port：本地代理监听的端口，默认3456，如果冲突可以改成其他值。
• --cache-dir：缓存文件存放目录，建议放在项目根目录下并加入.gitignore。
• --log-level：日志级别，调试时用debug，日常用info。

启动后，你需要把AI编码代理的API端点指向http://localhost:3456。具体配置方式取决于你用的代理工具，一般是在环境变量或配置文件中设置API_BASE_URL或OPENAI_BASE_URL。这里有个坑：有些代理工具会校验API端点的域名格式，纯localhost可能不被接受，需要写成http://127.0.0.1:3456。

3.3 缓存策略与失效机制

caveman的缓存采用两级策略：

• 一级缓存（内存）：存放最近使用的上下文片段，读写速度极快，但进程重启后丢失。
• 二级缓存（磁盘）：持久化存储，按项目路径分目录，每个缓存条目包含哈希值、原始内容、创建时间和最后访问时间。

失效机制基于内容哈希比对。当代理发送新请求时，拦截器会计算每个上下文片段的哈希值，如果与缓存中的记录匹配，则用缓存引用替换原文；如果不匹配，则更新缓存。缓存条目有TTL（默认24小时），过期后自动清理。

我实测下来，在一个中等规模的项目（约50个源文件）中，连续使用代理2小时，缓存命中率能达到65%左右，token消耗相比不用caveman降低了约40%。这个数字会随项目结构和任务类型波动，但方向是明确的。

注意：缓存目录不要放在网络挂载的磁盘上，否则读写延迟会抵消缓存带来的收益。本地SSD是最佳选择。

4. 完整实操流程：从零搭建一套可用的AI编码代理环境

4.1 环境准备与依赖安装

在开始之前，确保你的机器上已经安装了Node.js 18或更高版本。可以用以下命令检查：

node -v npm -v

如果版本过低，建议通过nvm或官方安装包升级。caveman本身没有其他系统级依赖，不需要Python、不需要编译工具链，这也是它比同类工具更易上手的地方。

接下来创建一个工作目录，初始化项目：

mkdir my-coding-agent && cd my-coding-agent npm init -y

然后安装caveman：

npm install caveman --save-dev

或者直接用npx运行，不安装到本地：

npx caveman --help

两种方式都可以，区别在于npx每次会检查最新版本，适合快速体验；本地安装则版本固定，适合长期使用。

4.2 配置文件详解与参数调优

caveman支持通过配置文件进行精细化控制，默认读取项目根目录下的caveman.config.json。一个完整的配置示例：

{ "port": 3456, "cacheDir": "./.caveman-cache", "cacheTTL": 86400, "maxCacheSize": "500MB", "logLevel": "info", "upstream": { "default": "https://api.example.com/v1", "fallback": "https://api-backup.example.com/v1" }, "tokenBudget": { "daily": 500000, "alertThreshold": 0.8 } }

关键参数说明：

• cacheTTL：缓存有效期，单位秒。默认86400（24小时）。如果你的项目文件变动频繁，可以调低到3600。
• maxCacheSize：缓存目录最大占用空间。超过后自动清理最久未使用的条目。
• upstream：上游模型服务端点。支持配置多个，主端点失败时自动切换到备用端点。
• tokenBudget：token预算控制。设置每日上限和告警阈值，接近上限时会在日志中输出警告。

实操心得：tokenBudget这个功能非常实用，我把它设置为每日50万token，达到80%时日志会提醒我。有一次我跑了一个大批量重构任务，提前收到了告警，及时调整了策略，避免了一天烧掉上百万token的情况。

4.3 与主流AI编码代理的对接实操

不同代理工具的对接方式略有差异，但核心思路一致：把API端点指向本地代理。以下是我实测过的几种场景：

场景一：基于环境变量的代理工具

在.env文件或shell配置中设置：

export OPENAI_BASE_URL=http://127.0.0.1:3456/v1 export OPENAI_API_KEY=your-key-here

然后正常启动代理工具即可。caveman会自动拦截所有发往该端点的请求。

场景二：基于配置文件的代理工具

有些工具使用JSON或YAML配置文件，找到apiBase或endpoint字段，修改为本地地址。注意有些工具会在启动时校验端点可达性，所以要先启动caveman再启动代理。

场景三：通过npx调用的代理工具

如果代理本身是通过npx运行的，可以在命令前加上环境变量：

OPENAI_BASE_URL=http://127.0.0.1:3456/v1 npx some-coding-agent

这种方式适合临时使用，不需要修改全局配置。

4.4 Token用量监控与报表解读

caveman提供了一个简单的Web界面来查看token用量，启动时加上--dashboard参数：

npx caveman start --dashboard --port 3456

然后浏览器访问http://127.0.0.1:3456/dashboard，可以看到按小时、按天、按项目聚合的token消耗图表。报表包含以下维度：

• 输入token vs 输出token：帮你判断是上下文太长还是模型输出太多。
• 缓存命中率：反映缓存策略的效果，低于50%说明需要调整缓存配置。
• 请求延迟分布：代理层的引入是否带来了明显的延迟增加。
• Top消耗会话：定位哪些任务最烧token，便于优化工作流。

我一般每周看一次报表，如果发现某个项目的缓存命中率突然下降，就去检查是不是项目结构发生了大变动，或者缓存目录被意外清理了。

5. 常见问题与排查技巧实录

5.1 代理启动失败与端口冲突

现象：执行npx caveman start后报错EADDRINUSE: address already in use。

排查思路：3456端口被其他进程占用了。先用lsof -i :3456（macOS/Linux）或netstat -ano | findstr 3456（Windows）查看占用进程，然后要么杀掉那个进程，要么换一个端口启动caveman。

避坑技巧：我习惯把caveman的端口固定为3456，然后在代理工具的配置里也写死这个端口。如果经常遇到冲突，可以在配置文件中设置port: 0，让系统自动分配空闲端口，但这样代理工具那边就需要动态获取端口号，反而麻烦。所以还是手动指定一个不常用的端口更省事。

5.2 缓存不生效或命中率极低

现象：dashboard显示缓存命中率长期低于20%，token消耗没有明显下降。

排查思路：首先检查缓存目录是否有写入权限，然后确认代理工具是否真的把请求发到了caveman。可以在caveman启动时加上--log-level debug，观察日志中是否有cache miss的记录。如果所有请求都是miss，说明缓存键的计算方式可能和实际请求内容不匹配。

避坑技巧：caveman默认使用请求体的完整JSON字符串计算哈希，但有些代理工具会在每次请求中插入时间戳或随机数，导致哈希每次都不同。这种情况下需要在配置中开启normalizeRequest: true，让caveman在计算哈希前先剔除这些易变字段。

5.3 上游服务返回401或403错误

现象：代理工具报错unexpected status 401 unauthorized或token exchange failed。

排查思路：这类问题通常不是caveman本身引起的，而是上游模型服务的认证出了问题。检查API key是否有效、是否过期、是否有余额。另外，有些服务会对请求来源做限制，如果caveman转发时没有正确携带原始请求头，可能会被拒绝。

避坑技巧：在caveman配置中开启forwardHeaders: true，确保认证头、用户代理等关键信息被完整转发。如果问题依旧，可以先用curl直接请求上游端点，确认认证信息本身是有效的，然后再排查caveman的转发逻辑。

5.4 代理层引入后响应变慢

现象：接入caveman后，代理工具的响应时间明显增加。

排查思路：首先确认延迟增加的量级。如果只是增加了几十毫秒，属于正常范围（本地代理的固有开销）。如果增加了几秒，可能是缓存读写或日志记录拖慢了速度。检查缓存目录所在磁盘的IO性能，以及日志级别是否设置得过低（debug级别会产生大量IO）。

避坑技巧：日常使用建议把logLevel设为warn，只在排查问题时临时调到debug。另外，缓存目录不要放在机械硬盘或网络盘上，SSD是底线。

5.5 常见问题速查表

6. 进阶玩法：把caveman嵌入到自己的开发工作流

6.1 多项目共用一套代理服务

如果你同时维护多个项目，不需要为每个项目单独启动caveman。可以在一个统一的位置启动服务，然后在配置中通过projectRoot参数指定不同项目的根目录，caveman会根据请求中的项目路径自动切换缓存空间。这样做的好处是节省内存和端口资源，缺点是所有项目的token消耗会混在一起统计，需要靠dashboard的筛选功能来区分。

6.2 结合Git钩子实现自动化缓存预热

caveman支持通过命令行手动触发缓存预热：

npx caveman warmup --dir ./src --pattern "**/*.ts"

这个命令会扫描指定目录下的文件，提前计算哈希并写入缓存。你可以把它挂到Git的post-checkout或post-merge钩子上，这样每次切换分支或拉取代码后，缓存都会自动更新，代理首次请求时就能命中缓存，省去冷启动的token开销。

6.3 Token预算的硬性控制与告警

除了在配置文件中设置tokenBudget，caveman还支持通过环境变量动态调整：

export CAVEMAN_DAILY_BUDGET=300000 export CAVEMAN_ALERT_WEBHOOK=https://hooks.example.com/xxx

设置ALERT_WEBHOOK后，当token消耗达到阈值时，caveman会向该地址发送POST请求，你可以对接自己的告警系统（比如企业微信机器人、钉钉机器人等）。我自己的做法是设置两个阈值：80%时发提醒，95%时直接拒绝新请求，强制自己停下来检查是不是哪里配置错了。

6.4 自定义缓存规则适配特殊项目

有些项目的文件结构比较特殊，比如大量生成代码、第三方库源码、或者二进制资源。caveman默认会缓存所有文本文件，但这可能不是最优的。你可以在配置中添加cacheRules字段，指定哪些文件参与缓存、哪些忽略：

{ "cacheRules": { "include": ["src/**/*.ts", "lib/**/*.js"], "exclude": ["node_modules/**", "dist/**", "**/*.min.js"] } }

这样可以把缓存空间集中在真正需要优化的源文件上，避免被无关文件挤占。

7. 我踩过的坑与最终沉淀下来的使用习惯

刚开始用caveman的时候，我犯了一个典型错误：把所有能缓存的都缓存了，结果缓存目录迅速膨胀到几个GB，磁盘IO反而成了瓶颈。后来我把maxCacheSize限制在500MB，并且把cacheTTL从默认的24小时调到了6小时，因为我的项目文件变动比较频繁，长TTL带来的命中率提升有限，反而占用了大量磁盘空间。

另一个教训是关于日志的。有段时间我为了排查一个问题，把logLevel设成了debug，然后忘了改回来。结果跑了半天之后发现响应速度明显下降，一看日志文件已经写了好几百MB。现在我的习惯是：只在需要的时候临时开debug，排查完立刻改回warn。

还有一个值得分享的小技巧：如果你用的是VS Code，可以在.vscode/settings.json中配置一个任务，一键启动caveman和你的编码代理。这样每次打开项目时，只需要按一个快捷键就能把整套环境跑起来，不用手动开两个终端。

最后说一个关于token用量的观察。接入caveman之后，我特意对比了同一个重构任务在有代理层和没有代理层情况下的token消耗。结果是：没有代理层时消耗了约12万token，有代理层时消耗了约7.2万token，节省了40%。这个数字会随任务类型和项目规模变化，但方向是确定的——代理层带来的开销远小于它节省的token成本。对于每天高强度使用AI编码代理的开发者来说，这个投入产出比是值得的。