通用知识教学（Topic Teach）

概述

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

功能：

• 双模式交付：大主题走课程制（多阶段大纲 → 阶段概览 → 分批知识点教学），小主题走速览（单篇讲透 + 延伸大纲）
• 故事化教学叙事骨架：每课遵循"场景引入 → 认知冲突 → 层层揭示 → 实操验证 → 体系收束"五幕结构，以场景代入而非定义堆砌开场；大纲规划时同步设计故事主线，把架构/知识点拆成有情节推进的故事线
• 每课入口零术语可达：进入细节前依次给「一句话本质 + 处境对照」（第一幕末，定性 + 动力）与「一眼全局图 + 本课地图」（第三幕首，全貌 + 路线）——没学过本课的人应能看懂那张图；直述模式豁免（详见「课级入口要素」）
• 术语双轨：术语进来时降维（「术语通俗化」：人话解释 + 中英对照），讲透后对标（「行话锚定」：行业标准叫法 + 在哪遇到——配置项 / 监控指标 / 报错关键字 / 官方文档章节）；讲"多策略"的内容必配「策略-术语对照表」（详见「表现形式规范 · 术语双轨」）
• 多阶段备课制：正式讲解前先规划「阶段 → 课 → 知识点」三层大纲（通常 2–4 个阶段 = 完整学习旅程），并随学习进度 / 目标变更 / 重点变更动态调整（活文档）
• 多角色主题分离（按需启用）：主题的使用者分属职责显著不同的角色时（Redis 开发 vs 运维、MySQL 开发 vs DBA、k8s 应用开发 vs 集群运维……），主线只围绕学习者角色展开，次角色内容收敛为独立子教程（子教程/{专项名}/，按需学习、不进主线进度）；主线中次角色知识只做"提及级"带过（一句话 + 指向子教程）。判定信号与拆分规则见 planning.md Step 1.1「多角色判定」
• 评审把关：多阶段大纲、阶段概览、学习路径总览经 course-reviewer 子 agent（教学法视角）评审；每批教学内容必须经两个 course-reviewer 实例以不同视角（教学法视角 + 学习者视角）独立评审，冲突由主 agent 裁决（教学逻辑 / 准确性 / 完整性 / 格式规范 / 一致性 + 场景吸引力 / 由浅入深 / 认知阶梯 / 故事弧 / 困惑点 / 全局定位），P0 问题清零后才交付用户；评审以 00-评审清单.md 为强制检查点（事前占位待办 + 事后勾选，未勾选 = 未评审）
• 分批生成：以知识点为最小单位，每批 3–5 个知识点生成并确认，禁止一次性生成整个阶段的内容，保证质量与学习节奏
• 教学效果推演闸门（课程制大纲定稿前必做）：站在教学者角度模拟"学习者学完这套大纲"，用领域高频工作场景（日常任务 / 故障排查 / 设计决策）+ 理论理解问题构建覆盖矩阵，检验实战覆盖与理论理解是否达标——🔴 零覆盖的高频场景必须补进大纲后才能定稿（执行方法见 Step 1.2a，推演模式定义见 review-dimensions.md 的「教学效果推演执行方法」）
• 课级应用实战（按需配套 · 独立成册）：通过判定的课配一篇应用实战（场景 → 全貌一句话（非本课设计点到为止）→ 渐进演进：基础实现 → 它的问题 → 综合实现），独立落盘于 应用实战/ 目录——正文不在课内，课内双位置入口（第四幕入口块 + 文末「🧭 课程导航」区「🎯 练一练」行）跳转；判定规则见 planning.md Step 1.1「应用实战判定」（不是每课都配——强配反而意义不大）；应用实战/INDEX.md 一键跳转全部实战（固定入口，随课程进度更新）。每个演进一步各配一张固定 SVG「分步设计图」（渐进式讲解的骨架：这一版长什么样、比上一版改了什么，一目了然）与代码示例（不要求真实运行，但必须做正确性 review——主 agent 直接审，保证代码正确）；目标是"会用"不是"能上生产"；与 Phase 3 结课项目、Phase 5 场景解法库的边界见「教学叙事骨架 · 应用实战」
• 源码解析（按需配套 · 独立成册 · 限库 / SDK / 框架类主题）：过判定的课配一篇——针对核心 / 常用功能读真实库源码（为什么读它 → 功能全貌 → 源码直击 → 设计权衡 → 回扣用法），至少 1 张图（调用链用 Mermaid / 结构布局用 SVG）；独立落盘 源码解析/，课内文末「🧭 课程导航」区留入口（🔬 行）；判定见 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）
• 基础环境准备课（技术域 · 有实操即必做）：课程要求读者自己运行命令 / 代码时，大纲阶段 1 首课固定为「环境准备」——最小环境集 → 主路径 + 备选装法（Docker / 本机 / 云）→ 验证命令 → 常见安装坑，并标注"已有环境可跳过"；后续课需要额外环境时在该课课首轻量补充。与「运行环境约定」分工：本课管"读者装自己的环境"（教学内容），后者管"AI 跑代码的纪律"（执行规范）——判定见 planning.md Step 1.1「动手环境判定」
• 运行环境约定：讲解过程中需要真的运行代码（Phase 3 实战项目的 实现/、4.1 机制验证的命令、临时验证脚本）时，按「先探测 → 不污染全局 → 不擅自改用户环境」三条硬纪律执行；工具选型走优先级链（用户指定 > 项目约定 > 默认 uv run / fnm exec + pnpm）——4.1 属"能跑则跑"必跑类（判定与留痕见「4.1 的实证要求」）（细则见 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/
│   │   │   ├── 01-{课名}.md            # 课文件名 = {NN}-{课名}：两位数序号 + 中文课名，不带 `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/{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，课文件不得加 lesson- 前缀（应为 {NN}-{课名}.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（低频内容不常驻本文件）。

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——Phase 0-1 + 四个判定 + 大纲活文档
收尾（课时讲完）	wrapup.md——Phase 3 实战项目 / Phase 4 手册 / Phase 5 三产物 / Phase 6
提交产物 / 清理 / 跑代码	ops.md——产物仓库卫生 + 运行环境约定
写课的格式模板	reference.md——单课模板 / 各产物模板
写应用实战 / 源码解析篇（随课产物）	reference.md「应用实战文件与索引」/「源码解析文件与索引」——逐槽位套模板（含分步设计图槽位，不得删槽）
自评 / 评审维度	review-dimensions.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。开课 / 规划或调整大纲时先读它（写课会话不需要）。

