在大型仓库里,智能体真正难的不是写代码——而是找到那十二行真正相关的代码。
代码检索这个问题在 2026 年有了答案,而答案并不站在多数团队搭的那套东西这一边:Cursor 下掉了自己做了多年的语义索引,换成本地 grep;而 Claude Code 从来就没有过索引。原因不是嵌入检索失效了——而是搜索结果以什么方式进入上下文,比用哪个检索器更要紧。把智能体的代码导航建立在廉价、精确、结果内联、可反复收敛的搜索之上,把上下文预算花在「读」上,而不是花在「建索引」上。
步骤 1前沿的 harness 都收敛到了「不建索引的搜索」。
这值得当成事实而不是偏好来陈述,因为它推翻了很多团队内部编码智能体所依据的那套架构。
- Claude Code 没有代码库索引。它的导航原语是 glob、正则内容搜索和读文件,按需对工作区当前状态执行。没有嵌入存储,也没有同步任务,所以智能体看到的永远是磁盘上此刻的那份文件。
- Cursor 在 2026 年期间移除了语义索引。索引相关设置——包括重新同步和删除索引——从界面上消失了,检索改为一个在本地构建、本地查询的精确匹配索引,Cursor 把它称作 instant grep。Cursor 自己发在社区论坛上的理由是:模型使用 grep 和索引搜索的能力已经好到让那条专门的语义通路不再带来有意义的帮助。由于该索引与某个 git 提交绑定,非 git 目录会退回到纯
ripgrep。
两点提醒,免得你读过了头。某个版本具体调用哪个正则二进制程序已经变过不止一次,不是值得围绕它做设计的稳定事实。另外,至少有一份对比声称 Cursor 仍会在服务端计算加密的嵌入、用于搜索以外的用途,这一点存在争议;反复被陈述、因而稳定的那个说法范围更窄——搜索是 grep 形态的、且在本地。
下文描述的是截至 2026 年 11 月的状态。这个方向此前已经反转过一次(当时是转向支持索引),而且还可能再反转——所以这篇文章的重点是机制,不是比分。
步骤 2决定胜负的是结果的投递方式,不是检索器。
这里最有用的一项公开结果,也是最反直觉的一项。《Is Grep All You Need? How Agent Harnesses Reshape Agentic Search》(arXiv:2605.15184,2026 年 5 月)固定检索器不变,只改变其输出如何到达模型。当搜索结果内联在工具响应里返回时,grep 在受测的全部十组 harness 与模型组合上都胜过向量检索。而当同样的结果被写进文件、需要智能体再去打开时,向量检索赢了十组中的五组。
把它理解成关于回路的论断,而不是关于相似度数学的论断。内联结果是模型可以当场判断并立刻改进的东西——一个糟糕的正则只花掉一个便宜的回合,换来一个更好的正则。而以文件形式投递的结果,是模型必须先付出一次读取、才能知道这次检索好不好,这就奖励「第一次就命中」的检索器,惩罚反复收敛。精确搜索更适合做反复收敛的搭档,因为它的失败是可读的:零命中意味着符号拼法不对,四百个命中意味着这个词太泛。嵌入搜索则总会自信地返回它的 k 个最近邻,不管其中有没有一个是答案。
# the loop that makes exact search win hits = grep("refresh_token") # 0 hits -> the name is wrong, cost: 1 turn hits = grep("refreshToken") # 41 hits -> too broad, still cheap hits = grep("refreshToken.*expir") # 3 hits -> now read those # the loop that makes similarity search expensive docs = vector_search("token refresh expiry", k=8) # 8 plausible neighbours, no signal about whether any is right, # and you must spend 8 reads to find out.
所以给你的 harness 的设计问题不是「建哪种索引」,而是:你的搜索工具返回的每条命中是否足够丰富——路径、行号,以及周围几行上下文——好让模型在不打开任何文件的前提下就能决定下一步该打开什么。这一个选择比换检索器更值钱。
步骤 3索引仍然买到了什么,以及那份收益为何蒸发了。
语义检索的收益是真实的,而且被测量过。Cursor 自己早前的研究报告称,语义搜索相对纯 grep 平均带来约 12.5% 的准确率提升——这恰恰是「移除」这件事有意思的地方。那份收益没有被推翻,而是被吃掉了:被那些学会了把搜索工具用好、从而用正则加更多回合就能到达同样答案的模型吃掉了。
剩下的那片「索引仍然划算」的区域比看上去更窄:
- 提问者叫不出那个名字的查询。「我们在哪里处理重试退避」这句话里没有共享标识符,如果代码把它叫做
jitteredDelay的话。精确搜索找不到一个没人写下来的名字。 - 没有文档的遗留代码与糟糕的命名,也就是结构已经不再说真话的地方——元编程、动态分派、生成代码,或者
Handler出现在九个互不相关服务里的 monorepo。 - 面对超大代码树的延迟,这是产品层面的关切,而不是召回率问题。这正是以索引为基础的产品把索引留下来的那个安静的理由:等自动补全的人类的时间预算,和做一项四分钟任务的智能体的时间预算,不是一回事。
注意这三者的共同点:没有一条是「智能体找不到代码」。它们是廉价路径所需的回合数超过了你愿意支付的量。把索引当成一项附带同步任务的「延迟与命名优化」来定价——和混合检索与重排是同一套取舍逻辑,只是天平比处理自然语言时远远更偏向词法一侧。如果你确实要跑一个索引,失效问题才是真正的成本:索引新鲜度与失效解释了为什么过期的代码索引比没有索引更糟——它会满怀自信地返回一个已经不存在的行号。
步骤 4索引符号与调用图,而不只是文本。
扁平的文本索引回答不了「找引用」。基于解析器或 LSP/ctags/tree-sitter 构建的符号索引,把跳转到定义和查找引用作为原语工具交给智能体——也就是人类工程师在代码中穿行所用的同一套可操作性。这把导航从「读文件然后祈祷」变成了图遍历:从 issue 表面提到的符号跳到它的定义,再跳到它的调用方,每跳一次都在收窄候选修改范围,而不是把整份文件灌进上下文。
结构化搜索是 STEP 2 论点的补充,而不是它的例外,因为它具备让 grep 取胜的同一性质:答案精确,失败可读。一项关于结构化代码库索引的公开研究发现,它并没有重复能干的 agentic grep 已经能够达到的效果——而且同样重要的是,它也没有让智能体退步。这就是截至 2026 年末对结构化这一层的诚实总结:在可静态分析的代码上,它是一项真实的可操作性,而不是一次阶跃式提升。
# navigation as graph traversal, not file dumping hits = repo.grep(symbol) # lexical: exact, cheap, verifiable defn = repo.goto_def(hits[0]) # structural: one true site calls = repo.refs(defn) # who depends on this? ctx = budget.select(defn, calls, k=12) # keep ~12 spans, not 12 files
优先使用带窗口的视图,而不是整份文件。一个 open(path, line, ±40) 的取景窗能让智能体停留在相关片段上,并把预算留给调用图;而把一个 1500 行的模块整个倒出来,会把上下文窗口花在噪声上,之后每一个回合还得重新略读一遍。
步骤 5搜索很便宜;读取才是账单。
一旦搜索变得免费,约束条件就转移了,而多数团队把优化对准了错的那一半。在一个大仓库上做一次正则扫描,输出成本是几百个 token。打开它指向的那六个文件,成本是几万个 token——而且是永久性的,在这次运行的每一个后续回合里都要付——更何况一个名义上很大的窗口,远在被填满之前就开始退化,这正是有效上下文与标称上下文讨论的主题。
把窗口当成一份固定预算,在四个相互竞争的索取方之间分配:任务(issue 加复现步骤)、待修改的代码(你将要改动的那些片段)、证据(调用方、测试、能为这次改动提供依据的 trace),以及草稿区(智能体自己的推理与历史)。每一个花在无关文件上的 token,都是从证据那里偷走的。这里的纪律是无情的逐出:为验证某个假设而读入、而该假设已被推翻的文件,应当被压缩成一行并丢弃,而不是一直背着。
真正有效的结构性解法,是把昂贵的读取放到别处去。Claude Code 的做法是一个只读的探索子智能体,跑在更小的模型上、拥有自己的上下文窗口:由它去搜索和读取,然后返回一份摘要,于是主回路付的是结论的钱,而不是整份记录的钱。其中的取舍——这个受托者能看到什么、看不到什么,以及摘要什么时候会丢掉你正需要的细节——在子智能体继承了什么与塑形工具结果里。当主窗口无论如何还是满了,上下文压缩是退路,而它按构造就是有损的:把仓库地图和任务陈述钉住,别让压缩把它们吃掉。
one navigation turn, order of magnitude:
grep across 40k files, 12 hits with context ~ 700 tokens
read the 3 files those hits sit in ~ 24,000 tokens
read 40-line windows around the 12 hits instead ~ 3,100 tokens
the search was never the expense.
步骤 6失败模式是自信地定位错了,而不是漏掉了某个文件。
像 handler 或 config 这样的符号会匹配上数百个无关位置;语义检索则会返回看似合理但错误的邻居。不加过滤,这就是上下文投毒——模型锚定在一个被自信检索出来的错误文件上,然后去改它。缓解办法:按与出错栈帧的结构距离排序,而不只是按匹配数量;优先相信 traceback 点名的那个文件;并且要求智能体先陈述它的定位假设、并通过复现这个 bug 来确认它,再去编辑,这样一次糟糕的检索会被预言机(oracle)抓住,而不是被 diff 抓住。交接到补丁生成与测试的那一步,才是导航质量真正被衡量的地方。
U2 里最昂贵的失败是自信地定位错了:检索出来的文件看起来没错,补丁很干净,针对性的测试甚至通过了——而别处一条没有测试覆盖的调用路径现在坏了。高检索召回率而缺乏结构性依据,制造的正是这种结果;而且任何只检查「指定的那个测试是否变绿」的评测,都看不见它。
有两个便宜的习惯,比换检索器更能减少这种失败。第一,仓库地图——一份紧凑的、按重要性排序的顶层包、关键模块及其公开符号的提纲,也就是 Aider 推广开来的那项技术——只用几百个 token 就给智能体一副持久的骨架,于是导航从「认证相关代码大概在这一带」开始,而不是从零开始。第二,强制智能体为它关于代码的每一项断言给出路径和行号,这把一个无法被证伪的说法,变成了评审者一次点击就能核对的东西。
如果你今天就在搭这套东西:先把搜索结果做成内联且信息充分的(路径、行号、周围几行),再去建任何索引——2026 年 5 月那项 harness 研究说,这是收益最大的那一处改动。通过 LSP 或 tree-sitter 加上符号层,以获得跳转到定义与查找引用,因为它们的答案是精确的。给探索单独配一个子智能体和一个自己的上下文窗口,让读取不在主回路里累积。把仓库地图钉住,让它跨越压缩存活。而语义索引,只有当你能指着一类有日志记录、能点名、能给出计数的查询,说明精确搜索与结构化搜索在它上面失败了,才去加——因为它真正的代价不是嵌入,而是失效。