本文介绍了一项由南京大学计算机软件新技术国家重点实验室的潘中强、李传意、钟文康、冯毅、罗斌，以及德克萨斯大学达拉斯分校人类语言技术研究所的Vincent Ng共同完成的原创性研究工作。该研究以“RepoRepair: leveraging code documentation for repository-level automated program repair”为题，于2018年8月发表于*ACM Transactions on Software Engineering and Methodology*期刊第37卷第4期，文章编号为111。
自动化程序修复（Automated Program Repair， APR）是软件工程领域的关键技术，旨在自动定位并修复代码中的缺陷。随着大型语言模型（Large Language Models, LLMs）如GPT-4和DeepSeek-V3的崛起，APR在函数级修复方面取得了显著进展。然而，将修复能力从孤立的函数扩展到完整的代码仓库（repository-level）面临巨大挑战。修复仓库级问题不仅需要理解单个函数的逻辑，更需要具备全局的、任务感知的（task-aware）能力，以在错综复杂的跨文件依赖中准确定位并实施必要的修改。
当前的主流方法存在明显的局限性。一方面，基于智能体（agent-based）的方法（如SWE-Agent）依赖于LLM与环境的多次交互迭代，虽然灵活但计算成本高昂，且容易受到错误反馈的误导。另一方面，非智能体（agent-free）方法（如Agentless）虽然成本较低，但在利用仓库信息方面往往停留在表面，仅依赖目录结构树和基于检索的零散代码片段。这种方法在处理复杂、跨文件的问题时显得力不从心，尤其是在新兴的、包含多模态信息（如图像、截图）的软件开发场景中。
这种局限性的根源在于缺乏一种能够有效连接高层次问题描述与低层次代码变更的、结构化的仓库语义表示。代码文档（code documentation）作为开发中系统化抽象实现细节、辅助程序理解和维护的认知工具，为解决这一问题提供了灵感。基于此，研究团队提出了RepoRepair，其核心洞察在于：利用LLM为代码仓库生成层次化的代码文档（从函数级到文件级），创造出结构化的语义抽象，从而赋能LLM理解仓库级的上下文和依赖关系。
本研究旨在设计并验证一个新颖的、文档增强的（documentation-enhanced）仓库级自动化程序修复框架。具体目标包括：1）通过生成层次化代码文档，显著提升基于LLM的缺陷定位（fault localization）精度；2）设计一个高效、鲁棒的修复流程，能够生成并通过测试验证最小化的代码补丁；3）在极具挑战性的基准测试集（如SWE-Bench Lite和SWE-Bench Multimodal）上实现具有竞争力甚至领先的修复成功率，同时保持较低的平均修复成本。
RepoRepair是一个无智能体（agent-free）的两阶段框架，其工作流程包含三个核心阶段：文档生成、定位和修复。整个流程被形式化为一个算法（Algorithm 1），依次执行。
第一阶段：文档生成 此阶段旨在为整个目标仓库的所有代码文件生成结构化的知识库。研究采用基于文本的LLM（如DeepSeek-V3）来完成此任务，温度参数设置为0以保证输出的确定性和事实准确性。 1. 函数/类级文档生成：首先，使用开源库Tree-sitter对源代码文件进行解析，生成与语言无关的抽象语法树（AST），系统性地提取函数、类、导入、调用等关键程序结构。对于JavaScript/TypeScript中的匿名函数（如箭头函数），会分配“function_x”格式的标准名称。接着，为每个函数或类构造提示词（Prompt），输入其完整的源代码和提取的元数据（名称、签名、上下文、依赖等），要求LLM生成标准化的文档，内容包含参数介绍、代码描述、使用说明和输出示例。 2. 文件级文档生成：在获得所有函数级文档后，为每个文件生成更高层次的摘要。提示词会输入该文件的所有函数级文档以及项目结构树，要求LLM生成包含两部分内容的文档：一是对文件中每个函数/类功能的简明总结；二是对整个文件在项目中的架构角色和依赖关系的高级描述。 *关键设计*：为了模拟真实开发流程并优化成本，RepoRepair采用了增量文档生成策略。处理同一仓库中的多个问题时，按GitHub Issue ID（通常代表时间顺序）升序处理，仅对相较于上一个问题状态发生变化的文件重新生成文档，未改变的文件复用之前的文档。
第二阶段：多模态缺陷定位 此阶段的目标是从数百个文件中精确定位需要修改的少数几个函数或类。这是一个分层三步骤的流水线。 1. 检索最相关文件：为了避免将整个仓库的原始代码输入LLM带来的巨大上下文开销，本研究使用文件级代码文档作为代理进行检索。首先将所有文件级文档通过嵌入模型（如sentence-transformers/all-mpnet-base-v2）向量化并构建索引（Faiss数据库）。对于问题描述，如果是多模态的（包含截图等），会先用多模态LLM（如Claude-4）将其转换为全面的文本分析报告（描述错误行为和根本原因），再将此文本作为查询向量。根据语义相似度，检索出与问题最相关的Top-50个文件。 2. 定位可疑文件：从检索出的文件中，进一步筛选出最可能包含缺陷的少数文件。这里继续向LLM提供这些候选文件的文件级文档（而非完整代码），要求LLM分析问题描述，并利用思维链（Chain-of-Thought, CoT）推理，输出一个最可疑文件的排序列表（默认取Top-5）。 3. 定位相关函数/类：对于每个被定位的可疑文件，进一步缩小范围，精确到需要修改的具体函数或类。此时向LLM提供这些文件的函数级代码文档。LLM基于问题描述和文档语义，识别出文件中需要修改的具体代码单元。此步骤也作为对文件级定位结果的验证：如果在一个被标记为可疑的文件中找不到任何相关的函数/类，则可能意味着文件定位有误，流程会回溯并重新执行文件定位。
第三阶段：上下文感知修复与验证 基于定位结果，生成并验证正确的补丁。 1. 构建修复上下文：简单地提供整个文件的原始代码会引入大量无关噪声。RepoRepair采用了依赖感知的代码剪枝（dependency-aware code pruning）策略。对于每个待修复的文件，保留以下内容：a) 所有被定位为目标的需要修改的函数/类；b) 文件级的结构性语句（如import/require语句、全局变量声明）；c) 任何被保留的目标代码单元在文件内静态引用的、未被定位的其他函数/类。其余所有无关代码均被删除。这创造了一个信息丰富且聚焦的上下文。 2. 生成补丁：将剪枝后的代码文件依次输入给强大的LLM（如Claude-4），要求其基于问题描述生成差分格式（diff-format） 的补丁，即“搜索/替换”编辑对，而不是生成完整的新代码文件。这种方式强制LLM进行最小化、有针对性的修改，降低了产生幻觉（hallucination）的概率，并提高了输出效率和可靠性。 3. 验证补丁：采用一种系统化的、迭代的组合测试验证流程。 * 在每次修复迭代中（温度T固定），会生成针对所有定位文件的候选补丁。 * 组合验证：不单独测试每个补丁，而是测试所有可能的补丁组合。对于n个被修改的文件，测试从单文件补丁（C(n,1)种组合）、两文件组合（C(n,2)），直到所有n个补丁一起应用（C(n,n)）。所有组合在仓库的现有测试套件上进行并行回归测试。 * 最小化选择：在所有通过测试的组合中，选择修改文件数量最少的组合作为当前迭代的最佳结果，这符合软件维护中“最小变更”的最佳实践。 * 温度迭代：如果当前温度下没有产生任何通过测试的组合，则将LLM的温度升高0.1（从0开始，最高到0.9），重新启动新一轮的修复、组合验证和选择流程，以探索更多样化的解决方案。循环直到找到有效补丁或温度达到上限。
研究在两个权威基准上进行了全面评估：SWE-Bench Lite（323个Python仓库问题）和更具挑战性的SWE-Bench Multimodal（619个JavaScript/TypeScript多模态仓库问题）。
整体修复性能： 在SWE-Bench Lite上，RepoRepair取得了45.7%的修复率（%resolved），平均每个修复成本仅为0.44美元。虽然略低于使用Claude-4的顶尖工具Experepair（60.33%），但显著优于其他多个知名基线，如OpenHands（41.67%）、PatchPilot（45.33%），并且成本远低于大多数基于智能体的方法（如SWE-Agent的1.62美元）。 在SWE-Bench Multimodal上，RepoRepair的表现更为突出，取得了37.1%的修复率，达到了当前最先进的（state-of-the-art）性能，超过了此前最好的工具Guirepair（35.98%）和OpenHands-Versa（34.43%），平均成本为0.56美元。这证明了RepoRepair在复杂、跨文件、多模态问题上的强大修复能力。
缺陷定位精度： 定位精度是修复成功的基础。在SWE-Bench Lite上，RepoRepair的文件级定位正确率（%correct localization）达到79.0%，高于Agentless Lite的74.7%。在SWE-Bench Multimodal上，其优势是压倒性的：文件级定位正确率高达59.8%，相比Agentless Lite（30.4%）有近30个百分点的绝对提升，相比Guirepair（44.3%）也有显著优势。这直接印证了其文档增强方法在理解仓库语义、准确找到问题根源方面的有效性。函数级定位也表现出高精度（SWE-Bench Lite 86.5%, Multimodal 88.4%）和高效率（绝大多数情况仅需一轮分析）。
独特修复能力分析： Venn图分析显示，RepoRepair能够解决一些其他顶尖工具无法解决的独特问题。在SWE-Bench Multimodal上，RepoRepair独自修复了21个Guirepair、OpenHands-Versa和Agentless Lite均未能修复的错误。这些问题通常描述中提及的文件很少，需要深度的仓库语义理解，这正是RepoRepair的核心优势。
消融实验（Ablation Study）： 研究通过系统性的消融实验验证了各个核心组件的必要性。 1. 去除文件检索：导致定位阶段需要处理所有文件的文档，使得总计算令牌（token）成本激增（SWE-Bench Lite增长5.6倍），且由于上下文过长导致LLM推理能力下降，修复率分别下降了9.5%（Lite）和4.7%（Multimodal）。 2. 去除代码文档：在定位阶段使用原始代码路径或骨架替代文档。虽然极大降低了令牌成本（Lite降低75%，Multimodal降低66%），但严重损害了定位和修复性能。尤其在Multimodal上，修复率从37.1%暴跌至26.3%，证明了代码文档提供的语义理解对于准确识别跨文件、匿名函数等问题至关重要。 3. 去除代码剪枝：在修复阶段提供完整的未剪枝代码。这增加了修复阶段的令牌成本，并由于引入了大量无关噪声，导致修复率下降（Lite从45.7%降至42.7%，Multimodal从37.1%降至33.7%），证实了依赖感知剪枝策略对于聚焦LLM注意力、生成正确补丁的有效性。 4. 文档质量影响：在Django项目上的对比实验表明，使用较弱模型（Qwen2.5-7B）生成的文档，其质量在人工评估中远逊于DeepSeek-V3（文件级文档偏好度96% vs 4%），并导致整个定位-修复流程性能大幅下降（修复率从58.8%降至34.2%），说明高质量的文档生成是RepoRepair成功的基石。
案例研究： 以问题“carbon-design-system/carbon-3610”为例，问题描述报告了React Listbox组件中一个属性传播缺失的错误。基于关键词匹配的方法错误地定位到了listbox.js。而RepoRepair通过分析文件级和函数级文档建立的语义连接，正确地将根本原因定位到了更高层的组件dropdown.js中的属性传递不当，并生成了与开发者修复完全一致的补丁。这凸显了文档增强方法在超越表面关键词、理解代码间实际关系方面的关键价值。
本研究提出了RepoRepair，一个创新的、利用层次化代码文档实现仓库级自动化程序修复的框架。实验结果表明，该框架在SWE-Bench Lite和SWE-Bench Multimodal两个基准测试上均实现了领先或具有高度竞争力的修复性能，同时保持了良好的成本效益。
本研究的科学价值在于：它首次系统性地提出并验证了将LLM生成的层次化代码文档作为“语义桥梁”，用于连接自然语言问题描述和仓库级代码修改的可行性。这为APR领域，特别是仓库级修复，提供了一种新的、有效的范式。其应用价值显著：RepoRepair作为一种非智能体方法，为在实际软件开发中低成本、高效率地处理复杂的、跨文件的、甚至包含多模态信息的软件维护任务提供了有力的工具前景。研究者已公开所有实验材料（代码、生成文档、结果），以促进可重复性和未来研究。
作者也坦诚指出了RepoRepair的局限：1）目前文档生成仅针对包含函数/类的代码文件，无法处理纯配置文件、静态资源文件等，导致对此类文件的修改支持不足；2）当前工作流假设缺陷存在于已有文件中，无法处理需要创建全新文件的功能请求；3）增量文档生成策略可能无法捕捉未变文件因周围代码变化而产生的角色演变。
针对这些局限，作者提出了未来方向：1）扩展文档覆盖范围，纳入配置文件等；2）通过扩展工作流或受控的智能体方法支持需要创建文件的增量化修改。这些改进旨在进一步提升框架在真实世界复杂场景下的适用性和鲁棒性。