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-14 02:42:04 +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/
-```