上个月我在调一套代码理解 Agent 的账单时发现输入侧 Token 的消耗比预想高出整整一大截。排查到最后锅根本不在模型推理而在每个请求都要把向量库命中的代码片段重新铺进上下文——检索一次就是一千多 Token多轮对话下来翻好几倍。很多人默认“给代码 Agent 配个向量库做语义检索”是标准答案但在我实际做过检索体系改造之后结论却很反直觉绝大多数场景下一个精简 CLI 反而比向量库更轻、更准端到端 Token 能省到四成上下。这篇文章想聊的就是这个取舍。我会解释向量库在代码检索场景里的真实成本模型说明一个只做“精确查询、按需展开”的 CLI 为什么能赢并把我实测到的数据、命令设计、对接方式和踩过的坑都整理出来。适合正在做代码 Agent、Copilot 类工具或者想优化 LLM 上下文消耗的团队参考也适合想搞清楚“Token 到底烧在哪”的开发者。1. 向量库在代码 Agent 场景里到底哪里“重”先说清楚一个概念这里说的“重”不是指部署费劲、硬盘占用大。向量库真正的成本发生在 Agent 每轮请求把检索结果塞进上下文的瞬间。存储和索引只是静态成本动态成本才是大头。1.1 成本不只是存储和索引而是每次请求的“搬运费”我见过很多团队给代码检索搭 Milvus、PgVector 这类服务索引几十万条函数切片embedding 模型跑一轮下来花不少时间。这确实是成本但一次性投入之后还会持续消耗的东西更隐蔽——每次 Agent 发起请求向量库里所有命中的片段都会被打包进 LLM 的 prompt再按 Token 计价。可以类比成不是买一个大书架贵而是每次要读书时都得把这书架上的书搬到书房里来回搬。向量库本身是书架真正烧钱的是“搬运费”。对一个 Agent 来说用户问“订单模块的支付状态流转”向量库可能会召回 5 段源码每段展开成 300 到 600 Token 的文本一次就是 1500 到 3000 Token。多轮对话中模型并不会自动记住上一轮看到的代码所以每次后续请求都要把相近的片段重新“搬”一遍。这个重复搬运开销是账面上最容易被忽视的部分。1.2 召回质量普遍比想象中差噪声直接烧 Token更麻烦的是代码语义和自然语言差异非常大。平时训练 embedding 模型的语料里代码往往只占一小部分而且代码本身的命名、结构、依赖关系很难被纯语义向量完全表达。函数名叫processOrder还是po_hdl查询“订单处理流程”时的召回表现完全不一样缩写、拼写错误、跨语言混排都会导致召回的片段文不对题。召回出来之后Agent 还得自己判断哪些片段有用、哪些没用。这个判断过程依然消耗 Token而且噪声越多模型越容易走弯路。我曾经在一个 40 万行左右的仓库里测试“库存回退逻辑”的语义查询向量库召回 6 个文件其中 3 个其实跟核心链路毫无关系展开到上下文里白白多了 1200 多 Token。最扎心的是模型并不能一眼看出“这段没用”它还得假装严肃地分析一下再决定忽略它——分析又花掉一批 Token。1.3 多轮对话中的“无效重复”是隐形成本向量库检索通常发生在工具调用层结果会被附到 system prompt 或者上下文窗口里。每轮请求这些检索片段都会重新覆盖一次因为 LLM 本身没有跨请求的记忆。如果 Agent 在一个任务里要连续调用 5 次工具那同一段代码可能被重复“搬运”5 次。上下文缓存能缓解一部分问题但大多数轻量化项目的缓存粒度根本做不到精细管理按段落、按符号级别的缓存很少见。更常见的是整个 prompt 原样重放前端刚消耗了一千多 Token 的检索结果后端又原样收一遍费。这里还没有算上输出侧的浪费——上下文越臃肿模型越倾向于啰嗦地复述自己“看到了什么”输出 Token 也会跟着水涨船高。2. 精简 CLI 的翻身逻辑用仓库本身的索引打败语义索引理解了上面的成本模型再来看 CLI 方案为什么会赢逻辑就很清晰了。CLI 的核心思路是不要用“语义向量”去模拟理解代码而是把代码库自带的确定性结构变成可查询的索引。2.1 代码库天生自带结构化索引每个仓库都是一个天然的结构化信息源。路径就是最朴素的语义索引——src/payment/state.go已经告诉你这是支付模块的状态函数名、类名、接口定义就是 keyAST 和符号表里还藏着完整的调用关系。这些信息不需要训练不需要 embedding原生就存在。代码 Agent 面对的问题有相当大比例可以降级成确定性搜索找符号定义、找调用者、找引用点、找文件路径。开发者问“ConfirmDialog 组件在哪定义的”CLI 用一行命令就能返回src/components/ConfirmDialog.tsx:12准确率 100%Token 消耗不到 20。换成向量库可能要先 embedding、再召回、再排序最后返回 3 段无关紧要的解释——两者效率差距一目了然。2.2 CLI 只回答精确问题不猜测模糊意图好用的代码检索 CLI设计原则是“把复杂问题拆成可验证的小查询”。Agent 负责把自然语言翻译成几条精确指令然后 CLI 返回可信的、可验证的结果。这种“可信结果”对 LLM 来说特别重要因为模型不需要脑补相关文件叫什么名字了——它只需要照着路径和行号去读。这其实是把 Agent 的思考成本从“猜文件名”转移到“读文件内容”。猜文件名这件事LLM 做得很差但读文件内容、理解逻辑、做修改决策LLM 做得很不错。我们应该让模型做它擅长的事把它不擅长的“记住代码位置”交给工具。2.3 输出即上下文真正的收益在 prompt 瘦身向量库方案的问题在于返回的是“大段包含语义的文本”因为 embedding 召回天然会把代码片段整体切出来。CLI 方案可以做到输出即上下文一个符号的定义被压缩成一行路径签名一个函数调用关系被压缩成几张表格一次 grep 结果被限制在 10 行以内。从复杂度角度看向量库方案的 prompt 成本是O(召回的 Token)跟召回片段数量和长度成正比CLI 方案则是O(命令输出)O(按需展开)大部分情况下我只会展开真正需要深入阅读的文件片段。这也是“四成 Token”节省的核心来源——不是模型变聪明了而是喂给它的东西变少了而且每一样都是它有实际需求的。3. 四十个百分点的 Token 节省是怎么算出来的说“省四成”不能只靠感觉下面给出我实际测算用的账本和场景。需要说明的是这不是严谨 A/B 实验而是我自己在一条真实开发任务上的对比记录但结构和方法是能复用的。3.1 先定基线完整向量库方案的 Prompt 构成设一个单轮请求中向量库方案的输入 Token 组成为系统指令约 300 Token向量库命中片段N 个片段平均每个 280 Token取 5 个片段就是 1400 Token历史对话记录约 800 Token当前用户问题约 50 Token单轮合计大概2550 Token。看起来还能接受对吧问题出在多工具调用的任务上。一个“帮我实现订单超时自动关闭”的任务Agent 往往要经历定位模块 - 看状态定义 - 找状态机实现 - 看定时任务 - 写代码这是 5 轮以上的工具循环。如果每轮都带着 5 个语义片段那就是 5 × 1400 7000 Token 的检索上下文消耗。3.2 CLI 方案的 Prompt 构成换成 CLI 之后同样任务我记录到的输入 Token 组成是这样的系统指令约 300 Token命令输出符号定位、引用列表、文件概览约 250 到 350 Token按需展开的真实代码片段只有 2 到 3 次每次 200 到 400 Token合计约 1000 Token历史对话记录策略性压缩后约 600 Token当前用户问题约 50 Token单轮合计约1850 到 2300 Token看起来只省了 10% 到 20%。真正的差距在多轮CLI 方案在第 1 轮拿到符号位置后后续轮次不需要重复检索——模型已经知道path:line需要看细节时直接按需展开而展开过的片段也会严格控制长度。于是整段任务的检索相关 Token 从 7000 降到大约 2000 到 2500光这一项就省了 65% 以上。3.3 实测数据对比我找了一个中等规模的 Go 仓库跑了一个“给订单状态机增加超时关闭逻辑”的开发任务。两种方案使用同一份历史对话记录、同一个模型区别只在检索工具层。输入类 Token 累计结果如下阶段向量库方案输入 TokenCLI 方案输入 Token节省比例第 1 轮任务理解与模块定位4,8602,65045.5%第 2 轮确认引用链路3,9501,72056.5%第 3 轮读取核心实现5,2003,11040.2%第 4 轮编写变更4,8803,02038.1%第 5 轮自检与修正3,7402,01046.3%合计22,63012,51044.7%这个任务里我的 CLI 方案端到端省了接近 45%所以标题里说“四成”其实偏保守。更重要的一个隐藏收益是上下文干净之后模型少走了很多弯路输出 Token 通常也能再省 10% 到 20%。你可以看到第 4、5 轮节省比例略低那是因为按需展开代码的占比上升了但这部分是有意义的 Token不是噪声。3.4 复现这套测算的方法如果你也想自己测记住一个原则不要只对比“单次请求的 Token 数”要对比“整段任务的累计 Token 数”。我用的方法是在每个 LLM 请求发出前用 tokenizer 离线计算 prompt 的 Token 长度再按工具调用轮次累加同时把系统指令、历史、检索片段分列记录。推荐手动记录三列数据检索工具名、返回的原始字节数、估算 Token 数。连续跑 3 到 5 个典型开发任务取平均就能得到你自己环境下的节省比例。你可能会发现越是需要多文件联动的任务CLI 方案的优势越明显。4. 落地一个“Agent 友好”的轻量 CLI设计与实现要点下面进入实操部分。我从零搭了一个内部代号zq的检索 CLI目前只有几千行脚本加少量原生模块核心思想可以完全复用到你自己的项目里。4.1 核心命令集设计这组命令不需要一开始全做完先做前 4 个就能覆盖 80% 场景。所有命令默认输出纯文本或 TSV后面加--json给 Agent 解析。# 查符号定义输出 path:line 函数签名 主体前 3 行 zq symbol # 查某个符号的所有引用最多 10 条 zrefs symbol --max10 # 输出文件内函数/类名清单 行号不输出函数体 zbrief file # 在指定目录做快速子串/正则匹配 zgrep pattern --rootdir --ignore-case # 扩展查 AST 依赖关系 zdeps symbol # 扩展按区间展开文件 zopen file --line41:60我特别强调zbrief的价值它只返回文件里的函数名和行号不返回函数体。因为很多时候 Agent 只需要知道“这个文件有哪些能力”不需要为了找这个信息把整个文件塞进上下文。这跟查字典是一样的逻辑——先看目录页再翻到对应页而不是把整本书背下来。4.2 把输出压进 300 Token 的硬性约束CLI 设计里最重要的一条约束是默认输出必须足够短。我给每个命令都设置了隐性的 Token 预算超出即截断并明确打上...标记让模型知道信息不完整、需要进一步展开。举个例子一个zq OrderState.Transition的输出应该长这样src/payment/state.go:41 func (s *OrderState) Transition(next Status) error // line 41: validates state transitions by (string of from/to) // line 44: marks timestamps triggers event bus ...它只给出主干信息函数体不完整展开。模型看到这个就知道“哦定义在 state.go 的 41 行状态转换有校验逻辑继续看细节要zopen state.go --line41:80”。这一步就把“看文件”变成了按需动作而不是一次性搬运。为了让这个策略可复现我给zq的输出格式定了三条铁律每个命中项只占一行路径用相对于仓库根目录的缩写。函数签名只保留返回值和参数类型注释只保留第一行。超过 10 条结果只显示前 10 条末尾输出... and N more。这三条直接把输出从“让人读”变成“让模型读”——对 Agent 来说信息密度高、数据结构稳定比华丽的格式重要得多。4.3 与 Agent 循环的对接方式CLI 命令天然适合作为 function calling 的本地工具暴露给 Agent。我在 OpenAI-compatible 工具协议里注册了zq、zrefs、zbrief、zopen四个工具模型发现自己不知道某个符号时会先调用工具拿到结果再继续推理。对接时要注意三件事第一支持--json结构化输出。zq payment_state --json会返回{ file: ..., line: 41, signature: ... }这样的结构方便 Agent 精确读取字段而不是让模型在一个大文本块里自己找信息。第二设置超时和退出码。检索工具必须在 2 秒内返回。如果仓库巨大导致命令超时不要让工具挂起直接返回 timeout 错误让模型知道这次检索失败需要换个更小的范围。退出码要分开设计0 表示正常1 表示无结果2 表示凭证/环境错误3 表示超时。第三做结果缓存。同一仓库的同一个检索命令在 30 分钟内直接返回上次结果以git rev-parse HEAD作为仓库版本标识。我试过最差情况一个大仓库第一次zq需要 600ms命中缓存后只需要 20ms这对 Agent 的多轮调用特别友好。4.4 索引构建的成本控制说到索引先澄清一个误解CLI 不一定需要跑索引。最简版本就是rg universal-ctags jq凑出来的这样的实现里zgrep走原生目录扫描zq走 ctags 生成的 tags 文件完全能工作。真正的索引是给超大型 monorepo 准备的用 tree-sitter 生成 AST 符号表一次性构建可能花几分钟存放在.zq-cache/目录。增量更新我用的是 git hook每次 commit 后触发一次局部更新只处理变更过的文件把构建时间控制在秒级。不要一开始就做全量复杂索引那会重蹈向量库的覆辙把成本重新堆回来。CLI 方案的核心竞争力就在于“简单”一旦复杂了它就跟它要取代的东西没有区别了。5. 哪些坑是真实测过的CLI 方案与向量库的边界CLI 不是银弹。我踩过不少坑也看到过一些做得很难受的方案这里把边界问题讲清楚。5.1 语义模糊请求仍然需要向量库有些查询本质上是模糊的比如“用户下单后超过 24 小时未支付就自动取消”这类业务规则开发者描述的是业务行为而不是具体代码标识符。这种情况下zq cancelOrder或zgrep 24h不一定能命中你需要让模型先借助 CLI 做结构枚举——列出订单模块所有文件、读取关键服务的zbrief、让 LLM 推理哪里可能藏着超时逻辑——再用小范围向量召回做二次排序。我最终的方案是混合模式先用 CLI 做“粗筛”让模型把候选文件压到 3 个以内然后只对这 3 个文件做向量片段召回。这样既保留了语义兜底又把向量库的 Token 消耗压到了原来的四分之一。这里的经验是不要因为向量库慢就彻底否定它把它挪到第二层“精排”效率反而最高。5.2 冷启动、超大型仓库与索引失效第一次 clone 回来的仓库CLI 可能没有任何缓存索引。这时候zq如果直接返回“符号不存在”模型可能真的以为代码里没有这个函数然后开始瞎写代码。解决方法是启动时先检测.zq-cache/是否存在不存在就直接在命令结果里加一行[index-missing] rebuilding...引导 Agent 先调一次zq --rebuild。超大型 monorepo 还有另一个问题符号表 JSON 可能膨胀到上百 MB加载本身就是灾难。我的做法是分层索引——默认只加载“最近活跃模块”的子符号表跨模块查询时才按需加载二级索引。听起来有点复杂但其实是拿着 monorepo 的依赖图做切片逻辑并没有那么可怕。另外Agent 经常读取的是工作区里未提交的代码而索引是基于已提交版本构建的。新旧不一致会让命中的行号偏掉模型按旧的path:line去读文件时看到的是别的内容。我最后改用 watchman 做文件监听文件变更后只更新受影响文件的符号保证索引尽量跟工作区同步。如果你暂时不想引入 watchman至少要在命令输出里带上 git hash让模型知道“当前检索的是哪个版本”。5.3 凭证过期与本地依赖的小坑最后说一个实务问题。CLI 方案如果需要访问远程仓库、私有包 registry 或调用外部服务就会遇到凭证管理的问题。自动化环境里最常碰到的是本地登录态过期检索工具静默失败Agent 得不到结果却已经为这次调用支出了一部分 Token然后开始“迷路”。我的建议很直接在 CLI 层做前置检查凭证无效时立刻返回明确的错误状态码和一句话说明不要让模型去猜发生了什么。输出的错误信息也最好固定句式比如ERROR: auth-expired, run: zq login模型看到能直接理解下一步动作。同时给命令增加一个--stats开关返回本次检索消耗的 Token 估算值方便你做成本审计。我就是在加了--stats之后才真正意识到“噪声召回”到底烧掉了多少 Token。另外提一句如果你计划把这套 CLI 打包成 npm 包或者分发到团队内部执行环境里的 Node 版本、系统依赖都会成为变量。最省心的办法是编译成单个二进制文件分发或者做成容器镜像减少“我这能跑你那不能跑”的尴尬。这个坑我踩过两次一次是环境变量缺失一次是动态链接库版本不一致都是“差一点”却特别折磨人的问题。根据我个人经验最值得先动手做的不是复杂的符号索引而是zq和zopen这两个命令。拿现有仓库跑一遍给 Agent 接上观察轮数和 Token 变化你很快就能看到上下文瘦身的效果。很多人以为代码检索必须用上“智能语义”但代码本身已经足够结构化我们真正该做的是把这种结构以最低成本输送给模型。向量库当然有它的位置但在代码 Agent 这个场景里先用轻量 CLI 把能确定的事情确定下来剩下的未知空间再去求助于语义才是 Token 花费效率最高的路径。