【開源拆箱 01】退換貨規則寫了一整頁？實測用 diagram-design 轉成新人看得懂的流程圖

想像一家電商在大促銷隔天，客服後台塞滿退換貨詢問。

手冊明明寫了三頁，新人還是不斷轉頭問老鳥：超過鑑賞期還能補件嗎？發票遺失要走哪條路？

把文字梳理成流程圖是大家都想到的解法，但真要做起來往往痛苦不堪。打開專業繪圖軟體，手動拖拉對齊方塊動輒耗掉兩三個小時；用線上繪圖服務，每個月都要付一筆帳號月費；如果直接叫生成式模型畫圖，產出來的點陣圖字體常常模糊不清，改動一個錯字就得整張重算。

這週我們在 GitHub Trending 週榜上，看到一個單週新增近萬顆星的開源專案：diagram-design。

我們在隔離環境裡把這個專案完整跑了一遍。好處在哪裡、有哪些踩坑卡點，這篇拆箱老老實實說給你聽。

一、專案速覽：這到底是個什麼工具？

先說結論：這不是一個按一下按鈕就自動生圖的桌面應用軟體，也不是自帶大語言模型的獨立推論程式。

它的本質是一套專門寫給 AI 代理（Agent）閱讀的設計規則手冊，搭配乾淨的 HTML 與 SVG 向量圖模板。你負責把業務流程邏輯整理好，讓代理讀取這套排版規格，接著由代理直接寫出符合專業視覺規範的網頁代碼。

二、為什麼這週值得關注？

文字轉圖表的需求一直都在，市面上最常見的工具是傳統的語法繪圖工具（例如 Mermaid）。那類工具雖然好上手，但預設配色與間距較為生硬，想當成正式報告交付給客戶時，往往需要額外花時間手動美化。

圖像生成模型雖然畫面華麗，但致命傷在於圖片中的文字是死像素，根本無法複製選取，更別提後期局部微調。

diagram-design 選擇了一條很務實的路徑：它不重新發明模型，而是把資深設計師的排版經驗（包含文字行高、節點距離、語意配色、箭頭轉折路徑）整理成一份給 AI 閱讀的提示規範。

只要你的 AI 代理讀懂了這份規範，輸出的就是單純的 HTML 網頁檔與 SVG 向量檔。這意味著：

1. 零雲端工具月費：完全不需要綁定特定繪圖軟體的訂閱費用。
2. 原始文字可編輯：產出後的每一個中文文字節點，都能在瀏覽器裡反白選取，用一般的文字編輯器就能直接修改內容。
3. 程式碼完全自持：檔案就在你的本機硬碟裡，不需要把內部流程上傳給第三方伺服器。

三、真機實測：安裝步驟與最小可行範例

我們在公司的 ARM64 架構 Linux 伺服器（Ubuntu 24.04 LTS）上建立了獨立的測試目錄 /tmp/jh-gh-unboxed-01/，全程不更動系統全域設定。

1. 測試環境清單

• 作業系統：Ubuntu 24.04.4 LTS（aarch64 晶片架構）
• 基礎工具：Git 2.43.0、Python 3.12.3、Node.js 22.22.3
• 輔助驗證：Playwright 1.64.0（瀏覽器自動化測試工具）、Chrome 152
• 字型支援：系統內建思源黑體（Noto Sans CJK TC）

2. 實測題目：電商退換貨處理流程

為了驗證繁體中文排版與複雜條件分支，我們設計了一道虛構的「電商退換貨流程」： - 主流程：收到申請 → 檢查鑑賞期 → 檢查資料齊全 → 核准案件 → 倉庫退款結案。 - 兩條例外分支：鑑賞期檢查不符合，走「逾期結案」；資料不齊全通知補件，補件逾期走「補件逾期結案」。 - 總共包含 9 個業務節點、9 條連接箭頭與 2 條例外處理路徑。

3. 操作指令路徑

先將專案原始碼抓取到本機，並切換到我們核對過的穩定提交版本：

# 建立專屬測試目錄並下載專案
mkdir -p /tmp/jh-gh-unboxed-01
git clone https://github.com/cathrynlavery/diagram-design.git /tmp/jh-gh-unboxed-01/diagram-design
git -C /tmp/jh-gh-unboxed-01/diagram-design checkout --detach 11b08eade8049c441ed3df1895e3b527c26c0fbe

接著讓 AI 代理（這次我們用的是 Codex）循序閱讀專案內的排版規則文件： - skills/diagram-design/SKILL.md（核心設計準則） - skills/diagram-design/references/type-flowchart.md（流程圖專用規則） - skills/diagram-design/references/style-guide.md（色彩與字體定義）

當代理理解設計規則後，我們將流程文字丟入，讓代理根據畫布尺寸（1280×1040）計算各節點座標，產出單一 電商退換貨流程.html 網頁檔。

最後，透過專案內建的 Python 工具將 HTML 轉為獨立 SVG 向量圖檔：

# 匯出為可獨立使用的向量圖檔（使用本機字型）
python3 /tmp/jh-gh-unboxed-01/diagram-design/skills/diagram-design/scripts/export_svg.py \
  /tmp/jh-gh-unboxed-01/產物/106-電商退換貨流程.html \
  /tmp/jh-gh-unboxed-01/產物/電商退換貨流程.svg --system-fonts

4. 實測結果展示

產出的視覺效果相當整齊，9 個節點各自落在合理的空間網格中，箭頭轉折平滑且清晰標示了判斷條件。

［圖：桌面全頁.png］

［圖：流程圖.png］

