RepoAgent：用于存储库级代码文档生成的 LLM 支持的开源框架

Qinyu Luo

{}^{1}

, Yining Ye

{}^{1*}

, Shihao Liang

{}^{1}

, Zhong Zhang

{}^{1}

, Yujia Qin

{}^{1}

, Yaxi Lu

{}^{1}

, Yesai Wu

{}^{1}

,
Xin Cong

{}^{1}

, Yankai Lin

{}^{2}

, Yingli Zhang

{}^{3}

, Xiaoyin Che

{}^{3}

, Zhiyuan Liu

{}^{1{\dagger}}

, Maosong Sun

{}^{1}

{}^{1}

Tsinghua University

{}^{2}

Renmin University of China

{}^{3}

Siemens AG.
qinyuluo123@gmail.com, yeyn2001@gmail.com Indicates equal contribution. Corresponding Author.

摘要

生成模型在软件工程中展示了巨大的潜力，特别是在代码生成和调试等任务中。然而，它们在代码文档生成领域的利用仍未得到充分探索。为此，我们引入了RepoAgent，这是一个大型语言模型驱动的开源框架，旨在主动生成、维护和更新代码文档。通过定性和定量评估，我们验证了我们方法的有效性，表明 RepoAgent 在生成高质量存储库级文档方面表现出色。代码和结果可通过 https://github.com/OpenBMB/RepoAgent 公开访问。

1简介

Refer to caption — 图1：简单摘要方法和建议的 RepoAgent 生成的代码文档的比较。

开发人员通常花费大约 58% 的时间用于程序理解，而高质量的代码文档在减少此时间方面发挥着重要作用（Xia 等人，2018；de Souza 等人，2005）。然而，维护代码文档也会消耗大量的时间、金钱和人力（Zhi等人，2015），而且并非所有项目都有资源或热情将文档作为首要关注点。

为了减轻维护代码文档的负担，自动文档生成的早期尝试旨在为源代码提供描述性摘要（Sridhara 等人，2010；Rai 等人，2022；Khan 和 Uddin，2022；Zhang 等人，2022 )，如图1所示。然而，它们仍然存在很大的局限性，特别是在以下方面：（1）总结性差。以前的方法主要侧重于总结孤立的代码片段，忽略了更广泛的存储库级别上下文中代码的依赖关系。生成的代码摘要过于摘要和碎片化，导致难以准确传达代码语义以及将代码摘要编译成文档。（2）指导不足。好的文档不仅能准确描述代码的功能，还能细致地指导开发者正确使用所描述的代码（Khan and Uddin，2022；Wang等人，2023）。这包括但不限于澄清功能边界、强调潜在的误用以及提供输入和输出的示例。以前的方法仍然无法提供如此全面的指导。（3）被动更新。雷曼软件演化第一定律指出，正在使用的程序将不断演化以满足新的用户需求（Lehman，1980）。因此，及时更新文档以与代码更改保持一致至关重要，这是以前的方法忽略的功能。最近，大语言模型（Large Language Models）取得了重大进展（OpenAI，2022，2023），特别是在代码理解和生成方面（Nijkamp 等人，2023；Li 等人，2023 ; Chen 等人, 2021; Rozière 等人, 2023; Xu 等人, 2024; Sun 等人, 2023; Wang 等人, 2023; Khan 和 Uddin, 2022)。鉴于这些进步，人们很自然地会问：大语言模型能否用于生成和维护存储库级代码文档，解决上述限制？

在本研究中，我们介绍了RepoAgent，这是第一个由大语言模型支持的框架，旨在主动生成和维护整个存储库的综合文档。图1中演示了一个运行示例。 RepoAgent提供以下功能： (1) 存储库级文档： RepoAgent利用全局上下文来推断整个存储库中目标代码对象的功能语义，从而能够生成准确且语义一致的结构化文档。 (2) 实践指导： RepoAgent不仅描述了代码的功能，还提供了实用的指导，包括代码使用说明、输入输出示例等，方便开发者快速理解代码库。 (3)维护自动化： RepoAgent可以无缝集成到使用 Git 管理的团队软件开发工作流程中，并主动接管文档维护，确保代码和文档保持同步。这个过程是自动化的，不需要人工干预。

