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

第一次看到“caveman”这个词被用来命名一个AI coding agent，我脑子里浮现的画面是：一个裹着兽皮、拎着石斧的原始人，蹲在电脑前敲代码。这个反差感极强的命名本身就传递了一个信号——它不打算走“大而全”的路线，而是要用最原始、最直接的方式解决一个具体问题。

这个项目要解决的核心问题，是所有用过AI编码助手的人都绕不开的：token消耗。不管你用的是哪家的模型，只要涉及多轮对话、代码上下文注入、工具调用，token就像沙漏里的沙子一样哗哗地流。一个中等复杂度的重构任务，来回几轮下来，几万token就没了。而caveman的思路是：与其让AI在每次交互时都重新理解整个项目结构，不如用一个轻量的本地代理层来管理上下文，把真正需要传给模型的信息压缩到最小。

它适合谁？如果你日常用AI辅助编码，但被token账单或者响应速度困扰，或者你手头有多个模型供应商的API key想要统一管理，再或者你单纯对“AI agent怎么和模型通信”这件事好奇，想找个代码量不大、结构清晰的参考实现来读，那caveman值得花时间研究。它不要求你懂深度学习，但需要你对HTTP代理、Node.js生态和基本的API调用有概念。

我花了几个晚上把这个项目从安装到实际跑通，中间踩了一些坑，也总结了一些文档里不会写的经验。下面我把整个拆解过程按模块整理出来，尽量让不同基础的朋友都能找到自己需要的部分。

2. 核心设计思路：为什么是“代理层”而不是“插件”

2.1 代理模式的选择逻辑

市面上AI编码工具和模型通信的方式大致有三种：直接调用API、通过SDK封装、或者走一个中间代理层。caveman选了第三种。这个选择背后有很实际的考量。

直接调用API的问题在于，每个模型供应商的接口格式、认证方式、错误码都不一样。你今天用A家的模型，明天想换成B家，代码里所有调用点都得改。SDK封装好一些，但SDK本身有版本依赖，而且不同语言的SDK成熟度参差不齐。代理层的思路是：在本地起一个HTTP服务，所有AI编码工具的请求都先发到这个本地服务，由它来负责路由、转换、缓存和token管理。

这样做的好处很直接。第一，统一入口。你的编辑器插件、命令行工具、甚至自己写的小脚本，都只需要知道本地代理的地址，不用关心背后是哪个模型。第二，上下文复用。代理层可以缓存项目结构、文件摘要、历史对话的压缩版本，避免每次请求都重新传输。第三，可观测性。所有请求都经过你手里，token消耗、响应时间、错误率一目了然。

注意：代理层不是万能的。它增加了网络跳数，如果本地服务挂了，所有AI功能都会中断。所以稳定性设计很关键，后面会讲怎么处理。

2.2 token优化的三个层次

caveman在token优化上做了三层处理，这个分层思路值得单独拎出来说。

第一层是请求去重。同一个文件在短时间内被多次引用时，代理层会识别出来，只在第一次传输完整内容，后续用引用ID代替。这听起来简单，但实现时要处理文件变更检测——如果文件在两次引用之间被修改了，缓存必须失效。

第二层是上下文压缩。对于长对话历史，不是简单截断，而是用一个小模型或者规则引擎提取关键信息。比如把十轮对话压缩成“用户要求重构X函数，已确认使用Y方案，当前卡在Z错误”。这个压缩过程本身也消耗token，所以需要权衡压缩收益和压缩成本。

第三层是按需加载。AI编码工具通常需要知道项目结构，但不需要一次性加载所有文件内容。caveman的做法是只传文件树和关键文件的摘要，当模型明确要求查看某个文件时再按需传输。这要求代理层能解析模型的工具调用请求，并动态响应。

2.3 与npx生态的集成考量

项目用npx作为分发方式，这个选择很务实。npx的好处是用户不需要全局安装，直接npx caveman就能跑起来，降低了尝试门槛。但这也带来一些限制：npx每次运行可能会检查更新，启动速度受影响；而且npx的缓存机制在不同Node版本下行为不一致。

我实测下来，如果网络环境正常，首次npx启动大概需要3-5秒下载依赖，之后有缓存会快很多。但如果你的项目对启动时间敏感，建议还是本地安装。另外npx运行时的工作目录是当前目录，所以配置文件的位置要特别注意，后面会详细说。

3. 环境准备与安装实操

3.1 Node.js版本选择与依赖检查

caveman对Node.js版本有要求，我建议用18 LTS或20 LTS。16也能跑，但某些依赖包会警告。安装前先确认版本：

