Topic Teach

---
name: topic-teach
description: 用五幕叙事（场景引入→认知冲突→层层揭示→实操验证→体系收束）教学通用知识主题（技术/非技术域皆可），产出 Markdown 学习材料：课程制/速览双模式、大纲定稿前经教学效果推演闸门（模拟学完能否覆盖实战工作场景与理论理解）、课级应用实战与源码解析（均按需配套 · 独立成册）、结课实战项目、实战经验+排障手册+场景解法库，配双 agent 评审、数据流全链路 SVG 图、事实核查、可选自测。讲解本项目代码模块改用 module-teach。仅在用户明确指定时触发（如"教我 k8s""讲讲 ETF""给我个项目练手""考我一下"）。
---

# 通用知识教学（Topic Teach）

## 概述

**目的**：让 AI 充当"全科私教"，把学习任意知识主题这件事结构化成**可校验、渐进式、生动形象**的教学流程——从技术主题（k8s / docker / Python）到非技术主题（投资 / 理财），都能产出可反复查阅的学习材料。

**功能**：
- 双模式交付：大主题走**课程制**（多阶段大纲 → 阶段概览 → 分批知识点教学），小主题走**速览**（单篇讲透 + 延伸大纲）
- **故事化教学叙事骨架**：每课遵循"场景引入 → 认知冲突 → 层层揭示 → 实操验证 → 体系收束"五幕结构，以场景代入而非定义堆砌开场；大纲规划时同步设计故事主线，把架构/知识点拆成有情节推进的故事线
- **每课入口零术语可达**：进入细节前依次给「一句话本质 + 处境对照」（第一幕末，定性 + 动力）与「一眼全局图 + 本课地图」（第三幕首，全貌 + 路线）——**没学过本课的人应能看懂那张图**；直述模式豁免（详见「课级入口要素」）
- **术语双轨**：术语进来时降维（「术语通俗化」：人话解释 + 中英对照），讲透后对标（「行话锚定」：行业标准叫法 + 在哪遇到——配置项 / 监控指标 / 报错关键字 / 官方文档章节）；讲"多策略"的内容必配「策略-术语对照表」（详见「表现形式规范 · 术语双轨」）
- **多阶段备课制**：正式讲解前先规划「阶段 → 课 → 知识点」三层大纲（通常 2–4 个阶段 = 完整学习旅程），并随学习进度 / 目标变更 / 重点变更**动态调整**（活文档）
- **多角色主题分离（按需启用）**：主题的使用者分属职责显著不同的角色时（Redis 开发 vs 运维、MySQL 开发 vs DBA、k8s 应用开发 vs 集群运维……），主线只围绕**学习者角色**展开，次角色内容收敛为独立**子教程**（`子教程/{专项名}/`，按需学习、不进主线进度）；主线中次角色知识只做"提及级"带过（一句话 + 指向子教程）。判定信号与拆分规则见 [planning.md](planning.md) Step 1.1「多角色判定」
- **评审把关**：多阶段大纲、阶段概览、学习路径总览经 `course-reviewer` 子 agent（教学法视角）评审；**每批教学内容必须经两个 `course-reviewer` 实例以不同视角（教学法视角 + 学习者视角）独立评审**，冲突由主 agent 裁决（教学逻辑 / 准确性 / 完整性 / 格式规范 / 一致性 + 场景吸引力 / 由浅入深 / 认知阶梯 / 故事弧 / 困惑点 / 全局定位），P0 问题清零后才交付用户；**评审以 `00-评审清单.md` 为强制检查点**（事前占位待办 + 事后勾选，未勾选 = 未评审）
- **分批生成**：以知识点为最小单位，每批 3–5 个知识点生成并确认，**禁止一次性生成整个阶段的内容**，保证质量与学习节奏
- **教学效果推演闸门**（课程制大纲定稿前必做）：站在教学者角度模拟"学习者学完这套大纲"，用领域高频工作场景（日常任务 / 故障排查 / 设计决策）+ 理论理解问题构建覆盖矩阵，检验实战覆盖与理论理解是否达标——🔴 零覆盖的高频场景必须补进大纲后才能定稿（执行方法见 Step 1.2a，推演模式定义见 `review-dimensions.md` 的「教学效果推演执行方法」）
- **课级应用实战（按需配套 · 独立成册）**：**通过判定的课**配一篇应用实战（**场景 → 全貌一句话（非本课设计点到为止）→ 渐进演进：基础实现 → 它的问题 → 综合实现**），**独立落盘于 `应用实战/` 目录**——正文不在课内，课内**双位置入口**（第四幕入口块 + 文末「🧭 课程导航」区「🎯 练一练」行）跳转；判定规则见 [planning.md](planning.md) Step 1.1「应用实战判定」（**不是每课都配**——强配反而意义不大）；**`应用实战/INDEX.md` 一键跳转全部实战**（固定入口，随课程进度更新）。**每个演进一步各配一张固定 SVG「分步设计图」**（渐进式讲解的骨架：这一版长什么样、比上一版改了什么，一目了然）与**代码示例**（**不要求真实运行，但必须做正确性 review——主 agent 直接审，保证代码正确**）；目标是"会用"不是"能上生产"；与 Phase 3 结课项目、Phase 5 场景解法库的边界见「教学叙事骨架 · 应用实战」
- **源码解析（按需配套 · 独立成册 · 限库 / SDK / 框架类主题）**：**过判定的课**配一篇——针对**核心 / 常用功能**读真实库源码（为什么读它 → 功能全貌 → 源码直击 → 设计权衡 → 回扣用法），**至少 1 张图**（调用链用 Mermaid / 结构布局用 SVG）；独立落盘 `源码解析/`，课内文末「🧭 课程导航」区留入口（`🔬` 行）；判定见 [planning.md](planning.md) Step 1.1「源码解析判定」（**不是每课都配**；服务端 / 系统组件不配）；源码引用须真实（标注 `源码锚点 @ {版本}`）、**禁止编造**、教错按 P0；与「源码探索」的分界（自用求证 vs 教学讲解）见「教学叙事骨架 · 源码解析」
- **结课综合实战项目**（课程制默认必做）：全部阶段完成后产出**跨阶段整合**的实战项目——含覆盖知识点地图、≥2 个设计决策权衡、反例对照、验收清单，把散装知识点焊成整体能力（防退化成玩具 demo，复杂度有硬门槛）
- **实战经验 + 排障速查手册 + 场景解法库**：同一次生成三份互补产物——《实战经验》是**学习态**（适用边界 / 高频故障模式五段式 / 落地 Checklist），《排障速查手册》是**使用态**（按症状倒查的条件-动作表，机长 QRH 式），《场景解法库》是**设计态**（**独立成册**：`场景解法库/`——经典设计题 + 规模压力题两类场景，每道题先想后看，给**解法谱系（含代价 + 按题定制的效果对比）→ 关键代码 → 非本栈替代路线 → 推荐路径**，**每个解法各配 1 张机制图**（画清该解法的核心逻辑 + 标出它的失效点 / 代价；引擎按「图表选型」定，纯配置 / 参数类可写理由豁免）；从会用走向会设计）
- **续学闭环**：每批产物末尾附**下一批接力提示词**，用户复制粘贴即可继续学习，无需重新描述上下文
- 每个核心概念在层层揭示中配生活化类比；流程 / 结构类内容用 Mermaid，复杂拓扑 / 学习路径图用 SVG；**跨组件数据流全链路图固定用 SVG**（泳道分区 + 编号步骤 + 对象形态变化，见 reference.md「数据流全链路图规范」），用户显式要求时可经 archify 生成并由 archify-svg-export 导出（可选增强路径，见同节）
- 双轨领域适配：技术域给可运行的实操命令 / 代码，非技术域给案例推演 + "数字算给你看" + 风险提示
- **双段质量闸门**：**写前**「官方文档学习闸门」——动笔前按官方文档核对本课要讲的结论（治"自认为正确、实际已过时"的知识盲区）；**写后**「事实核查闸门」——时效敏感内容（版本号 / 行情 / 法规）按需联网核实并标注置信度，杜绝幻觉
- **源码探索（文档不足时的下沉路径 · 限库 / SDK / 框架类主题）**：被学对象是"你代码调用的库"（如 redis-py 的用法）时——新知识点 + 官方文档没写清 / 没写全，不硬猜也不省略——下沉**源码求证**（**官方测试用例优先**；只盯课程要用的核心方法 / 函数），挖出的**未文档化稳定用法**（测试覆盖的；**两类用途：求证 + 使用扩展**——既确认事实，也发现"它还能怎么用"）→ **场景联想**（有现实价值才写）→ 转「非模板化亮点」/「源码解析」素材；标注 `源码验证 @ {版本}`。**服务端 / 系统组件（Redis 本体等）不探**——文档不足改走 release notes / issue。适用对象 / 两类用途 / 三信号 / 粒度见「源码探索」小节
- **备课期预收集官方文档**：大纲定稿后按主题涉及的官方站走 `web-index`（已建则查表、未建则建索引），索引落在本教程目录 `web-index/`（不用仓库根 `.web-index/`），后续每课的「📚 官方文档」链接与事实核查都从索引取 URL，杜绝现编链接
- **以 Markdown 为主载体**；图表默认 Mermaid，复杂图用 SVG 独立文件（入 `assets/`），**不使用 HTML**
- **产物仓库卫生**：每完成一个课程单元（整课 / 实战项目 / 收尾产物）后，用 `git status --porcelain -- "{topic-slug}/"` 列出该主题目录下未提交的文件，逐条判为「✅ 要提交 / 🚫 要忽略 / ⚠️ 存疑」并输出判定表，再把 🚫 项增量追加进产物仓库根 `.gitignore`——写课过程会持续产出依赖目录、构建产物、日志等"非教学产物"文件，配「禁止忽略清单」防误伤教学产物；另清理本轮亲手创建且已登记的临时文件（只认清单，禁用 `git clean -fd`）（**细则见 [ops.md](ops.md)**）
- **基础环境准备课（技术域 · 有实操即必做）**：课程要求读者自己运行命令 / 代码时，大纲**阶段 1 首课固定为「环境准备」**——最小环境集 → 主路径 + 备选装法（Docker / 本机 / 云）→ 验证命令 → 常见安装坑，并标注"已有环境可跳过"；后续课需要额外环境时在该课课首轻量补充。**与「运行环境约定」分工**：本课管"读者装自己的环境"（教学内容），后者管"AI 跑代码的纪律"（执行规范）——判定见 [planning.md](planning.md) Step 1.1「动手环境判定」
- **运行环境约定**：讲解过程中需要**真的运行代码**（Phase 3 实战项目的 `实现/`、**4.1 机制验证的命令**、临时验证脚本）时，按「先探测 → 不污染全局 → 不擅自改用户环境」三条硬纪律执行；工具选型走优先级链（用户指定 > 项目约定 > 默认 `uv run` / `fnm exec` + `pnpm`）——**4.1 属"能跑则跑"必跑类**（判定与留痕见「4.1 的实证要求」）（**细则见 [ops.md](ops.md)**）
- **敏感信息禁入**：教程会被复制 / 分享 / 提交，正文、代码块、配置示例、日志、图表（含 SVG 图内文字与图注）、示例数据**一律不出现真实敏感信息**——真实凭据（token / 密码 / 私钥）、非公开 URL、真实 IP 与内网拓扑、个人真实信息；一律用占位符与文档专用地址（`example.com` / `192.0.2.x` / `<YOUR_API_KEY>`）替代（详见「表现形式规范」第 11 条）
- 可选知识点对齐：选择题自动评分、错题巩固、跨轮次追踪进步

**使用场景**：
- 系统学习一个新领域："教我 k8s""从零开始学 Python""理财入门"
- 快速搞懂一个概念："讲讲 docker 网络模式""什么是 ETF"
- 学完练手与避坑："给我个项目练手""k8s 生产上常见的坑""出问题时怎么排查"
- 续学与自测："继续学 k8s""考我一下 docker 知识"

**与 module-teach 的分工**：教学对象是**本项目的代码模块** → 用 `module-teach`（证据来自代码回读）；教学对象是**跨项目的通用知识** → 用本技能（证据来自内置知识 + 联网核查）。用户只说"考我一下"未指明对象时：当前会话在讲代码模块 → 路由到 module-teach；在讲通用主题 → 本技能；无上下文 → 询问用户要考哪个。

## 教学产物落盘

**产物仓库**：所有教学产物存放于一个独立的 git 仓库（或用户指定的产物目录）。每个主题一个目录 `{topic-slug}/`，**直接放在产物仓库根目录**（`topic-slug` 取主题的 kebab-case 英文名，如 `k8s-basics`、`personal-finance`）。不使用 `.teach-topics/` 等冗余前缀。

