项目理解skill-v1

codebase_architecture_analyzer_v1/reference/report-generation.md

@@ -0,0 +1,259 @@
+# Phase 5: 报告生成指南
+
+**执行时间**：约 30 秒
+
+**目标**：汇总所有分析结果，生成完整的架构分析报告
+
+---
+
+## 生成步骤
+
+### 步骤 1: 收集所有分析结果
+
+从前 4 个 Phase 收集以下信息：
+
+1. **Phase 1 - 快速扫描**
+   - 项目类型
+   - 主要编程语言
+   - 核心框架
+   - 子系统列表
+   - 代码规模
+
+2. **Phase 2 - 系统架构**
+   - 系统架构 Mermaid 图
+   - 子系统清单（名称、路径、技术栈、入口文件）
+   - 通信关系列表
+
+3. **Phase 3 - 核心流程**
+   - 工作流 Mermaid 图（stateDiagram-v2 / flowchart）
+   - 执行单元清单（Agent / 服务 / 函数）
+   - 关键决策点
+
+4. **Phase 4 - 数据流**
+   - 序列图 Mermaid
+   - 数据模型清单
+   - 数据转换链路
+
+### 步骤 2: 使用模板生成报告
+
+使用 `assets/report.md` 模板，将收集的信息填充到相应章节。
+
+### 步骤 3: 添加快速上手指南
+
+从项目文件中提取以下信息：
+
+1. **环境要求**
+   - 从 README.md 或 pyproject.toml 提取
+   - Python/Node.js 版本要求
+   - 系统依赖（Docker、Redis 等）
+
+2. **安装步骤**
+   - 依赖安装命令
+   - 环境变量配置
+   - 数据库初始化
+
+3. **启动命令**
+   - 开发环境启动命令
+   - 生产环境部署命令
+   - 测试运行命令
+
+4. **核心入口文件**
+   - 主入口文件路径
+   - 配置文件路径
+   - 关键模块路径
+
+### 步骤 4: 生成代码位置索引
+
+汇总所有关键文件的位置：
+
+```
+代码位置索引:
+├─ 入口文件
+│  ├─ 后端入口: backend/app/main.py:1
+│  └─ 前端入口: frontend/src/main.tsx:1
+├─ 核心模块
+│  ├─ Agent 编排: agents/graph.py:23
+│  ├─ 研究 Agent: agents/nodes.py:45
+│  └─ 写作 Agent: agents/nodes.py:78
+├─ API 端点
+│  ├─ 研究 API: backend/app/routes.py:42
+│  └─ WebSocket: backend/app/routes.py:58
+└─ 数据模型
+   ├─ ResearchTask: models/task.py:8
+   └─ Report: models/report.py:22
+```
+
+### 步骤 5: 保存报告
+
+将生成的报告保存到项目根目录：
+
+- **保存路径**: `PROJECT_ARCHITECTURE.md`
+
+---
+
+## 报告结构模板
+
+```markdown
+# [项目名] 架构分析报告
+
+> 生成时间: [YYYY-MM-DD HH:MM:SS]
+> 分析工具: Claude Code - Codebase Architecture Analyzer
+
+---
+
+## 一、项目概览
+
+**项目类型**: [自动推断]
+**主要语言**: [Python 3.11]
+**核心框架**: [FastAPI + LangGraph]
+**代码规模**: [156 个 Python 文件, 89 个 TypeScript 文件]
+
+**子系统**:
+- frontend/ (React + TypeScript)
+- backend/ (FastAPI + Python)
+- agents/ (LangGraph)
+
+---
+
+## 二、系统架构
+
+### 2.1 架构图
+
+```mermaid
+[Phase 2 生成的 Mermaid 图]
+```
+
+### 2.2 子系统详情
+
+[Phase 2 生成的子系统清单]
+
+### 2.3 通信机制
+
+[Phase 2 生成的通信关系列表]
+
+---
+
+## 三、核心业务流程
+
+### 3.1 流程图
+
+```mermaid
+[Phase 3 生成的 Mermaid 图]
+```
+
+### 3.2 执行单元清单
+
+[Phase 3 生成的 Agent/服务/函数清单]
+
+### 3.3 关键决策点
+
+[Phase 3 识别的条件分支和路由规则]
+
+---
+
+## 四、数据流分析
+
+### 4.1 序列图
+
+```mermaid
+[Phase 4 生成的 Mermaid 序列图]
+```
+
+### 4.2 数据模型清单
+
+[Phase 4 生成的数据模型列表]
+
+### 4.3 数据转换链路
+
+[Phase 4 追踪的数据流转路径]
+
+---
+
+## 五、快速上手指南
+
+### 5.1 环境要求
+
+- Python 3.11+
+- Node.js 18+
+- Docker (可选)
+
+### 5.2 安装步骤
+
+```bash
+# 1. 安装后端依赖
+pip install -r backend/requirements.txt
+
+# 2. 安装前端依赖
+cd frontend && npm install
+
+# 3. 配置环境变量
+cp .env.example .env
+```
+
+### 5.3 启动命令
+
+```bash
+# 启动后端
+cd backend && uvicorn app.main:app --reload
+
+# 启动前端
+cd frontend && npm start
+```
+
+### 5.4 核心入口文件
+
+- 后端入口: `backend/app/main.py`
+- 前端入口: `frontend/src/main.tsx`
+- Agent 编排: `agents/graph.py`
+
+---
+
+## 六、代码位置索引
+
+[Phase 2-4 汇总的所有关键文件位置]
+
+---
+
+## 附录：分析方法说明
+
+本报告由 Claude Code 的 `codebase-architecture-analyzer` Skill 自动生成。
+
+分析方法:
+- Phase 1: 快速扫描（识别技术栈）
+- Phase 2: 系统架构分析（Explore sub-agent）
+- Phase 3: 核心流程提取（智能模式识别）
+- Phase 4: 数据流追踪（类型追踪）
+- Phase 5: 报告生成（本文档）
+```
+
+---
+
+## 输出示例
+
+执行完成后，向用户显示：
+
+```
+✓ 分析完成！
+
+报告已保存: PROJECT_ARCHITECTURE.md
+
+核心发现:
+- 采用 LangGraph 编排 Multi-Agent 工作流
+- 支持条件路由和循环优化
+- 数据流: 查询 → 搜索 → 写作 → 审核 → 报告
+
+快速上手:
+1. 安装依赖: pip install -r requirements.txt
+2. 配置环境: cp .env.example .env
+3. 启动后端: uvicorn app.main:app --reload
+4. 启动前端: cd frontend && npm start
+```
+
+---
+
+## 注意事项
+
+1. **Mermaid 图表检查**：确保所有 Mermaid 代码块语法正确
+2. **代码位置准确性**：所有文件路径和行号必须准确
+3. **快速上手可用性**：安装步骤必须可执行，不能遗漏关键步骤
+4. **避免敏感信息**：不要在报告中包含 `.env` 文件内容或 API 密钥