fireworks-tech-graph 詳細安裝與使用教學

本文件 deep-dive 整理 yizhiyanhua-ai/fireworks-tech-graph 的安裝、設定、API 使用、應用情境，並附上對所有 scripts/ 與 SKILL.md 的資安審查結果。閱讀對象：想把這個 skill 納入個人 / 團隊 Claude Code 工作流的開發者。

1. 專案定位（一句話總結）

把「畫圖」變成「描述」：用中／英文敘述系統架構，幾秒內得到出版品質的 SVG + 1920px PNG。

它是什麼？

• Claude Code Skill：以 markdown + Python + Bash 組成的能力包，由 Claude Code 在偵測到觸發詞時自動載入
• 本地離線執行：所有運算在本機完成，不呼叫任何外部 API（無 telemetry、無雲端依賴）
• 以 Python 模板引擎 + 風格 metadata 為核心：generate-from-template.py 把 JSON 結構描述渲染成 SVG，STYLE_PROFILES dict 控制 7 種視覺風格的所有顏色 token

它不是什麼？

• 不是 Mermaid / draw.io 替代品（互補關係）
• 不是 LLM-only 黑盒：generator 邏輯、style token、validation rule 全部 open
• 不是 SaaS：沒有帳號、沒有訂閱

2. 安裝指南

2.1 先決條件

2.2 步驟 1 — 安裝 Skill

1# 一鍵安裝（從 GitHub）
2npx skills add yizhiyanhua-ai/fireworks-tech-graph

⚠️ 不要 寫成 npx skills add @yizhiyanhua-ai/fireworks-tech-graph（npm package 名）。skills add 解析來源限定為 GitHub repo 或本地路徑；npm 頁面只是公開分發頁。

替代方案：手動 clone

1git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git \
2  ~/.claude/skills/fireworks-tech-graph

更新到最新版

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

2.3 步驟 2 — 安裝 PNG renderer（擇一）

驗證安裝（任一即可）：

1python3 -c "import cairosvg; print(cairosvg.__version__)"
2rsvg-convert --version

2.4 步驟 3 — 確認 Skill 已載入

在 Claude Code 中輸入觸發詞測試：

1畫一張簡單的 RAG 架構圖

若 Claude Code 自動分類為 architecture diagram + style 1，並產出 .svg / .png，代表 skill 安裝成功。

2.5 已知安裝問題

3. 核心架構解析

3.1 檔案總覽

 1fireworks-tech-graph/
 2├── SKILL.md                            # 590 行：圖類型分類規則 + shape vocab + arrow semantics
 3├── package.json                        # npm metadata（42 行）
 4├── README.md / README.zh.md            # 雙語使用說明
 5│
 6├── references/                         # 9 份參考文件（Skill 動態載入）
 7│   ├── style-1-flat-icon.md            # 白底，預設風格
 8│   ├── style-2-dark-terminal.md        # #0f0f1a，等寬字
 9│   ├── style-3-blueprint.md            # 藍圖網格
10│   ├── style-4-notion-clean.md         # Notion 風
11│   ├── style-5-glassmorphism.md        # 玻璃態
12│   ├── style-6-claude-official.md      # 溫暖奶油色（Anthropic）
13│   ├── style-7-openai.md               # 純白（OpenAI）
14│   ├── icons.md                        # 40+ 產品 icon SVG path
15│   ├── style-diagram-matrix.md         # 風格 × 圖類型推薦表
16│   └── svg-layout-best-practices.md
17│
18├── agents/openai.yaml                  # 給 OpenAI Agent runtime 的 metadata
19│
20├── fixtures/                           # 7 個 regression test fixture
21│   ├── mem0-style1.json
22│   ├── tool-call-style2.json
23│   ├── microservices-style3.json
24│   ├── agent-memory-types-style4.json
25│   ├── multi-agent-style5.json
26│   ├── system-architecture-style6.json
27│   └── api-flow-style7.json
28│
29├── scripts/                            # 工具腳本（核心）
30│   ├── generate-diagram.sh             # 181 行：CLI 入口，validate + export
31│   ├── generate-from-template.py       # 1587 行：SVG 生成核心
32│   ├── validate-svg.sh                 # 306 行：7 項 SVG 驗證檢查
33│   ├── test-all-styles.sh              # 143 行：批次跑 fixtures
34│   └── README.md                       # 269 行：scripts 內部使用說明
35│
36├── templates/                          # 10 個 SVG 起始模板
37│   ├── architecture.svg / data-flow.svg / flowchart.svg
38│   ├── sequence.svg / state-machine.svg / use-case.svg
39│   ├── er-diagram.svg / comparison-matrix.svg / timeline.svg
40│   └── agent-architecture.svg
41│
42└── assets/samples/                     # 7 個 showcase PNG

