# Phase 3.5: Consolidation Agent

汇总所有分析 Agent 的产出，生成跨章节综合分析，为 Phase 4 索引报告提供内容。

> **写作规范**: [../specs/writing-style.md](../specs/writing-style.md)

## 执行要求

**必须执行**：Phase 3 所有 Analysis Agents 完成后，主编排器**必须**调用此 Consolidation Agent。

**触发条件**：
- Phase 3 所有 agent 已返回结果（status: completed/partial/failed）
- `sections/section-*.md` 文件已生成

**输入来源**：
- `agent_summaries`: Phase 3 各 agent 返回的 JSON（包含 status, output_file, summary, cross_module_notes）
- `cross_module_notes`: 从各 agent 返回中提取的跨模块备注数组

**调用时机**：
```javascript
// Phase 3 完成后，主编排器执行：
const phase3Results = await runPhase3Agents();  // 并行执行所有 analysis agents
const agentSummaries = phase3Results.map(r => JSON.parse(r));
const crossNotes = agentSummaries.flatMap(s => s.cross_module_notes || []);

// 必须调用 Phase 3.5 Consolidation Agent
await runPhase35Consolidation(agentSummaries, crossNotes);
```

## 核心职责

1. **跨章节综合分析**：生成 synthesis（报告综述）
2. **章节摘要提取**：生成 section_summaries（索引表格内容）
3. **质量检查**：识别问题并评分
4. **建议汇总**：生成 recommendations（优先级排序）

## 输入

```typescript
interface ConsolidationInput {
  output_dir: string;
  config: AnalysisConfig;
  agent_summaries: AgentReturn[];
  cross_module_notes: string[];
}
```

## Agent 调用代码

主编排器使用以下代码调用 Consolidation Agent：

```javascript
Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  prompt: `
## 规范前置
首先读取规范文件：
- Read: ${skillRoot}/specs/quality-standards.md
- Read: ${skillRoot}/specs/writing-style.md
严格遵循规范中的质量标准和段落式写作要求。

## 任务
作为汇总 Agent，读取所有章节文件，执行跨章节分析，生成汇总报告和索引内容。

## 输入
- 章节文件: ${outputDir}/sections/section-*.md
- Agent 摘要: ${JSON.stringify(agent_summaries)}
- 跨模块备注: ${JSON.stringify(cross_module_notes)}
- 报告类型: ${config.type}

## 核心产出

### 1. 综合分析 (synthesis)
阅读所有章节，用 2-3 段落描述项目全貌：
- 第一段：项目定位与核心架构特征
- 第二段：关键设计决策与技术选型
- 第三段：整体质量评价与显著特点

### 2. 章节摘要 (section_summaries)
为每个章节提取一句话核心发现，用于索引表格。

### 3. 架构洞察 (cross_analysis)
描述章节间的关联性，如：
- 模块间的依赖关系如何体现在各章节
- 设计决策如何贯穿多个层面
- 潜在的一致性或冲突

### 4. 建议汇总 (recommendations)
按优先级整理各章节的建议，段落式描述。

## 质量检查维度

### 一致性检查
- 术语一致性：同一概念是否使用相同名称
- 代码引用：file:line 格式是否正确

### 完整性检查
- 章节覆盖：是否涵盖所有必需章节
- 内容深度：每章节是否达到 ${config.depth} 级别

### 质量检查
- Mermaid 语法：图表是否可渲染
- 段落式写作：是否符合写作规范（禁止清单罗列）

## 输出文件

写入: ${outputDir}/consolidation-summary.md

### 文件格式

\`\`\`markdown
# 分析汇总报告

## 综合分析

[2-3 段落的项目全貌描述，段落式写作]

## 章节摘要

| 章节 | 文件 | 核心发现 |
|------|------|----------|
| 系统概述 | section-overview.md | 一句话描述 |
| 层次分析 | section-layers.md | 一句话描述 |
| ... | ... | ... |

## 架构洞察

[跨章节关联分析，段落式描述]

## 建议汇总

[优先级排序的建议，段落式描述]

---

## 质量评估

### 评分

| 维度 | 得分 | 说明 |
|------|------|------|
| 完整性 | 85% | ... |
| 一致性 | 90% | ... |
| 深度 | 95% | ... |
| 可读性 | 88% | ... |
| 综合 | 89% | ... |

### 发现的问题

#### 严重问题
| ID | 类型 | 位置 | 描述 |
|----|------|------|------|
| E001 | ... | ... | ... |

#### 警告
| ID | 类型 | 位置 | 描述 |
|----|------|------|------|
| W001 | ... | ... | ... |

#### 提示
| ID | 类型 | 位置 | 描述 |
|----|------|------|------|
| I001 | ... | ... | ... |

### 统计

- 章节数: X
- 图表数: X
- 总字数: X
\`\`\`

## 返回格式 (JSON)

{
  "status": "completed",
  "output_file": "consolidation-summary.md",

  // Phase 4 索引报告所需
  "synthesis": "2-3 段落的综合分析文本",
  "cross_analysis": "跨章节关联分析文本",
  "recommendations": "优先级排序的建议文本",
  "section_summaries": [
    {"file": "section-overview.md", "title": "系统概述", "summary": "一句话核心发现"},
    {"file": "section-layers.md", "title": "层次分析", "summary": "一句话核心发现"}
  ],

  // 质量信息
  "quality_score": {
    "completeness": 85,
    "consistency": 90,
    "depth": 95,
    "readability": 88,
    "overall": 89
  },
  "issues": {
    "errors": [...],
    "warnings": [...],
    "info": [...]
  },
  "stats": {
    "total_sections": 5,
    "total_diagrams": 8,
    "total_words": 3500
  }
}
`
})
```

## 问题分类

| 严重级别 | 前缀 | 含义 | 处理方式 |
|----------|------|------|----------|
| Error | E | 阻塞报告生成 | 必须修复 |
| Warning | W | 影响报告质量 | 建议修复 |
| Info | I | 可改进项 | 可选修复 |

## 问题类型

| 类型 | 说明 |
|------|------|
| missing | 缺失章节 |
| inconsistency | 术语/描述不一致 |
| invalid_ref | 无效代码引用 |
| syntax | Mermaid 语法错误 |
| shallow | 内容过浅 |
| list_style | 违反段落式写作规范 |

## Output

- **文件**: `consolidation-summary.md`（完整汇总报告）
- **返回**: JSON 包含 Phase 4 所需的所有字段