CodeScout: Contextual Problem Statement Enhancement for Software Agents

本文提出了 CodeScout，一种通过轻量级预探索将模糊的用户请求转化为包含复现步骤、预期行为及探索提示的综合性问题陈述的上下文查询优化方法，该方法在不修改现有智能体架构的前提下，显著提升了其在 SWEBench-Verified 基准上的代码问题解决率。

要点

这篇论文介绍了一个名为 CodeScout（代码侦察兵）的新工具，它的核心任务是帮人工智能（AI）程序员“读懂”任务，而不是盲目地开始干活。

我们可以用"修车"和"侦探破案"的比喻来理解它。

1. 核心问题：AI 为什么经常“翻车”？

想象一下，你是一位天才修车师傅（现在的 AI 编程助手），你的技术非常精湛，能修好任何复杂的引擎。

但是，客户（开发者）给你的修车指令却非常模糊：

“师傅，我的车开起来有点怪，好像有点不对劲，你帮我看看。”

没有具体描述：

• 是刹车响？还是方向盘抖？
• 是刚换过轮胎后出现的？还是下雨天才这样？
• 具体是哪款车？

结果会怎样？
这位天才师傅虽然技术好，但他只能盲目地试错：

1. 先拆了轮胎看看（过度探索）。
2. 发现没坏，又去换机油（重复尝试）。
3. 换了三个零件还是没修好，最后累得半死，车还是没修好。

在论文中，这种现象被称为"过度探索"（Over-exploration）和"死胡同循环"。AI 因为缺乏上下文，在代码库里乱撞，浪费了大量时间却找不到真正的 Bug。

2. CodeScout 的解决方案：先侦察，后行动

CodeScout 就像是一个经验丰富的“现场侦察兵”。在让那位“天才修车师傅”动手之前，CodeScout 先做三件事：

第一步：快速扫描（构建知识图谱）

CodeScout 不会直接去修车，而是先拿着图纸（代码库结构）快速浏览一遍。它知道车的引擎、轮胎、刹车系统大概在哪里，它们之间是怎么连接的。

第二步：精准定位（上下文分析）

当客户说“车有点怪”时，CodeScout 会结合图纸去分析：

• “哦，客户提到是刚换了轮胎后出现的，那重点检查轮胎和悬挂系统。”
• “根据经验，这个型号的车在雨天容易刹车失灵，这可能是个线索。”
• “这里有个零件是最近刚改过的，嫌疑最大。”

第三步：生成“超级任务卡”（增强问题陈述）

CodeScout 把原本模糊的“车有点怪”，转化成了一张超级详细的维修工单，交给 AI 修车师傅：

任务： 修复刹车异响问题。
线索： 发生在雨天，且最近更换过轮胎（PR #27515）。
重点检查： 悬挂系统的第 3 号螺丝（具体文件路径）。
预期结果： 刹车时不应有金属摩擦声。
避坑指南： 别去动引擎，那是好的。

现在的 AI 修车师傅拿到这张单子后：

• 直奔第 3 号螺丝。
• 拧紧螺丝，问题解决了。
• 只用了 6 步就修好了，而之前盲目尝试用了 21 步还没修好。

3. 这个工具厉害在哪里？

• 不改变 AI 的大脑：CodeScout 不需要给 AI 换大脑（不需要重新训练模型），它只是给 AI 递了一张更清晰的“地图”。
• 省钱省力：实验证明，用了 CodeScout 后，AI 解决问题的成功率提高了 20%，而且能多修好 27 个 以前修不好的 Bug。
• 以小博大：甚至可以用一个比较便宜、简单的 AI 来当“侦察兵”（写任务卡），然后让一个昂贵、强大的 AI 去“修车”。这样既省了钱，又保证了修车质量。

4. 总结

CodeScout 的核心思想是：
在让 AI 动手写代码或修 Bug 之前，先花一点时间把问题想清楚、把背景理清楚。

这就好比磨刀不误砍柴工。

• 以前：AI 拿到模糊指令，像无头苍蝇一样乱撞，越撞越远。
• 现在：CodeScout 先帮 AI 把“模糊的抱怨”翻译成“精准的技术指令”，让 AI 能有的放矢，一击即中。

这篇论文告诉我们，提升 AI 编程能力的关键，不仅仅是让 AI 变得更聪明，更重要的是如何把人类模糊的需求，转化成 AI 能听懂的精准指令。CodeScout 就是那个完美的翻译官和侦察兵。

技术摘要

1. 研究背景与问题定义 (Problem Statement)

核心问题：
当前的 AI 驱动代码辅助工具（基于大语言模型 LLM 的软件工程代理）在处理**定义模糊、上下文缺失的问题陈述（Problem Statements）**时表现不佳。

• 现状： 开发者提交的问题通常简洁但缺乏关键细节（如复现步骤、技术细节、明确预期），假设代理能“心领神会”代码库结构。
• 后果： 这种输入质量低导致代理陷入低效的探索轨迹，表现为：
  1. 过度探索 (Over-exploration)： 因上下文过载而无法触及问题根源。
  2. 重复尝试 (Repeated Attempts)： 在没有适当测试或演进的情况下，反复应用相同的修复方案。
  3. 结果： 导致软件任务解决率低下，且消耗大量计算资源。

研究假设：
代理失败的主要原因并非模型推理能力不足，而是输入问题的规格说明（Specification）质量差。现有的代理架构缺乏在任务执行前进行系统性“预探索”和上下文理解的能力，导致它们只能被动反应，无法建立战略性的心理模型。

---

2. 方法论：CodeScout (Methodology)

CodeScout 是一种上下文查询细化（Contextual Query Refinement）方法。它不修改现有的代理架构，而是作为一个前置处理步骤，将模糊的用户请求转化为详尽、可操作的问题陈述。

