fireworks-tech-graph

Fireworks Tech Graph

生成生產級品質的 SVG 技術圖表，並透過 cairosvg（推薦）、rsvg-convert 或 puppeteer 匯出為 PNG。

安裝來源

從 GitHub 安裝此 Skill：

npx skills add yizhiyanhua-ai/fireworks-tech-graph

公開套件頁面：

https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph

請勿直接將 @yizhiyanhua-ai/fireworks-tech-graph 帶入 skills add 指令，因為 CLI 需要 GitHub 或本機儲存庫來源。

更新指令：

npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y

輔助腳本（推薦）

scripts/ 目錄中提供四個輔助腳本，用於穩定生成與驗證 SVG：

1. generate-diagram.sh - 驗證 SVG + 匯出 PNG

./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

• 驗證現有的 SVG 檔案
• 驗證通過後匯出 PNG
• 範例：./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

2. generate-from-template.py - 從範本建立初始 SVG

python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'

• 載入內建的 SVG 樣板
• 依 JSON 輸入渲染節點、箭頭與圖例項目
• 自動跳脫文字內容以保持 XML 格式有效

3. validate-svg.sh - 驗證 SVG 語法

./scripts/validate-svg.sh <svg-file>

• 檢查 XML 語法
• 確認標籤成對平衡
• 驗證標記（marker）參照
• 檢查屬性完整性
• 驗證路徑（path）資料

4. test-all-styles.sh - 批次測試所有樣式

./scripts/test-all-styles.sh

• 測試多種圖表尺寸
• 驗證所有生成的 SVG
• 生成測試報告

何時使用腳本：

• 生成複雜 SVG 時使用腳本，以避免語法錯誤
• 腳本提供自動化驗證與錯誤回報
• 推薦用於生產環境的圖表製作

何時直接生成 SVG：

• 元素較少的簡單圖表
• 快速原型設計
• 當您需要完全掌控 SVG 結構時

工作流程（請務必依序執行）

1. 分類 圖表類型（請參閱下方「圖表類型」）
2. 擷取結構 — 從使用者描述中識別層級、節點、邊（連接線）、流程與語意群組
3. 規劃版面 — 套用該圖表類型的版面配置規則
4. 載入樣式參考 — 除非使用者另有指定，否則務必載入 references/style-1-flat-icon.md；載入對應的 references/style-N.md 以取得精確的色彩標記 (color tokens) 與 SVG 樣式範本
5. 對映節點至形狀 — 使用下方的形狀圖庫 (Shape Vocabulary)
6. 檢查圖示需求 — 如需已知產品圖示，請載入 references/icons.md
7. 撰寫 SVG（採行自適應策略，參閱下方「SVG 生成策略」）
8. 驗證：執行 python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" 檢查 XML 語法
9. 匯出 PNG：使用 cairosvg（推薦）。詳細方法比較請參閱下方的 SVG → PNG 轉換 章節
10. 回報 生成的檔案路徑
11. （選擇性）視覺自我審查 — 若您的執行環境支援讀取圖片，請將匯出的 PNG 載入進行檢視。語法正確並不代表視覺呈現完美：箭頭可能會穿過元件內部、標籤可能與生命線或其他標籤重疊碰撞、框線可能交疊、異動框 (alt-frame) 文字可能壓在訊息上，或是圖例覆蓋了內容。若發現上述情形，請修正 SVG 並重新匯出，重複此步驟直至渲染圖片乾淨無誤。常見修正方式：
    • 調整箭頭路徑，使其穿過框線之間的空隙，而非直接穿越元件內部
    • 將箭頭標籤往外移動 6-8px 避開箭頭線（位移優先）；僅在位移仍不足時加上背景方框
    • 加寬列與列、欄與欄之間的間距，讓同一層級的箭頭有清晰的通道
    • 將重複跨層的箭頭整合成單一條在內容區塊外側的「向下委派」軌道
    • 將圖例/註記移出任何會與箭頭或標籤交會的區域
    • 增加 viewBox 的高度/寬度，而非將元素排得更緊湊
    • 若套用濾鏡（如 drop-shadow 陰影、模糊）的元素有一側邊框缺失，請將其移離 viewBox 邊緣 ≥30px，或直接移除濾鏡，改用顏色/對比度進行視覺分隔
      若執行環境不支援圖片讀取，請直接靜默跳過此步驟 — 切勿胡亂推測。

圖表類型與版面配置規則

架構圖 (Architecture Diagram)

節點 = 服務/元件。分組為 水平層級（上→下 或 左→右）。

