Module Teach

---
name: module-teach
description: 系统讲解本项目代码：模块讲解（能力大纲 → 代码 wiki → 功能推演 → 应用场景 → 数据流）或变更讲解（commit / PR / 任意 diff：逐处解读 → 影响面 → 意图与权衡），产出可反复查阅的 Markdown 材料。触发："讲讲这个模块"、"学习一下 XXX 代码"、"讲讲这个 commit/PR"、"这个改动是什么意思"、"帮我搞懂这块代码"、"考我一下"。通用知识主题用 topic-teach。
---

# 代码讲解（Module Teach）

## 概述

**目的**：把"读懂一段陌生代码"这件高认知负荷的事，结构化成一个**可校验、渐进式、带图表**的教学流程，让 AI 充当"代码讲解员"，帮助用户快速建立从全局到细节的认知。

**讲解对象**不止是模块，也包括**变更**（详见「讲解对象与范围边界」）：

| 对象 | 回答的问题 | 默认强度 |
|------|-----------|---------|
| **模块**（目录 / 包） | 这个模块能做什么、长什么样、怎么跑、数据怎么流 | **完整讲解** |
| **变更**（commit / PR / 任意 diff 范围） | 这次改动改了什么、为什么改、影响谁、有什么风险 | **精简讲解** |

**功能**：
- 先与用户确认讲解对象与范围（通用知识 / 项目专用知识 / 两者都含）
- **两类对象共用同一套阶段骨架**（Phase 1–7），各阶段按对象类型回答不同问题——编号规则统一为「Phase N 产出 `(N-1)-*.md`」
- 每个讲解点标注 `[通用]` 或 `[专用]`，让用户分清"哪部分是跨项目常识、哪部分是本项目特有"
- **大纲零术语可达**：大纲必含「一句话本质 + 直觉主图（零术语 SVG）+ 特性卡」，让**没有该领域背景**的人也能一看就懂（详见「认知阶梯 · 直觉层」与 Phase 1 A-1）
- 设"正确性核对"质量闸门（Phase 3）：产出结论后回读代码二次校验，杜绝幻觉
- **course-reviewer 双视角评审**（教学法视角 + 新人视角），P0 清零才放行；`00-评审清单.md` 是强制检查点
- **问题驱动叙事骨架**：从"这段代码要解决什么问题"开场，而非从定义或目录树开场（详见「代码讲解叙事骨架」）
- **备课期预收集外部官方文档**：知识范围含 `[通用]` 时，按大纲涉及的官方站走 `web-index`（已建则查表、未建则建索引），后续外部引用与正确性核对从索引取 URL，杜绝编造链接
- **运行环境约定**：运行代码验证结论时按「先探测 → 不污染全局 → 不擅自改用户环境」三条纪律执行，默认 `uv run` / `fnm exec` + `pnpm`（详见对应章节，SSOT 在 topic-teach）
- 最终文档以 Markdown 汇总：Mermaid 以代码块内嵌，复杂图用独立 SVG 文件讲解，便于反复查阅（**不使用 HTML**）
- 大模块自动分批讲解（文件数超阈值时拆分子模块）
- 按学习目标（读懂 / 改造 / 评审）自动调整讲解深度，改造和评审场景增加风险点与建议
- **可选伴读分支**（Phase 7 收尾时询问）：教程完成后可把要点就地注释到核心代码——新建 `teach/{module-slug}` 分支、工作区不干净则不创建、AI 不代为提交（详见「伴读分支」）

**使用场景**：
- 接手 / 维护某个不熟悉的模块，需要快速建立全局认知
- 新人 onboarding，需要一份"从大纲到数据流"的标准化学习材料
- 重构 / 评审前，需要先把模块的真实行为、数据流、适用场景梳理清楚
- **看懂一次变更**：刚 pull 下来一堆改动想搞清楚改了什么、code review 时看不懂别人的 PR、接手前想摸清某个功能是怎么一步步长出来的
- 用户说"讲讲这个模块""学习一下 XXX 代码""讲讲这个 commit / PR 做了什么""这个改动是什么意思"时

> **只讲不改判**：本技能产出"让人读懂"的讲解材料。讲变更时说清"做了什么 / 为什么 / 影响谁"，**不下"该不该合"的结论、不出问题清单**——那是 `code-review` 的职责（详见「与相邻 skill 的分工与路由」）。

## 与相邻 skill 的分工与路由

讲解类需求容易同时命中多个 skill。按下表路由，**判定顺序自上而下，命中即停**：

| 相邻 skill | 它做什么 | 与本技能的分界 | 路由判定 |
|---|---|---|---|
| `code-survey` | 为**设计**做调研，按需取 13 个维度输出事实清单 | 要"讲懂一个模块" → 本技能；只要"查清某几个事实点" → code-survey | "讲讲 / 搞懂 / 接手这个模块" → 本技能；"调研一下 / 了解现有代码 / 代码风格是什么" → code-survey |
| `expert-team` | 沉淀**可复用资产包**（契约层 + 实现层），供 AI 后续复用 | 要"人读懂" → 本技能；要"AI 以后能直接复用" → expert-team | "建个专家 / 沉淀这个模块" → expert-team |
| `code-review` | **裁决**——改动该不该合、有什么问题，给分级意见 | 本技能**只讲不改判**：讲清"这个模块是什么、怎么工作"；"代码有没有问题"归 code-review | "review 这个提交 / 挑毛病" → code-review；"讲讲这个模块 / 帮我搞懂这块代码" → 本技能 |
| `topic-teach` | 教**跨项目通用知识**（k8s / 理财等），证据来自内置知识 + 联网 | 讲解对象是**本项目代码** → 本技能；是通用知识主题 → topic-teach | 只说"讲讲 X"：X 是本项目代码路径 → 本技能；否则 → topic-teach |
| `web-index` | 给外部文档站建「我要做什么 → 去哪一页」的本地路由表 | **不是竞争路由，是被本技能调用**——Phase 1.5 用它收集 `[通用]` 部分要引用的官方文档 | "讲讲这个模块" → 本技能（内部按需调 web-index）；单独说"给这个站建个索引" → web-index |
| `index-lookup`（+ `backend-index` / `frontend-index`） | 提供已落盘的「模块 ↔ 目录/依赖/数据表」或「页面 ↔ 接口」索引（消费侧统一入口） | 索引给**范围与依赖骨架**（去哪看），本技能负责**讲懂**；`module` 类讲解可先用它锁定模块边界与依赖（省一次全仓扫描，Phase 0/1 的取证更省；**无索引 / 未命中 / 过期则照常直读代码，不阻塞**） | "讲讲这个模块" → 本技能（内部先查索引拿范围）；单纯问"这代码在哪 / 改了影响谁" → index-lookup |

> **分界的核心一句话：教学 vs 裁决。** 本技能产出的是"让人读懂"的讲解材料，**不下质量结论、不出问题清单**。讲解过程中用户主动追问"那这样写有问题吗" → 转 `code-review`，本技能不越权。
>
> 本次**不在相邻 skill 侧新增**反向指针（避免双源漂移）；`topic-teach` 已有的「与 module-teach 的分工」说明保持不变，两侧措辞若有冲突，以本表为准。

## 讲解对象与范围边界

**核心抽象：讲解对象 = 一组代码 + 一个范围边界。** 模块是**空间边界**（目录树），变更是**时间边界**（diff）。两类对象共用 Phase 1–7 骨架，差异只在"各阶段回答什么问题"与"取证方式"。

### 对象类型矩阵

| 对象类型 | 范围边界 | 取证方式 | 核心问题 | 落点 |
|---------|---------|---------|---------|------|
| `module` 模块 | 目录 / 包 / 单文件集合 | `list_dir` / `search_file` / `read_file` | 这个模块能做什么、怎么工作 | `.teach/{module-slug}/` |
| `commit` 提交 | 单个或多个 commit、未提交改动 | `git show {sha}` / `git diff A..B` / `git status` | 这次改动改了什么、为什么改 | `.teach/commits/{slug}/` |
| `pr` 变更集 | PR 的完整 diff + 描述 + 评论 | PR 元数据 + 跨 commit 合并 diff | 这个 PR 整体要解决什么、各提交怎么串 | `.teach/prs/{slug}/` |
| `change` 任意范围 | 指定路径 / 版本区间 / 工作区改动 | `git diff A..B -- {path}` | 这批改动做了什么 | `.teach/changes/{slug}/` |

**slug 命名**：`commit` 用 `{短 sha}-{一句话主题}`（如 `a1b2c3d-修复并发下重复下单`）；`pr` 用 `{PR号}-{主题}`；`change` 用用户可辨识的主题 kebab-case。中文主题可保留，与 module 落盘的中文件命名惯例一致。

### 取证纪律（变更类专属）

1. **diff 是唯一事实源**：一切结论必须能回溯到 diff 的具体行。**禁止凭 commit message 或 PR 描述推断改动内容**——描述会过时、会写错、会漏。
2. **意图必须分级标注**：
   - `[显式]`：commit message / PR 描述 / 代码注释里**写明**的动机 → 可直接引用
   - `[推断]`：从 diff 语义反推的动机 → **必须标注为推断**，并给出推断依据（如"该函数新增了重试分支，推断为应对 X 场景的失败"）
   > 两者混在一起就是体面的编造。读者最想知道的恰恰是"作者当时为什么这么改"，把推断当显式说是最糟的失真。
3. **影响面必须实证**：讲"改了这里会影响谁"时，**必须**用 GitNexus `impact` / `context` + `search_content` 取证调用方与消费方，**禁止凭 diff 文本推断**——diff 只显示被改的文件，调用方在 diff 之外。判定不了影响面时写"影响面待确认"，不猜。
   > **降级路径（必读）**：GitNexus MCP 不可用时，退回 `search_content` 全局搜索调用点 + 逐处 `read_file` 回源码确认，**结论同样须回到源码**。此时在 `03-影响面分析.md` 顶部标注 `⚠️ 影响面基于 grep + 源码阅读取证（GitNexus 不可用），覆盖度可能低于图谱查询`。**MCP 不可用不是降低取证标准的理由，只是换一种取证方式。**
