1. 项目缘起为什么我要折腾一个叫 caveman 的 AI coding agent第一次看到caveman这个词我脑子里蹦出来的画面是原始人拿着石斧敲键盘。但真正让我决定动手研究它的是最近半年 AI coding agent 这个赛道卷得实在太离谱了——从 Cursor 到 Claude Code从 Aider 到各种开源方案几乎每周都有新东西冒出来。而caveman这个名字本身就带着一种反讽意味当所有人都在堆功能、堆上下文、堆 token 的时候它偏偏用了一个原始人的名字暗示着某种极简主义的回归。我最初是在一个开发者社区里看到有人提到caveman说它是一个轻量级的 AI coding agent核心卖点是用极少的 token 完成代码生成和修改任务。当时我的第一反应是又一个蹭热度的玩具吧但仔细看了它的设计思路之后我发现这东西确实有点意思。它不像那些动辄要吃掉几万 token 上下文的方案而是试图用更聪明的方式去理解代码库、定位问题、生成补丁。说白了它想解决的核心问题是在 token 成本越来越高、上下文窗口越来越贵的今天怎么让 AI coding agent 既便宜又好用。这篇文章适合谁看如果你是一个日常写代码的开发者正在用或者准备用 AI 辅助编程但被 token 消耗和响应速度折磨过那这篇内容会对你有帮助。如果你是一个对 AI agent 架构感兴趣的技术人想了解一个轻量级 agent 是怎么设计的那也值得往下读。我会从设计思路、核心机制、实操部署、常见问题几个维度把caveman这个东西拆开揉碎讲清楚同时结合我自己踩过的坑给你一些能直接抄作业的方案。2. 核心设计思路拆解caveman 到底在省什么2.1 为什么 token 是 AI coding agent 的命门要理解caveman的设计得先搞清楚一个基本事实AI coding agent 的成本大头在 token 上。你每次让 agent 读一个文件、分析一段代码、生成一个补丁背后都是在消耗 token。一个中等规模的项目如果 agent 每次都要把整个代码库塞进上下文那 token 消耗是惊人的。我实测过一个大概 5 万行的 TypeScript 项目用某个主流 agent 做一次全量代码审查光输入 token 就烧掉了将近 80 万按当时的 API 价格算一次审查成本接近 3 美元。这还没算上它反复读取文件、来回确认的消耗。caveman的思路很直接与其让 agent 每次都看全量代码不如让它像原始人一样只关注眼前最需要的那块石头。具体来说它做了几件事第一用更激进的代码索引和检索策略只把跟当前任务相关的代码片段喂给模型第二用更紧凑的 prompt 格式减少冗余描述第三在 agent 的决策循环里加入 token 预算控制避免无限循环烧钱。这三板斧下来官方宣称能把 token 消耗降低到同类方案的 30% 到 50%。2.2 轻量级 agent 的架构取舍caveman的架构跟那些大而全的 agent 有明显区别。主流方案通常是一个复杂的多阶段 pipeline先做代码解析再做依赖分析然后规划任务最后生成代码。每个阶段都可能调用一次甚至多次模型token 消耗自然就上去了。caveman则倾向于把流程压缩能用规则解决的不调模型能用小模型解决的不调大模型。我拆过它的源码结构核心模块大概分四块索引器负责把代码库切成小块并建立检索索引检索器根据任务描述找到最相关的代码片段规划器决定下一步做什么操作执行器负责实际的文件读写和命令执行。这四块里索引器和检索器是省 token 的关键——它们决定了每次到底有多少代码会被送进模型。规划器和执行器则负责控制 agent 的行为边界防止它跑偏。这种设计的优势在于可控性。你可以清楚地知道每次模型调用大概会消耗多少 token因为送进去的上下文是经过检索筛选的不是一股脑全塞。劣势也很明显如果检索策略不够好agent 可能会漏掉关键代码导致生成的补丁不完整或者有 bug。这就是为什么caveman在检索环节下了很大功夫后面我会详细讲。2.3 跟主流方案的对比什么时候该用它我把caveman跟我用过的几个主流方案做了个对比方便你判断什么场景下该选它维度caveman重型全量 agent轻量补全工具token 消耗低按需检索高全量上下文极低仅当前文件任务复杂度中等适合局部修改高适合跨文件重构低适合单行补全部署成本中需要配置索引高需要大量资源低开箱即用代码理解深度中依赖检索质量高全局视野低局部视野适合场景日常 bug 修复、小功能开发大型重构、架构调整快速补全、样板代码从表里能看出来caveman卡在一个中间位置它比补全工具聪明能理解跨文件的上下文又比重型 agent 省钱不会动不动就烧掉几十万 token。如果你日常的工作主要是修 bug、加小功能、写测试那它挺合适的。但如果你要做的是大规模重构那还是得用重型方案因为检索策略再聪明也可能漏掉关键的依赖关系。3. 核心机制深度解析检索、规划与执行3.1 代码索引与检索怎么找到那块石头caveman的检索机制是整个项目最核心的部分。它的基本思路是先把代码库切成有语义的块然后给每块生成一个向量表示任务来了之后用相似度检索找到最相关的块。听起来跟 RAG 差不多但细节上有不少讲究。首先是切块策略。它没有简单地按行数切而是按语法结构切——函数、类、接口、类型定义各自成块。这样做的好处是检索出来的代码片段是完整的语义单元不会出现函数头在这块、函数体在那块的尴尬情况。我实测下来这种切法比按固定行数切的效果好很多尤其是对于 TypeScript 和 Python 这种结构清晰的语言。其次是索引更新。代码库是不断变化的索引不能只建一次。caveman用了一个增量索引的策略文件修改后只重新索引这个文件相关的块而不是全量重建。这个设计很实用我试过一个 2000 多文件的项目全量索引大概要 3 分钟但增量更新基本在秒级完成。注意索引质量直接决定 agent 的表现。如果你的项目里有大量动态生成的代码、或者用了很重的元编程检索可能会不准。这种情况下建议手动配置一些检索规则把关键文件标记为总是包含。3.2 规划器的决策逻辑怎么避免想太多规划器负责决定 agent 下一步做什么。这里有个经典的难题如果让模型自由发挥它可能会陷入过度思考——反复分析、反复确认token 哗哗地烧。caveman的做法是给规划器加了一个步骤预算和置信度阈值。步骤预算很好理解一次任务最多允许 agent 执行 N 步操作超过就强制停止。置信度阈值则是说如果模型对下一步操作的置信度低于某个值就不让它继续瞎猜而是直接报告需要更多信息。这两个机制配合起来能有效防止 agent 在模糊任务上无限循环。我自己的经验是把步骤预算设在 10 到 15 步比较合适。太少了任务做不完太多了又容易烧 token。置信度阈值则要看具体模型不同模型的输出分布不一样需要调几次才能找到合适的值。3.3 执行器的安全边界怎么防止手滑执行器是真正动文件、跑命令的部分也是最容易出问题的地方。caveman在这里做了几层防护第一所有文件修改都先写到临时区确认无误后才落盘第二危险命令比如删除文件、强制推送需要显式确认第三每次操作都有完整的日志记录方便回滚。这些设计看起来简单但实际用起来差别很大。我之前用过一个没有临时区的 agent它直接改了我的源文件结果改错了还没法撤销只能从 git 里恢复。caveman这种先写临时区再落盘的做法虽然多了一步但安全感强很多。实操心得建议把 agent 的工作目录跟你的主开发目录分开让它在一个副本上操作。确认结果没问题后再手动合并回主目录。这样即使 agent 出了什么幺蛾子也不会影响你的正常工作。4. 实操部署从零把 caveman 跑起来4.1 环境准备与依赖安装部署caveman的第一步是准备环境。它本身是一个 Node.js 项目所以你需要先装好 Node.js建议用 18 以上的 LTS 版本。我试过用 16 版本有些依赖会报错所以别省这一步。安装方式有两种一种是用npx直接跑适合快速体验另一种是克隆源码本地构建适合需要定制的情况。如果你只是想试试看用npx最省事npx caveman init这个命令会在当前目录初始化一个配置文件然后引导你填一些基本信息比如代码库路径、模型 API 配置、检索策略等。如果你要本地构建流程大概是git clone caveman-repo cd caveman npm install npm run build npm linknpm link是为了把caveman命令链接到全局这样你在任何目录都能调用。构建过程大概需要一两分钟取决于你的机器性能。注意如果你在公司网络环境下npm install可能会因为网络策略失败。这种情况建议配置好 npm 的镜像源或者用离线包安装。我遇到过好几次npx playwright install失败的情况基本都是网络问题导致的换成国内镜像源就解决了。4.2 配置文件详解每个参数都别乱填caveman的配置文件是核心里面有几个关键参数需要仔细设置。我拿一个典型的配置举例{ codebasePath: ./src, model: { provider: openai, name: gpt-4, maxTokensPerCall: 4000, temperature: 0.2 }, retrieval: { topK: 8, minScore: 0.75, alwaysInclude: [package.json, tsconfig.json] }, agent: { maxSteps: 12, confidenceThreshold: 0.6, dryRun: true } }这里几个参数值得展开说。maxTokensPerCall控制单次模型调用的最大 token 数设太小了模型可能看不全上下文设太大了又浪费。我的经验是 4000 到 8000 之间比较合适具体看你用的模型。topK是检索返回的代码块数量8 是一个比较平衡的值太少了可能漏掉关键代码太多了又增加 token 消耗。minScore是检索相似度阈值低于这个值的块不会被送进模型0.75 是我试出来的一个比较稳的值。dryRun这个参数特别重要建议一开始设成true。这样 agent 只会告诉你它打算做什么不会真的改文件。等你确认它的行为符合预期了再改成false让它实际执行。4.3 第一次运行从简单任务开始配置好之后别急着让它做复杂任务。先找一个简单的小任务试试水比如给这个函数加个参数校验或者把这个变量名改得更清晰。运行命令大概是caveman run 给 validateEmail 函数加上空值检查它会先做检索找到相关的代码块然后规划步骤最后生成补丁。在dryRun模式下你会看到它打算修改哪些文件、改成什么样。仔细检查一遍确认没问题后再关掉dryRun实际执行。我第一次跑的时候它把一个函数的参数校验加在了错误的位置原因是检索到的代码块不完整。后来我把那个文件加进了alwaysInclude列表问题就解决了。所以如果你发现 agent 老是漏掉某些关键文件记得手动把它们加进白名单。5. 常见问题与排查技巧实录5.1 token 消耗异常怎么定位和优化用caveman的过程中最常见的问题就是 token 消耗比预期高。可能的原因有几个检索返回的块太多、prompt 模板太啰嗦、agent 循环次数太多。排查的时候先看日志里每次模型调用的 token 数找到消耗最大的那几次然后分析原因。如果是检索的问题调小topK或者提高minScore。如果是 prompt 的问题检查一下你的任务描述是不是太模糊模糊的描述会让模型需要更多上下文来理解。如果是循环的问题调小maxSteps或者提高confidenceThreshold。我遇到过一次 token 消耗突然翻倍的情况查了半天发现是索引没更新检索到了一堆已经删除的旧代码。重新建索引之后就正常了。所以定期重建索引是个好习惯尤其是代码库变动比较大的时候。5.2 检索不准agent 找不到关键代码检索不准的表现是 agent 生成的补丁不完整或者改错了地方。原因通常是代码块的语义表示跟任务描述不匹配。解决办法有几个一是调整切块策略把粒度调细一点二是手动添加alwaysInclude规则三是改进任务描述用更具体的词汇。我处理过一个案例agent 老是找不到某个工具函数的定义因为那个函数的命名很抽象跟任务描述里的词汇对不上。后来我在配置里加了一条规则把utils/目录下的所有文件都标记为高优先级问题就解决了。5.3 执行失败权限、路径、依赖问题执行阶段的失败通常跟环境有关。常见的有文件权限不足、路径配置错误、依赖命令不存在。排查的时候先看错误信息然后检查对应的环境配置。我踩过的一个坑是路径问题配置文件里的codebasePath用了相对路径但我在不同目录下运行命令导致 agent 找不到代码库。后来改成绝对路径就没事了。所以配置文件里的路径尽量用绝对路径能省掉很多麻烦。5.4 常见问题速查表问题现象可能原因排查方法解决方案token 消耗过高检索块太多、prompt 冗余、循环过多看日志找消耗最大的调用调小 topK、精简 prompt、限制步数补丁不完整检索漏掉关键代码检查检索结果加 alwaysInclude、调细切块粒度执行报权限错误文件权限不足检查文件权限修改权限或换工作目录找不到代码库路径配置错误检查 codebasePath改用绝对路径模型调用失败API 配置错误或额度不足检查 API key 和额度更新配置或充值索引过期代码变动后未重建对比索引时间和文件修改时间重建索引或开启增量更新6. 进阶玩法把 caveman 集成进日常工作流6.1 跟 git 配合自动生成 commit messagecaveman可以跟 git 钩子结合在提交前自动分析改动并生成 commit message。配置方式是在.git/hooks/prepare-commit-msg里调用caveman的分析命令把生成的描述写进 commit message 模板。这样你每次提交都不用自己想描述agent 会根据 diff 内容帮你写好。我用了这个方案之后commit message 的质量反而比以前自己写的高因为它会分析改动的语义而不是简单罗列文件名。当然生成的内容你还是得看一眼确认没问题再提交。6.2 跟 CI 配合自动代码审查在 CI 流程里加一步caveman审查可以在合并前自动检查代码问题。配置大概是在 CI 脚本里加一行caveman review --diff origin/main...HEAD --output review.md它会分析这次改动涉及的代码生成一份审查报告。你可以把报告作为 CI 的产物或者直接评论到 PR 上。我实测下来它能抓到一些常见的代码坏味道比如重复逻辑、过长的函数、缺失的错误处理。虽然不能完全替代人工审查但能省掉不少机械性的检查工作。6.3 自定义检索规则让 agent 更懂你的项目每个项目都有自己的特点通用的检索策略不一定适用。caveman支持自定义检索规则你可以根据项目结构配置哪些目录优先、哪些文件总是包含、哪些模式需要特殊处理。比如对于一个 monorepo 项目你可以配置每个 package 的入口文件总是被包含这样 agent 在跨 package 修改时就不会漏掉依赖。我自己的配置里加了几条规则src/core/下的文件优先级最高*.test.ts文件在写测试任务时优先migrations/目录在数据库相关任务时总是包含。这些规则看起来琐碎但实际用起来能明显提升 agent 的准确率。7. 我个人的使用体会折腾caveman这段时间最大的感受是AI coding agent 的瓶颈不在模型能力而在工程细节。同样的模型检索策略不同、prompt 设计不同、执行边界不同效果能差出好几倍。caveman的价值不在于它用了多先进的模型而在于它在这些工程细节上做了很多扎实的优化。另一个体会是别指望 agent 能完全替代你思考。它适合做那些你已经知道怎么做、只是懒得手写的任务。如果你自己都没想清楚要改什么agent 大概率也帮不上忙反而可能把代码改乱。所以我的习惯是先自己想清楚方案然后用 agent 去执行最后自己审查结果。这个流程下来效率提升是实实在在的。最后分享一个小技巧如果你发现 agent 在某类任务上表现不好别急着换工具先看看是不是检索配置的问题。大部分情况下调一调检索规则就能解决。我遇到过好几次以为要换方案的情况最后都是靠调整配置搞定的。
