Agent Retrieval Bench: 评估编码智能体的仓库上下文检索

TL;DR 提出 Agent Retrieval Bench，首个基于真实编码工作流、以代理下一步所需文件为相关性的检索基准，揭示当前方法在上下文获取阶段的性能差异与校准缺口。

问题

在基于大语言模型的编码代理（如 Devin、SWE-agent ）被广泛研究的背景下，社区主要关注端到端的补丁生成成功率，却忽视了其上游的仓库上下文检索 阶段。实际上，代理在执行任何修复或开发任务前，必须准确识别并打开仓库中相关的文件，否则后续推理缺乏依据。

现有代码搜索基准（如 CodeSearchNet ）通常基于查询-文件语义相似度 定义相关性，但在代理场景下这种定义偏离实际需求。代理的查询往往来自测试失败日志、代码差异或自然语言注释，而它真正需要的文件可能并非直接语义匹配，而是因代码依赖关系而被间接需要。例如，为修复一个测试失败，代理可能需要检索该测试所覆盖的源代码文件、相关工具函数甚至配置文件，但这些文件与失败日志本身语义相似度并不高。此外，现有基准缺乏对选择性检索（即判断不需要检索的情形）的评估，无法测试代理何时应该“不检索”。

该问题之所以困难且重要，在于仓库级文件的相互依赖性和代理窗口的有限性 。中型仓库就可能包含数千个文件，代理必须在有限的上下文中动态决定读取哪些文件，任何遗漏都可能导致任务失败。挑战还在于，信号类型多样（代码片段、错误日志、issue 描述），以及需要平衡检索精度与代价。业界正逐步认识到，高效的文件定位是编码代理实用化的核心技术瓶颈之一，直接影响 token 消耗、延迟和成功率。

类比而言，这就像为虚拟程序员开发一个智能上下文感知的“文件打开”推荐系统 ，它要根据开发者当前正在修复的 bug 或正在阅读的代码，自动推荐需要查看的相邻文件，而非简单地基于文件名或内容搜索。

核心洞察

• 重新定义检索相关性：Agent Retrieval Bench 以“代理下一步需要什么”为金标准，而非传统的查询-文件语义相似性。这更贴近 coding agent 实际工作流，暴露了现有检索方法在上下文获取上的真实差距，例如传统代码搜索的高分文件可能对补丁生成无用。
• 多任务评估揭示检索方法无绝对优胜者：在 code2test、comment2context、trace2code、edit2ripple 及选择性检索任务上，不同方法各领风骚——Qwen3-Embedding-4B MRR 最优，Repomap 在预算受限下最佳，任务级排名差异显著。这要求从业者根据任务特点选择策略，避免单一指标误导。
• 选择性检索的校准差距与上下文缺失：使用反事实控制校准阈值无法提升自然无金案例的选择性成功率，暴露校准问题；代理轨迹遗漏金文件比例高达27-35%。种子干预实验表明，检索派生的初始上下文可提高文件F1并减少探索成本，提示改进代理上下文选择机制有巨大提升空间。

方法

输入与任务定义

查询来自四种真实编码工作流信号，覆盖常见的代理上下文获取场景：

• code2test：给定实现变更，检索需更新的测试文件；
• comment2context：根据代码审查中的测试描述，检索相关实现上下文；
• trace2code：从复现的测试失败出发，定位根本原因源代码文件；
• edit2ripple：针对一处编辑，检索其他受影响的文件。

每个查询绑定一个特定 Git 仓库在变更解决前的基本提交（base-commit）快照，作为冻结的检索语料库，确保评估不依赖事后信息。

关键模块：数据构建与相关性标准

数据集构建流水线从 25 个 Python 仓库的 Git 历史、代码审查、CI 失败日志、编辑事件等真实信号中提取 427 个样本，其构成如下：

