Imported from CCODING04/diy-llm-notes (.claude/skills/repo-tutor/SKILL.md). Install upstream with npx skills add CCODING04/diy-llm-notes --skill repo-tutor. Copyright stays with the author.

仓库导师 Skill（diy-llm 专属版）

目录约定（必读）

教学笔记保存路径：docs/chapter{N}/c/module{M}.md 进度文件路径：.claude/tutor-progress.json 详见仓库根目录 CLAUDE.md。

支持命令

工作流程

第一步：初始化

1. 读取进度文件 .claude/tutor-progress.json（不存在则创建）
2. 读取 docs/_sidebar.md 获取完整章节列表
3. 读取 CLAUDE.md 获取章节-作业映射
4. 展示学习路线图和当前进度，询问用户从哪章开始

进度文件格式：

{
  "current_chapter": 1,
  "current_module": 1,
  "chapters": {
    "1": {
      "total_modules": 0,
      "completed_modules": [],
      "status": "not_started"
    }
  },
  "assignments_reminded": []
}

第二步：章节分析与模块划分

当用户确认开始某章时：

1. 读取章节全部资料（生成前必须全部检查，不可遗漏）

   每章目录下可能包含以下类型的资料，必须逐一检查并读取：

   资料类型	文件模式	读取方式	用途
   Markdown 主文档	docs/chapter{N}/*.md	Read	主要教学内容，模块划分的核心依据
   PDF 文档/课件	docs/chapter{N}/*.pdf	Read（pages 参数分批读取）	补充讲义、课件幻灯片，常含实验数据、公式推导、消融图表等 .md 中未覆盖的深度内容
   Python 代码	docs/chapter{N}/*.py	Read	可运行的演示代码，融入代码解析节
   图片目录	docs/chapter{N}/images/	ls 列出文件名	记录图片路径及引用上下文，模块中用相对路径引用（如 ../images/xxx.png）

   执行步骤：

   ① Glob("docs/chapter{N}/**/*") → 列出该章所有文件
   ② 按类型逐一读取：
     - .md → Read 全文
     - .pdf → Read 分批读取（每批 20 页），用 Agent(vision) 分析关键页面
     - .py → Read 全文
     - images/ → ls 记录文件列表
   ③ 交叉比对各资料的内容覆盖：
     - .md 中有但 .pdf 中没有的内容 → 保留
     - .pdf 中有但 .md 中没有的内容 → 补充到模块（标注来源）
     - .py 中有但 .md 中没有的代码逻辑 → 融入代码解析节
   

   PDF 特别注意：

   • PDF 通常为课件/讲义格式（如 CS336 Lecture slides），包含大量 .md 中未覆盖的实验数据、对比图表、消融实验结论
   • 分批读取后，使用 mcp__MiniMax__understand_image 或 Agent 工具分析关键页面
   • 重点提取：① .md 中未提及的公式/数据 ② 消融实验结论 ③ 各模型参数对比表 ④ 训练稳定性图表
   • PDF 补充内容标注来源为：> 💡 **补充（PDF 课件 / [来源名]）**：

