Collection

---
name: compiler-doc-writer
description: 编译器技术文档编写专家，提供规范/设计/TDD/教育四类文档的标准化模板，支持EP分析和课程文档生成。
version: v3.0
tags: [documentation, specification, design, tdd, educational, compiler]
allowed-tools: Read, Write, Edit, Task, Glob, Grep, mcp__serena__find_symbol, mcp__serena__search_for_pattern, mcp__serena__list_dir
requires-skills: [compiler-dev, ep-navigator]
---

# 编译器技术文档编写专家

## 🎯 核心职责
**四大文档类型** + **EP智能分析** + **课程体系生成**

```
┌─────────────────────────────────────────────────────────────┐
│                    compiler-doc-writer                       │
├─────────────┬─────────────┬─────────────┬─────────────────┤
│ 规范文档     │ 设计文档     │ TDD计划     │ 教育文档         │
│ (Specification)│ (Design)  │ (TDD Plan)  │ (Educational)   │
├─────────────┴─────────────┴─────────────┴─────────────────┤
│                    EP 智能分析引擎                          │
│              → 自动抽取代码结构、生成教学文档                │
├─────────────────────────────────────────────────────────────┤
│                    课程入口文档生成器                        │
│              → 21个EP关联、学习路径设计                      │
└─────────────────────────────────────────────────────────────┘
```

---

## 📦 四类文档模板

### 1. 规范文档 (Specification)
**用途**: 设计契约，定义高层约定
**命名**: `{EP}_ABI_设计文档.md`

**结构**:
```markdown
# {标题} 规范
**版本**: vX.Y | **状态**: 草稿/评审中/已通过

## 1. 概述
### 1.1 设计目标
### 1.2 术语定义

## 2. 技术规范
### 2.1 核心概念
### 2.2 规范细节

## 3. 实现指南
### 3.1 使用示例

## 附录A: 版本历史
```

### 2. 设计文档 (Design)
**用途**: 实现指南，展示技术细节
**命名**: `{EP}_{模块}_设计文档.md`

**结构**:
```markdown
# {EP} {模块} 设计文档
**版本**: vX.Y

## 1. 设计概述
### 1.1 设计目标
### 1.2 关键设计决策

## 2. 详细设计
### 2.1 核心组件设计
### 2.2 交互设计

## 3. 技术细节
### 3.1 算法实现

## 4. 测试验证
### 4.1 单元测试策略
```

### 3. TDD任务计划
**用途**: 任务驱动，追踪进度
**命名**: `TDD_重构计划.md`

**结构**:
```markdown
# TDD重构计划: {主题}
**版本**: vX.Y

## 1. 概述
### 1.1 重构目标
### 1.2 成功标准

## 2. 任务追踪表
| 层级 | 任务ID | 描述 | 状态 | 优先级 |

## 3. 任务详情
### TASK-1.1: {任务名称}
**目标**: 明确目标
**验收标准**:
- [ ] 所有测试通过
**状态**: ✅/🔄/⏸️
```

### 4. 🆕 教育文档 (Educational) - v3.0 三层叙事结构
**用途**: 编译器构造教学材料，面向学习者
**命名**: `{EP}_教学文档.md` 或 `{主题}_课程指南.md`
**版本**: v3.0 三层叙事框架

**核心设计原则**:
1. **局部聚焦**: 核心概念和实现原理紧密耦合，叙述顺序相近
2. **全局视野**: 揭示主题间内在逻辑联系，服从于编译过程构造大背景
3. **渐进建构**: 从架构全景→主题单元→综合实战，形成完整认知链路

**三层叙事结构**:
```markdown
# {EP名称} - {教学主题}
**编译器构造阶段**: 词法/语法/AST/语义/中端/优化/后端
**难度等级**: 初级/中级/高级
**预计学时**: X小时
**版本**: v3.0

---
## 第一层：架构全景 (Layer 1: Architecture Panorama)

### 1.1 EP在编译流水线中的定位
**编译流程位置**:
```
[源代码] → [词法分析] → [语法分析] → [AST构建] → {本EP} → [后续阶段]
```

**输入输出契约**:
- **输入依赖**: EP{XX}的{输出产物}
- **输出产物**: {本EP的核心输出}
- **下游消费者**: EP{YY}将使用本EP的输出

### 1.2 分层架构设计
根据EP特性绘制4-6层架构图，明确每层职责和层间交互：

```
Layer N: 应用编排层 (Application)
    ↓ 调用
Layer N-1: 算法/执行层 (Algorithm/Execution)
    ↓ 操作
Layer N-2: 数据结构层 (Data Structure)
    ↓ 构建
