tech-diagram-gif

name	tech-diagram-gif
description	繪製流程圖、架構圖、走向圖（流量走向動畫），最終交付 GIF。當提到「畫流程圖」「畫架構圖」「走向圖」「流程動畫」「diagram」時自動啟用。不適用於資料視覺化圖表（用 dataviz）或網頁 UI 設計（用 frontend-design）。
allowed-tools	Read, Grep, Glob, Bash, Write, Edit

Tech Diagram GIF — 技術圖表繪製與 GIF 匯出

不引入 Python/cairosvg 管線的技術圖表流程：手寫 SVG（依 vendored 風格規範）→ 瀏覽器渲染自檢 → 匯出無縫循環 GIF。 風格規範 vendored 自 fireworks-tech-graph（MIT，見 LICENSE.txt）； 只收編其 markdown 規範，不引入其 Python/cairosvg/FFmpeg 管線。

硬閘門

1. 結構未確認前，不寫任何 SVG — 先用純文字把節點/分組/連線定案（工作流程第 1 步）。
2. 交付物只有 GIF（使用者硬規則）。SVG 僅為中間產物：GIF 產出並驗證後即刪除， 不留在交付目錄。唯一例外：環境無 ffmpeg 時依第 5 步退化交付 SVG 並附裝法與資安說明 （SVG 格式可含 script，收件方有信任成本；本 skill 產的 SVG 零 script，交付前必驗證）。
3. 渲染自檢不可省 — 沒親眼看過渲染結果不得宣稱完成。

工作流程

1. 結構確認（純文字，不畫圖）

把要畫的內容整理成清單給使用者確認，格式：

節點（N）：① 名稱（語意桶）→ ② …
分組（M）：分組名 / 涵蓋節點
連線與語意：A→B 主流程（金）/ C⇢D 條件檢查（虛線）/ 自迴圈…

使用者確認或修改 → 定案才進下一步。內容事實（節點名稱、流程順序）不確定時回問，不自行腦補。

2. 選風格與動畫模式

風格	檔案	何時用
Style 8 Dark Luxury（預設）	references/style-8-dark-luxury.md	架構、流程、資料流、拓撲 — 通用首選
Style 2 Dark Terminal	references/style-2-dark-terminal.md	開發者風格；UML 類（ER/時序/狀態機/use case）優先用此 — Style 8 深底吃 UML 細節與人形，比較表也不適合
Style 11 Event Transit	references/style-11-event-transit.md	事件流/串流拓撲（Kafka/Pulsar/NATS、消費者群、DLQ）— 提到「事件流」「地鐵圖」「Kafka 拓撲」時用
Style 12 Ops Pulse	references/style-12-ops-pulse.md	事故排查/SLO review（golden signals、critical path、trace 瀑布）— 提到「事故圖」「golden signals」「reliability」時用

動畫兩種模式（詳見 references/motion-narrative.md）：

• 循環流動（預設）：小球沿線跑（animateMotion）或 dash 脈衝
• 建置 → 營運（敘事）：開場無連線 → 逐條畫入 → 營運流動 → 淡出循環 — 對外展示/README hero 用

使用者無明示偏好時用預設，不必多問；圖型落在特定風格的甜蜜區時主動建議換風格（一句話，不反覆）。

3. 手寫 SVG

• 版面規則照 references/svg-layout-best-practices.md（間距 ≥80px、正交轉角、標籤偏移、z-order； 該檔僅取版面規則，其 cairosvg/PNG 匯出段落不適用本 skill）
• 節點複雜或含 DB/佇列/使用者/決策時，用 references/icons.md 的語意圖形 （DB 圓柱、佇列管、LLM 雙框、Agent 六角形、User 人形、決策菱形、文件摺角）取代一律圓角矩形
• 量化版面預算照 references/composition-quality-contract.md：0 交叉、每邊 ≤2 折、 繞路比 ≤1.35、節點間 ≥40px、容器 gutter ≥20px；先排容器與列才排線、保留跨層走廊、 同側多線分 port、legend 不進流程走廊。超出預算 → 調節點位置或拆圖，不硬塞
• 色票/節點語意色桶照所選風格檔；畫布建議 viewBox 0 0 1440 1080 — 注意風格檔的字級/間距以 960 寬為基準，用 1440 畫布時需等比放大（約 ×1.5）
• 字體堆疊必含跨平台 CJK 後備（以本段為準，覆蓋風格檔的 PingFang SC）： 襯線 Georgia,'Times New Roman','Songti TC','Noto Serif CJK TC',serif、 無襯線 -apple-system,'Helvetica Neue','PingFang TC','Noto Sans CJK TC',sans-serif （macOS 已驗證；Linux 走 Noto 後備，未實測）
• 小球規則：核心 r4 + 光暈 r8 opacity 0.22、顏色跟隨箭頭語意、等速（dur ∝ 路徑長）、 長路徑放 2 顆錯開半週期
• 所有動畫 dur 與 begin 必須整除同一個總循環長（如 7.2s）— GIF 才能無縫循環
• dash 脈衝模式：實線疊亮色 stroke-dasharray: 7 41 動 stroke-dashoffset；位移量須為 dasharray 週期整數倍

