graphviz

graphviz 技能概覽

graphviz 的用途

graphviz 是一種以 DOT 為基礎的繪圖技能，用來把結構化關係轉成自動排版的圖。當你需要的圖表會隨著規模變大仍然保持可讀性時，它最適合：像是相依樹、呼叫圖、套件階層、權責關係圖，以及其他手動擺位會變成瓶頸的 graphviz 繪圖情境。

誰適合使用

如果你腦中或文字裡已經有關係結構，希望模型快速產生有效的 DOT，graphviz 技能就很適合。對開發者、技術寫作者、架構師，以及需要把粗略結構轉成可渲染語法的代理來說，這是一個很實用的 graphviz 指南。

它有什麼不同

它的核心價值是語法可靠性，而不只是「畫出圖」。這個技能特別強調 Graphviz 的專屬限制，例如 digraph 和 graph 的差異、-> 與 -- 的差異、cluster 命名，以及含空格的 ID 需加引號。這很重要，因為多數失敗不是設計失敗，而是渲染失敗。

什麼情況下 graphviz 不適合

如果你要的是儀表板風格的圖表、以圖示為主的網路拓樸，或需要大量視覺品牌設計的簡報圖，就不要用 graphviz。若你需要的是表格型圖表或統計圖，其他工具會更合適。若你的需求是有明確邊線、可自動排版的階層關係圖，graphviz 通常才是正確選擇。

如何使用 graphviz 技能

先安裝並查看正確檔案

先把 graphviz 技能安裝到你的 skills 目錄，再在開始畫圖前閱讀技能本體和語法參考。這個 repo 裡最有用的檔案路徑是 SKILL.md 和 references/syntax.md；它們是最快理解實際 graphviz 安裝預期，以及實務上最常出錯語法的方式。

把模糊需求轉成可直接寫 DOT 的輸入

像「幫我畫一張架構圖」這種請求太弱。更好的請求會包含圖的類型、節點、邊的方向，以及任何版面限制。例如：「建立一個 digraph，呈現 frontend、API gateway、services 和 database。使用由上到下的流程，將 services 分成一個 cluster，標註 gateway 到 service 的邊，且只有在必要時才替 node 名稱加引號。」

先從最小可行圖開始

先建立最小且有效的圖：選擇 digraph 或 graph，定義核心節點，使用正確的邊運算子連接它們，接著等結構能正常渲染後再加屬性。這樣可以避開最常見的 graphviz 使用問題：明明圖已經壞了，卻先去做樣式調整。

加入複雜度前先讀語法規則

在加 cluster、record 節點或邊標籤之前，先查閱語法參考，確認 node IDs、cluster 名稱、edge attributes 和 layout controls 的寫法。Graphviz 的錯誤常常只來自一個不合法的 token，所以快速掃過語法規則，通常比反覆試錯更省時間。

graphviz 技能 FAQ

graphviz 比一般提示詞更好嗎？

是的，前提是輸出必須是有效的 DOT，而且要能穩定渲染。一般提示詞可能把圖的內容描述得很好，卻還是會漏掉 graphviz 的語法細節。對重視安裝式正確性，而不只是大致說明的使用者來說，graphviz 技能更適合。

哪一類圖最適合？

最適合的是階層型或關係密集型圖表：相依樹、呼叫流程、套件關係圖、決策樹、權責結構圖。若版面需要自動排版，而且邊線需要清楚表達方向，graphviz 會是很強的選擇。

初學者需要先懂 DOT 嗎？

不需要，但需要有明確目標。初學者只要清楚說出實體、它們之間的關係，以及圖應該是有向還是無向，通常就能成功。這個技能可以處理語法，但無法從模糊需求中自行推斷你的領域模型。

什麼時候不該用 graphviz？

如果圖表依賴像素級精準擺位、視覺圖示，或偏圖表式的簡報呈現，就不要用它。若你的需求本質上是資料視覺化，而不是關係映射，也應該避免使用。在這些情況下，即使 graphviz 技術上能畫出一張圖，它仍然不是對的工具。

如何改進 graphviz 技能

先把圖的結構交代清楚

提升 graphviz 結果最有效的方法，是先提供乾淨的節點與邊清單。說明核心物件、哪些物件應該分組，以及關係是單向還是互相連結。這樣可以減少歧義，並提升第一次渲染的成功率。

指定真正重要的版面限制

如果你的圖一定要由上到下、由左到右，或要依子系統分組，就要明確說出來。也要提到 cluster 的邊界、跨 cluster 的邊是否應盡量減少，以及是否有某些節點需要在視覺上保持居中。對多數 graphviz 使用情境來說，這些細節比樣式偏好更重要。

避開常見語法陷阱

最常見的失敗包括圖型種類和邊語法不一致、含空格的 node ID 沒有加引號，以及 cluster 名稱沒有以 cluster_ 開頭。如果第一次輸出不對，先檢查這些地方，再考慮要求重設計。很多 graphviz 安裝問題，其實本質上都是語法問題。

每次只要求修正一個面向

如果第一次輸出在結構上是對的，但視覺效果不夠好，就一次只調整一個維度：標籤、cluster 邊界、邊標籤，或 rank 方向。這樣比直接說「幫我弄得更好看」更容易得到乾淨結果，也能幫模型保留它已經產生的有效 DOT。