• 典型層級：用戶端 (Client) → 閘道/負載平衡 (Gateway/LB) → 服務層 (Services) → 資料/儲存層 (Data/Storage)
• 使用 <rect> 虛線外框群組同一層級的相關服務
• 箭頭方向依循資料/請求的流向
• ViewBox：標準為 0 0 960 600，較高的垂直堆疊可使用 0 0 960 800

資料流圖 (Data Flow Diagram)

強調 資料如何流向何處。聚焦於資料轉換過程。

• 為每一條箭頭標註資料類型（例如：「embeddings」、「query」、「context」）
• 主要資料路徑使用較粗的箭頭 (stroke-width: 2.5)
• 控制/觸發流程使用虛線箭頭
• 依資料類別為箭頭配色（不限於 Agent/RAG，應靈活運用語意）

流程圖 (Flowchart / Process Flow)

順序性的決策與程序步驟。

• 優先使用由上至下佈局；較寬的流程可採用由左至右
• 菱形代表決策分支、圓角矩形代表程序、平行四邊形代表輸入/輸出 (I/O)
• 節點標題保持簡短（≤3 個字詞）；詳細資訊放入副標題
• 網格對齊節點：x 軸座標以 120px 為間距，y 軸以 80px 為間距

Agent 架構圖 (Agent Architecture Diagram)

展示 AI Agent 如何進行推理、呼叫工具與管理記憶體。
務必考量的核心概念層級：

• 輸入層 (Input layer)：使用者、查詢、觸發條件
• Agent 核心 (Agent core)：LLM、推理迴圈、規劃器 (Planner)
• 記憶體層 (Memory layer)：短期記憶（上下文視窗）、長期記憶（向量/圖資料庫）、情節記憶 (Episodic)
• 工具層 (Tool layer)：工具呼叫、API、搜尋、程式碼執行
• 輸出層 (Output layer)：回應、操作、邊際效應 (Side-effects)
  使用環狀箭頭（迴圈弧線）展示疊代推理過程。在視覺上區隔不同的記憶體類型。

記憶體架構圖 (Memory Architecture Diagram, Mem0/MemGPT 風格)

專注於記憶體操作的特化 Agent 圖表。

• 分別展示記憶體的 寫入路徑 與 讀取路徑（使用不同箭頭顏色）
• 記憶體層級：工作記憶體 (Working Memory) → 短期記憶 → 長期記憶 → 外部儲存庫
• 標註記憶體操作名稱：store()、retrieve()、forget()、consolidate()
• 儲存層級採用堆疊矩形或分層圓柱體呈現

時序圖 (Sequence Diagram)

參與者之間依時間順序排列的訊息互動。

• 參與者表示為垂直 生命線 (lifelines)（頂部標籤 + 垂直虛線）
• 訊息表示為生命線之間的水平箭頭，時間順序由上至下
• 啟用方塊（生命線上的細長填色矩形）展示作用中的處理狀態
• 使用 <rect> 迴圈/分歧外框 (loop/alt frames) 進行群組，標籤置於左上角
• ViewBox 高度 = 80 + (訊息數量 × 50)

比較/功能矩陣圖 (Comparison / Feature Matrix)

多種方法、系統或元件的橫向對比。