```
{topic-slug}/
├── 00-学习档案.md               # 学习者画像 + 模式 + 知识点级进度表 + 大纲调整记录 + 评审记录（断点续学依据）
├── 00-评审清单.md               # 评审强制检查点：事前占位待办 + 事后勾选（未勾选 = 评审未完成，禁止进入下一批）
├── 01-学习路径总览.md           # 学习目标 + 全阶段总览：各阶段目标/重点一览 + 阶段依赖图（SVG）
├── 02-课程目录.md               # 书本式课程目录：按阶段列出各课 / 速览 / 手册（已编写 = 链接，活文档）
├── assets/                      # 根级 SVG 图（学习路径总览 / 课程手册引用）
├── stages/                      # 课程制模式的阶段目录
│   ├── 1-基础知识学习/           # 阶段目录名 = {阶段序号}-{阶段名称}（用名称，不用 slug）
│   │   ├── overview.md          # 阶段概览：目标 / 学习重点 / 必须掌握的知识点 + 本阶段路径图（SVG）
│   │   ├── lessons/
│   │   │   ├── lesson-01-{课名}.md     # 课文件名用中文课名（与阶段目录名一致，全程中文）
│   │   │   └── lesson-02-{课名}.md
│   │   └── assets/              # 本阶段引用的 SVG 图
│   └── 2-进阶实战/
├── 应用实战/                    # 应用实战独立目录（按需配套——过判定的课才有；课内第四幕只留入口块跳转）
│   ├── INDEX.md                 # 一键跳转索引（固定入口）：按阶段/课列出全部实战（活文档）
│   ├── assets/                  # 分步设计图（SVG，每演进一步一张）
│   └── {NN}-{课名}.md           # 编号 = 课的全局序号（01、02…）
├── 源码解析/                    # 源码解析独立目录（按需配套 · 限库 / SDK 类主题——过判定的课才有；课内文末导航区留入口）
│   ├── INDEX.md                 # 一键跳转索引（固定入口）：按阶段/课列出全部解析（活文档）
│   ├── assets/                  # 解析图（Mermaid 内嵌正文；复杂结构用 SVG 落此）
│   └── {NN}-{课名}.md           # 编号 = 课的全局序号（01、02…）
├── 子教程/                      # 多角色主题的旁支教程（planning.md Step 1.1 判定后启用；按需学习、不进主线进度）
│   └── {专项名}/                # 如「运维专项」；overview 随大纲评审落盘，课文件按需生成
│       ├── overview.md          # 子教程大纲：定位 / 前置（主线哪一段）/ 课清单 / 与主线的引用关系
│       └── lessons/lesson-NN-{课名}.md
├── overview.md                  # 速览模式的单篇产物（含延伸大纲 + 接力提示词）
├── projects/                    # 结课综合实战项目（课程制 Phase 3，默认必做）
│   └── {项目名}/                # 目录名用中文项目名
│       ├── README.md            # 需求 / 目标 / 覆盖知识点地图 / 运行方式
│       ├── 设计决策.md          # ≥2 个权衡点：选项对比 → 选择 → 理由 → 代价
│       ├── 反例对照.md          # "能跑但很糟"的版本 + 逐条对比
│       ├── 实现/                # 技术域：可运行代码（中文注释）；非技术域此目录改名为 `推演/`，放完整决策推演
│       └── 验收清单.md          # 自测项：怎么确认自己真的做成了
├── final-课程手册.md            # 汇总手册（Markdown，含实战项目收录）
├── 08-实战经验.md               # 学习态：适用边界 / 高频故障模式五段式 / 落地 Checklist
├── 09-排障速查手册.md           # 使用态：按症状倒查的条件-动作表（机长 QRH 式）
├── 场景解法库/                  # 设计态："新要求来了怎么设计"的设计题详解（先想后看 · 独立成册）
│   ├── INDEX.md                 # 导航：怎么用 + 场景清单（场景名 / 类型 / 覆盖知识点 / 链接）
│   ├── 场景-01-{名}.md          # 每场景一文件：先想 → 提示 → 展开解法（解法谱系 + 代码 + 替代路线）
│   └── assets/                  # 逐解法机制图（每解法至少 1 张；SVG，mermaid 内嵌正文）
├── 07-知识点对齐.md             # 最新一轮知识点对齐 + 成绩单（每轮覆盖更新，可选，命名与 module-teach 统一）
└── 知识点对齐记录/             # 历次知识点对齐记录（可选）
    ├── INDEX.md                 # 轮次索引：轮次/日期/正确率/错题知识点
    └── round-01.md
```

> **`07-知识点对齐.md` 的编号保持不变**（与 module-teach 统一约定），不因流程顺序在它之前而重编号——它是历史约定，改了会破坏跨技能一致性。**新增「文件」产物从 `08` 起编；目录类产物（`应用实战/`、`源码解析/`、`子教程/`、`场景解法库/`）不带编号**。

> 🔴 **形态即契约（勿自造目录 / 文件名）**：上面这棵树里的**目录名与文件名照写**——不自造 `practices/`、`handson/` 之类等价物，也不把 `应用实战/{NN}-{课名}.md` 写成 `README.md`。**形态跑偏时，INDEX、课内入口、图槽位会同时失去落点**，而这类错误在"内容看着没问题"的表象下极难回头（实测根因：三篇实战零图，第一层原因不是忘画图，是产物形态压根不是规范形态）。落盘前按「应用实战 · 落盘前自检」第 0 条核形态。

**载体原则**：Markdown 是唯一主载体（课程/速览/汇总均为 `.md`）。图表默认用 Mermaid（内嵌代码块）；**仅当出现 SVG 触发信号**（分支回环密、交叉连线多、需泳道/分区语义、扇入扇出大、需精确位置/方向控制）或属于**学习路径 / 阶段依赖总览图**时，改用 SVG 独立文件（入 `assets/`，kebab-case 命名，如 `learning-path-overview.svg`）。**不使用 HTML**。

每写完一个批次 / 阶段文件，在对话中给一句摘要（本批要点 + 文件链接）+ **下一批接力提示词**，不要一次性把全文甩进对话。

## 产物仓库卫生 + 运行环境约定 → 见 `ops.md`

> ① **产物仓库卫生**（.gitignore 维护 + 临时文件清理）——每完成一个课程单元 / 提交产物前读；② **运行环境约定**（Python / Node 跑代码的工具链纪律）——Phase 3 跑代码或临时验证脚本时读。**两节细则见 [ops.md](ops.md)**（低频内容不常驻本文件）。

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

> **维度定义 SSOT**：本技能全部评审维度（教学法视角 / 学习者视角 / 专项 A、B、C、F 维度 / 三模式执行方法 / 分级规则 / 自检清单）都在 **`review-dimensions.md`**（与本文件同目录，属"同 skill 内相对路径"，**必然可达**，不依赖子 agent 是否已创建）。
> **本文不写死维度数量**——维度以该文件为准，新增维度时本文无需同步。
> **两种用法**：① **内联评审**（默认）→ 主 agent **直接读该文件**；② **委派子 agent** → 把该文件全文作为 **【评审维度】传入**——子 agent 内置的只是**兜底骨架**，细则以本技能文件为准。

所有评审节点统一按此规则执行。course-reviewer 支持**三模式**（教学法视角 `pedagogy` / 学习者视角 `learner` / 教学效果推演 `rehearsal`，`rehearsal` 仅用于大纲评审），由主 Agent 通过【评审模式】字段指定。

### 评审节点与模式

| 评审节点 | 模式与实例数 |
|----------|-------------|
| **大纲评审**（Step 1.2） | **先推演后评审，两步都不可跳过**——先委派 1 个实例（`rehearsal`，即教学效果推演），按推演结论修订大纲后，再委派 1 个实例（`pedagogy`）评审定稿 |
| 阶段概览 / 路径总览评审 | 只委派 1 个实例（`pedagogy`） |
| **批次内容评审**（含随课的实战 / 解析文件） / 速览评审 | **必须委派 2 个实例**（`pedagogy` + `learner` 各 1），独立评审 |
| **结课实战项目 / 实战经验与排障手册 / 场景解法库评审**（收尾专项） | **必须委派 2 个实例**（`pedagogy` + `learner` 各 1），独立评审；叠用对应专项维度（A / B / C）。**场景解法库须逐场景评**（每个场景独立过一遍 C1–C12，不合并成一轮；评审前逐场景占位，Phase 1 不预占位） |
| **源码解析评审**（随对应课一并） | **必须委派 2 个实例**（`pedagogy` + `learner` 各 1），独立评审；叠用专项维度 F |

### 执行步骤

1. **可用性检查**：评审前确认 `course-reviewer` 子 agent 是否可用（通过 `use_agent(course-reviewer)`）。
2. **已创建** → `use_agent(course-reviewer)`，**按上表委派**，须在输入中指定【评审模式】与【评审维度】（【评审维度】= 本技能 `review-dimensions.md` 全文）。
3. **未创建** → 二选一，**默认走"直接评审"，不阻塞教学流程**：
   - **直接评审（默认）**：主 agent 直接以 course-reviewer 的角色定位与对应评审维度执行评审。
     - **大纲评审时**：主 agent 先按 `review-dimensions.md`「教学效果推演执行方法」内联推演（场景提取 → 覆盖矩阵 → 分级），修订大纲后再按「教学法视角维度」执行一轮（pedagogy **全部维度**）评审。
     - 批次内容评审时，主 agent 先以教学法视角执行一轮（pedagogy **全部维度**），再以学习者视角执行一轮（learner **全部维度**），输出两份独立意见。
     - **收尾与专项产物评审（实战项目 / 经验 / 手册 / 场景解法库 / 源码解析〔随批次〕）**：两个视角均须**叠用 `review-dimensions.md` 的对应「专项维度」逐条核查**（A 实战项目 / B 经验手册 / C 场景解法库 / F 源码解析）——仅凭 pedagogy + learner 的通用维度会漏掉复杂度门槛、证据纪律与源码真实性这几类 P0 检查点（**内联时主 agent 必须主动读该文件**；委派时它随【评审维度】一并传入）。
     - **内联模式独立性约束**：主 agent 内联评审时，学习者视角不得走过场——**必须逐项输出 learner 全部维度的完整评审表**（每维度至少 1 条意见或"无问题"），不得省略。主 agent 同时扮演生成者 + 两个评审者 + 裁决者四重身份，独立性最弱，须以完整输出补偿。在 `00-学习档案.md` 评审记录的「评审方式」标注「主 agent 内联（子 agent 未创建，独立性受限）」，并提醒用户"可创建独立 course-reviewer 子 agent 获得更独立的评审视角"。
   - **提醒创建**：若用户希望先建 agent，提示"course-reviewer 子 agent 尚未创建，可按 create-sub-agent 规范创建"；用户同意则调用 `create-sub-agent` 创建（**维度取本技能 `review-dimensions.md`**，按 create-sub-agent 规范连同维度一起写进 agent 定义），创建完成后回到正常委派流程。
4. **评审结论**：无论何种方式，评审结论均记入 `00-学习档案.md` 的「评审记录」表（P0 清零才放行）。
5. **评审清单强制检查点**：`00-评审清单.md` 是唯一可验证的**待办勾选**检查点（与学习档案「评审记录」表分工：清单管"待办勾选"，档案管"结论摘要"）。Phase 1 落盘时按已规划的阶段/课**占位**全部评审节点（`- [ ]`）；每批内容评审完成且 P0 清零后，**必须回到清单勾选对应条目**（`- [x]`）。**未勾选条目 = 评审未完成**，是断点续学时发现漏评审并补做的依据。

### 双模式冲突处理

两个实例（或主 agent 内联的两轮评审）的评审意见可能冲突：
- 如教学法视角说"知识点齐全 P0=0"，学习者视角说"第三幕认知跳跃 P0=1"
- **由主 Agent 自行裁决**：主 Agent 以自身判断决定最终采纳哪些意见
- 在 `00-学习档案.md` 评审记录的「意见摘要」中标注"双模式冲突，主 Agent 裁决：{裁决理由}"

## 工作流程

### 内容路由（按需加载——先看这里再动手）

| 时机 | 读什么 |
|------|--------|
| **每批写课（主流程）** | **本文件**：Phase 2 + 教学叙事骨架 + 表现形式规范 + 双段闸门 + 断点续学 |
| 开课 / 规划或调整大纲 | [planning.md](planning.md)——Phase 0-1 + 四个判定 + 大纲活文档 |
| 收尾（课时讲完） | [wrapup.md](wrapup.md)——Phase 3 实战项目 / Phase 4 手册 / Phase 5 三产物 / Phase 6 |
| 提交产物 / 清理 / 跑代码 | [ops.md](ops.md)——产物仓库卫生 + 运行环境约定 |
| 写课的格式模板 | [reference.md](reference.md)——单课模板 / 各产物模板 |
| **写应用实战 / 源码解析篇（随课产物）** | [reference.md](reference.md)「应用实战文件与索引」/「源码解析文件与索引」——**逐槽位套模板**（含分步设计图槽位，**不得删槽**） |
| 自评 / 评审维度 | [review-dimensions.md](review-dimensions.md) |
| 看成品长什么样 | [examples.md](examples.md) |

> **为什么拆分**：主文件原 1255 行，而每批写课其实用不到收尾 / 卫生 / 备课细则——拆出低频大块后主文件约 600 行（**每批写课加载量减半**）；拆出的文件按上表**按需读取**。

复制此清单并跟踪进度：

