架構解說器 是做什麼的？
每個解說器產生一個自包含的 HTML 檔案：執行環境、拓撲、文章內容、字型與樣式全部嵌入其中，執行時無需任何網路請求。可放置在任何主機上、離線開啟、嵌入 <iframe> 或附加於電子郵件中。
模型
單一拓撲，多重投影。 系統只需一次性地完整定義。其他的都只是該單一圖表上的選擇器—絕不產生第二張圖。
拓撲 節點 + 邊 + 中繼資料 ← 唯一需要編寫的內容
──────────────────────────────────────
角色 解析策略 — 詞彙、折疊深度、哪些事實浮現
透鏡 關注覆蓋層 — 哪些邊存在、每個節點廣告哪個事實
時代 過去 / 現在 / 規劃 — 存在性與狀態樣式
節奏 敘事 — 鏡頭、焦點、文字、依序進行
執行環境強制執行兩條規則，且你不得違抗：
- 顏色歸透鏡所有。 節點類型由形狀表示 — 來源用折角、儲存用書脊、人類步驟用人物、閘道用斜角。切勿重新引入按類型配色的方案；那會讓圖表變成彩虹，並使透鏡切換失去意義。
- 沒有引導導覽的圖表不算完成。 檢查器會在節奏為零時中斷建置。這條規則讓這些圖表能夠自我解說，而不僅僅是好看。
工作流程 — 依序進行
1. 訪談。不要自行發明系統。
最大的失敗模式是產生一個看似合理、但使用者從未描述過的架構。在開始撰寫任何內容之前，請先提問。如果您的代理工具有結構化提問功能，請使用它。
涵蓋：
- 層級。 哪 5–8 個頂層階段或群組？這些會成為 L1 方塊。
- 每層的元件。 僅列出值得顯示的項目。「Postgres」是一個方塊；但其資料表則不是。
- 生命週期。 追蹤一個代表性的請求或任務從頭到尾的流程。這會產生邊。
- 閱讀對象。 高階主管 / 架構師 / 工程師是常見的組合，但請務必詢問 — 可能是「客戶 / 我們的團隊」或「學生 / 從業人員」。
- 哪些關注點重要。 資料流程加上 2–4 個：成本、延遲、信任與治理、故障模式、所有權、安全性。每個透鏡都需要自己的邊或事實。
- 是否有歷史。 v0 → 現今 → 規劃是客戶工作和路線圖中價值最高的軸線。如果系統沒有值得一提的過去，則跳過此項。
- 論點。 讀者讀完後應該相信什麼？這會成為節奏。如果使用者沒有論點，解說器就沒有主軸 — 請促使他們提出一個。
2. 選擇主要軸線
深度通常不是最有趣的軸線。詢問圖表的用途：
| 目的 | 主要軸線 |
|---|---|
| 教學如何運作 | 時間 — 節奏逐步引導一個請求 |
| 客戶 / 利害關係人簡報 | 時代 — 現有與提議的內容 |
| 設計審查、風險評估 | 透鏡 — 故障模式、信任邊界 |
| 新手上路、參考文件 | 深度 — 層級再到元件 |
3. 撰寫規格
在撰寫之前，請完整閱讀 references/spec-format.md。這是完整的節點 / 邊 / 節奏參考，包含所有可選欄位。
複製 assets/runtime/specs/llm-eval.js 作為範例 — 它使用了所有功能，是很好的模仿對象。將新的規格檔案寫入 specs/<name>.js，然後將 src/spec.js 指向它（只需一行 — 入口點和檢查器都透過它讀取）。
4. 建置
先將 assets/runtime 複製到工作目錄後再進行建置。請勿在已安裝的技能資料夾內執行 npm install — 該位置通常是共用或符號連結的安裝位置。
cp -R <skill-dir>/assets/runtime ./explainer
cd explainer
npm install # 需要網路連線；約 20 秒
npm run build # 先檢查規格，然後輸出 dist/index.html
檢查輸出會告訴你投影的數量。如果失敗，請修正規格 — 絕不要削弱檢查器。 它所強制的每一條規則，都是因為有真實的圖表在缺少該規則的情況下出貨而變得糟糕。請參閱 references/spec-format.md 了解每條規則的含義。
5. 視覺驗證 — 強制執行，兩種尺寸都要檢查
這是最常被跳過、但影響最大的步驟。版面計算並非小事，且失敗通常是靜默的：標籤被裁切、邊線穿越五個方塊、鏡頭對到空白區域。未經目視檢查，請勿宣告完成。
node scripts/shots.mjs # 桌面矩陣 → shots/
然後自行以手機尺寸 (390×844) 截圖，並開啟檢查圖片。檢查：
- 每個角色 × 時代的組合 都能正常渲染，無重疊或裁切。
- 每個透鏡 確實會改變畫面 — 如果兩個透鏡看起來相同，則它們的邊集合有誤。
- 節奏取景。 逐步瀏覽節奏；每個節奏應將焦點與可見的上下文一同取景，而非空白區域或整個系統。
- 標籤。 無任何裁切，無任何內容疊在方塊上。
- 手機尺寸。 重整為單欄，在 100% 縮放下可讀，控制項不溢出。
- 主控台。 零錯誤，包含在沙盒化 iframe 內。
如果看起來有問題，請在修改版面程式碼之前閱讀 references/troubleshooting.md。
6. 交付
將建置好的 dist/index.html 交給使用者。告知該檔案是自包含的，可代管、嵌入或離線開啟。
僅限 Claude Code / Claude 應用程式。 使用
SendUserFile傳送檔案。如果使用者會再次查看 — 大多數解說器都是如此 — 也請用create_artifact持久保存。
不可妥協的事項
- 每個節點都有一個
why— 一句話說明該方塊存在的原因，而非它是什麼。 - 任何高階主管能看到的內容，都必須使用高階主管級詞彙提供
detail。 - 至少 6 個節奏，每個都有實際的文章內容。過於單薄的節奏會產生投影片，而非論證。
- 葉節點 ≤ 34 個。超過此數量，請拆分為多個解說器，而非硬塞在一起。
- 每次建置使用一個主題。讀者只能切換淺色/深色模式，別無其他。
調整
- 不同的視覺方向 —
src/themes.js中包含五個主題（house、swiss、editorial、draft、shadcn）。變更src/App.jsx中的THEME_ID。如果你新增字型，則必須正確設定metrics.charFactor，否則每個標籤都會被裁切；請參閱references/troubleshooting.md。 - 更多角色 / 透鏡 / 時代 — 純規格資料，無需修改程式碼。
- 從原始碼產生 — 一個能遍歷儲存庫並輸出
DIAGRAM樹的腳本是合理的擴展，但why、detail和節奏仍須由人類提供。
範圍
此技能用於建置說明性圖表，非即時儀表板、非自由繪圖工具，也非基礎設施庫存。如果使用者想要一個可以持續拖動編輯的圖表，他們應該使用 drawio。如果他們想要頁面上的一個數字，他們應該使用圖表。