我们定性地展示了 RepoAgent 为真实的 Python 存储库生成的代码文档。结果表明，RepoAgent 擅长生成与人类创建的质量相当的文档。从数量上看，在两次盲目偏好测试中，RepoAgent生成的文档比人类编写的文档更受青睐，在 Transformers 和 LlamaIndex 存储库上分别达到了 70% 和 91.33% 的偏好率。这些评估结果表明了所提出的RepoAgent在自动代码文档生成方面的实用性。

2 RepoAgent

RepoAgent由三个关键阶段组成：全局结构分析、文档生成和文档更新。 2展示了RepoAgent的整体设计。全局结构分析阶段涉及从源代码中解析必要的元信息和全局上下文关系，为RepoAgent推断目标代码的功能语义奠定基础。在文档生成阶段，我们设计了一套复杂的策略，利用解析的元信息和全局上下文关系来促使大语言模型生成具有实际指导意义的细粒度文档。在文档更新阶段，RepoAgent利用Git工具跟踪代码变更并相应更新文档，确保代码和文档在整个项目生命周期中保持同步。

2.1全局结构分析

生成准确且细粒度的代码文档的一个重要先决条件是对代码结构的全面理解。为了实现这一目标，我们提出了项目树，这是一种数据结构，用于维护存储库中的所有代码对象，同时保留它们的语义层次关系。首先，我们过滤掉存储库中的所有非 Python 文件。对于每个Python文件，我们应用摘要语法树（AST）分析（Zhang等人，2019）来递归解析文件中所有类和函数的元信息，包括它们的类型、名称、代码片段等这些与其元信息关联的类和函数被用作文档生成的原子对象。值得注意的是，大多数设计良好的存储库的文件结构都反映了代码的功能语义。因此，我们首先利用它来初始化项目树，其根节点代表整个存储库，中间节点和叶子节点分别代表目录和Python文件。然后，我们将解析后的类和函数作为新的叶节点（或子树）添加到相应的Python文件节点中，形成最终的项目树。

除了代码结构之外，代码内部的引用关系作为一种重要的全局上下文信息，也可以帮助大语言模型识别代码的功能语义。此外，对目标函数的引用可以被视为自然的上下文学习示例（Wei等人，2022）来教大语言模型使用目标函数，从而帮助生成实用的文档指导。我们考虑两种类型的引用关系：Caller 和 Callee。我们使用 Jedi 库¹¹1https://github.com/davidhalter/jedi 通过替换代码解析工具，可扩展到Python以外的编程语言。提取存储库中的所有双向引用关系，然后将它们接地到项目树中相应的叶节点。通过引用关系增强的项目树形成有向无环图²²2我们只是忽略了循环依赖以避免循环，因为大多数情况都可能存在错误。（有向无环图）。

2.2文档生成

RepoAgent旨在生成具有实用指导意义的细粒度文档，其中包括详细的功能、参数、代码说明、注释和示例。后端大语言模型利用前一阶段解析的元信息和参考关系，使用精心设计的提示模板生成具有所需结构的文档。图 3 显示了一个说明性的提示模板，LABEL:lst:prompt_template 中给出了完整的真实提示示例。

提示模板主要需要以下参数： Project Tree帮助RepoAgent感知存储库级别的上下文。代码片段充当RepoAgent生成文档的主要信息来源。参考关系提供代码对象之间的语义调用关系，并协助RepoAgent生成指导说明和示例。元信息表示目标对象的类型、名称、相对文件路径等必要信息，用于文档的后处理。另外，我们可以将之前生成的对象直接子节点的文档作为辅助信息来帮助理解代码。这是可选的，因为省略它可以显着节省成本。

RepoAgent遵循从下到上的拓扑顺序为DAG中的所有代码对象生成文档，确保每个节点的子节点以及它引用的节点都在之前生成了文档它。文档生成后，RepoAgent将其编译为人类友好的 Markdown 格式。例如，不同级别的对象与不同的 Markdown 标题相关联（例如，##、###）。最后，RepoAgent利用 GitBook³³3https://www.gitbook.com/ 将 Markdown 格式的文档呈现为方便的 Web 图形界面，为文档读者提供轻松的导航和可读性。

2.3文档更新

RepoAgent通过与 Git 无缝协作支持自动跟踪和更新文档。 Git 的预提交钩子用于使 RepoAgent 能够检测任何代码更改并执行文档更新。更新后，挂钩会提交代码和文档更改，确保代码和文档保持同步。这个过程是完全自动化的，不需要人工干预。