4. **PR 数据的获取方式**：优先用 `gh pr diff {N}` / `gh pr view {N}`（GitHub CLI）；无 `gh` 时用 `git diff {base}...{head}` 取合并 diff（`...` 三点语法取合并基准到 head 的变更）；IDE 提供 PR 视图时可直接读取。**取不到 PR 元数据时，降级为按 `change` 类型讲解 diff 本身**，并在产物顶部标注"未取到 PR 描述，意图分析仅基于 diff"。
5. **非 git 环境降级**：无法取 diff 时（用户只粘贴了代码片段 / 仓库无 git），显式降级为「仅解读用户提供的文本」，在产物顶部标注 `⚠️ 本材料基于用户提供的片段，未取完整 diff，影响面未验证`，且**跳过影响面分析阶段**——没有 diff 就没有影响面的证据基础。
6. **不越权评审**：讲变更时只描述与解释。发现明显问题 → 记录进 `05-风险与待确认.md` 的「需向作者确认」清单，**不写成"这个改动不该合"**。
7. **档案是一次性消费，可随时删除**：变更档案（`.teach/commits|prs|changes/`）与模块档案不同——模块档案会反复查阅，变更档案通常读完就完成使命，且**会随时间无限堆积**（讲 50 个 commit 就是 50 个目录）。落盘时告知用户这点，清理时**可整目录删除**（与模块档案的"禁止误伤"不同：`*.md` 与 `assets/` 的禁止误伤约束针对**正在讲解的**产物，已完成的变更档案不在此列）。

### 两级强度（防流程过载）

| 模式 | 默认适用 | 执行阶段 | 产物 | 评审 |
|------|---------|---------|------|------|
| **完整讲解** | `module`；变更类在用户要求"详细点"或规模大（跨 20+ 文件）时 | Phase 0 → 7 全量（含 `[通用]` 时插入 **Phase 1.5**） | 00–06 全套 | 按评审规则表：大纲单实例 / 解读双实例 / 收尾双实例 |
| **精简讲解** | `commit` / `pr` / `change` | Phase 0 → 1 → 2 → 3 → 7（跳过 1.5 / 4 / 5 / 6） | `00-变更大纲` / `01-逐处解读` / `02-正确性核对` / `06-最终文档` | `01-逐处解读` 单实例 + 收尾单实例 |

> **为什么变更类默认精简**：用户说"讲讲这个 commit"通常要的是 10 分钟读懂，不是一份 6 文件的档案。默认给重的，多数场景是浪费；默认给轻的，想要的能一句话升级——**漏做比多做容易补**。
>
> **"精简"是相对完整模式，不是相对"随便讲讲"**：精简模式仍有 4 份产物 + 两轮评审 + 质量闸门，比一次性的"你给我解释下这段 diff"系统得多。用户要"系统且详细"时，说一句"再详细点"即可升级（接力提示词已指向升级），**无需重新描述上下文**。
>
> **模式必须显式标注**：变更类每份产物顶部须写一行——`本文为{精简 / 完整}讲解（Phase 0→1→2→3→7）。如需影响面 / 意图权衡 / 风险分析，说"再详细点"可升级为完整模式。` 不标注，用户就不知道还有升级这回事。
>
> **精简模式下 Phase 3 正确性核对不可跳过**——它是质量闸门，变更解读最易失真的地方就是"这段 diff 我理解错了"。

## 教学产物落盘

所有产物写入 `.teach/` 下按对象类型分目录。

**模块类**（`module-slug` 取模块目录名的 kebab-case）：

```
.teach/{module-slug}/
├── 00-能力大纲.md            # Phase 1：对外职责 / 公开能力 / 关键抽象
├── 00-评审清单.md            # 评审强制检查点：事前占位待办 + 事后勾选
├── 01-代码wiki.md            # Phase 2：结构 / 关键类与函数 / 依赖 / 模式与不变量
├── 02-正确性核对.md          # Phase 3：质量闸门（回读代码校验前序结论）
├── 03-功能推演.md            # Phase 4：运行时行为 / 边界异常 / 性能
├── 04-应用场景.md            # Phase 5：适用场景与不适用场景 / 待解决问题
├── 05-数据流.md              # Phase 6：数据生命周期 / 状态流转 / 异步流
├── 06-最终文档.md            # Phase 7：汇总全部阶段（Mermaid 代码块内嵌 + SVG 图引用）
├── assets/                   # 复杂图 SVG（kebab-case 命名）
├── 07-知识点对齐.md           # Phase 8：最新一轮选择题 + 成绩单（可选）
├── quiz-history/             # 历次知识点对齐记录（可选）
│   ├── INDEX.md              # 轮次索引：轮次/日期/正确率/错题知识点
│   └── round-01.md           # 第 1 轮：题目+选项+正确答案+用户作答+知识点标签
└── sub-modules/              # 可选：大模块分批讲解时子模块产物存放于此
    ├── {sub-1}/
    └── {sub-2}/
```

**变更类**（`commit` / `pr` / `change` 同构，此处以 commit 为例）：

```
.teach/commits/{短sha}-{主题}/
├── 00-变更大纲.md            # Phase 1：改了哪些文件 + 意图归类
├── 00-评审清单.md            # 评审强制检查点（变更类精简模式只占位 2 条评审 + 1 条质量闸门）
├── 01-逐处解读.md            # Phase 2：逐 hunk before → after 对照
├── 02-正确性核对.md          # Phase 3：质量闸门（精简模式也不可跳过）
├── 03-影响面分析.md          # Phase 4（完整模式）：调用方 / 消费方 / 契约 / 数据流影响
├── 04-意图与权衡.md          # Phase 5（完整模式）：显式意图 vs 推断意图 + 设计权衡
├── 05-风险与待确认.md        # Phase 6（完整模式）：风险点 + 需向作者确认的问题
├── 06-最终文档.md            # Phase 7：汇总
└── assets/
```

> **编号规则统一**：**Phase N 产出 `(N-1)-*.md`**。两类对象同编号不同名（`03-功能推演.md` vs `03-影响面分析.md`），便于跨类型形成一致习惯。
>
> **`07-知识点对齐.md` 与 `06-最终文档.md` 的编号差是历史约定**（Phase 8 产出 07，与 `topic-teach` 统一），不因流程顺序在末尾而重编号——`topic-teach` 反向依赖本技能的 Phase 8。

每写完一个阶段文件，在对话中给一句阶段摘要（结论 + 关键发现 + 文件链接），不要一次性把全文甩进对话。

## 产物卫生（落盘须知）

产物写在 **`.teach/` 目录，落在被讲解的项目仓库内**——它和用户的源码共用同一个 git 仓库。这是本技能与 `topic-teach`（独立产物仓库）在落盘上的根本差异，故须遵守：

1. **不动用户的忽略规则**：用户项目已有的 `.gitignore` 一律不改，即使看起来该加规则。**正常讲解不运行被讲解的代码**，故**默认不需要维护 `.gitignore`**——`topic-teach` 需要（它会生成并运行实战项目），本技能默认不需要，**不要照搬整套机制**；完整机制以 `topic-teach` SKILL 为准。
   > **例外（不留真空）**：若本轮为验证结论**实际运行了脚本 / 测试**并产生了依赖目录、缓存、日志（如 `__pycache__/` / `.pytest_cache/` / `.venv/` / `node_modules/`），则仍需追加对应规则——同样遵守「只追加、范围限定 `.teach/` 与临时目录、不碰用户既有规则」。触发概率低，但第 3 条已承认会产生临时验证脚本，此处不能把门关死。
   > **运行本身就按「运行环境约定」执行**（先探测环境、用 `uv run` / `fnm exec`、不污染全局）——做对了，这里的例外就很少触发。
2. **首次落盘时提示一次**：生成 `.teach/` 后在对话中告知"`.teach/` 已生成于项目根目录，是否提交由你决定"。**不代为执行 `git add` / `git commit`**，也不擅自把 `.teach/` 加进 `.gitignore`——那是用户的选择，不是 AI 的。
3. **临时文件清理**：讲解过程中若产生中间草稿 / 临时验证脚本，**创建时就在对话中记下路径**，落盘收尾时按记录清理——**只删记录在案的文件，用精确路径删除，禁用 `git clean -fd`**（会连用户自己的未跟踪文件一起删）。**没有记录的一律不删**：8 个 Phase 的长流程里"本轮亲手创建"的记忆同样会失真，判断依据只能是记录；漏记的失败方向是安全的（临时文件留在磁盘上），绝不为"完成清理动作"而现场凑清单。
4. **禁止误伤**：`.teach/` 下的 `*.md` 与 `assets/*.svg` 是讲解产物本体，任何时候都不删除、不忽略。
   > **例外**：**已完成讲解的变更档案**（`.teach/commits|prs|changes/` 下的旧目录）可整目录删除——它们是一次性消费且会无限堆积，见「取证纪律」第 7 条。本条的禁止误伤约束针对**正在讲解的**产物。

> **判定口诀**：*这个动作是在动我的产物，还是在动用户的项目？* 只动前者。
>
> **唯一例外**：用户显式同意下的「伴读分支」（见下节）——只在新分支上进行、只加可整体还原的自然注释（无标记前缀）、不提交、不合并。

## 伴读分支（可选 · 仅 `module` 类）

> **定位**：教程是"文档层讲解"，伴读分支是"代码层讲解"——把要点**就地注释**到核心代码上，读代码时不用来回翻文档。这是本技能**唯一获授权改动用户源码**的场景（「产物卫生」的显式例外），必须同时满足：用户显式同意 ＋ 新分支隔离 ＋ 只加注释 ＋ 不提交 ＋ 可整体剔除。

