project-docs-generator（项目文档生成器）

项目文档生成器

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

核心理念

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

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

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

文档生成流程

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. 匹配项目复杂度
   ├── 小型项目 → 精简结构 (README + 核心文档)
   ├── 中型项目 → 标准结构 (快速开始 + 架构 + 模块)
   └── 大型项目 → 完整结构 (多层级 + 领域划分)

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

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

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 必备文档类型

3.2 内容质量标准

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

Phase 4: 图表可视化

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

PlantUML 复杂度控制 ⭐ 重要：

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

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

语法校验：

# 使用校验脚本检查所有图表
python3 scripts/validate_plantuml.py ./docs --verbose

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

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

执行检查清单

探索阶段

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

设计阶段

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

生成阶段

• [ ] 生成文档导航 README.md
• [ ] 为每个文档添加适当内容
• [ ] 添加可视化图表
• [ ] 确保代码示例准确
• [ ] 检查文档间交叉引用

质量验证

• [ ] PlantUML 语法正确（使用 validate_plantuml.py）
• [ ] 每个图表元素数 ≤ 25
• [ ] 复杂图表已拆分为多个小图
• [ ] 代码示例可运行
• [ ] 术语使用一致
• [ ] 链接路径有效

常见项目类型处理策略

纯前端项目 (Vue/React/Angular)

探索重点:

- 组件组织方式 (按功能/按页面/原子设计)
- 状态管理方案 (Pinia/Vuex/Redux/Zustand)
- 路由结构
- API 调用层封装
- 样式方案 (CSS-in-JS/Tailwind/SCSS)

建议文档重点:

├── 组件体系
├── 页面路由
├── 状态管理
├── API 集成
└── 构建部署

纯后端项目 (Spring Boot/Django/Express)

探索重点:

- 分层架构 (Controller-Service-Repository/MVC)
- 数据模型和表结构
- API 端点设计
- 中间件集成 (缓存/消息队列/搜索)
- 认证授权机制

建议文档重点:

├── 架构分层
├── 数据模型
├── API 参考
├── 业务服务
└── 配置说明

全栈项目

探索重点:

- 前后端通信方式 (REST/GraphQL/WebSocket)
- 认证授权流程
- 数据流和状态同步
- 部署架构

建议文档重点:

├── 整体架构
├── 前端模块
├── 后端模块
├── 交互流程 (重点!)
└── 部署方案

微服务架构

探索重点:

- 服务划分依据
- 服务间通信 (HTTP/gRPC/消息队列)
- 数据一致性方案
- 服务发现和注册
- 监控和日志

建议文档重点:

├── 服务地图
├── 各服务独立文档
├── 通信机制
├── 基础设施
└── ADR 决策记录

Monorepo 项目

探索重点:

- 包/项目之间的关系
- 共享代码和工具
- 构建和发布流程
- 依赖管理策略

建议文档重点:

├── 整体结构
├── 各包独立文档
├── 共享工具
└── 开发工作流

库/SDK 项目

探索重点:

- 核心功能和设计理念
- API 设计模式
- 示例代码
- 版本兼容性

建议文档重点:

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

网络检索指南

何时需要检索:

1. 不熟悉的框架
   搜索: "[框架名] official documentation"
   搜索: "[框架名] architecture best practices"
   目的: 理解核心概念和推荐用法

2. 技术选型原因
   搜索: "[技术A] vs [技术B] comparison"
   搜索: "[技术] pros and cons"
   目的: 补充选型背景

3. 目录结构确认
   搜索: "[框架名] project structure"
   搜索: "[语言] clean architecture folder structure"
   目的: 确认文档结构是否合理

4. 设计模式参考
   搜索: "[领域] design patterns"
   搜索: "[技术] common patterns"
   目的: 确保文档符合行业惯例

相关参考

• 技术栈检测方法
• PlantUML 图表模式 - 包含复杂度控制和拆分策略
• validate_plantuml.py - PlantUML 语法校验工具