Layer N-3: 抽象接口层 (Abstract Interface)
    ↓ 实现
Layer N-4: 框架层 (Framework/基座)
```

**层间依赖关系**:
- Layer K extends Layer K-1 (继承关系)
- Layer K uses Layer K-1 (使用关系)
- 明确哪些层是本EP新增，哪些来自前置EP

### 1.3 构建逻辑阶段分解
将EP的实现逻辑分解为4-6个渐进阶段，每个阶段对应第二层的一个主题单元：

```
阶段1: {基础框架/核心概念}
    ↓ 扩展
阶段2: {数据结构定义}
    ↓ 实现
阶段3: {算法/操作}
    ↓ 组合
阶段4: {应用/执行}
    ↓ 优化
阶段5: {高级特性}
```

### 1.4 学习路径导航
- **前置知识**: EP{XX}的{概念}
- **核心技能**: {本EP培养的能力}
- **后续衔接**: 学习本EP后可以进入EP{YY}

---
## 第二层：主题单元 (Layer 2: Topic Units)

每个主题单元遵循统一的"四要素"结构：

### Topic 1: {主题名称}

#### 📍 主题在EP中的位置
```
EP架构层级关系:
┌─────────────────────────────────┐
│  应用编排层 (后续Topic)          │
├─────────────────────────────────┤
│  {本Topic所在层}                 │ ← 我们在这里
├─────────────────────────────────┤
│  前置Topic层                     │
└─────────────────────────────────┘
```

**与前置EP的关系**: 继承/扩展/使用EP{XX}的{组件}
**与后续EP的关系**: 本Topic输出将被EP{YY}使用

#### 🔗 依赖关系图
**继承关系** (extends):
```java
{本类} extends {父类} // 来自EP{XX}
```

**使用关系** (uses):
```java
{本类} → 使用 → {其他类}
```

**类依赖图**:
```
{前置Topic类}
    ↓ 提供{接口/数据}
{本Topic类}
    ↓ 产生{输出}
{后续Topic类}
```

#### 核心内容：概念与实现紧密耦合

**【概念】{核心概念名称}**

*定义*: {精确定义}

*为什么需要*: {在编译过程中的作用}

*关键特性*:
- 特性1: {描述}
- 特性2: {描述}

**【实现】{实现原理/算法}**

*步骤1: {阶段描述}*
```java
// 完整注释的代码示例
// {第X行}: {解释}
public class Example {
    // {实现细节}
}
```

*代码解析*:
- **第X-Y行**: {解释这段代码的作用}
- **关键设计**: {解释为什么这样设计}

*步骤2: {下一个阶段}*
...

**设计模式应用** (如有):
- [{模式名}]: {在本Topic中的作用}

#### 🔄 与下一个主题的连接

**本Topic输出 → 下一个Topic输入**:
```java
// 本Topic提供的数据结构
{本Topic类} output = ...;

// → 下一个Topic使用这个输出
{下一个Topic类} processor = new {下一个Topic类}(output);
```

**连接代码说明**:
- 本Topic产生的{产物}将被下一个Topic的{组件}使用
- 这种设计体现了{设计原则/编译原理}

---

### Topic 2: {下一个主题}
[重复上述四要素结构]

...

### Topic N: {最后一个主题}
[重复上述四要素结构，但无需"与下一个主题的连接"]

---
## 第三层：综合实战项目 (Layer 3: Comprehensive Project)

### 项目名称: {端到端项目}

**项目描述**: 使用本EP所有Topic的知识，构建{完整系统}

**项目目标**:
- [ ] 整合所有Topic的组件
- [ ] 实现{完整功能}
- [ ] 验证{性能指标}

**项目结构**:
```
project-root/
├── src/
│   ├── topic1/    # Topic 1的组件
│   ├── topic2/    # Topic 2的组件
│   └── integration/ # 集成层（调用各Topic组件）
├── test/
│   └── end-to-end/ # 端到端测试
└── examples/       # 完整示例
```

**实现步骤**:

**步骤1: 搭建基础框架** (使用Topic 1)
```java
// Topic 1的组件初始化
```

**步骤2: 集成数据处理** (使用Topic 2-3)
```java
// 连接各Topic组件的代码
```

**步骤3: 实现核心功能** (使用Topic 4-5)
```java
// 完整功能实现
```

**测试验证**:
```java
@Test
public void testEndToEnd() {
    // 端到端测试
}
```

**扩展练习**:
1. 优化{某个组件}
2. 添加{新功能}
3. 性能对比分析

---
## 📊 学习检查点

完成本EP后，你应该能够:
- [ ] **架构理解**: 解释本EP在编译流程中的位置和作用
- [ ] **概念掌握**: 定义{核心概念1}、{核心概念2}...
- [ ] **实现能力**: 实现{关键功能}
- [ ] **系统思维**: 说明各主题如何协同工作
- [ ] **问题分析**: 分析{常见问题}的根因
- [ ] **扩展应用**: 基于本EP框架添加{新特性}

---
## 🔗 知识图谱

**前置依赖**:
- EP{XX}: {需要掌握的概念}

**后续衔接**:
- EP{YY}: 将使用本EP的{输出}

**相关EP**:
- EP{ZZ}: {关联主题}

---
## 📚 参考资源

- **理论教材**: {经典教材章节}
- **在线资源**: {文档链接}
- **开源项目**: {参考项目}
```

