RepoAgent：一个基于大语言模型的仓库级代码文档生成框架。

英文说明文档 • 简体中文说明文档

:tv: 演示

👾 背景

在计算机编程领域，全面的项目文档——包括对每个Python文件的详细说明——其重要性毋庸置疑。这类文档是理解、维护和改进代码库的基础。它为代码提供了必要的背景信息和设计意图，使当前及未来的开发者更容易掌握软件的目的、功能和结构。这不仅有助于现有和新加入的开发人员快速理解项目的用途与架构，还能确保项目长期可访问性和可修改性，从而显著降低新成员的学习曲线。

传统上，创建和维护软件文档需要大量的人力与专业知识，这对缺乏专职人员的小团队而言是一项挑战。而随着GPT等大型语言模型（LLMs）的出现，这一局面发生了根本性的转变：AI如今能够承担起大部分文档编写工作。这样一来，人类开发者便可以将精力集中在审核与微调上，大大减轻了手动撰写文档的负担。

🏆 我们的目标是打造一款智能文档助手，帮助人们阅读和理解代码仓库，并自动生成文档，最终提升效率、节省时间。

✨ 功能

• 🤖 自动检测Git仓库中的变更，跟踪文件的新增、删除和修改。
• 📝 独立通过抽象语法树（AST）分析代码结构，为各个代码对象生成文档。
• 🔍 准确识别对象间的双向调用关系，丰富文档内容的全局视角。
• 📚 根据变更无缝替换Markdown内容，保持文档的一致性。
• 🕙 执行多线程并发操作，提升文档生成效率。
• 👭 提供可持续的自动化文档更新方案，助力团队协作。
• 😍 以惊艳的方式展示代码文档。（每个项目都配有由Gitbook驱动的文档书）

🚀 快速入门

安装方法

使用GitHub Actions

本仓库支持GitHub Actions，可用于自动化构建、测试和部署等工作流。有关如何在此仓库中设置和使用GitHub Actions的详细说明，请参阅actions/run-repoagent。

使用pip（推荐用户使用）

直接通过pip安装repoagent包：

pip install repoagent

使用PDM进行开发环境搭建

如果您希望参与贡献或搭建开发环境：

• 安装PDM：如果尚未安装，请先安装PDM。

• 使用CodeSpace，或克隆仓库：

  • 使用CodeSpace 这是最简便的获取RepoAgent开发环境的方式。点击下方链接即可使用GitHub Codespace，然后进入下一步。

  

  • 克隆仓库

  git clone https://github.com/LOGIC-10/RepoAgent.git
  cd RepoAgent
  

• 使用PDM进行环境配置

  • 初始化Python虚拟环境。请务必在/RepoAgent目录下运行以下命令：

    pdm venv create --name repoagent
    

  • 激活虚拟环境

  • 使用PDM安装依赖项：

     pdm install
    

配置RepoAgent

在配置RepoAgent的具体参数之前，请确保已在命令行中将OpenAI API密钥设置为环境变量：

export OPENAI_API_KEY=YOUR_API_KEY # 在Linux/Mac上
set OPENAI_API_KEY=YOUR_API_KEY # 在Windows上
$Env:OPENAI_API_KEY = "YOUR_API_KEY" # 在Windows (PowerShell)上

运行 RepoAgent

进入 RepoAgent 的根目录，并在终端中尝试以下命令：

repoagent run #此命令将生成文档，或更新文档（pre-commit 钩子会自动调用）
repoagent run --print-hierarchy # 打印 RepoAgent 如何解析目标仓库

run 命令支持以下可选标志（如果设置，则会覆盖配置默认值）：

