Refactor project analysis phases: remove diagram generation phase, enhance report generation with detailed structure and quality checks, and introduce consolidation agent for cross-module analysis. Update CLI commands to support final output options and improve history management with copy functionality.

2026-02-13 02:41:50 +08:00 · 2025-12-26 12:13:27 +08:00
parent 89f6ac6804
commit 0c0301d811
15 changed files with 2037 additions and 639 deletions
--- a/.claude/skills/project-analyze/SKILL.md
+++ b/.claude/skills/project-analyze/SKILL.md
@@ -8,82 +8,147 @@ allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write

 Generate comprehensive project analysis reports through multi-phase iterative workflow.

+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Context-Optimized Architecture                                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Phase 1: Requirements      → analysis-config.json              │
+│           ↓                                                      │
+│  Phase 2: Exploration       → 初步探索，确定范围                  │
+│           ↓                                                      │
+│  Phase 3: Parallel Agents   → sections/section-*.md (直接写MD)   │
+│               ↓ 返回简要JSON                                     │
+│  Phase 3.5: Consolidation   → consolidation-summary.md          │
+│           Agent                 ↓ 返回质量评分+问题列表          │
+│           ↓                                                      │
+│  Phase 4: Assembly          → 合并MD + 质量附录                  │
+│           ↓                                                      │
+│  Phase 5: Refinement        → 最终报告                           │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Key Design Principles
+
+1. **Agent 直接输出 MD**: 避免 JSON → MD 转换的上下文开销
+2. **简要返回**: Agent 只返回路径+摘要，不返回完整内容
+3. **汇总 Agent**: 独立 Agent 负责跨章节问题检测和质量评分
+4. **引用合并**: Phase 4 读取文件合并，不在上下文中传递
+
 ## Execution Flow

 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  Phase 1: Requirements Discovery                                │
 │  → Read: phases/01-requirements-discovery.md                    │
-│  → Collect: report type, depth level, scope                     │
+│  → Collect: report type, depth level, scope, focus areas        │
+│  → Output: analysis-config.json                                 │
 ├─────────────────────────────────────────────────────────────────┤
 │  Phase 2: Project Exploration                                   │
 │  → Read: phases/02-project-exploration.md                       │
-│  → Launch: parallel cli-explore-agents                          │
+│  → Launch: parallel exploration agents                          │
+│  → Output: exploration context for Phase 3                      │
 ├─────────────────────────────────────────────────────────────────┤
-│  Phase 3: Deep Analysis                                         │
+│  Phase 3: Deep Analysis (Parallel Agents)                       │
 │  → Read: phases/03-deep-analysis.md                             │
-│  → Execute: Gemini CLI with exploration context                 │
+│  → Reference: specs/quality-standards.md                        │
+│  → Each Agent: 分析代码 → 直接写 sections/section-*.md          │
+│  → Return: {"status", "output_file", "summary", "cross_notes"}  │
 ├─────────────────────────────────────────────────────────────────┤
-│  Phase 3.5: Diagram Generation                                  │
-│  → Read: phases/03.5-diagram-generation.md                      │
-│  → Reference: ../_shared/mermaid-utils.md                       │
-│  → Generate: Mermaid diagrams based on report type              │
+│  Phase 3.5: Consolidation (New!)                                │
+│  → Read: phases/03.5-consolidation.md                           │
+│  → Input: Agent 返回的简要信息 + cross_module_notes             │
+│  → Analyze: 一致性/完整性/关联性/质量检查                        │
+│  → Output: consolidation-summary.md                             │
+│  → Return: {"quality_score", "issues", "stats"}                 │
 ├─────────────────────────────────────────────────────────────────┤
 │  Phase 4: Report Generation                                     │
 │  → Read: phases/04-report-generation.md                         │
