人工智能咨询培训老师叶梓 转载标明出处

开发者通常花费约58%的时间在程序理解上，高质量的代码文档在减少这一时间上扮演着重要角色。然而，维护代码文档同样消耗大量的时间、金钱和人力。为了减轻维护代码文档的负担，早期尝试自动文档生成的方法旨在为源代码提供描述性摘要。但是，这些方法在总结化、指导不足和被动更新方面存在显著局限性。清华大学、中国人民大学和西门子公司的研究团队提出了RepoAgent，一个由大模型（LLM）驱动的开源框架，旨在主动生成、维护和更新代码文档。通过定性和定量评估，验证了本方法的有效性，表明RepoAgent在生成高质量的仓库级文档方面表现出色。代码和结果已在GitHub公开访问。

RepoAgent框架

如图2所示RepoAgent方法分三个组成部分：全局结构分析（Global Structure Analysis）、文档生成（Documentation Generation）和文档更新（Documentation Update）。这三个组件不仅可以独立执行，还可以打包成工具钩子（hook），用于各种工具集成目的。当这三个组件协同工作时，RepoAgent能够确保从头开始构建和维护代码仓库的文档，将文档的重要性提升到与代码同等的水平，从而促进团队之间的同步和协作。

全局结构分析

全局结构分析是构建高质量代码文档的基础。研究者们首先提出了项目树这一概念，它作为理解整个代码库结构的关键数据结构。项目树的构建过程从筛选出Python文件开始，排除了其他非目标语言的文件，以确保分析的准确性。随后，通过应用抽象语法树（AST）分析，研究者们能够递归地解析每个Python文件中的类和函数，详细提取它们的元信息，包括类型、名称和代码片段等。这些信息成为了后续文档生成过程中的基本构建块。

文档生成

文档生成阶段，研究者们设计了一套策略，使得后端的大型语言模型（LLM）能够利用项目树中的元信息和代码间的引用关系，生成结构化且具有实用指导性的文档。这一过程涉及到一个精心构建的提示模板，它能够引导LLM生成包含功能、参数、代码描述、注意事项和示例等部分的文档。

图3提供了一个用于文档生成的提示模板示例，这个模板是与大模型（LLM）交互的接口，指导模型生成结构化且内容丰富的文档。

在文档生成阶段，RepoAgent首先利用项目树（Project Tree）来感知整个代码库的上下文。项目树中的每个节点，代表代码中的一个类或函数，都携带有其元信息，例如类型、名称和相对文件路径。这些元信息为LLM提供了生成文档所需的基本信息。

接着，RepoAgent使用精心设计的提示模板，将这些元信息以及代码片段作为输入传递给LLM。提示模板中包含了一些关键部分，例如：

功能描述（Functionality）：使用清晰、简洁的句子描述代码对象的主要功能。

参数（Parameters）：列举函数或类的参数，并提供每个参数的描述。

代码描述（Code Description）：详细阐述代码的工作原理、逻辑流程以及它在整个项目中的作用。

注意事项（Notes）：提供关于代码使用的额外信息，可能包括潜在的错误、优化建议或其他重要提示。

示例（Examples）：如果代码对象有返回值或特定的使用场景，提供示例可以帮助开发者更好地理解如何使用这段代码。

最后，RepoAgent将LLM生成的文本编译成Markdown格式，这是一种轻量级的标记语言，可以轻松地转换成HTML，用于在Web上展示。Markdown格式的文档具有清晰的结构和易于阅读的样式，使得开发者可以快速浏览和查找所需信息。

文档更新

文档更新是RepoAgent自动化能力的另一重要体现。研究者们通过与Git的紧密集成，实现了文档的自动跟踪和更新。通过Git的预提交钩子，RepoAgent能够在代码提交前自动检测变更，并触发文档的更新流程，确保文档与代码的同步。这一自动化过程显著减少了人工干预的需求，并且由于代码的低耦合特性，RepoAgent能够智能地仅更新受影响部分的文档，而不是每次都重新生成整个文档。文档更新的触发条件包括源代码的修改、引用关系的变更等，这些都是确保文档准确性和时效性的关键因素。

通过这三个阶段的协同工作，RepoAgent不仅提升了文档的质量和可用性，还强化了团队协作的效率，使得每个团队成员都能够轻松访问最新、最准确的项目文档。这种自动化和智能化的文档管理方式，是现代软件开发实践中的一个重要进步，有助于提升开发速度和代码质量。

实验

研究者选择了9个不同规模的Python代码仓库作为实验对象，这些仓库在GitHub上因其经典性或高流行度而被选中，并且具有高代码质量和项目复杂性。研究者提供了这些仓库的详细统计数据，包括代码行数、类和函数的数量。他们还介绍了实验中使用的后端大型语言模型（LLMs），包括gpt-3.5-turbo、gpt-4-0125、Llama-2-7b和Llama-2-70b。

研究者以ChatDev仓库为例，展示了RepoAgent生成的文档。生成的文档结构清晰，首先用简洁的句子描述对象的功能，然后是参数部分，详细列举了所有相关参数及其描述。代码描述部分全面阐述了代码的各个方面，包括对象的角色和它与全局上下文中其他代码的关联。笔记部分进一步丰富了描述，突出了代码中的逻辑错误或潜在优化。如果对象有返回值，模型还会生成示例部分，展示预期输出。

研究者采用了人类评估员来评估RepoAgent生成的文档质量。由于缺乏有效的评估方法，他们进行了偏好测试，比较了人类编写的和模型生成的代码文档。评估员被要求根据一系列评估标准来选择每对文档中的较优者。评估结果显示，RepoAgent生成的文档在质量上超越了人类编写的内容。

“定量分析”部分包含了几个关键的定量测试，用以评估RepoAgent的性能：

参考召回（Reference Recall）：研究者评估了模型识别代码对象全局上下文中的引用关系的能力。他们比较了几种不同的文档生成方法，包括基于机器学习的方法、长上下文连接方法和单对象生成方法。结果显示，RepoAgent使用Jedi工具和双向解析准确传递了全局引用关系，有效克服了其他方法在生成仓库级代码文档时遇到的范围限制。

格式对齐（Format Alignment）：研究者评估了LLMs生成的文档是否遵循了定义的格式。大型模型如GPT系列和Llama-2-70b在格式对齐方面表现良好，而小型模型Llama-2-7b在格式对齐上表现较差。

参数识别（Parameter Identification）：研究者进一步评估了模型在所有9个仓库中识别参数的能力。结果显示，GPT系列在参数识别方面显著优于LLaMA系列，其中gpt-4-0125表现最佳。

经过深入研究和实践，RepoAgent已被证明是一个强大的工具，它不仅提升了代码文档的生成质量，还显著增强了开发团队的协作效率。虽然存在一些限制，比如目前主要支持Python语言，并且可能需要人工监督来确保文档的准确性和完整性，随着技术的不断发展，RepoAgent将能够克服这些限制，服务于更广泛的编程语言和应用场景。

论文链接：https://arxiv.org/abs/2402.16667

项目链接：https://github.com/OpenBMB/RepoAgent