**触发**：Phase 7 收尾三件事完成后**询问一次**（用户可拒绝、可改分支名）；用户显式要求时直接执行。**未经用户同意不得创建分支。** 变更类不适用（一次性消费）。

**硬闸门（任一不满足 → 不创建，并说明原因）**：

1. **工作区必须干净（本技能自身产物除外）**：`git status --porcelain` 输出中，剔除本技能产物（`.teach/`、`.web-index/`、`temp/web-index-*`）后仍非空 → **不创建**，列出剩余脏文件，请用户先自行提交或暂存后再来。**AI 不替用户处理工作区**（不代提交、不代 stash）。
   > 为什么排除自身产物：三者正是本流程刚生成的教程档案 / 网页索引 / 临时文件，且「产物卫生」规定其提交与否由用户决定——不排除，功能在"教程刚落盘、产物未提交"的常见流程下会被自己的产物卡死；闸门真正要防的是**用户的未提交改动**被卷入伴读分支。
2. **非 git 环境** → 不提供，一句话说明。
3. **分支已存在**（`teach/{module-slug}`）→ 不覆盖、不加 `-f`，列出候选让用户决定。

**执行步骤**（用户同意后）：

1. 记录基准：当前分支名 + `git rev-parse --short HEAD`。
2. 创建并切换：`git switch -c teach/{module-slug}`。
3. **加注释**（纪律）：
   - **只加注释、不改一行语义**（不顺手格式化 / 重命名 / 修 bug）；**不加任何标记前缀**——像项目原生注释一样自然书写；剔除靠 `git restore`（整体或按文件还原）。
   - **就近分散**：每条注释紧贴它解释的那一行 / 那个分支；**禁止把整段讲解堆在函数 / 类 / 方法签名上方**——签名上方至多一句"这是干什么的"，机制细节下沉到函数内部对应语句旁。正反例见 [reference.md](reference.md) §9.2。
   - 每个被注释文件头部保留**一行**自然语言说明（声明含教学注释 + 还原方式），模板见 [reference.md](reference.md) §9.2。
   - 只覆盖教程**重点文件与关键函数**（Phase 2 wiki 的关键清单），不撒胡椒面；语言与风格随项目既有约定。
   > 注释是"第二次通读代码"：动笔前**抽查**核心文件的 `file://` 锚点与当前代码是否仍对应——明显漂移（函数已改名 / 删除）以代码为准并告知用户；**若发现教程结论与代码不符，先按 Phase 3 修正级联修正教程，再据修正后的内容写注释**（不得照抄错误结论）。
4. **机械自检**：`git diff --numstat` —— **删除数必须为 0**（只有注释行新增）；发现语义改动立即修正。
5. **记录**：在 `06-最终文档.md` 追加「伴读分支」小节（模板见 [reference.md](reference.md) §9）——分支名 + 基准 sha + 日期 + 注释范围 + **"未提交"警示**；该小节是元信息（非讲解内容），不需重跑评审。
6. **对话提示**：告知四条——① 已切到伴读分支、注释**未提交**；② **未提交的注释不在分支里**（只附着工作区，切到哪跟到哪；`git restore .` 丢弃即消失），**想固定到分支上、随时回看，请自行提交**；③ **切回主线前必须先处理**（提交保留，或丢弃改动），否则未提交改动会**跟随**到主线工作区；④ 分支留存或删除由用户决定。

**硬边界**：

- AI **不执行** `git add` / `git commit`，也不得绕过签名要求——是否提交、何时提交由用户决定。
- **不合并、不 push**；伴读分支是"一次性伴读层"——未提交时注释不存储在分支里（丢弃即消失），其持久化只由用户提交决定。

## 运行环境约定（精简版 · SSOT 在 topic-teach）

讲解中若需**运行代码**验证结论（临时验证脚本、跑测试、复现某段行为），完整规则见 `topic-teach` 的 `ops.md`「运行环境约定」（**SSOT**）。此处只留模块讲解场景的四条要点：

1. **三条硬纪律**（优先于任何工具选型）：
   - **先探测，后执行**——不假定项目装了 uv、不假定 Node 版本
   - **绝不污染全局**——禁止裸 `pip install <pkg>`（会装进系统 Python）、禁止 `npm i -g`
   - **不擅自安装或切换用户环境**——uv / fnm 不存在就**提示并询问**，不自行安装；不 `fnm install` 新版本、不改 `fnm default`。**安装工具链是改变用户机器状态，需要授权**
2. **优先级链**：用户显式指定 > 项目既有约定（lockfile / `.python-version` / `.nvmrc` / `packageManager` 字段）> 默认推荐。**项目约定优先于口头指定**——lockfile 是事实
3. **默认推荐**：Python → `uv run <命令>`（含 `uv run --with <pkg>` 跑一次性依赖）；Node → `fnm exec --using <ver> -- <命令>` + `pnpm`（一次性工具用 `pnpm dlx`，不用 `npx`）。**跑不通时按 SSOT 的三步降级链处理**（`fnm env` 注入 → 标注实际版本后直跑 → 仍失败则报告用户），**不自行安装工具链、不改全局默认版本**
4. **与产物卫生联动**：`uv run` 会自动建 `.venv/`、`pnpm install` 会建 `node_modules/`——跑完须按「产物卫生」第 1 条例外确认已忽略。**优先用一次性依赖形式**，不写进项目依赖、不产生新增 lockfile

> 模块讲解运行代码的场景远少于 topic-teach（后者要验证 Phase 3 实战项目 `实现/` 真的能跑），故此处不重复定义完整规则，只留执行要点。

## course-reviewer 评审执行规则（各评审节点通用）

正确性核对（Phase 3）是**自检**——主 agent 回读自己的结论。评审是**他检**，两者不可替代。本技能全部评审节点统一按此规则执行，`course-reviewer` 支持三模式（本技能只用前两种：`pedagogy` / `learner`；第三种 `rehearsal` 教学效果推演仅供 topic-teach 大纲评审使用），由主 Agent 通过【评审模式】字段指定：

| 模式 | 视角定位 | 核心问题 |
|---|---|---|
| **教学法视角**（`pedagogy`） | 讲解质量审查者——检查知识组织与内容准确性 | 结构是否递进、结论是否可溯源、有无编造、`[通用]`/`[专用]` 标注是否到位、图表选型是否合规 |
| **新人视角**（`learner`） | 接手者代入——化身"刚接手这段代码的新人"实际读一遍 | 能不能读懂？在哪里会卡住？术语是否未铺垫就出现？读完后能否说清这段代码在系统里的位置？ |

> **新人视角不是教学法视角的补充，是独立的第二视角**：讲解者最常犯的错是"自己觉得讲清楚了"。新人视角专门抓这个——它要的是"读不懂的具体位置"，不是抽象的"不够清晰"。

### 评审节点与模式

| 评审节点 | 模块类（完整模式） | 变更类（精简模式） | 叠用专项维度 |
|---|---|---|---|
| 大纲评审（Phase 1） | 单实例 `pedagogy` | 跳过 | **D8**（零术语可达性，本节点第一优先级） |
| 解读评审（Phase 2） | **双实例** | **单实例 `pedagogy`（不可跳过）** | D（变更类叠加 E） |
| 收尾评审（Phase 7） | **双实例** | 单实例 `pedagogy` | D（变更类叠加 E） |

### 执行步骤

1. **可用性检查**：评审前确认 `course-reviewer` 子 agent 是否可用（通过 `use_agent(course-reviewer)`）。
2. **已创建** → `use_agent(course-reviewer)`，输入中指定【评审模式】【评审节点】【对照基准】【评审维度】（Phase 0 确认的对象 / 范围 / 学习目标；【评审维度】= 本技能 `review-dimensions.md` 全文）。
3. **未创建** → 二选一，**默认走"直接评审"，不阻塞讲解流程**：
   - **直接评审（默认）**：主 agent 直接以两种角色定位执行评审。双实例节点须**分两轮独立输出**（先 pedagogy 完整评审一遍，再 learner 完整评审一遍），**不得合并成一轮"综合评审"**——合并即丧失独立性。
     - **独立性约束**：内联评审时新人视角不得走过场，**必须逐项输出完整评审表**（每维度至少 1 条意见或"无问题"）。主 agent 同时扮演生成者 + 两个评审者 + 裁决者，独立性最弱，须以完整输出补偿。在 `00-评审清单.md` 标注「主 agent 内联（子 agent 未创建，独立性受限）」，并提醒用户可创建独立子 agent 获得更独立的评审。
   - **提醒创建**：提示用户可按 `create-sub-agent` 规范创建；用户同意则创建后回到正常委派流程。
4. **评审结论**：无论何种方式，结论记入 `00-评审清单.md`（P0 清零才放行）。
5. **评审清单强制检查点**：`00-评审清单.md` 是唯一可验证的**待办勾选**检查点。Phase 1 落盘时**占位**全部评审节点（`- [ ]`）；每个节点评审完成且 P0 清零后，**必须回到清单勾选**（`- [x]`）。**未勾选条目 = 评审未完成**，是断点续学时发现漏评审并补做的依据。

### 专项维度（SSOT 在 `review-dimensions.md`，此处只索引）

- **专项维度 D（代码讲解）**：`file://` 与行号区间可溯源、无编造结论、`[通用]`/`[专用]` 标注完整、章节来源跨度合规、认知阶梯不倒序、**零术语可达性（D8）**、**术语对标（D9）**
- **专项维度 E（变更讲解）**：意图标注区分显式 / 推断、影响面有实证、before → after 对照准确、**只描述不裁决**

> 完整维度定义与分级规则见 **`review-dimensions.md`（SSOT）**——与 `SKILL.md` 同目录，属"同 skill 内相对路径"，**必然可达**，不依赖子 agent 是否已创建。**本技能不重复定义评审维度**——重复定义必然双源漂移（子 agent 内置的只是兜底骨架，细则以该文件为准）。

