技术摘要：SHERLOC —— 用于代码修复智能体的结构化诊断定位技术

1. 问题陈述

仓库级代码修复日益依赖于大型语言模型（LLM）智能体，这些智能体通过将推理过程与结构化工具调用交织在一起，来解决 GitHub 问题。然而，对现有智能体的系统性分析揭示了一个关键的低效问题：智能体在尝试进行代码补丁修复之前，会将近一半的交互预算（平均每个实例 18.5 轮，超过 32 万个 token）仅仅消耗在**故障定位（fault localization）**上。

目前的定位方法存在两个主要局限性：

1. 输出不完整： 大多数方法仅检索出有缺陷的文件或函数，但未能提供下游修复智能体有效执行所需的诊断上下文（根因、解决方案方向）。
2. 评估错位： 专门的定位框架通常被评估为文件检索系统，而非可操作的诊断工具，它们只能产生定位结果，却无法产生修复所需的推理过程。

这造成了性能瓶颈：大量的计算资源被消耗在搜索而非构建上，且生成的定位信息往往缺乏指导修复所需的特异性。

2. 方法论：SHERLOC

作者引入了 SHERLOC（基于假设驱动的探索与推理的结构化定位），这是一个无需训练的框架，旨在将推理型 LLM 与一套精简的仓库工具及自恢复机制相结合。

核心架构

SHERLOC 以单个推理 LLM 的形式运行，通过一个有界的迭代循环（最多 20 轮）与确定性的工具执行器进行交互。它不需要微调、强化学习或多智能体编排。

• 工具集： 该框架利用了四个对 LLM 友好的工具：
  • View File（查看文件）：通过模糊路径匹配和可选的行范围来检查文件内容。
  • Codebase Search（代码库搜索）：进行带有上下文的全仓库字面量搜索。
  • Repository Tree（仓库树）：展示过滤后的文件层级结构以恢复全局上下文。
  • Connected Tree（关联树）：总结导入关系（直接和反向导入）以导航依赖关系。
• 迭代交互： 模型在推理和工具选择之间交替进行。它将观察结果（代码片段、路径、依赖摘要）累积在上下文历史中，以形成假设状态。
• 自恢复机制： 为了稳定长程工具使用，SHERLOC 采用了轻量级的恢复策略：
  • 上下文截断（保留初始提示词和最近的轮次）。
  • 循环检测（针对重复且无效率的调用发出警告）。
  • 隐式工具调用恢复（解析格式错误但含义明确的请求）。
  • 最终轮次综合（在步数预算耗尽时强制得出结论）。

结构化诊断输出

不同于以往仅输出文件路径的方法，SHERLOC 为每个预测的位置生成结构化诊断发现（structured diagnostic finding）。该发现包含五个字段：

1. 位置说明（Location Explanation）： 为什么怀疑该文件。
2. 根因（Root Cause）： 错误的底层机制。
3. 解决方案思路（Solution Idea）： 用于修复的可操作指导（不含代码）。
4. 依赖关系（Dependencies）： 对其他模块的影响。
5. 测试影响（Testing Impact）： 建议的测试修改方案。

评估指标

论文提出了与结构无关的块级指标（覆盖率召回率、精确度和平均紧凑度）而非基于行号跨度，因为补丁并不总是与函数或类等语法单元对齐。

3. 关键结果

定位性能

SHERLOC 在无需特定任务训练的情况下，实现了跨模型规模的 SOTA（最先进）文件级定位性能：

• SWE-Bench Lite： 84.33% 的 accuracy@1（使用 Qwen3-235B）。
• SWE-Bench Verified： 81.27% 的 recall@1（使用 Qwen3-235B）。
• 规模效率： 在匹配的 ~30B 参数规模下，SHERLOC (Qwen3-30B) 达到了 75.07% 的 recall@1，显著超越了微调基线（如 ToolTrain-32B）和非微调方法（提升了 7.0 至 18.3 个百分点）。
• 跨家族迁移： 该方法在不同模型家族间具有有效的迁移能力（例如，DeepSeek-V3 达到 79.53% 的 recall@1）。

向代码修复的下游迁移

将 SHERLOC 的定位结果和诊断发现注入现有的修复智能体（OpenHands 和 SWE-Agent）中，可以带来显著提升：

• 解决率： 在五个修复基座上，平均解决率提升了 5.95 个百分点。
• 效率： 定位阶段的 token 减少了 36.7%，总 token 减少了 23.1%。
• 质量中介作用： 迁移收益取决于质量。较小的模型受益于“所有 SHERLOC 发现”，而更大、更强大的模型则从经过质量过滤的发现（由 LLM 评判得分 ≥4.0 的发现）中获益最多。未经过滤的发现可能会由于低置信度诊断带来的负迁移，从而降低强力智能体的性能。

消融实验与有效性研究

• 组件重要性： 移除 View File 工具或最终轮次提示词会导致性能大幅下降，这证实了代码检查和综合压力是至关重要的。
• 隐性知识 vs. 推理： 通过屏蔽问题文本中的文件路径进行控制实验显示，虽然 LLM 对流行仓库（如 scikit-learn, requests）拥有隐性熟悉度，但主动的工具辅助探索贡献了显著的性能增益（比仅文本基线高出约 22 个百分点）。
• 推理的必要性： “思考（Thinking）”模式模型明显优于“指令（Instruct）”模式模型，后者往往无法维持多轮协议。

4. 重要性与主张

论文认为，结构化诊断输出（而非仅仅是位置检索）才是定位过程中有用的基本单元。一个带有误导性诊断的正确文件路径可能会误导下游智能体，而一个包含根因分析和解决方案思路的结构化发现则能实现有效的修复。

主要主张包括：

1. 无需训练的 SOTA： 单个推理 LLM 配合精简工具和自恢复机制，即可达到甚至超过专门微调的定位系统。
2. 可操作上下文： 包含结构化诊断字段（根因、解决方案思路）对于将定位成功转化为下游修复任务至关重要。
3. 高效性： SHERLOC 大幅降低了定位阶段的 token 成本，为实际的代码修复释放了预算。
4. 质量过滤： 必须进行质量过滤以防止负迁移；高质量的发现驱动成功，而低质量的发现则可能产生负面影响。

作者总结道，定位应该根据**诊断的可操作性（diagnostic actionability）**而非仅仅是文件检索准确率来进行评估。他们指出，虽然其结果很强，但在一定程度上受到 LLM 预训练中对公开仓库熟悉度的干扰，未来的工作需要使用留存的仓库分布进行更纯净的评估。该框架在设计上是语言无关的，尽管目前的工具依赖于特定语言的解析器来处理导入树。