```
任务进度：
- [ ] Phase 0：确认主题与学习者画像
- [ ] Phase 0.5：模式判定（课程制 or 速览）
- [ ] Phase 1 备课：一次性生成多阶段大纲（阶段→课→知识点 + 故事主线；含四个判定：多角色 / 动手环境 / 应用实战 / 源码解析）→ **教学效果推演（Step 1.2a，必做闸门）** → course-reviewer 评审（教学法视角，Step 1.2b）→ 落盘（路径总览 + 阶段概览 + 骨架；技术域含「环境准备」课，多角色主题含子教程规划，按需配套含实战 / 解析 INDEX 骨架）→ **Step 1.4 外部官方文档收集（课程制，含判定）**
- [ ] 课程制：Phase 2 分批次生成（每批 3-5 知识点：按五幕叙事骨架生成 → 双 agent 评审 → 确认 → 落盘）
- [ ] 速览：按五幕叙事骨架生成 overview.md（双 agent 评审）
- [ ] 每批**动笔前**：官方文档学习闸门（不可跳过，含课首「📖 文档核对」留痕；文档不足 → 源码探索下沉）
- [ ] 每批产出后：事实核查闸门（不可跳过）+ 双 agent 评审 + 更新进度表与大纲 + 附下一批接力提示词
- [ ] Phase 3：综合实战项目（课程制默认必做：跨阶段整合 + 设计决策 + 反例对照 + 验收清单）
- [ ] Phase 4：课程手册汇总（含实战项目收录）
- [ ] Phase 5：实战经验 + 排障速查手册 + 场景解法库（一次生成三份，学习态 + 使用态 + 设计态）
- [ ] Phase 6：知识点对齐 · 选择题（可选）
```

> 讲解一律基于 AI 内置知识 + 按需联网核查，**不得编造不存在的 API、命令、数据或案例**。时效敏感结论必须走事实核查闸门。

### Phase 0-1：开课与备课 → 细则见 `planning.md`

> 画像确认（Phase 0）/ 模式判定（Phase 0.5）/ 备课与四个判定（Phase 1：多角色 / 动手环境 / 应用实战 / 源码解析）/「大纲是活文档」——**全部细则见 [planning.md](planning.md)**。开课 / 规划或调整大纲时先读它（写课会话不需要）。

### 断点续学（跳过 Phase 0 的入口）
**断点续学**：用户说"继续学 XX"时，跳过 Phase 0：先在**产物仓库根** `list_dir` 列出已有主题目录，与用户口语主题做模糊匹配（如"继续学 k8s"匹配到 `k8s-basics/`）；命中唯一目录则先看 `02-课程目录.md` 课程目录（已编写 = 链接）快速定位，再读 `00-学习档案.md` 进度表 + **「外部文档索引」小节** + `01-学习路径总览.md` 最新大纲 + `00-评审清单.md`（**先看大纲调整记录与评审记录，确认结构是否已变；并检查评审清单是否有未勾选条目——有则说明上一批评审被漏，先补评审再续学**）。

**续学落点判定**（按序判断，命中即停）：

| # | 条件 | 落点 |
|---|------|------|
| 1 | 清单有未勾选条目，**且其对应产物文件已存在**（课文件 / `projects/` / `08-`-`09-` / `场景解法库/`） | **漏评审** → 先补做该条目的评审再继续 |
| 2 | 用户明确指名子教程（如"继续学 {主题} 的运维专项"） | → **进入子教程**：读 `子教程/{专项名}/overview.md`，按 Phase 2 同口径分批生成课文件（生成前自行占位评审条目） |
| 3 | 进度表有**非"已完成"**的知识点 | 从「当前阶段第一个未完成知识点」继续 Phase 2 |
| 4 | 知识点全部完成，但 `projects/` 不存在且未标注"用户跳过" | → **Phase 3 综合实战项目** |
| 5 | 实战项目完成（或已跳过），但 `08-`/`09-`/`场景解法库/` 任一不存在 | → **Phase 5 实战经验 + 排障速查手册 + 场景解法库** |
| 6 | 全部完成 | 询问用户想做什么（汇总手册 / 知识点对齐 / 深入新方向 / 子教程） |

> **第 1 条的判定关键是"产物是否已存在"**：清单未勾选 ≠ 漏评审——正常学到课 2 时，课 3 条目当然未勾选（还没学到）。**只有产物文件已落盘而清单未勾选，才是真的漏评审**。否则会误把"还没学到"当"漏评审"，卡住正常续学。
> **第 5 条的旧形态兼容**：若存在**旧版单文件** `10-场景解法库.md`（本机制升级为目录形态前生成的课程），**同样视为已完成、不重跑 Phase 5**——旧产物不回溯；用户主动要求时才升级为 `场景解法库/` 目录形态。
>
> **"继续学"不等于"继续听课"**：知识点讲完后还有 Phase 3 / 5 两个收尾环节。若直接回"都学完了"，就是默认跳过了它们——这正是这两个 Phase 最容易被漏掉的时刻，故在此显式判定。

命中多个或零个目录时，列出候选让用户选择，选不到则告知"未找到已有档案"并走全新流程。

### Phase 2：分批次生成教学内容（课程制）

**核心规则：禁止一次性生成整个阶段的内容。** 以**知识点**为最小生成单位，按批次推进：

**批次划分**：
- 默认**以课为批次边界**：一课的知识点 ≤ 5 个 → 一课一批；> 5 个 → 拆多批（每批 3–5 个知识点）。
- **知识点细化后按篇幅灵活调整**：每个知识点含 2–4 个关键点、按六要素展开后篇幅增大，若单批内容过重，可将每批知识点数降至 **2–3 个**，以"单轮可消化、不超长"为准。
- 批次顺序 = 大纲顺序，严格从前置到后置。

**每批六步**（顺序执行，缺一不可）：
0. **文档学习（写前必做）**：按「官方文档学习闸门」查索引 → 核对本批要讲的结论 → 修订认知并在课首留痕——**没有这一步，"生成"就是拿可能过时的内置知识在写**；核对出的差异表可直接充当本批的非模板化亮点。**文档没写清 / 没写全时按「源码探索」下沉求证**（测试用例优先；结果标注 `源码验证 @ {版本}`，有价值的用法转场景联想）。
1. **生成**：按单课模板写本批知识点正文，**必须遵循「教学叙事骨架」五幕结构**。首批在 Phase 1 落盘的课骨架上**展开正文**（骨架含课名/知识点清单/本课目标/情节定位）；若本批即一课的全部知识点 → 直接成文 `lesson-NN-{课名}.md`；若是拆批的课 → 后续批次在既有课文件末尾**追加小节**（每小节 = 一个知识点）。**本课配实战 / 解析时**：独立文件按 [reference.md](reference.md) 对应模板**逐槽位生成**（实战篇 → 「应用实战文件与索引」；解析篇 → 「源码解析文件与索引」），**模板里的图槽位不得删除**——图的落点是模板槽位，删了槽位就等于默认不画图（实测教训：三篇实战零图，根因是没套模板、图槽位根本不存在）。
2. **事实核查**：按「事实核查闸门」扫描本批的时效敏感内容、按需联网核实并标注时点（不可跳过——这是写后闸门，与第 0 步的写前核对互为两端）。
3. **代码审查 + 双 agent 评审**：本批含应用实战 / 源码解析代码示例（含该课**独立实战文件 / 解析文件**）时，**先做代码正确性 review**（主 agent 直接静态审查、**不调用 skill**、不要求运行，见「应用实战 · 代码要求」与「源码解析 · 源码引用纪律」）→ **过一遍「落盘前自检」**（实战篇 7 条 / 解析篇 4 条——产物形态、图的张数、引用语法、`assets/` 目录、链接与代码结论；**课正文自身的固定场景图在第 5 步清点**）→ 再按「course-reviewer 评审执行规则」评审本批内容（**含该课实战 / 解析文件与相应入口链接**）——**必须委派两个 course-reviewer 实例**，分别以 `pedagogy` 模式（教学法视角：内容准确性 + 格式规范 + 完整性）和 `learner` 模式（学习者视角：场景吸引力 + 由浅入深 + 认知阶梯 + 故事弧 + 困惑点 + 全局定位）独立评审。冲突由主 agent 裁决。P0 清零后**回到 `00-评审清单.md` 勾选本批条目**。
4. **用户确认**：评审 P0 清零后，对话中给一句摘要 + 文件链接 + **下一批接力提示词（原样贴，不概括）**，询问"继续下一批 / 先消化 / 调整节奏"。
5. **落盘**：用户确认继续后，更新 `00-学习档案.md` 进度表（本批知识点 → ✅ 已完成）+ **评审记录** + 更新 `02-课程目录.md` 课程目录（本批课改为可点击链接）+ 检查是否需要**动态调整大纲**（按"大纲是活文档"规则）+ 写入下一批接力提示词。
   > **落盘前固定场景清点（每批必做，30 秒）**：本课/本批该有的**固定 SVG 场景图**都在吗——**每课「一眼全局图」**（第三幕首，入本阶段 `assets/`；非直述模式）、**跨组件数据流全链路图**（命中 B-⑥）、**C 类四型**（布局 / 集合 / 对比 / 层级）、本批随课的**实战分步设计图 / 解析图**（第 3 步已过专项自检，此处只复核文件在不在）？**逐项数张数：某一项一张都没有（连 mermaid 都没有）→ 补画后才落盘**（补画的图在本批评审记录里记一句即可，**不必重开一轮评审**）。
   > **为什么单列**：固定场景此前只写了"必须用 SVG"，没写"必须画"——实测 12 课零张一眼全局图、三篇实战零张图，而事后评审一条都没查出来。**这是生成侧的最后一眼**，不依赖评审记得查图（评审是事后动作，且内联时独立性最弱）。

> **「每批六步」是批次执行顺序的单一事实源**——原「每批写完必做四件事」与之维护同一流程（双源），已合并至此（其"评审记录"一项归入第 5 步；对话摘要与接力提示词的交代归入第 4 步）。**勿再引入第二份流程清单。**

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

````markdown
## 🚀 下一批接力提示词

> 学完本批后，**复制下面这段文字发给 AI**，即可无缝进入下一批（无需重新描述上下文）：

```
继续学 {主题}。我的学习档案在 {topic-slug}/00-学习档案.md，
刚学完阶段 {X}《{阶段名}》的课《{课名}》知识点 {知识点1、知识点2…}，
请按大纲继续讲解下一批知识点。
```
````

> 接力提示词**随批次更新**，始终指向"下一批"（一课拆多批时，第二批生成后更新为指向第三批）。
> 若这是本阶段最后一批，改为"🎉 本阶段完成"提示 + 建议进入下一阶段（或先做阶段自测 / 阶段性总结）。
> 若这是**全部阶段**的最后一批，指向 **Phase 3 综合实战项目**（"课程知识已讲完，接下来做一个跨阶段整合的实战项目"），而不是就此结束——**知识讲完 ≠ 学完**。

**课程导航（上一课 / 下一课链接）**：整课完成（该课全部知识点批次写完、不再追加小节）时，在课文件末尾（接力提示词之后）追加「🧭 课程导航」区块，含上一课 / 下一课 / 返回目录三个链接（格式见 [reference.md](reference.md) 单课模板）：
- 上一课 / 下一课用课文件相对链接——同阶段直接 `lesson-XX-{课名}.md`，跨阶段 `../../{阶段名}/lessons/lesson-XX-{课名}.md`；
- **课 → 根级文件的路径（勿写错）**：`lessons/` 到根是**三级**——`../../../02-课程目录.md`、`../../../应用实战/{NN}-{课名}.md`、`../../../源码解析/{NN}-{课名}.md`；两级只到 `stages/`；
- 第一课省略「上一课」；最后一课的「下一课」改为「🎉 课程知识已讲完——接下来做综合实战项目」（链接回课程目录，**不写"本课程已完成"**——课时讲完 ≠ 学完，后面还有 Phase 3 / 5）；
- 该区块是**课级**导航，整课完成时一次写入，**不随批次更新**；拆批过程中（课未写完）不写。

**整课完成时追加一项：卫生检查**——课写完（导航区块落盘的同一时刻）执行（`.gitignore` 增量维护 + 本轮临时文件清理，流程见 [ops.md](ops.md)）。**课级一次，不每批做**。本轮既无新增残留、也无待清理临时文件则不动，也不必在对话中提及。

### 领域双轨适配（Phase 2 / 速览通用）

| 环节 | 技术域（k8s / docker / Python…） | 非技术域（投资 / 理财…） |
|------|--------------------------------|------------------------|
| 实操环节 | 可直接运行的命令 / 代码（**输出须实测**——跑不了标 `⚠️ 未实测（{原因}）`，见「4.1 的实证要求」），课末附**命令速查卡** | 案例推演（虚构人物走一遍决策）+ **数字算给你看**（如复利 / 费率对比表格） |
| 图表偏好 | 架构图、时序图、状态图（Mermaid），复杂拓扑用 SVG | 决策流程图、对比表、饼图（Mermaid `pie`），复杂决策树用 SVG |
| **综合实战项目**（Phase 3） | **可运行**的多文件工程（含目录结构、模块划分、错误处理） | **完整决策推演**（一个人物/家庭从 0 到 1 走完全流程，含取舍与后果核算） |
| **实战经验 + 排障手册**（Phase 5） | 故障模式以**日志关键字 / 报错原文**索引；排障条目给命令与检查项 | 风险以**可观测信号**索引（如"连续 3 月跑输基准""接到索要验证码的电话"）；排障条目给处置动作与止损话术 |
| **场景解法库**（Phase 5） | 场景是**设计题**（"流量翻 10 倍""数据量翻 100 倍"），解法按层给多选项 + 代价 + 递进路径 | 场景是**决策题**（"通胀""单一收入""家庭变故"），解法按目标给多路径 + 后果核算 |
| 附加义务 | 标注命令 / API 适用的大版本 | **强制**：⚠️ 风险提示 + 免责声明 + 数据时点标注（模板见 [reference.md](reference.md)） |

