清华开源RepoAgent：大模型驱动的项目级代码文档生成框架

来源：TsinghuaNLP@公众号
声明：本文只做分享，版权归原作者，侵权私信删除！

编辑：青稞AI

在软件工程领域，代码文档的质量直接关系到开发效率和软件质量。然而，文档的生成和维护往往耗费大量的时间和资源，成为项目团队的一大负担。针对这一问题，我组联合中国人民大学和西门子公司的研究人员，共同提出开源框架RepoAgent。RepoAgent 底层由大型语言模型（LLM）驱动，旨在自动化生成、自动维护和更新项目级别的代码文档，全程无需人类介入，极大地提升了软件开发和维护的效率。

论文信息

paper：RepoAgent: An LLM-Powered Open-Source Framework for Repository-level Code Documentation Generation
arXiv：https://arxiv.org/abs/2402.16667
code：https://github.com/OpenBMB/RepoAgent

系统架构

RepoAgent 通过三个关键的技术模块实现：全局结构解析、项目级文档生成和文档自动维护更新，旨在提升代码库的可理解性和维护效率。

RepoAgent 的三个关键技术模块

全局结构解析

全局结构解析阶段，RepoAgent 解析维护代码库中所有代码对象的元信息和语义层次关系。具体来说，通过应用深度递归和抽象语法树（AST）分析，RepoAgent精确解析每个 Python 文件中的类和函数，并根据代码对象的层次关系构建项目树（Project Tree）。随后，RepoAgent 解析出代码对象间的双向引用关系（Bidirectional References），为LLM提供全局的上下文视野以辅助识别代码的功能语义，为生成细粒度的实用代码文档提供支持。

文档生成

文档生成阶段，RepoAgent 生成细粒度的代码文档，其中包含代码对象的功能描述、参数描述、代码描述、注意事项和使用示例。RepoAgent 结合前一阶段解析的元信息和双向引用关系，通过精心设计的 Prompt 模板，使用 LLM 生成结构化的代码文档。RepoAgent 将生成的代码文档编译为标准 Markdown 格式，并利用GitBook 渲染成更便于导航和阅读的 Web 图形界面。

文档更新

文档更新阶段，RepoAgent 实现无缝集成 Git 工具，完成代码跟踪并自动更新文档。RepoAgent 利用 Git 的 pre-commit hook 在代码提交阶段跟踪检测代码变更并执行文档更新，确保代码和文档保持同步。在更新策略上，RepoAgent 只对局部的受影响代码进行文档更新，提高生成效率并维持整体文档的一致性。这一过程完全自动化，无需改变操作流程和开发习惯，也无需人工干预。

更新 ChatDev 函数的文档

案例展示

以 ChatDev 代码库为例，RepoAgent 为其生成的代码文档包含以下结构：功能描述 (Functionality) 、参数描述(Parameters or Attribute)、代码描述(Code Description)、注意事项 (Note)，以及示例 (Output Example)，实现了准确清晰的结构化代码文档。

由 RepoAgent 生成的 ChatDev 存储库的代码文档演示

根据以上案例，RepoAgent 展现了其卓越的效率和成本效益。在采用 gpt-4-0125-preview 模型、并配置 25 个并发线程的设置下，仅用 15 分钟和 15 美元即完成了对项目仓库内全部 390 个对象的文档生成，RepoAgent 不仅在时间效率上超越传统方法，同时在经济成本上也展现出极高的性价比，为开发者和企业减轻经济负担的同时，显著提升工作效率。

人类评估

在人类评估实验中，通过把 RepoAgent 生成的文档与人类编写的文档进行比较，验证了 RepoAgent 在 Transformers 和 LlamaIndex 代码库上的文档生成质量均超过了人类，胜率分别达到了 70% 和 91.33%，凸显了 RepoAgent 在自动生成代码文档方面的优越表现。

人工编写和模型生成的代码文档的人类偏好测试结果

机器评估

实验从引用关系识别（图1）、格式对齐（图2）、参数识别（图3）三个角度对生成的文档进行了定量评估。实验结果表明 RepoAgent 在全局范围的代码上下文感知和局部范围的代码理解中都表现优越，生成的文档具有高度的格式一致性。

图1: 识别参考关系的召回率

图2: 不同LLM的格式对齐准确度

图3: 使用不同LLM作为后端的识别函数参数的准确度

创新点

针对代码文档自动生成和维护，RepoAgent通过将代码、项目结构、代码父子级关系以及双向引用关系相结合，创新性地赋予了大语言模型项目级别的全局视野能力，首次实现了项目级别的细粒度代码文档自动化生成和主动更新，从而极大减轻了开发者在文档编写上的负担，提高了团队协作效率。

总结

本研究成果推出了 RepoAgent 开源框架，为项目级别的代码库生成细粒度的代码文档，并实现了代码文档构建和更新维护的自动化。RepoAgent 有望大幅减轻软件开发人员的文档维护负担，提高代码库的可维护性和可理解性，带来新的软件开发流程范式。

---

备注：昵称-学校/公司-方向/会议(eg.ACL)，进入技术/投稿群

id：DLNLPer，记得备注呦