Agent Retrieval Bench：面向编码智能体的仓库上下文检索评测基准 Agent Retrieval Bench: Evaluating Repository Context Retrieval for Coding Agents
评测编码智能体在改代码前定位所需文件的能力，揭示检索无单一最优解
前置知识
BCY (Budgeted Context Yield)
预算约束下的上下文收益率。检索器把文件按排名贪婪装进固定 token 预算 B。BCY_τ@B=(1/N)Σ_i(1/|G_i|)Σ_{g∈G_i}1[m_{ig}(B)≥min(τ,L_{ig})]，m_{ig}(B) 为 g 装入的非头部 token 数。规范 τ=1 即曝光就给分。
传统 Recall@k 只关心文件是否进 top-k，但编码智能体真正瓶颈是 token 预算——一个 1500 行源文件就算排第一也可能塞不进上下文。BCY 把「能不能在预算内看到金标内容」量化成可比较曲线，是理解本文主表的关键。
RRF (Reciprocal Rank Fusion)
倒数排名融合，无需训练的混合排序法。对文件 f 在方法 m 中的排名 r_m(f)，融合分 s_RRF(f) = Σ_{m∈M} (60 + r_m(f))^{-1}，常数 k=60。论文 RRF-3 是 Qwen3-4B/8B 与 RepoMap 三方融合；文件不在某法 top-20 时贡献为零。
本文最重要的方法论发现之一就是「语义嵌入与结构化检索互补」，而 RRF 是验证这种互补性的最简手段。理解 RRF 才能看懂为什么简单的无训练混合就能把 overall MRR 从 0.2296 提升到 0.2713。
RepoMap (仓库结构图)
以 Aider 工具的 repo map 为灵感、纯结构化（vectorless）的仓库结构基线。不使用任何向量相似度，而用路径、符号、引用和仓库图信号（如源-测试路径重叠、同模块关系、符号共享）排序文件。它是「结构感知」方法族代表，与基于语义嵌入的 Qwen3 系列形成对比。
RepoMap 是 trace2code 任务的 MRR 和 Recall@20 双料冠军，也是整体 BCY@8k 的最佳方法，直接论证了「结构信号在某些工作流信号下不可替代」。要理解论文的「无单一最优」结论，必须理解 RepoMap 代表的方法族。
SWE-bench / SWE-agent
SWE-bench 是基于真实 GitHub issue 与解决 PR 构建的端到端软件工程评测，要求智能体生成通过单元测试的补丁；SWE-agent 是配套框架，评测完整 issue 解决工作流。SWE-Explore 是其延伸，研究固定行预算下的仓库探索。
Agent Retrieval Bench 的定位正是在 SWE-bench 这类端到端评测「之前」插入一层：端到端 patch 成功可能因检索、推理、编辑、验证任一环节失败，本文要把检索层单独隔离诊断。不熟悉 SWE-bench 就难理解本文「上下文获取层」在评测 pipeline 哪一段。
MRR 与 Recall@k
MRR（Mean Reciprocal Rank）对每个样本取第一个金标文件的倒数排名 1/rank 再平均，强调「金标出现越早越好」。Recall@k 是前 k 个去重文件中含金标的比例，k 常取 5/10/20。论文用 Recall@20 衡量「宽覆盖」，用 MRR 衡量「早命中」。
论文最有意思的发现之一是 MRR 领先者（Qwen3-4B）和 Recall@20 领先者（Qwen3-8B）不是同一个模型——4B 把成功命中放得更早，8B 在 top-20 里覆盖更多样本。要理解这种「排序深度敏感性」，必须区分这两个指标的语义。
Agentic Relevance（智能体相关性）
本文核心概念：一个文件是 agentically relevant 的，当且仅当读取它能实质性帮助智能体在工作流中走出下一个正确步骤，哪怕该文件与查询语义上不直接相似。论文把它分为四类可重叠关系：语义直接 D、结构间接 S、工作流约定 W（如实现→测试）、因果间接 C。
这是论文区别于传统代码搜索（query-document 语义相似度）的根本概念创新。理解它才能看懂为什么 trace2code 里「可见的测试/栈帧不算金标，真正的金标是根因源文件」，以及为什么论文要保留 realistic distractors。
研究动机
现代编码智能体（如 OpenAI Codex、SWE-agent）通常只用最终结果来评估：补丁是否通过测试、是否解决了 issue。但这种端到端度量掩盖了一个前置的「上下文获取层」——在智能体推理或编辑之前，必须先找到仓库里需要读的文件。日志数据显示，OpenAI 严格上下文智能体平均每样本只读 3.2 个文件，Codex CLI 恢复的上下文约 6 个文件/路径事件，可即便如此，这些交互式轨迹在 code2test/comment2context/trace2code 的 287 个样本上仍有 35.2%（OpenAI）和 27.2–29.3%（Codex）的样本完全没碰到任何金标文件。这意味着弱检索会被智能体用更多工具调用、token 和延迟「补偿」掉，端到端指标无法暴露上下文获取这一上游失败面与成本中心。传统代码搜索基准（CodeSearchNet、CodeXGLUE）又聚焦于函数/片段级的 query-document 语义匹配，与「智能体下一步需要的文件」语义不一致。
本文的目标是构建一个文件级的代码检索基准 Agent Retrieval Bench，把上下文获取层从端到端 patch 流水线中隔离出来单独评测。给定一个来自真实编码工作流的查询和冻结在 base commit 的仓库语料，检索器或上下文引擎需要对「智能体下一步会需要的文件」排序；基准不评测最终补丁能否合成，而评测上下文获取层能否在编辑开始前找到有用的文件、并能在真实的排名深度与 token 预算约束下做到。配套还要回答两类问题：正向检索能否找到 next-context 文件，以及选择性检索能否识别「仓库里没有可用本地上下文」从而弃权。
与已有工作不同的是，本文的独特切入角度有三点。第一，把「相关性」从 query-document 语义相似度重新定义为「工作流下一步需要的仓库上下文」——PR 实现信号要找的是回归测试，评审评论指向一个文件但缺失约束在另一模块，失败 trace 提到测试但根因是不相关的实现文件。第二，每条样本都从真实工作流信号构造（PR、评审评论、复现命令、锚定编辑），并冻结在 pre-resolution 的 base commit 上评测，从根本上杜绝「已修复代码泄漏」。第三，引入显式的 leakage 诊断（金标路径、原始 patch、修复 commit 哈希、模型生成产物四类均为零），保留 realistic distractors（可见但不足的文件），并提供 token 预算曲线 BCY、选择性弃权、轨迹成本与受控 seed 干预等多元评测面——这些都是 CORE-Bench、SWE-Explore 等近期工作没有同时覆盖的。
核心方法
整体直觉是：与其训练一个能搞定所有任务的通用检索器，不如先把「智能体相关性」这件事显式形式化、再用受控的工程化流程构造可验证的样本，让不同方法族的结构性差异暴露出来。技术路线分四步：(1) 从 25 个真实 GitHub 仓库挖掘 PR、评审、issue、CI 等工作流证据，构造任务特定的查询与金标；(2) 把仓库冻结在 pre-resolution base commit、对金标做证据审计与泄漏清洗；(3) 用一套统一的指标体系（Recall@5/10/20、MRR、BCY@B、弃权、轨迹成本）评测词法/结构/嵌入三类静态检索器，以及日志化的智能体上下文选择轨迹；(4) 通过受控 seed 干预把静态排序与交互式探索的因果链路接起来。基准刻意保持「诊断性」而非「web 规模」——427 个样本但每个查询都在 39.2 万文件、792 万 chunk 的大语料上搜索。
核心创新点是「agentic relevance」的形式化与四类工作流信号的正向任务定义。与已有方法的本质区别在于：相关性不由查询与文件的语义相似度决定，而由「读取该文件能否实质性推进工作流下一步」决定。这衍生出五个独特设计：(a) 四类正向任务 code2test（实现信号→相关测试）、comment2context（评审评论+被评审文件→额外上下文文件，被评审文件不算金标）、trace2code（复现失败命令→根因源文件，可见测试不算金标）、edit2ripple（锚定编辑→额外受影响文件，锚点不算金标）；(b) 用四类可重叠的相关性关系 D/S/W/C 描述查询-金标的多重联系；(c) 保留 realistic distractors 强制方法区分「可见、看似合理但不足」的文件；(d) 反事实错误仓库控制 + 自然证据支持弃权双层选择性评测；(e) base-commit 冻结 + 四类致命泄漏诊断保证评测卫生。这些是 CORE-Bench（强调规模）与 SWE-Explore（强调行预算与下游关联）所没有的组合。
方法步骤详情
数据构造分五步。第一步从 25 个有可重建 Git 历史、可用 PR/评审/issue/CI 证据的仓库采集：code2test 选同时改实现与已有测试的合并 PR，清洗后 PR 标题/正文+实现变更摘要为查询，证据关联测试为目标；comment2context 用内联评审评论+被评审文件+hunk 上下文为查询，被评审文件外、由首个有效评论后响应 commit 改动的额外文件为目标；trace2code 在 base commit 用测试侧变更复现失败，命令+失败摘录为查询，解决变更支持的实现文件为根因目标；edit2ripple 给定锚定编辑，其他证据关联变更文件为目标；自然弃权需维护者证据证明方案在仓库外，反事实则把合理信号与不相关仓库配对。第二步冻结仓库在 base commit 并验证正向目标存在。第三步清洗查询——移除原始 diff、修复哈希、精确目标路径、自动生成产物。第四步跑独立的模型辅助证据审计。第五步跑 schema、语料成员、去重、泄漏四类检查。指标用确定性 regex tokenizer 对标识符、数字 span、非空白符号计数，路径头计入预算。
技术新颖性
技术新颖性体现在五处。第一，BCY@B 是首个把 token 预算直接纳入检索排序评测的指标，并通过 τ 参数（1/16/32/64/128 敏感性分析显示最大绝对下降仅 0.0081）证明「一 token 曝光」给分不会扭曲排序结论。第二，四类可重叠的相关性关系 D/S/W/C 加上一个确定性 primary-label 投影（trace2code 选 C、code2test 在 d_i≥0.30 时选 D 否则 W 等），既保留多标签真实又提供不相交切片分析。第三，反事实错误仓库控制与自然证据弃权的双层分离设计——论文用这套设计证伪了「顶部分数能做仓库无关弃权」的朴素假设（mixed 协议看似成功，natural-only 协议下三个 ranker 全部下降）。第四，把静态排序、日志轨迹、受控 seed 干预、闭工具 Docker 隔离策略四种评测面统一在同一个金标集上。第五，把 PES@k（潜在探索节省）定义为可避免的金标定位延迟上界代理，并在 16/40 样本配对轨迹上用 Spearman ρ=0.674/0.529 校准其与真实首金步骤缩减的关联。
实验结果
核心发现：无单一检索方法族能跨工作流信号与上下文预算同时取胜。345 正向样本上，Qwen3-4B 拿最佳加权 MRR 0.2379，Qwen3-8B 拿最佳加权 R@20 0.7029，RepoMap 拿最佳 BCY@8k 0.3788；任务宏下 BCY 领先反转为 Qwen3-8B。任务赢家截然不同：code2test 是 Qwen3-4B 0.3225，comment2context 是 jina-0.5b 0.3043，trace2code 是 RepoMap 0.2742，edit2ripple 是 pplx-4B 0.2877。仓库均衡把 R@20 领先者反转回 Qwen3-4B。trace2code 是最强「嵌入不够」证据：RepoMap 双第一，MRR 冠军 Qwen3-4B 在该任务 MRR 仅 0.0827。RRF 混合把 overall MRR 从 0.2296 提到 0.2713。日志轨迹显示 OpenAI/Codex 仍有 27–35% 样本不触金标。seed 干预显示检索种子 +0.075 F1、Oracle +0.3115 揭示 headroom。
查看结构化数据
| 任务 | 指标 | 本文 | 基线 | 提升 |
|---|---|---|---|---|
| 整体正向检索（345 样本，加权） | MRR / Recall@20 / BCY@8k | Qwen3-4B MRR=0.2379；Qwen3-8B R@20=0.7029；RepoMap BCY@8k=0.3788 | BM25 MRR=0.1520 / R@20=0.4452 / BCY@8k=0.2051 | 最佳 MRR 比 BM25 高 0.0859（+56.5%）；最佳 R@20 比 BM25 高 0.2577（+57.9%）；最佳 BCY@8k 比 BM25 高 0.1737（+84.7%） |
| trace2code（101 样本） | MRR / Recall@20 | RepoMap MRR=0.2742，R@20=0.8366 | Qwen3-4B MRR=0.0827，R@20=0.5050（整体 MRR 冠军在此任务极弱） | RepoMap 在该任务 R@20 比 Qwen3-4B 高 0.3316（+65.7%），证明结构化方法在因果间接相关性上的不可替代性 |
| 三任务 RRF 混合（Qwen3-8B + RepoMap，287 样本） | MRR / Recall@20 / nDCG@20 | overall MRR=0.2713，R@20=0.7331，nDCG@20=0.3651 | 最佳单跑 MRR=0.2296，R@20=0.7070 | 无训练混合 MRR +0.0417、R@20 +0.0261；trace2code R@20 提到 0.8795 超过两个输入各自值 |
| 闭工具 seed 干预（45 样本，Codex GPT-5.5） | Final File F1 / Any-gold / 首次命中步 | RRF 种子 F1=0.3967、Any-gold=0.8000、首次命中=1；Oracle F1=0.6337 | No-seed F1=0.3222；Random 非金标 F1=0.3437 | RRF 比 no-seed +0.0744 F1；比 random +0.0530；Oracle 揭示残留 headroom 高达 +0.3115 |
| 选择性弃权（自然无金标协议，395 样本） | Selective Success@20 | Lexical=0.294，Jina=0.334，BM25=0.220（全部低于 no-abstention） | 无弃权 baseline：Lexical=0.499，Jina=0.489，BM25=0.463 | 负向结果：所有阈值都让选择性成功率下降，证明顶部分数不足以做仓库无关弃权 |
局限与改进
作者承认多条局限。基准是诊断性而非 web 规模：仅 427 样本、25 仓库，仓库频率严重不均——Gin 贡献 345 正向中的 88 个（25.5%），前四大仓库占 58.8%；论文并行报告样本加权、任务宏、仓库宏三种视角，但仓库宏 BCY 因 artifacts 按任务聚合无法报告。基准是文件级的，文件曝光≠有用区域定位：51.8% 样本-金标文件超 500 行，而 287 span 标注样本中证据中位数仅占文件 4.7%；Qwen3-8B 文件 R@20=0.7070 第一但行 F1=0.0165 第四。语料固定在 base commit，主排行榜不评动态工具使用与多轮探索。seed 试点每样本-臂仅一条轨迹、未记录温度/随机种子，故配对差值含策略采样方差、无统计显著性。四类相关性关系是确定性诊断标注而非独立验证潜在类，且 causal-indirect 恰等同 trace2code，相关性类型与任务构成混淆。我额外观察：Oracle 仅 +0.3115 说明即便定位完美，下游推理/编辑/验证仍有大量失败空间。
独立分析的弱点
独立分析有四处弱点。第一，样本规模与覆盖面有限：345 正向样本对评估方法族间统计显著性不够，每任务 58–106 样本，任务级排名易受少数难例驱动；改进方向是扩展更多语言、仓库与工作流信号。第二，相关性关系阈值是基准约定而非学得边界——code2test 的 d_i≥0.30、comment2context 的 d_i≥0.16/0.12 都是手动设定，缺跨任务校准；可改为基于证据的学习式分类或至少做阈值敏感性扫描。第三，文件级与 span 级鸿沟被低估：作者承认 75.7% span-文件对占用 ≤10% 文件，但 BCY 仍给整文件满分；对一个 1500 行文件排第一但实际只需 27 行的场景，BCY 会高估真实可用性——改进方向是把 span yield 纳入主指标并要求每个方法输出行区间。第四，seed 干预每样本-臂仅一条轨迹且无显式随机种子，无法区分「检索质量差异」与「策略采样噪声」；改进方向是同一闭工具策略下做多次重复采样、报告均值与置信区间，并把 endpoint 从 File F1 扩展到可执行补丁通过率。
未来方向
作者明确四个方向：(1) 混合检索系统——结合语义向量、词法/路径信号、仓库图、源-测试关系与任务感知重排序，论文已用 RRF 验证互补性可用；(2) 更大规模发布，覆盖更多语言、仓库与工作流信号，潜在新任务包括 issue-to-code、bug-report-to-root-cause、migration-to-affected-files 检索；(3) 查询改写——为相同样本配对开发者导向重写，评测检索器对表述鲁棒性；(4) 双向扩展——细粒度上为 edit2ripple 补 span 标注；下游上做配对干预的可执行 issue-resolution 实验：固定模型/scaffold/工具/token 预算/采样配置，仅变初始上下文，用官方测试 harness 评补丁、主 endpoint 为补丁解决率。基于成果可延伸：把 agentic relevance 关系用作训练检索器的多任务监督信号；探索 query-time 工具组合策略（先 RepoMap 粗筛再用嵌入重排）；用 PES@k 在线指导智能体探索预算分配。
复现评估
复现评估总体良好但有门槛。论文提供 Project/Benchmark/Evaluation 三工件链接，发布 427 样本 JSONL 与组合语料 manifest（308 repo/base 行、792 万 chunk）。五个嵌入基线（Qwen3-4B/8B、jina-0.5b、pplx-4b、nomic）均有完整 HF checkpoint 标识与 12 位 commit 前缀（Table 24），L2 归一化、max 聚合。指标用确定性 regex tokenizer，规则公开。算力中等偏高：edit2ripple 跑在 NVIDIA H20、batch=8；去重后 81.99% 重复率，建议共享嵌入缓存。复现难点：(1) pplx tokenizer 警告未处理，标 provisional；(2) 日志轨迹涉及 OpenAI/Codex 闭源付费模型；(3) seed 干预需 Docker 隔离且未记录温度/种子；(4) base commit 快照需重建 Git 历史。整体：静态排行榜可复现，轨迹与 seed 干预较难。
论文图表
该图用三栏展示了基准的整体协议：左栏是五类工作流来源的查询（code2test 的 PR/实现变更、comment2context 的评审评论+给定文件、trace2code 的复现命令+失败输出、edit2ripple 的变更意图+锚点 diff/文件、selective 的自然 issue 或错误仓库控制），中栏是冻结在 base commit 的仓库快照与可选方法族（词法/嵌入/RepoMap/智能体工具），右栏是任务特定的 agentic relevance 目标（相关测试、额外上下文、根因源文件、ripple 文件或弃权）。底部强调核心定义：相关性 = 智能体下一步需要读的仓库上下文，而非与查询文本最相似的文件。
这张图是理解整篇论文的「概念地图」——它一图说清了五类任务的输入输出语义、与传功代码搜索的本质区别（agentic relevance 而非语义相似度），以及为什么被评审文件/可见测试不算金标。读者必须在脑中建立这张图才能理解后续所有任务级结果。