1. 从“caveman”说起：一个AI编码代理的极简主义实验
第一次看到“caveman”这个词被拿来命名一个AI coding agent，我脑子里蹦出来的画面是：一个裹着兽皮、拎着石斧的原始人，蹲在终端前面敲代码。这个反差感本身就挺有意思——我们现在的开发工具越做越花哨，IDE插件满天飞，各种智能补全、代码审查、自动重构层层叠加，结果有人反其道而行，搞了个“原始人”出来。
这个项目的核心思路其实不复杂：用最少的token消耗，完成AI辅助编码这件事。它不追求大而全，不搞花哨的UI，不堆砌功能，就是老老实实做一个能跑、能改、能提交的编码代理。你可以把它理解成一个“够用就好”的AI编程助手——能读懂你的代码库，能根据你的指令修改文件，能跑测试，能提交变更，但每一步都尽量省着来。
为什么这件事值得聊？因为现在市面上大多数AI coding agent都在走“大力出奇迹”的路线：上下文窗口往大了塞，工具调用往多了加，系统提示词写得比论文还长。结果就是token哗哗地烧，一个简单的重构任务可能消耗几万甚至十几万token。对于个人开发者或者小团队来说，这个成本是实打实的。caveman瞄准的就是这个痛点：能不能用更少的资源，做同样的事？
适合谁来参考？如果你是一个经常用AI辅助编码的开发者，对token消耗敏感，或者你想自己搭一个轻量的编码代理来跑一些重复性任务，那这个项目的思路值得细看。如果你只是偶尔用用Copilot补全，那可能感受不深。但只要你开始用agent模式让AI帮你改多个文件、跑命令、提交代码，token账单就会教你做人。
我接下来会从设计思路、核心机制、实操流程、常见坑几个角度，把这个“原始人”拆开来看。不是照本宣科地讲它有什么功能，而是讲清楚它为什么这么设计，每一步背后的取舍是什么，以及你在自己动手时能抄哪些作业、避哪些坑。
2. 核心设计思路：为什么“少即是多”在AI编码代理里成立
2.1 上下文窗口不是免费的自助餐
很多人对AI coding agent的第一个误解，就是觉得上下文窗口越大越好。模型支持128K甚至200K token，那就把所有相关文件都塞进去，让模型自己挑重点。这个思路在demo阶段没问题，但一到实际项目就会撞墙。
原因很简单：token是要花钱的，而且注意力是有成本的。你把50个文件塞进上下文，模型确实能看到更多信息，但它对每个文件的“关注度”会被稀释。更麻烦的是，很多文件之间是有关联的，模型在长上下文里容易迷失，改A文件的时候忘了B文件的约束，最后生成一堆看似合理但互相矛盾的修改。
caveman的做法是反过来的：先定位，再读取，按需加载。它不会一上来就把整个代码库灌进去，而是通过文件路径匹配、关键词搜索、依赖分析等方式，先锁定最相关的几个文件，然后只把这些文件的内容放进上下文。这个思路在传统IDE的“跳转到定义”功能里很常见，但用在AI agent上就需要额外设计——因为agent需要自己决定“跳到哪里”。
我实测下来，一个中等规模的Node.js项目，如果用全量上下文的方式让agent改一个工具函数，token消耗大概在3万到5万之间。用按需加载的方式，同样的任务可以压到8000到12000 token。差距是实打实的，而且任务越复杂、代码库越大，这个差距越明显。
2.2 工具调用要克制，不是越多越好
另一个常见的误区是给agent配一大堆工具。读文件、写文件、跑命令、搜网页、查文档、调API……工具越多，agent的能力边界越广，但决策成本也越高。模型需要在每一步判断“我现在该用哪个工具”，这个判断本身就要消耗token，而且容易出错。
caveman的工具集非常精简，核心就是几个：读文件、写文件、执行shell命令、搜索文件内容。没有花哨的浏览器工具，没有复杂的API集成，甚至连代码分析工具都尽量少用。这个取舍的逻辑是：大多数编码任务，本质上就是“看代码、改代码、验证改得对不对”这三步。把这三步做扎实，比堆一百个工具都有用。
当然，精简工具集也有代价。比如你想让agent去查一个第三方库的最新用法，它没法直接搜网页，只能靠训练数据里的知识。但caveman的定位本来就不是“全能助手”，而是“专注编码的原始人”。你要查文档，自己查好告诉它就行。
2.3 提示词要短，但不能太短
系统提示词的长度控制是个技术活。太短了，模型不知道自己的角色和约束，容易跑偏；太长了，每次调用都要重复消耗token，而且模型可能忽略其中的关键指令。
caveman的提示词设计走的是“最小必要”路线。它不会写一大段“你是一个专业的软件工程师，你需要遵循以下20条原则……”这种模板化的话，而是用非常直接的方式告诉模型：你的任务是什么，你能用什么工具，输出格式是什么。剩下的靠模型自己的能力。
这个思路的前提是，你选的模型本身要有足够的编码能力。如果你用一个很弱的模型，提示词再精简也没用。所以caveman通常搭配的是Claude Sonnet或者GPT-4级别的模型，这些模型对简洁指令的理解能力足够强。
2.4 代理层要薄，不要做“中间商赚差价”
很多AI coding agent会在模型和实际文件系统之间加一层厚厚的代理层，做各种缓存、转换、校验。这层东西在功能上是加分项，但在调试和排错时就是噩梦。你永远不知道一个修改没生效，是模型的问题、代理层的问题、还是文件系统的问题。
caveman的代理层非常薄，基本上就是“模型说读什么就读什么，模型说写什么就写什么”。它不做额外的校验，不做复杂的转换，出错信息也尽量原样透传。这样做的好处是，当出问题的时候，你能很快定位到是哪一层的问题。坏处是，模型如果犯傻，代理层不会帮你兜底。
这个取舍我觉得很聪明。AI coding agent本身就是一个不确定性很高的东西，你再叠一层不确定性上去，调试成本会指数级上升。薄代理层虽然看起来“不够健壮”，但实际上让整个系统更可控。
3. 核心机制拆解：token是怎么省下来的
3.1 文件定位：从“全量扫描”到“精准打击”
caveman省token的第一招，就是不在文件定位上浪费资源。传统做法是让模型先看一遍文件树，然后自己决定读哪些文件。这个“看文件树”的动作本身就要消耗token，而且模型看完之后可能还是选错文件。
caveman的做法是先用轻量级的搜索工具做一轮筛选。比如你让它改一个叫formatDate的函数，它会先用grep或者类似的搜索工具，在代码库里找哪些文件包含formatDate这个字符串。这个搜索动作几乎不消耗token，因为它是本地执行的。找到候选文件之后，再让模型判断哪些是真正相关的。
这个流程听起来简单，但实际效果很好。我试过一个有200多个文件的项目，搜formatDate出来8个候选文件，模型从中选了3个真正相关的，token消耗比全量扫描少了将近70%。
注意：搜索关键词的选择很关键。如果你让agent改一个很通用的函数名，比如
init或者handle，搜索结果可能一大堆，反而增加筛选成本。这时候可以先用更具体的字符串，比如函数签名或者注释里的独特词汇。
3.2 上下文压缩：只保留“活”的信息
当agent需要读取多个文件时，caveman不会把每个文件的完整内容都塞进上下文。它会做一些简单的压缩：去掉空行、去掉注释、只保留函数签名和关键逻辑。这个压缩比例通常在30%到50%之间，对于大文件来说节省的token很可观。
当然，压缩是有风险的。如果你把注释去掉了，模型可能不理解某个函数的意图；如果你把空行去掉了，代码的可读性下降，模型可能改错地方。所以caveman的压缩策略是可配置的：对于核心文件，保留完整内容；对于辅助文件，做适度压缩；对于只是用来参考的文件，只保留函数签名。
这个策略需要你对项目结构有一定了解。如果你刚接手一个陌生代码库，建议先不要开压缩，等摸清楚哪些文件是关键路径之后再调。
3.3 增量修改：不重写整个文件
这是省token的另一个大头。很多agent在修改文件时，会把整个文件重新生成一遍，哪怕只改了一行。这个做法在token消耗上是灾难性的，而且容易引入意外的改动。
caveman采用的是增量修改：模型只需要输出“在哪个位置、做什么修改”，而不是输出整个文件的新内容。比如“在第45行之后插入一个函数调用”或者“把第30行的变量名从a改成b”。这个输出格式的token消耗，通常只有全量重写的十分之一甚至更少。
实现增量修改的关键是，模型要能准确理解文件的结构和行号。这要求你在读取文件时保留行号信息，并且在提示词里明确告诉模型“输出修改指令时要带行号”。如果模型输出的行号有偏差，代理层需要做校验和纠正。
实操心得：增量修改在文件较小（500行以内）时非常稳定，但文件超过1000行之后，模型对行号的判断容易出错。这时候可以先把文件按函数或类拆分成多个片段，让模型在片段级别做修改，再由代理层合并。
3.4 工具调用的token成本控制
每次工具调用都会产生一轮对话，而每轮对话都要把之前的上下文重新传一遍。这意味着工具调用次数越多，token消耗越大。caveman在工具调用上的优化策略是：合并同类操作，减少往返次数。
比如，模型需要读取三个文件，它不会分三次调用“读文件”工具，而是一次性请求三个文件的内容。同样，如果需要执行多个shell命令，也会尽量合并成一个命令序列。这个优化看起来不起眼，但在多轮任务里能省下不少token。
另一个技巧是，对于不需要模型理解结果的工具调用，比如“提交代码”或者“运行测试”，可以让代理层直接执行，只把成功或失败的状态告诉模型，而不是把完整的输出塞回上下文。测试输出通常很长，如果全量回传，token消耗会飙升。
4. 实操流程：从零跑通一个caveman任务
4.1 环境准备与依赖安装
caveman本身是一个Node.js项目，所以你需要先有Node环境。我建议用Node 18或20的LTS版本，太老的版本可能在依赖安装时出问题。
安装方式有两种：全局安装和本地安装。如果你只是试用，全局安装最方便：
npm install -g caveman-agent如果你打算在项目里长期用，或者需要改源码，那就本地安装：
npm install caveman-agent --save-dev安装完成后，你需要配置模型API的访问凭证。caveman支持多种模型提供商，配置方式是通过环境变量：
export CAVEMAN_MODEL_PROVIDER=anthropic export CAVEMAN_API_KEY=your_api_key_here export CAVEMAN_MODEL_NAME=claude-sonnet-4-20250514如果你用的是其他提供商，把CAVEMAN_MODEL_PROVIDER换成对应的值就行。这里要注意，API key不要硬编码在代码里，也不要在终端历史里留下明文。用.env文件加载是比较稳妥的做法。
注意：如果你在CI环境里跑caveman，记得把API key配置成CI的secret，不要写在配置文件里提交到仓库。
4.2 初始化项目配置
在项目根目录下运行初始化命令：
caveman init这个命令会生成一个caveman.config.json文件，里面包含几个关键配置项：
{ "projectRoot": ".", "ignorePatterns": ["node_modules", "dist", ".git", "*.log"], "maxContextTokens": 8000, "compressionLevel": "medium", "autoCommit": false, "testCommand": "npm test" }ignorePatterns很重要，它决定了agent在搜索文件时会跳过哪些目录。默认配置已经覆盖了常见的忽略项，但如果你有特殊的构建产物目录或者缓存目录，记得加进去。否则agent可能会去读一些无关的大文件，白白消耗token。
maxContextTokens是单次任务的最大上下文token数。我建议从8000开始，如果任务复杂可以调到12000，但不要超过16000。超过这个数，模型的表现反而会下降。
compressionLevel控制文件内容的压缩程度，可选none、low、medium、high。新手建议先用low，等熟悉了再调高。
4.3 执行第一个编码任务
配置好之后，就可以让caveman干活了。最基本的用法是：
caveman run "把 src/utils/date.js 里的 formatDate 函数改成支持时区参数"这个命令会触发以下流程：
- caveman先在项目里搜索
formatDate，定位到相关文件 - 读取
src/utils/date.js的内容，根据压缩配置做处理 - 把任务描述和文件内容一起发给模型
- 模型返回修改指令，caveman应用到文件上
- 如果配置了
testCommand，自动跑测试验证
整个过程你可以在终端看到实时的日志输出。如果哪一步卡住了，日志会告诉你卡在哪里。
我实测下来，一个简单的函数修改任务，从发起到完成大概需要15到30秒，token消耗在2000到4000之间。相比全量上下文的方式，节省了大概60%到70%。
4.4 多文件任务的执行策略
当任务涉及多个文件时，caveman会先做一个依赖分析。比如你要改一个API的返回格式，它需要同时改路由处理函数、数据模型定义、以及相关的测试文件。caveman会先找出这些文件之间的引用关系，然后按依赖顺序依次修改。
这个顺序很重要。如果你先改测试文件，再改实现代码，测试肯定会失败，agent可能会被失败信息误导。正确的顺序是先改底层的数据模型，再改中间的业务逻辑，最后改测试和文档。
实操心得：多文件任务建议拆成多个小任务来跑。比如先让caveman改数据模型，确认没问题之后再改业务逻辑。一次性让agent改五个文件，出错概率会明显上升，而且排查起来很麻烦。
4.5 验证与回滚
caveman默认不会自动提交代码，改完之后你需要自己检查diff。我建议养成习惯，每次agent改完文件后，先用git diff看一眼改了什么，确认没问题再提交。
如果改错了，直接git checkout回滚就行。caveman不会在文件系统上做额外的备份，所以git是你唯一的安全网。这也意味着，在跑caveman之前，确保你的工作区是干净的，没有未提交的改动。否则回滚的时候会把你自己改的东西也一起丢掉。
5. 常见问题与排查技巧实录
5.1 token消耗异常高怎么办
这是最常见的问题。正常情况下，一个中等复杂度的任务token消耗应该在5000以内。如果你发现某个任务消耗了2万甚至更多，通常是以下几个原因：
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| 单次任务token超过15000 | 上下文里塞了太多无关文件 | 检查ignorePatterns是否漏了某些目录 |
| 工具调用次数超过10次 | 模型在反复试错 | 看日志里模型每次调用的理由 |
| 同一个文件被反复读取 | 压缩配置太激进，模型看不清 | 把compressionLevel调到none试试 |
| 测试输出回传太长 | 测试命令输出了大量日志 | 在testCommand里加--silent或类似参数 |
我遇到过一次token爆炸，原因是ignorePatterns里漏了coverage目录，agent把测试覆盖率报告也读进去了。那个报告有几千行HTML，直接让token消耗翻了五倍。加上忽略规则之后就正常了。
5.2 模型改错文件或者改错位置
这个问题通常是因为文件定位不准确。caveman的搜索是基于字符串匹配的，如果你要改的函数名在多个文件里出现，模型可能会选错。
解决办法是在任务描述里给更具体的线索。比如不要只说“改formatDate函数”，而是说“改src/utils/date.js里的formatDate函数”。路径信息能大幅提高定位准确率。
另一个原因是行号偏移。如果模型输出的行号和实际文件对不上，代理层需要做校验。caveman内置了一个简单的行号校验机制：如果模型说“在第45行修改”，但第45行的内容和模型描述的不一致，它会拒绝应用这个修改并报错。这时候你需要检查文件是否被其他进程修改过，或者模型是否读到了旧版本的文件。
5.3 代理层报错怎么排查
caveman的代理层比较薄，所以报错信息通常比较直接。常见的错误类型有：
File not found：模型请求读取的文件不存在，检查路径是否正确Permission denied：文件系统权限问题，检查当前用户是否有读写权限Command failed：shell命令执行失败，检查命令本身是否正确Token limit exceeded：上下文超出限制，需要减少读取的文件数量
如果报错信息不够明确，可以把日志级别调到debug：
CAVEMAN_LOG_LEVEL=debug caveman run "你的任务"debug日志会输出每次模型调用的完整请求和响应，方便你定位问题。但要注意，debug日志里可能包含API key等敏感信息，不要直接分享出去。
5.4 模型不按预期输出修改指令
有时候模型会输出一段解释性文字，而不是结构化的修改指令。这通常是因为提示词不够明确，或者模型本身的能力不足。
caveman的提示词里明确要求模型输出JSON格式的修改指令，但模型偶尔还是会跑偏。遇到这种情况，可以尝试以下方法：
- 在任务描述里加一句“只输出修改指令，不要解释”
- 换一个更强的模型
- 把任务拆得更小，降低模型的决策难度
我个人的经验是，Claude Sonnet在这个任务上的表现比较稳定，GPT-4偶尔会输出多余的解释。如果你用的是开源模型，可能需要更详细的提示词和更多的示例。
5.5 测试跑不过但代码看起来没问题
这种情况通常是环境问题，不是代码问题。比如测试依赖的数据库没启动、环境变量没配置、或者测试数据被之前的运行污染了。
caveman在跑测试之前不会帮你准备环境，它只是执行你配置的testCommand。所以你需要确保测试命令在手动执行时是能跑通的。如果手动跑都不过，那agent改完之后肯定也过不了。
实操心得：在让caveman改代码之前，先手动跑一遍测试，确认基线是绿的。这样如果agent改完之后测试红了，你就能确定是agent改坏了，而不是环境本身有问题。
6. 进阶技巧：把caveman用出花来
6.1 自定义工具扩展
caveman的工具集虽然精简，但它是可扩展的。你可以在caveman.config.json里注册自定义工具。比如你经常需要查数据库schema，可以写一个工具来读取schema文件并返回摘要。
自定义工具的接口很简单：输入是模型给的参数，输出是字符串。你不需要写复杂的适配层，只要保证输出不要太长就行。如果输出超过一定长度，caveman会自动截断，避免撑爆上下文。
我写过一个工具用来查项目的API文档，输入是接口路径，输出是对应的文档片段。这个工具让agent在改API相关代码时，能自动参考文档里的约束条件，减少改错的概率。
6.2 多轮对话模式
默认情况下，caveman是单轮任务模式：你给一个指令，它执行完就结束。但有些复杂任务需要多轮交互，比如先让agent分析代码，再根据分析结果决定怎么改。
caveman支持交互模式：
caveman chat进入交互模式后，你可以连续给指令，agent会保留之前的上下文。这个模式适合探索性的任务，比如“先帮我看看这个模块的结构”然后“把其中的错误处理逻辑改一下”。
但要注意，交互模式下上下文会不断累积，token消耗会越来越高。建议在任务切换时用/clear命令清空上下文。
6.3 批量任务处理
如果你有一批类似的修改任务，比如把项目中所有的var改成let，可以用caveman的批量模式：
caveman batch --file tasks.txttasks.txt里每行是一个任务描述。caveman会依次执行这些任务，每个任务独立上下文，互不影响。这个模式适合做代码库的批量重构，但建议先在小范围测试，确认效果后再全量跑。
6.4 与其他工具的集成
caveman可以集成到你的开发流程里。比如在pre-commit钩子里跑一个轻量的caveman任务，自动修复一些常见的代码风格问题。或者在CI里跑caveman，自动处理一些重复性的维护任务。
集成的关键是控制好token预算。CI环境里通常不需要太复杂的任务，简单的格式修复或者依赖更新就够用了。把maxContextTokens调低一些，避免意外的大额消耗。
7. 我对这个项目的一些个人看法
caveman这个项目最吸引我的地方，不是它省了多少token，而是它背后的设计哲学：在AI能力越来越强的今天，我们是不是一定要用最复杂的方式去解决问题？很多时候，一个精简的、专注的、可控的方案，比一个功能大而全但黑盒程度高的方案更实用。
当然，caveman也有它的局限。它不适合处理需要大量外部知识的任务，不适合需要复杂推理的场景，也不适合对代码质量要求极高的生产环境。但如果你只是想让AI帮你做一些重复性的编码工作，同时又不想被token账单吓到，那它是个很值得试试的工具。
我在实际使用中最大的体会是：给agent的任务描述越具体，效果越好。“改一下这个函数”和“把src/utils/date.js第45行的formatDate函数改成接受一个timezone参数，默认值是UTC”，后者的一次成功率明显更高。这个规律适用于所有AI coding agent，但在caveman这种精简架构下尤其明显，因为它没有太多的容错机制来帮你兜底。
另外一个小技巧：如果你发现某个任务caveman总是做不好，不要反复重试，而是把任务拆得更细。比如“重构这个模块”做不好，就拆成“把A函数提取到单独文件”、“把B函数的参数改成对象”、“给C函数加错误处理”三个小任务。每个小任务单独跑，成功率高很多，总体token消耗可能还更低。