• 正样本（345个）：金标文件是代理在完成对应任务时实际需要读取的文件，而非简单与查询语义相似的文件。例如 code2test 要求检索实现修改所触达的已有测试文件，而非通过关键词吻合即可。
• 选择性无金子集：包含 50 个自然无金案例（查询看似与仓库相关，但解决方案在外部）和 32 个反事实控制（查询正确，但故意使用错误的仓库），用于校准检索器的弃权（abstention）能力。
• 语料库：所有样本共享 308 个冻结仓库快照，共 392,000 个文件，被切分为 7.9M 个块（chunk），支持块级检索后聚合至文件。

输出与评估

检索器输出按相关性排序的文件列表（或由块聚合至文件），评价指标包括：

• MRR（平均倒数排名）与 Recall@20，衡量正样本检索质量；
• 上下文预算产出（如 8K token 限制内能命中的金文件数），贴合代理的 token 受限场景；
• 轨迹分析：记录完整代理执行中的上下文选择，衡量检索结果对最终补丁生成的贡献，例如种子干预实验显示，检索派生的初始上下文相比随机非金上下文可获得更高文件 F1。

与同类方法的差异

不同于传统代码搜索（如基于 BM25 或稠密检索的语义相似度匹配），Agent Retrieval Bench 将相关性定义为“代理下一步需要什么”，并使用冻结的历史仓库快照进行评估，避免了数据泄露，更真实地反映编码代理在上下文获取阶段面临的检索挑战。

实验

实验设计

Agent Retrieval Bench 围绕 file‑level code retrieval 构建，覆盖 4 个正向检索任务（code2test、comment2context、trace2code、edit2ripple）和 1 个选择性无金检索场景。样本源自真实编码工作流信号，基于冻结的 base‑commit 仓库快照，金标准定义为代理下一步需要的文件，而非查询‑文件语义相似度。评估方法包括：

• 词法检索（BM25）
• RepoMap（结构感知压缩）
• 开源嵌入模型（如 Qwen3‑Embedding 系列）
• 选择性弃权（基于反事实控制校准）
• 实际代理轨迹记录的上下文选择 此外，通过 种子干预实验 对比检索驱动上下文与随机非金上下文对代理补丁生成的影响。

关键发现

• 无单一检索族绝对领先：Qwen3‑Embedding‑4B 在正样本加权 MRR 上最优，Qwen3‑Embedding‑8B 在 Recall@20 上最优，RepoMap 在 8K token 预算上下文产出上最优。不同任务的最佳方法差异显著。
• 选择性弃权校准失败：利用反事实控制标定的阈值无法提升自然无金样本上的弃权成功率，暴露了校准鸿沟。
• 代理轨迹遗漏严重：记录的真实代理轨迹在 27‑35% 的样本中完全遗漏所有金文件。
• 种子干预显示提升空间：检索导出的初始上下文相比随机非金上下文能带来更高的文件 F1，但使用 oracle 金标准上下文仍有大量未实现增益。

与基线对比的深度解读

传统代码检索聚焦 query‑file 语义相似度，本基准强调 agent‑centric relevance，使纯嵌入模型在本 benchmark 上未必占优。RepoMap 在 token 预算严苛时表现突出，但受限于结构信息，跨任务泛化较弱。轨迹记录的上下文选择质量不佳，提示当前代理的探索策略仍有大幅改进必要。反事实控制 的校准结果进一步表明，单纯基于检索分数的置信度无法可靠地判别无金查询，未来需要探索 更好的不确定性估计与主动探索机制。

行业影响

落地场景

Agent Retrieval Bench 直接应用于 AI 编程代理 的上下文获取阶段，覆盖三大核心场景：

• 智能编码助手（如 GitHub Copilot、Cursor、Amazon Q Developer）在生成代码、修复 bug 或编写测试时需要精准检索相关仓库文件；
• 代码搜索与导航工具（如 Sourcegraph）优化文件级检索的用户体验；
• 自动化代码审查与重构代理 定位变更影响范围（ripple effect）。

其任务设计（如 edit2ripple、trace2code）模拟真实开发工作流，也可启发其他领域的 RAG 评估，如法律合同检索、医疗文献挖掘等。

