给一个自主编码代理装上真正的代码库理解能力——不是让它靠 grep 东拼西凑，而是知道自己在改什么、改完会影响到哪里——这个念头一开始简单得像句口号。

开源社区早就有现成的工具：CodeGraph、code-review-graph 之类，用 tree-sitter 解析仓库，把每个函数、类、导入关系织成一张图。代理做任务时不反复翻文件，直接查图就行。

打开网易新闻 查看精彩图片

可我们的代理一下午要切十几个项目。如果每个都拉起一个后台 watcher 同步磁盘索引，留下一个 .codegraph 文件夹，即使任务早就结束，索引仍在运转。这种“膨胀税”是我们死活不想背的。

我们要的是一种不留驻留成本的聪明：代码图在任务需要时恰好出现，任务完成立刻消失。站在代理的操作窗口里，这就是一个按需召唤、精准相关、不带痕迹的临时图层。

说起来轻巧，造起来闹心。搭建过程中，代理犯了一个让我们头疼不已的错——它在八步循环里一口咬定我们自己的文件系统坏了。

它反复调用 list_dir，拿到的分明是正常结果，却坚称工具已经失效。换了三家顶尖的 LLM 提供商，行为一模一样，因为我们的系统本身就不挑模型。这不是权限问题，就是模型对着上下文窗口里的目录清单，硬要幻觉出一个文件系统故障。

追着这个错误，我们又挖出另外两个同类问题。三个教训逼我们重新理解了该怎么为自家代理量身定做代码智能，其价值甚至超过了原本想做的功能本身。

磨人之处都在细节。有时候，一段能用且简单的代码，远胜过几十个层层堆叠的功能，最后变成为 80% 用户用不着的臃肿软件。

2026 年那篇《检索即决策》的论文（Retrieval as a Decision，arxiv.org/abs/2511.09803）恰好帮我们补上了理论底气。它主张检索增强系统应当将“要不要检索”本身视为一个头等的、可训练的步骤，而不是钉死在固定流水线里。这正是我们后来搭建的路数，只是没走训练那一步。

现在，代理每接一个任务，在碰任何图之前，先被归进三个层级。单文件小修小改，完全不碰图，直接读文件。涉及三个及以上文件，或者碰到配置文件、通用类型模块这类共享文件，触发一次范围构建：只解析被修改的文件和它们直接引入的模块，向外探两跳深度。只有当用户明确要求一份真正的架构纵览时，才会跑一个全仓解析——进得深，出得也干净。

“用后即弃”的图形层就这样被塞进了代理的工作流里。没有常驻索引，没有内存泄漏般的后台进程，也没有在任务结束后依然存活的数据脏迹。可它该聪明的时候，一点也没含糊。