docs/
├── README.md
├── overview/
├── packages/
│   ├── web-app/
│   ├── admin-panel/
│   └── shared-components/
├── tooling/
└── contributing/

├── 安装指南
├── 快速示例
├── API 参考
├── 高级用法
└── 贡献指南

项目文档生成器

智能分析任意代码库，生成定制化文档系统

---

核心理念

不预设固定结构 —— 每个项目都有其独特性，文档结构应该适配项目，而非让项目适配模板。

智能探索优先 —— 先深度理解项目，再决定文档结构。

按需网络检索 —— 遇到不熟悉的框架或需要确认最佳实践时，主动搜索学习。

---

文档生成流程

Phase 1: 项目探索 (智能分析)

目标: 深度理解项目架构、技术栈、模块组织

1.1 扫描项目根目录

识别配置文件:
├── package.json → Node.js/前端
├── pom.xml / build.gradle → Java
├── requirements.txt / pyproject.toml → Python
├── Cargo.toml → Rust
├── go.mod → Go
├── Gemfile → Ruby
└── composer.json → PHP

判断项目类型:
├── 纯前端 (Vue/React/Angular)
├── 纯后端 (API服务)
├── 全栈 (前后端分离)
├── 库/SDK
├── CLI工具
├── 微服务集群
└── Monorepo

1.2 探索目录结构

找出源码目录:
├── src/, lib/, app/, core/, internal/, packages/, modules/

理解模块划分:
├── 按功能? (user/, order/, payment/)
├── 按层? (controller/, service/, repository/)
├── 按领域? (DDD风格)
└── 混合? (需仔细分析)

识别特殊目录:
├── config/, settings/ → 配置
├── scripts/, tools/ → 工具脚本
├── docs/ → 现有文档
├── tests/, spec/, tests/ → 测试
└── migrations/, db/ → 数据库迁移

1.3 技术栈识别

解析依赖文件:
├── 提取框架和版本 (Spring Boot 3.4, Vue 3.5...)
├── 识别数据库
├── 识别中间件
└── 记录工具库

生成技术清单:
| 类别 | 技术 | 版本 | 用途 |

1.4 智能网络检索 (按需)

何时需要检索:

✅ 遇到不熟悉的框架
→ 搜索: [框架名] official documentation
→ 搜索: [框架名] architecture overview

✅ 不确定目录结构最佳实践
→ 搜索: [框架名] project structure best practices
→ 搜索: [语言] clean architecture

✅ 需要理解设计理念
→ 搜索: [框架名] design principles
→ 搜索: [技术] patterns and practices

检索原则:

• - 优先官方文档
• 参考权威博客
• 避免过时信息

1.5 提取核心信息

• - 入口文件
• 核心模块及其职责
• 数据流向 (请求 → 处理 → 响应)
• 模块间依赖关系
• 关键配置项
• 认证/授权机制 (如有)

---

Phase 2: 文档结构设计 (定制化)

目标: 根据项目特点设计最适合的文档结构

2.1 设计原则

1. 1. 匹配项目复杂度

├── 小型项目 → 精简结构 (README + 核心文档) ├── 中型项目 → 标准结构 (快速开始 + 架构 + 模块) └── 大型项目 → 完整结构 (多层级 + 领域划分)

1. 2. 适配项目类型

├── 纯前端 → 组件 + 页面 + 状态 + 路由 ├── 纯后端 → 配置 + 服务 + 数据 + API ├── 全栈 → 前端 + 后端 + 交互流程 ├── 微服务 → 各服务 + 通信 + 部署 └── 库/SDK → 安装 + API + 示例 + 贡献

1. 3. 反映实际模块

├── 按项目实际模块命名 ├── 文档层级与代码层级对应 └── 不强行套用模板目录名

1. 4. 考虑读者需求

├── 新手 → 快速开始必须清晰 ├── 开发者 → 模块详解和API必须完整 └── 架构师 → 架构决策和设计必须深入

2.2 灵活结构示例

小型 CLI 工具:

docs/
├── README.md (包含快速开始)
├── installation.md
├── usage.md
└── api-reference.md

中型 Spring Boot 项目:

docs/
├── README.md
├── getting-started/
├── architecture/
├── modules/ # 按实际模块命名: user/, order/, payment/
├── api/
└── configuration/

大型微服务系统:

docs/
├── README.md
├── overview/
├── services/ # 各微服务独立文档
│ ├── user-service/
│ ├── order-service/
│ └── ...
├── infrastructure/
├── decisions/ # ADR 架构决策记录
└── runbooks/

Monorepo 项目:

docs/
├── README.md
├── overview/
├── packages/
│ ├── web-app/
│ ├── admin-panel/
│ └── shared-components/
├── tooling/
└── contributing/

---

Phase 3: 文档内容生成

目标: 为每个文档填充高质量内容

3.1 必备文档类型

文档类型	适用场景	必含内容
README/概览	所有项目	一句话定位、核心功能、快速演示
快速开始

所有项目 | 环境要求、安装步骤、运行验证 | | 架构设计 | 中大型项目 | 架构图、分层说明、核心决策 | | 模块文档 | 多模块项目 | 职责、核心类/函数、使用示例 | | API文档 | 后端/库项目 | 端点、参数、响应、示例 | | 流程文档 | 业务系统 | 流程图、阶段说明、异常处理 | | 技术选型 | 复杂项目 | 对比表格、选择理由、使用经验 |

3.2 内容质量标准

项目概览: 新人 5 分钟理解项目价值
快速开始: 30 分钟内能运行起来
架构设计: 架构师 10 分钟把握全局
模块文档: 开发者能直接上手开发
API文档: 可直接用于接口对接
流程文档: 理解业务逻辑全貌

---

Phase 4: 图表可视化

目标: 用图表增强文档可读性

场景	推荐图表	示例
系统架构	组件图/分层图	PlantUML package
交互流程

序列图 | PlantUML participant |
| 数据模型 | ER图 | PlantUML entity |
| 状态变化 | 状态图 | PlantUML stateDiagram |
| 模块关系 | 依赖图 | PlantUML/Mermaid |
| 目录结构 | 树形图 | 纯文本 |

PlantUML 复杂度控制 ⭐ 重要：

每个图表限制：
├── 总元素数 ≤ 25（推荐 ≤ 20）
├── 代码行数 ≤ 60（推荐 ≤ 50）
└── 节点数量 ≤ 20（推荐 ≤ 15）

复杂图表拆分策略：
├── 按层级拆分：概览图 + 各层详图
├── 按阶段拆分：分阶段流程图
└── 按模块拆分：模块概览 + 模块详图

语法校验：

bash

使用校验脚本检查所有图表

python3 scripts/validate_plantuml.py ./docs --verbose

详细指南：参见 diagram-patterns.md

plantuml
@startuml
title [图表标题]
[定义参与者/组件]
[定义关系]
@enduml

---

执行检查清单

探索阶段

• - [ ] 识别项目类型和主要语言
• [ ] 扫描目录结构，理解模块划分方式
• [ ] 检测技术栈（框架、数据库、中间件）
• [ ] 对不熟悉的框架进行网络检索
• [ ] 识别入口文件和启动流程
• [ ] 理解模块间依赖和调用关系

设计阶段

• - [ ] 根据项目复杂度确定文档层级
• [ ] 根据项目类型调整文档重点
• [ ] 文档结构与实际代码结构对应
• [ ] 设计合理的阅读路径

生成阶段

• - [ ] 生成文档导航 README.md
• [ ] 为每个文档添加适当内容
• [ ] 添加可视化