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 已取消）、每章执行卡片、图清单登记表、知乎参考种子表

绝对路径：/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/硬件契约、资源/类型计数、表达一致性；图注、表、问答一并审），再强制用 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 对应位置。

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

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 的远端构建只是复核，不能替代本地验收。

工具链速查

# 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

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 类写法的 < 必须转义 <。裸 < 毁掉 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 背景）