其工作流程分为四个阶段（如图 2 所示）：

阶段 1：仓库知识图谱构建 (Repository Knowledge Graph Construction)

• 利用抽象语法树（AST）解析器遍历代码库。
• 构建有向图 $G(R)$，其中节点代表代码实体（类、函数、变量），边代表语义关系（继承、调用、导入）。
• 提取元数据，包括文件组织、类层次结构和依赖关系。

阶段 2：高层范围界定 (High-Level Scoping)

• 输入：原始问题陈述 $P_0$ 和知识图谱 $G(R)$。
• 过程：LLM 代理分析 $P_0$ 中的实体提及，结合调试模式和图谱结构，识别出15 个以内最相关的探索目标（文件、类、函数）。
• 输出：探索目标列表 $T$，包含实体类型、名称及相关性推理。

阶段 3：细粒度上下文分析 (Fine-grained Context Analysis)

• 针对每个探索目标 $t_i$，检索代码内容 $c_i$。
• 利用 LLM 进行结构化分析，提取以下洞察：
  • 角色评估 (Role Assessment)： 该代码与问题的关系。
  • 修复位置提示 (Fix Location Hints)： 潜在的修改点及置信度。
  • 技术洞察 (Technical Insights)： 实现模式、架构决策。
  • 替代假设 (Alternative Hypotheses)： 其他可能的根本原因。
• 过滤机制： 根据相关性评分（Relevance Score）过滤低质量洞察，仅保留高分洞察用于合成。

阶段 4：问题陈述合成 (Problem Synthesis)

• 将原始问题 $P_0$ 与过滤后的洞察 $I_{filtered}$ 结合，生成增强版问题陈述 $P_{aug}$。
• $P_{aug}$ 包含的关键组件：
  • 增强描述： 整合技术细节，明确问题机制。
  • 复现步骤： 补充内部技术细节和错误模式。
  • 预期行为： 基于代码分析明确正确行为。
  • 探索提示 (Exploration Hints)： 指定需检查的文件、关键类/函数及关注区域。
  • 修复提示 (Fix Hints)： 高置信度的修复位置、实施建议及替代假设。

---

3. 主要贡献 (Key Contributions)

1. CodeScout 框架： 提出了一种系统性的上下文问题规格增强方法，通过仓库感知分析将模糊查询转化为可操作规范。在 SWEBench-Verified 基准测试中，解决了率提升了 20%，额外解决了 27 个问题。
2. 实证验证： 在多种软件工程任务（SWEBench-Verified）和多种代理架构（SWE-agent, OpenHands, Mini-SWE-Agent）及不同 LLM（DeepSeek R1, Qwen3 Coder, GPT-5-mini）上验证了其有效性，表现出一致的性能提升。
3. 深入分析与成本效益：
   • 揭示了 CodeScout 如何通过减少非收敛轨迹来优化代理行为。
   • 展示了**“小模型增强大模型”或“强模型辅助弱模型”**的跨合成（Cross-synthesis）潜力：使用较弱的模型进行预探索增强，可以显著提升较弱运行时代理的性能，具有极高的成本效益。

---

4. 实验结果 (Results)

实验在 SWEBench-Verified 基准上进行，对比了默认基线（无增强）与 CodeScout 增强后的表现。

• 解决率提升：
  • 在 SWE-agent 上，使用 DeepSeek R1、GPT-5-mini 和 Qwen3 Coder 时，解决的问题数量分别增加了 11、15 和 24 个（相对提升约 9.6% - 13.1%）。
  • 整体解决率提升了 20%。
• 定位准确性 (Localization)：
  • 在文件级和函数级定位上，增强后的设置显著提高了准确性，特别是对于推理能力较弱的模型（如 DeepSeek R1），帮助其更准确地找到代码区域。
• 轨迹效率：
  • 步骤减少： 案例显示，原始代理需要 21 步失败，而使用 CodeScout 增强后仅需 6 步即可解决。
  • 探索更聚焦： 代理在早期更多地使用 view 和 grep 进行针对性搜索，减少了盲目的 find 操作。
• 成本分析：
  • 虽然增加了预处理的 Token 消耗，但对于大多数模型，每解决一个问题所需的总 Token 数（包括增强开销）是降低或持平的，因为减少了代理在无效路径上的浪费。
  • 对于 GPT-5-mini 这种产生超长轨迹的模型，增强带来的开销相对较小，收益依然显著。
• 消融实验：
  • 自主增强无效： 让代理在执行过程中“自主”增强问题陈述会导致性能下降，证明了结构化、分离的预处理阶段的必要性。
  • 过滤的重要性： 去除相关性过滤会导致性能下降，证明噪声控制至关重要。
  • LLM 范围界定优于传统检索： 基于 LLM 的语义范围界定比 BM25 等传统检索方法效果更好。

---

5. 意义与展望 (Significance & Conclusion)

• 范式转变： 论文提出，在 AI 辅助软件工程中，“先理解，后解决”（Look before you leap）至关重要。系统性地在执行前投入计算资源进行问题理解，是提升代理可靠性的关键。
• 架构无关性： CodeScout 作为一个即插即用的预处理层，不依赖特定的代理架构，具有广泛的适用性。
• 未来方向：
  • 扩展到多仓库（Multi-repository）场景。
  • 集成更深层的程序分析技术。
  • 应用于协作开发环境。

总结： CodeScout 证明了通过上下文感知的预探索来增强输入质量，是解决当前 AI 代码代理在模糊需求下表现不佳这一瓶颈的有效途径。它不仅提高了任务解决率，还显著优化了代理的探索策略和计算效率。