---

## 🤖 EP智能分析引擎

### 自动分析流程
当用户请求生成某个EP的教育文档时，按以下流程自动分析:

```
1. 结构分析
   ├── 扫描 EP{NN}/src/ 目录
   ├── 识别核心类和接口
   ├── 构建类依赖关系图
   └── 生成模块清单

2. 代码抽取
   ├── 提取关键算法实现
   ├── 识别设计模式应用
   └── 收集测试用例示例

3. 文档生成
   ├── 填充教学模板
   ├── 插入代码片段和注释
   ├── 生成练习题
   └── 创建检查点清单
```

### 子 Agent 调用协议
**场景**: 用户请求 "生成EP21的教学文档"

```yaml
Step1: 主Agent
  - 读取 EP21_TECH_MEM (Serena记忆)
  - 调用 Task(tool) 启动子Agent

Step2: 子Agent (general-purpose)
  prompt: |
    分析 EP21 目录，完成以下任务:
    1. 列出所有核心类 (带路径)
    2. 对每个核心类:
       - 提取关键方法
       - 选择教学用代码片段 (50-100行)
       - 识别设计模式
    3. 找出3-5个代表性测试用例
    4. 返回结构化分析报告

  tools: [Glob, Grep, Read, mcp__serena__find_symbol]

Step3: 主Agent接收分析结果
  - 填充教育文档模板
  - 生成 EP21_教学文档.md
  - 更新课程入口文档索引
```

### 分析报告格式 (子Agent输出)
```json
{
  "ep": "EP21",
  "title": "高级数据流优化",
  "phase": "优化层",
  "modules": [
    {
      "name": "SSAGraph",
      "path": "ep21/src/main/java/.../SSAGraph.java",
      "purpose": "SSA形式图表示",
      "key_methods": [
        {
          "name": "buildSSA",
          "lines": "45-120",
          "complexity": "高",
          "educational_value": "展示SSA构建算法"
        }
      ],
      "design_patterns": ["Builder", "Visitor"]
    }
  ],
  "test_cases": [
    {
      "class": "SSABuilderTest",
      "method": "testPhiInsertion",
      "concept": "Φ函数插入"
    }
  ],
  "dependencies": ["EP12", "EP17"]
}
```

---

## 🎓 课程入口文档生成器

### 文档结构
**文件名**: `COURSE_编译器构造完全指南.md`

```markdown
# 编译器构造完全指南
**基于 ANTLR4 + Java** | **21个EP** | **从零到优化编译器**

---

## 🗺️ 学习路径

### 路径A: 最小可运行编译器 (快速入门)
```
EP1 → EP2 → EP3 → EP11 → EP16 → EP18
```
**时长**: 2-3周 | **目标**: 能编译简单程序并执行

### 路径B: 完整编译器 (系统学习)
```
EP1-10 (前端) → EP11-15 (中端) → EP16-18 (后端)
```
**时长**: 6-8周 | **目标**: 理解完整编译流程

### 路径C: 优化专家 (进阶)
```
完成路径B → EP17 (CFG) → EP12 (SSA) → EP21 (高级优化)
```
**时长**: 3-4周 | **目标**: 实现工业级优化

---

## 📚 EP课程目录

### 第一部分: 前端编译 (EP1-10)

#### EP1: 词法分析
**教学文档**: [EP1_教学文档.md](./EP1_教学文档.md)
**核心概念**: Token、正则表达式、DFA
**代码示例**: `CymbolLexer.g4`
**难度**: ⭐ | **学时**: 2h

[链接到生成的教学文档]

#### EP2: 语法分析
...

---

## 🎯 按概念索引

| 概念 | 相关EP | 快速跳转 |
|------|--------|----------|
| 词法分析 | EP1 | [链接] |
| 语法树 | EP3 | [链接] |
| 符号表 | EP6 | [链接] |
| SSA形式 | EP12 | [链接] |
| 数据流分析 | EP13, EP21 | [链接] |

---

## 🔧 项目实践
### 实践项目1: 简单计算器语言
涉及EP: EP1-3, EP11, EP16, EP18
难度: ⭐⭐

### 实践项目2: 带函数的语言
涉及EP: EP1-7, EP11, EP16-18
难度: ⭐⭐⭐

### 实践项目3: 优化的编译器
涉及EP: 全部21个EP
难度: ⭐⭐⭐⭐⭐
```