在字體排版驗證方面，瀏覽器逐節點比對文字實際長寬與外框邊界，溢出清單為零，繁體中文在框線內排列工整。我們嘗試將「退款並結案」直接改為「退款完成（編輯測試）」，重整網頁後依然正常渲染，證實了內容具備完整的二次編輯能力。

四、實測卡點與踩坑紀錄

看起來很順利對吧？但實際動手跑，我們踩了五個具體卡點，讀者若要自己裝，務必注意這些細節：

1. 網路隔離環境下的下載失敗

在限制對外連線的沙箱環境中，第一步執行 git clone 就直接跳出 Could not resolve host: github.com 錯誤。如果你在封閉內網或嚴格權限的主機上操作，必須先確認開通 GitHub 網域的存取權限。

2. 純中文檔名匯出失敗，必須加上數字或英文前綴

這是最容易讓人抓狂的程式小臭蟲。當我們試圖將 電商退換貨流程.html 匯出成 SVG 時，專案內建的 export_svg.py 直接報錯拋出異常： cannot derive an ID slug from '電商退換貨流程.html'

從錯誤訊息看，匯出工具要從檔名裡取出英文字母或數字當作圖的 ID，純中文檔名取不出來，就直接報錯停下。

解法很簡單：只要在檔名前加上英文或數字前綴（例如改名為 106-電商退換貨流程.html），轉檔程式就能順利抓出 ID 並成功匯出。

3. 官方渲染檢查工具在沙箱內無法執行

專案附帶了一支 lint-render.py 檢查腳本，但它在我們的沙箱環境裡碰壁，跳出 setsockopt: Operation not permitted 權限阻礙。我們沒有假裝官方工具檢查通過，而是自行編寫了一套基於 Playwright 的小型無頭瀏覽器驗收腳本，在保留沙箱安全邊界的前提下，確認所有節點位置無誤，整趟檢查耗時不到一秒鐘。

4. 原始範例偷連 Google 字型，需手動切回本機字型

官方模板預設會自動連往 Google Fonts 載入字體。如果你的使用環境講求完全離線，或者不想讓外部網路知道你正在開啟文件，記得在產出時加上 --system-fonts 旗標，並在樣式表中指名本機字型（如思源黑體）。經實測，改用本機字型後在完全斷網模式下載入，頁面外連請求為零，依然清晰美觀。

5. 手機螢幕上需左右滑動檢視

在寬度只有 390 像素的手機螢幕上瀏覽時，這套系統並不會把 1280 像素寬的大圖暴力縮小成看不清的螞蟻字。它的處理方式是維持內容尺寸，在外部容器提供橫向滑動軸。在手機上查看需要左右滑動，如果你的業務場景極度仰賴手機單手閱讀，這點必須事先告知同仁。

［圖：手機初始畫面.png］

五、可以拿來做什麼？商業與落地途徑

如果你是一家接案工作室、一人顧問公司或中小企業，這個工具有三個很具體的落地場景：

1. 顧問梳理客戶業務的「即時交付物」

顧問在替傳統門市或電商客戶梳理流程與架構時，常常需要把客戶口頭描述的混亂流程（例如訂單客訴、瑕疵品退換、換貨手續）整理清楚。過去手動拉圖要花不少時間，現在讓 AI 代理讀取這套規範後把文字貼入，就能產出一份排版整齊、可再修改的向量流程圖，直接貼進提案簡報或結案報告，專業形象立刻提升。

2. 中小企業內部的視覺化作業標準書（SOP）

許多店家新人流動率高，文字手冊幾千字沒人有耐心讀完。把關鍵的請款、退款、備料流程轉成網頁版架構圖，嵌入內部的 Notion 或是自架內部系統首頁。因為是純 HTML 檔案，日後規則微調只要用文字編輯器改幾個字，不需要整張圖重做。

3. 自動化任務的「視覺化執行收據」

如果你平常有用腳本跑自動化任務（例如每日對帳、訂單匯整），可以在腳本執行完畢時，順便產出一張結構流程圖存檔。管理人員一眼就能看出這次自動化究竟走了常規主線，還是觸發了特定例外分支。

六、誰適合用、誰現在別碰？

誠實評估導入門檻，才能避免浪費時間。

適合誰

• 經常需要對外交付報告、架構圖的獨立顧問、技術人員與專案經理。
• 希望統一團隊內部文檔視覺風格，但不想每個月被商業繪圖軟體扣月費的小型團隊。
• 習慣使用命令列或已在工作流中引進 AI 代理的開發者。

誰現在別碰

• 習慣用滑鼠在視窗裡隨性拖拉形狀、完全不想看到程式碼的純非技術人員。
• 需要即時資料庫連動、複雜動態篩選或互動式點擊動畫的高階儀表板需求。

七、授權條款與安全紅線

在把開源工具投入實際業務前，法律與資料安全邊界必須先搞清楚：

1. 商業使用條款：diagram-design 採用寬鬆的 MIT 授權，商業使用、修改原始碼或將產出的圖形轉交給客戶完全合法，只需保留原專案著作權聲明。但要注意的是，圖表內部如果引用了客戶的商標圖片或特定商業字體，該素材的權利歸屬必須依照個別授權處理。
2. 隱私與資料安全：該專案原始設定具備連線外部字型與抓取網站的機制。商業應用時，務必將字型來源切換為本機字型（如 --system-fonts），並在隔離的本機目錄中執行，嚴禁將未去敏的客戶私密資料透過未受控的網路直接發送。

如果你也在本機試跑過這個專案，或在其他環境遇到不同報錯，歡迎透過站內聯絡管道交流實測心得。