NUS与北大发布Agent Retrieval Bench：交互Agent竟有35%从未摸到正确文件？

Agent Retrieval Bench: Evaluating Repository Context Retrieval for Coding Agents

论文原文 ↗ 论文发布 2026-07-27 解读发布 2026-10-03 解读：AI前沿分享

在过去一年多的时间里，以 SWE-bench 为代表的端到端基准成了评估软件工程智能体（Coding Agent）的事实标准。工业界与学界都在拼尽全力推高最终补丁的通过率（Resolve Rate）。然而，这种将整个开发流程压缩为“输入 Issue、输出 Patch、运行测试”的黑盒评测，在很大程度上掩盖了一个极其致命的前置阶段——上下文获取（Context Acquisition）。

ArXiv URL：https://arxiv.org/abs/2607.24882v1

在 Agent 真正提笔编写第一行修复代码之前，它必须先在包含数十万行代码的代码库中，准确找到应该阅读和修改的文件。如果这一步找错了，后续由大语言模型驱动的复杂推理、修改建议与验证环节，不过是在错误方向上的无用功。

针对这一长期缺乏系统评估的断点环节，来自新加坡国立大学（NUS）与北京大学的研究团队推出了专门针对代码智能体文件级检索的基准测试——Agent Retrieval Bench。该研究通过 25 个真实开源代码库、308 个冻结的提交快照（Base Commit）、39.2 万个文件以及近 800 万个代码切片，系统解构了 Agent 在编辑前寻找上下文的全过程。

实验暴露出一个令人警醒的现实：即便给主流开源与闭源 Agent 配备完善的文件读取与命令行探索工具，它们在 27% 到 35% 的任务中，整条交互轨迹自始至终都没有触碰过任何一个真正的黄金文件（Gold File）。当行业将焦点全部放在生成模型代码能力的微调上时，上游检索层早已成为了吞噬模型推理算力与导致任务崩溃的核心故障源。

颠覆传统代码搜索：什么是“智能体相关性”？

长久以来，学术界与工业界对代码搜索的理解主要停留在类似 CodeSearchNet 或 CodeXGLUE 的范式中：给定一段自然语言描述（如“解析 JSON 文件的函数”），检索系统在向量空间中去匹配语义最接近的函数实现。然而，真实软件工程中的 Agent 工作流根本不是这样运转的。

研究团队指出，在软件开发智能体的工作流中，文件检索的核心逻辑不是文本语义相似度，而是智能体相关性（Agentic Relevance）——即为了完成工作流的下一步操作，Agent 最需要阅读的代码库上下文是什么。在实际场景中，目标文件往往与当前手头的提示信息在字面上毫无相似之处。

为了把这种工作流依赖具象化，论文将智能体相关性拆解为四种正交的关系类型：

语义直接关联（Semantic-Direct）：Query 中暴露了目标路径或特定的符号线索，与传统搜索较为接近。
结构间接关联（Structural-Indirect）：Query 中的锚点文件通过代码库的拓扑依赖（如跨模块调用、继承关系或配置引用）间接指向目标文件。
工作流惯例关联（Workflow-Conventional）：源于软件工程的固定角色转换，例如开发者提交了一个核心模块的实现变更，Agent 下一步需要检索的却是对应的单元测试或回归测试文件。
因果间接关联（Causal-Indirect）：报错日志或调用栈中浮现的代码片段只是“受害者”，真正导致崩溃的根因（Root Cause）隐藏在下游的业务逻辑文件中，二者甚至使用完全不同的专业词汇。

正是因为存在这四类极其复杂且多变的关联，通用的密集向量检索（Dense Embedding）往往在此处水土不服。

贴合真实工程场景的四大正向任务与防守型子集

为了避免将评估降维成脱离工程实际的玩具测试，Agent Retrieval Bench 围绕开发者的真实日常，设计了四个正向检索任务与一个专门针对“拒答能力”的防守型子集。

首先是 code2test，模拟 Agent 接收到一个 Pull Request（PR）的改动意图或具体实现摘要，目标是找出代码库中关联的测试套件。这考查的是系统理解业务代码并定位验证逻辑的能力。

其次是 comment2context，模拟代码审查（Code Review）场景。系统向 Agent 提供一条评审意见以及正在被审查的文件，目标是检索出理解或满足该评审意见所需的额外上下文。在此任务中，已被提供的被审文件被严格划定为已知背景，不再计入检索目标，模型必须去跨模块挖掘隐藏约束。

第三是 trace2code，模拟故障排查。输入是复现失败的测试命令及截断的报错追踪（Traceback）。在真实的排查中，报错栈顶端的文件人人可见，因此基准明确将报错中可见的测试堆栈定义为“辅助证据”，真正的检索目标是引起该异常的根因源文件。

第四是 edit2ripple，模拟代码重构与变更影响分析（Impact Analysis）。任务给定一处已定位的代码修改锚点（Anchor Diff）及修改意图，要求系统检索出所有受到该修改波及、必须协同变更的源文件或测试文件。