• -m, --model TEXT：指定用于补全的模型。默认值：gpt-3.5-turbo
• -t, --temperature FLOAT：设置模型的生成温度。较低的值会使模型更加确定性。默认值：0.2
• -r, --request-timeout INTEGER：定义 API 请求的超时时间（以秒为单位）。默认值：60
• -b, --base-url TEXT：API 调用的基础 URL。默认值：https://api.openai.com/v1
• -tp, --target-repo-path PATH：目标仓库的文件系统路径。用作文档生成的根目录。默认值：path/to/your/target/repository
• -hp, --hierarchy-path TEXT：项目层级文件的名称或路径，用于组织文档结构。默认值：.project_doc_record
• -mdp, --markdown-docs-path TEXT：存放或生成 Markdown 文档的文件夹路径。默认值：markdown_docs
• -i, --ignore-list TEXT：文档生成过程中需要忽略的文件或目录列表，用逗号分隔。
• -l, --language TEXT：文档的语言 ISO 639 代码或语言名称。默认值：Chinese
• -ll, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]：设置应用程序的日志级别。默认值：INFO

你还可以尝试以下功能：

repoagent clean # 清除 RepoAgent 相关缓存
repoagent diff # 检查基于当前代码变更将更新或生成哪些文档

如果你是首次为目标仓库生成文档，RepoAgent 会自动创建一个维护全局结构信息的 JSON 文件，并在目标仓库的根目录下创建名为 Markdown_Docs 的文件夹来存储文档。

一旦你为目标仓库初步生成了全局文档，或者你克隆的项目已经包含全局文档信息，你就可以通过在目标仓库中配置 pre-commit 钩子，与团队无缝、自动地维护项目内部文档！

使用 pre-commit

RepoAgent 目前支持为项目生成文档，这需要在目标仓库中进行一些配置。

首先，确保目标仓库是一个 Git 仓库，并且已经初始化。

git init

在目标仓库中安装 pre-commit，以检测 Git 仓库中的变化。

pip install pre-commit

在目标仓库的根目录下创建一个名为 .pre-commit-config.yaml 的文件。示例如下：

repos:
  - repo: local
    hooks:
    - id: repo-agent
      name: RepoAgent
      entry: repoagent
      language: system
      pass_filenames: false # 防止将文件名传递给钩子
      # 你可以指定触发钩子的文件类型，但目前仅支持 Python。
      types: [python]

有关钩子的具体配置方法，请参阅 pre-commit。

配置好 YAML 文件后，执行以下命令安装钩子：

pre-commit install

这样一来，每次 Git 提交都会触发 RepoAgent 的钩子，自动检测目标仓库中的变化并生成相应的文档。

接下来，你可以在目标仓库中进行一些修改，比如添加新文件或修改现有文件。

只需按照正常的 Git 工作流程操作：git add、git commit -m "你的提交信息"、git push。

RepoAgent 钩子会在 Git 提交时自动触发，检测你上一步添加的文件，并生成相应的文档。

执行完成后，RepoAgent 会自动修改目标仓库中的暂存文件，并正式提交本次更改。执行完毕后，会显示绿色的“Passed”，如图所示：

生成的文档将存储在目标仓库根目录下指定的文件夹中。生成文档的渲染效果如下：

我们使用默认模型 gpt-3.5-turbo 为 XAgent 项目生成了文档，该项目约有 27万行 代码。你可以在 GitHub 上 XAgent 项目的 Markdown_Docs 目录中查看此次生成的结果。为了提升文档质量，我们建议考虑使用更先进的模型，如 gpt-4-1106 或 gpt-4-0125-preview。

最后，你可以通过自定义提示词灵活调整文档的输出格式、模板等。我们期待你探索更科学的自动化技术写作方法，并为社区做出贡献。

探索与仓库聊天

我们设想 Chat With Repo 是这些下游应用的统一入口，充当连接 RepoAgent 与人类用户及其他 AI 代理的桥梁。未来的研究将专注于适配各种下游应用的接口，并根据其独特特性和实施需求进行定制化。

这里我们展示了一个下游任务的初步原型：针对问题的自动问答和代码解释。你可以通过运行以下代码启动服务器。

pip install repoagent[chat-with-repo]
repoagent chat-with-repo

✅ 未来工作

