RepoMirage: Probing Repository Context Reasoning in Code Agents with Perturbations¶

会议: NeurIPS 2026
arXiv: 2605.26177
OpenReview: https://openreview.net/forum?id=I2uNqwM1hm
代码: https://anonymous.4open.science/r/RepoMirage
领域: LLM Agent
关键词: 代码智能体, 仓库上下文推理, 语义保持扰动, 探索漂移, 基准评测

一句话总结¶

本文提出基于扰动的代码智能体评测套件 RepoMirage，通过对 SWE-Bench Verified 进行语义保持的上下文重构与显式诊断任务扩展，揭示现有代码智能体高解决率主要依赖局部快捷线索而非跨文件结构推理，并在多文件上下文需求激增时普遍遭遇“探索漂移”瓶颈。

研究背景与动机¶

随着大语言模型在软件工程领域的迅猛推进，代码智能体已从单纯的单函数补全和单文件代码生成，演进到处理真实工业级代码仓库中的端到端软件工程任务（如 SWE-Bench 上的 GitHub Issue 修复）。在复杂的实际代码库中，一个表面报错往往源于跨模块调用链异常或分布式依赖约束，解决问题本质上依赖于在广阔的代码空间中检索分散证据、理解模块间关系并完成跨文件推理的能力，即“仓库上下文推理”（Repository Context Reasoning）。然而，现有的仓库级评测基准普遍采用端到端黑盒评分（即测试用例是否通过），未能将模型对跨文件结构的深层理解能力与局部代码补全能力有效剥离。

深入剖析 SWE-Bench Verified 的真实执行轨迹可以发现一个引人深思的局部化假象：超过 80% 的 Issue 最终仅需修改单个文件，且在先进模型成功修复的案例中，GPT-5 有 53.8% 的案例仅检索阅读了 1 个文件，88.0% 的案例检索阅读文件不超过 3 个；DeepSeek-V3.2 也有 55.7% 的成功案例文件访问数在 3 个以内。这意味着基准测试上的亮眼高分并不能证明智能体具备真正的全局上下文推理能力，模型很可能仅仅利用了直接的 import 语句、直白的文件名文本相似度或就近声明的常量等局部表面线索。如果简单构建包含多文件需求的新数据集，不仅难以与主流基准严格对齐，还会引入全新的环境与任务形式混淆变量。

面对这一困境，本文选择将“扰动”（Perturbation）作为受控探针工具，在保持原始仓库程序语义、可执行性及测试用例完全不变的前提下，通过对任务关键上下文进行系统性结构重组，强制剥离局部直观线索并放大对跨文件上下文推理的需求。核心 idea：利用语义保持的上下文重组（依赖路径间接化、运行时目标混淆、局部常量外部化）打破局部捷径，构建 RepoMirage-Perturb 评测与 RepoMirage-Extend 显式诊断任务，定量诊断代码智能体在仓库上下文推理上的能力缺陷与探索漂移机制，并以结构优先的解耦工作流 RepoAnchor 实施针对性引导。

方法详解¶

整体框架¶

RepoMirage 由“两阶段评测套件”与“行为诊断及原型缓解方法”有机组成。整个技术流水线以 SWE-Bench Verified 中的真实代码库与 Issue 为种子，首先通过基于抽象语法树（LibCST）的变换实施三种语义保持的仓库级扰动，构建 RepoMirage-Perturb，在任务目标不变的前提下检验性能稳定性；进而将扰动暴露的结构瓶颈转化为四类显式评测任务，构建 RepoMirage-Extend；接着通过轨迹状态转移矩阵揭示智能体在强上下文需求下的行为失调；最终提出将结构探索与代码编辑显式解耦的原型工作流 RepoAnchor。

%%{init: {'flowchart': {'rankSpacing': 24, 'nodeSpacing': 28, 'padding': 6, 'wrappingWidth': 400}}}%%
flowchart TD
    A["SWE-Bench Verified 仓库与 Issue"] --> B["语义保持的仓库级扰动<br/>多跳代理/包装目录/外部JSON"]
    B --> C["扰动衍生的显式诊断任务<br/>代理链补全/目标识别/常量恢复/多文件修复"]
    C --> D["行为轨迹与探索漂移诊断<br/>统计转移概率与预编辑探索步数"]
    D --> E["结构优先的解耦工作流 RepoAnchor<br/>探索生成 INSTRUCTION.md 并锚定下游编辑"]
    E --> F["最终补丁与任务验证结果"]