-│  → Reference: specs/quality-standards.md (Report Requirements)  │
-│  → Assemble: Markdown report with embedded diagrams             │
+│  → Check: 如有 errors，提示用户处理                              │
+│  → Merge: Executive Summary + sections/*.md + 质量附录          │
+│  → Output: {TYPE}-REPORT.md                                     │
 ├─────────────────────────────────────────────────────────────────┤
 │  Phase 5: Iterative Refinement                                  │
 │  → Read: phases/05-iterative-refinement.md                      │
-│  → Reference: specs/quality-standards.md (Quality Gates)        │
-│  → Validate: run quality checks before each iteration           │
-│  → Loop: discovery-driven questions until all gates pass        │
+│  → Reference: specs/quality-standards.md                        │
+│  → Loop: 发现问题 → 提问 → 修复 → 重新检查                       │
 └─────────────────────────────────────────────────────────────────┘
 ```

 ## Report Types

-| Type | Output | Focus |
-|------|--------|-------|
-| `architecture` | ARCHITECTURE-REPORT.md | System structure, modules, dependencies |
-| `design` | DESIGN-REPORT.md | Patterns, classes, interfaces |
-| `methods` | METHODS-REPORT.md | Algorithms, critical paths, APIs |
-| `comprehensive` | COMPREHENSIVE-REPORT.md | All above combined |
+| Type | Output | Agents | Focus |
+|------|--------|--------|-------|
+| `architecture` | ARCHITECTURE-REPORT.md | 5 | System structure, modules, dependencies |
+| `design` | DESIGN-REPORT.md | 4 | Patterns, classes, interfaces |
+| `methods` | METHODS-REPORT.md | 4 | Algorithms, critical paths, APIs |
+| `comprehensive` | COMPREHENSIVE-REPORT.md | All | All above combined |
+
+## Agent Configuration by Report Type
+
+### Architecture Report
+| Agent | Output File | Section |
+|-------|-------------|---------|
+| overview | section-overview.md | System Overview |
+| layers | section-layers.md | Layer Analysis |
+| dependencies | section-dependencies.md | Module Dependencies |
+| dataflow | section-dataflow.md | Data Flow |
+| entrypoints | section-entrypoints.md | Entry Points |
+
+### Design Report
+| Agent | Output File | Section |
+|-------|-------------|---------|
+| patterns | section-patterns.md | Design Patterns |
+| classes | section-classes.md | Class Relationships |
+| interfaces | section-interfaces.md | Interface Contracts |
+| state | section-state.md | State Management |
+
+### Methods Report
+| Agent | Output File | Section |
+|-------|-------------|---------|
+| algorithms | section-algorithms.md | Core Algorithms |
+| paths | section-paths.md | Critical Code Paths |
+| apis | section-apis.md | Public API Reference |
+| logic | section-logic.md | Complex Logic |

 ## Directory Setup

 ```bash
 timestamp=$(date +%Y%m%d-%H%M%S)
 dir=".workflow/.scratchpad/analyze-$timestamp"
-mkdir -p "$dir/diagrams" "$dir/iterations"
+mkdir -p "$dir/sections" "$dir/iterations"
 echo "$dir"
 ```

+## Output Structure
+
+```
+.workflow/.scratchpad/analyze-{timestamp}/
+├── analysis-config.json          # Phase 1
+├── sections/                     # Phase 3 (Agent 直接写入)
+│   ├── section-overview.md
+│   ├── section-layers.md
+│   ├── section-dependencies.md
+│   └── ...
+├── consolidation-summary.md      # Phase 3.5
+├── {TYPE}-REPORT.md              # Final Output
+└── iterations/                   # Phase 5
+    ├── v1.md
+    └── v2.md
+```
+
 ## Reference Documents

 | Document | Purpose |
 |----------|---------|
 | [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | User interaction, config collection |
-| [phases/02-project-exploration.md](phases/02-project-exploration.md) | Parallel agent exploration |
-| [phases/03-deep-analysis.md](phases/03-deep-analysis.md) | Gemini CLI analysis |
-| [phases/03.5-diagram-generation.md](phases/03.5-diagram-generation.md) | Mermaid diagram generation |
+| [phases/02-project-exploration.md](phases/02-project-exploration.md) | Initial exploration |
+| [phases/03-deep-analysis.md](phases/03-deep-analysis.md) | Parallel agent analysis |
+| [phases/03.5-consolidation.md](phases/03.5-consolidation.md) | Cross-section consolidation |
 | [phases/04-report-generation.md](phases/04-report-generation.md) | Report assembly |
-| [phases/05-iterative-refinement.md](phases/05-iterative-refinement.md) | Discovery-driven refinement |
-| [specs/quality-standards.md](specs/quality-standards.md) | Quality gates, error handling |
+| [phases/05-iterative-refinement.md](phases/05-iterative-refinement.md) | Quality refinement |
+| [specs/quality-standards.md](specs/quality-standards.md) | Quality gates, standards |
 | [../_shared/mermaid-utils.md](../_shared/mermaid-utils.md) | Shared Mermaid utilities |
-
-## Output Structure
-
-```
-.workflow/.scratchpad/analyze-{timestamp}/
-├── analysis-config.json
-├── exploration-*.json
-├── deep-analysis.json
-├── diagrams/
-│   ├── manifest.json
-│   ├── validation.json
-│   └── *.mmd
-├── {TYPE}-REPORT.md
-└── iterations/
-```
--- a/.claude/skills/project-analyze/phases/03-deep-analysis.md
+++ b/.claude/skills/project-analyze/phases/03-deep-analysis.md
@@ -1,58 +1,328 @@
 # Phase 3: Deep Analysis

-Execute deep analysis using Gemini CLI with exploration context.
+并行 Agent 直接写入 MD 章节文件，返回简要信息。

-## Execution
+> **规范参考**: [../specs/quality-standards.md](../specs/quality-standards.md)

-### Step 1: Prepare CLI Prompt
+## Agent 配置

-```bash
-ccw cli -p "
-PURPOSE: Generate ${type} analysis report for project
-TASK: 
-  • Analyze project structure and patterns from ${type} perspective
-  • Focus on: ${focus_areas}
-  • Depth level: ${depth}
-  • Key files: ${key_files}
-MODE: analysis
-CONTEXT: @**/* | Exploration results
-EXPECTED: 
-  - Structured analysis
-  - Code references (file:line format)
-  - Mermaid diagram data
-  - Actionable insights
-RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md)
-" --tool gemini --mode analysis
+根据报告类型，使用不同的 Agent 配置：
+
+### Architecture Report Agents
+
+| Agent | 输出文件 | 章节 |
+|-------|----------|------|
+| overview | sections/section-overview.md | System Overview |
+| layers | sections/section-layers.md | Layer Analysis |
+| dependencies | sections/section-dependencies.md | Module Dependencies |
+| dataflow | sections/section-dataflow.md | Data Flow |
+| entrypoints | sections/section-entrypoints.md | Entry Points & Critical Paths |
+
+### Design Report Agents
+
+| Agent | 输出文件 | 章节 |
+|-------|----------|------|
+| patterns | sections/section-patterns.md | Design Patterns Used |
+| classes | sections/section-classes.md | Class Relationships |
+| interfaces | sections/section-interfaces.md | Interface Contracts |
+| state | sections/section-state.md | State Management |
+
+### Methods Report Agents
+
+| Agent | 输出文件 | 章节 |
+|-------|----------|------|
+| algorithms | sections/section-algorithms.md | Core Algorithms |
+| paths | sections/section-paths.md | Critical Code Paths |
+| apis | sections/section-apis.md | Public API Reference |
+| logic | sections/section-logic.md | Complex Logic Breakdown |
+
+---
+
+## 通用 Agent 返回格式
+
+```typescript
+interface AgentReturn {
+  status: "completed" | "partial" | "failed";
+  output_file: string;
+  summary: string;               // 50字以内
+  cross_module_notes: string[];  // 跨模块发现
+  stats: {
+    diagrams: number;
+    code_refs: number;
+  };
+}
 ```

