docs: 层 2 关账——§6.1 远程实证勘误"预期见毛刺" + roadmap 存档点 + 接口回看

- docs/03 §6.1：两次远程跑（sanity/noclip）均平稳，勘误当初"预期毛刺"的错误
  预测；三条实证结论（爆炸真机制但本区间高度阻尼、grad_norm 是裁剪前值、层 5
  真正杀手锏是 logit-free）
- roadmap 存档点：层 2 ✅ 关账，判据全过、关键发现、接口回看（全判"深"，
  三条不返工小注）；章节索引 03 标已关账；下一步层 3

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/00-roadmap.md

@@ -8,14 +8,16 @@
 > 每次断点（层完成/工作暂停）更新此节。恢复上下文时：读 CLAUDE.md → 本节 → 对应章节文档。
 
 - **日期**: 2026-07-19
-- **当前层**: 层 2（white-box OPD），**代码已完成（U1-U5 全绿，66 单测通过）**，待远程冒烟
-- **层 2 远程冒烟待办（下一步，用户在远程机执行）**: `bash scripts/train_whitebox.sh sanity`（50 步）。三盯：① `nvidia-smi` 确认 B=4/T=2048 不 OOM（白盒 = student+teacher 两份全词表 logits，§5 估算但未实测，OOM 阶梯：降 B→2、再开 gradient_checkpointing）；② KL loss 曲线应见**毛刺**（§4.1 梯度爆炸实况，截图留档给层 5 当有界乘子对照）；③ `distill/num_gen_tokens_per_step` 不塌成 0（生成没空转）。首跑会下载 teacher Qwen3-4B（GB 级）到 /data/zym/hf_cache
-- **层 2 代码构成**: U1 DistillConfig（configs.py，两温度分名/三处刻意缺席）；U2 token_divergence + 梯度爆炸单测（trainer.py，全词表 KL/JSD）；U3 SFTCollator prompt_only 模式（data.py）；U4 DistillTrainer + build_generated_batch（trainer.py，生成→双前向→divergence）；U5 train_whitebox.py/.sh。附带：load_sft_dataset 毛刺已磨平（改吃散装参数，接口回看记录清账）
+- **当前层**: 层 2（white-box OPD）**✅ 已关账**；下一步进层 3（相似度 + MC 估计器）
+- **层 2 代码构成**: U1 DistillConfig（configs.py，两温度分名/三处刻意缺席/max_grad_norm 显式化）；U2 token_divergence + 梯度爆炸单测（trainer.py，全词表 KL/JSD）；U3 SFTCollator prompt_only 模式（data.py）；U4 DistillTrainer + build_generated_batch（trainer.py，生成→双前向→divergence）；U5 train_whitebox.py/.sh（full/sanity/noclip 三模式）。附带：load_sft_dataset 毛刺已磨平（改吃散装参数）；hf-mirror 不代理 Xet CAS → HF_HUB_DISABLE_XET=1
+- **层 2 关账判据全过**（详见 docs/03 §6.1 实证）: 66 单测全绿；B=4/T=2048 **实测不 OOM**（§5 估算成立）；两次远程跑（sanity 裁到 1.0 / noclip ≈关裁剪+lr5×）均平稳、不 NaN、生成不塌（num_gen ~1900-4096）、loss 0.35→0.21 下降；checkpoint 存下
+- **层 2 关键发现（勘误"预期见毛刺"）**: §4.1 梯度爆炸是真机制（U2 单测坐实单 token π_T→0 暴涨），但真实训练**高度阻尼**——同门 teacher + per-token mean 摊平，batch 级 grad_norm 峰值仅 ~14 且只降不升，关裁剪也不炸。启示：`grad_norm` 日志是**裁剪前**值（14→2 那串即爆炸证据，被 HF 默认 max_grad_norm=1.0 静默压平，现已显式化）；层 5 有界乘子 π̂ 真正杀手锏是 **logit-free**（白盒的同 tokenizer 约束把你锁在温和区间）
+- **层 2 接口回看**（§6.5 每层必做，全部判"深"，无需返工的毛刺）: DistillConfig/token_divergence/build_generated_batch/load_sft_dataset(已修) 接口均远简于实现。三条**记录不返工**的小注：① DistillTrainer 从 self.data_collator.tokenizer 取 student tokenizer（隐式耦合，但省一个冗余参数，可接受）；② SFTCollator 名字略超范（现含 prompt_only 非 SFT 模式），rename 的 churn 不值；③ token_divergence 的 labels 仅作掩码非目标（已在 docstring 标注）
 - **层 0**: ✅ 已关账（2026-07-18）
 - **层 1**: ✅ 已关账（2026-07-18）。判据全过：正本缓存 sha `33deb18c…`（1000 条，键唯一，think 残留 0，仅 2 条硬题截断）；正式 1 epoch loss 0.94→0.60（56s/16 步）；checkpoint 生成通顺（`/data/zym/outputs/sft_qwen3-0.6b_dapo1k`）；接口回看完成（全部模块判"深"；毛刺记录：load_sft_dataset 吃整个 SFTConfig 迫使诊断脚本填假 output_dir，层 2 第二消费方出现时定夺）
 - **层 1 疤痕档案**（详见 docs/02 §2.6/§5 勘误）: ① 显存大头是 (B,T,V) logits 链与激活（正比 B×T，与参数量无关），B=8 曾爆 80G；② HF 梯度累积契约两幕剧（×8 → ÷4），终解 = model_accepts_loss_kwargs=False 退出新式契约；③ 缓存正本纪律：本地生成一次、单向 scp 分发、sha256 对账，两侧独立生成曾花双份钱且内容漂移
 - **诊断工具箱**: scripts/diag_collator.py（对齐链逐环）、diag_loss_probe.py（预训练 CE 基准 0.85）、diag_generate.py（生成质量）——层 2+ 数值异常照此三板斧
-- **已完成学习**: 第一/二章全部精讲；第三章已写待读（含 standard 路径解剖三大反直觉点精讲）
+- **已完成学习**: 第一/二/三章全部精讲（第三章含 standard 路径三大反直觉点、两温度、抉择原则、§4.1 梯度爆炸机制+实证）
 - **未精讲的文档账**: docs/01 的 §3.7（KL 锚三处实现差异）、§3.8（论文外稳定器）、§4（训练步流程走读）
 - **远程磁盘备忘**: 根分区 100% 的结构性原因是 `/root/zym`（507G 历史工作区）压在根分区，建议择期整体搬迁 `/data`；临时缓解 = 清 `/tmp/pip-unpack-*`、旧 tar.gz、journal。所有新增写盘已改道 `/data/zym`
 
@@ -38,7 +40,7 @@
 | `00-roadmap.md` | 本文 | ✅ |
 | `01-paper-code-map.md` | 论文 §3-§4 精读 + 参考实现全景解剖 + 概念↔代码对照表 | ✅ |
 | `02-sft-baseline.md` | 层 1：SFT 与数据管线 | ✅ 待读 |
-| `03-whitebox-opd.md` | 层 2：token 级 KL 蒸馏及其脆弱性 | ✅ 待读 |
+| `03-whitebox-opd.md` | 层 2：token 级 KL 蒸馏及其脆弱性（含 §6.1 远程实证） | ✅ 已关账 |
 | `04-mc-estimator.md` | 层 3：MC 估计 + 贝叶斯平滑 | ⬜ |
 | `05-entropy-chunking.md` | 层 4：熵调度 | ⬜ |
 | `06-omniopd-full.md` | 层 5：完整损失与 teacher 客户端 | ⬜ |