关键设计¶

1. 语义保持的仓库级扰动：迫使智能体进行跨文件上下文追踪

传统基准中智能体往往借由显式线索实现“捷径定位”。为此，RepoMirage-Perturb 设计了三类互补且语义等价的 AST 级精确扰动，所有扰动均严格通过 SWE-Bench 的官方 PASS_TO_PASS（保证现有功能不损坏）与打上黄金补丁后的 FAIL_TO_PASS（保证原本可解性）双重验证： - 依赖路径间接化（Dependency-Path Indirection）：针对绝对导入语句直接暴露模块依赖关系的痛点，将目标文件中的直接导入替换为四层代理导入链（如通过多个中转模块动态转发真实依赖）。智能体无法仅凭单行 import 推断真实模块角色，必须沿着代理链跨多文件追踪真实定义。 - 运行时目标混淆（Runtime-Target Masking）：针对文件名文本与 Issue 描述高重合的痛点，将真实待修文件重命名，在原路径创建同名包目录并通过 __init__.py 进行动态封装转发；同时在同级目录下注入多个人工合成的假文件（Decoys，包含局部翻转的布尔条件或打乱的别名）。智能体必须深入检查包封装逻辑与运行时绑定关系，才能将“表面相似”的干扰项与“运行时实际执行”的真实目标区分开来。 - 局部常量外部化（Local-Value Externalization）：针对就近声明的常量值使模型无需跳出单文件的痛点，将关键常量提取至外部 JSON 资源文件中，并在源码中注入读取并合并字典的逻辑，以跨文件键值引用替代局部字面量。智能体必须跨越文件边界，将目标代码的控制逻辑与外部 JSON 数据建立关联。

2. 扰动衍生的显式诊断任务：将隐式结构瓶颈转化为独立评测目标

为了直接量化仓库上下文推理本身，RepoMirage-Extend 将上述扰动涉及的核心结构关系独立提炼为四类可自动化验证的明确任务，使评测目标从“黑盒修复代码”转变为“显式结构还原”： - 代理链补全（Proxy Chain Completion）：擦除四层代理链中的某个中间中转文件，要求智能体追踪上下游导入链路，编写正确的转发代码以恢复目标模块导入。验证时通过动态 import 校验解析出的对象是否与基准完全一致。 - 运行时目标识别（Runtime Target Identification）：隐藏包装模块 __init__.py 中对真实目标的直接引用，要求智能体比对多个候选实现文件，修正包装模块的导入映射以绑定真实运行时文件。验证时由检查脚本检验包解析结果。 - 缺失常量恢复（Missing-Constant Recovery）：擦除外部 JSON 文件中的部分键名（保留对应数值），要求智能体阅读目标代码的使用上下文（循环边界、数组索引、特殊常数等），推断出缺失键名并补全 JSON 文件。验证脚本读取并合并所有 JSON，核对合并字典键值映射是否正确。 - 多文件 Issue 修复（Multi-File Issue Resolution）：保留原始 SWE-Bench 中黄金补丁本就涉及多文件的挑战性实例，在完全扰动的仓库环境中检验智能体协调跨文件修改的综合能力。

3. 结构优先的解耦工作流 RepoAnchor：以两阶段上下文锚定遏制探索漂移

轨迹分析表明，智能体在强上下文需求下往往陷入“反复搜索与阅读、无法做出有效编辑决策”的探索漂移状态。为此，RepoAnchor 提出两阶段解耦范式，将结构理解与问题求解分离开来： - 阶段一（仓库定位与结构理解）：智能体被显式约束不得直接修改代码或运行修复测试，其唯一目标是探索相关目录、追踪调用与加载关系，并将推断出的仓库结构、候选文件角色、依赖映射及待决不确定点整理写入中间文件 INSTRUCTION.md。 - 阶段二（基于结构锚点的代码求解）：求解智能体以原始 Issue 与 INSTRUCTION.md 作为共同输入，以明确的结构视图为脚手架开展补丁设计、局部编辑与针对性测试，大幅减少了在庞大仓库中盲目往返试错的认知负荷。