node -v npm -v

如果版本太低，用nvm或者官方安装包升级。Windows用户注意，某些依赖需要编译原生模块，建议安装windows-build-tools或者直接用WSL。我在Windows上第一次跑的时候卡在node-gyp编译上，后来换了WSL就顺利了。

依赖安装有两种方式。全局安装：

npm install -g caveman

或者用npx直接运行：

npx caveman --help

npx方式适合快速体验，但如果你要长期用，还是全局安装更稳。全局安装后，配置文件默认在~/.caveman/config.json，npx方式则会在当前目录找.cavemanrc。

3.2 配置文件的关键参数

配置文件是caveman的核心，它决定了代理层怎么工作。一个最小配置大概长这样：

{ "port": 3456, "upstream": { "provider": "openai-compatible", "baseUrl": "https://api.example.com/v1", "apiKey": "your-key-here" }, "cache": { "enabled": true, "ttl": 300, "maxSize": "50mb" }, "logging": { "level": "info", "tokenStats": true } }

port是本地代理监听的端口，默认3456。如果冲突了可以改。upstream部分配置真实模型供应商的地址和密钥。注意apiKey不要直接写在配置文件里提交到git，可以用环境变量引用：

"apiKey": "${CAVEMAN_API_KEY}"

cache部分控制缓存行为。ttl是缓存过期时间（秒），maxSize是缓存上限。我建议初次使用时把ttl设短一点，比如60秒，观察缓存命中率后再调整。logging.tokenStats打开后会记录每次请求的token消耗，方便你分析优化效果。

实操心得：配置文件支持JSON5语法，可以写注释和尾逗号，对调试很友好。但注意npx方式下，配置文件查找顺序是当前目录 → 用户主目录 → 默认配置，优先级从高到低。

3.3 启动与验证

配置好后启动：

caveman start

或者用npx：

npx caveman start

启动成功会看到类似输出：

[caveman] proxy listening on http://127.0.0.1:3456 [caveman] upstream: https://api.example.com/v1 [caveman] cache: enabled (ttl=300s, max=50mb)

验证代理是否工作，可以用curl发一个测试请求：

curl http://127.0.0.1:3456/v1/models \ -H "Authorization: Bearer test"

如果返回模型列表或者一个合理的错误信息，说明代理层在正常工作。如果连接被拒绝，检查端口是否被占用，或者防火墙是否拦截了本地回环地址。

4. 核心机制拆解：token管理、代理转发与错误处理

4.1 token计数与预算控制

caveman的token计数不是简单调用一个库就完事。不同模型的tokenizer不一样，同一个文本在不同模型下的token数可能差20%以上。项目采用的方式是：优先使用上游API返回的usage字段，如果上游不返回，则用本地估算。

本地估算用的是tiktoken的JS移植版，但只对OpenAI系列模型准确。对于其他模型，caveman维护了一个粗略的映射表，按字符数和语言类型估算。这个估算肯定不精确，但用于预算控制足够了。

预算控制的逻辑是：在配置文件里设一个tokenBudget，比如每次请求最多5000 token。代理层在转发前会先估算请求的token数，如果超了，就触发压缩流程。压缩流程包括：去掉冗余的空白和注释、截断过长的文件内容、用摘要替换完整历史。

我实测下来，一个典型的代码补全请求，原始token数大概在2000-4000之间，经过caveman压缩后能降到1200-2500，节省30%-40%。如果是多轮对话场景，节省比例更高，因为历史对话的压缩空间更大。

4.2 代理转发的请求/响应转换

代理转发的核心是请求和响应的格式转换。不同供应商的API格式有差异，比如有的用messages数组，有的用prompt字符串；有的返回choices[0].text，有的返回choices[0].message.content。caveman在中间做了一层适配。

请求转换的流程是：接收客户端请求 → 解析出标准格式 → 根据上游供应商配置转换成对应格式 → 转发。响应转换反过来：接收上游响应 → 解析 → 转换成标准格式 → 返回给客户端。

这个过程中最容易出问题的是流式响应。很多AI编码工具依赖流式输出，但不同供应商的流式格式不一样。caveman的处理方式是：统一转换成Server-Sent Events格式，每个chunk包含一个delta对象。如果上游不支持流式，就模拟流式——先拿到完整响应，然后按句子或按token切分后逐个发送。

注意：模拟流式会增加首字延迟，因为要等完整响应回来。如果上游支持真流式，尽量用真流式。配置里有个streamMode参数，可以设成auto、force或off。

4.3 错误处理与重试策略

