TikZ 探索者书籍
你正在制作一本供人探索的书籍：一个单一网页，其首页是整个领域的概念图，而各个章节通过精心计算的 TikZ 图形，使每一个思想都变得可视化。读者希望先看到全貌、建立联系，然后自行选择深入之处。
可视化是优先事项。一个章节就是它的图形。文字引导读者进入图形，并从图形中引出结论；它绝不替代原本可以用图形展示的内容。在权衡时间时，请保持图形质量，削减文字。
此技能负责编排；图形的创作则存在于两个共享同一视觉语言（dlviz.sty，颜色=角色）的姊妹技能中。它们一同发布，并位于此技能文件夹的旁边；下文 <skills> 指代包含所有三个技能的文件夹（此技能的父文件夹，无论其安装位置如何）：
- tikz-dl-visualizer（
<skills>/tikz-dl-visualizer/）：静态图形。它的样式文件、原型和渲染脚本定义了优秀图形的标准。书中大多数图形是静态的。 - tikz-live（
<skills>/tikz-live/）：实时图形。一个由 pdflatex 编译的 TikZ 脚手架，加上一个描述运动部件的小型 JS 规范，使得读者可以拖拽起点、滑动温度或悬停标记，同时所有标签保留真正的 TeX 格式。书籍内嵌这些图形，它们遵循书籍的亮/暗主题。
在规划之前，请先阅读这两个 SKILL.md 文件，以便了解什么是好的图形，以及何时交互才有其价值。
交付物
<book>/
├── book.json 标题、部分、章节 ID、颜色角色、地图设置
├── SPEC.md 每个章节作者必须遵守的契约
├── chapters/00-front.html 前言、地图插槽、阅读指南、约定、图例
├── chapters/<cid>.html 每个章节一个 <section class="chapter">
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js 仅实时图形：规范；fig.sh 还会生成
│ .live.html（由构建内联），.html（独立）
│ 和 <slug>.<snapshot>.png（供审查）
├── scripts/<cid>-<slug>.py 图形中每个数字背后的 Python 代码
├── map/data.json 概念图：系列、概念、关键作品、链接、导览
├── tools/ build.py, shell.html（页面设计）, fig.sh, dllive.js（实时运行时）
└── index.html, preview.html 构建后的页面（发布 index.html）
要求：安装有 TikZ/pgfplots 的 TeX 发行版（pdflatex）、用于 PNG 的 Ghostscript 或 poppler、用于缩略图的 ImageMagick、用于图形数字的 uv（或带有 numpy/scipy 的 Python），以及用于实时图形的 node 和 PyMuPDF（uv run --with pymupdf，fig.sh 会为你执行）。页面加载 MathJax（jsDelivr）和 d3（cdnjs）。尽早检查 which pdflatex gs magick uv node；如果缺少 TeX 包，请告知用户 tlmgr install 命令，而不是自行安装。
工作流程
1. 理解来源与读者
阅读来源（获取课程日历或大纲，列出阅读材料）。然后定位读者：他们已知的内容（跳过他们已知的基础知识，但仍须精心绘制基本原理）以及他们的目标（工作、考试、研究方向）。目标决定书籍的结构：
- 第一部分遵循来源，每个课程单元对应一个章节。每个章节深入一个想法，而非概括所有内容。
- 第二部分是为读者目标准备的工具包，例如“视频生成研究人员必须知道的内容”：来源课程假设或跳过的跨领域基础知识，实用且前沿，配有真实数据。如果读者除了来源课程外没有其他目标，则跳过第二部分。
- 首页是概念图：在深入任何细节之前展示大局。
仅在目标确实不明确时才询问用户；否则，用一句话陈述你的理解，然后继续。
2. 围绕图形规划章节
为每个章节撰写简介：深入主题（一句话）、2-3 个图形，说明每个图形必须展示什么内容、使用哪个原型以及要计算什么。这是最重要的一步。明确机制名称的简介会带来出色的图形；只提及主题名称的简介只会产生方框示意图。
- 弱：“关于无分类器引导的图形”。
- 强：“一维两类混合；对引导 ODE 使用精确速度进行积分，w = 0, 1, 2, 4；将得到的密度与 p(x|c) 和倾斜密度以小型倍数图形式展示，显示引导过度偏离倾斜目标。”
好的图形主题：运行中的机制（路径、流程、更新）、前后对比、相同输入下的两种方法比较、形状和计数（张量形状、标记数量、FLOPs）、结果即为论点的数值实验。每个图形必须是可计算的：作者将用 Python 生成所有数字。
决定哪些图形是实时的。 当读者通过改变某物并观察机制响应而学习，且静态图片或小型倍数图无法同样好地展示时，交互才值得。在简介中写明其交互语句：“读者拖拽 X / 滑动 Y / 悬停 Z 并看到 W”。预算：每章大约一个实时图形，用于该章的核心机制；其余均为静态。好的候选：优化器路径（拖拽起点，滑动 β）、注意力或卷积（悬停一行或一个单元格）、引导权重或温度扫描、线性映射（拖拽基向量）、采样步骤（播放）。不合适的：流水线、架构图、任何小型倍数图已能展示趋势的内容。
- 实时图形简介：“一维两类混合；读者滑动引导权重 w 从 0 到 6，看到引导密度过度偏离倾斜目标；一个播放按钮逐步积分 ODE；数字：与目标的 KL 散度，实时显示。”
同时，为整本书一次性决定：颜色角色（哪种颜色代表什么含义；放到 book.json 中，以使图形、文本数学和图例一致）、约定（该领域有争议的部分：时间方向、符号、记法，以及在不同章节含义不同的符号，例如用于动量的速度和 Adam 的第二矩的 (v)），以及章节 ID（w01…，v01…；字母成为图形标签的前缀，如 W3.2、V5.1）。
3. 搭建脚手架
python3 <skill>/scripts/init_book.py <book> --title "书籍标题" --sub "来源·学期"
编辑 book.json（部分、章节 ID、角色）和 chapters/00-front.html；先阅读每个文件，因为工具拒绝覆盖你尚未阅读的文件。模板的角色是通用深度学习角色（输入、隐藏、潜在...）：用领域自身的角色替换它们（对于优化器：迭代、梯度、速度、损失...）。根据 references/author-spec.md 编写 <book>/SPEC.md，填写每个 «…» 块：读者、部分、角色表、约定、章节地图。章节作者只看到 SPEC.md 和他们的简介，因此 SPEC.md 必须独立完整。即使你自己撰写书籍，也要编写它：它是约定存放的地方，供后续章节和后续课程使用。
在启动任何人之前，通过 bash <book>/tools/fig.sh 渲染一个可丢弃的图形，以验证 TeX 流水线是否工作；如果计划中有实时图形，也渲染一个实时图形：将 <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js} 复制到 figs/_test/，运行 bash <book>/tools/fig.sh figs/_test/momentum.tex，然后 rm -rf <book>/figs/_test（其中间产物位于 figs/_test/.dllive/，因此不会留下任何内容）。这样可以验证 node 和 PyMuPDF 是否工作，并将 tools/dllive.js 放置到位。一个由九名并行作者发现的损坏流水线，其修复成本是九倍。
4. 委派章节
对于完整课程（10 个以上章节），并行生成通用子代理，每个代理负责 2-4 个相关章节（约 5-7 个图形）。每个提示包括：首先阅读 <book>/SPEC.md 并遵循它；其负责的章节 ID；每个章节的课程元数据、论文、深入主题和图形简介；渲染、检查、修正，然后按 SPEC 第 5 节报告。将相关章节分组给同一作者，以便共享图形保持一致（例如，动态 OT 与 OT 耦合）。
使用限制是真实存在的：同时使用九个作者可能会在运行中途耗尽会话限制。如果代理因速率限制错误而停止，其文件会保留。等待限制重置后，使用 SendMessage（“从你停止的地方继续；检查你已经创建的内容”）恢复每个代理，而不是启动新代理。对于大型书籍，考虑分两波启动。
对于小型书籍（一个主题，3-5 个章节），跳过子代理，自行编写，但仍需遵循 SPEC.md。
5. 作者绘图期间：前言和地图
编写 chapters/00-front.html（前言、阅读指南、约定、<!--ROLES--> 图例，可选地与来源对应的表格，例如包含章节链接的课程日历）和 map/data.json。阅读 references/concept-map.md 了解架构以及如何选择系列、节点、关系和导览。地图是概览：每个思想是什么、位于何处、如何关联，以及哪个章节更深入。不要在那里解释机制。
6. 报告到达时进行审查
每个报告列出其图形的“一句话思想”以及未经证实的声明。亲自打开最重要的图形（核心比较、用户特别要求的内容），并根据你已知的事实进行检查。将具体的修正反馈发送给绘制它的作者。
7. 组装、检查、阅读
python3 <book>/tools/build.py
python3 <skill>/scripts/check_book.py <book> --sheet
然后遵循 references/qa-and-publish.md：缩略图浏览、浏览器检查（数学错误、手机宽度溢出、地图、亮色模式、实时图形：全部挂载、拖拽和悬停正常工作、主题切换重新着色）、并在发布前阅读每个章节的文本。修复从你的简介中继承的元数据错误（课程编号、日期）。
不要跳过浏览器检查。静态检查无法运行页面的 JavaScript，而最重要的失败通常是静默的：地图从未渲染、数学停止排版。如果你确实无法打开浏览器，请在交接中说明，并将浏览器检查列为未完成。
8. 发布
将 <book>/index.html 作为构件发布，并附带所有图形 PNG 作为支持文件（check_book.py --files-json 会打印列表；实时图形已内联在页面中，因此不包含其 PNG 文件）；如果没有构件工具，则移交整个文件夹。告诉用户每个部分包含什么、哪些内容未经证实、哪些图形是图示而非计算结果，以及如何重建（python3 tools/build.py）或重新渲染图形。
后续请求
编辑同一文件夹并重新发布同一文件路径，以使链接保持不变：添加章节（在 book.json 中追加其 ID）、扩展地图（编辑 map/data.json）或重新样式（编辑 tools/shell.html）。当你修改 shell 或 map.js 时，请保留 references/qa-and-publish.md §3 中列出的修复。
参考文件
references/author-spec.md—SPEC.md的模板，章节作者的契约（图形规则、HTML 片段格式、引用规则）。references/concept-map.md—map/data.json架构以及如何编写连接要点地图。references/qa-and-publish.md— 检查、浏览器片段、已在模板中修复的已知陷阱、发布。assets/template/—init_book.py复制的书籍骨架。