UltraExplainer 是做什麼的？
將程式碼、系統、差異比較、計畫、數據與概念，轉換為單一自包含的 HTML 頁面，讓一個重要的想法在第一眼就能一目了然，並透過可追蹤的證據加以證明。UltraExplainer 由三個部分共同運作：
- 合成方法（大腦） — 決定要展示什麼、強調什麼、刪減什麼，以及如何確保不繪製來源中不存在的結構。請參閱
references/synthesis-method.md。 - 變色龍工作室（工藝） — 一個穩定且與設計語言無關的組件契約（
assets/core.css），可透過七種完整的設計語言（assets/themes.css）重新換膚。同樣的差異比較在 Terminal 下會呈現為 IDE 邊欄，在 Blueprint 下為帶有標線的註解，在 Editorial 下則為圖形。您可以選擇最適合主題的語言；發光效果只是其中一個選項（Luminous），而非預設。請參閱references/aesthetic-languages.md與references/component-contract.md。 - 互動層（
assets/ux.js）— 一個共享的狀態→渲染引擎，驅動滑桿、場景切換、逐步教學、可排序/可篩選的表格、滾動監控導航，以及路由式的節點邊緣圖。請參閱references/interactivity.md。
身份：真實 + 正確的設計語言 + 經過驗證的工藝。 不是「什麼都發光」，不是「盒子與箭頭的雜亂拼湊」，也不是「一堆相同的卡片」
何時使用此技能
當輸出本質上是視覺化、關聯性或可操作的，而 ASCII/Markdown 會破壞它時，請使用 HTML 頁面：
- 圖表、架構概覽或關於連線或流程的 節點邊緣圖。
- 一段差異比較 / PR 審查（變更的程式碼 + 原因 + 影響範圍）。
- 一份計畫 / 需求審查或比較矩陣。
- 一個儀表板，包含指標或任何超過 4 行 / 3 欄的表格。
- 一個概念說明，用來解釋機制，或一個互動模型，讀者應透過改變輸入來感受。
- 一份投影片，或一個用於情境切換的專案回顧。
如果誠實的回答可以濃縮成一句話或一個數字，請直接在聊天中告知 —— 不要為了製造頁面而製造頁面（最小可行說明規則）。當您確實需要建立時，請給出一行聊天摘要並交付檔案。
兩種模式 —— 在初始階段決定
請明確陳述您處於哪種模式（以便使用者更正）：
- EXPLAIN（解釋）（預設）— 論點優先，適用於需要快速結論的審查者、決策者或情境轉換者。顯著性上限適用（T0 ≤ 3，T1 ≤ 7）。
- TEACH（教學） — 問題優先，適用於需要可執行心像模型的學習者。具體先於抽象，預測後再揭示，最後以遷移檢查作結。請參閱
references/teaching.md。
方法簡述
在產生任何非平凡的內容之前，請閱讀 references/synthesis-method.md。簡短形式如下：
- 初始設定 — 一句話：「這解釋了 <成品>，高度 <A0–A4>，針對 <受眾>，以便他們能夠 <任務>」，加上模式（EXPLAIN/TEACH）。保持在同一高度。
- 帶有張力的論點 — 一個讀者還不知道的陳述性主張（不是一個主題）。選擇主軸（眼睛跟隨的單一軸線）。
- 證據清單 — 閱讀真實來源；為每個節點/邊緣/標籤/數字記錄
{主張, 錨點 (檔案:行數 / 符號 / git 引用 / 指標+日期), 信心水準 (verified|inferred|assumed)}。沒有錨點 → 它不會以事實的形式呈現。 對於互動模型，每個滑桿範圍/預設值以及輸入→輸出函數都必須被錨定或標記為「說明性模型，非實際測量值」。 - 調和 — 將論點與矛盾的證據進行比對；進行修正、縮小範圍，或展示它。切勿默默忽略它。
- 最小可行檢查 — 不要過度渲染。簡單的答案 → 英雄句子 + 一個視覺元素。
- 顯著性分級 — T0（論點 + 主軸，≤3）/ T1（承載證據，≤7）/ T2（佐證資料，放在
<details>/懸停中）。超過上限 → 拆分或降級，切勿縮小以符合。（TEACH 模式將上限替換為期望的困難預算。） - 選擇設計語言 — 根據主題 × 受眾 × 媒介對 7 種語言進行評分，並記錄一行：
LANGUAGE: <名稱> 因為 <主題 + 受眾 + 媒介>。請參閱下文。 - 呈現 — 先問可操作性問題（「讀者是否應該透過改變輸入來感受某種關係？」）；如果是，則使用模型/逐步操作/場景。否則，選擇墨水最少的靜態形式。以量化方式（大小/長度/位置）編碼幅度，而不是使用相同大小的盒子。
- 壓縮 — 省略是工藝的關鍵；摺疊重複內容（「×12 個處理程序」）；摘錄承重的程式碼行，而非整個檔案。
- 閘門 — 在交付前通過所有三個閘門（如下）。
三個交付閘門 —— 真實性高於一切
- 真實性 — 每個節點/邊緣/數字都能追溯到真實的錨點；推斷/假設的內容需明顯標示；論點已與矛盾的證據進行調和；您已重新檢查錨點。一個清楚標記的「無法確認 X」勝過一個看似確鑿的虛構內容。互動式謊言（一個滑桿滑動一個虛構的關係）是最大的禁忌。
- 工藝 — 斜視測試：從房間另一側看，它看起來是一個經過深思熟慮的設計語言，而不是一個重新上色的模板。正好一個 T0 焦點。
- 觀察 — 您確實渲染了頁面並看過它。建構它，開啟它（在約 1280 和約 360 解析度下進行無頭截圖），捕捉主控台錯誤，斷言沒有水平頁面滾動，且論點在第一個視口中可見，然後自我修正。停止斷言您從未測量過的清單屬性。
如何建構頁面（組裝）
頁面由 scripts/build.mjs 從 templates/_src/<名稱>.body.html 中的主體片段組裝而成。最快的方法：複製最接近的模板，更改 preset，並調整內容。
- 第 1 行指令（HTML 註解中的 JSON）選擇語言和調整：
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset：blueprint | editorial | terminal | instrument | notebook | swiss | luminous（預設為luminous）presets: ["…","…"]→ 為每種語言產生一個檔案（變色龍示範）theme：light | dark（預設為該 preset 的自然調整）fx：glow | flat（僅限 Luminous）head/foot：額外的標記；<名稱>.head.html/<名稱>.foot.html側車檔案也會被合併
- 建構工具會內聯
core.css+themes.css+ux.js，連結該 preset 的字型，並在繪製前設定data-theme-preset/data-theme/data-fx（實現無 FOUC），然後輸出templates/<名稱>.html。 - 執行：
node scripts/build.mjs <名稱-過濾器>（過濾器是一個子字串；省略則建構所有）。 - 頁面唯一的外部請求是 Google Fonts（附有系統後備字型 —— 佈局永遠不依賴它們），以及對於 Mermaid 頁面，還有 Mermaid CDN。即使這些請求失敗，頁面仍應看起來正常。
關鍵：在內聯任何包含字串
</script>的 JS 時（例如範例片段），請將其跳脫為</script>，否則它會過早關閉標籤並將原始碼傾倒在頁面上。
選擇設計語言
根據優點進行路由，並記錄原因。完整的評分卡與每種語言的簡介請參閱 references/aesthetic-languages.md。
| 主題 | 預設語言 |
|---|---|
| 架構、綱要、協定、基礎設施拓撲 | Blueprint |
| 概念、ADR、事後分析、高層敘事 | Editorial |
| 差異比較、PR、CLI 工具、CI 管線、日誌 | Terminal |
| 指標、基準測試、審計、儀表板 | Instrument |
| 教學、逐步操作、入門引導、溫和說明 | Notebook |
| 比較、原則/宣言頁面、狀態報告 | Swiss |
| 系統流程示範、產品願景、令人驚豔的簡報 | Luminous（永遠非預設） |
平局決策：尊重使用者的明確要求（「讓它變成 terminal 風格」）；輪流選擇以避免會話單調；永遠不要因為 Luminous 花俏就選擇它。
選擇呈現方式
根據認知的任務和資料形狀進行路由，而不是根據內容類型。優先考慮可操作性。完整目錄與路由請參閱 references/representations.md；誠實圖表請參閱 references/charts-honesty.md。
| 任務 | 呈現方式（組件） |
|---|---|
| 一個主要的結論 / 是或否 | 排版論點英雄（.ux-thesis），下方可能搭配一個視覺元素 |
| 讀者應感受某種關係 | 參數模型（[data-playground]） — 滑桿 + 綁定讀數 |
| 順序 / 中間狀態是重點 | 逐步教學（[data-stepper]） — 程式碼↔數據鎖步前進 |
| 不同配置下行為不同 | 場景切換（.ux-seg[data-scenario-ctl]）重新點亮一個圖表 |
| 真正的線性序列 | 編號列表 / 流程條（.ux-spine） — 不是流程圖 |
| 分支 / 合併 / 循環流程 | 節點邊緣圖（.ux-graph，≤12 個節點）或主題化 Mermaid |
| 密集的成對關係 | 矩陣熱力圖（.ux-matrix） — 勝過糾結的圖 |
| 程式碼變更 / PR | 註解式差異 + 結論（.ux-diff + .ux-verdict）+ 影響範圍 |
| 概念 / 誤解 | 天真 vs 正確面板（.ux-compare）+ 一個範例 |
| 比較 / 審計 / 矩陣 | 可排序、可篩選的表格（.ux-table，th[data-sort]，data-ux-filter） |
| 量化指標 | 領先變化的 KPI 行（.ux-kpis）+ 最簡潔的誠實圖表（.ux-bars/.ux-linechart） |
| 計畫 / 路線圖 | 當前→目標區塊 + 風險分層時間軸（.ux-timeline） |
| 簡報 | 投影片（templates/slides） |
| 無適合選項 | 使用主題 Token 的自訂內聯 SVG |
模板（templates/，原始碼在 templates/_src/）
| 模板 | 語言 | 展示 |
|---|---|---|
chameleon.<preset>.html | 全部 7 種 | 以每種語言呈現的相同解釋 —— 斜視測試 |
blueprint → playground | Blueprint | 參數驅動模型（滑桿、綁定 KPI/長條圖、預設值） |
terminal-diff | Terminal | PR 審查：註解式差異 + 結論 + 影響範圍 |
instrument-dashboard | Instrument | KPI 標題 + 誠實的折線/長條圖 + 可排序/可篩選的表格 |
editorial-concept | Editorial | 概念說明：滾動監控導航 + 自訂 SVG + 天真 vs 正確 + 旁註 |
notebook-teach | Notebook | TEACH 模式：逐步教學 + 預測後揭示 + 遷移檢查 |
swiss-comparison | Swiss | 決策矩陣：超大數字 + 可排序的比較表格 |
luminous-flow | Luminous | 場景切換（命中/未命中）+ 路由圖 + 可選發光效果 |
mermaid | 任意 | 主題化 Mermaid，具備縮放 / 平移 / 展開功能 |
slides | 任意 | 全視口投影片，支援鍵盤/滾輪導航 |
參考資料路由 —— 只讀取當前輸出需要的內容
| 需求 | 閱讀 |
|---|---|
| 如何決定展示什麼/如何展示（大腦） | references/synthesis-method.md |
| 7 種語言、選擇評分卡、斜視測試 | references/aesthetic-languages.md |
Token 層級、每個 .ux- 組件、建構/組裝 | references/component-contract.md |
| 呈現方式目錄 + 資料形狀 × 任務路由 | references/representations.md |
| 滑桿、場景切換、逐步操作、圖形、滾動監控 —— JS API | references/interactivity.md |
| 誠實圖表：數字帳本、頻道排名、軸線規則 | references/charts-honesty.md |
| TEACH 模式：學習者狀態、具體優先、預測揭示、遷移 | references/teaching.md |
| 按任務分類的劇本（pr-review, postmortem, ADR, perf-profile, …） | references/playbooks.md |
| 自包含、溢位安全、驗證循環、交付清單 | references/self-contained.md |
| 主題化 Mermaid（何時 + 如何） | references/mermaid.md |
| 投影片 | references/slides.md |
不變規則
- 真實性高於美觀與工藝。 錨定或省略；標記推斷/假設的內容；永遠不要發明層次、對稱性、邊緣或理由。互動範圍/函數必須被錨定或標記為「說明性模型」。
- 每頁一種語言，根據優點選擇並記錄。 它必須通過斜視測試。發光效果僅限 Luminous，透過
--fx-*路由，因此data-fx="flat"可以乾淨地移除它；靜態內容上無連續的呼吸/脈動效果。 - 無水平頁面滾動。 在網格/彈性盒子子項目上設定
min-width:0；寬內容（差異比較、表格、Mermaid）在其自己的overflow-x:auto容器內滾動。在 360px 寬度下驗證。 - 兩種主題都看起來經過設計。 淺色模式是重新調整過的，而不是反色。頁面以其選擇的主題打開，讀者可以切換（按 preset 持久化）；尊重
prefers-reduced-motion；保持鍵盤焦點可見；列印安全。 - 組件僅使用語意化 +
--fx-*Token —— 永遠不使用十六進位顏色。 新的外觀來自主題套件，而不是內聯顏色。 - 永遠不要定義頁面層級的
.node類別 —— Mermaid 內部使用它。所有 UltraExplainer 類別都以.ux-為前綴。 - 交付前先觀察。 渲染頁面，查看它，修正任何問題。不要斷言您未測量的內容。
最終檢查清單
自包含文件位於正確路徑 · 使用所選的 preset 建構 · 無主控台錯誤 · 在桌面和 360px 寬度下無水平溢出 · 字型優雅降級 · 在第一個視口中論點清晰可見，且只有一個焦點 · 表格/差異比較/圖表在其自己的容器內滾動 · 主題（以及 Luminous 發光效果）切換正常運作 · 每個主張都已錨定或標記 · 頁面確實已渲染並檢查過。