TikZ 探索者書
您正在製作一本供人「探索」的書：一個單一的網頁，其首頁是整個領域的概念圖，而各章節則透過精心計算的 TikZ 圖形，讓每個概念變得清晰可見。讀者希望先看到全貌，連結各個點，然後再依自己的選擇深入探索。
視覺化是首要任務。一個章節就是它的圖形。文字引導讀者進入圖形，並從中得出結論；它絕不能取代一個能展示相同內容的圖形。當您需要在時間上取捨時，請優先保持圖形品質，並刪減文字。
此技能負責協調；圖形的製作則存在於兩個共享同一種視覺語言 (dlviz.sty，顏色 = 角色) 的兄弟技能中。它們一同發布，並位於此技能資料夾的旁邊；下面，<skills> 表示存放這三個技能（此技能的父資料夾，無論安裝在哪裡）的資料夾：
- tikz-dl-visualizer (
<skills>/tikz-dl-visualizer/)：靜態圖形。它的樣式檔案、原型和渲染腳本定義了什麼是好的圖形。書中的大部分圖形是靜態的。 - tikz-live (
<skills>/tikz-live/)：動態圖形。由 pdflatex 編譯的 TikZ 骨架，加上一個繪製活動部分的小型 JS 規範，讓讀者可以拖曳起點、滑動溫度或懸停在一個 Token 上，同時每個標籤仍然是真實的 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 個圖形，每個圖形需說明必須讓什麼可見、使用哪個原型以及要計算什麼。這是最重要的一步。命名了機制的簡報會產生出色的圖形；僅命名主題的簡報只會產生方塊圖。
- 弱：「關於無分類器引導的圖形」。
- 強：「一維兩類混合；以 w = 0、1、2、4 的精確速度積分引導 ODE；結果密度與 p(x|c) 和傾斜密度的小型多圖，顯示引導過度於傾斜。」
好的圖形主題：運作中的機制（路徑、流程、更新）、前後對比、在相同輸入上比較兩種方法、形狀和計數（張量形狀、Token 計數、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；先閱讀每個檔案，因為檔案工具拒絕覆蓋您尚未讀取的檔案。範本的角色是通用的深度學習角色（輸入、隱藏、潛在...）：將它們替換為該領域自己的角色（對於最佳化器：迭代、梯度、速度、損失...）。撰寫 <book>/SPEC.md，使用 references/author-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 作為一個 Artifact 發布，並附上每個圖形 PNG 作為支援檔案（check_book.py --files-json 會印出列表；動態圖形已內嵌在頁面中，因此它們的 PNG 被排除在外），或者如果沒有 Artifact 工具，則移交整個資料夾。告訴使用者每個部分包含什麼、哪些部分未經證實、哪些圖形是插圖而非計算結果，以及如何重新建置（python3 tools/build.py）或重新渲染一個圖形。
後續請求
編輯同一個資料夾並重新發布同一個檔案路徑，以便連結保持不變：新增一個章節（在 book.json 中追加其 ID）、擴充地圖（編輯 map/data.json），或重新設定樣式（編輯 tools/shell.html）。當您修改外殼或 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複製的書籍骨架。