Write Leetcuda Book

---
name: write-leetcuda-book
description: >-
  把 LeetCUDA kernels/interview 教学源码（base/sgemv/sgemm/hgemm/flash_attn/ffpa_attn/fp8_gemm.cuh/fp4_gemm.cuh）+ ffpa-attn CuTe sm_120 源码（csrc/cuffpa/cute fp8/fp4，commit 861d75e）写成中文 CUDA 技术书（6 Part 41 章 = 38 主线 + CuTe 白皮书导读 + ch26b/ch26c 增补，5 附录；XeLaTeX→PDF，终态 584 页零 error）。RFC-0..O 已全部完成（2026-09-24，Part V=FP8/FP4 HGEMM 篇 ch34-37 新增，原 FP8/FP4 Attention 篇顺延为第六部分），当前任务形态 = 增补章（RFC-L/M/N/O 模式）/复审/勘误/图重绘。当任务涉及：撰写或修改书稿章节（chapters/chNN*.tex）、每章最小测试（book/tests/chNN_*.cu）、ffpa_attn.bench 验证、知乎资料收集与提炼、TikZ inline 图新建（主路径）与存量 drawio 图维护、源码注释核查、勾选 RFC 进度、构建/审校 book.pdf 时使用。规范源=BOOK_PLAN.md（章节结构/每章 DoD 八条/源码冻结/容差表/图片管线），执行跟踪=RFC.md（RFC-0..O 里程碑 + 各章卡片 + 图清单 + 知乎参考种子表）。
user-invocable: true
---

# write-leetcuda-book — LeetCUDA 成书工作流

本 skill 目录即唯一事实源，两份核心文档（同目录）：

| 文件 | 角色 |
|---|---|
| `BOOK_PLAN.md` | **规范源**：6 Part 41 章（38 主线 + ch19b 导读 + ch26b/ch26c 增补）+ 5 附录、每章模板与 DoD 八条（含 Part V 特化 DoD）、素材/测试/图表/公式工程、LaTeX 管线、风险与验收 |
| `RFC.md` | **执行跟踪**：RFC-0..O 里程碑 checkbox（B 已取消）、每章执行卡片、图清单登记表、知乎参考种子表 |
| `references/quality-assessment.md` | **质量评估快照（2026-10-25）**：六维评分口径 + 45 个评分单元（41 章 + 5 附录，ch19b 免评）+ 教学书质量判断 + 提分 backlog。基于 R31–R53 共 23 轮审核证据；书稿再改或补到新证据后**在原文件更新**（不新建），分数变化 ≥2 分须在 `leetcuda-correctness-review/references/audit-history.md` 记原因 |

绝对路径：`/workspace/dev/vipshop/LeetCUDA/kernels/interview/book/skills/write-leetcuda-book/`（已软链到 `/workspace/dev/vipshop/.github/skills/write-leetcuda-book`）。

## 工作流（每次任务）

1. **领任务**：读 `RFC.md` 里程碑总览表 + 对应章节的执行卡片。RFC-0..O 已全部收口（RFC-B 于 2026-09-18 取消，职能归附录 E + drawio 全量重建；RFC-O = ch36/ch37 NVFP4 量化 GEMM，2026-09-24），存量只剩零星复审项（如 B.5 RoPE 参考）；新需求 = 用户新点名的增补章/增强项，按 RFC-L/M/O 模式新开里程碑条目（源码整合→测试→bench→正文→接线→验收→code review→用户增强）逐项推进。
2. **读规范**：`BOOK_PLAN.md` §3 章节卡片（源码区间/宏/公式/图/参考/测试映射）+ §4 模板与 DoD + 相关工程节。
3. **执行**：章节任务四合一 = 正文 tex + 最小测试 .cu + 注释核查 + 增量 bench。
4. **验收**：对照 §4.2 DoD 八条逐条自检（编译零 error / 锚点断言 / CHECKLOG / 测试 PASS / bench 落盘 / 图表登记 / 延伸阅读 / pdftotext 抽查）。**内容改动后先加载 `leetcuda-correctness-review` 按“第零层（数理逻辑）+ 四层”自审**（先查推导链/量词/反例，再查定义/指称、API/硬件契约、资源/类型计数、表达一致性；图注、表、问答一并审）；其中 CuTe 布局代数断言先按硬规则 10 用 PyCuTe 纯 host 复算，再**强制用 `remove-tech-ai-tone` skill 做文风自检**（八类 AI 味模式 + 词表逐词 grep，存疑保留；图内文字只做等宽替换）。**本轮只要产生书稿改动，随后必须按该 skill §5.0 构建矩阵编译所有受影响 PDF（主 `book` 与 `cute-zhihu` 等，不能只编主 book），再执行 ReadTheDocs 三层验收，不能跳过；全部通过后，才把每个 PDF 与 RTD 结果追加到该 skill 的 `references/audit-history.md` 并进入下一步。**
5. **回写**：RFC.md 勾选 `- [x]` + 追加日期；发现问题记 CHECKLOG / RFC 对应位置。复审/评分类任务完成后，按 `references/quality-assessment.md` §6 更新受影响章节的分数与扣分点（同一文件内更新，不新建）。