**高风险领域红线**（投资 / 理财 / 医疗 / 法律）：只教知识与方法论，**不给个体化建议**（不推荐具体标的 / 药品 / 操作），每篇产物含免责声明，所有数字标注数据时点。

### 速览模式

单篇 `overview.md`，为单课模板的浓缩版：**顶部速览大纲**（本次核心 + 延伸方向 + 简要路线）→ 场景引入 → 认知冲突 → 核心原理（层层揭示，含 ≥ 1 张 Mermaid 图，复杂拓扑用 SVG）→ 实操验证（含应用实战轻量版：场景 → 基础实现 → 一句话演进方向，回扣场景；含代码示例时**同做正确性 review**，分步设计图若配**须用 SVG**） → 体系收束 → 🐞 误区 → 一图总结 → 📚 官方文档（如有） → **延伸学习提示词**。同样遵循五幕叙事骨架（浓缩版）。

> **入口要素同口径**：速览同样给「一句话本质 + 处境对照」（第一幕末）与「一眼全局图」（第三幕首）；**路线职能由「速览大纲」承担**，不另加「本课地图」（单篇浓缩、一屏可见）。生成前先初始化 `00-评审清单.md`（占位「速览评审」一条），并过**官方文档学习闸门**（速览无索引 → 现场查官方页核对，同样在课首留痕）；写完过事实核查闸门 + **双 agent 评审**（按「course-reviewer 评审执行规则」执行，教学法视角 + 学习者视角，冲突主 agent 裁决，P0 清零后交付），P0 清零后**勾选 `00-评审清单.md` 速览条目**。完成后在 `02-课程目录.md` 追加一条速览链接条目，并顺带过一遍卫生检查（速览只产 Markdown + 少量 SVG，通常既无新增残留、也无临时文件）。

> **速览默认不做 Step 1.4 文档收集**：单篇只讲一个概念，查阅次数通常 1–2 次，直接 fetch 更省。**但速览升级为课程制时须回到 Step 1.4 补做**——升级后是几十批的长流程，没有索引会反复踩"现编链接"的坑。

> **速览模式不做 Phase 3 / Phase 5**：速览是一篇讲透的单点概念，综合性实战项目与领域排障手册与其篇幅、目标都不匹配。**不因"流程要求"而硬做**——改为在延伸学习提示词中给出"下一步实战建议"（见 reference.md「速览 · 延伸学习提示词」），用户据此升级为课程制后才走 Phase 3 / 5。
>
> **速览升级为课程制时，须补占位**：速览阶段清单里没有两条收尾占位（见 Phase 1.3）。若用户从速览升级为课程制，走 Phase 0 重新规划后，**必须在 `00-评审清单.md` 补上「结课实战项目」与「实战经验 / 排障速查手册 / 场景解法库」两条 `- [ ]` 占位**——否则升级后的长流程同样会漏掉这两个收尾环节，速览阶段"不占位"的正确决策反而变成升级后的漏洞。

**速览也要可续**：速览不等于一次性。`overview.md` 顶部必须有"速览大纲"（本次讲什么 + 简要路线 + 1–2 条延伸方向），末尾附**延伸学习提示词**——用户复制即可把速览升级为系统学习（或换主题继续），避免"讲完就断"。

**延伸学习提示词模板**（速览本身不做 Phase 3 / 5，故给两条路径——选第二条会先升级为课程制再走 Phase 3 / 5）：

````markdown
## 🚀 想深入？复制发给 AI

**升级为系统课程**（含结课实战项目与排障手册）：

```
我刚看了 {topic-slug}/overview.md 关于 {主题} 的速览，
想进一步学习，请按我的情况（{水平} / 目标 {目标}）把 {延伸方向} 展开成一个课程。
```

**直接要实战 / 避坑**：

```
我刚看了 {topic-slug}/overview.md 关于 {主题} 的速览，
请给我一个综合实战项目练手，或讲讲 {主题} 的实战经验、排障速查手册与场景解法库。
```
````

速览模式默认输出 Markdown（`overview.md`），不使用 HTML。

### 官方文档学习闸门（写前 · 不可跳过）

> **为什么必须在写前**：下面的「事实核查闸门」是**写后**按"时效敏感类型"扫描——它只能抓住 **AI 已经意识到"这条可能过时"** 的项。而真正的盲区是 **AI 自认为正确、实际已被官方改掉** 的部分（默认值变更、参数废弃、推荐做法翻转、机制细节调整）：AI 不会把这类内容标为时效敏感，扫描就扫不到，**错误直接出货**。根治只有一个办法——**动笔前先按官方文档学一遍本课要讲的东西：用自己的知识写，用官方文档校**。

**适用范围**：课时 + 速览（讲机制、讲结论的产物）。实战项目与 Phase 5 三产物不走本闸门（前者跑代码即验证，后者已有更严的证据纪律），按「事实核查闸门」执行。

**执行时机**：每批**动笔之前**（Phase 2「每批六步」的第 0 步）。

1. **定位页面**：查本主题 `web-index/`（Step 1.4 索引）的「我要…」列，拿到本课每个知识点对应的官方页；未建索引（速览 / 非技术域 / Step 1.4 判定不建）→ 现场检索**官方站**（不拿博客 / 教程站当依据）。
2. **带着问题学，不通读**：准备讲什么结论，就核对官方文档里的对应段落什么——默认值 / 参数名 / 行为 / 版本要求 / 推荐写法。
3. **逐条比对与修订**（三种结果各有去处）：
   - **一致** → 正常写正文（按事实核查闸门标 `核查于 YYYY-MM`）
   - **有差异**（官方已改 / 自己记错）→ **以官方文档为准改写**；差异本身价值极高（网上到处是过时教程）→ 写进课首「📖 文档核对」差异表，可直接充当本课的**非模板化亮点**
   - **查不到 / 没写全** → **先下沉「源码探索」求证**（**限库 / SDK 类主题**，见下节）；仍无法证实的，按事实核查闸门第 3 / 5 条标置信度，**不得以确定语气陈述**
4. **留痕（可检查，防"我读过了"空口）**：课首元信息加一行 `> 📖 结论已按官方文档核对（核对于 YYYY-MM ｜ 来源：{站 / 页}）`；有差异时附差异表（**≤ 3 行**，不喧宾夺主）。
5. **豁免与下沉**：无官方来源可依的**纯推论 / 设计权衡**类内容不属本闸门（走事实核查闸门标置信度）；**有文档但没写清 / 没写全**（新知识点的高发形态）→ 下沉「源码探索」求证（**限库 / SDK 类主题**，见下节），不硬猜也不省略；**直述模式的速查类不豁免**——命令 / 参数 / 状态码恰恰最需要按官方文档核对（"这张表就是规范本身"）。

### 源码探索（文档不足时的下沉路径 · 写前）

**适用对象（先判这个——不是所有主题都该探）**：

| 主题类型 | 例 | 探索 |
|---------|-----|------|
| **库 / SDK / 框架 / 工具链**（"你代码调用的对象"） | redis-py 的用法、requests、React 组件库 | ✅ **有效**——探索的就是"你调用的那部分实现"，官方测试用例围绕用法 |
| **服务端 / 系统组件**（独立运行的大型工程） | Redis 本体、MySQL、k8s | ❌ **不探究**——C / Go 大规模工程，成本与难度不匹配，"怎么用"也不藏在实现里 → 文档不足改走 **release notes / CHANGELOG / issue / 社区** |
| 非技术域 / 无源码对象 | 理财、协议标准 | ❌ 不适用 |

> **一句话判据**：**这个知识点是"你代码调用的库"，还是一个"独立运行的系统"？** 前者才探。

> **什么时候下沉**：学习闸门核对时命中**三信号**任一——**新**（知识点 / API 是近期版本新增，训练数据大概率没有）；**缺**（官方文档写得不明：只写了一半 / 参数表不全 / 行为描述模糊）；**疑**（自己对结论没把握）。命中即触发**源码求证**；**只盯课程要用的核心方法 / 函数**——不扩散、不全量读库。

**源码来源**：能本地就本地（学习环境已装的依赖——版本与学习者一致，直接可读）；否则官方仓库页面（`web_fetch` 拉取）。

**探索路径**（可靠性从高到低）：

1. **官方测试用例**（最宝藏——文档没写的用法大概率藏在测试里；测试通过 = 维护者保证该用法有效）
2. **方法签名 / 参数默认值**（定义处直接可证）
3. 注释 / CHANGELOG / issue（辅助佐证）

**两类用途（求证 + 使用扩展）**：① **求证**——文档不足时确认事实（参数是否存在 / 默认值 / 接受哪些值 / 行为分支）；② **使用扩展**——主动发现"它还能怎么用"（文档未写的用法 / 能力边界）。两者都只停在**用法层**：不做"实现原理分析"（昂贵且易错）——"**讲透**为什么这么实现"是「源码解析」的活，不是探索的。

**关键区分（挖出的东西分两类）**：

| 类型 | 判定 | 处置 |
|------|------|------|
| **未文档化的稳定用法** | 被官方**测试用例**覆盖 | 可教 → 走产出转换 |
| **实现细节 / 未定义行为** | 仅源码逻辑可见、无测试覆盖 | **不教**（可能下版本就变）；仅在解释 "why" 时提及并明确标注 |

**产出转换**：源码确认（非猜测）→ **场景联想**（这用法能解决什么现实问题？有场景价值才写）→ 落地——**「非模板化亮点」的天然素材**（"文档说 A，源码里还有 B" = 反直觉对比型）+ 可选喂给 4.2 应用实战 / **「源码解析」的素材**（该课配解析时，"使用扩展"的发现正好进解析展开讲）——**同一发现一处讲透、他处引用，不多处重复展开**；**无场景价值的纯冷知识不硬塞**。

**标注**：`源码验证 @ {版本}（{仓库 / 文件}）`——源码行为随版本变，不标版本等于埋雷。

> **边界**：探索的是**外部库源码**（第三方，为通用知识求证）≠ `module-teach` 讲**本项目代码**；本机制是学习闸门的**下沉路径**（文档能说清就不下沉），与「事实核查闸门」同属证据链（一个"文档没说的从源码找"，一个"验证文档说得对不对"）。

### 事实核查闸门（质量闸门，不可跳过）

> **与「官方文档学习闸门」的分工**：学习闸门在**写前**按官方文档校准认知（治"不知道自己不知道"），本闸门在**写后**扫描兜底并标注时点——同一件事的两端，**都不可跳过**。

每批产物（课时 / 速览 / 实战项目 / 实战经验与排障手册 / 场景解法库）写完后立即执行：

1. **扫描时效敏感内容**，类型包括：软件版本号与 API 变更、工具生态推荐（"目前主流用 X"）、价格 / 利率 / 汇率 / 行情、法规 / 税则 / 政策、统计数据。
2. **按需联网核查**：对扫描出的条目用 web 搜索核实，核实后在文中标注 `（核查于 YYYY-MM）`。**本主题已建网页索引时（Step 1.4），先查索引定位页面再 fetch**，省掉"在站内搜该看哪页"的探索。
3. **无法核实的**：标注 `⏳ 置信度：低（截至训练知识，建议自行验证）`，不得以确定语气陈述。
4. **发现有误的**：立即修正原文，绝不带着错误结论进入下一批。
5. 非时效敏感但拿不准的结论（如某机制的细节行为），同样标注置信度，宁可示弱不可编造。
6. **起源/历史事实强制联网核实**：若本课含"起源背景"（作者、诞生年份、诞生动机、演化历程、解决的历史痛点等历史事实），**必须联网核实**，即使不涉及版本号/行情等时效敏感内容——历史事实凭内置知识易记错或编造。核实后标注 `（核查于 YYYY-MM）`；无法核实的标注 `⏳ 置信度：低` 并避免以确定语气陈述作者/年份。
7. **经验 / 排障手册 / 场景解法库从严**（Phase 5 专用）："经验"与"解法"是最容易编造的内容——AI 倾向于生成"听起来合理"的故障模式、修复步骤与设计方案。故收紧三条：① 每条「症状—根因—修复」与每个「场景解法」须可溯源（官方文档 / 联网核查 / 领域公认实践）；② 拿不准的一律标 `⏳ 置信度：低`，且**不得进入排障手册**（手册只收确定项）；③ 宁缺毋滥，凑不满条目就如实写已收录数，不硬凑。

### Phase 3-6：收尾阶段 → 细则见 `wrapup.md`

> 综合实战项目（Phase 3）/ 课程手册汇总（Phase 4）/ 三产物：实战经验 + 排障速查手册 + 场景解法库（Phase 5）/ 知识点对齐（Phase 6）——**全部细则见 [wrapup.md](wrapup.md)**。课时全部讲完后读它进入收尾。

## 教学叙事骨架（故事化教学核心）

> 这是比"表现形式规范"更高优先级的**结构约束**。表现形式规范是修辞层（类比、emoji、术语通俗化），教学叙事骨架是结构层——决定每课"从哪里开场、怎么推进、在哪收束"。

### 核心理念

