我们组的代码库在两年前涨到 130 万行,问题开始变味:不是「找不到」,是「找到了也不敢改」。一次改一个公共工具函数,全局引用有 400 多处,而其中 30% 是反射、字符串路径、动态导入——grep 搜不到、编译期也不报错。那半年我们因为这个回滚了 11 次。
后来我们建立了一套基于 tree-sitter + 调用图的「代码认知索引」,用来给人和 AI 同时提供「这个符号被谁用、怎么用」的地图。MCP 那篇(32 个工具让误调用率涨到 19%)讲的是 Agent 侧,这篇讲底层那条我们花了 19 周建的索引链。结论数据:改公共函数前能定位到全部真实影响面的比例,从 63.4% 提到 96.8%,回滚率从 9.1% 降到 1.4%。
一、为什么 grep 和 LSP 都不够
先把三个工具的边界说清楚,我们做了实测:
| 工具 | 强项 | 在 130 万行仓库上的失效点 | 实测覆盖率 |
|---|---|---|---|
| grep / ripgrep | 快、无状态、什么都能搜 | 字符串撞名、动态引用、跨服务约定 | 69.7% |
| LSP(go to definition / references) | 精确的类型与引用解析 | 需要打开 IDE、按项目加载、跨仓库不行 | 88.5% |
| tree-sitter + 调用图 | 语言无关、可离线、可喂给 AI | 动态分发、反射、运行时注入 | 93.4% |
覆盖率是真值——我们拿 12 个已知的「改这个函数会影响哪些服务」的历史案例逐个数,数出来的数字。LSP 的 88.5% 已经被我们惊讶了一次,但它死在两个地方:跨仓库引用(我们的服务拆在 23 个仓库)和没被打开的项目。Agent 不可能为了查一个引用打开 23 个 IDE。
而 tree-sitter 的价值是:它把「引用关系」从人的肌肉记忆和 IDE 状态里抽出来,变成一份能查询、能喂给模型的静态资产。剩下的 6.6% 缺口(反射等),我们后面用约定和显式标注补。
二、索引链怎么建:四个阶段,别跳步
2.1 阶段一:符号抽取,而不是文本切块
第一版我们用「每 200 行一个 chunk」做嵌入检索,答案检索命中率只有 41%。改成 tree-sitter 抽取符号后——函数签名、结构体定义、接口定义、类型别名——找回率涨到 78%。关键区别:代码的语义单位是符号,不是行块。一个 40 行的工具函数跨了两个 chunk,在两个 chunk 里都是半残的。
2.2 阶段二:引用图,分「确定」和「猜测」两级存
引用关系不能只有一条边,必须有可信度。我们存两种:
- 确定引用(compile-bound)。能被编译器/解释器验证的:类型、导入路径、直接调用。这类占 73.6%,可以在影响面计算里当硬依据。
- 猜测引用(heuristic)。字符串匹配到的同名字符串、注释里提到的符号名、路径构成的调用。这类不当依据用,只作「人工再看一眼」的提示。我们试过把它们也算进影响面,结果范围虚高 3 倍,等于没用。
2.3 阶段三:跨仓拼接,靠约定不靠语义
23 个仓库之间的引用是最大的坑。我们没有做聪明的语义推断,而是立了三条硬约定:所有跨仓调用必须走注册中心或生成好的 SDK stub;所有通过消息队列的解耦必须带 schema ID;所有反射调用必须在代码里留 @dynamic-bind(<target>) 注释。不满足约定的代码,CI 直接拦。这条是纯工程纪律,但它让 19~23 仓库之间的可追溯引用从 51.2% 提到了 82.9%。
2.4 阶段四:喂给模型的两层接口
- 精确查询层(结构化)。「谁调用了
refresh_token()」「这个结构体在哪几个包里被序列化」——结构化查询,毫秒级,结果可作为强事实。 - 语义检索层(向量)。「有没有处理过类似的幂等重试逻辑」——模糊语义,只做线索不给结论。两类都要标清楚类型,我们踩过让 Agent 把语义检索结果当确定事实引用给用户的坑,后来在系统提示里硬性写死了这个区分。
三、真实收益:改一个公共函数要多久
| 指标 | 建索引前 | 建索引后 |
|---|---|---|
| 定位全部真实影响面所需时间(中位) | 47 分钟 | 6 分钟 |
| 影响面定位完整率 | 63.4% | 96.8% |
| 改公共函数导致的回滚 | 9.1% | 1.4% |
| 新同学找到第一个可改点的时长 | 4.5 天 | 1.3 天 |
| 索引冷启动全量构建 | — | 21 分钟(增量 40 秒) |
最被低估的是最后两行。新人 onboarding 从 4.5 天到 1.3 天,比任何性能指标都更快说服了管理层继续投钱。而增量 40 秒意味着它可以挂在 pre-push hook 上而不被讨厌。
四、三个我们做错了的地方
- 一上来就想解析所有语言。我们同时上了 Go、Java、Python、TypeScript、Scala,Scala 的语法扩展拖了两周。后来按调用频次排:Go / TS / Python 先,Scala 用外部 stub 兜着。
- 把索引当一次性的项目交付。代码每周变,索引过期两周就等于没有。我们后来把它挂进 CI,任何公共签名变更必须同步更新索引,否则流水线红。索引是活物,不是交付物。
- 低估了「确定/猜测」区分的沟通成本。人和 AI 都会倾向于把猜测当确定用。我们对内的解法是UI 上和 API 返回里都用不同的视觉标记,让它难以被忽视。
- 漏掉了非代码但影响运行的配置。第一期我们只索引代码,结果一次线上故障是因为改了 YAML 里的 feature flag 名,而代码里用字符串引用它。后来把 Helm values、feature flag 注册表、环境变量清单也纳入索引,规则同样必须是显式注册,不允许在代码里裸写环境变量名。
4.5 给 AI 用的查询接口,和给人用的不是一套
这一点花了两周才想明白。我们最初把索引查询做成一个通用 API,人和 Agent 都用它。结果 Agent 拿到的是「400 个引用」的列表——它不知道先看哪个,也不知道这里面哪些是确定引用。后来我们给 Agent 的接口做了三处改造:默认返回确定引用、按「是否公共服务」「是否最近 90 天被改过」排序、单次最多返回 40 条并提示「还有 N 条,可继续翻页」。
改完之后一个明显变化:Agent 的「过度自信」型回答少了。以前它会说「没有其他地方引用这个函数」,现在它会说「在已索引的 12 个仓库中有 23 处确定引用,另有 6 处字符串匹配的待确认引用,需要人工核对」。后者啰嗦,但可信。
五、值不值得建:一个粗算的账
最后给想借鉴的团队一个成本视角。我们这套索引的总投入:2 名工程师 19 周,加上每年约 0.4 人月的维护。收益侧可量化的三块:
| 收益项 | 年化估算 | 说明 |
|---|---|---|
| 减少公共函数变更导致的回滚与故障 | 约 340 工时 | 按 11 次/半年降到 2 次/半年,每次平均 15 工时 |
| 新人定位可改动区域的时间 | 约 620 工时 | 全年入职 26 人,人均省 3.2 天 |
| Agent 代码任务的一次通过率 | 难单独归因 | 我们只在有索引的任务上做 A/B,通过率高 18 个百分点,但样本只有 240 个 |
前两项加起来约 960 工时,投入约 1,520 工时(含维护)。单看回滚和 onboarding,两年回本。但真正推动这件事立项的原因是第三项——没有索引,Agent 在大仓库里基本是在猜;有了索引,它至少能先查再动。在代码库超过 50 万行的团队里,这笔投入的性质正在从「效率工具」变成「AI 协作的地基」。
总结
130 万行代码的瓶颈不是读不完,是不敢改。把「谁在用它」从 IDE 状态和人的记忆里抽出来,变成一份随代码增量更新的结构化地图,这件事同时服务了人和 Agent——而后者需要的恰恰是「能被查询的确定性」,不是一堆相似 chunk。
如果只抄一条:引用要分「编译可证」和「猜测」两级,混在一起用等于没有。
互动提问:你们的代码库多大?有没有一套能回答「改这个会影响谁」的东西,还是靠问老同事?
互动提问:你觉得反射、动态注册、字符串路径这类「不可静态解析」的引用,更应该靠工具约束还是靠代码规范?我们选了规范,想知道有没有更好的路。
— IMAI 编辑部 | 2026-11-08