3.2 雙路徑生成模型

Skill 提供兩種 SVG 生成方式，視複雜度選用：

路徑 A：直接由 Claude 寫 SVG（簡單圖適用）

 1# Claude 在 SKILL.md 強制要求的「Python list method」
 2python3 << 'EOF'
 3lines = []
 4lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
 5lines.append('  <defs>')
 6# ... 每行獨立 append，避免 truncation / 拼字錯誤
 7lines.append('</svg>')
 8
 9with open('/path/to/output.svg', 'w') as f:
10    f.write('\n'.join(lines))
11EOF

路徑 B：經 generate-from-template.py（複雜圖建議）

1python3 ./scripts/generate-from-template.py \
2  architecture \
3  ./output/arch.svg \
4  '{"title":"My System","style":1,"nodes":[...],"arrows":[...]}'

JSON schema 主要欄位：

3.3 STYLE_PROFILES（核心資料結構）

generate-from-template.py 第 69 行起的 STYLE_PROFILES dict，是整個風格系統的單一事實來源：

 1STYLE_PROFILES = {
 2    1: {
 3        "name": "Flat Icon",
 4        "background": "#ffffff",
 5        "node_fill": "#ffffff", "node_stroke": "#d1d5db",
 6        "arrow_colors": {
 7            "control": "#7c3aed", "write": "#10b981",
 8            "read": "#2563eb", "data": "#f97316", ...
 9        },
10        ...
11    },
12    # 2–7 同結構
13}

設計意義：

• 風格不是 markdown 註解，而是 executable 的程式碼欄位
• 改 token 即改全圖，無需到處 search & replace
• 新增 style 8 只要再加一個 dict entry

3.4 Arrow Override 系統

當生成的箭頭路徑不理想時，只改 JSON 不改 SVG：

4. Helper Scripts 詳細用法

4.1 generate-diagram.sh — CLI 入口

1./scripts/generate-diagram.sh -t <type> -s <style> -o <output> [-w <width>] [--no-validate]

參數：

• -t 圖類型（14 種）：architecture / data-flow / flowchart / sequence / comparison / timeline / mind-map / agent / memory / use-case / class / state-machine / er-diagram / network-topology
• -s 風格 1–7（預設 1）
• -o 輸出 SVG 路徑（PNG 自動同名）
• -w PNG 寬度（預設 1920）
• --no-validate 跳過 SVG 驗證

注意：此腳本本身不生成 SVG，只負責 validate + export。SVG 內容仍由 Claude Code（或你手動）寫入。

4.2 generate-from-template.py — 核心生成器

1# 基本：JSON 經 argv 傳入
2python3 scripts/generate-from-template.py architecture out.svg '{...}'
3
4# 進階：JSON 經 stdin 傳入
5cat my-spec.json | python3 scripts/generate-from-template.py architecture out.svg

支援的 template_type（DEFAULT_VIEWBOX 對照）：

4.3 validate-svg.sh — 7 項 SVG 檢查

1./scripts/validate-svg.sh path/to/file.svg

檢查項目：

