module-teach

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

SKILL.md

GitHub

代码讲解(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 §9.2。
    • 每个被注释文件头部保留一行自然语言说明(声明含教学注释 + 还原方式),模板见 reference.md §9.2。
    • 只覆盖教程重点文件与关键函数(Phase 2 wiki 的关键清单),不撒胡椒面;语言与风格随项目既有约定。

      注释是"第二次通读代码":动笔前抽查核心文件的 file:// 锚点与当前代码是否仍对应——明显漂移(函数已改名 / 删除)以代码为准并告知用户;若发现教程结论与代码不符,先按 Phase 3 修正级联修正教程,再据修正后的内容写注释(不得照抄错误结论)。

  4. 机械自检:git diff --numstat —— 删除数必须为 0(只有注释行新增);发现语义改动立即修正。
  5. 记录:在 06-最终文档.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 §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 §1「通用格式规范」。

落盘时三件事(缺一不可):

  1. 初始化 00-评审清单.md:按计划评审节点一次性占位全部条目(- [ ])。模块类占位:大纲评审 + 解读评审 + 收尾评审;变更类精简模式只占位 2 条评审(01-逐处解读 评审 + 收尾评审)+ 1 条质量闸门(02-正确性核对)——模板见 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 §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 的 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 的 SVG 图表规范
  • 渲染环境不确定(聊窗讲解 / 终端 / 纯文本传阅)或需逐节点挂 文件:行号 批注时,结构类信息(子模块依赖、数据流主干、状态流转链)可用 🕸 文字树兜底(渲染无关);只作兜底,不替代上述 Mermaid / SVG 默认,最小语法与示例见 reference.md「5.1 🕸 文字树」
  • 用 Markdown 表格、引用块(提示框)增强讲解,顶部放目录锚点,便于跳转回顾
  • 版本控制友好,跨平台可渲染

学习目标附加内容(仅 Phase 0 选了"改造"或"评审"时生成):

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

Markdown 与 Mermaid / SVG 模板见 reference.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 不代为提交。 详见「伴读分支」小节。

接力提示词模板(写入产物末尾 + 对话中均使用):

## 🚀 下一步

> 复制下面这段文字发给 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 §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
  • 阶段产出示例与最终文档样例(含变更讲解示例):examples.md
  • 评审维度定义(SSOT):review-dimensions.md——专项维度 D(含 D8)/ E、分级与自检清单。内联评审直接读它;委派子 agent 时随【评审维度】传入
  • 评审 agent(可选):use_agent(course-reviewer)——未创建时主 agent 按上面的维度文件内联评审,不阻塞流程;其内置维度只是兜底骨架
  • 外部官方文档的本地路由表(Phase 1.5 调用建 / 查索引):use_skill("web-index")