代理层作为中间人，必须处理各种上游错误。常见的错误类型包括：认证失败（401）、限流（429）、服务不可用（503）、超时。caveman对不同类型的错误有不同的处理策略。

认证失败通常意味着API key过期或无效，这种情况不重试，直接返回错误给客户端，并在日志里标记。限流的话，根据响应头里的Retry-After字段决定等待时间，然后重试。服务不可用和超时，采用指数退避重试，最多重试3次。

重试策略的配置在retry字段：

"retry": { "maxAttempts": 3, "baseDelay": 1000, "maxDelay": 10000, "retryOn": [429, 503, 504] }

baseDelay是首次重试的等待毫秒数，之后每次翻倍，直到maxDelay。retryOn指定哪些状态码触发重试。

我踩过的一个坑是：某些上游在限流时返回200状态码，但响应体里包含错误信息。这种情况caveman会解析响应体，如果发现错误字段，也触发重试。这个逻辑在parseErrorFromBody函数里，你可以根据自己用的供应商调整。

4.4 缓存机制的设计与失效

缓存是token优化的关键。caveman的缓存分两级：内存缓存和磁盘缓存。内存缓存用LRU策略，存最近使用的请求-响应对。磁盘缓存用文件系统，存较大的响应体。

缓存的key是请求的规范化哈希，包括：模型名称、消息内容、温度参数、最大token数。注意，如果请求里包含随机种子或者时间戳，缓存会失效。所以caveman在计算key之前会先剥离这些字段。

缓存失效的触发条件有三个：TTL过期、文件变更、手动清除。文件变更的检测是通过监听项目目录的fs事件实现的。当检测到文件修改，所有涉及该文件的缓存条目都会被标记为失效。

实操心得：缓存对代码补全场景效果最好，因为同样的上下文经常被重复请求。但对创意写作场景效果一般，因为每次请求的差异较大。你可以根据使用场景调整cache.ttl，代码补全可以设长一点，比如600秒。

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

5.1 启动失败与端口冲突

最常见的问题是端口被占用。错误信息通常是EADDRINUSE。解决方法有两种：换端口或者杀掉占用进程。换端口改配置里的port字段。查占用进程：

# Linux/Mac lsof -i :3456 # Windows netstat -ano | findstr :3456

如果不想每次手动处理，可以在配置里设port: 0，让系统自动分配空闲端口。但这样客户端就不知道端口号了，所以caveman会把实际端口写到一个临时文件里，客户端从文件读取。

另一个启动问题是Node版本不兼容。如果看到SyntaxError: Unexpected token之类的错误，大概率是Node版本太低。升级到18以上基本能解决。

5.2 请求超时与响应缓慢

请求超时通常有三个原因：上游服务慢、网络问题、代理层处理逻辑太重。排查顺序是：先看代理层日志，确认请求是否成功转发到上游；如果转发成功但响应慢，用curl直接请求上游对比；如果直接请求上游也慢，那就是上游的问题。

代理层处理逻辑重的情况比较少见，但如果你开了很复杂的压缩规则，或者缓存命中率很低导致频繁回源，可能会感觉到延迟。这时候可以临时关闭缓存和压缩，看响应是否变快。

我遇到过一次响应缓慢，最后发现是DNS解析问题。代理层在转发时用了上游的域名，但本地DNS服务器响应慢。解决方法是在配置里直接用IP地址，或者在hosts文件里加一条静态解析。

5.3 token统计不准确

token统计不准确通常是因为上游返回的usage字段和实际消耗有偏差，或者本地估算模型不匹配。caveman的日志里会同时记录上游usage和本地估算值，你可以对比两者。

如果偏差很大，检查你用的模型是否在caveman的支持列表里。不在列表里的模型，本地估算会用一个通用规则，准确度会下降。你可以手动在配置里指定tokenizer类型：

"tokenizer": { "type": "cl100k_base", "model": "gpt-4" }

cl100k_base是OpenAI常用的tokenizer。如果你用的是其他系列的模型，查一下对应的tokenizer名称填进去。

5.4 缓存导致响应不一致

有时候你会发现，同样的请求，第一次和第二次返回的结果不一样。如果缓存开着，第二次应该返回缓存结果才对。出现不一致说明缓存key计算有问题，或者缓存被意外清除了。

检查缓存key的计算逻辑，确保所有影响响应的参数都包含在key里。特别是temperature和top_p这种采样参数，如果没包含在key里，不同参数的请求会命中同一个缓存条目，导致结果混乱。

另外，如果上游返回的响应里包含时间戳或者随机ID，缓存返回的结果会显得“过时”。这种情况可以在返回前对响应做一次后处理，替换掉这些动态字段。