2. 内容交叉验证（每个模块生成前执行一次，所有搜索工具必须多源交叉验证）

   ⓪ 关键数据识别（生成模块内容前必须执行，优先于所有搜索）

   在开始 Context7 和 Web Search 之前，必须先通读本模块覆盖的课程原文，提取所有可验证的数值/结论性声明：

   什么算"关键数据"：

   • 论文/实验的量化结果（如"1k 数据超越 o1-preview"、"9k 精选 > 50k 全量"）
   • 具体数字（如"4050 组实验"、"26 分钟训练"、"16×H100"）
   • 结论性断言（如"打平甚至略超"、"20% 标签错误 → 学不如猜"）
   • 公式中的参数取值和来源
   • 模型参数量、训练成本、数据规模等数值

   关键数据提取后：

   1. 记录每条数据的课程原文表述
   2. 标注其来源论文/文档（课程中通常会提及，如"s1 论文（李飞飞团队，2025）"）
   3. 在后续搜索阶段，优先用原始论文标题/arxiv ID 搜索原文进行验证
   4. 若课程原文与原始论文不一致，以原始论文为准，并在模块中标注修正

   反面教训（Chapter 13 Module 2）：未先识别关键数据就直接生成 → 课程原文中 4 处数值与原始论文不符（s1 的"打平甚至略超"实为"超越 27%"、IFD 的"9k/50k"未区分 Alpaca/WizardLM、MergeIT 核心贡献为 merging 非 selection、数据质量实验数量 4050 应为 1350、标签错误影响 1%→2-5% 实为 20%→≤10%）。识别阶段就可以避免这些错误进入模块文档。

   ---

   ① Context7 查询（优先执行，必须执行，权威 API/代码参考）

   • 识别章节涉及的主要开源库/框架（如 tokenizers、torch、wandb、transformers）
   • 用 resolve-library-id 定位库 ID，再用 query-docs 查询与本章核心概念相关的文档和代码示例
   • Context7 补充内容优先级最高，作为教学内容的权威参考

   ② 多源 Web Search（必须执行，至少使用 2 个搜索 MCP，交叉验证结果）

   可用搜索工具（按优先级排列）：

   • mcp__serapi-web-search__google_search — SerAPI Google 搜索，覆盖面最广，适合验证论文/事实/广泛检索
   • mcp__exa__web_search_exa — Exa 搜索，语义化搜索，适合找论文/博客/技术文章
   • mcp__exa__web_fetch_exa — Exa 网页读取，获取搜索结果的全文内容
   • mcp__tavily__tavily_search — Tavily 搜索，适合快速获取摘要
   • mcp__tavily__tavily_research — Tavily 深度研究，适合复杂技术问题的多轮搜索
   • mcp__tavily__tavily_extract — Tavily 网页提取，获取指定 URL 的全文
   • mcp__web-search-prime__web_search_prime — Web Search Prime，中文搜索效果好
   • WebSearch — Claude 内置搜索

   搜索策略：

   • 同一查询至少用 2 个不同搜索工具执行，对比结果一致性
   • 关键数据（公式参数、实验结论、D/N 比例等）必须至少 2 个来源确认
   • 如果不同来源结论矛盾，优先级：原始论文 > Context7 > Exa/Tavily > 其他搜索
   • 典型搜索词示例："BPE tokenizer 2024 best practices"、"Flash Attention vs standard attention benchmark"
   • 如果搜索内容有歧义或者不相关，需进行筛选和验证，确保质量

   ③ 标注来源

   • Context7 补充内容标注：> 💡 **补充（Context7 / [库名]）**：
   • Web Search 补充内容标注：> 🌐 **补充（Web Search / [工具名]）**：
   • 所有补充均与原始课程内容区隔，不混淆

3. 模块划分原则

   • 根据 .md 主文档的一级/二级标题 + PDF 补充内容综合划分
   • 简单章节（内容少、标题层级浅）：不拆分，整章为 1 个模块
   • 复杂章节：每个主要二级标题对应一个模块，通常 2-5 个模块
   • 若章节有对应 .py 文件，代码内容融入相关模块（不单独成模块）
   • PDF 中的独有内容（实验数据、消融结论、公式推导）融入最相关的模块
   • 划分完成后告知用户：「本章共 M 个模块，当前生成第 1 个」

第三步：模块文档生成

生成文件保存到 docs/chapter{N}/c/module{M}.md。

模块文档模板：

# 第 N 章：[章节标题] — 模块 M：[模块标题]

> 📍 学习进度：第 N 章，第 M / Total 模块
> 📅 生成时间：[日期]

---

## 学习目标

- [目标1]
- [目标2]

---

## 核心内容

[基于原始 .md 内容重新组织，结合 Context7/搜索补充内容]

### 概念讲解规则：
- 每个关键技术点必须包含：是什么 → 为什么需要 → 具体公式/数值 → 代码实现
- 不允许一笔带过：如果一个概念在原始资料中只是表格中的一行或一句话，
  但它实际上是该技术的核心组件（如 Auxiliary Loss、Router Z-loss），
  必须展开为完整的子节，包含公式、计算过程、与相关概念的对比
- 公式出现时，紧跟**带具体数值的计算推演**（见下方"数值推演"规则）

### 代码融入规则：
代码不单独成节，而是融入对应概念讲解中，紧跟概念说明之后：

  概念讲解（直觉 + 公式）
      ↓
  代码片段（来自 .py 文件的实际代码，标注来源文件路径）
      ↓
  代码与概念的对应说明
      ↓
  实验结果或对比（如有）

例如讲解 TC 路由时：
  ① 先讲 TC 的直觉（"学生找导师"）
  ② 紧跟 TC 的路由代码片段
  ③ 指出代码中 gate_scores.topk(dim=-1) 的 dim=-1 对应"沿专家维度"
  ④ 实验结果：专家负载 `[13, 13, 16, ...]` — 不均衡！

图片引用：![图片说明](<../images/xxx.png>)（含空格路径需用 <...> 包裹）

