【2026 最新】Reladraw 教學：AI 架構圖如何反覆修改並輸出 SVG（安裝＋驗收）

你請 AI 畫了一張架構圖，第一眼很清楚；隔天 API 多了一個佇列，圖卻只剩一張難以追修改動的圖片。Reladraw 教學要解決的是這個交接問題：先用文字寫下「誰在誰右邊、哪條線連到哪裡」，再輸出 SVG 給人看。

這篇寫給第一次接觸文字繪圖的讀者。你會從五個節點的小系統開始，學會自己改一條連線、讓程式代理依程式碼修圖，最後檢查 SVG 是否可以交付。需要會儲存純文字檔；下面每一步都附上可以照抄的內容。

先說結論：Reladraw 教學的核心是一份可回改的文字來源

一句話記住：可維護的架構圖＝程式碼證據＋.reladraw 關係描述＋SVG 成品驗收。把 .reladraw 想成食譜，SVG 是端上桌的菜。人與 Agent 修改食譜、重新出圖；別把改完的圖片當成下一輪唯一的原稿。

截至 2026 年 9 月 28 日，官方儲存庫與 0.9.0 語法文件把它描述成用相對位置安排節點的文字語言，並提供 CLI 把檔案輸出成 SVG。官方也標示語法仍在變動；本篇指令以 0.9.0 為準。

Reladraw 教學第一步：看懂三種檔案與五個零件

Reladraw 的基本句子像說明座位：「資料庫在 API 右邊」。你寫的是關係，軟體再算出實際座標。初學時先認五個零件：

1. 節點 node：畫面上的方塊，名稱如 api 是穩定代號，後面的「API」是顯示文字。
2. 位置：right of api、below api 指定相對方向；它們說明版面意圖。
3. 連線 edge：edge api -> db 說 API 指向資料庫；文字標籤交代「查詢」或「更新」。
4. 來源檔 .reladraw：人能直接改，Git 也能顯示哪一行改了。
5. 輸出檔 .svg：可縮放的向量成品，適合文件和簡報；下次修圖仍回到來源檔。

官方語法參考說明：每行一個敘述，註解用 //，節點有唯一名稱；這與把整張圖當成一塊任意拖拉的畫布，是兩種不同的編輯方式。

從零做一張圖：安裝、寫五個節點、輸出 SVG

① 先決定要畫什麼，不猜不存在的服務

假設一個教學用系統：瀏覽器呼叫 API；API 查資料庫，也把背景任務送到佇列；工作者從佇列取任務後更新資料庫。這是一個虛構範例，不是任何真實專案的架構。真正交付前，要把每一個方塊對回程式碼或部署設定。

② 安裝 0.9.0 並建立純文字檔

已有 Node.js 的讀者，在終端機執行 npm install -g reladraw@0.9.0。官方 README 的一般安裝寫法是 npm install -g reladraw；本文指定版本，是為了讓下方語法與你安裝的版本一致。想先看畫面，也可以打開官方瀏覽器 Playground，把同一份文字貼進 Source 欄。

新增 example.reladraw，依序貼入這些行；每個 node 是一個方塊，每個 edge 是一條有方向的線：

• node browser "瀏覽器"
• node api "API" right of browser
• node db "資料庫" right of api
• node queue "佇列" below api
• node worker "工作者" right of queue below db
• edge browser -> api "HTTP" from: right to: left
• edge api -> db "查詢" from: right to: left
• edge api -> queue "送任務" from: bottom to: top
• edge queue -> worker "取任務" from: right to: left
• edge worker -> db "更新" from: top to: bottom

執行 reladraw example.reladraw -o example.svg，打開輸出的 SVG。這份十行範例已用 0.9.0 CLI 產生下圖；你也可以用 Playground 的 Download 按鈕取得 SVG。

③ 用兩次小修改，理解「雙向」

先由人手修改：把 node worker "工作者" right of queue below db 改成 node worker "背景工作者" right of queue below db，重新執行輸出指令。接著假設程式碼顯示工作者只寫入另一個儲存服務，就請 Agent 檢查那段程式、提出來源檔的具體修改，並說明哪些檔案支持這條連線。這裡的雙向，是人與 Agent 輪流修改同一份文字來源；輸出的 SVG 仍要重新產生。

你可以把這段要求貼給能讀取專案檔案的程式代理：「請先列出瀏覽器、API、佇列、工作者與資料庫各自對應的程式檔或設定；逐條核對 example.reladraw 的 edge。只修改有證據支持的節點和連線，列出你改了哪幾行及證據；不確定的連線先標待確認。最後執行 reladraw example.reladraw -o example.svg，不要只回覆『完成』。」

如果你要讓代理讀懂更多語法，官方 README 也提供Reladraw Skill 安裝指令。先檢查第三方 Skill 的內容與專案權限，再決定是否安裝；小圖直接提供上述來源檔與官方語法連結即可開始。若想追蹤代理每輪讀了哪些檔案與工具執行結果，可接著看Agent 可觀測性教學。

