RepoAgent: 基于 LLM 的代码仓库文档生成框架

English readme • 简体中文 readme

:tv: Demo

👾 背景

在计算机编程领域，全面项目文档的重要性（包括对每个 Python 文件的详细解释）是不言而喻的。此类文档是理解、维护和增强代码库的基石。它为代码提供了必要的上下文和逻辑依据，使当前及未来的开发者能够更容易理解软件的目标、功能和结构。它不仅能帮助开发者掌握项目的目的和架构，还能确保项目在长期的迭代中保持可维护性，显著降低新成员的学习曲线。

传统上，创建和维护软件文档需要大量的人力投入和专业知识，这对于缺乏专门文档人员的小型团队来说是一个挑战。GPT 等大语言模型（LLM）的出现改变了这一现状，使 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-hook 会自动调用此命令）
repoagent run --print-hierarchy # 打印 repo-agent 解析目标仓库的层次结构

run 命令支持以下可选参数（若设置，将覆盖配置文件中的默认值）：

• -m, --model TEXT: 指定用于补全的 LLM 模型。默认：gpt-3.5-turbo
• -t, --temperature FLOAT: 设置模型的生成随机性。值越低，模型输出越确定。默认：0.2
• -r,