## 硬规则速查（违反必返工）

1. **源码冻结**：anchors.yaml 登记的全部源文件——各 `.cuh` + bench/ 下 10 个 .cu（`bench/bench_leetcuda.cu` 与 9 个模块 .cu：`bench/{base,sgemv,sgemm,hgemm,fp8_gemm,fp4_gemm,flash_attn,ffpa_attn,utils}.cu`，2026-09-29 迁入 bench/ 后均已登记）——在 RFC-A 登记 SHA256 后**零改动**。注释错误只记 `book/CHECKLOG.md` + 正文「勘误与考据」，不回写源码。
2. **正文形态**：原理讲解 + 关键代码段（每段 ≤40 行，`linerange` 多段裁剪，`firstnumber=auto`）；完整代码给附录 D 的 **GitHub commit permalink**；每章正文（非 listings）≥3500 字。
3. **测试**：`book/tests/chNN_*.cu` 无 cuBLAS/cuDNN 依赖，CPU fp64 参考 + 容差三档（F32Acc 1e-3 / F16Acc 5e-2 / TF32 1e-2），规模 ≤512，arch 不在位输出 SKIP；行数 ≤300（基础章）/≤500（复杂章）。
4. **知乎素材**：五步法（枚举→全文落 `zhihu-analysis/`→提炼→成文不照抄→附录 E 汇总）；**图片直接引用+出处标注**（作者/文章/链接/日期），原图归档 `book/figures/zhihu/`；水印/作者角标/平台 logo 一律标记为非内容元素，不得进入书内图。
5. **图管线（TikZ 主路径）**：新图默认 **TikZ inline** 写在章节 tex 内，用 `tikz-diagrams` skill（模板/编译渲染/视觉 QA 工具链；ch26b 六图先例，上游 5be940f 亦将存量图大规模迁为 tikzpicture）。drawio 已全部退役为**历史留档**（2026-09-28 迁移完成：`chapters/` 内 `\includegraphics` 全是 `% was:` 注释，41 章正文共 228 处 TikZ inline；`figures/drawio/` 的 64 套三件套只作旧版对照）。仅当用户点名改某张旧 drawio 图时才走存量维护：`drawio-reconstruction` skill 为主（inventory→重建→审查闭环），`drawio-diagram-builder`/`drawio-flow-forge` 辅助。**执行模式：主 agent 直接做，不派 task agent**（闭环子代理实测易卡死，用户 2026-09-11 拍板）。审查结论如实记 audit（自审需标注）。drawio 质量三查（XML well-formed + COVER=0 + 渲染宽不越界，见「drawio 制图铁律」）；`.drawio` 源文件必须入库（用户要求可手改，勿只提交 PNG）。
   **⚠️ TikZ 图强制视觉验收（2026-09-28 用户定为铁律）**：TikZ 图出现**文文重叠/图文重叠**极其常见（坐标估算的文字宽度与真实渲染字宽不符所致，N.19 七图 + O.18 六图全是此类）。任何新建/修改 tikzpicture 后，**必须**真实渲染并 view_image 逐角落检查确认无重叠后才算完成——只看代码/编译零 error **不算**验收。配方：抽图到 standalone（`border=8pt` + `\usepackage[UTF8,fontset=fandol]{ctex}`，fandol 失败则 `fontset=none` + `\setCJKmainfont{Noto Sans CJK SC}`，CJK 文本必须真实渲染、禁止用假文本代替——重叠取决于真实字宽）+ 从 `book/preamble.tex` 复制用到的颜色/样式定义 → `xelatex -interaction=nonstopmode` → `pdftoppm -r 150 -png` → view_image；修复优先级：平移节点/换 anchor/`text width`+`align` 换行/箭头改走线/竖排改横排（横排更宽，要挪到空白带）/字号降档（≥\scriptsize）。修法只动排版不动内容。foreach 标签里的循环变量（如 `16\i`）会被文本替换成数字，语义上想保留符号 i 必须改用显式值表（`{0/0/16,1/16/32,...}`）。