除了这 345 个正向样本外，该基准还包含 82 个无黄金文件（No-Gold）的测试样本。其中 50 例为自然真实样本，这些 Issue 经真实开源仓库的维护者确认，根因完全在于上游第三方依赖、外部云服务中断或纯粹的用户环境配置错误，代码库内部根本不存在修复文件；另外 32 例则是反事实对照样本，将真实的 Issue 故意挂载到一个毫不相关的错配代码库中。这个子集专门用于考察检索系统在面对无解问题时，是否具备主动放弃检索（Selective Abstention）的自知之明。

在数据清洗与防泄露机制上，研究团队展现了极高的严谨度。所有的正向样本均在修改发生前的冻结基准提交（Base Commit）快照上进行评测，彻底排除了修复后代码的时光倒流泄露。同时，系统自动化诊断确保了所有数据无一例外地剔除了黄金文件绝对路径、原始 Patch 补丁、修复 Commit Hash 以及由大模型自动生成的审查建议。这意味着模型无法通过走捷径（Shortcut）“作弊”，必须凭借代码库的真实结构与语义逻辑硬碰硬地查找。

评测结果：没有任何单一检索范式能够称霸

在评测基准构建完成后，研究团队对比了三大检索阵营：传统的词法启发式检索（包含 TF-IDF 与增强符号权重的变体）、无向量的代码拓扑图检索（以 Aider 为代表的 RepoMap 机制），以及当前开源最前沿的代码与通用 Embedding 模型（包括 Qwen3-Embedding 系列的 4B 和 8B 版本、Jina-code、Perplexity 等）。

评测不仅考察传统的 Recall@k 和 MRR（平均倒数排名），还提出了极具工程参考价值的 BCY@B（Budgeted Context Yield，固定 Token 预算下的上下文产出率）。该指标模拟了真实 Agent 的上下文窗口限制：当把排序靠前的代码文件按顺序打包进 8K 或 16K 的 Token 预算中时，到底有多少比例的真正黄金文件能够被完整塞进上下文窗口。

完整的榜单数据展现出了极其明显的互补性与割裂感，没有任何一个算法家族能够在所有指标和任务上建立绝对统治：

密集向量模型的局部胜利：在 345 个正向样本的加权平均下，Qwen3-Embedding-4B 取得了最高的 MRR（0.2296），而参数量翻倍的 Qwen3-Embedding-8B 则在 Recall@20 上拔得头筹（0.7070）。
结构化图检索在紧凑预算下的逆袭：虽然纯依赖符号引用、代码调用图与目录层级的 RepoMap 在无截断召回率上落后于顶级向量模型，但在 BCY@8k（8K Token 预算有效产出）这一关键指标上，RepoMap 却超越了所有嵌入模型。原因在于 RepoMap 依靠代码骨架抽取的关键上下文密度极高，避免了向量检索容易被大体积无关长文件挤爆上下文窗口的尴尬。
任务特异性极强：在需要跨文件推导影响范围的 edit2ripple 任务中，模型的表现随着 Token 预算的变动发生剧烈翻转；而在富含报错信息与代码符号的 trace2code 任务中，结构检索与向量检索的优势区间完全不同。

这种割裂直接证实了论文的核心论断：Agent 检索不是单一维度的语义匹配，单纯堆砌向量模型参数量无法解决跨文件结构推理的问题。

为了验证这种互补性，研究人员进行了一个简单的后处理实验：将 Qwen3-Embedding-8B 的向量排序结果与 RepoMap 的拓扑结构排序结果，通过倒数排名融合（Reciprocal Rank Fusion, RRF, $k=60$）进行简单叠加。

实验结果令人振奋：这个没有任何额外训练参数的朴素混合系统，直接将整体 MRR 从单模型的最高分 0.2296 推升到了 0.2713，Recall@20 也同步提升至 0.7331。尤其在寻找 Bug 根因的 trace2code 任务上，RRF 融合后的 Recall@20 冲到了 0.8795，大幅超越了此前任何单一模型的表现。这向所有构建 Coding Agent 的开发者传递了一个明确信号：结合语义向量与 AST 依赖图的代码库上下文引擎，才是打破当前检索瓶颈的高性价比路径。

轨迹日志揭示的残酷真相与“校准鸿沟”

如果说静态的检索测试跑分揭示了算法的性能边界，那么基准中对真实交互式 Agent 运行轨迹的跟踪分析，则击碎了很多人对“大模型自主多轮探索能搞定一切”的盲目乐观。

当前工业界广泛采用的 Agent 架构，往往依赖模型自主调用 grep、find_by_name 或阅读指定目录等工具自主排查。研究团队深入分析了 OpenAI 严谨上下文 Agent（OpenAI strict-context agent）与 Codex CLI 在 287 个核心样本上的实际探索日志。

数据相当冰冷：