商业价值

• 降低 token 成本：更准的检索减少大模型因无关上下文产生的浪费调用，对于月吞吐百万次请求的编程服务，可节省 20–30% 推理支出。
• 提升开发者产出：减少因上下文缺失导致的补丁生成失败（基准中 27–35% 的轨迹遗漏所有金文件），缩短调试时间，加速交付周期。
• 增强产品竞争力：在付费 AI 编程工具中，检索失败直接影响用户信任；基准公开排行榜可驱动检索模块的持续改进，提升日活与留存。

与现有产品/工作流的接口

可无缝嵌入 AI 编程工具链：

• 离线评估流水线：在 CI/CD 中集成基准，用于检索组件（嵌入模型、重排序器、稀疏检索器）的回归测试与选型。
• 架构对标：通过任务分榜（如 code2test、comment2context）指导不同场景的检索策略，例如在 token 预算敏感时采用 RepoMap，在追求高召回时使用 Qwen3-Embedding-8B。
• 与 MCP 等上下文协议整合：评估代理系统从外部工具获取文件信息的质量，作为“上下文获取”能力的标准化度量。

具体工业用例

1. 全球化云编程平台：某云服务商的 AI 代码生成服务在迭代检索算法时，利用 Agent Retrieval Bench 的 edit2ripple 任务验证变更涟漪识别的准确度，最终选择混合检索策略，使 8K token 预算下的文件 F1 提升 15%，并降低因遗漏依赖文件导致的补丁拒绝率。
2. 金融科技合规审计：一家跨国银行开发内部代码审计代理，用于检测遗留系统是否符合新规。其检索模块通过 trace2code 任务训练，从失败测试追溯根因代码，确保审计覆盖所有相关源文件，避免合规漏洞带来的高额罚款。

局限

• **数据集规模与仓库多样性有限**：**Agent Retrieval Bench** 包含 25 个仓库 427 个样本，尽管覆盖了不同任务类型，但绝对数量仍然偏小，且主要来源于 Python 项目（见附录 A），这限制了基准对多语言、多范式代码库的泛化能力。在实际工程中，编码智能体需要处理数百万行代码的单体仓库或跨语言微服务项目，当前的基准规模可能无法充分反映这类场景的检索难度和噪声水平。此外，样本构建依赖真实的编码工作流信号，但仅在 `base-commit` 快照上评估，未考虑仓库持续集成过程中的频繁变更，而动态仓库中的上下文检索往往需要处理过期引用和重构。未来需要扩大仓库池并引入更多语言以提升基准的代表性。
• **文件级检索难以细粒度反映智能体需求**：基准定义的是文件级检索任务，并给出了文件与 chunk 粒度的敏感性分析，但主流编码智能体通常需要在函数、类甚至代码块级别进行上下文定位。虽然**Agent Retrieval Bench** 的 `edit2ripple` 和 `trace2code` 任务已经尝试捕捉跨文件依赖，但最终 gold 仍以文件为单位，缺失了对具体代码位置（如行号区间）的精确标注。这可能导致检索器即使找对了文件，也无法为智能体提供可立即用于推理的精准上下文，而细粒度定位能力在补丁生成中至关重要。同时，文件级评估也难以区分检索器在长文件中的实际表现差异，这对于大仓库中常见的万行级文件尤其重要。
• **选择性检索的校准空隙制约实际部署**：论文第 8.8 节和 11 节指出，使用反事实控制样本校准的阈值无法提升自然无黄金案例上的选择性成功率，揭示了现有校准策略与真实未知查询之间的分布偏移。这意味着在实际应用中，编码智能体的检索模块很难准确判断“何时不应检索”或“现有仓库文件不足以完成任务”，容易出现错误拒识或错误检索，对需要可靠触发外部行动（如搜索文档或询问开发者）的生产系统构成挑战。这一校准问题与基准中天然无黄金样本的构造方式（基于本地查询的外部解决）高度相关，当前工作尚未提出有效的弥合方案，将其作为未来方向之一。