6. **行文风格（作者基线）**：参考 @DefTruth《图解:从Online-Softmax到FlashAttention V1/V2/V3》与《WINT8/4》系列——**原理一定要讲细**：公式逐项展开、指令逐 bit/逐字段解释、先直觉后形式化再代码；中文叙述、术语保留英文。其余可自由发挥。
7. **注释核查五类**：F1 架构事实（Prog Guide+cutlass skill arch guides）/ F2 PTX（本地 ptx-docs）/ F3 数学（独立推导）/ F4 性能断言（标来源）/ F5 历史陈述（对原论文）。
8. **构建**：CWD=`book/` 跑 `./build.sh`（两遍 `TEXMFCNF=../tex: xelatex -interaction=nonstopmode book.tex`，**尾部是冒号不是斜杠**——冒号表示追加系统默认配置，否则找不到 `xelatex.fmt`；`kernels/interview/tex/` 目录已不存在，实际靠系统 fmt 兜底）；本机已有 xelatex+ctexbook+Noto CJK（已验证）。TOC 全量装载报 `main_memory capacity exceeded`（PDF 目录丢失）时须 `fmtutil-sys --byfmt xelatex` 重建 fmt——`texmf.cnf` 的 main_memory 仅 fmt 生成期生效，改配置不重建无效（2026-09-22 L.9 根因）。
9. **ReadTheDocs 同步检查（改了 book 内容后强制，2026-10-10 定）**：任何书稿改动（`chapters/*.tex`、TikZ 图、封面）完成后，**必须**加载 `leetcuda-tex-to-readthedocs` skill，按其 `references/sync-and-deploy.md` 的「内容更新与自动同步 / 改稿检查清单」核对站点能否自动更新（`docs/readthedocs/README.md` 已缩为纯入口，细节统一维护在 skill 里）：① 正文/公式/表格改动 → push 即自动更新（中英文均然）；② **改 TikZ 图内中文文字或新增含中文图 → 必须先跑 `python -m tools.translate_figures --proxy …` 补 `docs/readthedocs/i18n/figures-en.json` 词典并 commit**，否则 RTD `post_build` 的词典覆盖核对不过、构建红灯（改的是图布局、节点中文文字未动则不受影响）；③ **改封面文案 → 必须重编译 `figures/misc/cover.pdf` 并 commit，英文封面另跑 `tools/build_cover_en` commit `cover.png`**，否则站点封面停留旧版。跳过此检查 = RTD 构建挂或中英文档静默脱节。**本地还必须先跑全量 `docs/readthedocs/build.sh` + `tools/visual_check.py` 三层验收；push 后 RTD 的远端构建只是复核，不能替代本地验收。**
10. **CuTe 布局断言先做 PyCuTe 纯 host 复算（2026-11-02）**：书中 `Layout`、`size`、`cosize`、`coalesce`、`composition`、`complement`、`logical_divide`、`logical_product` 等布局代数断言，除手工推导外必须用 [NVlabs/PyCuTe](https://github.com/NVlabs/CuTe) 再跑一遍。PyCuTe 是纯 Python 参考实现，**不需要 GPU、torch 或 CUDA runtime**；先 `git clone` 到 `$HOME/develop/CuTe`（可用 `CUTE_SRC` 覆盖），`python3 -m venv .venv && .venv/bin/pip install -e .`。脚本用书内原始 shape/stride，落盘 `book/.tmp/<task>/`，并记录 `git rev-parse --short HEAD`。它只证明布局代数，不证明 PTX/指令语义、资源计数或性能；当前未导出 `cosize`，需按像的 `max+1` 或独立公式计算。详细探针与边界见 `leetcuda-correctness-review` 的 Step 2.5。
11. **构建日期用当前最新时间（2026-11-05 用户定）**：每次 build PDF（主 `book`、`cute-zhihu`、`colfax` 等）时，封面落款、标题页版本日期等所有「成书时间」一律用**构建当刻的最新年月**，禁止写死 `2026 年 9 月` / `2026-09` 一类静态值，也不要沿用上次构建的日期。做法：封面 tex 导言区定义 `\newcommand{\builddate}{\the\year 年 \the\month 月}`（TeX 编译期取系统年月），落款用 `\builddate`；标题页 `\date` 用 `\the\year-\the\month`。**构建脚本必须每次重编封面 standalone PDF，不能只在 PDF 缺失或 tex 更新时才编**——否则跨月构建时封面日期仍停在旧月份。构建后用 `pdftotext -f 1 -l 2 <pdf> -` 抽查首页/标题页年月与 `date '+%Y 年 %-m 月'` 一致；三册（主 `book` / `cute-zhihu` / `colfax`）封面与标题页已于 2026-11-05 全部动态化。主书封面文案与 `docs/readthedocs/tools/build_cover_en.py` 的 `REPLACEMENTS` 精确耦合：改封面必须同步该工具，并用 `python3 tools/build_cover_en.py`（`python -m tools.xxx` 会被 site-packages 同名 `tools` 包顶掉）重生成英文封面，再跑 RTD 全量 `build.sh` + `tools/visual_check.py`。原文发表日期、arXiv 年份、章节内实测日期等历史事实不属于本规则，保持不变。

## 工具链速查

```bash
# drawio headless 导出（已装 v31.4.5 deb + xvfb；Ubuntu noble 无 apt 包，须用 GitHub releases deb）
DRAWIO_PATH=/usr/local/bin/drawio-headless \
  python3 /workspace/dev/vipshop/.github/skills/drawio-reconstruction/scripts/export_drawio.py in.drawio out.png
python3 /workspace/dev/vipshop/.github/skills/drawio-reconstruction/scripts/check_drawio.py in.drawio
# 也可直接：/usr/local/bin/drawio-headless -x -s 3 -o out.png in.drawio
# VS Code drawio 插件（用户已装）：用于人工查看/微调 .drawio；自动导出仍走上面 CLI

# 全书图几何体检（book/scripts/，2026-09 新增；改动后必须复检至 0）
python3 scripts/check_overlap.py figures/drawio/*/*.drawio   # 文字覆盖（COVER = 后画实心框盖住先画 text）
python3 scripts/check_text_fit.py figures/drawio/*/*.drawio  # 渲染宽 vs geometry 宽 + 页宽越界

# 知乎 CLI（已授权；--count 上限 10）
/root/.local/share/zhihu-cli/current/zhihu-cli search zhihu --query "..." --count 10
python3 /workspace/dev/vipshop/.github/skills/zhihu/scripts/fetch_column_fulltext.py <专栏URL>   # 枚举/取全文

# 源码锚点断言（RFC-A 后可用）
python3 /workspace/dev/vipshop/LeetCUDA/kernels/interview/book/scripts/verify_anchors.py --ch chNN

# PyCuTe 布局代数纯 host 复算（无需 GPU / torch / CUDA runtime）
CUTE_SRC=${CUTE_SRC:-$HOME/develop/CuTe}
[ -d "$CUTE_SRC" ] || git clone https://github.com/NVlabs/CuTe.git "$CUTE_SRC"
python3 -m venv "$CUTE_SRC/.venv"
"$CUTE_SRC/.venv/bin/pip" install -e "$CUTE_SRC"
git -C "$CUTE_SRC" rev-parse --short HEAD          # 记录复算所用版本
"$CUTE_SRC/.venv/bin/python" .tmp/<task>/check_layout.py   # 在 book/ 下运行
```

## drawio 制图铁律（存量图维护适用；2026-09 全书返工沉淀）

**生成器结构**：每图一份自包含 `gen.py`（`F` 类 box/text/line + 输出 `python3 gen.py <输出文件全名>`，如 `gen.py fig-12-2.drawio`——误传目录名会产生孤儿文件）。批量期的权威源在 `.tmp/drawio/gen_batch_{a,b1,b2,c1,c2,d,e}.py`（**`.gitignore` 忽略**），每图目录的 gen.py 是其回流拷贝（入库、自包含）。**改图必须改 `.tmp` 权威源再回流**，直接改目录版会在下一轮批量重跑时被静默覆盖（fig-14-2 实测踩中）；回流后用 `cmp -s` 校验。

**XML 铁律**：
1. `value` 禁裸 `<` / `&`：`Tile<64,64,16>`、`Swizzle<3,4,3>`、`->`、`R^16` 类写法的 `<` 必须转义 `&lt;`。裸 `<` 毁掉 well-formed → drawio **静默**渲染成细条（fig-26-1 只输出 2522x74，书里等于废图）。
2. 每个生成器末尾做 `ET.fromstring(xml)` 自检；全书定期 `python3 -c "ET.parse"` 全量扫（本次 2/39 破损）。
3. `text` 元素**不自动换行**：geometry 宽小于渲染宽，文字直接溢出色框（甚至越出页宽）。长注释必须手工拆多行，或把 geometry 宽改到 ≥ 估算渲染宽。
4. 宽度估算：CJK/全角 × `fontSize×1.02`，ASCII × `fontSize×0.58`（含全角标点按 CJK 计）。`check_text_fit.py` 用此公式报 `[OOB]`（越页宽）/`[COLLIDE]`（侵入右邻框）。
5. z-order：后画的**实心 box 会盖住**先画的 text。右上角注释卡与左侧网格文字相交时，把文字移出卡区（`check_overlap.py` 的 `COVER` 即此类）。
6. 导出体检：`PNG 宽 ≈ pageWidth × 3`（`-s 3`），高宽比 ≈ pageHeight/pageWidth。比例异常 = 渲染崩了（先查 XML well-formed），不要直接 `includegraphics`。

**常见布局病**（本轮回修）：说明行（y 40–60）与列头框（y 50+）净空不足 → 原点下移 16–26px；卡片内文字 409px 渲染塞 300px 框 → 框加宽 + 拆行；左表右侧的 `...` 居左文本 geometry 过宽侵入相邻框 → 宽度收到渲染宽；「标题 + 图」跨页 → 图示节前 `\needspace{图高+30mm}`（mm = `width_tw × 181 × png_h/png_w`，`preamble.tex` 已 `\usepackage{needspace}`）。

**其它约定**：CJK 禁 `bold`（易糊）；两位数格宽 ≥54px；纯色缩略格无文字；`.drawio`/`.png`/`gen.py` 三件套全部入库。

## 目录结构（book/，相对本 skill 的 `../../`）

```
kernels/interview/book/
├── book.tex / preamble.tex / build.sh      # RFC-0 产出
├── chapters/ch00-ch37 + ch19b/ch26b/ch26c + wp/ 白皮书导读 … appendices/  # RFC-C..O 产出
├── figures/{ascii,zhihu,drawio,ffpa,misc,tikz}/
├── tests/{common_test.h, chNN_*.cu, build_tests.sh}
├── notes/ references/ scripts/ CHECKLOG.md
├── skills/write-leetcuda-book/             # 本 skill（规范+跟踪）
└── .tmp/                                   # 测试/bench 临时产物（按任务建子目录）
```

## Examples

- `examples/drawio-recon-m1/`：drawio 重建 smoke test 固化样例（重建件 + headless 导出预览 + audit + 复现命令）。正式重建任务照此流程执行；原图在 drawio-reconstruction skill 的 `examples/m1.png`（路径引用，不复制）。

## 关联 skill

- `leetcuda-correctness-review`（**内容正确性自审（强制）**：书稿改动后、文风自检前加载——第零层先查数理逻辑/推导链，再查定义/指称、API/硬件契约、资源/类型计数、表达一致性；产出 claim ledger、边界矩阵、回修清单与残余风险；书稿改动后按 §5.0 构建矩阵编译所有受影响 PDF（主 `book` 与 `cute-zhihu` 等）并跑 ReadTheDocs 三层验收）
- `remove-tech-ai-tone`（**文风自检（强制）**：新章/增补章完成、commit 前必跑——技术文去 AI 味八类模式 + 高频词表 + 保留词表 + 验证工作流；目标文风「精确、简洁、沉稳、直接」。全书 2026-09-28 四轮扫描（~305 处）沉淀的词表源于此 skill）
- `tikz-diagrams`（**图主路径**：TikZ inline 写在章节 tex 内——2026-10-19 实测 41 章正文共 228 处 tikzpicture（`chapters/*.tex` 194 + `wp/` 34），ch26b/ch26c 全 TikZ 先例 + 上游 5be940f 大迁移；提供模板/编译渲染/视觉 QA 工具链，产出 .tex+.pdf+.png）
- `drawio-reconstruction`（drawio **仅历史留档**：迁移已完成、无活跃 png 引用；用户点名改旧图时才走 inventory→审查闭环）、`drawio-diagram-builder` / `drawio-flow-forge`（存量 drawio 修改）
- `zhihu`（资料五步法）
- `cuda-cpp-kernel`（ptx-docs=F2 核查源）、`cutlass-cpp-kernel`（arch guides=F1 核查源）、`cuda-auto-tune`（bench 复测方法论）
- `ffpa-cuda-understand`（ch19/26/26c 大 D split-D 背景）