### 双模式冲突处理

两个实例意见可能冲突（如 pedagogy 说"结构完整 P0=0"，learner 说"第三节术语未铺垫，新人必卡 P0=1"）：

- **P0 取两者并集**（任一模式报 P0 即需处理）
- 冲突意见**由主 Agent 自行裁决**，在 `00-评审清单.md` 标注"双模式冲突，主 Agent 裁决：{裁决理由}"

## 工作流程

复制此清单并跟踪进度（**按讲解对象勾选对应分支**）：

```
任务进度：
- [ ] Phase 0：确认对象与范围（对象类型 / 目标 / 知识范围 / 学习目标）
- [ ] Phase 0.5：分批判断（仅 module：大模块拆子模块？）

【模块类 · 完整讲解】
- [ ] Phase 1：能力大纲（含 A-1 零术语开场 + 直觉主图）→ 大纲评审（教学法视角）→（知识范围含 `[通用]`）Phase 1.5 外部官方文档收集
- [ ] Phase 2：基础代码 wiki → 双实例评审
- [ ] Phase 3：正确性核对（质量闸门）
- [ ] Phase 4：功能推演（含性能与复杂度）
- [ ] Phase 5：应用场景与待解决问题
- [ ] Phase 6：数据流分析
- [ ] Phase 7：最终文档 + 汇总完整性检查 + 收尾评审

【变更类 · 精简讲解（默认）】
- [ ] Phase 1：变更大纲
- [ ] Phase 2：逐处解读 → 单实例评审
- [ ] Phase 3：正确性核对（质量闸门，不可跳过）
- [ ] Phase 7：最终文档 + 汇总完整性检查 + 收尾评审

【变更类 · 完整讲解】—— 用户要求"详细点"或变更规模大（跨 20+ 文件）时追加
- [ ] Phase 4：影响面分析（调用方 / 消费方 / 契约 / 数据流）
- [ ] Phase 5：意图与权衡
- [ ] Phase 6：风险与待确认

【通用 · 可选】
- [ ] Phase 8：知识点对齐 · 选择题
- [ ] 伴读分支（仅 module）：工作区干净检查 → 切 `teach/{module-slug}` → 加教学注释（无标记、就近分散）→ 自检（删除数=0）→ 记录（不提交）
```

> 探索代码一律用 `list_dir` / `search_file` / `search_content` / `read_file` 等工具，**不要凭记忆讲解**。记录每个结论对应的 `file://路径#Lx-Ly`，供章节来源 / 图表来源使用。
>
> 讲**变更**时另需：`git show` / `git diff` 取 diff 作为事实源；**diff 之外的调用方与消费方必须用 GitNexus `impact` / `context` + `search_content` 实证**，不得凭 diff 文本推断（MCP 不可用时退回 grep + 源码阅读，结论须回到源码确认）。

### 断点续学

用户说"继续讲 XX""上次那个模块接着讲"时，**跳过 Phase 0**（对象与范围已定），直接定位落点：

1. **定位档案**：在 `.teach/` 下按对象类型找目录（模块类 `{module-slug}/`；变更类 `commits/` / `prs/` / `changes/`），与用户口语主题模糊匹配。命中多个或零个 → 列出候选让用户选。
2. **读状态**：先看 `00-评审清单.md`（**未勾选条目 = 对应评审未完成**），再看 `00-*.md` 顶部的对象与范围确认 **与「外部文档索引」小节**（有则后续外部引用走索引，不重新建）。`06-最终文档.md` 存在 = 已收尾。
3. **按序判定落点**（命中即停）：

   | # | 条件 | 落点 |
   |---|------|------|
   | 1 | 清单有未勾选条目，**且其对应产物文件已存在** | **漏评审** → 先补做该条目的评审 |
   | 2 | 某阶段产物文件缺失 | 从该阶段继续（按编号顺序 00 → 01 → 02 → …） |
   | 3 | 变更类精简模式已完成，用户说"再详细点" | 从 Phase 4 起补完整模式（补 03 / 04 / 05 并更新 06） |
   | 4 | 前序齐全但 `06-最终文档.md` 不存在 | Phase 7 汇总 |
   | 5 | 全部完成 | 询问用户想做什么（深入某方向 / 知识点对齐 / 伴读分支 / 换对象） |

   > **第 1 条的判定关键是"产物是否已存在"**：清单未勾选 ≠ 漏评审——正常讲到 Phase 2 时，Phase 4 条目当然未勾选（还没做到）。**只有产物文件已落盘而清单未勾选，才是真的漏评审**。否则会误把"还没做到"当"漏评审"，卡死正常续学。

4. **Phase 8 独立触发**不受此流程约束（"考我一下"直接进 Phase 8，见该阶段说明）。

### Phase 0：确认对象与范围

先向用户确认（不要跳过；Phase 8 独立触发时无需经过本阶段）：

1. **讲解对象类型**（`module` / `commit` / `pr` / `change`）：**通常可从用户措辞直接判定，不必单独问**：

   | 用户措辞信号 | 对象类型 |
   |---|---|
   | "这个模块 / 这块代码 / 这个包 / 这个目录" + 代码路径 | `module` |
   | "这个 commit / 这次提交 / {sha}" | `commit` |
   | "这个 PR / MR / !123 / 这个合并请求" | `pr` |
   | "这批改动 / 我改了这些还没提交 / A 版本到 B 版本之间" | `change` |
   | 给了路径但同时在说"这次改动" | **追问一句**："想听这个模块本身，还是这次对它的改动？" |

2. **目标**：
   - 模块 → 路径或目录名（用户未指定时用 `list_dir` 让其选择）。
   - 变更 → commit sha / PR 号 / diff 范围（用户未指定时用 `git log --oneline -20` 列出让其选择）。
3. **知识范围**（三选一，可多选）：
   - `通用`：该模块用到的语言特性、框架、算法、设计模式、协议等**跨项目通用**知识 → 讲解时引用权威外部文档。
   - `专用`：仅在本项目 / 本模块成立的概念、约定、状态机、业务规则、模块间耦合。
   - `两者都含`。
   - **默认**：若用户未明确选择，自动设为 `两者都含`，并在大纲中标注"默认范围，可调整"。
4. **学习目标**：用户想达成什么。目标决定讲解深度：
   - `读懂`（**默认**）：概览级，重在理解"它是什么、怎么工作、数据怎么流"。
   - `改造`：在读懂基础上，额外产出 **"改造风险点 + 建议切入点"** 小节（附在最终文档末尾），标注哪些部分改动风险高、哪些可安全重构。
   - `评审`：在读懂基础上，额外产出 **"潜在问题清单 + 改进建议"** 小节（附在最终文档末尾），按安全性 / 性能 / 可维护性 / 可测试性分类列出（详见 Phase 7 评审维度清单）。

   > **变更类只支持 `读懂`**：变更讲解默认回答"这次改动做了什么、为什么、影响谁"。用户想要"这次改动有没有问题 / 该不该合" → **转 `code-review`**，不在本技能内扩目标（详见「与相邻 skill 的分工与路由」）。

**问题交互规则**：Phase 0 共 4 个问题，其中 **目标**（第 2 项）为必答项，其余 3 项均有默认值——**讲解对象类型通常可从措辞直接判定，不必单独占用一轮提问**。若用户跳过某项，直接使用默认值并在大纲中标注。

将对象与范围写进 `00-*.md` 顶部（模块类写 `00-能力大纲.md`，变更类写 `00-变更大纲.md`），全程每个讲解点用 `[通用]` / `[专用]` 标签区分。

### Phase 0.5：分批判断（大模块自动拆分 · 仅 `module`）

> 变更类不走本阶段——变更的"分批"由 diff 本身的文件数决定，分组规则见 Phase 2「逐处解读」。

扫描目标模块：
- 统计模块内文件数（`search_file` / `list_dir`）。
- **不拆分**（默认）：文件数 ≤ 20 且未命中下方任一信号 → 直接进入 Phase 1。
- **拆分**：文件数 > 20，**或**命中以下任一信号（**文件数不是唯一判据**）：

  | 信号 | 为什么它也是拆分理由 |
  |---|---|
  | 目录层级 ≥ 3 且跨子目录互相引用 | 一次讲完会来回跳转，读者建立不了连贯认知 |
  | 存在 ≥ 2 个职责明显无关的子目录（如同时含 `auth/` 与 `report/`） | 讲完一个再讲另一个没有递进关系，不如分开 |
  | 单文件 > 1000 行 | 单文件也要按职责切段讲，否则细节淹没结构 |

  > **20 是经验值不是定律**：它标记的是"AI 一次上下文能吃下多少、读者一次能消化多少"的量级。命中上表信号时即使 ≤ 20 也该拆；反之模块虽大但高度同质（如 30 个同构的 DAO 文件）、且用户明确说"一起讲"，也可以不拆。

- 命中拆分条件时执行：
  1. 用 `list_dir` 列出目录树，按以下优先级识别逻辑子模块：
     - **优先级 1 — 目录层级**：子目录直接作为子模块边界（如 `module/core/`、`module/utils/`）。
     - **优先级 2 — 命名约定**：同一前缀的文件归为一组（如 `order_create_*`、`order_cancel_*`）。
     - **优先级 3 — 依赖关系**：用 `search_content` 搜索 `import`/`require`，将高度内聚的文件聚为一组。
  2. 产出拆分方案（Markdown 表格：子模块名 / 包含文件 / 一句话职责），提交用户确认（可修改）。
  3. **用户拒绝拆分时**：回退到不拆分的路径——跳过子模块独立处理，直接进入 Phase 1，但在 `00-能力大纲.md` 顶部标注 `⚠️ 模块较大（{N} 文件），用户选择未分批讲解，部分内容可能不完整`。
  4. 用户确认后，每个子模块独立走一遍 Phase 1–6，产物写入 `.teach/{module-slug}/sub-modules/{sub-slug}/`。**子模块默认走精简路径**：Phase 1 / 2 / 3 / 7 必做（大纲 / wiki / 正确性核对 / 子模块最终文档），**Phase 4–6 仅在该子模块是核心链路（含状态机 / 异步 / 复杂数据流）时才做**——子模块不是独立交付物，每个都完整走 7 个阶段会让大模块讲解产出 7×N 份文档。
  5. 全部子模块完成后，在 `.teach/{module-slug}/` 根目录产出 **汇总版** `00-能力大纲.md`（全局视角）+ 最终文档，整合各子模块要点。
  6. **汇总完整性检查**（必须执行）：
     - 确认所有子模块已在汇总版中被提及（逐个勾选）。
     - 确认子模块间依赖关系图覆盖所有跨子模块的 `import`/`require` 边。
     - 确认每个子模块的"一句话职责"与其 Phase 1 大纲一致。
     - 检查不通过时，在汇总文档顶部标注 `⚠️ 完整性待补` 并列出缺失项，提示用户是否需要补充缺失内容。