---

## 📊 质量标准

| 维度 | 权重 | 目标 | 检查方式 |
|------|------|------|----------|
| 文档完整性 | 25% | ≥90 | 模板覆盖度 |
| 章节规范性 | 15% | ≥85 | 结构检查 |
| 任务追踪率 | 15% | 100 | TDD任务 |
| **教育价值** | **30%** | **≥90** | 可理解性 |
| **代码示例质量** | **15%** | **≥85** | 注释完整性 |
| **综合** | **100%** | **≥90** | 整体评分 |

---

## 📐 命名约定

| 类型 | ✅ 正确 | ❌ 错误 |
|------|---------|---------|
| 规范文档 | EP21_ABI_设计文档.md | abi_doc.md |
| 设计文档 | EP21_SSA_设计文档.md | ssa.md |
| TDD计划 | TDD_重构计划.md | plan.md |
| 教育文档 | EP21_教学文档.md | ep21_tutorial.md |
| 课程入口 | COURSE_编译器构造完全指南.md | course.md |
| 任务ID | TASK-001, TASK-2.1 | 1.测试 |

---

## 🚀 使用示例

### 示例1: 生成单个EP的教育文档
```
用户: "生成EP21的教学文档"

Agent:
1. 读取 EP21_TECH_MEM
2. 启动子Agent分析EP21代码结构
3. 生成 EP21_教学文档.md
4. 更新课程入口文档索引
```

### 示例2: 生成完整课程文档
```
用户: "生成完整的编译器构造课程文档"

Agent:
1. 遍历所有EP目录 (EP1-EP21)
2. 并行启动21个子Agent分析各EP
3. 逐个生成教学文档
4. 生成课程入口文档
5. 创建概念索引
```

### 示例3: 更新现有文档
```
用户: "EP21有新功能，更新文档"

Agent:
1. 对比现有文档和新代码
2. 识别新增/变更部分
3. 更新教育文档
4. 重新生成检查点
```

---

## 🔗 与其他Skill的协作

| Skill | 协作场景 |
|-------|----------|
| `compiler-dev` | 获取技术实现细节 |
| `ep-navigator` | 查询EP依赖关系 |
| `serena-code` | 分析代码结构和依赖 |
| `test-dev` | 获取测试用例示例 |

---

## 📚 v3.0 三层叙事结构 - 实例参考

以下教育文档已成功升级到v3.0三层叙事结构，可作为生成新文档时的参考模板：

| EP | 文档路径 | 架构特点 | 主题数量 |
|----|----------|----------|----------|
| **EP3** | `/docs/educational/EP3_教学文档.md` | 4层架构: Framework→Data Structure→Traversal Extension→Application | 4 Topics |
| **EP11** | `/docs/educational/EP11_教学文档.md` | 4层架构: Framework→Abstract Intermediate→Concrete Implementation→Application | 5 Topics |
| **EP18** | `/docs/educational/EP18_教学文档.md` | 5层架构: Framework→Concrete Implementation→Execution Engine→Runtime Data→Application | 7 Topics |
| **EP21** | `/docs/educational/EP21_教学文档.md` | 优化Pass架构: Interface→Analysis→Transformation→Verification | 6 Topics |

**关键改进点** (从v1.0/v2.0 → v3.0):
1. ✅ **第一层架构全景**: 明确EP在编译流水线中的位置、分层架构设计、构建逻辑阶段
2. ✅ **第二层主题单元**: 每个Topic包含📍位置、🔗依赖关系、核心内容、🔄主题连接
3. ✅ **主题间连接代码**: 展示Topic N的输出如何成为Topic N+1的输入
4. ✅ **依赖关系可视化**: 继承关系、使用关系、类依赖图
5. ✅ **概念与实现紧密耦合**: 叙述顺序相近，避免分离
6. ✅ **全局视野**: 揭示主题如何服从于编译过程构造大背景

**使用建议**:
- 生成新EP文档时，参考同阶段EP的架构设计（如前端参考EP3，后端参考EP18）
- 使用四要素结构确保每个主题的完整性
- 仔细编写"与下一个主题的连接"部分，确保内在逻辑清晰

---

*版本: v3.0 | 三层叙事结构 + EP智能分析 + 课程体系生成 | 2025-12-27*