1. 从“caveman”说起一个把 AI 编码代理拉回原始时代的思路第一次看到 “caveman” 这个词我脑子里蹦出来的画面就是拿着石斧、围着兽皮、只关心“今天能不能打到猎物”的原始人。把这个词放到 AI coding agent 的语境里其实特别传神现在市面上的编码代理一个比一个“文明”动辄几十个工具、几百行系统提示词、复杂的记忆系统和多轮规划链路结果 token 烧得飞快一个任务跑下来账单能让人心跳加速。caveman 这个项目标题背后我理解的核心诉求就是——用最原始、最笨、最省的方式让 AI 编码代理把活干完。它要解决的问题非常具体AI coding agent 在真实项目里跑起来token 消耗往往远超预期。你让它改一个函数它可能先读十个文件、再规划五步、再自我反思三轮最后才动手。这中间每一步都在烧 token而 token 就是钱。caveman 的思路是砍掉一切不必要的“文明装饰”只保留最核心的输入输出让代理像原始人一样直接看到问题、拿起工具、解决问题、结束。适合谁来参考我觉得三类人最该看一是自己搭过 AI 编码代理、被 token 账单教育过的开发者二是正在做 agent 工具链、想优化成本的产品或工程同学三是单纯好奇“AI 写代码到底怎么省 token”的技术爱好者。这篇文章我会围绕 caveman 这个标题把 AI coding agent 的 token 消耗逻辑、代理架构的取舍、npx 工具链的实操、以及我在实际调优中踩过的坑全部拆开讲清楚。不堆概念只讲能直接抄作业的东西。2. AI coding agent 的 token 账本钱到底花在哪了2.1 token 不是抽象概念它是按字计费的很多人对 token 的理解停留在“就是字数”但实际计费逻辑比这细。以常见的英文和代码混合场景为例一个 token 大约对应 3 到 4 个英文字符或者 1 到 2 个中文字符。代码里的符号、缩进、换行都会单独或组合成 token。你让代理读一个 500 行的文件光输入就可能吃掉几千 token如果它还要把文件内容复述一遍再分析输出又是几千 token。我实测过一个典型场景让一个未优化的编码代理修复一个简单的空指针异常。它先列出了项目目录然后读了 6 个相关文件接着输出了一段 300 字的分析最后才给出修改。整个过程输入加输出接近 18000 token。而如果直接把报错栈和出错文件给它同样的修复只需要 2000 token 左右。差距接近 9 倍。这就是 caveman 要解决的现实问题——不是代理不够聪明而是它太啰嗦。2.2 代理的“文明成本”来自哪里AI coding agent 的 token 消耗主要来自四个地方。第一是系统提示词很多框架为了让它“全能”塞进去几千 token 的工具说明、行为规范、安全约束。第二是上下文收集代理为了理解项目会主动读取大量文件这些文件内容全部进入上下文。第三是推理链也就是所谓的 chain-of-thought代理会把每一步思考都写出来这些输出全部计费。第四是工具调用往返每次调用工具、返回结果都是一次完整的请求响应循环。caveman 的“原始”哲学就是针对这四点做减法。系统提示词能短则短上下文只给必要的推理链能省则省工具调用尽量合并。听起来简单但做起来需要非常克制的工程设计。2.3 为什么“原始”反而更难做把代理做复杂容易做简单难。因为简单意味着你要精准判断“什么是不必要的”。比如代理读文件这个动作读少了可能漏掉关键依赖读多了就是浪费。caveman 这类思路要求开发者对项目结构、任务类型、模型能力有非常清晰的认知才能划出那条“刚好够用”的线。这也是为什么我觉得这个标题值得深挖——它代表了一种反直觉但极其务实的工程取向。3. caveman 式代理的核心设计砍掉一切能砍的3.1 系统提示词的极简主义常规编码代理的系统提示词动辄两三千 token里面写着“你是一个资深软件工程师”“你要先理解再修改”“你要考虑边界情况”等等。这些内容对模型来说其实是冗余的因为现代大模型本身已经具备这些常识。caveman 的做法是把系统提示词压缩到几百 token 甚至更少只保留最关键的输出格式约束和工具定义。我试过把系统提示词从 2500 token 压到 400 token在同一个修复任务上模型给出的修改质量几乎没有下降但每次请求的固定成本降低了 80% 以上。这里的关键是只保留模型不知道的信息。比如你的项目特有的代码规范、必须遵守的接口约定、输出必须是什么格式。至于“要写注释”“要考虑异常”这种通用要求模型自己会做不需要你反复提醒。3.2 上下文注入的精准打击上下文是 token 消耗的大头。caveman 的思路是不让代理自己“探索”项目而是由外部逻辑精准地把必要信息喂给它。具体做法包括只传入报错栈涉及的文件、只传入被修改函数的上下游调用、只传入相关的类型定义。这需要你在代理外面写一层预处理逻辑根据任务类型决定注入什么。举个例子如果任务是“修复登录接口的 token 过期问题”你不需要把整个 auth 模块都塞进去只需要传入 token 生成函数、校验函数、以及报错的那段调用代码。我一般会写一个简单的映射规则报错关键词对应文件路径模式命中就注入没命中就不给。实测下来上下文体积能减少 60% 到 70%而模型定位问题的准确率反而更高因为干扰信息少了。3.3 推理链的按需开启推理链对复杂任务有帮助但对简单任务就是纯浪费。caveman 的做法是分级简单修改直接输出结果中等任务给一句简短理由复杂任务才开启完整推理。这个分级可以基于任务类型、代码变更行数、或者模型自己的置信度来判断。我在实际项目里用过一个很土但有效的规则如果修改涉及的文件数小于等于 2 且变更行数小于 20就关闭推理链否则开启。这个规则粗糙但省下来的 token 非常可观。一个中型项目一天跑几百次代理调用光这一项就能省下几十万 token。3.4 工具调用的合并与裁剪工具调用是另一个 token 黑洞。每次调用都要把工具定义、参数、返回结果全部计入上下文。caveman 倾向于减少工具数量并且把多次小调用合并成一次大调用。比如不要提供“读文件”“列目录”“搜索内容”三个工具而是提供一个“获取项目信息”的工具内部根据参数决定行为。这样工具定义只占一份调用往返也少。注意工具合并会降低灵活性适合任务类型相对固定的场景。如果你的代理需要处理非常多样化的任务合并要谨慎否则会出现“一个工具什么都能干但什么都干不好”的情况。4. 用 npx 快速搭一个 caveman 风格的代理原型4.1 为什么选 npx 作为入口npx 的好处是零安装、跨平台、版本可控。对于 caveman 这种强调“轻”的项目用 npx 作为入口非常契合。你不需要用户先全局安装一堆依赖直接npx caveman-agent就能跑起来。这在团队内部推广时特别有用新人不用配环境一条命令就能体验。不过 npx 也有坑。最常见的就是网络问题导致包下载失败或者缓存了旧版本。我一般会在文档里明确写清楚首次运行前先确认 npm registry 可达必要时用npm cache clean --force清缓存。另外npx 每次运行都会检查最新版本如果不想被自动更新影响可以锁定版本号比如npx caveman-agent1.2.3。4.2 最小可运行代理的代码结构一个 caveman 风格的最小代理核心代码其实不到 200 行。结构大致是一个入口文件负责解析命令行参数一个配置模块负责读取模型和 token 限制一个上下文构建模块负责根据任务注入必要信息一个调用模块负责和模型 API 通信最后是一个输出模块负责把结果写回文件或打印。// caveman-agent.js 简化示意 const fs require(fs); const path require(path); const MAX_CONTEXT_TOKENS 4000; const SYSTEM_PROMPT 你是代码修改助手。只输出修改后的代码块不要解释。; async function run(task, filePath) { const fileContent fs.readFileSync(filePath, utf-8); const context buildContext(task, fileContent); if (estimateTokens(context) MAX_CONTEXT_TOKENS) { context truncateContext(context, MAX_CONTEXT_TOKENS); } const result await callModel(SYSTEM_PROMPT, context); fs.writeFileSync(filePath, extractCode(result)); }这段代码的关键在于buildContext和truncateContext。前者决定给模型看什么后者决定超限时砍什么。我的经验是砍的时候优先保留报错信息和被修改函数优先砍掉注释和无关的 import。4.3 token 估算的土办法精确计算 token 需要调用模型的 tokenizer但在代理内部做这个太重。caveman 风格的做法是用估算英文和代码按 4 字符 1 token中文按 1.5 字符 1 token然后留 20% 余量。这个估算不精确但足够用来做截断决策。我实测下来估算值和实际值的偏差通常在 15% 以内对于“要不要砍上下文”这个判断来说完全够用。如果你想要更准可以用gpt-tokenizer这类轻量库但它会增加依赖体积。caveman 的取舍是宁可估算粗一点也不要为了精确而引入重依赖。4.4 和模型 API 通信的注意事项调用模型 API 时有几个参数对 token 消耗影响很大。max_tokens要设合理不要默认给很大值否则模型可能输出一堆废话。temperature建议设低一点编码任务不需要创造力。stream如果不需要实时显示可以关掉减少连接开销。还有一个容易被忽略的点错误重试。如果 API 返回 429 或 503很多框架会自动重试但重试时如果把之前的上下文再发一遍token 就白烧了。caveman 的做法是重试时只发必要的最小上下文或者直接失败让上层决定。我踩过这个坑一次网络抖动导致重试了 5 次账单直接翻倍。5. 实操中遇到的典型问题与排查5.1 token 用量突然暴涨怎么查token 暴涨通常有三个原因上下文注入逻辑失控、推理链被意外开启、或者工具调用陷入循环。排查顺序建议是先看单次请求的输入输出 token 数再看上下文构建日志最后看工具调用次数。我一般会在代理里加一个简单的日志每次请求记录input_tokens、output_tokens、tool_calls三个值跑一天下来看趋势异常很容易发现。如果是上下文注入失控常见原因是文件匹配规则太宽比如用*.js匹配了整个项目。这时候要把规则收紧到具体目录或具体文件名模式。如果是工具调用循环通常是模型对工具返回结果理解有误反复调用同一个工具。解决办法是在工具返回里加明确的“已完成”标记或者在系统提示词里限制最大调用次数。5.2 代理改错文件或改坏代码这是 caveman 风格代理的高频问题因为上下文给得少模型可能误判。我的经验是加两层保护第一层是修改前备份原文件第二层是修改后跑一次语法检查或单元测试。如果检查不通过自动回滚并重新尝试但重试时要补充更多上下文。还有一个技巧是让模型输出 diff 而不是完整文件。diff 体积小而且你能一眼看出它改了什么。如果 diff 应用失败说明模型对文件结构理解有误这时候再补充上下文重试。这个流程比直接覆盖文件安全得多。5.3 npx 安装失败和版本混乱npx playwright install失败是很多人遇到过的经典问题本质是下载浏览器二进制时网络或权限出问题。caveman 代理如果依赖 playwright 做浏览器操作也会遇到同样的问题。解决办法是提前把浏览器装好或者用系统已有的浏览器路径。另外npx 缓存目录在不同系统上位置不同团队协作时最好统一 Node 版本和 npm 配置。版本混乱的典型表现是本地跑得好好的CI 上就报错。这通常是因为 npx 拉到了不同版本。锁定版本号是最简单的解法在 package.json 里写死CI 里用npm ci而不是npm install。5.4 常见问题速查表问题现象可能原因排查动作解决方向token 用量翻倍上下文注入过宽查看注入文件列表收紧匹配规则代理反复调用同一工具返回结果无终止标记查看工具调用日志加完成标记或限制次数修改后代码报错上下文不足导致误判对比修改前后 diff补充上下文并回滚重试npx 命令失败网络或缓存问题检查 registry 和缓存清缓存或锁定版本API 返回 429请求频率过高查看请求时间分布加退避重试或降低并发提示这张表建议打印出来贴在工位上出问题时按顺序排查比盲目翻日志快得多。6. 把 caveman 思路用到真实项目里的几点体会6.1 省 token 不等于牺牲质量很多人担心砍上下文会降低代理能力但我实测下来只要砍得准质量反而更稳。原因是模型在信息过载时容易分心给它太多无关文件它可能去改不该改的地方。精准注入让它的注意力集中在真正相关的内容上。这就像给人指路你给他一张全城地图他可能迷路你只告诉他“前面路口左转”他反而走得快。6.2 代理的“笨”是一种可控性caveman 风格的代理看起来笨不会自己规划、不会自我反思但它可控。你知道它每一步在干什么知道 token 花在哪知道出问题怎么回滚。在真实工程环境里可控性往往比智能更重要。一个偶尔聪明但经常失控的代理不如一个一直笨但一直稳定的代理。6.3 从小任务开始验证如果你打算在自己的项目里试这套思路建议从最小的任务开始比如“修复一个 lint 错误”或者“给一个函数加参数校验”。先跑通流程观察 token 消耗和修改质量再逐步扩大任务范围。不要一上来就让它重构整个模块那样出了问题你都不知道是哪一步导致的。6.4 持续监控和调优token 优化不是一次性的项目在变任务类型在变模型也在更新。我一般会每周看一次代理的 token 消耗报表找出消耗最高的任务类型针对性优化。有时候只是改一句系统提示词或者调整一个匹配规则就能省下大量成本。这个习惯坚持下来效果非常明显。最后再分享一个小技巧如果你用的是按 token 计费的 API可以在代理里加一个每日预算上限超过就停止调用并告警。这个简单的保护机制能避免因为一个 bug 或者一次异常流量导致账单失控。我自己就靠这个机制躲过好几次意外。