> 分批讲解时，汇总版大纲和最终文档必须包含：各子模块间依赖关系图（Mermaid `graph TD`）+ 各子模块一句话职责 + **讲解路线**（子模块的讲解 / 阅读顺序——依赖图给的是关系，路线给的是顺序，两者不可互替）。

### Phase 1：大纲

按讲解对象回答不同的问题。

#### A. 模块类 → `00-能力大纲.md`

回答"这个模块**能做什么**"。分两段：**先让人进得来（A-1），再讲清它长什么样（A-2）**。

**A-1 开场 · 零术语可达（本阶段第一优先级）**：

| 要素 | 要求 |
|---|---|
| **一句话本质** | ≤ 2 句，**不出现任何技术名词**——"把 X 从 A 变成 B"。写不出这句 = 还没真正读懂这个模块 |
| **处境对照** | "不这么做会怎样" vs "这么做换来什么"，**带量化锚点**（多慢 / 多大 / 多贵）。不写"提升性能""增强可扩展性"这类空话 |
| **直觉主图** | **一张 SVG**（规范见 [reference.md](reference.md) §6「大纲直觉主图」）。一图只回答"它解决什么问题"；**图上不出现技术名词**，术语下沉到图注 |
| **特性卡** | 3–5 条，每条固定句式 **特性 → 换来什么 → 代价是什么**。只写优点的特性卡是宣传稿，不合格 |

> **处境必须来自真实证据**（README / 模块职责 / docstring / issue / 调用方），不得为了"好懂"编造业务场景——人话化是**表达要求**，不是编造许可（见「代码讲解叙事骨架 · 核心理念」）。
>
> **A-1 与 A-2 的关系**：A-1 讲"为什么需要它"，A-2 讲"它是什么"。A-2 的术语首次正式登场时须回指 A-1 的说法（见认知阶梯「术语引入纪律」）。

**A-2 骨架信息**：

- 对外职责边界：做什么、不做什么
- 公开能力清单（入口 / 公共 API / CLI / 事件），每条一句话职责
- 关键抽象（核心类 / 函数 / 类型）及其角色 + **术语对标**（项目自造词 → 业界标准叫法 + 代码位置，见「格式规范」）
- 子模块 / 包划分（路径 + 一句话职责）
- **讲解路线**：本次按什么顺序讲——模块类 = 各阶段文档的阅读顺序；分批 / 拆子模块时 = 子模块的先后顺序。让读者一眼知道"这份材料分几块、先读什么"。**不写进度状态**（进度以产物文件是否落盘 + `00-评审清单.md` 为准，防双源）

#### B. 变更类 → `00-变更大纲.md`

回答"**这次改动动了什么**"：
- **变更全景**：改了哪些文件、各文件增删行数、改动类型归类（修复 / 重构 / 新增 / 优化 / 配置 / 格式化 / 测试）
- **改动分组**：按**意图**分组，**不是按文件**——同一意图的改动常散在多个文件，按文件讲会打碎逻辑
- **一句话概括**：不写代码细节也能懂的改动描述
- **规模标注**：涉及文件数 / 增删行数 / 是否跨模块（作为判断强度与风险的输入）

> **格式化 / 依赖升级这类"噪音改动"单独归组并一笔带过**（如"另有 12 个文件仅格式化，无语义变更"），不逐文件展开——它们会淹没真正的语义改动。

**两类共同**：产出文件顶部写 Phase 0 确认的对象与范围，格式见 [reference.md](reference.md) §1「通用格式规范」。

**落盘时三件事（缺一不可）**：

1. **初始化 `00-评审清单.md`**：按计划评审节点**一次性占位全部条目**（`- [ ]`）。模块类占位：大纲评审 + 解读评审 + 收尾评审；**变更类精简模式只占位 2 条评审**（`01-逐处解读` 评审 + 收尾评审）**+ 1 条质量闸门**（`02-正确性核对`）——模板见 [reference.md](reference.md) §8。
   > **占位是防漏的唯一机制**：评审只写成流程文字，长流程里必漏（历史教训）。占位了 = 断点续学时可被发现并补做。
2. **大纲评审**：按「course-reviewer 评审执行规则」评审本阶段产物（教学法视角单实例），P0 清零后**勾选 `00-评审清单.md` 对应条目**。**变更类精简模式跳过本项**（清单只占位 2 条评审 + 1 条质量闸门，不含大纲评审）。
3. **产物卫生**：这是全流程首个落盘点，执行「产物卫生」第 2 条——提示 `.teach/` 已生成、是否提交由用户决定。**提示只此一次**，后续阶段不重复（第 1、4 条是全程约束）。**知识范围含 `[通用]` 时先执行 Phase 1.5**（它同样会落一个新目录），使这一次提示覆盖 `.teach/` 与 `.web-index/` 两者。

### Phase 1.5：外部官方文档收集（知识范围含 `通用` 时执行）

> **为什么**：`[通用]` 部分要引用权威外部文档（语言 / 框架 / 协议官方站），而「引用纪律」要求链接须真实存在、拿不准宁可不附。**先建索引再开讲**，Phase 2 的引用与 Phase 3 的核对才有稳定的取址入口——边讲边找链接是编造链接的根源。
>
> **"执行"不等于"一定建"**：本阶段是**进入判定**——按下面第 2 条走 `web-index` 的规模判断，判定不建（如只为一处 API 查一次）就一句话说明后回到直接 fetch，不产出索引。
>
> **跳过条件**：知识范围为纯 `专用`（只讲本项目特有概念）→ 跳过；**变更类精简模式** → 跳过（一次性解读，查阅次数通常 ≤ 2）。
>
> **变更类完整模式**：Phase 1 时通常看不出要不要查外部站，**升级为完整模式后（进入 Phase 4 之前）回到本阶段补做**——意图权衡常要对照框架官方的变更说明 / 迁移指南。

1. **列出文档站清单**：按 Phase 1 大纲里标注 `[通用]` 的知识点，定出要参考的官方站（1–3 个）。例：模块用了 SQLAlchemy → `docs.sqlalchemy.org`；涉及某协议 → 该协议 RFC / 官方站。**非官方来源（博客 / 教程站）不进索引**。
2. **按 `web-index` 做准入与执行**（**判定规则不在此复制**，见 `use_skill("web-index")` 的「被其它 skill 集成 · 规模判断」）：
   - 已在 `.web-index/INDEX.md` 在册 → **消费模式**，查表即可，**不重建**
   - 未收录 → 模块讲解跨多个阶段且档案会被反复查阅，天然满足"≥2 次查阅" → **建造模式**，按其阶段 0–5 执行
3. **scope 按模块实际用到的部分收窄**：不要整站建（文档站动辄上千页）。例：只用了 ORM 的查询 API → 收窄到查询 / 会话相关分支。
   > **中间产物须登记**：抓取脚本会把候选链接表写到 `temp/web-index-{slug}-map.md`。**创建即记下路径**（见「产物卫生」第 3 条），收尾时按记录清理。
4. **落点与提示**：索引落在**项目根**（与 `.teach/` 同级），结构由 `web-index` 管。
   > **时序（必读）**：本阶段须**在 Phase 1 第 3 件事（产物卫生首次提示）之前**执行——首次落盘提示只此一次，若先提示了 `.teach/` 才生成 `.web-index/`，结果只能是"漏提示"或"违约重复提示"二选一。**同一次提示里说明两个目录**（"`.teach/` 与 `.web-index/` 已生成于项目根目录，是否提交由你决定"）。
   > **不代为提交、不擅自加 `.gitignore`**（本技能不动用户的忽略规则）。
5. **登记**：在 `00-能力大纲.md`（变更类 `00-变更大纲.md`）的「外部文档索引」小节记一行（站点 / slug / 范围 / 生成日期 / 索引文件路径）。**断点续学时先读这一节**，否则新会话的 AI 不知道有索引可用。

**后续用法**：

- Phase 2 写 `[通用]` 知识点的外部引用时，**先查索引的「我要…」列拿 URL**；索引没有才现场查，确认常用后回补一行
- Phase 3 正确性核对中涉及"外部文档结论"的条目，同样走索引定位页面
- **索引只解决"去哪一页"**：版本 / API 变更的时效性仍按引用纪律标注 `核查于 YYYY-MM`
- **写前核对不可省**：索引只解决"去哪一页"，**"那一页现在怎么写的"要另外核对**——凡断言外部事实（版本 / 默认值 / API 行为 / 推荐做法）的 `[通用]` 内容，动笔前按「格式规范 · `[通用]` 结论按官方文档核对」执行并留痕

### Phase 2：解读

按讲解对象回答不同的问题。

#### A. 模块类 → `01-代码wiki.md`

