SGAgent：一种用于仓库级软件修复的、基于建议引导的大语言模型多智能体框架——学术研究报告
一、 主要作者、机构及发表信息 本文的主要作者包括：张全军（南京理工大学）、高成宇、韩宇、尚晔、方春荣、陈振宇（以上均来自南京大学软件新技术国家重点实验室）以及肖亮（南京理工大学）。该研究以题为“SGAgent: Suggestion-Guided LLM-Based Multi-Agent Framework for Repository-Level Software Repair”的论文形式，发表于 ACM Transactions on Software Engineering and Methodology (TOSEM) 期刊，具体卷期为第1卷第1期，文章号第1篇，发表于2024年1月。
二、 研究学术背景 本研究的核心科学领域为软件工程，具体聚焦于自动化程序修复（Automated Program Repair, APR）。近年来，大语言模型（LLM）在代码生成、测试生成等软件工程任务上取得了显著进展。然而，大多数现有研究主要集中于简化的函数级任务，其修复或生成范围仅限于单个函数或文件。这种设定虽然便于评估，但无法捕捉现实世界软件开发中固有的、仓库级别的依赖关系和上下文复杂性。 为了弥合这一差距，研究界开始关注仓库级软件修复，这已成为基于LLM的软件工程中最具挑战性和前景的方向之一。特别是，流行的基准测试SWE-Bench被引入，用于评估LLM在拥有完整仓库访问权限的情况下解决真实GitHub问题的能力。为了应对SWE-Bench提出的现实世界软件工程挑战，研究者们探索了两种主要范式：过程式（procedural）方法和智能体式（agentic）方法。智能体方法为LLM配备外部工具（如文件编辑、代码检索、测试执行），以实现迭代规划和环境交互，使LLM能够像人类开发者一样自主导航和修改大型代码库。 尽管最近成果喜人，但现有的软件修复方法主要遵循“定位-修复”（localize-then-fix）范式，即首先识别可疑代码元素，然后直接将其提供给LLM以生成补丁。然而，直接从故障定位跳到补丁生成引入了几个根本性挑战：1. 目标不匹配：定位回答“错误在哪里”，而补丁生成关心“如何修改代码库”，两者需要不同的语义粒度和上下文理解；2. 依赖不完美的定位：下游补丁生成的成功在很大程度上取决于定位准确性，而不准确的定位结果可能会被LLM放大；3. 缺少中间规划：在定位和修复之间没有明确的规划阶段，LLM倾向于直接对最可疑的代码片段进行编辑，依赖试错而非推理代码为何及如何修改，这可能导致补丁过拟合、冗余探索和浅层修复。此外，这种不透明的修复行为降低了可信度，阻碍了在实际开发工作流中的采用，因为开发者需要可解释、可证明的修复建议。 基于上述背景，本研究旨在解决“定位-修复”范式的固有缺陷。受人类调试实践的启发（通常遵循“分析问题并定位可疑代码”、“推理可疑区域与其他文件的交互并制定修复计划”、“尝试修改代码库并返回正确补丁”三步流程），本研究的目标是提出一种新的、更符合人类专家调试逻辑的软件修复框架，以提升仓库级软件修复的准确性、可解释性和效率。
三、 详细研究流程与方法 本研究提出了名为SGAgent的建议引导多智能体框架，其核心范式转变为“定位-建议-修复”（locate-suggest-fix）。该研究整体包含三个核心组成部分的构建与集成：知识图谱构建、基于知识图谱的工具包开发以及多智能体协作框架设计。研究的主要对象是基于真实GitHub项目的300个可复现的仓库级缺陷实例，这些实例来源于被广泛采用的SWE-Bench基准测试的子集SWE-Bench-Lite。
（一） 知识图谱构建流程 为了支持LLM进行仓库级的代码检索和推理，SGAgent首先基于静态代码分析构建一个结构化的知识图谱（Knowledge Graph, KG）。 1. 数据来源与处理对象：输入是完整的项目仓库，包括所有文件结构和内容。 2. 构建阶段： * 标签提取：对于项目中的每个文件，使用Tree-sitter进行抽象语法树分析以提取原始标签信息。如果标签解析失败，则额外使用Pygments来定位和补充缺失的定义，确保捕获所有实体。 * 文件结构分析：解析每个文件以获取其层次结构，捕获类和方法的嵌套包含等文件级关系。 * 实体与关系构建：定义了三种实体类型：类（Class）、方法（Method）、变量（Variable）。每种实体都包含一系列属性，如完全限定名、起始/结束行号、源代码内容、参数列表等。基于从嵌套结构中获得的信息，构建了七种关系类型，包括继承（inherits）、包含方法/变量（has_method/has_variable）、属于（belongs_to）、调用（calls）、引用（references）等。 * 图谱表示：最终的知识图谱被表示为一组三元组（头实体，关系，尾实体），可以存储于Neo4j数据库中，支持高效的查询和可视化。
（二） 基于知识图谱的工具包实现流程 在知识图谱的基础上，SGAgent设计了一个全面的检索工具包，使智能体能够高效地与整个仓库进行交互。 1. 工具功能设计：工具包提供了14个专门工具，针对不同的代码检索场景进行了预配置，分为四类： * 代码结构分析工具：如analyze_file_structure，获取Python文件的完整概览。 * 实体分析工具：如extract_complete_method，提取完整的方法实现；find_class_constructor，定位类构造函数；show_file_imports，提取文件中的所有导入语句。 * 内容搜索工具：如search_code_with_context，在Python文件中搜索关键词并附带上下文。 * 文件系统工具：如explore_directory（目录浏览）、read_file_lines（读取文件指定行）、execute_shell_command_with_validation（执行只读Shell命令）。 2. 开发方法：这些工具是自主实现的，紧密集成了对上述知识图谱的查询能力，旨在为智能体提供精确、上下文感知的检索功能，减少模糊或冗余的搜索。
（三） 多智能体框架工作流程 SGAgent采用由三个专门智能体组成的协作框架，模仿人类调试的三阶段实践。 1. 故障定位器智能体： * 职责：根据问题描述和仓库信息，识别潜在的缺陷位置。 * 工作流程：基于ReAct框架，执行“观察-思考-行动”模式。它主动利用问题描述，通过预构建的工具包检索知识图谱，动态搜索相关代码实体及其相互关系。在每一步检索后，会分析检索到的信息，评估是否足以进行缺陷定位。如果不够，则迭代调用更多工具。一旦获得足够上下文，它会采样最多4个候选缺陷位置，总结洞察，并传递给建议器。 * 核心创新（特殊方法）：使用一个精心设计的结构化提示（Prompt），将定位过程转化为结构化的推理任务。该提示要求智能体将问题描述作为唯一真相来源，分析症状，推断根本原因，并以精确的行号范围格式输出最多5个逻辑上相关的代码位置，确保最小的完美覆盖（捕获所有错误区域）且位置不重叠。 2. 修复建议器智能体： * 职责：对定位器识别出的位置进行二次上下文扩展检索，并生成可行的修复建议。 * 工作流程：从每个已识别的位置开始，在问题描述的指导下进行上下文扩展，直到认为检索到的信息足以充分理解缺陷的根本原因和潜在的修复方向。然后，为每个候选位置生成具体的修复建议和更新后的上下文摘要，传递给修复器。 * 核心创新（特殊方法）：引入了“建议”阶段，这是本研究的关键贡献。该智能体同样由一个结构化提示引导，其任务不是验证或修改定位结果，而是将这些位置视为正确的，专注于理解它们之间的交互，并生成可操作的、框架一致的修复策略。提示强调对位置间互连关系的分析、跨位置修复建议的协调性约束以及遵守项目特定设计规则。 3. 问题修复器智能体： * 职责：根据上游智能体提供的可疑代码片段和修复建议生成候选补丁，并进行验证和选择。 * 工作流程：首先，分析缺陷的根本原因，必要时通过知识图谱或工具包检索额外的依赖信息。其次，被明确要求解释其提出的修复为何能解决问题，以增强可解释性。最后，生成可执行的补丁。在补丁生成后，SGAgent采用一个三阶段的验证流水线进行筛选：1) 回归测试：对每个补丁执行回归测试，记录通过测试数，并据此排名选择表现最佳的子集；2) 复现测试：使用另一个LLM根据问题描述自动构建复现测试，对上一步选出的补丁执行，再次排名；3) 规范化与多数投票：对剩余补丁进行规范化处理，并应用多数投票，选择语义最一致的一个作为最终补丁。 * 核心创新（特殊方法）：验证流水线集成了测试反馈，提高了补丁的功能正确性和语义可靠性。
（四） 动态记忆摘要机制 为了解决长对话历史导致的上下文稀释和幻觉问题，SGAgent引入了动态记忆摘要机制。当某个智能体的消息队列中累积的令牌超过预设阈值时，会调用一个专门的摘要LLM来压缩当前对话历史，生成的摘要作为后续探索和推理的上下文的一部分保留，而只保留最近的部分消息，并确保工具调用-响应消息对的完整性。这平衡了长上下文保留和内存效率。
（五） 实验与评估流程 1. 研究问题：研究设定了四个研究问题来评估SGAgent：与其他基线方法相比的性能如何；各组件对性能的贡献；使用不同基础模型时的表现；在漏洞修复任务上的泛化能力。 2. 基准测试与数据对象：主要评估在SWE-Bench-Lite基准上进行，该基准包含来自12个活跃维护的GitHub Python项目的300个真实世界、完整且可复现的缺陷实例。每个实例包括项目仓库的快照、可执行的测试套件和自然语言问题描述。 3. 基线方法：选择了DARS Agent、LingXi、OpenHands、KGCompass等四种在SWE-Bench排行榜上先进的方法作为基线进行比较。 4. 评估指标：采用四个指标：解决率（% Resolved，成功通过所有测试的实例比例）、文件级定位准确率（File Acc.）、函数级定位准确率（Func Acc.）以及平均修复成本（Avg Cost per Bug）。 5. 实现细节：框架基于LangChain和LangGraph构建。主要使用Claude-3.5-Sonnet作为基础模型，并测试了DeepSeek-V3和Qwen3-235b-a22b以评估模型无关性。知识图谱构建使用了Tree-sitter、Python AST和Pygments。
四、 主要研究结果及其逻辑关联 （一） RQ1：与最先进方法的比较结果 在SWE-Bench-Lite上，SGAgent（使用Claude-3.5）取得了51.3%的解决率，显著优于所有使用相同基础模型的基线方法，在所有评估方法中总体排名第五（优于某些使用更新或更复杂模型的方法）。在定位准确率方面，SGAgent的文件级和函数级准确率分别达到81.2%和52.4%，在使用Claude-3.5的方法中均为最高。在计算成本方面，SGAgent平均每个实例花费1.48美元，在所有方法中成本排名第三低，表现出较高的性价比。重叠分析显示，SGAgent成功修复了14个其他所有Claude-3.5基线都未能修复的独特实例，数量排名第二。这些结果强有力地证明了SGAgent框架在仓库级软件修复中的有效性、精准性和独特性。“建议”阶段的引入有效扩展了智能体的推理边界。
（二） RQ2：消融研究结果 移除关键组件导致性能下降，验证了各组件的重要性。 1. 移除知识图谱模块：解决率下降5.3%，文件级和函数级定位准确率分别下降3.1%和4.0%。这表明，没有基于知识图谱的检索，智能体难以充分理解大型仓库的语义，从而削弱了后续阶段的性能。 2. 移除建议模块：对定位准确率影响甚微（分别下降0.9%和0.5%），但解决率急剧下降13.3%。这一结果至关重要，它直接证实了研究动机：引入“建议”阶段能显著增强语义级推理和跨阶段协调，是提升复杂仓库级修复任务成功率的关键，且不影响初始定位的准确性。 3. 重排序模块分析：仅使用多数投票策略（40.3%）已优于贪婪采样（37.7%）。逐步加入回归测试和复现测试后，解决率分别提升至44.7%和51.3%。这证明多阶段验证流水线对于筛选高质量、语义一致的补丁至关重要。
（三） RQ3：不同基础模型的性能结果 SGAgent在不同基础模型上表现出一致的性能排序：Claude-3.5（51.3%， 81.2%， 52.4%）> DeepSeek-V3（37.7%， 77.7%， 51.7%）> Qwen3-235b-a22b（32.7%， 71.0%， 45.3%）。定位准确率的差距小于解决率的差距，表明知识图谱检索对基础模型能力的依赖较小，而“建议”和“修复”阶段对模型的推理、综合和指令遵循能力更为敏感。总体框架在不同模型间保持一致的性能趋势，证明了其模型无关性和强大的泛化能力。
（四） RQ4：在漏洞修复任务上的泛化能力结果 将SGAgent扩展为SGAgent-Vul，并在Vul4J和VJBench漏洞数据集上评估。SGAgent-Vul总体实现了48.0%的解决率，优于所有基线方法（FSV、NTR、VRPilot）。消融研究同样显示了建议模块和知识图谱模块的重要性（移除后解决率分别降至26.0%和22.0%）。使用不同基础模型（GPT-4o， DeepSeek-V3， Qwen3）时，性能排序与RQ3类似，DeepSeek-V3表现最佳（52.0%）。这些结果证明SGAgent不仅在通用软件修复上有效，也能成功泛化到专门的漏洞修复领域，且其框架设计稳健，组件有效性在不同任务中得到验证。
五、 研究结论与意义价值 本研究提出了SGAgent，一个创新的、基于建议引导的多智能体框架，用于自动化修复现实世界的仓库级软件缺陷。其核心贡献在于用模仿专家调试专长的“定位-建议-修复”范式取代了传统的“定位-修复”范式，通过引入一个额外的“建议”阶段来弥合“错误在哪里”和“如何修复”之间的推理鸿沟。同时，研究首次开发了一个基于自主实现的细粒度知识图谱的、面向复杂场景的工具包，并紧密集成到多智能体框架中。 该研究的科学价值在于：1）为仓库级软件修复问题提供了新的、更符合认知过程的解决范式；2）展示了知识图谱在增强LLM对复杂代码库全局上下文感知和推理能力方面的潜力；3）验证了多智能体协作与工具使用在解决复杂、多步骤软件工程任务上的有效性。 其应用价值显著：SGAgent在标准基准测试上达到了先进的修复准确率（51.3%），同时保持了较低的成本（$1.48/实例），展示了在实际开发流水线中辅助或自动化部分调试和修复工作的潜力。开源实现促进了该领域的可复现性和进一步研究。
六、 研究亮点 1. 范式创新：“定位-建议-修复”范式是本研究最核心的亮点，它有效解决了现有方法中的目标不匹配、依赖不完美定位和缺少中间规划等根本挑战，并通过实验证明了其带来的显著性能提升（解决率提升13.3%）。 2. 方法集成创新：首次开发并集成了一个复杂的、基于细粒度知识图谱的场景导向工具包。该工具包包含14个专门工具，显著增强了智能体的上下文检索和仓库理解能力，带来了3.1%的整体性能提升。 3. 综合性能优越：在使用相同基础模型（Claude-3.5）的条件下，SGAgent在修复准确率、定位准确率上全面超越现有基线，并且能够修复许多其他方法无法处理的独特实例，同时成本效益高。 4. 强大的泛化能力：研究不仅证明了SGAgent在通用软件修复（SWE-Bench）上的有效性，还通过扩展实验证明了其在跨任务（漏洞修复）和跨编程语言（Java）上的强大泛化能力，凸显了框架设计的稳健性和通用性。 5. 可解释性与工程化：框架强调可解释性（如修复器需解释修复原因）和工程实用性（集成多阶段测试验证、动态记忆管理），提高了修复结果的可信度和系统的稳定性，更贴近实际应用需求。