由于低耦合原则，本地代码的更改一般不会影响其他代码，不需要每次较小的代码更新都重新生成整个文档。 RepoAgent仅更新受影响对象的文档。当 (1) 对象的源代码被修改时，会触发更新； (2) 对象的引用者不再引用它；或者 (3) 一个对象获得新的引用。值得注意的是，当对象的引用对象发生变化时，不会触发更新，因为我们遵循依赖倒置原则（Martin，1996），该原则规定高层模块不应依赖于低级模块的实现。

3实验

3.1实验设置

我们选择了 9 个不同规模的 Python 存储库来生成文档，代码量从不到 1,000 行到超过 10,000 行不等。这些存储库以其经典地位或在 GitHub 上的高人气而闻名，其特点是高质量的代码和相当大的项目复杂性。 §A.1中提供了存储库的详细统计信息。我们采用了基于API的大语言模型 gpt-3.5-turbo (OpenAI, 2022) 和 gpt-4-0125 ( OpenAI, 2023)，以及开源大语言模型 Llama-2-7b 和 Llama-2-70b (Touvron 等人，2023）作为 RepoAgent 的后端模型。

3.2案例研究

我们使用 ChatDev 存储库 Qian 等人 (2023) 和 gpt-4-0125 后端进行案例研究。生成的文档如图图4所示。 RepoAgent 生成的文档分为几个部分，首先是一个清晰、简洁的句子，阐明了对象的功能。接下来，参数部分枚举所有相关参数及其描述，帮助开发人员了解如何利用所提供的代码。此外，代码描述部分全面阐述了代码的各个方面，隐式或显式地展示了对象的角色及其与全局上下文中其他代码的关联。此外，注释部分通过涵盖手头对象的使用注意事项进一步丰富了这些描述。值得注意的是，它突出显示了代码中的任何逻辑错误或潜在的优化，从而提示高级开发人员进行修改。最后，如果当前对象产生返回值，模型将生成一个示例部分，其中填充模拟内容以清楚地演示预期输出。这对于开发人员来说非常有利，有助于高效的代码重用和单元测试构建。

一旦代码发生更改，就会触发文档更新，如图图5所示。在暂存区域中发生代码更改时，RepoAgent会识别受影响的对象及其双向引用，更新受影响范围最小的文档，并将这些更新集成到新的 Markdown 文件中，其中包括对象的添加或全局删除' 文档。这种自动化扩展到集成 Git 的预提交挂钩来检测代码更改和更新文档，从而在项目开发的同时无缝维护文档。具体来说，当代码更新暂存并提交时，会触发 RepoAgent，自动刷新文档并暂存以进行提交。它通过“通过”指示器确认该过程，无需额外的命令或手动干预，从而保留了开发人员通常的工作流程。

3.3人类评价

由于缺乏有效的评估方法，我们采用人工评估来评估生成文档的质量。我们进行了偏好测试来比较人类编写的代码文档和模型生成的代码文档。我们分别从 Transformers 和 LlamaIndex 存储库中随机抽取了 150 份文档内容，其中包括 100 个类对象和 50 个函数级对象。招募了三名评估员来评估这两个文档集的质量，详细的评估协议在 § A.2.2 中概述。 § 3.3 中提供的结果强调了 RepoAgent 在生成超越人类创作内容的文档方面的显着效率，实现了 $0.70$ 和 $0.91$ 。

RepoAgent：用于存储库级代码文档生成的 LLM 支持的开源框架

摘要

1简介

2 RepoAgent

2.1全局结构分析

2.2文档生成

2.3文档更新

3实验

3.1实验设置

3.2案例研究

3.3人类评价

3.4定量分析

参考回忆。

格式对齐。

参数识别。

4相关工作

代码总结。

大语言模型开发。

5结论与讨论

局限性

编程语言的限制。

人类监督的要求。

对语言模型功能的依赖。

缺乏评估标准。

更广泛的影响

提高生产力和创新。

提高软件质量和协作。

教育福利。

偏见和不准确。

安全和隐私问题。

致谢

参考

附录 A附录：实验细节

A.1实施细节

A.2设置

A.2.1技术环境

A.2.2人类评估协议