在整个探索流程中，OpenAI 架构下的智能体平均每个样本主动阅读 3.2 个文件，Codex CLI 平均触发约 6 次路径与文件交互。然而，OpenAI Agent 在高达 35.2% 的样本中，从开始到耗尽交互轮次退出，根本没有阅读过哪怕任何一个黄金文件；Codex 这一指标也徘徊在 27.2% 到 29.3% 之间。换言之，在超过三分之一的真实场景中，Agent 所有的分析和思考完全基于偏离航向的代码，最终合成的 Patch 自然免不了全面溃败。

不仅如此，即便是那些最终顺利触碰到黄金文件的成功样本，Agent 也展现出了明显的延迟感：OpenAI Agent 首次命中正确文件的步数中位数为第 2 步，而 Codex 则为第 3 步。前几步漫无目的的盲目探索不仅白白消耗了宝贵的输入输出 Token，拉长了系统响应延迟，更在多轮工具交互中向模型的上下文窗口注入了大量干扰噪声。

更为棘手的问题出现在选择性拒答（Selective Abstention）的评估中。

在真实软件工程中，优秀的架构师知道什么时候问题不在当前代码库内。但当模型面对 Agent Retrieval Bench 中的无黄金样本时，暴露出了严重的校准鸿沟（Calibration Gap）。如果系统使用人工构造的“反事实错配仓库”来调整相似度阈值，它看似能够轻易识别出那些极端不匹配的离谱查询；然而，一旦把这个阈值迁移到 50 个“自然无黄金样本”上，系统的拒答策略彻底失效。

面对那些描述得极其逼真、但实际上根因在上游依赖库中的真实 Issue，现有的检索系统根本无法在自身置信度上产生显著差异，它们依然会以极高的相似度分数把当前代码库中看似相关的业务模块排在前列，进而误导上层 Agent 开始煞有介事的错误分析。

精准上下文种子：治愈 Agent 漫游症的解药

为了进一步回答“一个更强大的上游检索器到底能为下游 Agent 带来多大收益”，论文进行了一项单轮闭环工具的受控干预实验（Seed-Intervention Pilot）。

研究人员固定下层 Agent 的推理策略，分别给其初始化注入三种不同质量的初始上下文“种子”（Seed Context）：

随机抽取的非黄金文件上下文；
基于上游检索系统输出的 Top 候选文件上下文；
完美的 Oracle 黄金文件上下文。

随后，记录 Agent 在获得种子后的文件定位精确度（File F1）以及后续主动触发工具进行二次探索的消耗。

实验得出了高度一致的因果结论：相较于随机上下文，由优秀检索器生成的初始上下文种子，能够让 Agent 以更少的后续探索调用，换取显著更高的最终文件定位 F1 分数。而第三组 Oracle 黄金上下文的表现则进一步揭示，当前检索层与理想上限之间依然存在着巨大的鸿沟——如果上游检索能做到 100% 精确，Agent 在后续交互中浪费在低效文件检索上的 Token 与时间成本将大幅下降数倍。

这也彻底扭转了过去的一种认知误区：有人认为随着大语言模型上下文窗口突破 100 万甚至 1000 万 Token，检索层将变得可有可无，只要把整个仓库塞给模型即可。而 Agent Retrieval Bench 的实验清晰地表明，上下文窗口变大并不等于模型的“有效注意力”无穷无尽。无序的长代码注入带来的“大海捞针”困境，不仅推高了延迟和调用成本，更直接劣化了模型的跨文件因果推导质量。在模型真正动笔写补丁之前，一个兼具语义理解与拓扑感知的专用代码检索层，依然是现代软件工程智能体不可或缺的基石。

重新思考下一代 Coding Agent 的系统架构

Agent Retrieval Bench 的推出，补齐了代码智能体领域长期缺失的重要拼图。它不再简单地将软件工程任务抽象为一个“输入问题、输出代码”的纯文本生成问题，而是第一次以极高的标准，对编辑发生之前的“代码侦察与获取能力”进行了全面体检。

这项工作给未来代码智能体的系统设计带来了极具实操价值的启示：

首先，必须在架构层面将“代码上下文检索”提升为与“代码编辑”同等重要甚至更前置的一级子系统。依赖大模型自主调用终端命令进行游击战式的盲目搜索，在三分之一的场景下会直接失焦。

其次，单一的技术路线已经走入死胡同。未来的代码检索引擎绝不能仅仅是一个通用的 Vector DB 加 Embedding，它必须深度内嵌程序分析技术，将 AST（抽象语法树）、符号调用图、Git 提交历史等结构先验，与高维语义向量有机结合起来。

当大家都在为大模型在 SWE-bench 上又微调提升了几个百分点而欢呼时，这项研究冷静地揭示了现实地基的松动。只有当上游的检索系统能够又快又准地把真正的黄金代码推到大模型眼皮底下时，那些惊艳的代码生成与自动化重构能力，才可能真正安全、可控地走入千万级企业的生产级代码库中。