4. 渲染自檢迴圈

用 playwright MCP 渲染並親眼檢查，已知陷阱與對策：

陷阱	對策
browser_navigate 擋 file://（回 Access to "file:" protocol is blocked）、localhost 逾時	單張看圖：SVG 包進 HTML 後轉 base64 data URI 導航（實測可行）。多幀連拍改走下一列，別把整份 HTML 編碼成字串傳來傳去
逐幀截圖要反覆換頁 / 讀本機檔	用 browser_run_code_unsafe，裡面的 page.goto('file://…') 不受工具層的 file 封鎖（限制在 MCP 工具層，不在瀏覽器）。同一次呼叫可跑完整個 144 幀迴圈
run_code 裡拿不到 fs	require 回 require is not defined，import('node:fs') 回 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING。要讀本機檔一律靠 page.goto('file://…')，不要嘗試在 code 裡讀檔
無限動畫使 screenshot 逾時	先 svg.pauseAnimations() 再截圖，並加 animations: 'disabled'
換頁後截圖仍逾時	瀏覽器殘留狀態所致 — browser_close 重開再導航
動畫是否真的在動	setCurrentTime(t) 定格兩個時間點各截一張，肉眼比對位移
延遲啟動的球停在畫面左上角 (0,0)	錯開相位一律用負值 begin（如 -3.6s），不用正延遲
瀏覽器捲軸被截進畫面（成品出現假捲軸）	包裝頁 CSS 加 overflow:hidden，截圖加 clip 限定 SVG 區域，交付前抽查四邊像素應為背景色
截圖輸出路徑受限	browser_take_screenshot 只能寫入其 allowed roots（通常是專案根/.playwright-mcp）；截完移出並清理，勿留在 repo。run_code 裡的 page.screenshot({path}) 可直接寫任意路徑（實測寫進 scratchpad 成功），連拍時用這條

檢查項：文字無溢出、箭頭不穿節點、標籤不壓線、小球在路徑上且有位移、 版面預算達標（0 交叉、每邊 ≤2 折、節點間 ≥40px — 見 composition-quality-contract）。 發現問題 → 改 SVG 重渲染,迴圈至乾淨。

5. GIF 匯出

先偵測 ffmpeg（command -v ffmpeg）：

• 有 ffmpeg：逐幀定格（pauseAnimations() + setCurrentTime(i*DUR/N) + 截圖，20fps × 總循環長）→

  ffmpeg -framerate 20 -i f%03d.png \
    -vf "split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" \
    -loop 0 out.gif
  

  • fps 用 20（或 25），不用 10：10fps 小球每格跳動明顯，使用者回饋「卡卡的」；GIF 幀延遲單位 是 1/100 秒，fps 須整除 100，且 50fps 會被多數播放器強制放慢，20/25 是流暢與相容的平衡
  • 幀數多時分兩段 run_code 截（單次呼叫有逾時上限）
  • 交付原尺寸，勿為壓檔縮小（使用者回饋過縮到 1080 寬「有點小張」；1440 寬 144 幀約 700KB 可接受）
• 無 ffmpeg：退化交付 SVG，明確告知「裝 ffmpeg 後可轉 GIF」（macOS：brew install ffmpeg），不硬轉。

6. 交付前驗證

• SVG 零 script：grep -cEi "<script|\bon[a-z]+[[:space:]]*=|javascript:|foreignObject" <svg> 必須為 0 （涵蓋事件處理器 on* 與 foreignObject，不只 onload）
• GIF 抽 2 幀（ffmpeg -fps_mode passthrough -vf "select=eq(n\,K)"）確認小球位置不同（動畫真的燒進去了）
• 暫存幀目錄與中間產物 SVG 清理乾淨（交付目錄只留 GIF）
• 成品輸出到使用者專案的當下目錄 ./diagrams/（使用者硬規則，不放 /tmp 揮發區）； 目錄不存在時 mkdir -p ./diagrams 自動建立； 該目錄若在 git repo 內且未被追蹤，提醒一句可加入 .gitignore 或自行 commit，不代決定
• 交付訊息附：GIF 路徑與開啟方式（退化交付 SVG 時才附資安說明）

常見錯誤

錯誤	正確做法
跳過結構確認直接畫	硬閘門 1：文字清單定案才動筆
動畫週期隨意設	全部整除同一總循環長，GIF 才無縫
只驗 getAnimations() 不看畫面	定格截圖親眼比對（API 只證明在跑，不證明可見）
交付 SVG 給外部收件人	一律 GIF；SVG 附資安說明留內部
截圖留在 repo 根目錄	移到暫存目錄並清理
機器特定路徑寫進產出流程	用相對/暫存路徑，保持可攜