• 结合全局文档自动生成 README.md
• 多编程语言支持 支持更多编程语言，如 Java、C 或 C++ 等。
• 支持本地模型，如 Llama、chatGLM、Qwen、GLM4 等。

🥰 特色案例

以下是一些采用 RepoAgent 的特色案例：

• MiniCPM：一款 2B 规模的边缘侧 LLM，性能可媲美 7B 模型。
• ChatDev：用于软件开发的协作式 AI 代理。
• XAgent：用于解决复杂任务的自主 LLM 代理。
• EasyRL4Rec：面向推荐系统的易用 RL 库。

📊 引用

@misc{luo2024repoagent,
      title={RepoAgent：一个由大语言模型驱动的开源仓库级代码文档生成框架}, 
      author={Qinyu Luo 和 Yining Ye 和 Shihao Liang 和 Zhong Zhang 和 Yujia Qin 和 Yaxi Lu 和 Yesai Wu 和 Xin Cong 和 Yankai Lin 和 Yingli Zhang 和 Xiaoyin Che 和 Zhiyuan Liu 和 Maosong Sun},
      year={2024},
      eprint={2402.16667},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

RepoAgent 快速上手指南

RepoAgent 是一个基于大语言模型（LLM）的框架，旨在自动生成仓库级别的代码文档。它能自动检测 Git 变更、分析代码结构并维护 Markdown 文档，帮助开发者高效理解和管理项目代码。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：支持 Python 3.8+
• Git：已安装并配置好 Git 环境
• API Key：需要拥有 OpenAI API Key（或兼容的 LLM API Key）

安装步骤

推荐使用 pip 进行安装：

pip install repoagent

提示：如果您希望体验“与仓库对话”（Chat With Repo）功能，请使用以下命令安装扩展包：

pip install repoagent[chat-with-repo]

开发环境搭建（可选）

如果您打算贡献代码或进行二次开发，建议使用 PDM 管理环境：

git clone https://github.com/LOGIC-10/RepoAgent.git
cd RepoAgent
pdm venv create --name repoagent
# 激活虚拟环境后执行
pdm install

基本使用

1. 配置 API Key

在使用前，需在终端设置环境变量以加载您的 API Key：

Linux / macOS:

export OPENAI_API_KEY=YOUR_API_KEY

Windows (CMD):

set OPENAI_API_KEY=YOUR_API_KEY

Windows (PowerShell):

$Env:OPENAI_API_KEY = "YOUR_API_KEY"

2. 生成文档

进入您的目标项目根目录，运行以下命令即可自动生成或更新文档：

repoagent run

执行成功后，RepoAgent 会在项目根目录下创建 markdown_docs 文件夹存储生成的 Markdown 文档，并生成 .project_doc_record 文件以记录全局结构信息。

常用参数示例：

• 指定模型（如使用 GPT-4）：

  repoagent run -m gpt-4-1106-preview
  

• 指定生成语言为中文（默认即为中文，也可显式指定）：

  repoagent run -l Chinese
  

• 查看解析层级结构：

  repoagent run --print-hierarchy
  

3. 集成 Pre-commit 钩子（自动化维护）

为了实现提交代码时自动更新文档，可配置 pre-commit 钩子：

1. 初始化 Git 并安装 pre-commit（若未安装）：

   git init
   pip install pre-commit
   

2. 创建配置文件：在项目根目录创建 .pre-commit-config.yaml，内容如下：

   repos:
     - repo: local
       hooks:
       - id: repo-agent
         name: RepoAgent
         entry: repoagent
         language: system
         pass_filenames: false
         types: [python]
   

3. 安装钩子：

   pre-commit install
   

配置完成后，每次执行 git commit 时，RepoAgent 将自动检测代码变更并更新相关文档，无需手动干预。

4. 其他实用命令

• 预览变更：检查当前代码变更将如何影响文档（不实际生成）：

  repoagent diff
  

• 清理缓存：移除 RepoAgent 相关的缓存文件：

  repoagent clean
  

• 启动对话服务：启动本地服务器以进行“与仓库对话”功能：

  repoagent chat-with-repo