**不当教科书，当故事**：每课不是"定义→原理→实操"的线性堆砌，而是以场景代入开场、以认知冲突驱动、以层层揭示推进、以实操验证落地、以体系收束闭环的叙事弧。

### 每课五幕结构（课程制与速览通用）

每课的正文必须按以下五幕组织。五幕是**结构骨架**，不是机械填充——各幕篇幅按内容自然分配，但顺序不可调换、不可缺失。

| 幕 | 名称 | 核心任务 | 做什么 | 不做什么 |
|----|------|----------|--------|----------|
| 第一幕 | **起源与场景引入** | 讲来历 + 让学习者身临其境 | **（可选）先讲知识/技术的起源背景**（如何诞生、作者/团队、解决什么历史痛点，联网核实，见下方"起源背景"说明）→ 再给真实问题场景（技术域如"公司服务上线后扛不住流量"；非技术域如"小王想理财但不知从何开始"）。场景必须贴近学习者认知水平——场景本身不能比要讲的概念更难懂；收于「一句话本质」+「处境对照」（见「课级入口要素」） | 不以定义开场；不以"今天我们学习 X"开场；不造场景（场景应是真实痛点）；起源背景不喧宾夺主（控制在 2-4 句） |
| 第二幕 | **认知冲突** | 制造"为什么需要这个知识"的求知欲 | 抛出场景中的矛盾/困惑（"为什么直接做会出问题？""为什么老办法不够用？"），让学习者先困惑再求知。冲突必须真实存在于场景中，不是硬造的 | 不直接给答案；不跳过冲突直接讲原理 |
| 第三幕 | **层层揭示** | 从直觉到抽象逐层展开 | **开头先给一张零术语的「一眼全局图」**（进入细节前先看全貌），**再给「本课地图」**（分几步走、现在在哪，见「课级入口要素」），再给直觉化解释（类比 + 白话），逐步引入术语和原理。每引入一个概念都回扣第一幕的场景。知识点按"感知层 → 概念层 → 机制层 → 实操层 → 定位层"的认知阶梯排列 | 不先讲底层原理再讲上层应用（禁止倒序）；不一次性甩出所有术语；不脱离场景讲纯理论；不跳过入口图与地图直接进知识点 |
| 第四幕 | **实操验证** | 回扣场景，验证刚学的知识；实战独立成篇 | 分两部分：**4.1 机制验证**（课内）——技术域给可运行命令/代码验证第三幕讲的机制，输出回扣第一幕场景（如"你看，加了这个配置后服务扛住了流量"）；非技术域给案例推演 + "数字算给你看"。**4.2 应用实战入口块**（**配实战的课才有**，课内只留入口）——正文在独立文件 `应用实战/{NN}-{课名}.md`（场景 → 全貌一句话 → 基础实现 → 它的问题 → 综合实现；结构与边界见下方「应用实战」小节），课内给可达链接 | 实操与场景脱节（变成独立命令清单）；不回扣第一幕的问题；4.2 课内重复实战正文（应只留入口块）；实战文件展开未学知识 / 膨胀成完整项目 / 无演进（三套方案平铺） |
| 第五幕 | **体系收束** | 建立全局视角 | 回到全景，把本课知识点在整体架构/体系中的位置标出来。告诉学习者"现在你会了什么、接下来要学什么、为什么"。为下一课埋伏笔 | 只讲本课知识点就结束；不交代这课在整体中的位置 |

#### 4.1 的实证要求（能跑则跑 · 跑不了要标）

> **为什么要有它**：4.1 是"**证明机制确实如此工作**"的黑盒实证——它的全部说服力来自**输出是真的**。而既有总纲只写了"不得编造不存在的 API、命令、数据"（管**有无**），管不了**真假**：AI 按记忆写出一条"看起来完全合理"的输出，不违反任何条款，读者却会照着它判断自己跑得对不对。

**适用范围**：技术域的 **4.1 机制验证**（**速览模式同口径**——速览是单课模板的浓缩版，无独立 4.1 小标题，留痕行挂在其「实操验证」段开头）、**环境准备课的验证命令**、第三幕知识点里"运行后给输出"形态的示例（**留痕粒度 = 每课 4.1 一行**，不逐条标）。**不适用**：非技术域（案例推演）、**应用实战代码示例**（示例级，走静态正确性 review，豁免见「应用实战 · 代码要求」）、直述模式的速查表（命令本身仍受"不得编造"总纲约束，不逐条实跑）。

| 情形 | 要求 | 留痕（4.1 开头一行） |
|---|---|---|
| **本地可执行**（shell / 单行 Python、Node / 已装 CLI / 装包验证） | **必须实跑**，把**真实输出**贴进正文——不是"预期输出"的想象稿 | `> ✅ 本节命令实测于 {环境 / 版本}` |
| **跑不了**（需集群 / 云资源 / 付费 / 特定硬件 / 非本机服务 / 破坏性 / 会改用户环境 / **当前无可用执行环境**——无 shell、沙箱受限、缺工具链且按「运行环境约定」不得擅自安装） | **不硬跑**，但**必须标注**——读者有权知道这条没验证过 | `> ⚠️ 未实测（{原因}）：输出为参考示例，请自行验证` |
| **部分能跑** | **逐条标注**（能跑的实测、跑不了的标原因），不整体含糊带过 | 分条给 ✅ / ⚠️ 标记 |

> **跑之前**：按「运行环境约定」三条硬纪律执行（先探测 → 不污染全局 → 不擅自改用户环境）——**4.1 属必跑类，在这套纪律射程内**（细则见 [ops.md](ops.md)）。**跑不通不是失败**：版本差异 / 环境依赖 / 命令废弃本身就是值得讲的内容，别改成"预期输出"糊过去。
> 🔴 **留痕只声明、不证明**：`✅ 实测于` 是作者的声明，**评审无法静态验证它是否真跑过**（与「📖 文档核对」留痕同理——只证明"核过"，不证明"核对正确"）。故本条的治理目标是**让"跑没跑"可见**（消灭"未实测却长得像实测"的灰色地带），不是消灭编造；输出与实际行为明显不符仍按维度 2 既有判据处理。**无执行能力时标 `⚠️`，绝不得打 `✅`**——逼出来的一句假留痕比没有留痕更糟。
> **与「📖 文档核对」的分工**：文档核对保证结论**没过时**（写前 · 对官方），本条保证输出**是真的**（写时 · 对机器）——**查文档查不出这条命令在你机器上到底跑出什么**。两者互为两端，都不可跳过。
> **评审锚点**：`review-dimensions.md` pedagogy 维度 2「内容准确性」。

#### 起源背景（可选叙事元素，增强故事代入感）

当知识点/技术**有可考的起源**时（如 Elasticsearch、Linux、Docker 等有明确作者和诞生故事），在第一幕"起源与场景引入"中先讲它的来历，把"技术的诞生"变成故事的开场：

| 起源要点 | 说明 | 示例 |
|----------|------|------|
| **诞生背景** | 为什么会出现？当年面临什么痛点/局限 | "Lucene 索引库功能强但太复杂，普通人用不了" |
| **作者/团队** | 谁创造的？什么动机 | "Shay Banon 希望让搜索像数据库一样容易" |
| **关键转折** | 解决了什么痛点 / 击败了什么替代方案 | "把 Lucene 包成 RESTful 服务，开发者开箱即用" |
| **演进** | 现在的状态 / 重要里程碑 | "从搜索库成长为日志分析、AI 搜索平台" |

**触发条件**：仅当知识点**有明确、可考据的起源**时启用。纯概念性知识（如"什么是 HTTP 状态码"）或工具速查（如"git 命令清单"）无明确起源，不强制。
**篇幅约束**：起源背景是**背景简介**，控制在 2-4 句，不喧宾夺主——主体仍是本课知识点。若起源故事丰富且对理解主题有实质帮助，可适度展开但仍须服务于教学主线。
**真实性命门**：起源背景是**历史事实**（作者、年份、诞生动机），**必须联网核实**（见"事实核查闸门"），不得凭内置知识编造或含糊其辞。

#### 课级入口要素（每课进入细节前的入口链）

> **为什么要有它**：五幕的"从直觉到抽象"此前只在**每个知识点内部**做（六要素的「直觉建立（类比）」），是**单点粒度**的直觉。读者进入第三幕前手里仍没有"这课整体在解决什么问题、要分几步走"的图景——术语一多就迷路。**单课讲得好 ≠ 入口讲得清**，两者不能互相顶替。
>
> 入口是一条链，四件各司其职：**定性**（本质）→ **动力**（处境）→ **全貌**（图）→ **路线**（地图）。

| 要素 | 位置 | 要求 |
|------|------|------|
| **一句话本质** | 第一幕末（场景之后） | 零术语、≤ 2 句，说清本课把什么"从 A 变成 B"。写不出这句 = 本课还没定准 |
| **处境对照** | 第一幕末，紧随本质 | "不这么做会怎样" vs "这么做换来什么"，**带量化锚点**（多慢 / 多大 / 多贵 / 省多少工作量）——不写"提升性能""更方便"这类空话（与 module-teach 直觉层同源要素对齐） |
| **一眼全局图** | 第三幕首（第一个知识点之前） | **固定 SVG**（入本阶段 `assets/`）；**按 [reference.md](reference.md) 单课模板的图槽位生成**（`![说明](../assets/{主题}-intuition.svg)`，lesson 在 `lessons/` 故用 `../assets/`）；一图只回答"解决什么问题、靠什么思路"；**图上零术语**（术语下沉到图注与后文）；必带一句话读图指引；图不承担结论；**不画 = 违规**（固定场景口径见「表现形式规范」第 2 条） |
| **本课地图** | 第三幕首，全局图之后 | **表格式路线清单**（不是图，**不占每课 SVG 配额**）：本质的 A→B 拆成 N 步 ↔ N 个知识点；只回答"分几步走、现在在哪"（细则见下方「本课地图」） |

- **验收口径**：**没学过本课的人应能看懂这张图**——看不懂就是画错了。
- 🔴 **处境对照的真实性**：量化锚点属事实（数字 / 耗时 / 代价）——能核实则核实；无把握时给**可观测的定性对比**并标 ⏳，**不得为凑对照编造数字**（与「表现形式规范」第 9 条真实性红线同源）。
- **三方分界（防退化雷同）**：「一眼全局图」= 课首 / **问题视角** / 零术语 / 给没学过的人；「本课地图」= 课首 / **路线视角** / 不含机制结论 / 回答"分几步走"；「一图总结」= 课末 / **知识视角** / 给刚学完的人。三者不可替代、不得雷同。
- **回指**：后文术语首次正式登场时，须回指本图 /「一句话本质」的说法（见「表现形式规范 · 术语双轨」），不出现两套词汇对不上。
- 四条硬约束细则、与 module-teach「大纲直觉主图」的同源关系见 reference.md「一眼全局图」。
- **豁免**：直述模式四件全免（见下方"五幕退出机制"）。

#### 本课地图（知识点路线 · 第三幕首）

> **为什么要有它**：课级两端都有路标（入口图管"为什么难、靠什么思路"，一图总结管"学到了什么"），**唯独知识点级没有**——读者读到第 3 个知识点时，不知道自己走到哪、还剩几步、这些点怎么拼成本课。地图就是**第三幕的行程表**。

| 项 | 要求 |
|------|------|
| **位置** | 第三幕首、「一眼全局图」**之后**、第一个知识点**之前** |
| **形态** | **表格式路线清单**（不是图，**不计入 SVG 配额**）；步骤编号与知识点一一对应 |
| **视角** | 只回答"**分几步走、现在在哪**"——不写机制、不写结论；每步的"要解决什么"用人话表述（知识点名本身允许出现，它就是后续小标题） |
| **不写学习状态** | 地图是**静态路线**；进度状态的 SSOT 在 `00-学习档案.md` 进度表，**不在地图里标"已学 / 未学"**（防双源） |

- 每步一行：`第 N 步 · {这一步要解决什么（人话）} → 知识点 N：{知识点名}`。
- **与课骨架「知识点清单」的关系**：骨架清单是**编写计划**（Phase 1 落盘），地图是**给读者的路线**（正文入口）——同一批知识点的两种用途；课范围变化时两处同步更新，**不视为双源**。
- **知识点衔接句（配套硬约束）**：每个知识点小标题下给一行 `🧭 第 N/M 步｜承接：{上一步留下的问题} → 本步：{把它解决成什么}`——把知识点从平铺列表变成**推进链**；第 1 个知识点的"承接"回指第二幕的冲突。
- **拆批的课**：地图在首批写入（一次列全 N 步，后续批次逐条兑现）；范围变化时与入口图同步重绘（见「大纲是活文档」）。
- **速览模式**：不单独写地图，路线职能由「速览大纲」承担（单篇浓缩、一屏可见）。
- **豁免**：直述模式不写（参考性 / 速查类无"路线"可讲）。

#### 应用实战（按需配套 · 独立成册）

> **为什么要有它**：4.1「机制验证」回答"这个机制确实如我所讲"，但学完一课，学习者常答不上"**这玩意儿现实里拿它干什么、怎么一步步用起来**"——"应用"这层是空的（Phase 3 综合项目只收口一次、门槛高，够不着每课）。**值得配的课**配一篇应用实战（判定见 [planning.md](planning.md) Step 1.1「应用实战判定」——**强配反而意义不大**）：**跟着作者走一遍"从幼稚到像样"的演进，把知识点焊进真实用法**。