亮點：第 5 項是內嵌的 200 行 Python，把 SVG <line> / <path> 分段成 segments，逐一檢查是否與 <rect> / <circle> / <ellipse> interior 重疊 —— 這是這個 skill 與一般 SVG 工具的核心差異點。

4.4 test-all-styles.sh — 批次回歸測試

1./scripts/test-all-styles.sh

對 fixtures/*.json 7 個樣本逐一執行：

1. generate-from-template.py 產 SVG
2. validate-svg.sh 7 項檢查
3. 嘗試 cairosvg → rsvg-convert 匯出 PNG
4. 統計 PASSED / FAILED 並輸出測試報告

輸出：test-output/<basename>_<timestamp>.svg/.png

5. 應用場景

5.1 個人開發者

5.2 AI / Agent 工程

5.3 Infra / Cloud

5.4 文件 / 簡報專業用途

5.5 軟體工程教育

• 14 種完整 UML 圖（class / use-case / sequence / state-machine / activity / ER / …）
• 內建 shape vocabulary 與 cardinality 標準（1, 0..*, 1..*）
• 適合做 OOAD / 系統設計課的範例產生器

6. 資安掃描報告（2026-05-13）

範圍：scripts/ 全部 4 個檔案、SKILL.md、package.json、agents/openai.yaml。掃描方式：人工 grep + 結構分析。

6.1 結論

🟢 整體風險：低。可安心納入個人 / 團隊本地工作流。

6.2 詳細結果

6.3 使用建議

6.4 已修復的歷史問題

• Issue #1：早期 SKILL.md frontmatter 格式錯誤（已 close，2026-04-11）
• Issue #5：codex 線框重疊（已 close，2026-04-12）
• Issue #13：手動微調生成結果（已 close，2026-04-15，藉由 arrow override 系統解決）

7. 常見問題（FAQ）

Q1：和 Mermaid 比起來，什麼時候該用 fireworks-tech-graph？

結論：快速文字流程圖用 Mermaid；需要視覺品質、品牌化、多風格切換用 fireworks-tech-graph。

Q2：可以離線使用嗎？

✅ 完全可以。安裝完成後（cairosvg 已 pip install），所有運算在本機完成，無任何網路依賴。

Q3：生成的 SVG 可以二次編輯嗎？

✅ 可以。SVG 是純內聯（無外部字型 / CSS / icon CDN），用 Inkscape / Illustrator / VSCode 都能編輯。

Q4：可以新增第 8 種風格嗎？

可以。在 scripts/generate-from-template.py 的 STYLE_PROFILES dict 加一個 entry，並寫一份 references/style-8-xxx.md。

Q5：支援中文 / 中日韓字元嗎？

✅ 支援。STYLE_PROFILES 的 font_family 已包含 'PingFang SC' / 'Microsoft YaHei' / 'Microsoft JhengHei' / 'SimHei' 等 fallback。

Q6：為什麼預設用 cairosvg 而不是 rsvg-convert？

歷史上預設是 rsvg-convert，但 2026-05-11（commit b76a0dd）切換到 cairosvg：rsvg-convert 對 <foreignObject> / 複雜 CSS / <style> block 渲染不完整，導致 PNG 出現缺邊框 / 缺文字的 bug。cairosvg 基於 Cairo，CSS 支援好得多。

Q7：Windows 可以用嗎？

部分支援。Bash 腳本在原生 Windows 不可用（Issue #7 open），建議用 WSL；Python generate-from-template.py 與 cairosvg 在 Windows native 可正常運作。

8. 進階技巧

8.1 Visual Self-Review（若 runtime 支援讀圖）

SKILL.md 第 9 步建議：產出 PNG 後讀回看，若發現以下問題就重畫並再 export：

• 箭頭穿過元件 interior
• 標籤碰撞 lifeline / 其他標籤
• 元件重疊
• alt-frame 文字壓在訊息上
• legend 蓋到內容

常見修法：

1. 拉開 inter-row / inter-column gutter
2. 為箭頭標籤加 <rect fill="canvas_bg" opacity="0.95"/> 背景
3. 把同層重複箭頭收攏成 single “delegates down” rail
4. 增大 viewBox（不要硬塞）
5. filter 元素離 viewBox 邊緣 ≥ 30px（否則 Chrome / cairosvg 會剪掉一邊邊框）

8.2 Chrome headless --window-size 陷阱

若用 puppeteer / 自製 headless Chrome 流程：--window-size=W,H 不是繪圖區大小。Chrome 即使 --headless=new 也會吃掉 ~15–20% 寬高（scrollbars + 內部 UI）。

修法：

1# SVG 1280×580，要 3× DPR，正確指令：
2--window-size=1600,800   # 比 SVG 大 1.2 倍
3# 之後 PIL / ImageMagick crop 回 3840×1740

或直接走 puppeteer page.setViewport()，沒有此問題。

8.3 Post-Generation Arrow Optimization 工作流

 1# 1. 讀現有 SVG，識別有問題的箭頭
 2# 2. 找到對應 JSON entry（用 source/target 配對）
 3# 3. 加 source_port / target_port 修出入方向
 4# 4. 加 corridor_x / corridor_y 把平行箭頭分到不同 lane
 5# 5. 萬不得已才用 route_points 強制 waypoint
 6# 6. 重跑 generate-from-template.py + validate-svg.sh
 7
 8# 範例：兩條平行箭頭分開
 9# JSON：
10[
11  { "source": "nodeA", "target": "nodeB", "corridor_y": [280] },
12  { "source": "nodeC", "target": "nodeD", "corridor_y": [320] }
13]

9. 整合進其他工作流

9.1 與 quarkdown 串接（本專案的場景）

1# Step 1：用 fireworks-tech-graph 產出技術圖（PNG）
2# Step 2：在 quarkdown 文件中以 ![](path/to/diagram.png) 引用
3# Step 3：qd compile 產 HTML，圖片自動 embed

9.2 與 kami 串接（出版品質文件）

1# Step 1：fireworks-tech-graph 產出 SVG
2# Step 2：在 kami HTML 模板的 <img> tag 引用 SVG（保留向量品質）
3# Step 3：kami build 用 WeasyPrint 渲染 PDF

9.3 在 CI 自動更新文件圖

1# .github/workflows/update-diagrams.yml
2- run: pip install cairosvg
3- run: python3 scripts/generate-from-template.py architecture docs/arch.svg < specs/arch.json
4- run: ./scripts/validate-svg.sh docs/arch.svg
5- run: python3 -c "import cairosvg; cairosvg.svg2png(url='docs/arch.svg', write_to='docs/arch.png', scale=2)"

10. 重點摘要 Checklist

• 安裝：npx skills add yizhiyanhua-ai/fireworks-tech-graph
• PNG renderer：pip install cairosvg（強烈推薦，勿用 rsvg-convert）
• 驗證：在 Claude Code 輸入「畫一張 RAG 架構圖」測試
• 複雜圖：透過 generate-from-template.py + JSON 規格產出
• 驗證 SVG：必跑 validate-svg.sh（內含 7 項檢查，含箭頭碰撞）
• 資安：本地離線使用無風險；包成 web service 須加 path 白名單
• 箭頭優化：用 corridor_x / target_port 微調，避免改動 SVG
• 跨工具串接：可與 quarkdown / kami / CI pipeline 整合
• 更新：每月 npx skills add ... --force -g -y，因為 active development（每週多次 PR）

11. 進一步閱讀

• 主 repo：https://github.com/yizhiyanhua-ai/fireworks-tech-graph
• npm package 頁：https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph
• 作者商業案例：https://bradzhang.dev/en/case-studies/fireworks-tech-graph
• License：MIT

本教學版本：2026-05-13；對應 repo commit 8ad56b8 之後的 main 分支。