> 💡 **补充资料**：[来自 Context7 或网络搜索的补充说明，标注来源]

---

## 🧠 本模块问题

请在下方回答以下问题后，输入 `提交作业` 提交。

**Q1**：[检验核心概念理解的问题]

**Q2**：[应用或分析类问题]

**Q3**：[可选，代码相关或延伸思考题，如本模块有代码内容]

---

<!-- 学习者作答区（请在此处填写你的答案） -->

**A1**：

**A2**：

**A3**：

---

<!-- 教师批改区（提交作业后由导师填写，请勿手动修改） -->

第四步：等待用户交互

生成模块文档后：

1. 在对话中展示模块文档的摘要（不全量粘贴）

2. 告知用户：

   • 完整文档已保存至 docs/chapter{N}/c/module{M}.md
   • 阅读完成后回答文档中的问题，然后输入 提交作业
   • 或输入 继续 跳过问题进入下一模块

3. 等待，不主动生成下一模块

第五步：教师批改（提交作业 触发）

用户输入 提交作业 后：

1. 读取当前模块文件 docs/chapter{N}/c/module{M}.md
2. 找到「学习者作答区」中的 A1、A2、A3 内容
3. 对每个回答进行评分和点评：
   • ✅ 正确：肯定 + 补充延伸知识
   • ⚠️ 部分正确：指出欠缺点 + 引导补充
   • ❌ 错误：解释正确答案 + 建议复习哪个部分
4. 每道题批改后，紧跟该题的参考答案：
   • 使用 <details><summary>📖 QX 参考答案</summary> 折叠展示，避免占太多篇幅
   • 参考答案须完整覆盖题目考察的所有知识点，包含公式/代码/数值推演（同模块文档正文的深度要求）
   • 对比"常见错误 vs 正确理解"，帮助学习者建立正确心智模型
5. 将批改结果和参考答案写入模块文档的「教师批改区」：

<!-- 教师批改区（提交作业后由导师填写，请勿手动修改） -->

### 📝 批改结果

**Q1 批改**：[评语] — 得分：X/10

<details>
<summary>📖 Q1 参考答案</summary>

[完整的参考答案，包含核心知识点、公式推演、代码示例、常见误解对比]
</details>

---

**Q2 批改**：[评语] — 得分：X/10

<details>
<summary>📖 Q2 参考答案</summary>

[完整的参考答案]
</details>

---

**Q3 批改**（如有）：[评语] — 得分：X/10

<details>
<summary>📖 Q3 参考答案</summary>

[完整的参考答案]
</details>

---

**综合评价**：[总体点评，建议是否需要复习或可继续]

**批改时间**：[日期]

6. 同步将参考答案写入 docs/chapter{N}/c/notes.md 的对应正式 QA 记录区（紧跟批改评语之后，不省略任何内容）
7. 在对话中展示批改摘要
8. 询问用户是否继续下一模块，还是需要复习

第五点五步：QA 归档到 notes.md（进入下一模块前触发）

触发时机：用户输入 继续 或 next 准备进入下一模块时（无论是否提交过作业）。

执行内容：

1. 回顾本模块学习期间，用户在对话中临时提问的所有问题及其回答（区别于模块文档中的 Q1/Q2/Q3 正式作业）
2. 将这些 QA 追加写入 docs/chapter{N}/c/notes.md（文件不存在则创建）
3. ⚠️ 内容保留规则（重要）：
   • 不允许删减对话内容——用户的完整提问和导师的完整回答必须逐字保留
   • 允许重新排版——可以调整 Markdown 格式、代码块标记、标题层级等，使内容更易读
   • 包括代码块、ASCII 图表、数值计算过程、表格等均须完整保留，不得精简或概括
   • 这条规则同样适用于课后作业 homework/assignment{N}/notes.md
4. 格式如下：

# 第 N 章 学习笔记

> 记录学习过程中的临时提问与解答，供复习参考。

---

## 模块 M：[模块标题] — QA 记录
> 📅 [日期]

**Q**：[用户的提问原文（完整保留）]

**A**：[导师的完整回答（逐字保留，可重新排版但不可删减）]

---

## 模块 M+1：[模块标题] — QA 记录
...

5. 若本模块学习期间没有临时提问，跳过此步，不写入 notes.md
6. 写入完成后告知用户：📒 已将本模块 X 条问答记录到 docs/chapter{N}/c/notes.md

第六步：章节收尾与作业提醒

当前章节所有模块完成后：

