Claude-Code-Workflow/.claude/skills/project-analyze/phases/04-report-generation.md

Phase 4: Report Generation

生成索引式报告，通过 markdown 链接引用章节文件。

规范参考: ../specs/quality-standards.md

设计原则

1. 引用而非嵌入：主报告通过链接引用章节，不复制内容
2. 索引 + 综述：主报告提供导航和高阶分析
3. 避免重复：综述来自 consolidation，不重新生成
4. 独立可读：各章节文件可单独阅读

输入

interface ReportInput {
  output_dir: string;
  config: AnalysisConfig;
  consolidation: {
    quality_score: QualityScore;
    issues: { errors: Issue[], warnings: Issue[], info: Issue[] };
    stats: Stats;
    synthesis: string;  // consolidation agent 的综合分析
    section_summaries: Array<{file: string, summary: string}>;
  };
}

执行流程

// 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 report = generateIndexReport(config, consolidation);

// 3. 写入最终文件
const fileName = `${config.type.toUpperCase()}-REPORT.md`;
Write(`${outputDir}/${fileName}`, report);

报告模板

通用结构

# {报告标题}

> 生成日期：{date}
> 分析范围：{scope}
> 分析深度：{depth}
> 质量评分：{overall}%

---

## 报告综述

{consolidation.synthesis - 来自汇总 Agent 的跨章节综合分析}

---

## 章节索引

| 章节 | 核心发现 | 详情 |
|------|----------|------|
{section_summaries 生成的表格行}

---

## 架构洞察

{从 consolidation 提取的跨模块关联分析}

---

## 建议与展望

{consolidation.recommendations - 优先级排序的综合建议}

---

**附录**

- [质量报告](./consolidation-summary.md)
- [章节文件目录](./sections/)

报告标题映射

类型	标题
architecture	项目架构设计报告
design	项目设计模式报告
methods	项目核心方法报告
comprehensive	项目综合分析报告

生成函数

function generateIndexReport(config, consolidation) {
  const titles = {
    architecture: "项目架构设计报告",
    design: "项目设计模式报告",
    methods: "项目核心方法报告",
    comprehensive: "项目综合分析报告"
  };

  const date = new Date().toLocaleDateString('zh-CN');

  // 章节索引表格
  const sectionTable = consolidation.section_summaries
    .map(s => `| ${s.title} | ${s.summary} | [查看详情](./sections/${s.file}) |`)
    .join('\n');

  return `# ${titles[config.type]}

> 生成日期：${date}
> 分析范围：${config.scope}
> 分析深度：${config.depth}
> 质量评分：${consolidation.quality_score.overall}%

---

## 报告综述

${consolidation.synthesis}

---

## 章节索引

| 章节 | 核心发现 | 详情 |
|------|----------|------|
${sectionTable}

---

## 架构洞察

${consolidation.cross_analysis || '详见各章节分析。'}

---

## 建议与展望

${consolidation.recommendations || '详见质量报告中的改进建议。'}

---

**附录**

- [质量报告](./consolidation-summary.md)
- [章节文件目录](./sections/)
`;
}

输出结构

.workflow/.scratchpad/analyze-{timestamp}/
├── sections/                    # 独立章节（Phase 3 产出）
│   ├── section-overview.md
│   ├── section-layers.md
│   └── ...
├── consolidation-summary.md     # 质量报告（Phase 3.5 产出）
└── {TYPE}-REPORT.md             # 索引报告（本阶段产出）

与 Phase 3.5 的协作

Phase 3.5 consolidation agent 需要提供：

interface ConsolidationOutput {
  // ... 原有字段
  synthesis: string;           // 跨章节综合分析（2-3 段落）
  cross_analysis: string;      // 架构级关联洞察
  recommendations: string;     // 优先级排序的建议
  section_summaries: Array<{
    file: string;              // 文件名
    title: string;             // 章节标题
    summary: string;           // 一句话核心发现
  }>;
}

关键变更

原设计	新设计
读取章节内容并拼接	链接引用，不读取内容
重新生成 Executive Summary	直接使用 consolidation.synthesis
嵌入质量评分表格	链接引用 consolidation-summary.md
主报告包含全部内容	主报告仅为索引 + 综述