Compiler Doc Writer

编译器技术文档编写专家

🎯 核心职责

四大文档类型 + EP智能分析 + 课程体系生成

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

📦 四类文档模板

1. 规范文档 (Specification)

用途: 设计契约，定义高层约定 命名: {EP}_ABI_设计文档.md

结构:

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

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

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

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

## 附录A: 版本历史

2. 设计文档 (Design)

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

结构:

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

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

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

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

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

3. TDD任务计划

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

结构:

# 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. 渐进建构: 从架构全景→主题单元→综合实战，形成完整认知链路

三层叙事结构:

# {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):

{本类} → 使用 → {其他类}

类依赖图:

{前置Topic类}
    ↓ 提供{接口/数据}
{本Topic类}
    ↓ 产生{输出}
{后续Topic类}

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

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

定义: {精确定义}

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

关键特性:

• 特性1: {描述}
• 特性2: {描述}

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

步骤1: {阶段描述}

// 完整注释的代码示例
// {第X行}: {解释}
public class Example {
    // {实现细节}
}

代码解析:

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

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

设计模式应用 (如有):

🔄 与下一个主题的连接

本Topic输出 → 下一个Topic输入:

// 本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)

// Topic 1的组件初始化

步骤2: 集成数据处理 (使用Topic 2-3)

// 连接各Topic组件的代码

步骤3: 实现核心功能 (使用Topic 4-5)

// 完整功能实现

测试验证:

@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输出)

{
  "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

# 编译器构造完全指南
**基于 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
难度: ⭐⭐⭐⭐⭐

📊 质量标准

📐 命名约定

🚀 使用示例

示例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的协作

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

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

关键改进点 (从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