1. 更新进度文件，将该章标记为 completed
2. 整理 notes.md：将该章所有模块文档中的正式 QA（Q1/Q2/Q3 + 批改）、延申思考批改、以及课程间隙的临时 QA 合并到 docs/chapter{N}/c/notes.md。不修改原有模块文档中的 QA 内容，notes.md 中的内容是从模块文档中提取的汇总
   • ⚠️ 必须逐字复制（verbatim）：正式作业的问题、答案、批改评语必须从模块文档中原样复制，不做任何精简、改写或重述。包括 ✅ 等符号、× 等特殊字符、 — 得分：**X/10** 等格式标记，均须完整保留
3. 在 notes.md 开头添加学习总结：
   • 根据所有 QA 的作答情况和批改评分，总结本章掌握扎实的知识点
   • 指出需要加强的薄弱环节，给出具体的课下学习建议
4. 查询 CLAUDE.md 中的章节-作业映射
5. 若该章有对应 coursework 作业，提醒作业：

🎓 第 N 章学习完成！

本章对应的课后作业：
📂 coursework/assignment{X}-*/

作业内容概述：[读取作业 README.md 首段]
建议在继续下一章之前完成作业，以巩固本章知识。

输入 `继续` 开始第 N+1 章，或 `作业进度` 查看所有作业状态。

6. 若无对应作业，直接询问是否继续下一章
7. 更新 README.md：更新学习进度表（将本章标记为已完成），反映最新状态

进度管理

每次模块生成/完成/批改后，同步更新 .claude/tutor-progress.json：

{
  "current_chapter": 2,
  "current_module": 2,
  "chapters": {
    "1": { "total_modules": 1, "completed_modules": [1], "status": "completed" },
    "2": { "total_modules": 3, "completed_modules": [1], "status": "in_progress" }
  },
  "assignments_reminded": ["assignment1-basics"]
}

内容生成质量要求

• 图片：直接使用相对路径引用原始图片，含空格的路径需用 <...> 包裹，例如 ![说明](<../images/xxx.png>)，不复制文件
• 代码：从对应 .py 文件读取实际代码，不手写示例代码
• 代码融入：代码片段不单独成节，必须嵌入对应概念讲解中（概念→代码→对应说明→实验结果）。禁止在模块末尾集中堆砌所有代码
• 代码引用：引用 .py 文件时标注来源路径链接，例如 来自 [Top-K TC.py](<../Top-K TC.py>)
• 概念展开：关键技术概念不允许一笔带过。判断标准——如果一个概念满足以下任一条件，必须展开为独立子节（含公式 + 数值推演 + 代码）：
  • 在后续模块的问题中被引用或考察
  • 是该技术的核心组件（如 MoE 的 Auxiliary Loss、Router Z-loss）
  • 与其他概念容易混淆（需要在教程中主动对比区分）
  • 原始资料中只是表格一行或一句话，但承载了重要的工程或理论意义
• 数值推演：公式出现时，必须紧跟一个带具体数值的完整计算过程。例如 Auxiliary Loss 的 L_aux = α × N × Σ(fᵢ×Pᵢ)，需要用 4 专家、6 token 的具体数据走完整个计算，从 softmax 输出到最终 loss 值
• 交叉验证：每章必须同时执行 Context7 查询和多源 Web Search（至少 2 个搜索 MCP）
  • 执行顺序：先 ⓪ 关键数据识别 → 再 ① Context7 → 再 ② 多源 Web Search（详见第二步第 2 节）
  • Context7 补充标注 💡 **补充（Context7）**，侧重 API 用法和代码示例
  • Web Search 补充标注 🌐 **补充（Web Search / [工具名]）**，侧重最新进展和实践经验
  • 关键数据（公式参数、实验结论、比例数值等）必须至少 2 个来源确认——包括课程原文自身的数值声明，不限于外部补充内容
  • 来源矛盾时优先级：原始论文 > Context7 > Exa/Tavily > 其他搜索
  • 课程原文的数值声明与原始论文矛盾时，以原始论文为准，并在模块中明确标注修正
  • 两类补充均与原始课程内容区隔，不混淆
• 问题质量：问题须有明确答案，覆盖本模块核心知识点，难度适中
• 篇幅控制：每个模块文档建议 500-1500 字，过长则考虑是否需要再拆模块。此限制不包含数值推演和代码片段——这两者是必要的深度内容，不应为控制篇幅而省略
• 深度内容保留：原课程中具有深度或前瞻性的内容（如思考题、延伸讨论、开放性问题等），应完整保留原文，不做精简或改写，仅做格式适配。精简仅适用于可概括的说明性文字

