d3group/d3-explainer

D3 Explainer（互動式 HTML，專為作者本人設計）

<skill-dir> 在此技能中代表技能本身的基礎目錄，Claude Code 在載入技能時會顯示該目錄（作為外掛安裝時：${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer；手動複製時：~/.claude/skills/d3-explainer）。請在每個指令中替換為實際路徑。<wording-dir> 代表 <skill-dir>/../d3-scientific-wording，這是每個 D3 外掛都附帶的共享用字技能。

一份離線 HTML 檔案，用於向正在撰寫該研究專案的人員解釋專案內容：問題是什麼、填補了哪個缺口、核心概念如何運作、每個推導的過程與原因、這些內容在程式碼中的位置、證據顯示了什麼，以及哪些問題仍然懸而未決。互動式圖表傳達直觀感受；文字則貼近原始來源並明確標示出處。

讀者是作者及其共同作者。 這決定了以下幾乎所有事項：

• 他們了解該領域。除非他們的筆記顯示某個部分是其弱點，否則跳過教科書等級的背景知識。
• 他們想要理解，因此誠實比精美更重要：假設、論文與程式碼之間的歧異，以及開放性問題，都會有專屬章節，並且會標示出哪些是解讀。
• 他們會根據自己的檔案來驗證主張，因此每個實質的主張都必須指向其來源，且建置過程會驗證該指標確實存在。
• 詳盡是可以的，但不必 exhaustive。只有部分讀者想要的深度內容會放在可折疊區塊中。「每個細節」僅在使用者要求時才提供，且僅限於他們指定的部分。

所有 Python 程式碼都透過 uv 執行（uv run、uv run --with <pkg>）；永遠不要使用 pip 或全域安裝。

參考檔案（按需載入）

檔案	載入時機
references/scanning.md	第一階段：在 token 預算內閱讀儲存庫、輸入層級、vault / recall / NotebookLM、先前的解說器
references/content-design.md	第二與第三階段：章節主幹、深度預算、如何呈現缺口與推導、誠實盤點、解說器用字的特有規則（即 d3-scientific-wording 的規則）
references/components.md	第三階段：HTML 詞彙、原始碼晶片、建置指令、explainer.toml、D3X JavaScript API
references/visualization.md	第二與第三階段：設計能傳達知識的互動式圖表；模式目錄；常見陷阱
references/review.md	第四階段：兩個審查者提示、token 規則、迭代流程
assets/example/	一個含有完成解說器的小型儲存庫。請閱讀 assets/example/explainer/sections/*.html 一次，以了解每個元件的運作模式。切勿將其複製到使用者的專案中。

步驟 0：一次性提問

除非使用者已經說明，否則請在一次訊息中詢問以下問題，之後不再重複詢問：

範圍。 整個專案，還是某一部分（模型、推導、流程）？ 深度。 focus（一個想法或一個推導：1 到 3 個章節，一到兩個圖表，約 5 分鐘）、overview（4 到 6 個章節，約 10 到 15 分鐘閱讀）、standard（預設：7 到 10 個章節，4 到 8 個互動式圖表，1 到 3 個推導，20 到 35 分鐘）、或 deep（最多 14 個章節）。「Deep on X」代表標準加上一個關於 X 的深入章節。 審查。 light：自動檢查加上我自己的數字驗證，幾乎不消耗額外 token。single：一個審查代理人同時負責忠實度與圖表，一輪，約 50 到 70k token。standard：兩個審查代理人並行（一個負責對原始來源的忠實度；另一個負責圖表與互動性），一輪，總計約 100 到 150k token。審查者的成本主要是一個固定基礎，幾乎不隨專案規模變化，因此我的建議會依循深度：focus 用 light，overview 用 single，standard 與 deep 用雙代理人審查。full：兩個代理人反覆進行，直到每個評分都達到 9/10，最多三輪，成本約為標準審查的兩到三倍。 用字。 ste（預設：遵循 ASD-STE100 的簡化技術英語，每句最多 25 個字，主動語態，一個詞只有一個意思；對英語為第二語言的共同作者最友善）或 standard（團隊的科學用字，無 STE 限制）。

「quick」、「no review」、「cheap」或「short on tokens」代表 light。「thorough」代表 full。「just this derivation」、「only explain X」、「keep it short」代表 focus。「plain」、「STE」或未說明代表用字 ste；「normal wording」、「paper style」或「no STE」代表 standard。未說明則代表深度 standard，並使用該深度建議的審查方式。

當無人能回答時（批次或代理人執行）：採用預設值，為此技能會詢問的每個點做出決定，將每個決定記錄在 brief.md 的第 0 節中，然後繼續。這個簡報將成為作者了解為他們決定了哪些事項的地方。

工作流程

在每個階段的邊界列印一行帶有時間戳記的狀態，如同其他 D3 技能：[HH:MM:SS] PHASE: ...。

第一階段：繪製專案地圖（以正確順序低成本閱讀）

uv run <skill-dir>/scripts/scan.py            # 從儲存庫根目錄執行；加上 --out explainer/scan.md 以保留

掃描報告會顯示輸入層級（A：程式碼與論文，B：僅論文，C：僅程式碼，D：僅 PDF，E：僅筆記）、各個方向文件、論文與每個程式碼資料夾的最後修改時間（可發現過時的 CLAUDE.md 或被放棄的方法）、論文大綱及其方程式標籤、最大的程式碼模組（含符號名稱與行號）、可嵌入的結果檔案、按資料夾分類的 vault 中作者自己的筆記、先前的解說器，以及每個方向文件、論文、章節檔案、程式碼模組與筆記的 token 估算。列印 INPUT TIER: X 並讓使用者覆寫。

然後按以下順序閱讀，並在能夠撰寫簡報時停止。詳細資訊與預算請見 references/scanning.md。

1. 方向文件（CLAUDE.md、README、根目錄下的規格或分析筆記）。
2. 論文：摘要、引言、貢獻聲明，然後是模型與方法章節。略讀結果以取得主要數字。
3. 掃描找到的先前的解說器：大綱（scan.py --explainer <file>），然後完整閱讀一個章節以了解語氣（--section N）。它們顯示了作者已經理解的部分以及他們喜歡的語氣。在此基礎上建構；不要重複它們。
4. Vault：根據標題挑選的概述、概念、缺口、決策與開放性問題筆記。不包括文獻轉儲。
5. 程式碼：僅實現核心概念的模組，透過符號映射找到。對於大型程式碼庫（超過約 40 個檔案或 8,000 行程式碼），派送一個 Explore 子代理人來產生論文到程式碼的對應圖，並保留其結論，而非檔案本身。

選擇性強化，僅當儲存庫中的缺口或專案歷史資訊不足時提供：recall 技能（決定了什麼，何時決定）或 NotebookLM（文獻怎麼說）。與 d3-abstract 中的協議相同。當掃描找到了文獻資料夾、含有匯入來源的 vault 或 NotebookLM 筆記本時，在同一個問題中提供 d3-scientific-winding（步驟 1b）的主題設定檔：它顯示文獻對每個概念使用哪個詞彙與拼寫，這為符號表與術語表提供了基礎。列印 ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile]。

第二階段：內容簡報，在任何 HTML 之前獲得批准

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # 建立 ./explainer：explainer.toml、brief.md、sections/、d3x/
#   儲存庫中有多篇論文：加上 --paper <folder>        解說器在其他位置：init.py <dir> --repo <repo root>

儲存位置：<repo>/explainer/，位於外部儲存庫的根目錄（不在論文子模組內：Overleaf 用不到它）。在與簡報相同的訊息中確認位置。

填寫 explainer/brief.md：用兩句話說明專案、讀者之後應該能夠做什麼、已閱讀與特意不閱讀的來源、缺口、章節規劃、推導、誠實盤點、刻意省略的內容，以及在 ## Wording 標題下的用字簡報（類別為解說器、讀者為共同作者、領域、選擇的用字模式，以及專案結構與符號的術語表）。章節規劃每行一個章節，並且對於每個互動式圖表，寫出其旋鈕到洞察的句子：「移動 X 會顯示 Y」。沒有這類句子的圖表就是裝飾品，會在這裡被刪除，而不是在建立之後。

以簡潔形式在聊天中顯示簡報並獲得批准。這是唯一強制性的檢查點：它花費幾百個 token，但可以防止寫出錯誤的 6,000 個字。在獲得批准之前，不要撰寫章節。

第三階段：逐節撰寫

在撰寫第一個章節之前，調用 d3-scientific-wording（技能工具：d3-scientific-wording:d3-scientific-wording；如果未列出，則閱讀 <wording-dir>/SKILL.md），並使用 brief.md 中的簡報。在 ste 模式下，也閱讀 <wording-dir>/references/ste.md。載入 references/components.md 與 references/visualization.md，並略讀範例章節一次；它們是以 STE 撰寫的。

• 每個章節一個檔案：explainer/sections/NN-slug.html，每個檔案恰好包含一個 <section id=... data-nav=... data-kicker=...>。建置過程會為它們編號並建立導航。
• 每個章節後都進行建置，以便錯誤保持在局部：uv run explainer/d3x/build.py --draft（TODO 標記與指向尚未撰寫章節的連結只會發出警告）
• 核心概念章節內的順序：簡潔陳述、互動式圖表、正式陳述、推導、在程式碼中的位置。先直觀，後代數。
• 讓儲存庫說話，而不是重新打字。 <div class="eq" data-label="eq:prob"></div> 從論文的 .tex 檔案中拉取方程式（如果存在 .aux 檔案，則包含其編號）。<pre class="code" data-src="src/model.py" data-lines="88-104"></pre> 拉取真實的程式碼行。兩者都比打字便宜，且不會與原始來源脫節。
• 使用晶片指向來源： [[paper:eq:prob]]、[[code:src/model.py:88 def solve]]、[[vault:Note name]]、[[result:results/table.csv]]，以及 [[reading]] 用於你自己的解讀。建置過程會針對不存在的檔案、行、符號、標籤或筆記報錯；vault 晶片在 explainer.toml 中未設定 vault 時只會發出警告。失敗的晶片是你理解上的發現：修正主張，而不是刪除晶片。
• 互動式圖表按優先順序顯示：儲存庫的結果檔案；儲存庫自己的程式碼在網格上計算的數字（一個小的 explainer/data/make_data.py，請參見 visualization.md）；或在瀏覽器中以玩具尺寸重新實現的真實公式，宣告為 toy: true，這會在其上放置一個可見的「說明性玩具」徽章。預設值採用論文中的設定。數字從檔案中嵌入，絕不從記憶中輸入。
• 每個圖表說明都以 {fig} 開頭（建置過程會為圖表編號；使用 {fig:figure-id} 來引用一個圖表），並說明要嘗試什麼以及要注意什麼。

第四階段：驗證

uv run explainer/d3x/build.py                  # 無 --draft：TODO 標記現在會報錯；根據深度預算列印每個章節的字數
uv run explainer/d3x/check.py --shots          # 無頭瀏覽器：移動每個控制項、拖曳每個把手、逐步執行每個推導

check.py 必須以 0 error(s) 結束。然後檢查章節的用字（在 standard 模式下省略 --ste）；修正每個錯誤並對每個警告做出決定：

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

它可以捕捉到閱讀原始碼無法發現的問題：路徑中的 NaN、不會改變任何東西的控制項、MathJax 無法渲染的公式、在滑桿極端值處被截斷的標籤、在手機寬度下頁面溢出。在機器上第一次執行時可能會要求一次瀏覽器：uv run --with playwright playwright install chromium（它會回退到已安裝的 Chrome 或 Edge）。

親自查看 explainer/review/shots/ 中的兩到三張截圖。然後以所選的深度進行審查；提示與 token 規則在 references/review.md 中：

• single：一個唯讀審查者，使用來自 references/review.md 的合併提示，在一次回合中閱讀兩個封包、check.md 與截圖。然後像下面那樣驗證並應用。
• light：無審查代理人。親自進行一次數字驗證：文字中的每個數字、KPI 圖塊，以及圖表預設值，都對照其所引用的論文或結果檔案。然後停止。
• standard：兩個並行的唯讀審查者，一輪。每次建置會將兩個封包寫入 explainer/review/：fidelity-packet.md（解說器的文字含行號、推導步驟含理由，以及每個晶片所引用的方程式或程式碼行作為證據）和 figures-packet.md（每個圖表的說明與腳本）。忠實度審查者根據第一個封包檢查推導、數字、缺口主張與用字（冷讀與 d3-scientific-wording 的規則）；體驗審查者根據第二個封包檢查每個圖表是否傳達了其旋鈕到洞察的句子，加上 check.md 與截圖。兩者都不需要在儲存庫中漫遊，這使得審查成本可以負擔。在他們執行期間不要編輯章節檔案。然後親自驗證每個阻擋性與主要問題，應用它們，重新建置，重新執行 check.py。只有在阻擋性問題時才進行第二次檢查，且僅由提出該問題的審查者負責，並且僅針對已更改的檔案。
• full：相同的兩個審查者，反覆進行直到每個類別都達到 9 分或更高，最多三輪；然後將剩餘的問題交給使用者。

第五階段：交付

給出路徑 explainer/dist/<name>.html（一個檔案，可離線運作，可安全地透過電子郵件傳送）、所使用的審查深度，以及包含已修復項目的合併發現表格。提及：n 開啟符號抽屜，推導透過「Next step」逐步進行，當遠端位於 GitHub 時，晶片會連結到建置提交的 GitHub 永久連結。如果儲存庫有 vault，提議將一份 HTML 副本放入 vault，與作者先前的解說器放在一起。向 d3-scientific-wording（步驟 5）詢問水印問題一次；如果回答是，則清理 explainer/sections/*.html（絕不清理已建置的檔案，因為它嵌入了 MathJax 與字型）並重新建置。提議提交說明，當作者確認時，交付 explainer/dist/<name>.html 並完成。