断点续学（跳过 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 落盘的课骨架上展开正文（骨架含课名/知识点清单/本课目标/情节定位）；若本批即一课的全部知识点 → 直接成文 {NN}-{课名}.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 步）。勿再引入第二份流程清单。

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

## 🚀 下一批接力提示词

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

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

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

课程导航（上一课 / 下一课链接）：整课完成（该课全部知识点批次写完、不再追加小节）时，在课文件末尾（接力提示词之后）追加「🧭 课程导航」区块，含上一课 / 下一课 / 返回目录三个链接（格式见 reference.md 单课模板）：

• 上一课 / 下一课用课文件相对链接——同阶段直接 {NN}-{课名}.md，跨阶段 ../../{阶段名}/lessons/{NN}-{课名}.md；
• 课 → 根级文件的路径（勿写错）：lessons/ 到根是三级——../../../02-课程目录.md、../../../应用实战/{NN}-{课名}.md、../../../源码解析/{NN}-{课名}.md；两级只到 stages/；
• 第一课省略「上一课」；最后一课的「下一课」改为「🎉 课程知识已讲完——接下来做综合实战项目」（链接回课程目录，不写"本课程已完成"——课时讲完 ≠ 学完，后面还有 Phase 3 / 5）；
• 该区块是课级导航，整课完成时一次写入，不随批次更新；拆批过程中（课未写完）不写。

整课完成时追加一项：卫生检查——课写完（导航区块落盘的同一时刻）执行（.gitignore 增量维护 + 本轮临时文件清理，流程见 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）

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

速览模式

单篇 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）：

## 🚀 想深入？复制发给 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。课时全部讲完后读它进入收尾。

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

这是比"表现形式规范"更高优先级的结构约束。表现形式规范是修辞层（类比、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）。跑不通不是失败：版本差异 / 环境依赖 / 命令废弃本身就是值得讲的内容，别改成"预期输出"糊过去。 🔴 留痕只声明、不证明：✅ 实测于 是作者的声明，评审无法静态验证它是否真跑过（与「📖 文档核对」留痕同理——只证明"核过"，不证明"核对正确"）。故本条的治理目标是让"跑没跑"可见（消灭"未实测却长得像实测"的灰色地带），不是消灭编造；输出与实际行为明显不符仍按维度 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 单课模板的图槽位生成（，课文件在 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 Step 1.1「应用实战判定」——强配反而意义不大）：跟着作者走一遍"从幼稚到像样"的演进，把知识点焊进真实用法。

项	要求
位置与落盘	正文独立成篇：应用实战/{NN}-{课名}.md（NN = 课的全局序号）——按 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	引用用图片语法 	写成 [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 Step 1.1「源码解析判定」——限库 / SDK / 框架类主题，服务端 / 系统组件不配）：带学习者读一段真实的库源码，把"用法"焊到"实现"上。

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