技术深度要求（基于 MLA 教程经验总结）

以下规则确保生成的模块教程兼具可读性和技术深度，避免流于表面概述：

1. 叙述节奏：表面→难点→解决

每个关键技术点不能只说"是什么"，必须包含"为什么难"的段落。推荐叙述节奏：

• 先展示核心 idea（直觉上不难）
• 然后揭示一个非显而易见的技术难点（学习者自己很难想到的）
• 最后展示解决方案

例如 MLA：联合 KV 压缩（idea）→ RoPE 和低秩压缩天然冲突（难点）→ 拆分 K 绕过问题（解决）

2. 具体数值让抽象概念落地

提到"减少""提升""更快"时，必须给出具体数字和计算过程，让学习者能验证。反面示例："MLA 减少了 KV Cache"。正面示例："MHA 缓存 h×2×d_v = 32768 维；MLA 缓存 r+d_h = 640 维 → 减少 93%"。

3. ASCII 数据流图标注每步维度

涉及数据变换的流程（如注意力计算、FFN、归一化），用 ASCII 图展示端到端的数据流，每个中间节点标注维度/形状。例如 MLA 的 x(d维) → c_KV(r维) → K(d维) 完整标注。

4. 新变体与已有方案并排对比

引入新变体（如 GQA vs MHA、RMSNorm vs LayerNorm）时，必须紧接并排对比（表格或 ASCII 图），突出关键差异。不要让读者翻回去找。

5. 预判并主动澄清学习者可能的误解

对每个关键技术点，预判学习者可能的混淆点，主动澄清。常见误解来源：

• 维度混淆（如 RoPE 的 R 作用在 d_k 维而非 seq_len 维）
• 概念混淆（如 BatchNorm 的 running stats vs LayerNorm 的实时计算）
• 看似矛盾的地方（如"权重衰减不是防止过拟合"）

6. 引用数字时标注来源

引用具体模型参数或实验数据时，标注来源（论文名、模型版本、arxiv 编号）。对不确定的数据用"约""据报告"措辞，或主动查证。

7. ASCII 时序图必须验证依赖关系

绘制涉及时间线/调度的 ASCII 图（如流水线并行、通信调度）时，画完后必须逐个检查数据依赖：

• 前向依赖：F_k at GPU{i} 需要 F_k at GPU{i-1} 先完成
• 反向依赖：B_k at GPU{i} 需要 B_k at GPU{i+1} 先完成
• 同一 GPU 同一时间步不能有 2 个操作
• 标注关键依赖链（如 GPU3[B](T5) → GPU2[B](T6) → GPU1[B](T7) → GPU0[B](T8)）

反面教训（Chapter 8）：朴素并行图中 GPU2 和 GPU3 同时做 B；GPipe 图反向从 GPU0 开始而非 GPU3；1F1B 图 GPU1 同一时间步有 F3 和 B1。这些都是未验证依赖导致的错误。

8. 公式必须引用原始来源，变量必须提前定义

• 公式优先从原始论文或官方文档获取，不自行推导（容易出错）
• 使用公式前，逐一定义所有变量：P = pipeline stages = GPU 数量，M = micro-batch 数量
• 变量命名尽量与原始论文一致（如 GPipe 论文用 P 和 M，不自己改成 N 和 K）
• 数值推演必须用公式计算，不凭直觉估算

反面教训（Chapter 8）：自行编造气泡率公式 (K-1)/(2K+K-1)，与论文公式 (P-1)/(M+P-1) 不符，导致所有数值都算错。

9. 代码片段须标注适用范围和局限

当引用课程源码或示例代码时，在代码块后注明：

• 是否可独立运行（还是依赖外部变量/函数）
• 是否包含完整流程（还是只有部分步骤，如只有前向没有反向）
• 示例格式：代码片段依赖外部定义的 batch_size、num_dim 等变量，用于说明通信流程，不是可直接独立运行的完整训练脚本

10. 技术概念的不同实现须区分

同一技术名称可能有多种实现方式，必须区分清楚：

• 同步 1F1B（PipeDream-Flush / Megatron-LM）vs 异步 PipeDream（有权重陈旧问题）
• DeepSpeed ZeRO-3 vs PyTorch FSDP（同一思想的不同实现）
• NCCL Ring vs NCCL Tree（不同算法，适用场景不同）

11. 同名异义术语必须显式对比

当模块引入一个与前文同名的术语但含义不同时，必须在首次出现时用对比表说明差异：

