AI 文档生成器

这是一个基于 AI 的代码文档生成器，能够自动分析代码仓库，并利用先进的语言模型创建全面的文档。该系统采用多 Agent 架构，执行专业的代码分析并生成结构化的文档。

📝 博客文章

阅读本项目背后的完整故事：

• 🇺🇸 英文：不过期的文档：多 Agent AI 如何重写我们的工作流
• 🇮🇷 波斯语：从代码助手到智能同事；第一步：文档噩梦

目录

• 特性
• 安装
• 快速开始
• 使用方法
• 配置
• 架构
• 许可证

特性

• 多 Agent 分析：针对代码结构、数据流、依赖关系、请求流和 API 分析的专业 AI Agent。
• 自动化文档：生成包含可配置章节的综合 README 文件。
• AI 助手配置：自动为 AI 编程助手生成 CLAUDE.md、AGENTS.md 和 .cursor/rules/ 文件。
• GitLab 集成：针对 GitLab 项目的自动分析，并支持创建合并请求 (Merge Request)。
• 并发处理：并行执行分析 Agent 以提升性能。
• 灵活配置：基于 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 

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

# 生成 AI 助手配置文件
uv run src/main.py generate ai-rules --repo-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 了解环境变量设置。