| 项 | 要求 |
|----|------|
| **位置与落盘** | 正文**独立成篇**：`应用实战/{NN}-{课名}.md`（NN = 课的全局序号）——**按 [reference.md](reference.md)「应用实战文件与索引」模板逐槽位生成**（两张分步设计图槽位**不得删**）；**目录名 / 文件名照规范写，不另起形态**（`应用实战/{NN}-{课名}.md` + `应用实战/assets/` + `应用实战/INDEX.md`）——**形态跑偏（如自造 `practices/README.md`）则 INDEX、双入口、图槽位全部无从落地**，这是最难回头的一类错（实测根因）；课内**双位置展示**（均为跳转链接，**不重复正文**）：第四幕 **4.2 入口块** + 文末「🧭 课程导航」区的 **🎯 练一练行**（首行——学完课就地可跳，不必回翻）——课管教学、实战册管动手，课内 ↔ 实战册 ↔ INDEX 三向互达 |
| **索引（一键跳转）** | `应用实战/INDEX.md`：按阶段/课列出全部实战（课链接 / 场景 / 覆盖知识点 / 实战链接）；**Phase 1 随大纲落盘建骨架**（列出计划条目，未编写 = 纯文本），**随后随每课完成同步更新**（与 `02-课程目录.md` 同节奏）——是"通览全部实战"的固定入口 |
| **结构** | **场景**（一句话：本课知识点在什么现实场景里用得上）→ **全貌一句话**（完整方案还需要哪些**非本课**设计，点到为止、不展开）→ **渐进演进**（打底两跳：**基础实现**（能跑但幼稚）→ **它的问题**（1–3 条具体问题）→ **综合实现**（把本课知识点组合起来，即"被问题逼出来的下一步"）；中间还有值得演示的坑可加一跳「改进实现」；**跳到综合即止，不得只有基础一段**——只有一段就退化成 4.1 了） |
| **图（固定 SVG · 分步设计图）** | **每个演进阶段各配一张**（入 `应用实战/assets/`，命名 `app-step{N}-{主题}.svg`〔N = 演进步序〕）——每张画**该步方案的设计形态**（组件构成 / 连接 / 数据流），**并在图上标注本步的优化点 / 变化**（新增元素高亮 + 一句"本步解决了什么"）——"比上一张图多了什么"要**一目了然**；**渐进式讲解的骨架就是这组图**，代码与文字挂在图上；**不计入每课 SVG 配额**；表达要求见 reference.md「应用实战分步设计图」，每张图后必带一句话读图指引（首图讲"这是什么"，后续图讲"比上张多了什么、为什么"） |
| **代码** | 演进**每一步**都配代码示例（只给思路 / 伪代码 = 半成品）；**不要求真实运行**（示例级，区别于 Phase 3 的可运行性 P0），但**必须做正确性 review**（主 agent 直接审，保证代码正确）——三条细则见下方「代码要求」 |
| **完成标准** | **"会用"而非"能上生产"**：不要求工程完整性（不谈监控 / 高可用 / 多文件工程）、不展开未学知识（超纲部分只在「全貌一句话」里点名）、篇幅克制——**量化软锚点：不超过对应课篇幅的 1/3**，超出即考虑移入阶段小项目（演进思路 + 关键代码/命令，**不是**完整项目） |
| **收口** | 结尾给一句 `🎯 会用标志：{做到什么就算学会}`（如"能独立写出带探针的 Pod YAML 并说清每段为什么需要"） |
| **数量** | **不是每课都配**（先过「应用实战判定」）；配则默认 1 个场景/篇，密度高、应用面广的课可 1–3 个（篇内多场景小节） |
| **非技术域** | 改为**决策演进**：基础做法 → 它的问题（数字算给你看）→ 综合方案（组合本课知识点，如"活期 → 跑不赢通胀 → 分层配置"） |
| **速览模式** | **不独立成篇**（速览无边目录结构）：轻量版留在 `overview.md` 内——场景 → 基础实现 → 一句话问题 + 一句话演进方向 |

**生成与评审**：**判定为「配」的课**，其实战篇与课**同批生成、同批评审**（`00-评审清单.md` 占位写作"阶段 X·课 Y《课名》（含应用实战）"，不单独占位；**同课两者都配时**合并写作"（含应用实战 / 源码解析）"）；官方文档学习闸门与事实核查闸门照常；**代码正确性 review 先于双 agent 评审**（见「每批六步」第 3 步）。

**落盘前自检（7 条 · 逐条过完再交付）**：

> **为什么要有它**：实战篇是"随课的附属产物"，写完课容易顺手带过；而评审是**事后**动作、且内联时主 agent 独立性最弱——实测三篇实战**零张图、连 `assets/` 目录都没有**，事后评审（跑了 13 条断言）一条都没查图。**自检是生成侧的最后一道闸**，不依赖任何人记得。

| # | 检查项 | 不合格形态 |
|---|--------|-----------|
| 0 | **产物形态正确**：文件落 `应用实战/{NN}-{课名}.md`，配套 `应用实战/assets/` 与 `应用实战/INDEX.md` | **自造目录 / 文件名**（如 `practices/README.md`）——形态错则 INDEX、双入口、图槽位全部无从落地，**是最难回头的一类错** |
| 1 | **分步设计图 N 张**（N = 演进步数：基础 + 综合，中间跳有则加） | **0 张**（= 没画）；张数 < 步数（缺步）；用 mermaid 顶替 |
| 2 | **图入 `应用实战/assets/`**，命名 `app-step{N}-{主题}.svg` | 图放进阶段 `assets/`；命名不符；**有引用无文件** |
| 3 | **引用用图片语法** `![说明](./assets/xxx.svg)` | 写成 `[xxx.svg](…)` 链接式——**图不渲染**，且"文件存在"类检查查不出来 |
| 4 | **每张图有读图指引 + 变化标注** | 无指引；后续图无"比上张多了什么"（高亮 / 虚线框 + 本步解决了什么） |
| 5 | **链接层**：`INDEX.md` 本课条目已更新（纯文本 → 链接）+ 课内双位置入口可达（4.2 入口块 + 文末「🎯 练一练」行，路径三级 `../../../应用实战/`） | INDEX 漏收；任一入口缺失或链接断 |
| 6 | **代码**：每条演进都有代码示例 + **正确性 review 已做且结论入评审记录** | 只有思路 / 伪代码；review 结论未入记录 |

> 第 0 条管**形态**（跑偏则全盘皆错），第 1–4 条管**图**（本次事故点，也是固定 SVG 场景的落地检查），第 5–6 条管**链接与代码**。**七条（0–6）全绿才算这篇写完**——不是"写完正文等评审挑"。

**边界（四条，勿混）**：

| 相邻机制 | 它做什么 | 与应用实战的分界 |
|----------|---------|-----------------|
| 4.1 机制验证 | 验证"机制确实如此工作"（命令输出证明） | **验证的是机制，应用的是场景**——4.2 回答"知识点能拿现实做什么" |
| Phase 3 结课实战项目 | 跨阶段整合、多文件工程、高门槛（合奏） | 4.2 是**单课内**的应用（单练）；**Phase 3 不因 4.2 降门槛、4.2 不因 Phase 3 可省** |
| Phase 5 场景解法库 | 「先想后看」——**横向解法谱系**（多方案对比 + 代码落地，设计训练） | 4.2 是「**跟着走**」——**纵向演进**（作者演示"基础 → 问题 → 综合"，会用教学）；**一个"自己想"、一个"带着走"，方向相反** |
| 「非模板化亮点」的 mini 案例 | 每课至少一处"跳出模板"的内容 | 4.2 天然可**兼任** mini 案例型亮点，但**不强制绑定**（亮点仍可落在报错日志 / 反例 / 数字表） |

> **真实性**：演进中的"问题"必须来自真实工程实践（不硬造），拿不准标 `⏳ 置信度：低`——与「非模板化亮点」的真实性红线同源。
> **评审锚点**：结构与边界 → `review-dimensions.md` pedagogy 维度 4；演进可读性 → learner **L4**；**代码正确性 → 主 agent 直接 review**（见下方「代码要求」）。

**代码要求（应用实战 · 三条）**：

1. **每步都有代码**：演进的每一步（基础 / 综合，含中间跳）都给代码示例——只写思路不给码 = 半成品。
2. **不要求真实运行**（区别于 Phase 3 实战项目的可运行性 P0）：示例级代码，不强制跑通、不强制锁定依赖版本；但**须语法正确、逻辑自洽、符合最佳实践**——不做"看着像代码"的伪代码或占位式敷衍。
3. **必须保证代码正确（直接 review，不调 skill）**：生成后**由主 agent 直接静态审查**——过一遍正确性 / 安全 / 与所讲知识点的一致性，确保代码正确、逻辑自洽；结论并入本批评审记录。**发现与知识点矛盾的写法按 P0 处理**（把读者教错）。范围 = 应用实战文件的代码示例（4.1 命令的准确性仍由事实核查 + pedagogy 维度 2 把关）。

> **豁免**：直述模式课（参考性 / 纯定义 / 速查类）不写 4.2（同入口要素豁免口径）；**子教程课不配 4.2**（按需学习、不进主线进度——边界见 reference.md「子教程」的内容边界）。

#### 源码解析（按需配套 · 独立成册 · 限库 / SDK / 框架类主题）

> **为什么要有它**：课讲到"这个功能怎么用"，学习者常止步于"照文档用"——**不知道它内部怎么实现**，"为什么这么设计 / 为什么有这个限制 / 坑的根因在哪"就答不上来；使用层的熟练撑不起深理解。**值得配的课**配一篇（判定见 [planning.md](planning.md) Step 1.1「源码解析判定」——**限库 / SDK / 框架类主题**，服务端 / 系统组件不配）：**带学习者读一段真实的库源码，把"用法"焊到"实现"上**。

| 项 | 要求 |
|----|------|
| **位置与落盘** | 正文**独立成篇**：`源码解析/{NN}-{课名}.md`（NN = 课的全局序号）——**按 [reference.md](reference.md)「源码解析文件与索引」模板逐槽位生成**（图槽位不得删）；课内**入口**：文末「🧭 课程导航」区一行 `🔬 源码解析`（配解析的课才有；不开幕内入口——阅读时机是"学完之后"）——课内 ↔ 解析篇 ↔ INDEX 互达 |
| **索引（一键跳转）** | `源码解析/INDEX.md`：按阶段/课列出全部解析（课链接 / 解析的功能 / 覆盖知识点 / 解析链接）；**Phase 1 随大纲落盘建骨架**（列出计划条目，未编写 = 纯文本），**随后随每课完成同步更新**（与 `02-课程目录.md` 同节奏） |
| **结构** | **为什么读它**（认知引入：一个值得深挖的问题，如"为什么 `cached_property` 第二次访问就不进 `__get__` 了？"）→ **功能全貌**（一张图：它在哪、调用链怎么走）→ **源码直击**（关键片段节选 + 逐段讲解"为什么这么写"）→ **设计权衡**（为什么这么做 / 不这么做会怎样）→ **回扣用法**（所以用的时候：注意 X / 可以 Y / 别 Z——解析不悬空） |
| **图（至少 1 张）** | 按既有「图表选型」信号判定——调用链 / 控制流通常 **Mermaid**；命中 A/B 类信号或属 C 类内容（数据结构 / 内存布局 / 对象关系）则 **SVG**（入 `源码解析/assets/`，命名 `src-{NN}-{主题}.svg`）；每张图后带一句话读图指引；**不计入每课 SVG 配额** |
| **源码引用纪律** | **必须真实**：节选**真实源码**（标注 `源码锚点 @ {版本}（{仓库 / 文件}）`）；**可简化节选但必须标注**（如"节选，省略参数校验"）——不得把简化版伪装成原文；**禁止编造源码**（与"官方文档链接不得编造"同级红线） |
| **完成标准** | 聚焦 **1–2 个核心 / 常用功能**（不铺全库、不做"逐行考古"）；目标是**看透这一个功能**（理解机制 / 理解坑 / 理解边界），不是"读懂整个库"；篇幅克制（**软锚点：不超过对应课篇幅**） |
| **收口** | 结尾给一句 `🔬 看透标志：{能说清什么就算读懂}`（如"能说清 `cached_property` 的缓存为什么写在实例 `__dict__` 里"） |
| **数量 / 速览模式** | **不是每课都配**（先过判定）；配则 1 篇/课（篇内 1–2 个功能）。速览模式**不做**（无边目录结构，解析承载不了） |

**生成与评审**：**判定为「配」的课**，解析篇与课**同批生成、同批评审**（`00-评审清单.md` 占位写作"阶段 X·课 Y《课名》（含源码解析）"，不单独占位；**同课两者都配时**合并写作"（含应用实战 / 源码解析）"）；官方文档学习闸门与事实核查闸门照常；**源码引用真实性 + 讲解正确性**由主 agent 直接审（**教错 → P0**）。

**落盘前自检（4 条 · 同应用实战口径）**：① **图 ≥ 1 张**（引擎按「图表选型」定，SVG 入 `源码解析/assets/`、命名 `src-{NN}-{主题}.svg`；**0 张 = 不合格**）且引用用图片语法、带读图指引；② **源码引用真实**（标 `源码锚点 @ {版本}（{仓库 / 文件}）`，简化处已注明"节选，省略…"）；③ **课内文末「🔬 源码解析」入口行 + `INDEX.md` 本课条目已更新**；④ 收口有「🔬 看透标志」。