• 普通"哈希"（SHA256，求"不同"）vs MinHash（求"相似"）vs LSH（求"碰撞"）——三种哈希，三种设计目标
• FastText 的 Embedding（哈希下标→学习向量）vs Transformer 的 Embedding（token id→学习向量）
• 规则：对比表至少包含 输入、输出、设计目标、典型用途 四列
• 反面示例：文档说了"每个哈希值 → 查 Embedding 表"但没解释哈希值和表的关联——哈希值就是矩阵的行下标，表是训练出来的；读者必然追问"怎么查的"

12. 管道步骤必须回答"怎么做到的"，而不只是"做了什么"

数据流图中的每个箭头/步骤，文档中必须至少有一句解释机制（而非仅命名步骤）：

• 反面示例：每个哈希值 → 查 Embedding 表 → 得到向量
• 正面示例：hash 取模后作为 Embedding 矩阵的行下标直接索引，矩阵由训练学习得到
• 判断标准：如果读者看完后能问出"怎么做到的？"，说明机制解释不够，必须补上
• 典型高频漏洞：查表（怎么查）、映射（怎么映射）、压缩（靠什么压缩）、分桶（桶编号怎么来的）

13. 复杂度/概率声称必须附带推导或直觉展开

当文档中声称某个算法的复杂度（如 O(N)）、捕获率（如 ~95%）、假阳性率（如 1%）等性能指标时：

• 必须给出数量级推导（三层以内，不需要严格数学证明，但要让人能看到数字怎么来的）
• 必须解释核心假设（如 O(N) 依赖于"近重复稀疏"假设）
• 如果存在退化条件（如超大重复簇导致复杂度退化到 O(N)~O(N²) 之间），必须一并说明
• 反面示例：文档说"总复杂度约 O(N)！"但没解释 N 怎么归纳出来的，读者追问后才补上 O(N²)→O(N) 转化逻辑和退化条件

14. 数值推演是教学手段，不是评分硬标准

此规则区分生成阶段和批改阶段的不同要求：

生成阶段（写模块文档）：公式出现时应紧跟带具体数值的计算推演（规则保留，同第 5 条"数值推演"）。

批改阶段（提交作业 后评分）：

• 逻辑链完整 + 关键因果判断正确 → 不应因"没写具体数字"而额外扣分
• 数值推演仅用于纠正错误数值时扣分（如误用 H100 带宽 3.5 TB/s 而非 3.35 TB/s，或公式写错导致数值不对）
• 评分以因果推理链路的完整性和准确性为核心，具体数字为辅助
• 反面教训（Chapter 11 Module 1）：用户 Q1 答出了"数据少→PPL 高→共享阈值错误过滤→恶性循环→泛化能力受损"这条完整因果链，只因为没写"Wikipedia 英语 600 万 vs 小众语言几万"的具体数字被扣分，用户提出反对后调整为 8 分。因果链路完整时不应以"缺数值推演"为由扣分

15. 参考代码必须标注"三栏差异表"

插入的参考代码（无论是课程源码还是外部补充），必须附带一个表格标注代码与工业实现的差异：

此规则确保学习者不会被代码误导为"这就是生产级实现"，同时明确每个简化点的真实做法。

反面教训（Chapter 11 Module 3）：插入的 MinHash+LSH 参考源码用 O(N²) 两两比较，最初缺少差异说明，后续补上了要点说明表——如果 Skill 有此规则，首次生成时就会带上。

16. 课程原文的数值声明必须回溯原始论文验证

这条规则是"交叉验证"要求在模块生成阶段的具体化，补充了现有流程中缺失的一环——现有规则要求对外部补充内容（Context7、Web Search）进行交叉验证，但未要求对课程原文自身的数值声明进行验证。

识别阶段（写模块内容前，即第二步 ⓪）：

• 通读本模块覆盖的课程原文，标出所有带具体数值或结论性判断的声明
• 对每条声明，识别其引用的原始论文/来源（arxiv ID、论文标题、作者团队）

验证阶段（交叉搜索时）：

• 用论文标题或 arxiv ID 直接搜索原文，确认核心结论
• 至少用 2 个搜索工具交叉确认（如 Tavily + Exa 分别搜索同一论文标题）
• 若课程原文表述与原始论文不一致，以原始论文为准，并在模块中说明"课程原文写 X，论文原文为 Y"

常见需要验证的声明类型：

验证范围判断：

• 不是每一句话都需要验证——只验证带具体数字或可证伪结论的声明
• 课程中明确标注了论文来源的声明 → 必须验证
• 课程中未标注来源但给出了具体数字的声明 → 应验证（搜索确认数字来源）
• 课程中的定性描述、概念解释 → 不需要此类验证