• 欄位標頭 = 系統名稱，列標頭 = 屬性特徵
• 列高：40px；欄寬：至少 120px；標頭列高：50px
• 支援項目：淺色背景（如 #dcfce7）+ ✓ 勾選符號；不支援項目：#f9fafb 填色
• 交錯的列填色 (#f9fafb / #ffffff) 以提升可讀性
• 最多建議 5 欄以保持最佳可讀性；超越 5 欄時請拆分為兩張圖表

時間軸 / 甘特圖 (Timeline / Gantt)

展示持續時間、階段與里程碑的水平時間軸。

• X 軸 = 時間（週/月/季）；Y 軸 = 項目/任務/階段
• 進度條：圓角矩形，依類別配色，標籤置於內部或旁邊
• 里程碑標記：特定 x 座標上的菱形或實心圓，標籤置於上方
• ViewBox：典型為 0 0 960 400；時間跨度較長時可拓寬為 0 0 1200 400

心智圖 / 概念圖 (Mind Map / Concept Map)

從核心概念發散的放射狀版面。

• 中心節點位於 cx=480, cy=280
• 第一層分支：圍繞中心均勻分布 (360/N 度)
• 第二層分支：從第一層以 30-45° 偏移角度延伸
• 分支使用貝茲曲線的 <path>，避免使用直線

類別圖 (Class Diagram - UML)

展示類別、屬性、方法與相互關係的靜態結構圖。

• 類別框 (Class box)：三分格矩形（名稱 / 屬性 / 方法），最小寬度 160px
  • 頂格：類別名稱，粗體、置中（抽象類別使用 斜體）
  • 中格：標註存取修飾子的屬性（+ 公用/public, - 私有/private, # 保護/protected）
  • 底格：方法簽章，採用相同的存取修飾子標記
• 關係 (Relationships)：
  • 繼承 (Inheritance/extends)：實線 + 空心三角形箭頭，子類別 → 父類別
  • 實作 (Implementation/interface)：虛線 + 空心三角形箭頭，類別 → 介面
  • 關聯 (Association)：實線 + 開放箭頭，標註多重性 (1, 0.., 1..)
  • 聚合 (Aggregation)：實線 + 容器端的空心菱形
  • 組合 (Composition)：實線 + 容器端的實心菱形
  • 相依 (Dependency)：虛線 + 開放箭頭
• 介面 (Interface)：名稱上方加註 <<interface>> 原型，或使用圓形/棒棒糖記號
• 列舉 (Enum)：加註 <<enumeration>> 原型的分格矩形，列舉值置於底格
• 配置：父類別置於上方，子類別置於下方；介面置於實作者的左右兩側
• ViewBox：標準為 0 0 960 600；階層較深時使用 0 0 960 800

用例圖 (Use Case Diagram - UML)

從使用者角度展示系統功能。

• 參與者 (Actor)：火柴人圖示（圓形頭部 + 身體線條），放置於系統邊界外
  • 標籤置於火柴人下方，字型 13-14px
  • 主要參與者在左側，次要/支援參與者在右側
• 用例 (Use case)：橢圓形，標題置中，最小尺寸 140×60px
  • 名稱保持動詞片語：「建立訂單」、「處理付款」
• 系統邊界 (System boundary)：大型矩形，虛線邊框，左上角標註系統名稱
• 關係：
  • 包含 (Include)：從基礎用例指向被包含用例的虛線箭頭 <<include>>
  • 擴充 (Extend)：從擴充用例指向基礎用例的虛線箭頭 <<extend>>
  • 泛化 (Generalization)：實線 + 空心三角形（特化 → 泛化）
• 配置：系統邊界置中，參與者在外，用例在內
• ViewBox：標準為 0 0 960 600

狀態機圖 (State Machine Diagram - UML)

實體的生命週期狀態與狀態轉移。

• 狀態 (State)：圓角矩形，標註狀態名稱，最小尺寸 120×50px
  • 內部活動：小字標示 entry/ action、exit/ action、do/ activity
  • 初始狀態 (Initial state)：實心黑圓 (r=8)，出一條箭頭
  • 終止狀態 (Final state)：空心圓 (r=12) 包裹實心圓 (r=8)
  • 選擇 (Choice)：小型空心菱形，出箭頭上附帶條件防衛標籤 [condition]
• 轉移 (Transition)：箭頭，可附帶標籤 event [guard] / action
  • 條件防衛 (Guard) 包裹於方括號內
  • 動作 (Action) 接在 / 之後
• 複合/巢狀狀態：包含子狀態的大矩形，附帶名稱分頁頁籤
• 分流/匯合 (Fork/join)：粗體水平或垂直黑條（同步線）
• 配置：初始狀態在左上，終止狀態在右下，流程由上至下
• ViewBox：標準為 0 0 960 600

ER 圖 (Entity-Relationship Diagram)

資料庫 Schema 與資料關係。

• 實體 (Entity)：矩形，標頭為實體名稱（粗體），下方列出屬性
  • 主鍵 (Primary key) 屬性：加底線
  • 外鍵 (Foreign key)：斜體或標註 (FK)
  • 最小寬度：160px；屬性字體大小：12px
• 關係 (Relationship)：連接線上的菱形
  • 菱形內標籤：「has」、「belongs to」、「enrolls in」
  • 實體附近的基數標籤：1、N、0..1、0..*、1..*
• 弱實體 (Weak entity)：雙邊框矩形，搭配雙邊框菱形關係
• 關聯實體 (Associative entity)：菱形與矩形複合體（矩形內包菱形）
• 線條樣式：識別性關係使用實線，非識別性關係使用虛線
• 配置：實體排成 2-3 列，關係介於相關實體之間
• ViewBox：標準為 0 0 960 600；實體較多時可加寬為 0 0 1200 600

網路拓撲圖 (Network Topology)

實體或邏輯網路基礎架構。

• 設備 (Devices)：圖示化矩形或圓角矩形
  • 路由器 (Router)：圓形