**边界（四条，勿混）**：

| 相邻机制 | 它做什么 | 与源码解析的分界 |
|----------|---------|-----------------|
| 「源码探索」（写前闸门） | **自用求证 + 使用扩展**（文档不足 → 查证事实 / 发现用法） | 探索是**写课人自用**的事实核查（不产出教学内容）；解析是**教给学习者**的系统讲解（独立成篇）——**一个"未知 → 已知"，一个"已知 → 教会"** |
| 4.1 机制验证（第四幕） | 跑起来看行为（命令 / 输出证明"机制确实这样工作"） | 4.1 是**黑盒实证**；解析是**白盒讲解**（读源码看"为什么这样实现"）——一个"证明它确实如此"，一个"看懂它为何如此" |
| 知识点六要素「核心原理」 | 用文字 / 类比讲机制 | 解析是**当文字讲不透时**"下沉到源码"的手段——更深一档，服务同一目标（讲透机制）；一课的对应功能讲清了就不必配解析 |
| `module-teach` | 讲**本项目代码**（代码讲解档案） | 解析讲**外部库源码**（第三方，为通用知识服务）——对象不同，不重叠 |

> **评审锚点**：判定合规 → `review-dimensions.md` 专项维度 **F**；源码真实性 / 讲解正确性 → 主 agent 直接审 + F2；图与读图指引 → F4。
> **豁免（同应用实战口径）**：直述模式课与环境准备课不配解析；**子教程**亦不配（按需学习、不进主线进度——同不做 Phase 3 / 5 的轻量口径）。

#### 五幕退出机制（不适合时的降级路径）

五幕是**默认骨架**，但并非所有知识都适合故事化叙事。以下情况允许采用**直述模式**，在课文件顶部标注"本课采用直述模式，原因：{理由}"：

| 不适合五幕的知识类型 | 原因 | 直述模式怎么写 |
|---------------------|------|---------------|
| **参考性知识**（如"Python 内置函数清单""HTTP 状态码表"） | 无场景冲突可设，硬造场景反而干扰查阅 | 直接以表格 + 简要说明呈现，不强制五幕 |
| **纯定义性知识**（如"什么是变量""什么是字符串"） | 概念太基础，场景比概念更复杂 | 简短定义 + 代码示例 + 一句话记住 |
| **速查/命令手册**（如"git 常用命令""kubectl 速查"） | 学习目标是查阅而非理解 | 按功能分类列表，每条附简短示例 |

**判定规则**：主 agent 在 Phase 2 生成每课前判断是否适合五幕。若不适合，在该课骨架中标注"直述模式"及理由，双 agent 评审时**学习者视角增加一条检查**："本课是否适合直述模式？标注的理由是否成立？若强行套五幕是否会更差？"（L4 故事弧完整性在直述模式下降级为"结构完整性"检查——内容是否完整有序而非是否是故事弧）。**直述模式下「知识点六要素」同步降级**：保留「一句话定义 / 核心原理 / 一句话记住」，可省略「直觉建立 / 示例演示 / 常见误区」，避免简单概念被六要素撑得冗长。**课级入口要素（本质 / 处境对照 / 全局图 / 地图）同步豁免**——参考性 / 纯定义 / 速查类知识无"解决什么问题"可画，硬画反而干扰查阅。

### 故事主线设计（Phase 1 备课时同步规划）

整个主题需有一条**叙事 spine**——不是知识点罗列，而是一条故事线贯穿始终：

- **找主角**：整个主题的核心对象是什么？（如 k8s 的主角是"Pod 生命周期"、理财的主角是"复利与风险"）
- **找冲突**：主角要解决什么问题？为什么这个问题难/重要？
- **找转折**：每个阶段是故事的一个"章节"，每个章节有关键转折（引入新机制解决前一个章节遗留的问题）
- **找收束**：学完整个主题后，学习者应该能回答什么"大问题"？

示例：
- k8s 故事线 = "一个程序员从单机部署到管理万台集群的进化之路"
  - 阶段 1（容器与 Pod 基础）= "单机时代的终结"——为什么需要容器
  - 阶段 2（调度与工作负载）= "让机器自己干活"——如何声明式管理
  - 阶段 3（网络与服务）= "让世界看到你的服务"——如何对外暴露
- 理财故事线 = "小王从月光到财务自由的进阶之路"
  - 阶段 1（基础概念）= "钱去哪了"——收入与支出
  - 阶段 2（投资工具）= "让钱生钱"——复利与工具选择
  - 阶段 3（风险管理）= "守住钱"——风险与配置

故事主线写入大纲模板的「故事主线」字段，每课正文生成时以此 spine 串联。

### 认知阶梯约束

第三幕"层层揭示"中的知识点排列必须遵循认知阶梯：

| 层 | 目标 | 知识点类型 |
|----|------|-----------|
| 感知层 | 让学习者"见过这个东西" | 是什么、长什么样 |
| 概念层 | 让学习者"理解这个东西" | 为什么存在、解决什么问题 |
| 机制层 | 让学习者"搞懂它怎么工作" | 内部原理、工作流程 |
| 实操层 | 让学习者"能动手用它" | 命令、代码、配置 |
| 定位层 | 让学习者"知道它在全局中的位置" | 与其他组件的关系、适用场景 |

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

## 表现形式规范

> **与「认知阶梯约束」的分工**：认知阶梯管**内容顺序**（结构层），本节管**怎么表达**（修辞层）——两者独立、互不替代。
> **本节硬约束对应的评审检查项**（缺了就等于没约束）：图表选型与 C 类、**术语双轨（回指 / 行话锚定 / 多策略对照表 / 编造）** → `review-dimensions.md` 的 pedagogy 维度 4「格式规范」；**跨课术语一致** → pedagogy 维度 5「一致性」；读图指引与**课级入口要素**（本质 / 处境 / 全局图 / 地图）→ learner **L7**；**知识点承接** → learner **L4**；连续纯文字段 / 非模板化亮点 → learner **L8**；**敏感信息禁入** → pedagogy 维度 4「格式规范」。

所有产物遵守：

1. **场景先行 + 类比辅助**：概念首次出现时不是先给定义，而是在五幕叙事中——先有场景引入（第一幕）建立直觉，再在层层揭示（第三幕）中用类比建立认知桥梁，最后引出术语定义。类比须在讲完原理后**指出类比失效的边界**，防止误导。类比不是开场修辞，而是贯穿第三幕的认知桥梁。
2. **图表选型（Mermaid + SVG 双引擎）**：流程 / 步骤 → flowchart；组件交互 → sequenceDiagram；概念从属 / 结构 → graph TD 或 classDiagram；状态流转 → stateDiagram；占比 → pie。SVG 有**两类触发信号**，命中任一即用 SVG（即使节点 ≤ 10）：

   **A 类：图形复杂度信号**（继承自 document-writer，适用于流程/拓扑类图）
   - ① 分支 / 回环密集 ② 交叉连线多 ③ 需泳道 / 分区语义 ④ 扇入 / 扇出大 ⑤ 需精确位置 / 方向控制

   **B 类：教学认知难度信号**（topic-teach 教学专属，适用于知识点讲解中的"光靠文字讲不清"场景）
   - ① **数据结构内部结构**：需展示内存布局/节点关系/索引映射（如哈希表 数组+链表、树的结构、图的邻接表）→ 用 SVG 具象化内部构造
   - ② **算法执行过程**：需分步演示状态变化（如数组插入元素逐步移动、排序过程、递归调用栈展开）→ 用 SVG 分步图 + 标注
   - ③ **抽象概念映射 / 层级结构**：需建立"抽象 → 具体"的视觉桥梁或表达多层嵌套/层级关系（如 key-value 映射、指针/引用关系、OSI/TCP/IP 分层模型、MVC 架构层）→ 用 SVG 概念模型图或层级图
   - ④ **多概念对比分类**：需并排对比多个概念的异同/分类（如线性 vs 非线性数据结构、各排序算法对比）→ 用 SVG 对比矩阵/分类图
   - ⑤ **数据 / 函数可视化**：需展示连续数据的形态/趋势/分布/对比曲线（如时间复杂度 O(n) vs O(n²) 曲线、概率分布）→ 用 SVG 轻量数据图表（坐标轴+曲线+关键点标注）
   - ⑥ **跨组件数据流全链路**：一个请求 / 数据 / 对象从入口到终态流经 **≥3 个组件**、需按时间步骤呈现"谁把什么传给谁、对象形态与状态如何逐步变化"（如 k8s `kubectl create deployment` 七步链路、HTTP 请求经网关→服务→DB 的生命周期、支付回调链路）→ **固定用 SVG**（正文可另配简版 mermaid 做速查，但不能替代全链路 SVG）；表达硬要求见 reference.md「数据流全链路图规范」——**只有编号文字列表、没有数据流图 = 该讲透的链路没讲透**

   **C 类：内容类型直查（固定 SVG，不靠 AI 判定）**——知识点**在讲什么类型的东西**，直接定引擎：

   | 知识点在讲什么 | 该画什么图 | 引擎 |
   |---|---|---|
   | **空间布局**：谁在哪（副本在各 Broker 的分布 / 节点与角色归属 / 数据落点） | 布局图（分区框 + 位置关系） | **SVG** |
   | **集合 / 范围关系**：A ⊂ B、"哪些算在内"、名单的收缩与扩张 | 集合图（区间 / 包含嵌套） | **SVG** |
   | **多概念对比分类**：并排比异同、带颜色语义的分类 | 对比矩阵 / 分类卡片 | **SVG** |
   | **层级 / 分层结构**：协议栈、分层架构、嵌套概念 | 层级图（横向分层 + 层间箭头） | **SVG** |
   | 步骤时序 / 组件交互 / 状态流转 / 占比 | 时序图 / 状态图 / 饼图 | mermaid（保持） |

   > **为什么 C 类不靠信号判定（实测依据，勿回退）**：B 类要求 AI 自评"学习者会不会脑补累"——**AI 系统性低估**。实测一课 4 张图**全部退化为 mermaid、0 张 SVG**（该阶段 `assets/` 里唯一的 SVG 是"阶段路径图"，即唯一被固定场景钉死的那张）；而退化的图里有三张恰是上表**前三行的典型**：副本在 Broker 上的分布、`AR = ISR + OSR` 的收缩扩张、带颜色语义的全课总结。**结论：类型判定（在讲什么）比难度判定（累不累）可靠得多**——C 类因此改为直查，不给 AI 留自评空间。
   > **表达形式（怎么画）**见 reference.md「C 类：内容类型直查」。

   **固定 SVG 场景**（统一用 SVG，不退回 mermaid）：**每课「一眼全局图」**、**每篇应用实战「分步设计图」**（每演进一步一张）、学习路径总览图、阶段依赖图、阶段路径图、**跨组件数据流全链路图**（命中 B-⑥）、**C 类表列出的四类内容**。

   > 🔴 **固定场景 = 必画 + 必 SVG（两条都硬，勿只记后半条）**：固定场景的意义是**取消 AI 在这一处的判定权**——它不只意味着"不许退回 mermaid"，**"干脆不画"同样是违规**（与"用 mermaid 顶替"同级，P1）。
   > **实测教训（勿重演）**：三篇应用实战**零张图**（连 mermaid 都没有，比"退化成 mermaid"还退一步），另有 12 课**零张「一眼全局图」**——两个固定场景同时长期失效。AI 当时的理由是"表格 + 数据已经讲清，不用画图"：**它心里的选项集是 {画 mermaid, 画 SVG}，"不画"从未被列为一个违规选项**。
   > **因此固定场景的落点必须是模板槽位**（套模板 → 槽位带出图），不能只靠 AI 记得；验收走对应产物的「落盘前自检」（见「应用实战」「源码解析」小节与 reference 各模板）。
   **图配额（每课）**：**下限** = 第三幕**每个知识点至少配 1 张图**（mermaid 或 SVG；命中 C 类的必须是 SVG）。**上限只管"自主升级"的图**——
   - **不计入上限**（数量由内容决定）：**「一眼全局图」、应用实战「分步设计图」（数量 = 演进步数）、跨组件数据流全链路图、C 类四型**——内容需要几张就画几张，**不得为守配额把 C 类图退回 mermaid**
   - **计入上限**：其余图（A 类信号 / B-1 数据结构 / B-2 算法过程 / B-5 数据可视化，即 AI 自行判断要不要升级为 SVG 的）→ **每课 ≤ 2 张**，防见猎心喜
   - 「本课地图」为表格，**不计入任何配额**
   > **为什么上限只管自主升级（勿回退）**：本条原表述是"每课 SVG 上限 3 张"，与同节的"C 类必须 SVG + 固定场景"**自相矛盾**——一课含「一眼全局图」+ 一张全链路图 + 2 个 C 类知识点就已 4 张。上限的本意是**降低启动阻力、防凑数**（心理层面），不是限制内容必需的图；**配额与强制场景打架时不得牺牲强制场景**。
   **图型要有差异**：连续多张都是 flowchart 会让读者视觉疲劳（mermaid 图长得都一样），C 类图的存在本身就是"不枯燥"的一部分。
   **反向约束（已收窄）**：默认用 mermaid；**但 C 类与固定场景不受此约束**——它们不是"更精美"，是 **mermaid 表达不了**（画不出空间、体积、包含嵌套、并排对比）。仅对 C 类之外的图，禁止为好看把简单图升级为 SVG。
   **判断口诀**：*在讲"什么"（布局 / 集合 / 对比 / 层级）→ 直接 SVG；在讲"顺序"（步骤 / 交互 / 状态）→ mermaid；文字讲不清的概念 → SVG。*
   **每张图后必须紧跟一句话读图指引**（"看图：左边是……右边是……差别在于……"）——**没有指引的图等于没画**（实测：某课 4 张图仅 1 张有指引，其余读者只能自己猜）。
   **SVG 的最小合格形态**：**框 + 箭头 + 标签即合格**，不做美术加工（不追求渐变 / 插画 / 拟物）——**SVG 不是"重活"，不必因怕做不好而退回 mermaid**。
   SVG 独立文件入 `assets/`（kebab-case 命名，如 `{图作用}-{图主题}.svg`）。
   **archify 增强路径（可选，默认不依赖）**：上述 SVG 默认由 AI 手写（能力边界见 reference.md）；仅当用户环境已安装 archify 且**用户明确要求**用它出图时，用 archify 生成可交互 HTML，再**由用户显式调用** `archify-svg-export` 导出 SVG 落 `assets/`——命名 / 引用 / 配色规范不变，导出不可用则降级为手写 SVG，不阻塞教学。**教学流程不得自动触发 `archify-svg-export`**（其触发契约为仅显式调用），也不得因 archify 缺失而省略全链路图。
   **配色约束**：图表（mermaid 与 SVG 通用）背景禁用黑色 / 过深颜色，一律浅色背景（含白色）+ 深色文字；深色仅用于元素强调（表头 / 高亮块，其上文字用浅色），不作大面积背景（详见 reference.md「配色与背景约束」）。
   > 完整 AI 能力边界（含 CSS 微动画、数据可视化图等）见 reference.md「AI 生成 SVG 的能力边界」。