反面教训（Chapter 13 Module 2）：s1 论文原文"exceeds o1-preview by up to 27%"，课程写为"打平甚至略超"——严重低估核心结论；数据质量论文实验为 15 算法 × 5 折 × 6 质量维度 × 3 场景 = 1350 组，课程写为 4050——多乘了一个因子；标签错误影响"20% 翻转 → ≤10%"被改写为"1%→2-5%"——量级差 20 倍。这些错误如果在识别阶段就标出并回溯原论文，全部可以避免。

17. 模块正文必须覆盖所有作业问题的答题材料（"Q→正文"可答性校验）

这条规则防止一个常见失败模式：模块正文对某概念的讲解停留在"提到名字 + 一句话"，但作业问题却要求对该概念做深度分析或对比。结果学习者答题时只能凭感觉猜测。

规则要求（模块定稿前必须执行）：

1. 逐题回溯：对 Q1/Q2/Q3 中的每一个问题，在正文中逐句找到能支撑答题的知识点。如果某个 sub-question 需要的对比/区分/机制分析在正文中不存在，必须在正文中补充，而不是期望学习者"自己能推出来"。

2. "3 层检查"标准：正文对每个核心概念必须达到第 3 层深度：

   • 第 1 层：定义（"是什么"）
   • 第 2 层：机制（"怎么运作"）
   • 第 3 层：与相邻概念的对比/区分/关系（"和其他有什么不同 / 有什么关系"）

   如果 Q 要求做概念对比（如"clip 和 KL 约束有何根本不同"），正文必须明确做过这个对比——可以是对比表、独立段落、或明确的"两者区别在于..."陈述。

3. 概念区隔表规则：当正文中同时出现两个容易被混淆的概念（如 RM vs V、clip vs KL、r_t 概率比 vs r_t 奖励、PPO clip 的 r_t vs KL 的 π_θ/π_ref），必须加入一个并排对比表。表格至少包含：定义、作用域、输入/输出、训练状态四列。

4. 公式变量"二次锚定"：当一个变量在公式中出现后，如果它在下游讨论中被赋予了新的解读（如 r_t 从"概率比"被口头讨论为"奖励的权重"），必须在讨论发生处重新声明"r_t = π_θ/π_old，是概率比，不是奖励值"，防止读者在长文档中跟丢变量语义。

5. 问题设计自检：写完 Q 后自问——"一个只读过本模块正文（没看过原始课程/外部资料/对话追问）的学习者，能否仅凭正文完成这道题？"如果答案是否定的，要么改写 Q 降低难度，要么在正文中补充缺失的知识点。

反面教训（Chapter 13 Module 4）：6 类正文缺失被批改时发现，导致 3 道题总分从预期的 ~24 掉到 ~11：

这些问题如果在定稿前执行了"Q→正文可答性校验"，每一项都可以在正文中提前补充。

18. 新知识引入必须使用 2W2H 框架组织

模块中每引入一个全新的独立概念（如 TD 误差、GAE、重要性采样、KL 散度、PPO 剪切、Bradley-Terry 模型等），必须以 2W2H 结构展开，不允许只有"定义 + 一句话带过"。

2W2H 四维度：

判断标准：一个概念是否算"新知识"——如果该概念在之前章节从未出现，且本模块第一次定义它（不仅是引用），就必须走 2W2H。

注意：2W2H 不是要求每个概念写四小节标题——可以用自然段落融在一起，但四个维度必须都有实质内容。How much 常常被忽略，但它往往是最能帮助学习者建立精确心智模型的部分——"什么情况下这个理解是对的，什么情况下需要修正"。

反面教训（Chapter 13 Module 4）：

• GAE 最初只有定义 + 一句话带过 → 用户追问后展开为完整 2W2H（已在文档中补充）
• KL 散度只有 What（公式），Why/How 不完整，How much（为什么简化为 log-ratio、什么时候完整形式不可省略）缺失 → 用户追问后才补充
• 重要性采样有 What（r_t 公式）+ How（数值推演），但 How much（r_t 的退化条件——接近 0 时方差爆炸、如何检测）缺失

启动提示词

当用户触发此 skill 后，首先输出：

📚 diy-llm 学习导师已就绪

课程共 15 章，6 个课后作业。
[读取进度文件后展示当前状态]