-### Step 2: Parse Analysis Results
+---

-Extract structured data from CLI response:
+## Agent 提示词模板
+
+### Overview Agent (Architecture)

 ```javascript
-const deepAnalysis = {
-  findings: [],           // Analyzed findings with confidence scores
-  patterns: [],           // Identified patterns with consistency scores
-  dependencies: [],       // Dependency relationships
-  recommendations: [],    // Prioritized recommendations
-  sections: [],           // Report section data
-  diagram_data: {}        // Data for diagram generation
-};
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+[ROLE] 系统架构师，专注于系统全貌和核心组件。
+
+[TASK]
+分析 ${config.scope}，生成 System Overview 章节。
+输出: ${outDir}/sections/section-overview.md
+
+[QUALITY_SPEC]
+- 内容基于代码分析，无臆测
+- 代码引用格式: \`file:line\`
+- 每个子章节 ≥100字
+- 包含至少1个 Mermaid 图表
+
+[TEMPLATE]
+## System Overview
+
+### Project Summary
+{项目概述，技术栈，核心功能}
+
+### Architecture Diagram
+\`\`\`mermaid
+graph TD
+    subgraph Core["核心层"]
+        A[组件A]
+    end
+\`\`\`
+
+### Key Components
+| 组件 | 职责 | 文件 |
+|------|------|------|
+
+### Technology Stack
+| 技术 | 用途 | 版本 |
+|------|------|------|
+
+[FOCUS]
+1. 项目定位和核心功能
+2. 技术栈和依赖
+3. 核心组件及职责
+4. 整体架构模式
+
+[RETURN JSON]
+{"status":"completed","output_file":"section-overview.md","summary":"<50字>","cross_module_notes":[],"stats":{"diagrams":1,"code_refs":5}}
+`
+})
 ```

-### Step 3: Validate Analysis Quality
-
-Check analysis completeness:
+### Layers Agent (Architecture)

 ```javascript
