Deep Document Builder
基于 NextJS 和 AI 实现的智能文档生成工具
功能特性
- 🔍 智能分析: 自动分析 Git 仓库结构，识别组件和 API
- 📚 文档生成: 基于代码分析生成详细的组件文档
- ⚡ 实时反馈: 实时显示分析进度和状态信息
- 🌐 Web 界面: 类似谷歌搜索的简洁界面
- 🔄 实时通信: WebSocket 实时推送分析状态
- 📊 详细进度: 右侧滑出面板展示分步骤分析过程
- 🏃♂️ 并行分析: 实时展示多个组件的并行分析状态
- ⏹️ 终止控制: 支持用户随时终止分析过程
启动方式
环境要求
- Node.js 20+
- pnpm
安装依赖
# 安装依赖
pnpm install配置环境变量
创建 .env.local 文件并配置以下环境变量：
# MCP 服务器配置（后端 API 地址）
# 客户端直接访问后端（因为 Next.js rewrites 不支持 SSE 流式响应）
NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:3000
# 服务器端配置
MCP_SERVER_URL=http://localhost:3000
# GitLab 访问令牌（可选）
# 获取方式: GitLab Settings -> Access Tokens -> Create Personal Access Token
# 需要的权限: api, read_repository, write_repository
GITLAB_ACCESS_TOKEN=your_gitlab_access_token_here也可以直接复制 .env.example 文件：
cp .env.example .env.local重要说明:
- 前端直接访问后端 API（不通过 Next.js rewrites），因为 Next.js rewrites 不支持 SSE 流式响应
- 后端已配置 CORS 允许前端访问
- 需要设置
NEXT_PUBLIC_MCP_SERVER_URL环境变量指向后端地址
注意: 文档生成功能已迁移到 MCP 服务器，请确保先启动 deep-document-builder-mcp-server 服务。详细的迁移说明请参考 MIGRATION_GUIDE.md启动项目
1. 启动 MCP 服务器
首先启动后端 MCP 服务器：
cd ../deep-document-builder-mcp-server
pnpm install
pnpm run build
pnpm run startMCP 服务器将在 http://localhost:3000 启动
2. 启动前端应用
# 启动 NextJS 开发服务器
pnpm dev前端应用将在 http://localhost:3001 启动
使用旧版本脚本
如果你想使用原来的命令行版本：
pnpm legacy项目结构
├── app/ # NextJS App Router
│ ├── fs-api/ # 本地文件系统 API 路由
│ │ └── docs/ # 文档读写接口
│ ├── docs/ # 文档浏览页面
│ ├── globals.css # 全局样式
│ ├── layout.tsx # 根布局
│ └── page.tsx # 主页面（分析入口）
├── components/ # React 组件
│ ├── SearchBox.tsx # 搜索输入框
│ ├── StatusDisplay.tsx # 状态显示组件
│ ├── ProgressPanel.tsx # 进度面板
│ └── AccessTokenModal.tsx # Token 输入模态框
├── lib/ # 工具库
│ ├── config.ts # 服务器端配置
│ └── status-stream.ts # 状态流工具
├── docs-store/ # 生成的文档存储目录
└── types/ # TypeScript 类型定义架构说明
API 路由
- 后端 API（MCP Server）直接访问:
- POST http://localhost:3000/api/analysis/project - 项目分析（SSE 流式响应） - POST http://localhost:3000/api/analysis/package - 包分析（SSE 流式响应） - POST http://localhost:3000/api/analysis/component - 组件分析（SSE 流式响应） - 前端直接调用后端 API，通过 CORS 处理跨域 - 为什么不用 Next.js rewrites？ Next.js rewrites 会缓冲整个响应，无法实时推送 SSE 流式数据
- 前端 API（Next.js）:
- GET /fs-api/docs/packages - 获取本地文档包列表 - GET /fs-api/docs/packages/[path] - 获取指定包的文档列表 - GET /fs-api/docs/content - 读取文档内容 - POST /fs-api/docs/save - 保存文档内容 - 这些接口仅用于访问本地文件系统，读写 docs-store 目录
SSE 流式响应说明
为什么前端直接访问后端而不使用 Next.js API Routes 代理？
- Next.js rewrites 不支持流式响应: rewrites 会等待整个响应完成后才转发，导致 SSE 无法实时推送
- Next.js API Routes 作为代理也有问题: 虽然可以手动转发流，但会增加一层不必要的复杂度
- 直接访问最简单: 后端配置 CORS 后，前端可以直接访问，减少中间层
后端 CORS 配置（src/main.ts）:
app.enableCors({
origin: ['http://localhost:3001', 'http://localhost:3000'],
methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
credentials: true,
allowedHeaders: 'Content-Type,Authorization,Accept',
});核心流程
graph TD
A[用户输入 Git 地址] --> B[右侧滑出进度面板]
B --> C[Step 1: 分析仓库类型]
C --> D[克隆仓库到临时目录]
D --> E[分析项目结构]
E --> F[Step 2: 查找入口文件]
F --> G[提取组件列表]
G --> H[Step 3: 并行分析组件]
H --> I[组件1分析中...]
H --> J[组件2分析中...]
H --> K[组件N分析中...]
I --> L[生成 Markdown 文档]
J --> L
K --> L
L --> M[清理临时文件]
M --> N[分析完成]
style A fill:#e1f5fe
style B fill:#fff3cd
style C fill:#d4edda
style F fill:#d4edda
style H fill:#d4edda
style N fill:#e8f5e8API 接口
POST /api/generate
生成文档的主要接口（代理到 MCP 服务器）
请求体:
{
"gitUrl": "https://github.com/user/repo.git"
}响应:
{
"success": true,
"sessionId": "uuid-generated-by-mcp-server",
"message": "文档生成任务已启动"
}GET /api/status?sessionId=xxx
Server-Sent Events (SSE) 实时状态推送接口，返回详细的分析进度信息。
响应格式:
{
"status": "success",
"data": [
{
"id": "task-id",
"title": "任务标题",
"description": "任务描述",
"status": "running",
"startTime": 1640995200000,
"endTime": null
}
]
}状态类型:
pending: 待执行running: 执行中completed: 已完成failed: 失败
支持的仓库格式
- GitHub:
https://github.com/user/repo.git - GitLab:
https://gitlab.com/user/repo.git - SSH:
git@github.com:user/repo.git - 其他 Git 仓库地址
注意事项
- 必须先启动
deep-document-builder-mcp-server服务 - 需要配置有效的 GitLab Access Token
- 确保 MCP 服务器地址配置正确
- 生成的文档会被提交到 GitLab 仓库的对应分支