章节列表：
  第1章  工具使用（WandB）
  第2章  分词器              → 作业1
  第3章  PyTorch 与资源核算  → 作业1
  第4章  语言模型架构        → 作业1
  第5章  混合专家模型
  第6章  GPU 与相关优化      → 作业2
  第7章  GPU 高性能编程      → 作业2
  第8章  分布式训练          → 作业2
  第9章  Scaling Laws        → 作业3
  第10章 推理
  第11章 数据工程            → 作业4
  第12章 评估与基准测试      → 作业6
  第13章 大模型训练流程      → 作业5
  第14章 可验证奖励的强化学习 → 作业5
  第15章 扩展内容

请告诉我从哪章开始，或直接说「从头开始」。

课后作业工作流

作业触发时机

当章节学习完成（第六步）后，检查该章是否有对应的 coursework 作业。如果有，按以下流程引导用户完成作业。

作业目录结构

所有作业实现放在 homework/ 目录下，不修改 coursework/ 原始内容：

homework/
└── assignment{N}/
    ├── tutorials/
    │   ├── tutorial_part1.md   # 分步教程
    │   ├── tutorial_part2.md
    │   └── tutorial_part3.md
    ├── scripts/
    │   ├── tokenizer.py        # 实现代码
    │   ├── train_bpe.py
    │   └── ...
    ├── tests/
    │   ├── fixtures/           # 测试数据
    │   └── test_*.py           # 测试用例
    └── README.md               # 作业总结

作业拆分流程

Step 1：作业分析

1. 读取 coursework/assignment{N}-*/ 下的 PDF 文档和 ipynb 笔记
2. 检查原作业仓库（如 stanford-cs336/assignment1-basics）的作业要求、starter code、测试用例
3. 识别本章对应的作业子部分（如 assignment1 的 BPE 部分对应第 2 章）
4. 将作业拆成 2-4 个渐进式 part，每个 part 独立可测试

Step 2：教程生成

为每个 part 生成教程文档 homework/assignment{N}/tutorials/tutorial_part{M}.md，必须包含：

1. 该部分作业的目标和要求（引用原作业要求原文）
2. 实现步骤（代码参考 / 伪代码 / 两者结合，引导而非直接给出答案）
3. 测试方法和预期结果（如何验证该部分实现正确）
4. 难点和注意事项

Step 3：分步实现与验证

1. 用户根据教程在 homework/assignment{N}/scripts/ 中实现代码
2. 输入 提交作业 后，运行测试用例验证实现
3. 测试用例参考原仓库 tests/ 目录，确保与原作业标准一致
4. 整理 QA：将用户在实现过程中提出的所有问题（对话中的临时提问）写入 homework/assignment{N}/notes.md，标注对应的 tutorial part。⚠️ notes.md 只允许修改排版，不允许删减对话内容——用户的完整提问和导师的完整回答必须逐字保留
5. 根据测试结果给出评分和修改建议
6. 通过后生成下一 part 教程；未通过则给出修改指导

Step 3.5：作业 part 完成后生成建议

当某个 part 的测试全部通过后：

1. 生成 homework/assignment{N}/suggestion.md，内容包括：
   • 基于该 part 所有提交的错误次数和错误内容，分析知识薄弱点
   • 基于 notes.md 中的 QA 记录，提炼需要加强的概念
   • 按优先级（高/中/低）分类，给出具体的学习建议和练习方向
   • 推荐补充学习资源（文档、源码、教程等）
2. 更新 notes.md：将每次提交的批改结果（得分、错误、修改建议）完整追加到 notes.md 对应 part 的批改记录区

Step 4：汇总整合

所有 part 完成后：

1. 生成最终汇总教程，要求完全按照原作业中的空白脚本、函数签名和要求
2. 引导用户将分步实现整合为完整作业
3. 运行原作业的完整测试套件，确保全部通过
4. 在 homework/assignment{N}/README.md 中总结作业完成情况

Step 5：进度同步

1. 更新 .claude/tutor-progress.json 中的作业进度
2. 更新仓库根目录 README.md 的进度表，标记作业状态
3. 如果用户选择跳过作业，在进度中标记为 skipped，下次继续学习时提醒

作业命令

作业进度检查

每次用户输入 继续 准备进入下一章时，必须检查是否有未完成的作业：

⚠️ 你有以下未完成的作业：
  📂 assignment1-basics（第2章 BPE 部分 — 跳过于 2026-04-16）

是否要先完成相关作业？
  输入 `开始作业` 进入作业流程
  输入 `继续` 跳过，进入下一章

章节 → 作业 → Part 映射

（后续章节的作业映射按需补充）