回答"这个模块**长什么样**"：
- 项目结构（目录树 + 各子模块职责，标注路径）
- 关键类 / 函数清单（名称 + 路径 + 职责 + 行号区间）
- 依赖关系：内部依赖 / 外部库 / 被谁依赖
- 设计模式、不变量、关键约束
- **回扣大纲 A-1**：大纲「特性卡」的每条特性在此落到具体实现（谁实现 / 在哪 / 怎么实现）；术语首次正式登场时回指直觉层的说法
- 涉及**通用知识**时，补充一段该通用概念的简明讲解并引用权威来源；涉及**专用知识**时，说明它在本项目为何这样设计
  > **引用纪律**：外部文档链接须真实存在，**拿不准宁可不附、不得编造**；**链接优先取自 Phase 1.5 建的网页索引**，不凭记忆写、不按路径规律拼；涉及版本号 / API 变更 / 时效性结论时标注核实月份（`核查于 YYYY-MM`）；无把握的结论标注置信度，不得以确定语气陈述。详见 [reference.md](reference.md) §2「知识范围标注约定」。

#### B. 变更类 → `01-逐处解读.md`

回答"**每处改动具体改了什么**"。按 Phase 1 的意图分组逐组展开，组内逐 hunk 写：

| 要素 | 要求 |
|---|---|
| **before → after** | 关键代码前后对照（**只贴关键片段，不贴整文件**），标 `file://路径#Lx-Ly` |
| **改了什么** | 语义变化，不是逐字符描述（"给 X 加了重试分支"而非"新增 12 行"） |
| **为什么改** | `[显式]`（message / 注释写明）或 `[推断]`（**必须给推断依据**） |
| **影响谁** | 波及的调用方 / 消费方（**须实证**，见「取证纪律」第 3 条）；判定不了写"待确认" |
| **范围标注** | `[通用]` / `[专用]` |

**分组规则**：一组 = 一个意图。**单组改动跨 > 5 个文件时**，先给该组"改动模式"一句话总结，再挑 2–3 个代表文件展开，其余列表带过——逐文件平铺会让读者抓不住模式，只看到一堆 diff。

**评审**：按「course-reviewer 评审执行规则」评审本阶段产物：
- **模块类完整模式 → 双实例**（教学法视角 + 新人视角）
- **变更类精简模式 → 单实例**（教学法视角）。本阶段是变更讲解的核心交付物，**精简模式下也不可跳过**
- P0 清零后**勾选 `00-评审清单.md` 对应条目**

产出 `01-代码wiki.md`（模块类）或 `01-逐处解读.md`（变更类）。

### Phase 3：正确性核对（质量闸门）

**这是本技能的质量闸门，不可跳过。**

回读实际代码，逐条校验 Phase 1–2 的结论：
- `已确认`：结论与代码一致
- `存疑`：代码证据不足，需标注"待用户确认"
- `有误`：结论与代码矛盾 → **必须修正前面文件**，并在 `02-正确性核对.md` 中记录"原结论 X → 修正为 Y（来源：file://...）"

存在 `有误` 或 `存疑` 时，先修正再继续后续阶段；绝不允许带着错误结论进入功能推演。

**修正级联规则**：修正了某个阶段的产物后，需检查后续已产出的文件是否引用了被修正的结论——若引用了，则重新核对该引用条目并更新。具体：
- 修正 `00-*.md`（Phase 1）→ 重新检查 `01-*.md`（Phase 2）中引用大纲结论的条目。
- 修正 `01-*.md`（Phase 2）→ 重新检查后续所有文件中引用该结论的条目（通常为 Phase 4–6）。
- 交叉引用检查完成后，在 `02-正确性核对.md` 底部追加 `级联检查记录` 小节，列出被更新的文件及修改项。

**变更类的核对重点**（在通用清单之外额外逐条核对）：

| 核对项 | 说明 |
|---|---|
| **diff 解读准确性** | 每条 before → after 对照是否与实际 diff 一致（**最常见的失真是把 diff 读反或看漏 hunk**） |
| **意图标注诚实性** | `[显式]` 是否真的写在 message / 注释里？没写却被标成 `[显式]` 就是编造 |
| **影响面有实证** | 每条"影响谁"是否有 `impact` / grep 取证？凭感觉写的降级为"待确认" |
| **噪音改动未误判** | 被归为"仅格式化"的文件是否真的无语义变化（有时格式化里夹着真改动） |

> **变更类的核对是回读 diff + 回读调用方代码**，不只是回读当前文件——diff 本身通常已经被 Phase 2 读过一遍，这里要校验的是"解读是否正确"，不是"改动是否存在"。

产出 `02-正确性核对.md`，含核对清单表（结论 / 判定 / 代码来源）。**两类对象共用同一文件编号与格式。**

### Phase 4：推演 / 影响面

#### A. 模块类 → `03-功能推演.md`

基于已校验的事实，**推演真实运行时行为**：
- 核心流程如何串起来（正常路径）
- 边界 / 异常路径、隐式行为、副作用
- 与其它模块的交互点
- 设计意图推断（为什么这样写）
- **性能与复杂度**（当满足以下任一条件时必填）：
  - 代码中存在显式循环（`for`/`while`/`do`）、递归调用、或大数据集处理（如 `.map`/`.filter`/`.reduce` 链式调用 > 3 层）
  - 代码注释或变量名暗示性能关注（如 `cache`/`pool`/`throttle`/`debounce`/`lazy`/`batch`）
  - 用户学习目标为"评审"
  - 分析内容：
    - 核心算法的时间 / 空间复杂度（用大 O 表示）
    - 热点路径（循环 / 递归 / 频繁调用点）
    - 资源消耗（内存、I/O、网络）
    - 与替代方案的性能对比（如有）
  - 若不满足条件，在推演中加注"性能分析：本模块不涉及算法密集型操作，跳过详细分析"。

产出 `03-功能推演.md`，关键流程配 Mermaid 流程图；复杂度对比曲线、分步执行过程等复杂图用独立 SVG 文件（选型规则见 [reference.md](reference.md) 的 SVG 图表规范）。

#### B. 变更类 → `03-影响面分析.md`（完整模式）

回答"**这次改动影响了谁**"。**这是变更讲解中最容易凭空想象的部分，故每项都必须有实证**：

| 维度 | 内容 | 取证方式 |
|---|---|---|
| **直接调用方** | 被改符号（函数 / 类 / 导出）的调用点清单 | GitNexus `impact` / `context` + `search_content` |
| **间接影响** | 契约变更的下游（数据结构 / 返回格式 / 错误码 / 事件 payload） | grep 字段引用 + 源码确认 |
| **数据流影响** | 数据生命周期是否变化（新增/删除字段、改变落库时机、调整异步顺序） | 沿调用链读源码 |
| **兼容性** | 是否破坏向后兼容（签名 / 默认值 / 枚举 / 配置项） | 逐一比对 before/after 签名 |
| **未覆盖区域** | 哪些调用方没被本次改动同步更新（**潜在的遗漏点**） | 调用方清单扣除已改清单 |

> **判定不了就写"待确认"，不猜。** 影响面猜错比不写更糟——读者会基于错误的影响面做决策。
>
> **禁用方式**：不得仅凭 diff 中出现的文件名推断调用方。diff 只显示被改的文件，调用方在 diff 之外。

### Phase 5：定位与意图

#### A. 模块类 → `04-应用场景.md`

- **应用场景**：真实可用该模块的场景（含何时**不该**用它）
- **解决的问题**：它解决的核心痛点是什么
- **待解决问题 / 风险**：已知局限、技术债、潜在 bug、扩展点

产出 `04-应用场景.md`。

#### B. 变更类 → `04-意图与权衡.md`（完整模式）

回答"**为什么这么改、有没有别的路**"：

| 要素 | 要求 |
|---|---|
| **显式意图** | commit message / PR 描述 / 代码注释里写明的动机，原文引用 |
| **推断意图** | 从 diff 反推的动机，**逐条给推断依据**，并标注 `[推断]` |
| **备选方案** | 这个改动至少还有哪些常见替代做法（≥ 1 个），为什么没走那条路 |
| **付出的代价** | 这个方案的成本（复杂度 / 性能 / 可维护性 / 兼容性） |
| **什么情况下该改选** | 未来什么条件变化后，现在的选择就不再合适 |

> **两条红线**：① 把推断当显式写（编造作者动机）；② 只讲"这么改多好"不讲代价（退化成改动说明书，失去教学价值）。

### Phase 6：数据流 / 风险收尾

#### A. 模块类 → `05-数据流.md`

分析数据在模块内的生命周期：
- 入口 → 变换 → 出口 的完整链路
- 状态流转（有状态机时配 `stateDiagram`）
- 异步流（队列 / 定时 / 回调）
- 数据一致性 / 丢失风险

产出 `05-数据流.md`，至少 1 张 Mermaid 图（流程图 / 时序图 / 状态图），图后紧跟 `图表来源`；密集依赖拓扑等复杂图可用独立 SVG 文件，同样紧跟 `图表来源`。

#### B. 变更类 → `05-风险与待确认.md`（完整模式）

| 区块 | 内容 |
|---|---|
| **风险点** | 本次改动引入或暴露的风险，按 兼容性 / 性能 / 并发 / 数据一致性 / 可维护性 分类；每条写清"什么情况下会触发" |
| **需向作者确认的问题** | 解读过程中无法从代码判定的问题清单（**这是交付给用户的行动项，不是 AI 的自问自答**） |
| **解读置信度** | 哪些结论是确定的（有代码证据）、哪些是推断的（标 `[推断]`） |

> **只描述，不裁决**：发现明显问题写进风险点，**不写"这个改动不该合"**——判定权在 `code-review` 与用户。用户若追问"那这次改动有没有问题"，转 `code-review`。

### Phase 7：最终完善文档

汇总全部阶段为最终文档（**Markdown 唯一主载体，不使用 HTML**）：

