json-canvas

json-canvas skill 概覽

json-canvas skill 能做什麼

json-canvas skill 可協助 AI 代理建立與編輯符合 JSON Canvas 1.0 結構的 .canvas 檔案，這也是 Obsidian 風格視覺看板所使用的格式。它真正的價值不在於「一般性的畫圖」，而是能產出有效的 nodes 與 edges JSON，並正確處理 ID、座標與參照關係，讓檔案能順利開啟，而不是出現那些不容易第一時間察覺、卻會讓畫布壞掉的細微錯誤。

哪些人適合安裝 json-canvas

這個 json-canvas skill 特別適合已經清楚知道自己想做出什麼結果的使用者，例如心智圖、流程圖、專案看板、概念圖或筆記畫布，但不想手動撰寫 schema。若你本來就在 Obsidian 裡工作、會把 .canvas 檔案放進 repo 管理，或希望對既有 canvas 進行可重複、可控的 AI 輔助編修，而不是只做一次性的視覺建議，它會尤其實用。

為什麼它比一般提示詞更好用

一般提示詞或許能描述方塊和箭頭，但常常會漏掉真正影響可用性的格式細節，例如唯一的 16 字元 hex ID、有效的 fromNode 與 toNode 參照、不互相重疊的位置配置，以及文字節點與群組節點之間的差異。json-canvas skill 提供代理一個明確的目標格式與範例，因此能減少生成後還要補救、修 JSON 的工作量。

採用前你需要知道的事

這個 skill 是刻意做得很聚焦的。它主要處理 .canvas 檔案結構與常見編修流程；它不是完整的視覺排版引擎、語意式製圖工具，也不是自動設計最佳化器。如果你的核心需求是精緻樣式或匯出到多種圖表格式，json-canvas for Diagramming 可能會讓你覺得太底層；如果你要的是快速得到有效的 canvas JSON，那它就很合適。

如何使用 json-canvas skill

安裝情境與優先閱讀順序

若要在支援 skills 的環境中使用 json-canvas install，請先從 kepano/obsidian-skills repository 加入這個 skill，接著先讀 skills/json-canvas/SKILL.md，再讀 skills/json-canvas/references/EXAMPLES.md。這兩個檔案是最實用的核心內容：前者說明必要結構與工作流程，後者提供完整範例，方便你直接比對、照著模式出稿。

這個 skill 要吃到哪些輸入，效果才會好

json-canvas usage 的品質，很大程度取決於你的需求描述有多具體。建議提供：

• 目標檔案路徑，或既有的 .canvas 內容
• 你要建立新 canvas，還是修改既有 canvas
• 需要的節點類型，例如 text 或 group
• 大致的版面意圖，例如由左到右流程，或 kanban 欄位布局
• 節點之間預期的連線關係
• 尺寸或間距方面的要求

弱的需求是「幫我做一個專案 canvas」。更強的需求則像是：「建立一個新的 .canvas，包含三個群組欄位 To Do、In Progress、Done，每個大小 300x500，彼此間隔 50px，並在前兩個群組內各加入三個文字任務節點。」

怎麼把模糊需求變成高品質提示

如果你想提升 json-canvas guide 的輸出品質，最好同時要求「生成」與「驗證」。一個好用的提示格式通常是：

1. 先用白話說明目標。
2. 指定是建立還是修改。
3. 定義節點清單與彼此關係。
4. 要求代理在最終輸出前驗證 JSON 與 edge references。

例如：
「Use the json-canvas skill to create a new .canvas file for a product launch plan. Add one central text node, four supporting text nodes around it, connect each support node to the center, keep 100px spacing to avoid overlap, generate unique 16-character hex IDs, and return valid JSON only.」

能省下時間的實務工作流建議

若想讓 json-canvas usage 更順，建議先從簡單版本開始，再逐步迭代：

• 先要求一個結構有效、最小可用的 canvas。
• 開啟或檢查它。
• 再一次只要求一種變更：加節點、重分群、重接線，或重排位置。

如果你是在修改既有檔案，請明確要求代理先解析目前的 ID，再新增任何內容。最常見的損壞來源就是 ID 衝突，以及 edge 指向不存在的 node。若版面很重要，也要把間距規則講清楚；否則 JSON 可能 technically 有效，但視覺上會非常凌亂。

json-canvas skill 常見問題

json-canvas 適合新手嗎？

適合，前提是你已經知道畫布裡應該放哪些內容。這個 skill 幫你省掉大多數 schema 猜測成本，讓新手不必死背 spec，也能產出有效的 .canvas 檔案。不過，如果你連圖本身的邏輯都還在摸索，它就沒那麼理想；這個 skill 擅長把結構正確編碼出來，不是替你完整發明整套資訊設計。

什麼情況下應該用 json-canvas，而不是一般 AI 提示？

當你的輸出必須是一個可正常使用的 .canvas 檔案時，就該用 json-canvas，尤其是要修改既有 canvas 的時候。一般提示詞適合拿來發想結構，但只要你在意正確性——像是唯一 ID、有效陣列、真實存在的 node references，以及 Obsidian 相容格式——這個 skill 會比通用提示更可靠。

json-canvas 能處理所有製圖需求嗎？

不能。json-canvas for Diagramming 最適合的是節點—邊畫布、簡單看板，以及以筆記連結為核心的視覺整理。它不能取代 BPMN 工具、精緻簡報圖像工具，或進階自動排版系統。如果你需要廣泛的圖表標準支援或更完整的樣式控制，請改用其他工具，必要時再考慮轉成 .canvas。

它的主要邊界或不適用情況是什麼？

如果你的目標不是 .canvas 檔案、你需要很重的自動排版最佳化，或真正的 source of truth 應該維持在 Mermaid、Excalidraw 或試算表等其他格式，就不建議用這個 skill。另外，也要避免像「幫我弄得好看一點」這類過度模糊的提示；這個 skill 在結構與位置意圖明確時，表現會最好。

如何提升 json-canvas skill 的效果

提供更強的結構化輸入

想明顯提升輸出品質，最有效的方法就是一開始就給更完整的結構資訊。把你要的節點、節點之間的連線關係，以及預期的空間排列模式都講清楚。像是「hub-and-spoke」、「three-column board」或「timeline from left to right」這類描述，都足以讓代理做出合理配置，而不是靠猜。

避開最常見的失敗模式

多數 json-canvas 問題其實都很機械性：

• 重複的 ID
• edge 指向不存在的 node
• 座標重疊
• 缺少必要欄位，例如 type、x、y、width、height

請要求代理在回傳檔案前，先驗證所有 ID 與參照關係。如果是在修改既有 canvas，也要明確要求它保留既有 ID，除非那次變更真的需要新增 node 或 edge。

先有第一版，再逐層細修

把第一次輸出當成骨架即可，之後再一層一層往上修：

• 調整間距與對齊
• 新增群組
• 微調標籤與文字內容
• 新增或移除連線

這樣通常比一開始就要求一個資訊密度很高的最終版更有效，因為視覺結構上的錯誤，在早期比起大規模生成完成後更容易發現與修正。

有意識地套用範例與 repository 模式

如果想改善 json-canvas skill 的輸出品質，與其全靠抽象描述，不如直接借用 references/EXAMPLES.md 裡的版型。如果你的目標像專案看板，就要求代理遵循以 group 為核心的模式；如果比較像概念圖，就要求它採用簡單的文字節點連線模式。重用 repository 原生的模式，通常能得到更乾淨的 JSON，也比較不會踩到相容性上的坑。