AI 文档生成器

一款基于 AI 的代码文档生成工具，能够自动分析代码仓库，并利用先进的语言模型生成全面的文档。该系统采用多智能体架构，执行专业的代码分析并生成结构化的文档。

📝 博文

阅读该项目的完整故事：

• 🇺🇸 英文：不会腐朽的文档：多智能体 AI 如何重塑我们的工作流程
• 🇮🇷 从代码助手到智能伙伴；第一步：文档编写的噩梦

目录

• 功能
• 安装
• 快速入门
• 使用
• 配置
• 架构
• 许可证

功能

• 多智能体分析：专门用于代码结构、数据流、依赖关系、请求流程和 API 分析的 AI 智能体
• 自动化文档生成：生成包含可配置章节的全面 README 文件
• AI 助手配置：自动为 AI 编码助手生成 CLAUDE.md、AGENTS.md 和 .cursor/rules/ 文件
• GitLab 集成：对 GitLab 项目进行自动化分析，并创建合并请求
• 并发处理：并行执行分析智能体以提升性能
• 灵活配置：基于 YAML 的配置，并支持环境变量覆盖
• 多 LLM 支持：兼容任何 OpenAI 兼容的 API（OpenAI、OpenRouter、本地模型等）
• 可观测性：内置监控功能，支持 OpenTelemetry 跟踪和 Langfuse 集成

安装

前提条件

• Python 3.13
• Git
• 对兼容 OpenAI 的 LLM 提供商的 API 访问权限

1. 克隆仓库：

git clone https://github.com/divar-ir/ai-doc-gen.git
cd ai-doc-gen

2. 推荐使用 uv 进行安装：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

3. 或者使用 pip 安装：

pip install -e .

快速入门

1. 设置环境和配置：

# 复制并编辑环境变量
cp .env.sample .env

# 复制并编辑配置文件
mkdir -p .ai
cp config_example.yaml .ai/config.yaml

2. 运行分析并生成文档：

# 分析您的代码仓库
uv run src/main.py analyze --repo-path .

# 生成 README 文档
uv run src/main.py generate readme --repo-path .

# 生成 AI 助手配置文件（CLAUDE.md、AGENTS.md、.cursor/rules/）
uv run src/main.py generate ai-rules --repo-path .

生成的文档将保存在 .ai/docs/ 目录中，AI 配置文件则会放置在您的代码仓库根目录下。

使用

可用命令

# 分析代码库
uv run src/main.py analyze --repo-path <path>

# 生成 README 文档
uv run src/main.py generate readme --repo-path <path>

# 生成 AI 助手配置文件
uv run src/main.py generate ai-rules --repo-path <path>

# 运行定时任务（GitLab 集成）
uv run src/main.py cronjob analyze

高级选项

分析选项：

# 带特定排除项进行分析
uv run src/main.py analyze --repo-path . --exclude-code-structure --exclude-data-flow

# 使用自定义配置文件
uv run src/main.py analyze --repo-path . --config /path/to/config.yaml

README 生成选项：

# 带特定章节排除项生成
uv run src/main.py generate readme --repo-path . --exclude-architecture --exclude-c4-model

# 使用现有 README 作为上下文
uv run src/main.py generate readme --repo-path . --use-existing-readme

AI 规则生成选项：

# 跳过覆盖现有文件
uv run src/main.py generate ai-rules --repo-path . \
    --skip-existing-claude-md \
    --skip-existing-agents-md \
    --skip-existing-cursor-rules

# 自定义详细程度和行数限制
uv run src/main.py generate ai-rules --repo-path . \
    --detail-level comprehensive \
    --max-claude-lines 600 \
    --max-agents-lines 150

配置

该工具会自动在您的代码仓库中的 .ai/config.yaml 或 .ai/config.yml 中查找配置。

配置选项

• 排除特定分析：跳过代码结构、数据流、依赖关系、请求流程或 API 分析
• 自定义 README 章节：控制生成文档中出现哪些章节
• 配置定时任务设置：设置工作路径和提交时间过滤条件

您可以通过 CLI 标志快速覆盖配置。所有可用选项请参阅 config_example.yaml，环境变量请参考 .env.sample。

架构

系统采用 多智能体架构，配备专门的 AI 智能体用于不同类型的代码分析和文档生成：

• CLI 层：入口点，负责命令解析和子命令路由
• 处理器层：特定于命令的业务逻辑（分析、生成、定时任务）
• 智能体层：基于 AI 的分析和文档生成
  • 分析智能体：结构、数据流、依赖关系、请求流程、API 分析
  • 文档智能体：README 生成
  • AI 规则生成器：CLAUDE.md、AGENTS.md 和 Cursor 规则生成
• 工具层：文件系统操作和实用工具

技术栈

• Python 3.13 结合 pydantic-ai 用于 AI 智能体编排
• 兼容 OpenAI 的 API 用于访问 LLM（OpenAI、OpenRouter 等）
• GitPython 和 python-gitlab 用于代码仓库操作
• OpenTelemetry 和 Langfuse 用于可观测性
• YAML + Pydantic 用于配置管理

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

致谢

• 基于 pydantic-ai 构建，用于 AI 智能体编排
• 通过兼容 OpenAI 的 API 支持多种 LLM 提供商（包括 OpenRouter）
• 使用 Langfuse 实现 LLM 可观测性

ai-doc-gen 快速上手指南

ai-doc-gen 是一款基于多智能体（Multi-Agent）架构的 AI 代码文档生成工具。它能自动分析代码仓库结构、数据流和依赖关系，并生成高质量的 README 文档及 AI 编程助手配置文件（如 CLAUDE.md, AGENTS.md）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux / macOS / Windows (WSL)
• Python 版本：Python 3.13 (必须)
• 其他依赖：
  • Git
  • 有效的 LLM API Key（支持 OpenAI、OpenRouter 或本地兼容模型）

提示：国内开发者若访问 GitHub 或 PyPI 较慢，建议配置国内镜像源或使用代理网络。

安装步骤

推荐使用 uv 进行安装，以获得更快的依赖解析速度和更好的环境管理体验。

1. 克隆项目

git clone https://github.com/divar-ir/ai-doc-gen.git
cd ai-doc-gen

2. 安装依赖

方式一：使用 uv（推荐）

# 安装 uv 工具
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步并安装项目依赖
uv sync

方式二：使用 pip

pip install -e .

基本使用

1. 初始化配置

在项目根目录下创建环境变量文件和配置文件：

# 复制环境变量模板并编辑（填入你的 LLM API Key）
cp .env.sample .env

# 创建配置目录并复制配置模板
mkdir -p .ai
cp config_example.yaml .ai/config.yaml

注意：请务必编辑 .env 文件，设置正确的 LLM_API_KEY 和 LLM_BASE_URL（如果使用非 OpenAI 官方接口）。

2. 运行分析

对当前仓库进行代码结构和逻辑分析：

uv run src/main.py analyze --repo-path .

3. 生成文档

根据分析结果生成 README 文档：

uv run src/main.py generate readme --repo-path .

4. 生成 AI 助手规则（可选）

为 Cursor、Claude Code 等 AI 编程工具生成上下文规则文件：

uv run src/main.py generate ai-rules --repo-path .

执行完成后，生成的文档将保存在 .ai/docs/ 目录中，AI 规则文件将直接生成在项目根目录。