bybit-exchange/svg-diagram

svg‑diagram – AI 代理生成的 SVG 的統一風格與 lint 工具

是什麼 – 一個零相依性的輕量級 Node 工具，為手寫 SVG 圖表定義嚴格的視覺風格，並提供命令列 lint 工具（svg‑lint），用於檢查完成的 SVG 是否符合該風格。該儲存庫包含 技能（markdown 檔案 SKILL.md），可安裝至多個主流編碼代理（Claude、Gemini、Copilot 等），使代理精確掌握如何設定框體、放置文字、繪製連接線、選擇顏色。

對 AI 代理為何重要 – 現代程式碼生成代理經常需要輸出圖表（架構草圖、流程圖、基準測試圖）。透過提供明確的算術規則而非模糊的「看起來好看」，該技能使輸出具有決定性，可作為純文字審查，並能透過 lint 工具自動驗證。這減少了生成後的手動編輯，確保了不同代理間的一致性。

核心特性

• 統一風格 – 固定的 viewBox 邊距、字型大小、顏色三元組、箭頭幾何、CJK 安全字型堆疊，以及明確的轉義規則。所有規則均在 SKILL.md 中文件化。
• 零相依性 lint 工具 – 一個單一的 Node 腳本（tools/svg‑lint/bin/svg‑lint.mjs），無需 npm install 即可在任何機器上執行。執行 12 項檢查（轉義、viewBox、字型堆疊、框體尺寸、基線、間距、箭頭標記、溢出、重疊、調色板、連接線幾何、文件模型健全性檢查）。
• 代理無關安裝 – 使用 npx skills add bybit-exchange/svg-diagram -g 可將技能和 lint 工具複製到數十種代理的對應目錄中。技能的 front-matter name 決定安裝路徑，因此倉儲可移動而不會破壞安裝。
• 人類可讀的修復建議 – 每個 lint 失敗報告目前值、允許範圍/值，以及一行「修復」建議，例如 font-family: absent → 'PingFang SC', …。
• 合規圖表圖庫 – 十個範例 SVG 展示了每條規則（佈局、創作循環、lint 門禁、資料流、技能生命週期、倉儲架構、多代理安裝、CJK 字型處理、分層路由、A/B 基準）。
• 測試套件 – npm run lint:svg:all 驗證隨附的 SVG；npm test 執行 984 個單元測試，確保 lint 工具和技能保持可靠。

如何使用

1. 為你的代理安裝該技能：

   npx skills add bybit-exchange/svg-diagram -g   # 全域安裝，適用於所有代理
   

2. 在新的代理會話中請求生成圖表；代理將宣布正在使用 svg‑diagram 技能，並遵循其中定義的算術規則。
3. 代理輸出 diagram.svg 後，執行 lint 工具驗證合規性：

   node ~/.claude/skills/svg-diagram/tools/svg-lint/bin/svg-lint.mjs diagram.svg
   

   加上 --json 以取得機器可讀輸出。
4. 若任何檢查失敗，根據修復提示編輯 SVG，或調整技能描述後重新執行。

專案存在的原因 – 讓 AI 生成的圖表 可作為程式碼審查：每個座標都明確，每個樣式都是呈現屬性，且 lint 工具保證輸出符合共享視覺語言，無需依賴佈局引擎或外部 CSS。這提升了可重現性，簡化了基於 diff 的審查，並確保 CJK 字元在各平台上正確渲染。

授權 – MIT。