很多人第一次把整个代码仓库丢给 AI 的时候，都会经历同一个落差：问「这个项目的登录逻辑在哪」，它答得挺像样；再问「我要是改动这个校验函数，会影响哪些地方」，它就开始编——编出不存在的函数名、编出不存在的调用关系，语气还特别自信。
这时候常见的反应是「换个更聪明的模型」。但换完之后往往也就是好一点，没解决根本问题。因为这不是模型能力问题，是检索方式的问题：代码这种材料，和「一堆文档」的检索逻辑完全不一样。
这篇把「怎么让 Agent 真正读懂一个代码仓库」拆成四件事：检索手段怎么分工、上下文怎么给、索引怎么保持新鲜、答案怎么验证。全程围绕一个问题：让你问代码问题时，Agent 给的是有出处的答案，而不是看起来合理的猜测。
先说清楚：代码为什么不能用普通文档那套检索
文档问答的常规做法是「切片 → 向量化 → 按相似度召回」。这套放在代码上，有四个原理性的不适配：
- 切片会破坏语法结构。一段函数被从中间切开，剩下的半截既不是合法代码，也读不出意图。文档切歪了还能靠上下文猜，代码切歪了直接失真。
- 代码的含义大量依赖跨文件关系。「这个接口改了会波及谁」的答案根本不在任何单个文件里，它散落在整个仓库的导入、继承、调用关系上。
- 标识符需要精确匹配，语义相似反而有害。你问
parseInvoice，语义检索很可能把parseReceipt、parseBill排在前面。这些名字在人类看来很像，在代码里却是完全不同的东西——名字差一个词，行为可能天差地别。 - 仓库塞不进上下文。中型项目几十万行，就算窗口再大也不该全量注入——又贵又会被淹没。
换个角度说：文档问答要的是「找意思相近的段落」，代码问答要的是「精确定位 + 关系推演」。这两件事需要不同的工具。如果你已经把文档知识库做扎实了（企业内部知识库怎么搭、知识库检索怎么做才准确），会更容易理解这个差别——同样的入库、召回、重排思路，在代码上要换一套手感。
四类检索手段，各管一段路
真正好用的代码库问答不是「选一种检索」，而是让四种检索按顺序上场。它们的分工很清楚：
- 符号索引（AST / LSP）。做的是精确定位：这个类定义在哪、这个函数被谁引用、这个字段属于哪个模型。这是代码问答的主力，也是最容易被忽略的一环——因为它不像向量检索那样「AI 感」强，但它决定答案准不准。
- 全文精确检索。找字符串、配置项、日志文案、错误码。这类内容向量化之后几乎必然失真，直接精确匹配反而又快又准。
- 语义检索（向量）。用在「这个功能大概在哪个模块」「有没有类似的实现可以参考」「这段业务规则在哪提过」这类你不知道该搜什么词的问题上。它的价值是发现，不是定位。
- 调用图 / 依赖图。回答「改动影响面」「这串调用最终打到哪个下游」这类问题。这是代码问答相比文档问答独有的能力，也是最容易做浅的一环——只做一层引用统计，和多层次调用链分析，结论差别很大。
顺序上通常是：先用语义检索缩小范围（找到相关模块）→ 再用符号索引精确定位（找到具体定义）→ 再用调用图推演影响（找到波及面）→ 最后用全文检索补漏（找配置和文案）。反过来做也行，但先把范围收小再精确，成本最低。
上下文不要全塞，要「先给地图再点菜」
代码库问答最大的上下文陷阱是：要么全量注入（贵且没用），要么只召回几段（信息不够推理）。中间那条路是分层给：
- 第一层：仓库地图。目录结构、每个模块一句话职责、关键入口文件清单、技术栈和约定。这一层很小，几百到一两千字，但决定了 Agent 知不知道该去哪找。
- 第二层：命中的文件本身。让 Agent 自己根据地图和问题定位到几个候选文件，再把完整的文件内容给它——注意是完整文件，不是切片。代码切片的价值极低，一个 300 行的文件整体给进去，比给它五个片段有用得多。
- 第三层：必要的邻接信息。它调用的接口签名、它继承的基类、相关的类型定义。按需追加，不要预加载。
这个「地图 → 定位 → 加载」的三步走，本质上是把上下文预算花在它真正会读的地方。这和通用 Agent 的上下文管理是同一套思路，站内 上下文管理怎么做 里有更细的拆解，可以对照着看：代码场景的特殊之处只在于，你天然有一份现成的结构可以当索引，不用自己造。
还有一条经验：把项目的编码约定写进地图。比如「所有外部请求必须走 gateway 封装」「日期统一用 UTC 存储」「新增接口要同步更新 schema 文件」。这些约定不写进去，Agent 就会自作主张另起一套写法——这是代码类 Agent 最常见、也最难在事后发现的问题。
索引必须能跟上代码变化
代码库问答最隐蔽的失败模式是「索引过期」：Agent 基于三个月前的代码结构给你答案，说得头头是道，但那个函数早改名了。
要做到不过期，三件事是必须的：
- 按文件增量重建。每轮同步先比文件指纹，只对变化的文件重做解析和向量化。全量重建在中型仓库上动辄几十分钟，没人会天天跑。
- 挂到提交动作上。合并到主分支就触发同步，而不是靠人记得手动跑。定时兜底也行，但触发点越靠近变更越好。
- 把索引版本和代码版本绑死。每次回答要能说清「基于哪个提交」。这一点比看起来重要：出问题时你能立刻判断是「代码变了」还是「模型答错了」——前者重跑索引，后者才需要改检索。站内 模型版本管理 里讲「切换模型要跑回放验证」，是同一个思路：先能分清是哪一层变了，才谈得上修。
答案必须可验证：引用到文件行号
代码问答和文档问答有一个关键差别：代码答案对不对，是可以机械校验的。「这个函数在第几行」这种断言，去文件里看一眼就知道真假。
所以有一条硬要求：凡是指向代码的结论，都要带「文件路径 + 行号 + 关键片段」。没有引用的结论直接当不可信处理。这一条能挡掉大部分幻觉——Agent 编一个不存在的函数名很容易，但让它同时编出这个函数在哪个文件第几行，难度就大得多，而且一旦编了立刻能被发现。
配套的还有两点：
- 引用要被程序化验证。拿到回答后，用符号索引回查一遍：提到的文件存在吗？提到的函数在这个文件里吗？不一致就退回重查。这一步是自动的，成本很低。
- 关键结论要留证据链。涉及大范围改动的判断（比如「这次重构会影响到结算流程」），把检索过程、命中的文件、推理依据一起留下来。这就是代码场景版的证据包，思路和 证据包怎么留 完全一致——只不过留证对象从业务结论变成了代码结论。
三个最容易翻车的地方
第一，幻觉出「看起来合理」的方法签名。这是最普遍的问题：Agent 会照着项目里已有函数的命名风格，编一个并不存在的方法出来。防线就是上面说的引用校验——凡是没有文件行号背书的 API 调用，一律不信。
第二，只顾局部，无视全局约定。它读到了某一个文件的写法，就照着那个写法继续写，却不知道项目里早就有了统一封装。结果代码能跑、但风格跑偏，评审的时候一堆意见。防线是把约定写进仓库地图，并且在检索时优先注入约定文档，而不是只注入代码。
第三，索引过期带来的「自信的错误」。比幻觉更难发现，因为答案在写出它的那一刻是自洽的，只是对应的代码已经变了。防线是索引版本绑定 + 定期巡检：对仓库地图和关键文件做一遍一致性检查，把明显过时的条目挑出来。这和 知识库陈旧内容巡检 是同一件事，只不过对象换成了代码索引。
什么场景值得做，什么场景不值得
值得做：代码量大、新人上手慢、跨模块改动频繁、「这功能在哪 / 改了会影响谁」这种问题每天都要被问好几遍。这类场景里，代码库问答省下的是最贵的那部分时间——找代码和理解影响面。
不太值得：项目只有几千行（直接全量给模型就够了）、代码规范极差且没人维护（索引质量会跟代码一样乱）、或者团队真正缺的是「怎么改」而不是「在哪」——那是另一个问题，靠检索解决不了。
还想再往上走一层的话，这里有个判断顺序：先把符号索引和引用校验做扎实，再考虑要不要上图结构。如果问题进一步升级成「业务概念和代码模块之间的对应关系」，那是知识图谱要解决的问题，站内 知识图谱什么时候该上 里有更系统的判断标准。至于让 Agent 真正动手改代码、提 PR，那是另一个环节，OpenClaw 接 GitHub 那一套流程 可以接着看；而如果你要给 Agent 设计检索类工具本身，工具怎么设计才好用 里的描述、参数、返回格式几条经验可以直接套用。
总结
代码库问答做不准，八成不是模型不够聪明，而是把它当文档在检索。四件事按顺序做好，效果提升非常明显：
- 检索分工：符号索引管精确定位，全文检索管字符串，语义检索管发现，调用图管影响面。别指望一种手段包打天下。
- 上下文分层：先给仓库地图，再按需加载完整文件，绝不切片。约定要写进地图。
- 索引保鲜：增量重建、挂到提交动作上、版本和代码绑定。
- 答案可验证：所有代码结论必须带文件行号和片段，并且自动回查。
最后提醒一句：这四条里，第三条和第四条最容易被跳过，恰恰也最决定「敢不敢信」。一个答得慢但每次都能指到行的 Agent，比一个答得飞快但偶尔编造的 Agent 有用得多。上线前把门禁定好也很关键，站内 质量门禁怎么设 里的检查项可以照搬一份。