- 产出 `06-最终文档.md`
- Mermaid 以代码块形式嵌入（` ```mermaid `），GitHub 或支持 Mermaid 的 Markdown 阅读器可直接渲染
- 复杂图（结构 / 过程 / 对比类，如复杂度曲线、递归栈展开、密集依赖拓扑）用独立 SVG 文件（入 `assets/`，kebab-case 命名），`![说明](./assets/xxx.svg)` 引用；选型规则见 [reference.md](reference.md) 的 SVG 图表规范
- 渲染环境不确定（聊窗讲解 / 终端 / 纯文本传阅）或需逐节点挂 `文件:行号` 批注时，结构类信息（子模块依赖、数据流主干、状态流转链）可用 **🕸 文字树**兜底（渲染无关）；**只作兜底，不替代上述 Mermaid / SVG 默认**，最小语法与示例见 [reference.md](reference.md)「5.1 🕸 文字树」
- 用 Markdown 表格、引用块（提示框）增强讲解，顶部放目录锚点，便于跳转回顾
- 版本控制友好，跨平台可渲染

**学习目标附加内容**（仅 Phase 0 选了"改造"或"评审"时生成）：
- `改造`：在最终文档末尾追加 `## 改造风险点与建议切入点`，按以下维度分析：
  - **高风险区**：改动可能影响全局行为的核心逻辑（如状态机、中间件链、事务边界）。
  - **中风险区**：改动可能影响局部行为的辅助逻辑（如工具函数、格式化、日志）。
  - **安全重构区**：纯内部实现、无外部依赖、可自由重构的部分（如重命名、提取函数、优化循环）。
  - **建议切入点**：推荐的改动顺序和最小影响路径。
- `评审`：在最终文档末尾追加 `## 潜在问题清单与改进建议`，按以下 **4 维度** 分类列出（每个维度至少给出 3 个检查点）：
  - **安全性**：输入校验、权限检查、注入风险、敏感数据泄露、依赖安全。
  - **性能**：热点路径、N+1 查询、不必要的重计算、内存泄漏风险、异步阻塞。
  - **可维护性**：命名清晰度、单一职责、重复代码、魔法数字、注释质量。
  - **可测试性**：是否可独立测试、依赖是否可 mock、边界条件覆盖。

Markdown 与 Mermaid / SVG 模板见 [reference.md](reference.md)；完整示例见 [examples.md](examples.md)。

**汇总完整性检查**（必须执行，逐项确认）：

- [ ] 所有已产出阶段的内容均已纳入（**精简模式下确认被跳过的阶段是有意跳过，不是漏做**）
- [ ] 各阶段产物的 `章节来源` 与 `图表来源` 全部保留，未因汇总而丢失
- [ ] `[通用]` / `[专用]` 标注在汇总后仍然完整
- [ ] 大纲的**一句话本质 / 直觉主图 / 特性卡**已进入最终文档（这是全篇门面，丢失则读者进不来）
- [ ] （模块类）大纲的**讲解路线**已进入最终文档（读者要知道这份材料分几块、按什么顺序读）
- [ ] 分批讲解时：所有子模块已纳入，子模块依赖图覆盖跨子模块引用边
- [ ] 变更类精简模式时：`01-逐处解读.md` 的核心 before→after 对照已提炼进最终文档（**最终文档是精简模式的门面，不能只剩大纲**）
- 检查不通过时，在文档顶部标注 `⚠️ 完整性待补` 并列出缺失项

**收尾三件事**（缺一不可）：

1. **收尾评审**：按「course-reviewer 评审执行规则」评审 `06-最终文档.md`（双实例；变更类精简模式单实例），P0 清零后**勾选 `00-评审清单.md` 的收尾条目**。
2. **接力提示词**：在最终文档末尾写入下一阶段接力提示词（模板见下），并在对话中原样贴给用户。
3. **产物卫生**：① 按记录清理本轮产生的中间草稿 / 临时验证脚本（第 3 条：**只删记录在案的文件**，精确路径删除，无记录的不删）；② 若本轮**实际运行过脚本 / 测试**，顺带确认是否产生了依赖目录 / 缓存 / 日志，有则按第 1 条例外追加忽略规则。两条均无则跳过，不必提及。

> **可选追加（仅 `module` 类）**：**伴读分支**——询问用户是否把教程要点就地注释到核心代码。流程：工作区干净检查（不干净则不创建）→ `git switch -c teach/{module-slug}` → 加教学注释（无标记、就近分散；`git diff --numstat` 删除数必须为 0）→ 在 `06-最终文档.md` 追加「伴读分支」记录（元信息，不需重跑评审）。**AI 不代为提交。** 详见「伴读分支」小节。

**接力提示词模板**（写入产物末尾 + 对话中均使用）：

````markdown
## 🚀 下一步

> 复制下面这段文字发给 AI，即可继续（无需重新描述上下文）：

```
{模块类}：我刚看完 {module-slug} 的讲解材料，档案在 .teach/{module-slug}/。
请就 {具体方向：某子模块 / 数据流 / 边界行为} 再深入讲一层。

{变更类}：我刚看完 {commit/PR} 的讲解，档案在 .teach/{类型}/{slug}/。
请补充 {具体方向：影响面中待确认的项 / 完整模式的影响面与意图分析}。
```
````

> 变更类**精简模式**下，接力提示词默认指向"升级到完整模式（补 Phase 4–6）"——用户说"再详细点"即可继续，无需重新描述。

### Phase 8：知识点对齐 · 选择题（可选）

若用户想快速验证对模块「关键 / 易混淆知识点」的掌握度（或说"考我一下""出几道题""知识点对齐""测一下易混淆点"），进入本阶段。以**选择题**为主、自动评分、按模块落盘成绩、跨轮次追踪进步。可**独立触发**，不必重跑完整 teach。

**模块解析（独立触发时必做）**：
- 用户已在本会话教过某模块 → 沿用该模块路径与 `{module-slug}`。
- 用户指定模块路径 → 直接用。
- 用户未指定（如首次直接说"考我一下"）→ 用 `list_dir` 让用户选择目标模块。
- `{module-slug}` 取模块目录名的 kebab-case：绝对路径取最后一级目录名（如 `/a/b/order` → `order`）。
- **目录初始化**：若 `.teach/{module-slug}/` 不存在（首次独立触发），创建该目录及 `quiz-history/` 子目录，无需执行 Phase 0–7。**若这是 `.teach/` 目录的首次创建，同样须执行「产物卫生」第 2 条提示**（独立触发跳过了 Phase 1，不能因此漏掉落盘提示）。

> **变更类同样可触发本阶段**（用户看完某次改动讲解后想自测）：出题输入改为该变更的 `01-逐处解读.md` / `04-意图与权衡.md`，落点在该变更目录下的 `quiz-history/` 与 `07-知识点对齐.md`，其余机制完全一致。

**出题输入**：
- 优先复用 `.teach/{module-slug}/` 下已有产物（大纲 / wiki / 数据流），提取关键概念、状态机分支、近似 API、业务规则、边界值等易混点。
- 若产物缺失，做一次轻量代码探索（`list_dir` / `search_content` / `read_file`）提取上述易混点。

**历史读取（新一轮必做）**：
- 读取 `.teach/{module-slug}/quiz-history/INDEX.md`（不存在则为首轮）。
- 提取历史累计**答错的知识点**列表。

**出题策略（错题巩固 + 新题互补）**：
1. **优先巩固错题**：本轮 ≥ 1/2 题目来自历史答错的知识点——换表述 / 换角度重测，不直接照搬原题。
2. **补充新题避免重复**：其余题目从尚未考过 / 未错过的知识点生成，且与历史题目不重复。
3. **首轮**：直接基于易混点生成。
4. **去重依据（强制）**：以「知识点标签 + 题干核心实体」作为题目身份指纹，与 `quiz-history/` 下所有 round 文件的指纹比对，命中则视为重复、必须换题。
5. **状态不一致兜底**：若 `INDEX.md` 与 `round-NN.md` 缺失其一，仅以现存文件为准（缺 INDEX 则本轮按首轮处理、仅依赖 round 文件去重；缺 round 文件则仅按 INDEX 的错题知识点巩固）；不报错、不中断。

**题目生成规则**：
- **题型与评分**：
  - **单选题**：4 选项（1 正确 + 3 干扰），答对得 1 分。
  - **多选题**（须明确标注「多选」）：选项 ≥ 4，用户作答为组合（如 `A,C`）；**全对才得分**（不支持部分给分），避免歧义。
  - 分数 = 答对题数 / 总题数（正确率 %）。
- **易混淆聚焦（强制）+ 可溯源**：干扰项必须来自**真实存在的**近似概念 / 易混 API / 近似行为 / 状态机分支 / 边界值，禁止凭空编造的明显错项；每个干扰项的"迷惑来源"必须**引用真实代码出处**（`file://路径#Lx-Ly`），未找到真实依据的干扰项不得入题。
- **覆盖**：必含 1 题核心流程、1 题关键约束（不变量 / 业务规则），其余从易混点选取。
- **总题数**：3–6 题（按模块规模或用户指定）。
- **可选主题聚焦**：用户可指定"只考状态机混淆点"等，缩小出题范围。

**交互与评分**：
- 逐题展示（`Q1:` 题干 + `A/B/C/D` 选项），用户作答后**即时反馈**：
  - `✅ 正确` / `❌ 错误（正确答案 X）`
  - 解析重点讲清"这个易混点为什么容易错"及正确项依据（引用 `file://路径#Lx-Ly`）。
- 自动判定，无需人工。分数 = 答对题数 / 总题数（正确率 %）。
- 全部答完后输出**本轮成绩单**：正确率、各知识点掌握情况、**与上一轮对比**（正确率变化、错题收敛数）。

