Obsidian Excalidraw 畫布建構器
生成可在 Obsidian Excalidraw 外掛中正確開啟的 .excalidraw.md 檔案，包含手寫 LaTeX 區塊、綁定箭頭與主題正確的顏色。
使用時機
- 在筆記庫中建立知識地圖 / 決策樹 / 公式板作為 Excalidraw 畫布
- 將 Markdown 大綱或筆記轉換為視覺畫布
- 修正渲染破圖、文字隱形、公式過大或意外白/暗背景的畫布
- 讓新畫布與同一筆記庫中現有畫布的視覺語言一致
請勿用於獨立交給網頁應用程式的 .excalidraw JSON，或用於產生 PNG/SVG——如需區別，請參閱 references/when-not-to-use.md。
黃金規則（從慘痛經驗學到）
- LaTeX 不是文字。 公式是
type: "image"元素，其原始碼位於## Embedded Files區段，格式為<40-hex-id>: $$tex$$。若圖片元素缺少對應的 Embedded Files 條目，會顯示為破圖。詳見references/latex.md。 - 不要手寫
$$...$$在文字元素中——這對此外掛會顯示原始碼。外掛只渲染 Embedded Files 中的方程式。 - 場景主題並非權威。 外掛會以應用層級主題覆寫
appState.theme。因此畫布顏色來自viewBackgroundColor，但淺色主題無論如何都會強制白色背景。詳見references/theme-and-color.md。 - 在創造顏色前，先複製同一筆記庫中現有畫布的調色盤。 使用
scripts/inspect_canvas.mjs解壓縮、讀取其筆觸顏色與字型家族，然後重複使用。 - 統一公式高度，寬度依長度決定。 固定的寬度過大會將短公式拉成巨獸。詳見
references/layout.md。 - 外掛會重新儲存為
compressed-json（LZString base64，每約 120 字元換行）。請從生成器腳本重新產生畫布，而不是修補已儲存的檔案。讀取需要解壓縮——scripts/inspect_canvas.mjs可以做到。 - 在宣稱成功前先驗證。 執行檢查腳本，確認：方程式數量等於圖片數量、沒有懸空綁定、主題/背景符合預期。
- 「看起來不錯」是可以量化的。 容器比例 ≤ 30%、字型大小種類 ≤ 4、公式高度變異數為 0、重疊數為 0。
scripts/inspect_canvas.mjs現在會將這些列為「美學警告」；將任何警告視為缺陷，而非偏好。詳見references/design-metrics.md。 - 一次性寫入，使用穩定 ID，先刪除再寫。 元素 ID 必須從內容衍生（文字/TeX/標籤的雜湊），絕不能隨機。且在寫入前，先解除目標檔案的連結。若不同時做到這兩點，重新產生 目前正在 Obsidian 中開啟 的畫布時，新元素會合併到即時場景中：所有東西都會加倍，外掛會將加倍的場景自動儲存回磁碟。詳見
references/troubleshooting.md→「元素加倍/三倍」。 - 交件前先渲染。
scripts/render_preview.mjs可以無頭方式（Node，無瀏覽器）將檔案柵格化。觀看 PNG——JSON 檢查只能捕捉結構，只有像素才能捕捉「間距看起來不對」。LaTeX 在該預覽中會顯示空白（MathJax 位於 Obsidian 外掛中，而非渲染器），因此請在那裡判斷佈局，並從## Embedded Files判斷公式正確性。 - 只有一個
$$層級。 TeX 在資料模型中是裸的（A=\int…）；分隔符號只在輸出## Embedded Files行時加入。生成的檔案中任何$$$都是雙層包裹的錯誤，會渲染出字面上的錢符號。
兩種佈局流派——繪製前選一種
| 欄位網格（表格派） | 線條為結構（結構派） | |
|---|---|---|
| 形狀 | 欄位方塊 + 行分隔線 | 主幹線 + 分支線 + 漂浮文字 |
| 容器比例 | 高（每欄一個方塊） | 接近 0 |
| 閱讀感受 | 查詢表，嚴謹 | 講座黑板，輕盈 |
| 適用場景 | 多個同層級行，需逐格檢查 | 分支，或欄位間互相衍生 |
| 失敗模式 | 「看起來像投影片範本」 | 分支過多→線條交叉 |
經驗法則：同級欄位→欄位網格；一欄衍生自其他欄→結構線。 兩者範例均存在於 design-metrics.md 中，內容相同（第十講畫布），因此您可以在選擇前比較。
工作流程
- 讀取目標筆記庫的慣例。 找到使用者喜歡的現有
.excalidraw.md，執行node scripts/inspect_canvas.mjs <file>並記錄：主題、viewBackgroundColor、主要筆觸顏色、fontFamily、roughness、典型字型大小。 - 將內容設計為欄或行（參閱
references/layout.md）——每種數量/步驟系列一欄，每個公式一行，只將真正同類的項目分組。根據上表選擇佈局流派（欄位網格 vs 結構線）。 - 撰寫生成器腳本，以
scripts/gen_canvas.mjs為範本：編輯其CONFIG區塊（標題、欄數、行數）並執行。不要手動編輯 30 kB 的 JSON。保留其內建的兩個安全機制：內容衍生的 ID 和writeFileSync前的rmSync。 - 檢查結果 使用
scripts/inspect_canvas.mjs，修正計數/顏色/綁定。同時確認檔案中沒有$$$，且元素數量與生成器印出的相符（若是其倍數，表示發生了合併錯誤）。然後渲染它，使用scripts/render_preview.mjs並實際觀看 PNG；修正間距/重疊/過短線條後再回報。 - 回報使用者在 Obsidian 中需執行的操作（關閉並重新開啟檔案，或使用「解壓縮目前 Excalidraw 檔案」指令）——外掛只在檔案重新開啟時才會重新讀取。
參考文件地圖
| 檔案 | 內容 |
|---|---|
references/file-format.md | 精確的 .excalidraw.md 骨架，兩種編碼方式，區段順序，標頭註解 |
references/element-schema.md | 每種元素型別的必要欄位、綁定文字、箭頭綁定、index 排序 |
references/latex.md | Embedded Files 契約、\color、尺寸調整、測試過的三種渲染變體、失敗特徵 |
references/theme-and-color.md | 為何畫布開啟為白色、matchThemeAlways、調色盤提取、此筆記庫的既定色彩 |
references/layout.md | 欄/行幾何、公式尺寸啟發法、畫布看起來未完成的原因 |
references/script-engine.md | 外掛內的 JS 腳本引擎：腳本放哪、能做什麼、ExcalidrawAutomate API、能否做表格、與檔案級生成的取捨 |
references/design-metrics.md | 量化美學：容器比例、字型層級數量、公式變異數、空白、語意色彩；兩種佈局流派；如何在沒有渲染器的情況下驗證 |
references/troubleshooting.md | 至今所有失敗的症狀→原因→修正對照表 |
scripts/gen_canvas.mjs | 配置驅動的畫布生成器（文字、latex、矩形、水平線、箭頭） |
scripts/inspect_canvas.mjs | 解壓縮 + 稽核：主題、計數、方程式/圖片匹配、綁定、字型、美學指標。--describe 印出緊湊的 ID/位置/標籤/連接清單；--dump 印出原始場景 JSON |
scripts/render_preview.mjs | 透過 mcp-excalidraw-server render 進行無頭 PNG 預覽（無瀏覽器）。LaTeX 渲染空白——僅供佈局參考 |
evals/evals.json | 回歸測試提示：每種實際發生過的失敗模式各一則 |
examples/ea-table.md | 一個可執行的應用內腳本，使用矩形+文字建立表格 |
編輯現有畫布
- 解壓縮以了解目前狀態（
inspect_canvas.mjs --dump <file>會印出場景 JSON）。 - 優先從生成器腳本重新產生。如果使用者有值得保留的手動編輯，請撰寫範圍轉換（讀取場景→變異特定元素→重新序列化未壓縮），而不是重寫整個畫布。
- 絕不留下半轉換的畫布：要嘛每個圖片都有其方程式，要嘛都沒有。
此筆記庫的尺寸與排版預設值
- 正文文字
fontFamily: 6、roughness: 0、strokeWidth: 1。 - 標題 28–30 px、欄標題 19–22 px、行標籤 15–16 px、公式圖片高度 50–52 px。
- 行距 116–130 px；欄寬 320–340 px；間距 28–40 px。
- 畫布背景
#ffffff；墨水#1e1e1e；淡化#868e96；細線#e9ecef。