损失函数 / 训练策略¶

本文作为评测与工作流研究，不涉及模型权重梯度更新，所有实验基于各主流前沿模型的 API 或开源权重（通过 vLLM 部署于 4 张 NVIDIA A800-80GB GPU）。核心评测协议与行为度量设计如下：

智能体交互统一采用 mini-swe-agent 框架的纯 Bash 模式，步数预算严格限制为 250 步。智能体轨迹中的每一步 Shell 命令被严格解析为四种原子操作：编辑（edit，含补丁应用与写入）、测试（test，含测试执行与运行验证）、搜索（search，如 rg、find、ls）与阅读（read，如 cat、head）。分析时将搜索与阅读合并为探索状态（explore），定义动作状态集合 $\mathcal{S} = \{\textit{explore},\textit{edit},\textit{test}\}$。任意两动作间的状态转移概率计算如下： $$p_{a\rightarrow b}=\frac{\#(a\rightarrow b)}{\sum_{s\in\mathcal{S}}\#(a\rightarrow s)},\quad a,b\in\{\textit{explore},\textit{edit},\textit{test}\}$$ 通过度量扰动前后转移概率的差值 $\Delta p_{a \rightarrow b}$，定量刻画智能体是否发生“探索到探索的高频空转”以及“探索向编辑的转移衰减”。

实验关键数据¶

主实验¶

在由 SWE-Bench Verified 转换而来的 RepoMirage-Perturb 上，评测了八款主流大语言模型。实验同时监控最终解决率（Resolved %）与平均访问文件数（Avg. #Files）。

模型	SWE-Bench 解决率 (%)	扰动后解决率 (%)	相对降幅 (%)	SWE-Bench 访问文件数	扰动后访问文件数	文件倍率
GPT-4.1	38.40	18.20	-52.60%	1.69	7.10	4.20×
GPT-5	65.00	49.00	-24.61%	2.83	7.04	2.49×
Gemini-3.1-Pro	70.60	54.40	-22.95%	17.32	24.94	1.44×
Claude-Sonnet-4.6	75.20	63.20	-15.96%	2.20	6.76	3.07×
DeepSeek-V3.2	70.00	52.00	-25.71%	4.66	14.32	3.07×
MiniMax-M2.7	78.20	65.40	-16.37%	2.24	6.92	3.09×
Qwen3-Coder-Next	69.20	42.60	-38.44%	4.66	26.90	5.77×
Qwen3.6-35B-A3B	67.80	53.40	-21.24%	2.52	11.90	4.72×

在显式任务套件 RepoMirage-Extend 上，模型的综合平均解决率出现断崖式下跌，展现出与原始端到端分数极不一致的真实结构推理瓶颈：

模型	多文件修复 (Org/Ext)	代理链补全 (Org/Ext)	运行时目标识别 (Org/Ext)	缺失常量恢复 (Org/Ext)	扩展总平均 (%)
GPT-4.1	10.00 / 2.86	45.14 / 4.17	40.14 / 3.52	43.75 / 2.78	3.40
GPT-5	31.43 / 25.71	70.83 / 11.11	68.31 / 35.92	72.22 / 36.80	27.60
Gemini-3.1-Pro	38.57 / 14.29	77.08 / 22.22	76.06 / 43.66	74.31 / 71.53	41.40
Claude-Sonnet-4.6	41.43 / 15.71	80.56 / 36.81	80.28 / 30.28	81.25 / 23.61	28.20
DeepSeek-V3.2	35.71 / 20.00	74.31 / 11.80	75.35 / 59.86	77.08 / 57.64	39.80
MiniMax-M2.7	45.71 / 22.86	81.25 / 7.64	86.62 / 26.76	81.94 / 6.25	14.80
Qwen3-Coder-Next	44.29 / 17.14	72.92 / 29.17	75.35 / 7.04	71.53 / 34.03	22.60
Qwen3.6-35B-A3B	31.43 / 24.29	80.56 / 14.58	72.41 / 19.01	68.00 / 38.89	24.20

消融实验¶

为验证智能体性能瓶颈究竟源于“无法检索信息”还是“无法将检索信息沉淀为结构指导”，作者设计了结构提示（Structural Hints）干预实验（在 prompt 中提供通用的仓库扰动机制结构说明，但不透露具体解）：

模型配置	多文件修复 (%)	代理链补全 (%)	运行时目标识别 (%)	缺失常量恢复 (%)	平均解决率 (%)
GPT-5 (基线)	25.71	11.11	35.92	36.80	27.60
GPT-5 + 结构提示 (Hints)	28.57	81.94	60.56	61.81	62.60 (+35.00)
DeepSeek-V3.2 (基线)	20.00	11.80	59.86	57.64	39.80
DeepSeek-V3.2 + 结构提示 (Hints)	24.29	86.11	84.51	85.42	76.80 (+37.00)

单项扰动消融结果同样证实：单独施加依赖路径间接化、运行时目标混淆或局部常量外部化，均导致解决率稳定下滑；而三者复合作用下滑幅最大，证明三类扰动成功打击了正交的上下文推理维度。

关键发现¶

表面高分与推理能力的不匹配：在原始 SWE-Bench 上表现优异的模型（如 MiniMax-M2.7 达 78.2%），在 RepoMirage-Extend 上暴跌至 14.80%；GPT-4.1 从 38.4% 跌至 3.4%。这证明端到端 Issue 修复率充斥着局部启发式捷径。
探索漂移现象的普遍存在：受到扰动后，模型平均访问文件数从 4.77 个激增至 13.24 个（Qwen3-Coder-Next 甚至从 4.66 激增至 26.90），但步数并未转化为有效编辑，探索到探索的转移概率显著上升，模型在缺乏结构锚点时极易迷失在代码检索循环中。
结构脚手架的决定性价值：提供结构提示后，GPT-5 解决率从 27.6% 跃升至 62.6%，DeepSeek-V3.2 从 39.8% 跃升至 76.8%；两阶段原型 RepoAnchor 同样在多款模型上取得显著提升，确立了“结构先行”的工作流价值。

亮点与洞察¶

将扰动作为诊断探针而非鲁棒性对抗手段：传统扰动多关注对抗攻击或简单变量重命名，RepoMirage 巧妙利用语义保持的 AST 重构，在不改变任务本质的前提下精准剥离局部表面线索，开辟了代码智能体深层能力评测的新范式。
揭示了“探索漂移”这一智能体系统级失调机制：论文敏锐地发现智能体在面对宽泛上下文时，痛点不在于“工具检索不出来”，而在于无法将多文件观察融合为连贯的结构心智模型，导致其在探索循环中徘徊耗尽步数。
RepoAnchor 的低成本双阶段迁移思路：无需重新微调模型权重，仅通过“第一阶段纯探索写 INSTRUCTION.md，第二阶段依据文档定点动工”的 Prompt 架构，即可显著提升复杂工程场景下的执行鲁棒性。

局限与展望¶

语言生态局限于 Python 仓库：受限于 AST 解析工具（LibCST）和 SWE-Bench Verified 的基础环境，当前扰动构建与校验仅覆盖 Python 语言，尚未扩展至具备复杂静态编译与构建系统的 C++/Java/Rust 项目。
任务形式依然偏向经典代码修改：RepoMirage-Extend 虽然衍生了四类结构任务，但仍以“改动仓库并运行单测验证”为主，未来有待拓展至架构重构审查、跨仓库迁移、长效维护与仓库级测试生成等多元软件工程场景。

评分¶

新颖性: ⭐⭐⭐⭐⭐ 巧妙利用语义保持的仓库级重构作为诊断探针，首次系统性揭示了代码智能体在仓库上下文推理中的局部捷径与评估盲区。
实验充分度: ⭐⭐⭐⭐⭐ 涵盖八款主流前沿模型、上千个测试实例，配备详尽的状态转移矩阵轨迹分析与结构提示干预实验，论据极为扎实。
写作质量: ⭐⭐⭐⭐⭐ 逻辑推导环环相扣，从问题揭示、受控扰动设计、显式任务拓展到行为诊断与缓解方案，行文流畅严谨。
价值: ⭐⭐⭐⭐⭐ 为软件工程智能体社区指明了超越单一通过率数字的关键方向，对下一代多文件代码 Agent 的架构设计深具指导意义。