project-analyze

项目分析技能

通过多阶段迭代工作流生成全面的项目分析报告。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│  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        → 最终报告                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

核心设计原则

1. Agent 直接输出 MD：避免 JSON → MD 转换带来的上下文开销
2. 简要返回：Agent 只返回路径和摘要，不返回完整内容
3. 汇总 Agent：由独立 Agent 负责跨章节问题检测和质量评分
4. 合并引用：第 4 阶段读取文件并进行合并，不在上下文中传递内容
5. 段落式描述：禁止罗列清单，采用层层递进、客观的学术表达

执行流程

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Requirements Discovery                                │
│  → Read: phases/01-requirements-discovery.md                    │
│  → Collect: report type, depth level, scope, focus areas        │
│  → Output: analysis-config.json                                 │
├─────────────────────────────────────────────────────────────────┤
│  Phase 2: Project Exploration                                   │
│  → Read: phases/02-project-exploration.md                       │
│  → Launch: parallel exploration agents                          │
│  → Output: exploration context for Phase 3                      │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3: Deep Analysis (Parallel Agents)                       │
│  → Read: phases/03-deep-analysis.md                             │
│  → Reference: specs/quality-standards.md                        │
│  → Each Agent: 分析代码 → 直接写 sections/section-*.md          │
│  → Return: {"status", "output_file", "summary", "cross_notes"}  │
├─────────────────────────────────────────────────────────────────┤
│  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                         │
│  → 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                        │
│  → Loop: 发现问题 → 提问 → 修复 → 重新检查                       │
└─────────────────────────────────────────────────────────────────┘

报告类型

类型	输出	Agent 数量	侧重点
architecture	ARCHITECTURE-REPORT.md	5	系统结构、模块、依赖关系
design	DESIGN-REPORT.md	4	设计模式、类、接口
methods	METHODS-REPORT.md	4	算法、关键路径、API
comprehensive	COMPREHENSIVE-REPORT.md	全部	以上内容的综合

各报告类型的 Agent 配置

架构报告

Agent	输出文件	章节
overview	section-overview.md	系统概览
layers	section-layers.md	层级分析
dependencies	section-dependencies.md	模块依赖关系
dataflow	section-dataflow.md	数据流
entrypoints	section-entrypoints.md	入口点

设计报告

Agent	输出文件	章节
patterns	section-patterns.md	设计模式
classes	section-classes.md	类关系
interfaces	section-interfaces.md	接口契约
state	section-state.md	状态管理

方法报告

Agent	输出文件	章节
algorithms	section-algorithms.md	核心算法
paths	section-paths.md	关键代码路径
apis	section-apis.md	公共 API 参考
logic	section-logic.md	复杂逻辑

目录设置

// 生成时间戳目录名
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const dir = `.workflow/.scratchpad/analyze-${timestamp}`;

// Windows (cmd)
Bash(`mkdir "${dir}\\sections"`);
Bash(`mkdir "${dir}\\iterations"`);

// Unix/macOS
// Bash(`mkdir -p "${dir}/sections" "${dir}/iterations"`);

输出结构

.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

参考文档

文档	用途
phases/01-requirements-discovery.md	用户交互、配置收集
phases/02-project-exploration.md	初步探索
phases/03-deep-analysis.md	并行 Agent 分析
phases/03.5-consolidation.md	跨章节整合
phases/04-report-generation.md	报告组装
phases/05-iterative-refinement.md	质量优化
specs/quality-standards.md	质量门槛、标准
specs/writing-style.md	段落式学术写作规范
../_shared/mermaid-utils.md	共享 Mermaid 工具集