交付前怎麼審查：來源、結構、畫面各查一次

成功產生 SVG 只代表語法與輸出流程跑通。真正交付時，我會用三層驗收，讓修改者與審核者說同一種話：

1. 來源層：在 Git 變更中看 .reladraw 哪些 node 與 edge 變了；為每條真實連線附上程式檔、API 規格或部署設定的依據。想建立這種核對習慣，可接著讀架構圖與程式碼審查教學。
2. 結構層：確認節點名稱沒有重複、箭頭方向正確、標籤能解釋資料或工作流向。工作者是否真的會更新資料庫，應以程式碼或設定回答，不能因為箭頭畫得順就算成立。
3. 畫面層：用瀏覽器開 SVG，放大與縮小檢查字有沒有被裁掉、連線有沒有蓋住標籤、深淺色是否足以辨識。縮圖也要看一眼；向量檔可縮放，不代表所有標籤在小尺寸都清楚。

需要把圖放到文件或網站時，連同 example.reladraw 一起交付。SVG 方便閱讀與排版，來源檔讓下一個人知道「為什麼這個節點在右邊」。若需要團隊通用的圖表交付規則，可參照圖表設計與 Mermaid 交付教學。

Reladraw 與 Mermaid 怎麼選？先問你要控制什麼

兩者都能用文字描述圖，也都能輸出視覺成品，但控制重點不同。Reladraw 的這份教學以 right of、below 明講節點相對位置；Mermaid Flowchart 官方文件則以節點、邊、方向與子圖描述流程，版面交給所選佈局器處理。Mermaid 另有架構圖語法與對齊指令，因此不能概括說它完全不能指定位置。

• 選 Reladraw：你希望在來源碼直接審查「資料庫必須在 API 右邊」之類的相對版面意圖，並願意用目前仍會變動的語法維護圖。
• 選 Mermaid：團隊已在文件平台使用 Mermaid，流程關係比精細位置更重要，或現成渲染與文件整合是主要需求。可看AlphaLab 的 Mermaid 圖表教學。
• 兩者都保留：同一份專案可以用 Mermaid 寫快速流程，用 Reladraw 維護需要明確相對位置的說明圖；不要為工具統一而重畫所有圖。

新手最常踩的五個坑

1. 只改 SVG：下一輪產出可能覆蓋手動調整。解法是把變更回寫 .reladraw，再重出圖。
2. 讓 Agent 猜架構：畫面漂亮不等於符合程式。解法是要求它列出每條連線的檔案證據，自己抽查關鍵資料流。
3. 節點位置描述不夠：出現版面衝突時，依 CLI 錯誤訊息補上相對方向，而不是憑空加一個座標；官方語法文件有完整寫法。
4. 版本混用：搜尋到的舊範例可能採用舊語法。此篇綁定 0.9.0；升級前先比對官方發行紀錄與目前 SYNTAX.md。
5. 沒看縮圖：字和箭頭在全尺寸沒問題，小尺寸可能辨不清。交付前至少看一次預期展示寬度。

常見問題：直接回答八個實作疑問

Reladraw 是 AI 畫圖工具嗎？

Reladraw 是文字圖表語言與輸出工具。AI 代理可以幫你寫或改來源檔，人也可以直接編輯。

一定要安裝 CLI 嗎？

不一定。先用官方 Playground 貼入文字、預覽與下載；要納入專案版本管理，再用 CLI 比較順手。

SVG 可以編輯，為何還要留來源？

SVG 是向量圖，但本文要保留的是「相對位置」與節點命名這層意圖；在來源檔修改後重出 SVG，審核較容易。

我能直接把整個程式庫交給 Agent 畫嗎？

可以讓能讀取檔案的代理分析，但先限定範圍與入口，要求逐條列證據；對沒有證據的服務關係保留疑問。

節點標籤可用中文嗎？

本篇五節點範例以 0.9.0 CLI 輸出含中文標籤的 SVG。交付時仍要在目標瀏覽器與字型環境檢查顯示效果。

圖輸出了，就等於架構正確嗎？

不等於。CLI 能把合規來源轉成圖；服務是否存在、箭頭是否符合程式，要另外查。

Reladraw 比 Mermaid 好嗎？

看任務。想審查相對位置就試 Reladraw；主要寫常見流程且已用 Mermaid 文件鏈，就沿用 Mermaid。

遇到語法錯誤怎麼辦？

先核對安裝版本，再看 CLI 指向哪一行；從那行的節點名稱、位置詞或連線端點開始修。

給新手的三個重點

• 先寫關係：從五個方塊和四、五條線開始，別先追求裝飾。
• 把文字當原稿：人改、Agent 改，都回到 .reladraw，再輸出 SVG。
• 用程式碼驗收：圖表描述的是系統主張，每個重要箭頭都要能找到依據。