-const qualityChecks = {
-  has_executive_summary: Boolean,
-  focus_areas_covered: config.focus_areas.every(area => analysis.covers(area)),
-  code_references_valid: analysis.references.every(ref => fileExists(ref)),
-  insights_actionable: analysis.insights.filter(i => i.actionable).length > 0
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+[ROLE] 架构分析师，专注于分层结构。
+
+[TASK]
+分析 ${config.scope}，生成 Layer Analysis 章节。
+输出: ${outDir}/sections/section-layers.md
+
+[QUALITY_SPEC]
+- 内容基于代码分析，无臆测
+- 代码引用格式: \`file:line\`
+- 每个子章节 ≥100字
+
+[TEMPLATE]
+## Layer Analysis
+
+### Layer Overview
+\`\`\`mermaid
+graph TD
+    L1[表现层] --> L2[业务层]
+    L2 --> L3[数据层]
+\`\`\`
+
+### Layer Details
+| 层级 | 目录 | 职责 | 组件数 |
+|------|------|------|--------|
+
+### Layer Interactions
+{层间交互说明}
+
+### Violations & Recommendations
+{违反分层的情况和建议}
+
+[FOCUS]
+1. 识别代码分层（按目录/命名空间）
+2. 每层职责和边界
+3. 层间依赖方向
+4. 违反分层原则的情况
+
+[RETURN JSON]
+{"status":"completed","output_file":"section-layers.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
+`
+})
+```
+
+### Dependencies Agent (Architecture)
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+[ROLE] 依赖分析师，专注于模块依赖关系。
+
+[TASK]
+分析 ${config.scope}，生成 Module Dependencies 章节。
+输出: ${outDir}/sections/section-dependencies.md
+
+[TEMPLATE]
+## Module Dependencies
+
+### Dependency Graph
+\`\`\`mermaid
+graph LR
+    A[ModuleA] --> B[ModuleB]
+    A --> C[ModuleC]
+    B --> D[ModuleD]
+\`\`\`
+
+### Module List
+| 模块 | 路径 | 依赖数 | 被依赖数 |
+|------|------|--------|----------|
+
+### Critical Dependencies
+{核心依赖说明}
+
+### Circular Dependencies
+{循环依赖检测结果}
+
+[FOCUS]
+1. 模块间依赖关系
+2. 依赖方向（单向/双向）
+3. 循环依赖检测
+4. 核心模块识别
+
+[RETURN JSON]
+{"status":"completed","output_file":"section-dependencies.md","summary":"<50字>","cross_module_notes":["发现循环依赖: A <-> B"],"stats":{}}
+`
+})
+```
+
+### Patterns Agent (Design)
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+[ROLE] 设计模式专家，专注于识别和分析设计模式。
+
+[TASK]
+分析 ${config.scope}，生成 Design Patterns 章节。
+输出: ${outDir}/sections/section-patterns.md
+
+[TEMPLATE]
+## Design Patterns Used
+
+### Pattern Summary
+| 模式 | 类型 | 实现位置 | 说明 |
+|------|------|----------|------|
+
+### Pattern Details
+
+#### Singleton Pattern
+**位置**: \`src/core/config.ts:15\`
+**说明**: {实现说明}
+\`\`\`mermaid
+classDiagram
+    class Singleton {
+        -instance: Singleton
+        +getInstance()
+    }
+\`\`\`
+
+### Pattern Recommendations
+{模式使用建议}
+
+[FOCUS]
+1. 识别使用的设计模式（GoF 23种 + 其他）
+2. 模式实现质量评估
+3. 模式使用建议
+
+[RETURN JSON]
+{"status":"completed","output_file":"section-patterns.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
+`
+})
+```
+
+### Algorithms Agent (Methods)
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+[ROLE] 算法分析师，专注于核心算法和复杂度。
+
+[TASK]
+分析 ${config.scope}，生成 Core Algorithms 章节。
+输出: ${outDir}/sections/section-algorithms.md
+
+[TEMPLATE]
+## Core Algorithms
+
+### Algorithm Inventory
+| 算法 | 文件 | 复杂度 | 说明 |
+|------|------|--------|------|
+
+### Algorithm Details
+
+#### {算法名称}
+**位置**: \`src/algo/xxx.ts:42\`
+**复杂度**: 时间 O(n log n), 空间 O(n)
+
+\`\`\`mermaid
+flowchart TD
+    Start([开始]) --> Process[处理]
+    Process --> End([结束])
+\`\`\`
+
+**说明**: {算法说明，≥100字}
+
+### Optimization Suggestions
+{优化建议}
+
+[FOCUS]
+1. 核心业务算法
+2. 复杂度分析
+3. 算法流程图
+4. 优化建议
+
+[RETURN JSON]
+{"status":"completed","output_file":"section-algorithms.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
+`
+})
+```
+
+---
+
+## 执行流程
+
+```javascript
+// 1. 根据报告类型选择 Agent 配置
+const agentConfigs = getAgentConfigs(config.type);
+
+// 2. 准备目录
+Bash(`mkdir -p ${outputDir}/sections`);
+
+// 3. 并行启动所有 Agent
+const results = await Promise.all(
+  agentConfigs.map(agent => launchAgent(agent, config, outputDir))
+);
+
+// 4. 收集简要返回信息
+const summaries = results.map(r => JSON.parse(r));
+
+// 5. 传递给 Phase 3.5 汇总 Agent
+return {
+  summaries,
+  cross_notes: summaries.flatMap(s => s.cross_module_notes)
 };
 ```

 ## Output

-Save analysis results to `deep-analysis.json`.
+各 Agent 写入 `sections/section-xxx.md`，返回简要 JSON 供 Phase 3.5 汇总。
--- a/.claude/skills/project-analyze/phases/03.5-consolidation.md
+++ b/.claude/skills/project-analyze/phases/03.5-consolidation.md
@@ -0,0 +1,198 @@
+# Phase 3.5: Consolidation Agent
+
+汇总所有分析 Agent 的产出，识别跨章节问题，生成汇总报告。
+
+## 输入
+
+```typescript
+interface ConsolidationInput {
+  output_dir: string;
+  config: AnalysisConfig;
+  agent_summaries: AgentReturn[];
+  cross_module_notes: string[];
+}
+```
+
+## 执行
+
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+## 任务
+作为汇总 Agent，读取所有章节文件，执行跨章节分析，生成汇总报告。
+
+## 输入
+- 章节文件: ${outputDir}/sections/section-*.md
+- Agent 摘要: ${JSON.stringify(agent_summaries)}
+- 跨模块备注: ${JSON.stringify(cross_module_notes)}
+- 报告类型: ${config.type}
+
+## 分析维度
+
+### 1. 一致性检查
+- 术语一致性：同一概念是否使用相同名称
+- 代码引用：file:line 格式是否正确
+- 图表编号：是否连续且正确
+
+### 2. 完整性检查
+- 章节覆盖：是否涵盖所有必需章节
+- 内容深度：每章节是否达到 ${config.depth} 级别
+- 图表数量：是否每章节包含图表
+
+### 3. 质量检查
+- Mermaid 语法：图表是否可渲染
+- 代码引用有效性：引用的文件是否存在
+- 建议可行性：推荐是否具体可操作
+
+### 4. 关联性检查
+- 章节间引用：是否有交叉引用
+- 逻辑连贯：内容是否逻辑一致
+- 重复内容：是否有冗余描述
+
+## 输出文件
+
+写入: ${outputDir}/consolidation-summary.md
+
+### 文件格式
+
+\`\`\`markdown
+# 分析汇总报告
+
+## 1. 章节统计
+
+| 章节 | 状态 | 图表数 | 代码引用数 | 字数 |
+|------|------|--------|------------|------|
+| System Overview | completed | 1 | 5 | 450 |
+| ... | ... | ... | ... | ... |
+
+## 2. 发现的问题
+
+### 2.1 严重问题 (阻塞报告生成)
+
+| ID | 类型 | 位置 | 描述 | 建议 |
+|----|------|------|------|------|
+| E001 | missing | section-dataflow | 缺少数据流章节 | 补充数据流分析 |
+
+### 2.2 警告 (影响报告质量)
+
+| ID | 类型 | 位置 | 描述 | 建议 |
+|----|------|------|------|------|
+| W001 | inconsistency | section-overview/layers | 架构描述不一致 | 统一术语 |
+
+### 2.3 提示 (可选优化)
+
+| ID | 类型 | 位置 | 描述 |
+|----|------|------|------|
+| I001 | enhancement | section-algorithms | 建议添加复杂度分析 |
+
+## 3. 跨章节关联
+
+\`\`\`mermaid
+graph LR
+    S1[Overview] --> S2[Layers]
+    S2 --> S3[Dependencies]
+    S3 --> S4[DataFlow]
+
+    S2 -.->|不一致| S1
+\`\`\`
+
+## 4. 报告质量评分
+
+| 维度 | 得分 | 说明 |
+|------|------|------|
+| 完整性 | 85% | 缺少1个章节 |
+| 一致性 | 90% | 2处术语不一致 |
+| 深度 | 95% | 符合 ${config.depth} 级别 |
+| 可读性 | 88% | 图表清晰 |
+
+## 5. 推荐操作
+
+1. **[必须]** 补充 section-dataflow 章节
+2. **[建议]** 统一 Overview 和 Layers 中的架构术语
+3. **[可选]** 为算法章节添加复杂度分析
+\`\`\`
+
+## 返回格式 (JSON)
+
+{
+  "status": "completed",
+  "output_file": "consolidation-summary.md",
+  "quality_score": {
+    "completeness": 85,
+    "consistency": 90,
+    "depth": 95,
+    "readability": 88,
+    "overall": 89
+  },
+  "issues": {
+    "errors": [
+      {"id": "E001", "type": "missing", "section": "section-dataflow", "desc": "缺少数据流章节"}
+    ],
+    "warnings": [
+      {"id": "W001", "type": "inconsistency", "sections": ["section-overview", "section-layers"], "desc": "架构描述不一致"}
+    ],
+    "info": [
+      {"id": "I001", "type": "enhancement", "section": "section-algorithms", "desc": "建议添加复杂度分析"}
+    ]
+  },
+  "stats": {
+    "total_sections": 5,
+    "total_diagrams": 8,
+    "total_code_refs": 42,
+    "total_words": 3500
+  }
+}
+`
+})
+```
+
+## 问题分类
+
+| 严重级别 | 前缀 | 含义 | 处理方式 |
+|----------|------|------|----------|
+| Error | E | 阻塞报告生成 | 必须修复 |
+| Warning | W | 影响报告质量 | 建议修复 |
+| Info | I | 可改进项 | 可选修复 |
+
+## 问题类型
+
+| 类型 | 说明 | 检查范围 |
+|------|------|----------|
+| missing | 缺失章节 | 必需章节列表 |
+| inconsistency | 不一致 | 术语、命名、描述 |
+| invalid_ref | 无效引用 | 代码引用、图表引用 |
+| syntax | 语法错误 | Mermaid 图表 |
+| shallow | 内容过浅 | 深度级别要求 |
+| enhancement | 增强建议 | 最佳实践 |
+
+## 与 Phase 4 的集成
+
+```javascript
+// Phase 4 装配时读取汇总报告
+const summary = JSON.parse(Read(`${outputDir}/consolidation-summary.md`));
+
+if (summary.issues.errors.length > 0) {
+  // 阻止装配，提示用户
+  return AskUserQuestion({
+    questions: [{
+      question: `发现 ${summary.issues.errors.length} 个严重问题，如何处理？`,
+      header: "质量检查",
+      multiSelect: false,
+      options: [
+        {label: "查看并修复", description: "显示问题，手动修复"},
+        {label: "忽略继续", description: "跳过检查，继续装配"},
+        {label: "终止", description: "停止报告生成"}
+      ]
+    }]
+  });
+}
+
+// 在报告中插入质量评分
+insertQualityScore(report, summary.quality_score);
+```
+
+## Output
+
+- 文件: `consolidation-summary.md`
+- 返回: 质量评分 + 问题列表 + 统计信息
--- a/.claude/skills/project-analyze/phases/03.5-diagram-generation.md
+++ b/.claude/skills/project-analyze/phases/03.5-diagram-generation.md
@@ -1,86 +0,0 @@
-# Phase 3.5: Diagram Generation
-
-Generate Mermaid diagrams based on report type and analysis data.
-
-> **Reference**: See [mermaid-utils.md](../../_shared/mermaid-utils.md) for utility functions.
-
-## Execution
-
-### Step 1: Determine Required Diagrams
-
-```javascript
-const diagramRequirements = {
-  architecture: [
-    {type: 'architecture', format: 'graph TD', file: 'architecture.mmd'},
-    {type: 'layers', format: 'graph TD', file: 'layers.mmd'},
-    {type: 'dependencies', format: 'graph LR', file: 'dependencies.mmd'},
-    {type: 'dataflow', format: 'flowchart LR', file: 'dataflow.mmd'}
-  ],
-  design: [
-    {type: 'class', format: 'classDiagram', file: 'class-diagram.mmd'},
-    {type: 'components', format: 'graph TD', file: 'components.mmd'},
-    {type: 'patterns', format: 'graph TD', file: 'patterns.mmd'},
-    {type: 'state', format: 'stateDiagram-v2', file: 'state.mmd'}
-  ],
-  methods: [
-    {type: 'algorithm', format: 'flowchart TD', file: 'algorithm-*.mmd'},
-    {type: 'sequence', format: 'sequenceDiagram', file: 'sequence-*.mmd'},
-    {type: 'critical_path', format: 'flowchart LR', file: 'critical-path.mmd'},
-    {type: 'api', format: 'graph LR', file: 'api.mmd'}
-  ],
-  comprehensive: [
-    {type: 'architecture', format: 'graph TD', file: 'architecture.mmd'},
-    {type: 'class', format: 'classDiagram', file: 'class-diagram.mmd'},
-    {type: 'sequence', format: 'sequenceDiagram', file: 'sequence-main.mmd'},
-    {type: 'dataflow', format: 'flowchart LR', file: 'dataflow.mmd'}
-  ]
-};
-
-const required = diagramRequirements[config.type];
-```
-
-### Step 2: Generate Each Diagram
-
-Use shared utilities from `../_shared/mermaid-utils.md`:
-
-```javascript
-// Import utilities
-const { sanitizeId, escapeLabel, generateClassDiagram, generateSequenceDiagram, validateMermaidSyntax } = require('../_shared/mermaid-utils.md');
-
-for (const diagram of required) {
-  const content = generateDiagram(diagram.type, diagram.format, analysisData);
-  Write(`${outputDir}/diagrams/${diagram.file}`, content);
-}
-```
-
-### Step 3: Validate All Diagrams
-
-```javascript
-const validationResults = validateDiagramDirectory(`${outputDir}/diagrams`);
-const failedDiagrams = validationResults.filter(r => !r.valid);
-
-if (failedDiagrams.length > 0) {
-  // Regenerate failed diagrams
-  for (const failed of failedDiagrams) {
-    regenerateDiagram(failed.file, failed.issues);
-  }
-}
-```
-
-### Step 4: Create Diagram Manifest
-
-```javascript
-Write(`${outputDir}/diagrams/manifest.json`, JSON.stringify({
-  generated_at: new Date().toISOString(),
-  diagrams: required.map(d => ({
-    type: d.type,
-    file: d.file,
-    format: d.format
-  })),
-  validation: validationResults
-}, null, 2));
-```
-
-## Output
-
-Save diagrams to `diagrams/` folder with `manifest.json`.
--- a/.claude/skills/project-analyze/phases/04-report-generation.md
+++ b/.claude/skills/project-analyze/phases/04-report-generation.md
@@ -1,94 +1,302 @@
 # Phase 4: Report Generation

-Assemble analysis and diagrams into structured Markdown report.
+合并所有章节文件，生成最终分析报告。

-## Execution
+> **规范参考**: [../specs/quality-standards.md](../specs/quality-standards.md)

-### Step 1: Determine Report Sections
+## 输入

-```javascript
-const reportSections = {
-  architecture: [
-    "# Architecture Report",
-    "## Executive Summary",
-    "## System Overview",
-    "## Layer Analysis",
-    "## Module Dependencies",
-    "## Data Flow",
-    "## Entry Points & Critical Paths",
-    "## Dependency Graph",
-    "## Recommendations"
-  ],
-  design: [
-    "# Design Report",
-    "## Executive Summary",
-    "## Design Patterns Used",
-    "## Class Relationships",
-    "## Interface Contracts",
-    "## State Management",
-    "## Component Diagrams",
-    "## Design Recommendations"
-  ],
-  methods: [
-    "# Key Methods Report",
-    "## Executive Summary",
-    "## Core Algorithms",
-    "## Critical Code Paths",
-    "## Public API Reference",
-    "## Complex Logic Breakdown",
-    "## Sequence Diagrams",
-    "## Optimization Suggestions"
-  ],
-  comprehensive: [
-    "# Comprehensive Project Analysis",
-    "## Executive Summary",
-    "## Architecture Overview",
-    "## Design Patterns & Principles",
-    "## Key Methods & Algorithms",
-    "## System Diagrams",
-    "## Recommendations & Next Steps"
-  ]
-};
-
-const sections = reportSections[config.type];
-```
-
-### Step 2: Generate Report Content
-
-```javascript
-let report = '';
-
-for (const section of sections) {
-  report += section + '\n\n';
-  
-  // Add section content from analysis
-  const sectionContent = generateSectionContent(section, deepAnalysis);
-  report += sectionContent + '\n\n';
-  
-  // Embed relevant diagrams
-  const relatedDiagrams = findRelatedDiagrams(section, diagrams);
-  for (const diagram of relatedDiagrams) {
-    report += `\`\`\`mermaid\n${Read(diagram.path)}\n\`\`\`\n\n`;
-  }
+```typescript
+interface ReportInput {
+  output_dir: string;
+  config: AnalysisConfig;
+  consolidation: {
+    quality_score: QualityScore;
+    issues: { errors: Issue[], warnings: Issue[], info: Issue[] };
+    stats: Stats;
+  };
 }
 ```

-### Step 3: Add Code References
-
-Format all code references as `file:line`:
+## 执行流程

 ```javascript
-// Example: src/auth/login.ts:42
-const codeRef = `${finding.file}:${finding.line}`;
+// 1. 检查质量门禁
+if (consolidation.issues.errors.length > 0) {
+  const response = await AskUserQuestion({
+    questions: [{
+      question: `发现 ${consolidation.issues.errors.length} 个严重问题，如何处理？`,
+      header: "质量检查",
+      multiSelect: false,
+      options: [
+        {label: "查看并修复", description: "显示问题列表，手动修复后重试"},
+        {label: "忽略继续", description: "跳过问题检查，继续装配"},
+        {label: "终止", description: "停止报告生成"}
+      ]
+    }]
+  });
+
+  if (response === "查看并修复") {
+    return { action: "fix_required", errors: consolidation.issues.errors };
+  }
+  if (response === "终止") {
+    return { action: "abort" };
+  }
+}
+
+// 2. 读取章节文件
+const sectionFiles = Glob(`${outputDir}/sections/section-*.md`);
+const sections = sectionFiles.map(f => Read(f));
+
+// 3. 读取汇总报告
+const summary = Read(`${outputDir}/consolidation-summary.md`);
+
+// 4. 装配报告
+const report = assembleReport(config, sections, summary);
+
+// 5. 写入最终文件
+const fileName = `${config.type.toUpperCase()}-REPORT.md`;
+Write(`${outputDir}/${fileName}`, report);
 ```

-### Step 4: Write Report
+## 报告结构
+
+### Architecture Report
+
+```markdown
+# Architecture Report
+
+> Generated: {date}
+> Scope: {config.scope}
+> Quality Score: {overall}%
+
+## Executive Summary
+
+{3-5 key takeaways from consolidation-summary}
+
+---
+
+{section-overview.md 内容}
+
+---
+
+{section-layers.md 内容}
+
+---
+
+{section-dependencies.md 内容}
+
+---
+
+{section-dataflow.md 内容}
+
+---
+
+{section-entrypoints.md 内容}
+
+---
+
+## Recommendations
+
+{从各章节汇总的建议}
+
+---
+
+## Appendix: Quality Report
+
+{consolidation-summary.md 的质量评分和问题列表}
+```
+
+### Design Report
+
+```markdown
+# Design Report
+
+> Generated: {date}
+> Scope: {config.scope}
+> Quality Score: {overall}%
+
+## Executive Summary
+
+{3-5 key takeaways}
+
+---
+
+{section-patterns.md 内容}
+
+---
+
+{section-classes.md 内容}
+
+---
+
+{section-interfaces.md 内容}
+
+---
+
+{section-state.md 内容}
+
+---
+
+## Design Recommendations
+
+{汇总的设计建议}
+
+---
+
+## Appendix: Quality Report
+
+{质量评分}
+```
+
+### Methods Report
+
+```markdown
+# Key Methods Report
+
+> Generated: {date}
+> Scope: {config.scope}
+> Quality Score: {overall}%
+
+## Executive Summary
+
+{3-5 key takeaways}
+
+---
+
+{section-algorithms.md 内容}
+
+---
+
+{section-paths.md 内容}
+
+---
+
+{section-apis.md 内容}
+
+---
+
+{section-logic.md 内容}
+
+---
+
+## Optimization Suggestions
+
+{汇总的优化建议}
+
+---
+
+## Appendix: Quality Report
+
+{质量评分}
+```
+
+## 装配函数

 ```javascript
-const reportFileName = `${config.type.toUpperCase()}-REPORT.md`;
-Write(`${outputDir}/${reportFileName}`, report);
+function assembleReport(config, sections, summary) {
+  const reportTitles = {
+    architecture: "Architecture Report",
+    design: "Design Report",
+    methods: "Key Methods Report",
+    comprehensive: "Comprehensive Project Analysis"
+  };
+
+  const header = `# ${reportTitles[config.type]}
+
+> Generated: ${new Date().toLocaleDateString('zh-CN')}
+> Scope: ${config.scope}
+> Depth: ${config.depth}
+> Quality Score: ${summary.quality_score?.overall || 'N/A'}%
+
+`;
+
+  // Executive Summary from consolidation
+  const execSummary = generateExecutiveSummary(summary, config.type);
+
+  // Merge sections
+  const mainContent = sections.join('\n\n---\n\n');
+
+  // Recommendations from sections
+  const recommendations = extractRecommendations(sections, config.type);
+
+  // Quality appendix
+  const appendix = generateQualityAppendix(summary);
+
+  return header + execSummary + '\n\n---\n\n' + mainContent + '\n\n' + recommendations + '\n\n' + appendix;
+}
+
+function generateExecutiveSummary(summary, type) {
+  return `## Executive Summary
+
+### Key Findings
+${summary.key_findings?.map(f => `- ${f}`).join('\n') || '- See detailed sections below'}
+
+### Quality Overview
+| Dimension | Score |
+|-----------|-------|
+| Completeness | ${summary.quality_score?.completeness || 'N/A'}% |
+| Consistency | ${summary.quality_score?.consistency || 'N/A'}% |
+| Depth | ${summary.quality_score?.depth || 'N/A'}% |
+
+### Issues Summary
+- Errors: ${summary.issues?.errors?.length || 0}
+- Warnings: ${summary.issues?.warnings?.length || 0}
+- Suggestions: ${summary.issues?.info?.length || 0}
+`;
+}
+
+function extractRecommendations(sections, type) {
+  const recommendationTitles = {
+    architecture: "## Architectural Recommendations",
+    design: "## Design Recommendations",
+    methods: "## Optimization Suggestions",
+    comprehensive: "## Recommendations & Next Steps"
+  };
+
+  // Extract recommendation sections from each section file
+  let recommendations = `${recommendationTitles[type]}\n\n`;
+
+  // Aggregate from sections
+  recommendations += "Based on the analysis, the following recommendations are prioritized:\n\n";
+  recommendations += "1. **High Priority**: Address critical issues identified in the quality report\n";
+  recommendations += "2. **Medium Priority**: Resolve warnings to improve code quality\n";
+  recommendations += "3. **Low Priority**: Consider enhancement suggestions for future iterations\n";
+
+  return recommendations;
+}
+
+function generateQualityAppendix(summary) {
+  return `---
+
+## Appendix: Quality Report
+
+### Overall Score: ${summary.quality_score?.overall || 'N/A'}%
+
+| Dimension | Score | Status |
+|-----------|-------|--------|
+| Completeness | ${summary.quality_score?.completeness || 'N/A'}% | ${getStatus(summary.quality_score?.completeness)} |
+| Consistency | ${summary.quality_score?.consistency || 'N/A'}% | ${getStatus(summary.quality_score?.consistency)} |
+| Depth | ${summary.quality_score?.depth || 'N/A'}% | ${getStatus(summary.quality_score?.depth)} |
+| Readability | ${summary.quality_score?.readability || 'N/A'}% | ${getStatus(summary.quality_score?.readability)} |
+
+### Statistics
+- Total Sections: ${summary.stats?.total_sections || 'N/A'}
+- Total Diagrams: ${summary.stats?.total_diagrams || 'N/A'}
+- Total Code References: ${summary.stats?.total_code_refs || 'N/A'}
+- Total Words: ${summary.stats?.total_words || 'N/A'}
+`;
+}
+
+function getStatus(score) {
+  if (!score) return '?';
+  if (score >= 90) return 'PASS';
+  if (score >= 70) return 'WARNING';
+  return 'FAIL';
+}
 ```

 ## Output

-Generate `{TYPE}-REPORT.md` in output directory.
+- 最终报告: `{TYPE}-REPORT.md`
+- 保留原始章节文件供追溯