module-teach
系统讲解本项目代码:模块讲解(能力大纲 → 代码 wiki → 功能推演 → 应用场景 → 数据流)或变更讲解(commit / PR / 任意 diff:逐处解读 → 影响面 → 意图与权衡),产出可反复查阅的 Markdown 材料。触发:"讲讲这个模块"、"学习一下 XXX 代码"、"讲讲这个 commit/PR"、"这个改动是什么意思"、"帮我搞懂这块代码"、"考我一下"。通用知识主题用
SKILL.mdskills/module-teach/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 落盘的中文件命名惯例一致。
取证纪律(变更类专属)
- diff 是唯一事实源:一切结论必须能回溯到 diff 的具体行。禁止凭 commit message 或 PR 描述推断改动内容——描述会过时、会写错、会漏。
- 意图必须分级标注:
[显式]:commit message / PR 描述 / 代码注释里写明的动机 → 可直接引用[推断]:从 diff 语义反推的动机 → 必须标注为推断,并给出推断依据(如"该函数新增了重试分支,推断为应对 X 场景的失败")两者混在一起就是体面的编造。读者最想知道的恰恰是"作者当时为什么这么改",把推断当显式说是最糟的失真。
- 影响面必须实证:讲"改了这里会影响谁"时,必须用 GitNexus
impact/context+search_content取证调用方与消费方,禁止凭 diff 文本推断——diff 只显示被改的文件,调用方在 diff 之外。判定不了影响面时写"影响面待确认",不猜。降级路径(必读):GitNexus MCP 不可用时,退回
search_content全局搜索调用点 + 逐处read_file回源码确认,结论同样须回到源码。此时在03-影响面分析.md顶部标注⚠️ 影响面基于 grep + 源码阅读取证(GitNexus 不可用),覆盖度可能低于图谱查询。MCP 不可用不是降低取证标准的理由,只是换一种取证方式。 - 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"。 - 非 git 环境降级:无法取 diff 时(用户只粘贴了代码片段 / 仓库无 git),显式降级为「仅解读用户提供的文本」,在产物顶部标注
⚠️ 本材料基于用户提供的片段,未取完整 diff,影响面未验证,且跳过影响面分析阶段——没有 diff 就没有影响面的证据基础。 - 不越权评审:讲变更时只描述与解释。发现明显问题 → 记录进
05-风险与待确认.md的「需向作者确认」清单,不写成"这个改动不该合"。 - 档案是一次性消费,可随时删除:变更档案(
.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-功能推演.mdvs03-影响面分析.md),便于跨类型形成一致习惯。
07-知识点对齐.md与06-最终文档.md的编号差是历史约定(Phase 8 产出 07,与topic-teach统一),不因流程顺序在末尾而重编号——topic-teach反向依赖本技能的 Phase 8。
每写完一个阶段文件,在对话中给一句阶段摘要(结论 + 关键发现 + 文件链接),不要一次性把全文甩进对话。
产物卫生(落盘须知)
产物写在 .teach/ 目录,落在被讲解的项目仓库内——它和用户的源码共用同一个 git 仓库。这是本技能与 topic-teach(独立产物仓库)在落盘上的根本差异,故须遵守:
- 不动用户的忽略规则:用户项目已有的
.gitignore一律不改,即使看起来该加规则。正常讲解不运行被讲解的代码,故默认不需要维护.gitignore——topic-teach需要(它会生成并运行实战项目),本技能默认不需要,不要照搬整套机制;完整机制以topic-teachSKILL 为准。例外(不留真空):若本轮为验证结论实际运行了脚本 / 测试并产生了依赖目录、缓存、日志(如
__pycache__//.pytest_cache//.venv//node_modules/),则仍需追加对应规则——同样遵守「只追加、范围限定.teach/与临时目录、不碰用户既有规则」。触发概率低,但第 3 条已承认会产生临时验证脚本,此处不能把门关死。 运行本身就按「运行环境约定」执行(先探测环境、用uv run/fnm exec、不污染全局)——做对了,这里的例外就很少触发。 - 首次落盘时提示一次:生成
.teach/后在对话中告知".teach/已生成于项目根目录,是否提交由你决定"。不代为执行git add/git commit,也不擅自把.teach/加进.gitignore——那是用户的选择,不是 AI 的。 - 临时文件清理:讲解过程中若产生中间草稿 / 临时验证脚本,创建时就在对话中记下路径,落盘收尾时按记录清理——只删记录在案的文件,用精确路径删除,禁用
git clean -fd(会连用户自己的未跟踪文件一起删)。没有记录的一律不删:8 个 Phase 的长流程里"本轮亲手创建"的记忆同样会失真,判断依据只能是记录;漏记的失败方向是安全的(临时文件留在磁盘上),绝不为"完成清理动作"而现场凑清单。 - 禁止误伤:
.teach/下的*.md与assets/*.svg是讲解产物本体,任何时候都不删除、不忽略。例外:已完成讲解的变更档案(
.teach/commits|prs|changes/下的旧目录)可整目录删除——它们是一次性消费且会无限堆积,见「取证纪律」第 7 条。本条的禁止误伤约束针对正在讲解的产物。
判定口诀:这个动作是在动我的产物,还是在动用户的项目? 只动前者。
唯一例外:用户显式同意下的「伴读分支」(见下节)——只在新分支上进行、只加可整体还原的自然注释(无标记前缀)、不提交、不合并。
伴读分支(可选 · 仅 module 类)
定位:教程是"文档层讲解",伴读分支是"代码层讲解"——把要点就地注释到核心代码上,读代码时不用来回翻文档。这是本技能唯一获授权改动用户源码的场景(「产物卫生」的显式例外),必须同时满足:用户显式同意 + 新分支隔离 + 只加注释 + 不提交 + 可整体剔除。
触发:Phase 7 收尾三件事完成后询问一次(用户可拒绝、可改分支名);用户显式要求时直接执行。未经用户同意不得创建分支。 变更类不适用(一次性消费)。
硬闸门(任一不满足 → 不创建,并说明原因):
- 工作区必须干净(本技能自身产物除外):
git status --porcelain输出中,剔除本技能产物(.teach/、.web-index/、temp/web-index-*)后仍非空 → 不创建,列出剩余脏文件,请用户先自行提交或暂存后再来。AI 不替用户处理工作区(不代提交、不代 stash)。为什么排除自身产物:三者正是本流程刚生成的教程档案 / 网页索引 / 临时文件,且「产物卫生」规定其提交与否由用户决定——不排除,功能在"教程刚落盘、产物未提交"的常见流程下会被自己的产物卡死;闸门真正要防的是用户的未提交改动被卷入伴读分支。
- 非 git 环境 → 不提供,一句话说明。
- 分支已存在(
teach/{module-slug})→ 不覆盖、不加-f,列出候选让用户决定。
执行步骤(用户同意后):
- 记录基准:当前分支名 +
git rev-parse --short HEAD。 - 创建并切换:
git switch -c teach/{module-slug}。 - 加注释(纪律):
- 只加注释、不改一行语义(不顺手格式化 / 重命名 / 修 bug);不加任何标记前缀——像项目原生注释一样自然书写;剔除靠
git restore(整体或按文件还原)。 - 就近分散:每条注释紧贴它解释的那一行 / 那个分支;禁止把整段讲解堆在函数 / 类 / 方法签名上方——签名上方至多一句"这是干什么的",机制细节下沉到函数内部对应语句旁。正反例见 reference.md §9.2。
- 每个被注释文件头部保留一行自然语言说明(声明含教学注释 + 还原方式),模板见 reference.md §9.2。
- 只覆盖教程重点文件与关键函数(Phase 2 wiki 的关键清单),不撒胡椒面;语言与风格随项目既有约定。
注释是"第二次通读代码":动笔前抽查核心文件的
file://锚点与当前代码是否仍对应——明显漂移(函数已改名 / 删除)以代码为准并告知用户;若发现教程结论与代码不符,先按 Phase 3 修正级联修正教程,再据修正后的内容写注释(不得照抄错误结论)。
- 只加注释、不改一行语义(不顺手格式化 / 重命名 / 修 bug);不加任何标记前缀——像项目原生注释一样自然书写;剔除靠
- 机械自检:
git diff --numstat—— 删除数必须为 0(只有注释行新增);发现语义改动立即修正。 - 记录:在
06-最终文档.md追加「伴读分支」小节(模板见 reference.md §9)——分支名 + 基准 sha + 日期 + 注释范围 + "未提交"警示;该小节是元信息(非讲解内容),不需重跑评审。 - 对话提示:告知四条——① 已切到伴读分支、注释未提交;② 未提交的注释不在分支里(只附着工作区,切到哪跟到哪;
git restore .丢弃即消失),想固定到分支上、随时回看,请自行提交;③ 切回主线前必须先处理(提交保留,或丢弃改动),否则未提交改动会跟随到主线工作区;④ 分支留存或删除由用户决定。
硬边界:
- AI 不执行
git add/git commit,也不得绕过签名要求——是否提交、何时提交由用户决定。 - 不合并、不 push;伴读分支是"一次性伴读层"——未提交时注释不存储在分支里(丢弃即消失),其持久化只由用户提交决定。
运行环境约定(精简版 · SSOT 在 topic-teach)
讲解中若需运行代码验证结论(临时验证脚本、跑测试、复现某段行为),完整规则见 topic-teach 的 ops.md「运行环境约定」(SSOT)。此处只留模块讲解场景的四条要点:
- 三条硬纪律(优先于任何工具选型):
- 先探测,后执行——不假定项目装了 uv、不假定 Node 版本
- 绝不污染全局——禁止裸
pip install <pkg>(会装进系统 Python)、禁止npm i -g - 不擅自安装或切换用户环境——uv / fnm 不存在就提示并询问,不自行安装;不
fnm install新版本、不改fnm default。安装工具链是改变用户机器状态,需要授权
- 优先级链:用户显式指定 > 项目既有约定(lockfile /
.python-version/.nvmrc/packageManager字段)> 默认推荐。项目约定优先于口头指定——lockfile 是事实 - 默认推荐:Python →
uv run <命令>(含uv run --with <pkg>跑一次性依赖);Node →fnm exec --using <ver> -- <命令>+pnpm(一次性工具用pnpm dlx,不用npx)。跑不通时按 SSOT 的三步降级链处理(fnm env注入 → 标注实际版本后直跑 → 仍失败则报告用户),不自行安装工具链、不改全局默认版本 - 与产物卫生联动:
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) |
执行步骤
- 可用性检查:评审前确认
course-reviewer子 agent 是否可用(通过use_agent(course-reviewer))。 - 已创建 →
use_agent(course-reviewer),输入中指定【评审模式】【评审节点】【对照基准】【评审维度】(Phase 0 确认的对象 / 范围 / 学习目标;【评审维度】= 本技能review-dimensions.md全文)。 - 未创建 → 二选一,默认走"直接评审",不阻塞讲解流程:
- 直接评审(默认):主 agent 直接以两种角色定位执行评审。双实例节点须分两轮独立输出(先 pedagogy 完整评审一遍,再 learner 完整评审一遍),不得合并成一轮"综合评审"——合并即丧失独立性。
- 独立性约束:内联评审时新人视角不得走过场,必须逐项输出完整评审表(每维度至少 1 条意见或"无问题")。主 agent 同时扮演生成者 + 两个评审者 + 裁决者,独立性最弱,须以完整输出补偿。在
00-评审清单.md标注「主 agent 内联(子 agent 未创建,独立性受限)」,并提醒用户可创建独立子 agent 获得更独立的评审。
- 独立性约束:内联评审时新人视角不得走过场,必须逐项输出完整评审表(每维度至少 1 条意见或"无问题")。主 agent 同时扮演生成者 + 两个评审者 + 裁决者,独立性最弱,须以完整输出补偿。在
- 提醒创建:提示用户可按
create-sub-agent规范创建;用户同意则创建后回到正常委派流程。
- 直接评审(默认):主 agent 直接以两种角色定位执行评审。双实例节点须分两轮独立输出(先 pedagogy 完整评审一遍,再 learner 完整评审一遍),不得合并成一轮"综合评审"——合并即丧失独立性。
- 评审结论:无论何种方式,结论记入
00-评审清单.md(P0 清零才放行)。 - 评审清单强制检查点:
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 之外的调用方与消费方必须用 GitNexusimpact/context+search_content实证,不得凭 diff 文本推断(MCP 不可用时退回 grep + 源码阅读,结论须回到源码确认)。
断点续学
用户说"继续讲 XX""上次那个模块接着讲"时,跳过 Phase 0(对象与范围已定),直接定位落点:
定位档案:在
.teach/下按对象类型找目录(模块类{module-slug}/;变更类commits//prs//changes/),与用户口语主题模糊匹配。命中多个或零个 → 列出候选让用户选。读状态:先看
00-评审清单.md(未勾选条目 = 对应评审未完成),再看00-*.md顶部的对象与范围确认 与「外部文档索引」小节(有则后续外部引用走索引,不重新建)。06-最终文档.md存在 = 已收尾。按序判定落点(命中即停):
# 条件 落点 1 清单有未勾选条目,且其对应产物文件已存在 漏评审 → 先补做该条目的评审 2 某阶段产物文件缺失 从该阶段继续(按编号顺序 00 → 01 → 02 → …) 3 变更类精简模式已完成,用户说"再详细点" 从 Phase 4 起补完整模式(补 03 / 04 / 05 并更新 06) 4 前序齐全但 06-最终文档.md不存在Phase 7 汇总 5 全部完成 询问用户想做什么(深入某方向 / 知识点对齐 / 伴读分支 / 换对象) 第 1 条的判定关键是"产物是否已存在":清单未勾选 ≠ 漏评审——正常讲到 Phase 2 时,Phase 4 条目当然未勾选(还没做到)。只有产物文件已落盘而清单未勾选,才是真的漏评审。否则会误把"还没做到"当"漏评审",卡死正常续学。
Phase 8 独立触发不受此流程约束("考我一下"直接进 Phase 8,见该阶段说明)。
Phase 0:确认对象与范围
先向用户确认(不要跳过;Phase 8 独立触发时无需经过本阶段):
讲解对象类型(
module/commit/pr/change):通常可从用户措辞直接判定,不必单独问:用户措辞信号 对象类型 "这个模块 / 这块代码 / 这个包 / 这个目录" + 代码路径 module"这个 commit / 这次提交 / {sha}" commit"这个 PR / MR / !123 / 这个合并请求" pr"这批改动 / 我改了这些还没提交 / A 版本到 B 版本之间" change给了路径但同时在说"这次改动" 追问一句:"想听这个模块本身,还是这次对它的改动?" 目标:
- 模块 → 路径或目录名(用户未指定时用
list_dir让其选择)。 - 变更 → commit sha / PR 号 / diff 范围(用户未指定时用
git log --oneline -20列出让其选择)。
- 模块 → 路径或目录名(用户未指定时用
知识范围(三选一,可多选):
通用:该模块用到的语言特性、框架、算法、设计模式、协议等跨项目通用知识 → 讲解时引用权威外部文档。专用:仅在本项目 / 本模块成立的概念、约定、状态机、业务规则、模块间耦合。两者都含。- 默认:若用户未明确选择,自动设为
两者都含,并在大纲中标注"默认范围,可调整"。
学习目标:用户想达成什么。目标决定讲解深度:
读懂(默认):概览级,重在理解"它是什么、怎么工作、数据怎么流"。改造:在读懂基础上,额外产出 "改造风险点 + 建议切入点" 小节(附在最终文档末尾),标注哪些部分改动风险高、哪些可安全重构。评审:在读懂基础上,额外产出 "潜在问题清单 + 改进建议" 小节(附在最终文档末尾),按安全性 / 性能 / 可维护性 / 可测试性分类列出(详见 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 文件)、且用户明确说"一起讲",也可以不拆。
命中拆分条件时执行:
- 用
list_dir列出目录树,按以下优先级识别逻辑子模块:- 优先级 1 — 目录层级:子目录直接作为子模块边界(如
module/core/、module/utils/)。 - 优先级 2 — 命名约定:同一前缀的文件归为一组(如
order_create_*、order_cancel_*)。 - 优先级 3 — 依赖关系:用
search_content搜索import/require,将高度内聚的文件聚为一组。
- 优先级 1 — 目录层级:子目录直接作为子模块边界(如
- 产出拆分方案(Markdown 表格:子模块名 / 包含文件 / 一句话职责),提交用户确认(可修改)。
- 用户拒绝拆分时:回退到不拆分的路径——跳过子模块独立处理,直接进入 Phase 1,但在
00-能力大纲.md顶部标注⚠️ 模块较大({N} 文件),用户选择未分批讲解,部分内容可能不完整。 - 用户确认后,每个子模块独立走一遍 Phase 1–6,产物写入
.teach/{module-slug}/sub-modules/{sub-slug}/。子模块默认走精简路径:Phase 1 / 2 / 3 / 7 必做(大纲 / wiki / 正确性核对 / 子模块最终文档),Phase 4–6 仅在该子模块是核心链路(含状态机 / 异步 / 复杂数据流)时才做——子模块不是独立交付物,每个都完整走 7 个阶段会让大模块讲解产出 7×N 份文档。 - 全部子模块完成后,在
.teach/{module-slug}/根目录产出 汇总版00-能力大纲.md(全局视角)+ 最终文档,整合各子模块要点。 - 汇总完整性检查(必须执行):
- 确认所有子模块已在汇总版中被提及(逐个勾选)。
- 确认子模块间依赖关系图覆盖所有跨子模块的
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「通用格式规范」。
落盘时三件事(缺一不可):
- 初始化
00-评审清单.md:按计划评审节点一次性占位全部条目(- [ ])。模块类占位:大纲评审 + 解读评审 + 收尾评审;变更类精简模式只占位 2 条评审(01-逐处解读评审 + 收尾评审)+ 1 条质量闸门(02-正确性核对)——模板见 reference.md §8。占位是防漏的唯一机制:评审只写成流程文字,长流程里必漏(历史教训)。占位了 = 断点续学时可被发现并补做。
- 大纲评审:按「course-reviewer 评审执行规则」评审本阶段产物(教学法视角单实例),P0 清零后勾选
00-评审清单.md对应条目。变更类精简模式跳过本项(清单只占位 2 条评审 + 1 条质量闸门,不含大纲评审)。 - 产物卫生:这是全流程首个落盘点,执行「产物卫生」第 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 之前)回到本阶段补做——意图权衡常要对照框架官方的变更说明 / 迁移指南。
- 列出文档站清单:按 Phase 1 大纲里标注
[通用]的知识点,定出要参考的官方站(1–3 个)。例:模块用了 SQLAlchemy →docs.sqlalchemy.org;涉及某协议 → 该协议 RFC / 官方站。非官方来源(博客 / 教程站)不进索引。 - 按
web-index做准入与执行(判定规则不在此复制,见use_skill("web-index")的「被其它 skill 集成 · 规模判断」):- 已在
.web-index/INDEX.md在册 → 消费模式,查表即可,不重建 - 未收录 → 模块讲解跨多个阶段且档案会被反复查阅,天然满足"≥2 次查阅" → 建造模式,按其阶段 0–5 执行
- 已在
- scope 按模块实际用到的部分收窄:不要整站建(文档站动辄上千页)。例:只用了 ORM 的查询 API → 收窄到查询 / 会话相关分支。
中间产物须登记:抓取脚本会把候选链接表写到
temp/web-index-{slug}-map.md。创建即记下路径(见「产物卫生」第 3 条),收尾时按记录清理。 - 落点与提示:索引落在项目根(与
.teach/同级),结构由web-index管。时序(必读):本阶段须在 Phase 1 第 3 件事(产物卫生首次提示)之前执行——首次落盘提示只此一次,若先提示了
.teach/才生成.web-index/,结果只能是"漏提示"或"违约重复提示"二选一。同一次提示里说明两个目录(".teach/与.web-index/已生成于项目根目录,是否提交由你决定")。 不代为提交、不擅自加.gitignore(本技能不动用户的忽略规则)。 - 登记:在
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 命名),引用;选型规则见 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 对照已提炼进最终文档(最终文档是精简模式的门面,不能只剩大纲) - 检查不通过时,在文档顶部标注
⚠️ 完整性待补并列出缺失项
收尾三件事(缺一不可):
- 收尾评审:按「course-reviewer 评审执行规则」评审
06-最终文档.md(双实例;变更类精简模式单实例),P0 清零后勾选00-评审清单.md的收尾条目。 - 接力提示词:在最终文档末尾写入下一阶段接力提示词(模板见下),并在对话中原样贴给用户。
- 产物卫生:① 按记录清理本轮产生的中间草稿 / 临时验证脚本(第 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/2 题目来自历史答错的知识点——换表述 / 换角度重测,不直接照搬原题。
- 补充新题避免重复:其余题目从尚未考过 / 未错过的知识点生成,且与历史题目不重复。
- 首轮:直接基于易混点生成。
- 去重依据(强制):以「知识点标签 + 题干核心实体」作为题目身份指纹,与
quiz-history/下所有 round 文件的指纹比对,命中则视为重复、必须换题。 - 状态不一致兜底:若
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")