json-canvas

json-canvas skill 概覽

json-canvas skill 的功能是什麼

json-canvas skill 可協助代理建立或編輯符合 JSON Canvas 格式規範的 .canvas 檔案，適用於 Obsidian 與其他相容的圖表工具。它真正的任務不是「畫出好看的圖」，而是「產出結構正確、可被畫布應用程式實際開啟的 canvas JSON」，其中包含節點、邊、群組、座標、尺寸與圖層順序等必要資料。

誰適合安裝 json-canvas

這個 json-canvas skill 特別適合已經知道自己要把哪些內容放上畫布，但不想手動撰寫 schema 的使用者。它很適合筆記整理、心智圖、流程圖、架構草圖、研究看板，以及各種輕量圖表工作流程；前提是你要的輸出必須是真正可用的 .canvas 檔，而不是一段描述圖表內容的文字。

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

一般提示詞常常會把格式寫得「差不多」，但最後還是漏掉必要欄位、節點類型或陣列結構。json-canvas 的價值在於它是以 JSON Canvas 的物件模型為核心：最上層的 nodes 與 edges、四種節點類型（text、file、link、group），以及像是節點陣列順序會影響 z-order 這類實務細節。若你的目標是在 Obsidian 中直接做圖，而不是生成一份看起來像 JSON 的範例，這能明顯減少後續清理成本。

如何使用 json-canvas skill

安裝情境與何時呼叫 json-canvas

如果你的代理平台支援 GitHub skills，可依照平常的 skill 安裝流程，從 MarsWang42/OrbitOS 加入 json-canvas。目前從 repository 可見的內容只有 SKILL.md，因此可以預期這是一個偏精簡、以格式指引為主的 skill，而不是附帶 helper scripts 或 validators 的工具包。當任務明確提到 .canvas、JSON Canvas、Obsidian Canvas，或要求輸出必須是可編輯的畫布 JSON 以支援視覺化圖表時，就應該呼叫它。

哪種輸入最能發揮 json-canvas 的效果

json-canvas 在你提供的是「圖表意圖」而不只是「主題」時，效果最好。高品質輸入通常會包含：

• 要表達的節點清單或區塊
• 節點之間的關係
• 期望使用的節點類型：text、file、link、group
• 大致版面方向：由左到右、由上到下、分群排列
• 是否要用群組把相關節點在視覺上包起來
• 若使用 file 或 link 節點，對應的檔案參照或 URL

較弱的提示詞：
「Make a canvas for my project.」

較強的提示詞：
「Create a .canvas for a project roadmap with three groups: planning, build, launch. Use text nodes for tasks, link nodes for docs URLs, connect task dependencies with edges, and arrange groups left to right.」

如何把模糊需求轉成可用的提示詞

若想穩定用好 json-canvas，提示詞要同時交代內容與結構。實務上可套用這個模式：

1. 定義畫布用途。
2. 列出節點分類。
3. 說明關鍵邊線。
4. 指定版面規則。
5. 明確要求只輸出有效的 .canvas JSON。

範例：
「Use the json-canvas skill to generate valid .canvas JSON for diagramming a hiring pipeline. Include groups for sourcing, screening, interview, and offer. Add text nodes for each stage, link nodes for ATS and policy docs, and edges showing candidate flow. Keep nodes spaced for readability and place groups in process order.」

先讀哪些檔案，以及實際工作流程建議

請先閱讀 EN/.agents/skills/json-canvas/SKILL.md。重點放在：

• 最上層檔案結構
• 節點類型與必要欄位
• 邊的建模方式
• 透過節點陣列順序控制 z-index

實務工作流程建議：

1. 先整理節點清單。
2. 先生成最小可用的 canvas。
3. 用你的 canvas app 開啟檔案。
4. 第二輪再修版面、群組與缺漏連結。

這通常比一開始就要求產出完整精修版看板更有效，因為格式是否正確，往往比視覺美化更容易先驗證。

json-canvas skill 常見問題

json-canvas 只能用在 Obsidian 畫圖嗎？

不是。json-canvas for Diagramming 只要目標應用程式支援 JSON Canvas 規格，就都適用。Obsidian 當然是最直接的使用場景，但它真正的價值在於能生成符合標準的 .canvas，而不是提供 Obsidian 專屬的樣式魔法。

這比直接叫 LLM 寫 JSON 更好嗎？

通常是，尤其當你的最終產物必須能穩定載入時。一般提示詞在很小的範例上或許可行，但這個 skill 會把模型更明確地收斂到實際的 canvas schema 與節點語意上。一旦你的圖裡有多種節點類型、群組區域或大量邊線，這點就非常重要。

json-canvas 適合新手嗎？

適合，前提是你對自己要做的看板已有基本概念。你不需要深入理解整份規格，但必須能清楚描述實體與它們之間的關係。如果你連節點或流程都還列不出來，skill 雖然還是能生成內容，但結果往往需要大量手動修改。

什麼情況下不該使用 json-canvas skill？

如果你只需要靜態圖片、Mermaid 圖、Excalidraw 匯出檔，或純文字大綱，就不建議用它。若你的圖高度依賴特定 app 的進階行為，而那些行為並不屬於基礎 JSON Canvas 格式，這個 skill 也不會是理想選擇。

如何改善 json-canvas skill 的使用效果

給模型的是畫布規劃，不只是主題

想讓 json-canvas 產出品質明顯提升，最有效的方法就是把節點與邊明確命名。與其只說「make a system architecture canvas」，不如直接提供：

• 服務清單
• 相依關係
• 外部連結
• 分組邏輯
• 預期閱讀順序

這不只會提升格式正確率，也會讓版面安排更合理，使 json-canvas guide 在實際工作中更有可操作性。

避免常見的 json-canvas 失敗模式

最常見的問題包括：缺少必要屬性、分組描述過於含糊，以及版面難以閱讀。要降低這些情況，可在提示中加入：

• 要求只輸出有效的 .canvas JSON
• 要求使用唯一的節點 ID
• 指定大致的畫布方向
• 區分哪些邊是「一定要連」，哪些只是可選的視覺連線
• 若希望群組在空間上包住節點，務必明說

如果你的看板打得開但看起來不對，代表結構可能是有效的，只是定位與排版品質不佳。

分兩到三輪迭代，json-canvas 的輸出通常更好

是否值得安裝 json-canvas，很大程度也取決於它能不能支援高效率迭代。這一點它做得到，但前提是你分階段使用：

• 第 1 輪：先產出 schema 正確的 nodes 與 edges
• 第 2 輪：再微調座標、寬度、高度與群組
• 第 3 輪：若視覺堆疊很重要，再調整節點順序

由於節點陣列順序會影響 z-index，若你希望群組在內容後方，或標籤顯示在最上層，請明確提出這個要求。

第一版產出後，json-canvas 應該怎麼追問

初稿生成後，最有效的改進方式是下具體的定向修改指令，例如：

• “Convert these URLs to link nodes.”
• “Wrap these five nodes in a group node.”
• “Reposition nodes to reduce edge crossings.”
• “Keep the same IDs but add missing dependency edges.”
• “Put groups on lower z-index than text nodes.”

這種有約束條件的後續調整，通常比從頭重生整個看板更容易得到理想結果。