ai-doc-gen

文档即代码：用多 Agent 重新定义代码文档生成

从"懒得写文档"到"文档自动化"的工程困境

每一个中型以上的代码仓库，都面临同一个痛点：文档和代码永远是脱节的。开发者写代码时不想写文档，代码交付后文档早已过时，维护团队疲于追赶。Divar（伊朗知名分类信息平台）团队同样被这个问题困扰。他们的工程团队每月维护数十个内部项目，每次接手新代码库，光是搞清楚「这个服务依赖哪些接口」「数据流向是怎样的」「为什么要这样设计」就要花掉好几天。

传统解决方案要么依赖人工编写规范（成本高、难坚持），要么用静态分析工具生成 API 文档（只覆盖表面，无法理解业务意图）。直到大语言模型展现出代码理解能力，Divar 团队工程师 Milad Noroozi 决定用 AI Agent 来解决这个问题——让多个专业化 Agent 协作，像一支「代码考古队」一样，自底向上理解整个代码库，然后输出结构化的文档。这就是 ai-doc-gen 的起源。

核心能力：五类 Agent 的协同分析

ai-doc-gen 的设计思路非常清晰：不是用一个通用 Agent 做所有事，而是为每种分析类型配置一个专业 Agent，通过 WorkerPool 实现并发执行。

这套设计的巧妙之处在于解耦：每个 Agent 都可以独立配置 LLM 模型、温度、超时时间、最大重试次数。例如结构分析可能只需要小模型快速出结果，而 API 分析需要更长的上下文和更低的温度来保证准确性。这种灵活的配置能力来自 Pydantic-AI 的模型无关 Agent 设计——每个 Agent 可以绑定不同的 OpenAI 兼容 API（OpenAI、OpenRouter、本地模型均可）。

技术架构：Pydantic-AI + asyncio 的工程级实现

从源码来看，ai-doc-gen 的架构可以分为三层：

Agent 层（src/agents/）：核心业务逻辑。AnalyzerAgent 使用 Pydantic-AI 的 Agent 类，通过 FunctionModel 注册工具函数。每个 Agent 持有自己的 PromptManager，加载 YAML 文件定义的提示词模板，支持「结构分析」「依赖分析」「请求流分析」等多种分析模式的选择性执行。

工具层（src/agents/tools/）：Agent 的感知窗口。目前实现了两类工具——ListFilesTool（递归列出目录下的文件，返回文件路径和大小）和 FileReadTool（按行读取文件内容，支持大文件截断）。这种工具注册机制使得 Agent 能够在分析过程中主动「探索」代码库，而不只是被动接收上下文。

调度层（src/handlers/ + src/main.py）：负责将 CLI 参数转换为 Agent 配置，并串联工作流。BaseHandler 提供统一的异步处理接口，AnalyzeHandler/ReadmeHandler/AIRulesHandler 分别对应三种命令入口。OpenTelemetry 在 handler 层面注入 span，追踪每个分析阶段的耗时和属性。

值得注意的是，nest_asyncio.apply() 的使用暗示了这款工具在某些执行环境（如 Jupyter Notebook、已运行事件循环的控制台）中的兼容性处理——Python 3.10+ 中 asyncio.run() 无法嵌套调用，但 Divar 团队通过 nest-asyncio 绕过了这个限制。

三大输出模式：从技术文档到 AI 助手机器人规则

ai-doc-gen 不仅仅生成 README，而是覆盖了文档生成的完整生命周期：

模式一：代码分析文档（ai-doc-gen analyze）——将代码库拆解为结构、数据流、依赖、请求流、API 五个维度，输出到 .ai/docs/ 目录。这些文档是后续生成高质量 README 的原材料。

模式二：README 生成器（ai-doc-gen generate readme）——调用 DocumenterAgent，基于分析结果和 Jinja2 模板生成完整的 README.md。支持排除特定章节（架构、C4 模型、API 文档等），并可选择「使用现有 README 作为上下文」或「从零生成」。

模式三：AI 助手机器人规则（ai-doc-gen generate ai-rules）——这是最有创新性的功能。Agent 不仅生成给人看的文档，还能生成给 AI 看的规则文件：CLAUDE.md（Claude 的项目上下文）、AGENTS.md（多 Agent 协作规范）、.cursor/rules/（Cursor IDE 的 .mdc 规则文件）。这意味着团队配置好 AI 编程助手后，新成员甚至 AI Agent 都能通过这些文件快速理解项目规范，无需反复沟通代码风格和架构约定。

部署与扩展：从本地单仓库到 GitLab CI/CD

部署方面，项目提供两条路径：本地安装（uv sync 或 pip install -e .）和容器化部署（Dockerfile + Helm Chart）。Python 3.13 是硬性要求，配合 uv 包管理器可以实现快速的环境重建。

对于大型团队，项目还设计了 GitLab 集成和 Cronjob 模式：JobAnalyzeHandler 可以定时扫描长期未更新的代码库，自动分析并创建 GitLab Merge Request，将文档更新提交给维护者审阅。这解决了「文档过期」的核心问题——不是靠人工定期更新，而是靠自动化监控和 PR 驱动。

Langfuse 集成（可选）提供了 LLM 调用的可观测性，团队可以追踪每个分析阶段的 token 消耗和响应质量，便于持续优化提示词。

局限与风险

这个项目并非没有局限。首先，对 API Key 的强依赖是最大的风险——没有 OpenAI 兼容 API Key 就无法工作，且不同模型生成的文档质量可能差异显著。其次，Python 3.13 的硬性要求在某些受限环境中（如企业内网旧版 Python）可能造成部署障碍。再者，分析质量高度依赖提示词工程——虽然项目提供了 YAML 模板化的提示词管理，但用户自定义提示词的能力有限，当代码库结构超出预设模式时，分析结果可能不尽如人意。最后，作为纯 CLI 工具，缺少 Web 界面意味着无法直观预览生成效果，对于非技术用户有一定门槛。

行业意义

ai-doc-gen 代表了一个新兴趋势：文档即代码（Docs-as-Code）的 AI 增强版。传统 Docs-as-Code 要求开发者将文档纳入代码审查流程，执行成本高；ai-doc-gen 通过 AI 将这个成本降到了接近零。更重要的是，它将 AI 编程助手的上下文工程（Context Engineering）前置化了——CLAUDE.md、.cursor/rules/ 这些文件不是给人类看的，而是给 AI Agent 看的，这开启了「让 AI 理解项目」的新范式。随着 Claude Code、Cursor 等 AI 编程工具的普及，这类「给 AI 写说明书」的工具价值会持续增长。

项目信息：Stars 729 · Fork 76 · MIT License · 76 个文件 · 最近更新 2025-11-24