3. **emoji 节制**：仅用于功能性标记（🎯 目标、💡 重点、🐞 陷阱、⚠️ 风险、🚀 进阶），每段 ≤ 2 个，宁少勿滥——美观服务于实用性。
4. **术语双轨（进来降维 + 出去对标）**：术语的"人话"与"行话"都要给，两端缺一不可——
   - **① 回指**：术语**首次正式登场**时，回指本课直觉层（「一句话本质」/「一眼全局图」）的说法——"就是第一幕说的'…'"，**不出现两套词汇对不上**（与 module-teach D8④ 同源）
   - **② 通俗化（降维）**：术语首次出现时给一句"人话"解释 + **标准叫法**。标准叫法按**命名三态 + 标注义务**取，判断依据是"**这个中文说法是否真有人在用**"，**不是"能不能翻出来"**：**有公认中文译名** → `中文（English）`（如 幂等（Idempotence））；**只有社区通用译法**（网上常见、官方未定名）→ 可以用，但须括注"社区常用译法，官方未定名"；**确无在用译名** → 优先英文 / 缩写（如 `OSR（Out-of-Sync Replicas）`），**确需中文可自拟、但必须标注"本文自拟、非通用译名"**（标注**只在首次登场处给一次**，后文不重复；"社区常用"须有出处）——**红线是"标注"不是"用不用中文"：没标注的译名才让读者对不上号**
   - **③ 行话锚定（对标）**：知识点讲透后，给出它在行业里的**标准叫法**（命名三态见 ②）与**在哪遇到**（配置项名 / 监控指标 / 报错关键字 / 官方文档章节）——这是学习者回工作现场能搜到、能对上号的钩子；**非技术域**将"在哪遇到"改为"**在什么场合遇到**"（合同条款 / 产品说明书 / 媒体报道 / 监管文件），来源用权威机构而非自媒体教程
   - **多策略必配对照表**：讲"同一件事的多种做法 / 策略"时（同步 vs 异步、一致性级别、几种模式…），必须给「本课说法（人话）｜行业标准叫法｜典型配置 / 在哪遇到｜代价」四列对照表——只给白话策略名 = 对不上行业坐标系
   - 🔴 **真实性**：标准叫法 / 配置项 / 报错原文属事实，**须过事实核查闸门**（优先从 Step 1.4 的 web-index 取官方文档页）——**编造不存在的"行业叫法"按 P0 判**
   - 形态与示例见 reference.md「术语锚定规范」；确无行业术语的纯概念知识点可标注"本知识点无行业术语"并省略。
   - **直述模式豁免 ①**（速查 / 参考类无直觉层可回指），②③ 照常执行。
5. **语言**：全程中文（代码注释也用中文），句式活泼但严谨，关键结论加粗。
6. **诚实**：不确定的内容按事实核查闸门标注置信度，绝不为了生动而牺牲准确。
7. **md 主载体、SVG 补充**：一切内容先落在 Markdown。图表默认 Mermaid；复杂拓扑 / 学习路径图用独立 SVG 文件（`assets/`）。**不使用 HTML**——SVG 已覆盖原有 HTML 的可视化场景，且跨平台兼容（GitHub 可正常渲染 SVG 文件）。
8. **官方文档链接**：涉及的概念 / 技术 / API / 命令如有官方文档，须在对应知识点后附「📚 官方文档」链接（如 Docker 文档、k8s 官方文档、Python 官方文档、MDN 等）；无官方文档或纯个人理解的知识点则省略，**不得编造链接**。**链接须来自 Step 1.4 建的网页索引，或当场 fetch 核实过的真实页面**——不凭记忆写、不按路径规律拼。非技术域附权威来源（监管机构 / 官方指南），不用自媒体。
9. **非模板化亮点（每课至少一处）**：五幕 + 六要素严格执行会让**每课长得一样**——"结构同构"是枯燥的主因之一。每课须至少有一处跳出模板的内容，四型任选：**真实报错日志** / **反例对照**（错的写法 + 为什么错 + 正确写法）/ **mini 案例**（一条完整场景走到底）/ **"数字算给你看"表格**。**通篇只有"定义 + 规则 + 流程图"的课不合格。**
   > **与 4.2 应用实战的联动**：4.2 写得好，天然可**兼任**「mini 案例」型亮点——但**两条要求不得互相豁免**：4.2 未兼任时，亮点仍须落在报错日志 / 反例 / 数字表 / 单独 mini 案例；亮点已具备时，4.2 照常写（它是结构要求，不是"凑亮点"的手段）。
   > **源码挖掘的用法（优先素材）**：源码探索挖到的"文档未写的稳定用法"（见「源码探索」）= **反直觉对比型的现成亮点**（"文档说 A，源码里还有 B"）——挖到就别浪费；无场景价值的纯冷知识不硬塞（同其产出转换口径）。
   > 🔴 **真实性红线（优先级高于本要求）**：四型中凡涉及"事实"的（真实报错日志 / 真实案例 / 数字），**必须来自真实来源，禁止为凑亮点编造**——编造报错日志是**失真**，与"准确"直接冲突，**比"没亮点"更糟**。确实无合适亮点时，允许用「反直觉对比」或「一个常见误解的来源」代替；也可标注"本课无合适亮点"——**不得硬造**。
   > **速览模式**：单篇 `overview.md` 同样要求至少一处亮点，密度按整篇计。
   > **旧课不回溯**：本要求只对**新生成**的课生效，已落盘的课不批量回填（与「课级入口要素」同口径）。
10. **密度交替（防文字墙）**：同一幕内**不得连续出现 4 个以上纯文字段落**——图 / 表格 / 代码块 / 引用框任一即可打断。**长文字墙与图型同质化是"枯燥"的两个直接来源**；能表格化的内容不要写成段落。直述模式（速查 / 参考类）豁免。
   > **适用范围**：**第 9、10 条为 topic-teach 专属**。`use_skill("module-teach")` 的产物是代码讲解档案，"不枯燥"由**沿真实调用链走一遍**（其叙事骨架第四幕）与**真实 diff 前后对照**承担，不另立这两条规则。
11. **敏感信息禁入（真实凭据 / 隐私数据不落正文）**：教程会被复制、分享、提交进 git——**正文、代码块、配置示例、日志、图表（含 SVG 图内文字与图注）、示例数据里一律不得出现真实的敏感信息**：token / API Key / 密码 / 私钥、非公开 URL（内网地址、预签名链接、内部系统域名）、真实 IP 与内网拓扑、个人真实信息（姓名 / 电话 / 邮箱 / 账号 / 身份证）。
    **正替代（给占位写法，不是简单删掉）**：占位符**少而可辨**，首次出现处给一句替换说明（"把 `<YOUR_API_KEY>` 换成你自己的 key"）——避免读者照抄时满篇填空。

    | 类型 | ❌ 真实值 | ✅ 占位写法 |
    |------|----------|------------|
    | 凭据 | `sk-1234abcd…` / 真实密码 | `<YOUR_API_KEY>` / `<YOUR_PASSWORD>`（全大写 + 尖括号，一眼可辨） |
    | IP | 真实环境地址（本机 / 公司内网 / 真实集群节点）及由此可推的拓扑 | 教科书式通用示例（`10.0.0.3` 的 Pod IP / `192.168.1.1`）或文档专用段（RFC 5737）`192.0.2.x` / `198.51.100.x` / `203.0.113.x`；本机 `127.0.0.1` |
    | 域名 / URL | 内网 GitLab / 监控台地址 | `example.com` 系（RFC 2606），如 `api.example.com` |
    | 个人信息 | 真实姓名 / 手机号 / 邮箱 | 虚构人物（如"小王"）或 `user@example.com`；示例数据可标注"示例" |

    > **判定标准（防过度脱敏）**：*这条信息是否指向一个真实存在的、非公开的系统或人？* 是 → 必须脱敏。**公开信息不受限**——官方文档 URL、开源仓库地址、`localhost`、公开示例值照常写，不因本条把公开链接误判为敏感；**教科书式通用示例**（`10.0.0.3` Pod IP / `192.168.1.1` 家用路由）不指向特定真实环境，照常可用——**照搬真实环境的地址与拓扑**才是问题。
    > **三条接缝（与既有规则交叉，最易漏）**：① **「真实报错日志」先脱敏再引用**——它是「非模板化亮点」四型之一，而真实日志最常带 token / 内网地址 / 用户名；**不为凑亮点编造日志，也不为"原汁原味"搬真实敏感值**（真实性红线与本条同时适用）；② **Phase 5「真实事故案例复盘」同理**——可引用公开事故报告，但不得搬运其中凭据、内网信息与个人可识别信息，**不得写入"来自某公司内部资料"的内容**；③ **Phase 3 实战项目 `实现/` 不得硬编码真实凭据**——一律走环境变量，真实值只存在于 `.env`（已被 `reference.md` 的 `.gitignore` 基线「本地配置与密钥」组覆盖），**正文与代码里永远只有占位符**。
    > **用户主动提供 / 要求写入真实值时**：默认仍脱敏——说明风险（教程会被分享、提交，且读者本来就需要替换成自己的值）并改占位符；**真实值对教程无增益**。
    > **适用范围**：反例对照代码（常由真实配置改写而来）脱敏标准与正文一致；非技术域同样适用（真实姓名 / 账号 / 收益截图中的可识别信息）。

## 更多资源

- 多阶段大纲 / 学习路径总览 / 阶段概览 / 单课 / **环境准备课** / **应用实战文件与索引** / **源码解析文件与索引** / **子教程** / 学习档案 / **课程目录索引** / **综合实战项目模板** / **实战经验与排障速查手册模板** / **场景解法库模板** / **产物仓库 `.gitignore` 基线模板** / 接力提示词模板、SVG 规范、免责声明模板、quiz 文件格式：[reference.md](reference.md)
- 速览 / 单课 / 学习档案 / SVG / **综合实战项目** / **实战经验与排障速查手册** / **场景解法库** / **源码解析** 的成品示例：[examples.md](examples.md)
- **按阶段细则（按需加载）**：[planning.md](planning.md)（Phase 0-1 备课）/ [wrapup.md](wrapup.md)（Phase 3-6 收尾）/ [ops.md](ops.md)（产物仓库卫生 + 运行环境约定）——由「工作流程 · 内容路由」按时机指向
- **评审维度定义（SSOT）**：[review-dimensions.md](review-dimensions.md)——教学法视角 / 学习者视角 / 专项 A、B、C、F 维度 + 三模式执行方法 / 意见分级 / 自检清单。**内联评审直接读它；委派子 agent 时随【评审维度】传入**
- 评审 agent（**可选**）：`use_agent(course-reviewer)`——未创建时主 agent 按上面的维度文件内联评审，不阻塞流程；其内置维度只是兜底骨架
- 数据流全链路图表达规范与 archify 增强路径细则：[reference.md](reference.md)「数据流全链路图规范」
- archify-svg-export（**可选 skill** · SVG 无头导出，仅用户显式调用；**未安装时忽略即可**，直接降级为 AI 手写 SVG）
- 外部官方文档的本地路由表（Step 1.4 调用建 / 查索引）：`use_skill("web-index")`——**落点被本技能覆盖**为 `{topic-slug}/web-index/`，规模判断与工作流仍以它为准