5.5 常见问题速查表

6. 进阶用法与扩展思路

6.1 多模型路由策略

caveman支持配置多个上游，然后根据规则路由。比如简单任务走便宜的模型，复杂任务走贵的模型。路由规则可以基于请求的token数、包含的关键词、或者客户端指定的标签。

配置示例：

"upstreams": [ { "name": "fast", "baseUrl": "https://api.fast.com/v1", "apiKey": "${FAST_KEY}", "rules": { "maxTokens": 1000 } }, { "name": "smart", "baseUrl": "https://api.smart.com/v1", "apiKey": "${SMART_KEY}", "rules": { "minTokens": 1001 } } ]

这样token数小于等于1000的请求走fast，大于1000的走smart。规则可以组合，比如同时按关键词和token数匹配。

6.2 自定义压缩规则

内置的压缩规则可能不满足你的需求。caveman允许你写自定义压缩函数，放在配置的compressors字段里。压缩函数接收原始消息数组，返回压缩后的消息数组。

一个简单的例子：去掉所有以//开头的注释行。

// compressors/strip-comments.js module.exports = function(messages) { return messages.map(msg => ({ ...msg, content: msg.content .split('\n') .filter(line => !line.trim().startsWith('//')) .join('\n') })); };

然后在配置里引用：

"compressors": ["./compressors/strip-comments.js"]

压缩函数按顺序执行，前一个的输出是后一个的输入。注意压缩函数应该是纯函数，不要有副作用，否则缓存会出问题。

6.3 与编辑器的集成方式

caveman作为本地代理，可以和任何支持自定义API地址的编辑器集成。以VS Code为例，如果你用的AI插件支持配置baseUrl，把它设成http://127.0.0.1:3456/v1就行。如果不支持，可以用环境变量覆盖，很多插件会读取OPENAI_BASE_URL之类的变量。

命令行工具的话，通常有--api-base参数。比如：

some-ai-tool --api-base http://127.0.0.1:3456/v1 --api-key dummy

注意api-key可以随便填，因为真正的认证在代理层和上游之间完成。代理层会用自己的key去请求上游。

实操心得：有些编辑器插件会校验api-key的格式，太短或者不符合规则会报错。这种情况可以填一个看起来像真的假key，比如sk-开头加32位随机字符。

6.4 监控与日志分析

caveman的日志默认输出到stdout，可以重定向到文件。日志格式是JSON Lines，每行一个JSON对象，方便用jq或者脚本分析。

统计token消耗：

cat caveman.log | jq -r 'select(.type=="token_stats") | .totalTokens' | awk '{sum+=$1} END {print sum}'

统计各模型的请求次数：

cat caveman.log | jq -r 'select(.type=="request") | .model' | sort | uniq -c

如果想把日志送到监控系统，caveman支持webhook配置，每次请求完成后POST一个事件到指定URL。你可以接自己的告警系统，当token消耗超过阈值时发通知。

7. 个人实操体会与几个小技巧

这个项目我从头到尾跑了大概两周，中间改过配置、写过压缩脚本、也遇到过各种报错。最大的体会是：代理层的价值不在于它多智能，而在于它把控制权还给了你。以前用AI编码工具，token怎么花的、请求发到哪了、响应为什么慢，全是黑盒。有了这层代理，每个环节都可以观测、可以干预、可以优化。

几个我觉得比较实用的小技巧。第一，先用默认配置跑一周，收集日志后再调优。不要一上来就改一堆参数，那样出了问题都不知道是哪个参数导致的。第二，缓存TTL从短到长逐步调整。先设60秒，观察命中率和响应一致性，没问题再往上加。第三，压缩规则要保守。过度压缩可能导致模型理解错误，反而增加来回次数。我一般只开请求去重和文件摘要，历史对话压缩设一个较高的阈值，比如超过5000 token才触发。

还有一个坑是关于npx的。npx每次运行会检查包更新，如果你的网络环境访问npm registry慢，启动会卡很久。可以设npm_config_update_notifier=false关掉更新检查，或者直接用全局安装。另外npx的缓存目录在不同系统下位置不一样，清理缓存用npx clear-npx-cache。

最后说一个扩展思路：caveman的代理层架构其实可以复用到其他场景。比如你有一个本地的小模型，想让它和云端大模型协同工作，可以用类似的代理层做路由——简单请求走本地，复杂请求走云端。或者你想给团队做一个统一的AI编码入口，把token预算按人分配，也可以在代理层加一层认证和配额管理。这个项目的代码结构比较清晰，改起来不算难，适合作为二次开发的基础。