清华开源RepoAgent：大模型驱动的项目级代码文档生成框架
清华开源RepoAgent：大模型驱动的项目级代码文档生成框架
在软件工程领域，代码文档的质量直接关系到开发效率和软件质量。然而，文档的生成和维护往往耗费大量的时间和资源，成为项目团队的一大负担。针对这一问题，清华大学自然语言处理实验室（TsinghuaNLP）联合中国人民大学和西门子公司的研究人员，共同提出了开源框架RepoAgent。RepoAgent底层由大型语言模型（LLM）驱动，旨在自动化生成、自动维护和更新项目级别的代码文档，全程无需人类介入，极大地提升了软件开发和维护的效率。
系统架构
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代码库为例，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在全局范围的代码上下文感知和局部范围的代码理解中都表现优越，生成的文档具有高度的格式一致性。
图2:不同LLM的格式对齐准确度
图3:使用不同LLM作为后端的识别函数参数的准确度
创新点
针对代码文档自动生成和维护，RepoAgent通过将代码、项目结构、代码父子级关系以及双向引用关系相结合，创新性地赋予了大语言模型项目级别的全局视野能力，首次实现了项目级别的细粒度代码文档自动化生成和主动更新，从而极大减轻了开发者在文档编写上的负担，提高了团队协作效率。
总结
本研究成果推出了RepoAgent开源框架，为项目级别的代码库生成细粒度的代码文档，并实现了代码文档构建和更新维护的自动化。RepoAgent有望大幅减轻软件开发人员的文档维护负担，提高代码库的可维护性和可理解性，带来新的软件开发流程范式。
论文信息
- 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