**落盘（按模块）**：
- **轮次号 NN**：读取 `quiz-history/` 下现有最大 `round-NN` 后 +1，零填充两位（如 `round-03.md`）；同一会话内连续出题必须重新读取，避免覆盖上一轮。
- 写入 `.teach/{module-slug}/quiz-history/round-NN.md`，含：日期、轮次号、题目（题干 + 选项 + 正确答案 + 知识点标签 + 易混点来源）、用户作答、是否正确、本轮正确率。
- 同步更新 `.teach/{module-slug}/quiz-history/INDEX.md`：追加一行（轮次 / 日期 / 正确率 / 错题知识点），便于快速回看趋势。
- 每次新轮次覆盖更新 `07-知识点对齐.md`（最新一轮题目 + 成绩单）。
- **进步对比口径**：`与上一轮对比` 优先按「相同 / 相近知识点标签」的正确率变化与错题收敛数呈现；若两轮题目集差异过大导致总体正确率不可比，需明确标注"本轮题目已更换，正确率为难度调整后的参考值"，避免误导。

**再考一轮**：用户说"再考一次""来新一轮"时，回到「历史读取」步骤，结合历史出题。

> 此阶段仅在用户要求时触发，不自动执行。

## 代码讲解叙事骨架

> 这是比「格式规范」更高优先级的**结构约束**。格式规范是排版层（cite 块、章节来源、图表选型），叙事骨架是结构层——决定讲解从哪里开场、怎么推进、在哪收束。

### 核心理念

**不当说明书，当讲解。** 不要从目录树、类清单或定义开场，而从"这段代码要解决什么问题"开场——读者记住的是问题与解法，不是清单。

> **与 topic-teach 五幕的关键区别（勿照搬）**：通用知识教学需要**造场景**建立直觉（"小王想理财但不知从何开始"）；**代码讲解有真实代码可依，硬造场景反而稀释信息密度并引入编造风险**。故代码讲解用**问题驱动叙事**——问题取自代码与变更记录本身（README / 注释 / commit message / PR 描述 / 调用方），不是编出来的。

### 五幕结构（两类对象通用）

| 幕 | 名称 | 核心任务 | 做什么 | 不做什么 |
|---|------|---------|--------|---------|
| 一 | **处境** | 这段代码为什么存在 | 从 README / 模块职责 / commit message / PR 描述取**真实问题**：模块类答"它承担什么职责、谁在用它"；变更类答"改之前是什么问题、为什么现在必须改" | 不从目录树或类清单开场；不编造业务场景；不写"本模块是一个…"这类定义式开场 |
| 二 | **冲突** | 为什么朴素做法不行 | 从代码里的 workaround、边界处理、历史缺陷痕迹、被放弃的替代方案**取证**复杂性 | 不为戏剧性夸大难度；确实无冲突就明说"这段逻辑本身不复杂"并直接进第三幕 |
| 三 | **拆解** | 核心机制逐层展开 | 按认知阶梯推进（见下），每层回扣第一幕的问题 | 不先讲底层实现再讲上层用途（禁止倒序）；不一次性甩出所有术语 |
| 四 | **验证** | 用真实证据回扣 | 模块类：**沿真实调用链走一遍执行路径**；变更类：**before → after 行为对照**（改之前会怎样、改之后会怎样） | 不用假想示例；不脱离真实代码做抽象推演 |
| 五 | **定位** | 它在全局中的位置与边界 | 与相邻模块 / 系统的关系、适用与不适用场景、已知局限 | 不只总结"本文讲了什么"就结束 |

> **第四幕是代码讲解比通用教学强的地方**：有真实调用链和真实 diff 可依，验证是有证据的，不是举例说明。

### 认知阶梯（第三幕内部）

> **第一幕另有一层前置：直觉层。** 它不在第三幕的递进序列里，只负责"让读者进得来"——见下表首行。

| 层 | 目标 | 内容 |
|---|---|---|
| **直觉层**<br>（**仅第一幕**） | "不懂术语也知道它在解决什么问题" | ① 一句话本质（把 X 从 A 变成 B，**零术语**）② 处境对照（不这么做会怎样 vs 这么做换来什么，**带量化锚点**）③ 一张**零术语主图**（SVG）④ 这套写法的**特性卡**（特性 → 换来什么 → 代价是什么） |
| 感知层 | "见过这个东西" | 对外长什么样（入口 / 签名 / 配置） |
| 概念层 | "理解这个东西" | 为什么存在、解决什么问题 |
| 机制层 | "搞懂它怎么工作" | 内部流程、关键算法、状态变化 |
| 实操层 | "能动手用它" | 怎么调用、常见配置、调试手段 |
| 定位层 | "知道它在全局的位置" | 与谁交互、边界在哪 |

**禁止倒序**：不得先讲机制再讲概念，不得先讲实操再讲原理。每层须以前一层为前提。

**直觉层只用于第一幕，不贯穿全篇**：它的存在是为了降低入口门槛，不是为了把整篇变成科普——第一幕之后即转入感知层，术语正常登场。

**术语引入纪律**：术语首次出现时给一句"人话"解释；**首次正式登场的术语应回指直觉层的说法**（如"物理索引——就是第一幕里说的'按天装订的那一册'"），避免直觉与术语各说各话、读者手里握着两套词汇对不上；**讲透后对标业界**——项目自造叫法给出业界标准叫法 + 代码位置（见「格式规范 · 术语对标」），读者要能拿着这个词去搜文档、看懂开源实现。不得在铺垫之前甩术语（新人视角评审的重点检查项，见专项维度 D）。

### 直述模式退出机制

并非所有代码都适合叙事。以下情况采用**直述模式**，在产物顶部标注"本文采用直述模式，原因：{理由}"：

| 不适合叙事的对象 | 原因 | 直述模式怎么写 |
|---|---|---|
| **配置 / 常量 / 枚举清单** | 无问题可讲，硬造问题反而干扰查阅 | 表格 + 简要说明 |
| **纯 CRUD / 样板代码** | 无设计冲突，叙事显得小题大做 | 结构说明 + 关键点提示 |
| **参考手册类**（API 列表 / 错误码表） | 学习目标是查阅而非理解 | 按功能分类列表 |
| **用户明确只要速查** | 目标就是快速定位 | 直接给清单 |
| **变更类：纯格式化 / 依赖升级 / 文案修改** | 无语义变更 | 一句"本次为 X 类改动，无语义变更"即可，不套五幕 |

> **判定规则**：主 agent 在 Phase 1–2 生成前判断。若采用直述模式，评审时新人视角的"叙事弧"检查降级为"结构完整性"检查——内容是否完整有序，而非是否是故事；**A-1 零术语开场按适用性裁剪**——「一句话本质」仍要求（它不依赖叙事），「处境对照」与「直觉主图」对配置 / 常量 / 参考手册类对象可不做。

## 格式规范

所有 `.md` 产物遵守 [reference.md](reference.md) §1「通用格式规范」（**SSOT**）。此处只重复六条最易漏的硬约束：

- `章节来源` **必须带 `file://` 与行号区间**，且行号须覆盖被论述代码的实际跨度（`Lx-Lx` 单点不合规）
- 任何 Mermaid / SVG 图后紧跟 `图表来源`
- **每张图必须带一句话读图指引**（"看图：左边是……右边是……差别在于……"）——**没有指引的图等于没画**，大纲的零术语直觉主图尤其如此
- **术语对标**：项目自造词 / 关键术语**首次正式登场后**，给出**业界标准叫法**（若存在；确无则写"本项目特有"）与**在本项目出现在哪**（`file://` 位置）；同一件事有**多种做法 / 策略**时给「项目叫法 ｜ 业界标准叫法 ｜ 代码位置 ｜ 代价」四列对照表。**编造业界叫法按 P0 判**（读者会拿它去搜文档、看开源实现、跟别的团队沟通——编造等于把人带沟里）；**无可对标的术语时本节可省略**（不写空表）。与 `use_skill("topic-teach")` 的「术语双轨」同源——**方法论 SSOT 在其 `reference.md`「术语锚定规范」**，本条只保留模块侧差异（"在哪遇到"落在 `file://` 代码位置）；细则见本技能 reference.md §1 的「术语对标」条目
- **`[通用]` 结论按官方文档核对（写前）**：凡断言**外部事实**的 `[通用]` 内容（版本 / 默认值 / API 行为 / 推荐做法），动笔前须查官方文档核对——先查 Phase 1.5 索引（未建则现场查官方站），**有差异以官方文档为准**；产物在该 `[通用]` 段落处留痕（整篇同类可合并到顶部交代一次） `📖 通用知识已核对（核对于 YYYY-MM ｜ 来源：{站 / 页}）`。**`[专用]` 内容不走此条**（其基准是代码，走 Phase 3 正确性核对）。方法论同源：`use_skill("topic-teach")` 的「官方文档学习闸门」（SSOT）——**为什么必须写前**：AI 自认为正确、实际已被官方改掉的部分，写后扫描抓不到
- 图表背景禁用黑色或过深颜色，一律浅色背景 + 深色文字；深色仅用于元素强调（表头 / 高亮块，其上文字用浅色）

> 每个讲解点按 Phase 0 范围标注 `[通用]` / `[专用]`（标注约定与引用纪律见 reference.md §2）。

## 更多资源

- 通用格式规范（§1）、知识范围标注与引用纪律（§2）、各阶段文档骨架（§3）、最终文档模板（§4）、Mermaid 速查（§5）、SVG 图表规范（§6）、**变更讲解模板与逐处解读 / 影响面 / 意图权衡骨架（§7）**、评审清单模板（§8）、伴读分支执行模板（§9）：[reference.md](reference.md)
- 阶段产出示例与最终文档样例（含变更讲解示例）：[examples.md](examples.md)
- **评审维度定义（SSOT）**：[review-dimensions.md](review-dimensions.md)——专项维度 D（含 D8）/ E、分级与自检清单。**内联评审直接读它；委派子 agent 时随【评审维度】传入**
- 评审 agent（**可选**）：`use_agent(course-reviewer)`——未创建时主 agent 按上面的维度文件内联评审，不阻塞流程；其内置维度只是兜底骨架
- 外部官方文档的本地路由表（Phase 1.5 调用建 / 查索引）：`use_skill("web-index")`