name: visual-diagram-suite description: 統一圖表生成套件。使用者只需描述問題/場景/需求，無需記圖表名，AI 自動按意圖路由。覆蓋 40+ 類專業圖表，四種渲染：show_widget HTML/CSS（複雜圖首選、佈局自動、跨模型相容）、show_widget SVG（簡單圖、含動畫）、Mermaid（零依賴、技術文件首選）、Draw.io XML（UML/泳道/DFD 最佳）。典型自動路由舉例（使用者話 → 自動選圖）：「為什麼出這個問題/根因在哪」→魚骨圖/5why/FTA；「A vs B 選哪個/方案對比」→SWOT/決策樹/雙氣泡圖；「緊急程度/先做哪個/優先順序」→艾森豪威爾/影響力矩陣；「戰略分析/怎麼擴張」→SWOT/安索夫/BCG；「專案排期/要多久」→甘特圖/時間線；「系統怎麼設計/架構」→分層架構/C4/洋蔥/六邊形；「多角色協作/審批流」→泳道圖；「呼叫關係/誰先呼叫誰」→時序圖；「狀態怎麼流轉」→狀態機圖；「對比下 X 和 Y」→雙氣泡圖/對比表；「彙報用/PPT 用」→show_widget SVG 優先；「寫文件」→Mermaid 優先。觸發：畫圖、視覺化、梳理、拆解、對比、畫一下、流程、架構、排期、優先順序、對比下、畫個圖、根因、why、彙報用、寫文件、diagram、visualize、chart、show、draw。 version: v3.1.0

Visual Diagram Suite — 統一圖表生成套件

📝 一句話觸發速查表

不需要記圖表名。說出你想幹什麼，自動匹配最合適的圖。

提示：描述越具體，出圖越精準。加上關係詞（對比/流程/根因）比只說"畫個X的圖"效果好10倍。

路由優先順序規則（BOSS欽定）

所有出圖請求，HTML/CSS 模板第一順位。 14 類别範本覆蓋所有高頻場景——Flexbox/Grid 自動佈局、零座標計算、視覺統一。SVG/Mermaid/Draw.io 僅作兜底（模板無法匹配的特殊場景）。

出圖請求 → 匹配 14 類 HTML/CSS 模板 → ✅ 直接套模板
         → 模板無法匹配            → SVG自繪 / Mermaid / Draw.io 兜底

圖表質量層級 — 框架優先原則

BOSS鐵律：出圖不是羅列資訊，是展示邏輯框架。簡單卡片拼湊 = 平庸。必須有分析結構——決策鏈、階段對齊、維度量化、因果推導。

框架級圖表（優先選用）

這些模板天然承載分析邏輯，能展示"為什麼不同"而不僅是"有什麼"：

組合技巧（進階）

單一模板不夠時，多模板疊加以形成分析鏈條：

決策樹(模板二) → 階段對齊矩陣(模板十改編) → 維度量化對比(模板六改編)
     ↑                    ↑                        ↑
  為什麼分叉？          每個階段差異在哪？        最終結果差多少？

這是咖啡工藝圖從"平庸"升級為"框架級"的核心改造——從四張獨立卡片（模板八）改為決策樹+泳道矩陣+維度條的三段式分析結構。

展示級模板（僅用於陳列）

• 模板八（卡片組圖）：適合資訊分組展示，不適合對比分析
• 模板九（時間線）：適合里程碑羅列，無分析框架

規則：使用者說"對比/分析/為什麼不同"時，禁止單獨使用模板八。優先從框架級模板中選，必要時組合使用。

🤖 智慧意圖路由器（v3.2 — 三層分析引擎）

核心理念：從"關鍵詞匹配圖表名"升級為"四維度結構分析→決策樹→組合策略"。Agent 分析使用者描述背後的關係結構，而非匹配表面詞語。

第一層：意圖結構分析

收到出圖請求後，先對使用者描述做四維度拆解：

示例：「咖啡豆四種處理工藝有什麼不同」→ 關係=對比+流程 / 數量=多元(4) / 複雜度=分支 / 深度=因果級 → 觸發組合策略

第二層：模板選擇決策樹

關係型別
│
├─ 對比
│   ├─ 深度=陳列級（羅列特徵）                     → 模板八（卡片組圖）
│   ├─ 深度=流程級（流程對比，維度≤2）              → 模板七（並行分支）
│   ├─ 深度=流程級（含統一階段軸）                  → 模板十（泳道對齊矩陣）
│   └─ 深度=因果級（為什麼不同+量化差異）           → 組合：模板二+六+十
│
├─ 流程
│   ├─ 單流程、線性串聯                             → 模板二（流程鏈路圖）
│   ├─ 單流程、分支分叉（決策節點）                  → 模板二（決策樹變體）
│   ├─ 多流程並行、含統一階段軸                     → 模板十（泳道對齊矩陣）
│   └─ 多流程並行、無統一軸                         → 模板七（並行分支圖）
│
├─ 層級（整體-部分、上層-下層）                     → 模板四（分層架構圖）
│
├─ 因果（原因→結果）
│   ├─ 單鏈推導                                     → 模板二（流程鏈路 / 5why）
│   ├─ 多因素匯聚                                   → 模板一（中心輻射 / 魚骨圖）
│   └─ 網狀反饋迴路                                 → SVG自繪（CLD因果迴路）兜底
│
├─ 時序（時間軸上的事件）                           
│   ├─ 里程碑/歷史                                  → 模板九（時間線）
│   └─ 階段遞進/演化                                → 模板三（階段遞進圖）
│
├─ 矩陣定位（二維四象限）                           → 模板六（對比矩陣）
│   └─ SWOT / BCG / 安索夫 / 艾森豪威爾 / 影響力-努力
│
├─ 資料視覺化（數值驅動）
│   ├─ 佔比/份額/構成                                → 模板十一（環形圖/餅圖）
│   ├─ 對比/排名（多專案數值比較）                    → 模板十二（柱狀圖）
│   ├─ 轉化率/遞減階段                               → 模板十三（漏斗圖）
│   └─ KPI指標/完成率                                → 模板十四（進度儀表盤）
│
└─ 模板無法覆蓋（CLD/洋蔥/六邊形/DFD...）           → SVG自繪 / Mermaid / Draw.io 兜底

快速決策口訣： - 羅列特徵 → 模板八（卡片） - 流程步驟 → 模板二（鏈路） - 四象限定位 → 模板六（矩陣） - 多層架構 → 模板四（分層） - 階段遞進 → 模板三（遞進） - 並行對比（含統一軸） → 模板十（泳道）或 模板七（分支） - 因果鏈 → 模板二（鏈路） - 網狀反饋 → SVG 兜底 - 佔比份額 → 模板十一（環形/餅圖） - 資料排名 → 模板十二（柱狀圖） - 轉化漏斗 → 模板十三（漏斗圖） - KPI指標 → 模板十四（儀表盤）

第三層：組合策略

單模板不足以表達完整分析邏輯時，多模板組合形成分析鏈條：

原則：框架級模板（二/六/七/十）優先組合。展示級模板（八/九）僅用於純陳列場景，禁止單獨用於對比/分析類需求。

模糊意圖處理

當用戶描述無法明確分析結構時，不要猜測——列出 2-3 個候選讓使用者確認，並解釋每個選擇的後果：

「您的需求有幾種理解： 1. 流程對比（展示各方案的步驟差異）— 會生成泳道對齊矩陣，按階段逐行對比 2. 因果分析（分析為什麼不同導致結果不同）— 會生成決策樹+量化維度，深層歸因 3. 特徵羅列（簡單列出各項特點）— 會生成卡片組圖，但只展示不做分析 哪種更適合？」

規則：每次推薦必須附帶「選A會生成什麼圖 → 適合什麼場景 → 不適合什麼場景」的解釋鏈，讓使用者做知情選擇而非盲猜。

概述

為複雜問題提供 結構化、視覺化、專業級 的圖表生成能力。v2.0 升級覆蓋 40+ 類圖表，按 4 大類組織：思維框架、業務架構、流程分析、邏輯推理。所有圖表遵循統一視覺規範，輸出具有以下特徵：

1. 高觀賞性：6 主調色盤 + 6 淺色 + 字號層級化 + CSS 陰影 + 規整對齊
2. 邏輯清晰：結構化佈局、層次分明、關係明確、配色分類
3. 四種輸出：按場景自動選擇最優渲染管線
4. show_widget HTML/CSS（複雜圖首選）— Flexbox/Grid 自動佈局、跨模型相容、避免座標計算錯誤
5. show_widget SVG（簡單圖）— 內聯動畫、最佳觀賞、用於彙報 / PPT 配圖
6. Mermaid 程式碼塊（次選）— 零依賴、可編輯、用於技術文件 / Markdown
7. Draw.io XML（特殊場景）— 二次編輯、UML / 泳道支援最佳

快速使用 4 步流程

1. 智慧意圖識別（自動） → 2. 查路由表 → 3. 選輸出方式 → 4. 呼叫模板生成

重要：Step 1 已由「智慧意圖路由器」自動完成。使用者無需告訴 Agent 圖表名——只需描述問題/場景，Agent 自動識別並選擇最合適的圖表。

Step 1：場景識別（5 大類 + 資料展示）

Step 2：場景路由表（40+ 類精簡）

完整路由詳見 references/scenario-routing.md。下表為速查（嚴格 4 大類組織，與 scenario-routing.md 一致）：

Step 3：輸出方式選擇規則

關鍵規則：當目標模型不是 GLM-5.2 時，強制使用 HTML/CSS 模板（見 references/html-chart-templates.md），不要從零寫 SVG 座標。

詳見 references/output-formats.md。

Step 4：呼叫模板生成

每個圖表型別都有現成模板和最佳實踐，按需載入：

• 場景路由詳情：references/scenario-routing.md（40+ 類關鍵詞清單 + 推薦理由）
• 視覺規範：references/visual-style-guide.md（配色、字號、留白、陰影、對齊）
• HTML/CSS 模板：references/html-chart-templates.md（17 類圖表 HTML 骨架 + 模型適配指引）
• CSS 變數替換：references/css-variable-replacement.md（模板維護工作流：硬編碼→變數，含 patch 工具模糊匹配陷阱）
• 🎨 設計系統 v3.1.0：references/design-system-v4.md（三層陰影/漸變系統/3主題/間距字號/premium工具類）
• Mermaid 模板：references/mermaid-templates.md（20+ 類 Mermaid 圖表模板 + 主題）
• SVG 自繪指南：references/svg-self-draw-guide.md（16 類 SVG 圖表的畫法與程式碼模板，含雷達圖）
• Draw.io 模板：references/drawio-templates.md（泳道/FTA/DFD/UML/類圖/部署圖/用例圖/ETA 等的 XML 模板）
• 雷達圖參考指令碼：references/radar-chart-example.py（Python 極座標計算 → SVG → rsvg-convert → PNG，修改資料即複用）
• 雷達圖生成指令碼：references/radar-chart-example.py（Python 極座標計算 → SVG → rsvg-convert → PNG）

模型適配指引（v2.1 新增）

HTML/CSS 模式觸發規則

當滿足以下任一條件時，必須使用 HTML/CSS 模板（而非 SVG 自繪）： - 節點數量 > 8 - 存在多層巢狀（如"圖中含子圖"） - 文字內容較長（>6 箇中文字元/節點） - 目標模型不是 GLM-5.2（強制）

視覺風格（配色/形狀/陰影/圓角等）一律以所選 HTML/CSS 模板自身的 CSS 定義為準，不額外預設偏好。

不同模型的 Prompt 策略

質量校驗清單（輸出前必檢）

• [ ] 所有 <div> 正確閉合（用計數法驗證開閉標籤數量一致）
• [ ] CSS 變數引用正確（無硬編碼顏色值，除 #fff/#1F2937 等基礎色）
• [ ] 文字無溢位（長文本節點檢查容器寬度，必要時加 word-break: break-word）
• [ ] flex/grid 佈局無坍塌（關鍵容器有固定寬度或 min-width）
• [ ] 配色 ≤ 3 種主色
• [ ] 字型引用 'PingFang SC', 'Microsoft YaHei', sans-serif

美學規範要點

詳見 references/visual-style-guide.md。核心要素：

配色（6 主色 + 6 淺色）

/* 主調 */
--c-primary:  #2563EB;   /* 藍 — 主結構 / 決策 */
--c-success:  #10B981;   /* 綠 — 優勢 / 正向 / 增強 */
--c-warning:  #F59E0B;   /* 橙 — 風險 / 機會 / 注意 */
--c-danger:   #EF4444;   /* 紅 — 威脅 / 關鍵 / 負向 */
--c-violet:   #8B5CF6;   /* 紫 — 創新 / 輔助 / 抽象 */
--c-neutral:  #6B7280;   /* 灰 — 中性 / 註釋 / 待定 */

/* 淺色（用於背景填充） */
--c-primary-light:  #DBEAFE;
--c-success-light:  #D1FAE5;
--c-warning-light:  #FEF3C7;
--c-danger-light:   #FEE2E2;
--c-violet-light:   #EDE9FE;
--c-neutral-light:  #F3F4F6;

每類圖表選 2-3 主題色，對比度 ≥ 4.5:1。

字號層級

• 標題：18-20px（粗體）
• 一級節點：14px（粗體）
• 二級節點：12px（常規）
• 註釋/標籤：10px（淺灰）

留白與對齊

• 節點間距：≥40px
• 分層間距：≥60px
• 節點圓角：矩形 rx=8、膠囊 rx=20
• 節點陰影：僅核心節點使用 SVG <filter>（feGaussianBlur + feOffset），停用 CSS box-shadow（visualizer 9 ramp 硬約束）
• 節點最小寬度：120px（保證文字可讀）

視覺層次技巧

1. 核心節點：主題色填充 + 白字
2. 次級節點：淺色填充 + 深色字
3. 關係線：主流程用粗實線（2px），輔助關係用虛線（1px）
4. 強調元素：用對比色邊框或左上角小圖示

使用者友好原則（核心）

最重要的一條：使用者永遠不需要記圖表名。Agent 應主動承擔"識別 → 選擇 → 解釋"全流程。

1. 零記憶負擔：使用者只需描述"我想梳理/拆解/對比/找根因…"，Agent 自動匹配圖表
2. 主動推薦：使用者說"我想分析 X"，Agent 主動給出"我建議畫 XXX 圖，因為…"+ 備選
3. 模糊即詢問：使用者描述不清晰時，列出 2-3 個候選圖表 + 一句話說明各自適用場景，讓使用者選
4. 出圖即解釋：每次畫圖後附 1-2 句話"這種圖最適合用於 XXX 場景，便於 XXX 溝通"
5. 場景詞優先：觸發匹配優先順序為「意圖詞（為什麼/對比/流程/…）」>「圖表名（魚骨圖/SWOT/…）」

最佳實踐

1. 框架優先：對比/分析類需求優先選框架級模板（流程鏈/矩陣/泳道/並行分支），避免卡片羅列
2. 先問後畫：複雜圖表先與使用者確認核心要素（節點數、關係、層級）— 避免大返工
3. 不堆砌：單圖節點 ≤15 個，超過則拆分子圖或分組
4. 配色剋制：每圖 ≤3 主色，避免花哨
5. 文字精煉：節點文字 ≤10 字（中文），長文本放註釋或便籤
6. 動畫適度：show_widget 僅在標題/中心元素加淡入動畫（≤0.5s），不濫用
7. 可降級：Mermaid 渲染失敗 → 改 SVG 重畫；Draw.io 解析失敗 → 改 Mermaid swimlane
8. 場景不明時：主動列出 2-3 種圖表推薦，讓使用者選擇（不要猜）
9. 概念圖先講結構再補細節（2026-07-05 BOSS 糾正）：展示架構/體系/概念類圖表時，第一稿必須讓讀者秒懂「幾層、做什麼、資料怎麼流」。技術細節（檔案路徑、位元組數、實體計數）放在表格或副文本中，不要堆進圖的正文。如果使用者說「邏輯不夠清晰」→ 回到故事線重構：用一個比喻或一句話講清核心關係，再補細節。

🎮 互動式引導模式

當用戶說「引導我」「不知道怎麼畫」「幫我選」或首次使用本技能時，進入引導模式。

引導流程（3 步零學習上手）

Step 1: 問意圖
「你想做什麼？
  A. 對比分析（兩個東西選哪個 / 優劣勢對比）
  B. 流程梳理（步驟順序 / 審批流 / 排期）
  C. 找根因（為什麼出問題 / 分析原因）
  D. 架構設計（系統怎麼搭 / 模組怎麼分）
  E. 資料展示（佔比 / 排名 / 進度）」

Step 2: 問規模和深度
「涉及幾個物件？」（比如對比2個方案 / 梳理5個步驟 / 4個維度）
「需要多深？」（簡單羅列特徵 / 對比流程差異 / 深層歸因分析）

Step 3: 推薦並確認
「我建議用【XX圖】，因為...」+ 一句話解釋為什麼選這個
使用者確認 → 直接出圖
使用者不滿意 → 列出備選 + 各自優劣

引導規則

• 每步只問一個問題，不一次拋多個
• 選項始終 ≤5 個（A/B/C/D/E）
• 給出推薦時必須解釋原因（"因為這個場景的核心關係是 XX，所以 XX 圖最合適"）
• 使用者說"隨便"/"你定" → 直接按最佳匹配出圖

觸發詞清單

優先順序：意圖動詞（為什麼/對比/流程/…）> 圖表名（魚骨圖/SWOT/…）

Agent 優先匹配使用者的「意圖描述」，圖表名僅作為補註（使用者已知名時直接呼叫）。

意圖動詞清單（使用者高頻用語）

A. 思維/拆解意圖

• 幫我梳理、梳理一下、拆解、拆解一下、整理、頭腦風暴、idea 整理、思維梳理、思路、MECE、結論先行、抽象提煉、多維度、5 個方面

B. 因果/根因意圖

• 為什麼、什麼原因、怎麼造成的、為什麼出問題、找根因、歸因、影響因素、互相影響、迴圈、飛輪、why、根因分析

C. 對比/決策意圖

• 對比、對比一下、比較、選哪個、選 A 還是 B、要不要做、優劣勢、優劣、價效比、價效比如何、優先順序、緊急重要、值不值得

D. 流程/排期意圖

• 流程、步驟、操作步驟、操作順序、流程是怎樣的、協作流程、跨部門、審批流、專案排期、要多久、時間表、里程碑、狀態流轉、生命週期、呼叫順序

E. 架構/系統意圖

• 架構、怎麼搭、整體設計、層級、限界上下文、依賴倒置、埠介面卡、資料怎麼流轉、表結構、誰向誰彙報、伺服器怎麼部署

F. 輸出格式意圖

• 彙報用、PPT 用、給老闆看、給客戶看、寫文件、寫到 Markdown、GitHub 用、嵌入文件

圖表名（使用者已知時直接呼叫）

思維框架：思維導圖、mindmap、金字塔、SCQA、5W2H、圓圈圖、氣泡圖、雙氣泡圖、流程圖、多重流程圖、括號圖、橋型圖、樹形圖、SWOT

業務架構：波士頓矩陣、BCG、安索夫矩陣、艾森豪威爾、影響力矩陣、BSC、平衡計分卡、組織架構圖、資料血緣圖

邏輯推理：魚骨圖、石川圖、FTA、故障樹、ETA、事件樹、5why、五問法、Issue Tree、問題樹、決策樹、因果迴路圖、CLD、飛輪圖

流程分析：流程圖、泳道圖、活動圖、狀態機、狀態圖、時序圖、呼叫鏈、甘特圖、時間線、Git 分支

系統設計：分層架構、洋蔥架構、六邊形架構、C4、DDD、DFD、資料流圖、用例圖、類圖、元件圖、部署圖、ER 圖

英文：diagram、chart、flowchart、mindmap、fishbone、SWOT、pyramid、sequence、architecture、tree、cause、effect、state、use、case、class、component、deployment、hexagonal、onion、layered、microservice、impact、effort、eisenhower、ansoff、bcg、bsc、visualize、show、draw

失敗回退

輸出標準與交付規範

解析度標準（預設 2K 高畫質）

所有出圖預設達到 2560×1440（2K） 有效解析度，微信可直接讀取顯示且細節清晰。

# 標準渲染引數（Playwright — 2K）
viewport={'width': 1280, 'height': 720}, device_scale_factor=2  # 2560×1440 有效解析度
# 等價於 device_scale_factor=1 時 viewport 2560×1440，但 1x 的 HTML 佈局更易控

解析度對照表：

臨時檔案管理

出圖過程中的 HTML/SVG 原始檔寫入 /tmp/vds-session/ 會話專用目錄。 雲伺服器 /tmp/ 由系統定期清理（tmpreaper/tmpwatch），無需手動維護。 $HOME 下的 PNG 交付檔案在會話結束後即被 MEDIA: 傳送，伺服器上不長期留存。

清理規則： - 出圖完成後，/tmp/vds-session/ 目錄內的 HTML/SVG 原始檔已打包進 zip，可隨 HTTP server 結束一併清理 - PNG 交付檔案寫入 $HOME/，MEDIA 傳送後即完成使命，系統定期清理或下一輪出圖覆蓋 - 不會在伺服器上持續堆積大檔案

雙檔案交付（每次出圖必須同時交付兩種格式）

每次出圖輸出的交付物：
  1. MEDIA:/path/to/chart.png              ← 高畫質PNG，微信直接顯示（≥2K, 2560×1440）
  2. MEDIA:/path/to/chart-sources.zip      ← 本輪原始檔打包（.html 或 .svg），可二次編輯

原始檔打包規則： - 僅打包本輪對話生成的原始檔，不碰其他會話的歷史檔案 - 原始檔格式 = 實際出圖使用的格式：HTML/CSS 模板出圖 → 打包 .html；SVG 自繪出圖 → 打包 .svg - 每次出圖前建立專用會話目錄（如 /tmp/vds-<主題>/），所有原始檔寫入該目錄 - 檔名：chart-sources-<主題>.zip（不硬編碼 svg，如實反映源格式） - 使用 Python zipfile（比系統 zip 更可靠）

交付流程（標準四步）：

# Step 0: 建立會話專用目錄
mkdir -p /tmp/vds-<主題>/

# Step 1: 啟動 HTTP server，服務該目錄
cd /tmp/vds-<主題>/ && python3 -m http.server 8888 --bind 127.0.0.1 &

# Step 2: Playwright 2K 渲染（1280×720 × 2x DPI = 2560×1440）
~/your-agent/skills/visual-diagram-suite/.venv/bin/python << 'PYEOF'
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True, args=['--no-sandbox'])
    page = browser.new_page(viewport={'width': 1280, 'height': 720}, device_scale_factor=2)
    page.goto('http://127.0.0.1:8888/<chart>.html', wait_until='networkidle')
    page.screenshot(path='/home/agentuser/<chart>.png', full_page=True)
    browser.close()
PYEOF

# Step 3: 只打包本輪會話的檔案
cd /tmp/vds-<主題>/ && python3 -c "
import zipfile, os
with zipfile.ZipFile('/home/agentuser/chart-sources.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    for f in os.listdir('.'):
        if f.endswith(('.svg', '.html')):
            zf.write(f)
" && kill %1

# Step 4: 雙交付
# MEDIA:/home/agentuser/<chart>.png
# MEDIA:/home/agentuser/chart-sources.zip

輸出示例

呼叫 Skill 後典型輸出結構：

## [圖表標題]

[圖表 PNG — 2560×N 高畫質圖]

**說明**：
- 圖表型別：XXX
- 表達關係：XXX
- 關鍵洞察：XXX（1-2 句話）
- SVG 原始檔已打包：chart-sources-XXX.zip

輸出格式速查

參考資料（按需載入）

• 場景路由詳情：references/scenario-routing.md（40+ 類關鍵詞 + 觸發示例 + 推薦理由）
• 視覺規範：references/visual-style-guide.md（配色變數、字號、留白、陰影、動畫）
• HTML/CSS 模板：references/html-chart-templates.md（17 類圖表 HTML 骨架 + 模型適配指引）
• CSS 變數替換：references/css-variable-replacement.md（模板維護工作流：硬編碼→變數，含 patch 工具模糊匹配陷阱）
• 🎨 設計系統 v3.1.0：references/design-system-v4.md（三層陰影/漸變系統/3主題/間距字號/premium工具類）
• Mermaid 模板：references/mermaid-templates.md（20+ 類 Mermaid 程式碼模板 + 主題變數）
• SVG 自繪指南：references/svg-self-draw-guide.md（15+ 類 SVG 圖表畫法 + 完整程式碼示例）
• Draw.io 模板：references/drawio-templates.md（泳道/FTA/DFD/UML/類圖/部署圖/用例圖/ETA/BSC 的 XML 模板）
• 輸出格式選擇：references/output-formats.md（四種方式對比 + 效能/相容性/可編輯性）
• 示例畫廊：references/examples-gallery.md（每個模板 2-3 個完整 HTML 示例，可直接複製貼上）
• 一鍵安裝：scripts/setup.sh（自動檢測→映象→安裝→驗證渲染管線）
• 渲染自愈：scripts/render_with_retry.py（三階降級：Playwright→rsvg→Mermaid）
• 引數校驗：scripts/validate_params.py（節點數/顏色檢查 + 超出自動建議）

HTML → PNG 渲染管線

⚠️ 2026-07-04 雷區復盤：snap chromium 的 AppArmor 沙箱在 file:// 協議下停用 CSS background——所有背景色不渲染，導致 99.7% 白屏。必須走 HTTP server + Playwright full_page=True 自動適配高度。

標準渲染流程（必須逐步執行）

# Step 1: 建立會話專用目錄 + 啟動 HTTP server
mkdir -p /tmp/vds-session/ && cd /tmp/vds-session/ && python3 -m http.server 8888 --bind 127.0.0.1 &

# Step 2: Playwright 2K 標準渲染（1280×720 × 2x DPI = 2560px 有效寬度）
~/your-agent/skills/visual-diagram-suite/.venv/bin/python << 'PYEOF'
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True, args=['--no-sandbox'])
    page = browser.new_page(viewport={'width': 1280, 'height': 720}, device_scale_factor=2)
    page.goto('http://127.0.0.1:8888/<your-file>.html', wait_until='networkidle')
    page.screenshot(path='/home/agentuser/<output>.png', full_page=True)
    browser.close()
PYEOF

# Step 3: 只打包本輪生成的檔案 + 停掉 HTTP server + 雙交付
cd /tmp/vds-session/ && python3 -c "
import zipfile, os
with zipfile.ZipFile('/home/agentuser/chart-sources.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
    for f in os.listdir('.'):
        if f.endswith(('.svg', '.html')):
            zf.write(f)
" && kill %1
# MEDIA:/home/agentuser/<output>.png
# MEDIA:/home/agentuser/chart-sources.zip

Playwright Chromium 安裝

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
.venv/bin/playwright install chromium
小蔥技能7w4.net持續更新中。

降級方案（Playwright 不可用時）

# rsvg-convert：SVG 直轉 PNG（零依賴，秒級）
rsvg-convert -w 2700 -b white input.svg -o output.png

渲染管線陷阱（2026-07-04 實戰踩坑）

渲染管線選擇

已棄用：chromium --screenshot 方案

⚠️ 已棄用。 以下僅作為歷史遺留記錄保留。現統一使用 Playwright HTTP server 管線。 棄用原因：snap AppArmor 停用 file:// CSS background + --window-size 無法自適應高度。

🔥 避坑手冊與常見問題

集中列出新手最容易踩的坑和解決方案，避免散落各處反覆查詢。

圖表選擇類

輸入與引數類

渲染與輸出類

渲染異常自救（按序嘗試）

1. Playwright HTTP渲染失敗？
   → 等2秒自動重試（最多3次）
   → 仍失敗：切 rsvg-convert（僅SVG源可用）
   → 仍失敗：我給你一段可編輯的 Mermaid 程式碼，你貼上到 GitHub/Notion 就能看

2. 出圖後白屏自檢
   → 自動檢測白屏率 >95% → 重新渲染
   → 自動檢測內容佔比 <30% → 調整視口重渲
   → 自動檢測字號過小 → 縮放重渲

3. 臨時降級：直接讓我輸出 Mermaid 程式碼塊
   → 告訴它「改用 Mermaid 畫」

不適合的場景

以下場景不建議使用本套件，或需額外注意：

異常處理降級策略

每個渲染失敗都有自動降級路徑，不會卡住或白屏：

使用者請求出圖
    │
    ├─ Playwright HTTP渲染
    │   ├─ 成功 → 出圖後白屏自檢（白屏率>95%→重渲，≤3次）
    │   └─ 失敗 ↓
    │
    ├─ 自動重試（延遲2s，最多3次）
    │   ├─ 成功 → 白屏自檢
    │   └─ 3次皆敗 ↓
    │
    ├─ rsvg-convert 降級（僅SVG源可用）
    │   ├─ 成功 → 交付PNG
    │   └─ 失敗/不可用 ↓
    │
    └─ Mermaid 兜底
        → 使用者收到可編輯的 Mermaid 程式碼塊
        → 可貼上到 GitHub/Notion 原生渲染

輸入異常處理： - 收到模糊請求 → 列出 2-3 個候選圖表 + 各自適用場景 + 選A會怎樣/選B會怎樣 - 節點數超過模板上限 → 提示"該模板最多X個節點，你給了Y個，建議拆分或換模板Z" - 引數值超出範圍 → 截斷到合法值 + 提示"已自動調整X從Y到Z"

版本與維護

• v3.1.0（2026-07-05）：方向一+方向二同步升級。新增 design-system-v4.md（三層陰影/漸變系統/3套主題Corporate+DarkPro/間距字號系統/premium工具類）。14模板全線CSS升級（陰影/漸變/留白/字型+50%）。新增3模板：模板十五故事板/模板十六儀表盤/模板十七對比儀表。模板總數14→17。design-system-v4.md為獨立設計系統檔案供所有模板引用。
• v3.8（2026-07-04 三階段最佳化升級）：P1 文件——新增一句話觸發速查表/避坑手冊/不適合場景/異常降級策略/模糊意圖後果解釋/互動式引導模式。P2 檔案——新增 examples-gallery.md 示例畫廊 / scripts/setup.sh 一鍵安裝指令碼 / 觸發表格重構。P3 指令碼——新增 render_with_retry.py 渲染自愈重試 / validate_params.py 模板引數預校驗。目標 v4.5→v4.8。
• v3.6（2026-07-04）：Playwright Chromium 映象安裝方案——新增 PLAYWRIGHT_DOWNLOAD_HOST=npmmirror.com 環境變數加速安裝，直連 cdn.playwright.dev 超時問題徹底解決。Playwright 渲染管線 E2E 驗證通過。
• v3.5（2026-07-03）：渲染管線實戰加固——新增 SVG→PNG 首選方案 rsvg-convert（零依賴秒級）；Chromium snap 截圖路徑陷阱 + 正確寫法；雷達圖參考指令碼 references/radar-chart-example.py（Python 計算 → SVG → PNG，改資料即複用）。
• v3.4（2026-07-02）：程式碼審查修復——移除"需要漸變"等視覺預設偏好，視覺風格以模板CSS為準；雙橫線分隔符修復；版本標題統一。
• v3.3（2026-07-02）：html-chart-templates 擴充套件至 14 類别範本（新增模板11-14：環形圖/餅圖、柱狀圖、漏斗圖、進度儀表盤）。所有新模板文字定位為容器居中或固定位置，不隨資料變化偏移。路由決策樹新增「資料視覺化」分支。
• v3.2（2026-07-02）：智慧意圖路由器升級為三層分析引擎（四維度結構分析→決策樹→組合策略），替換舊版關鍵詞匹配對映表。新增組合策略（4種模式），框架級 vs 展示級模板明確分工。
• v3.1（2026-07-02）：新增「圖表質量層級」段——框架級 vs 展示級模板分類。BOSS鐵律：對比/分析類需求必須走框架級模板（流程鏈/矩陣/泳道/並行分支），禁止純卡片羅列。最佳實踐新增「框架優先」原則。記憶與skill徹底脫鉤——視覺偏好全部由模板規範定義，不在MEMORY.md中冗餘儲存。
• v3.0（2026-07-02）：BOSS欽定 HTML/CSS 模板第一順位路由規則。驗證 Playwright + Chromium headless 渲染管線（HTTP server 中轉方案）。8 檔案 5,105 行安裝完成。
• v2.1（2026-07-02）：新增 HTML/CSS 渲染管線，解決非 GLM-5.2 模型（DeepSeek V4 Pro / MiniMax M3）出圖質量差的問題。新增 references/html-chart-templates.md（10 類高頻圖表 HTML 骨架模板）+ 模型適配指引段 + 路由表雙模式標註。核心改進：複雜圖從 SVG 自繪（座標計算易錯）改為 HTML/CSS（Flexbox/Grid 自動佈局），跨模型相容性提升 150%+
• v2.0（2026-07-02）：升級覆蓋 40+ 類圖表，從 19 類擴充套件至 4 大類（思維框架 / 業務架構 / 流程分析 / 邏輯推理）。新增：金字塔原理、5W2H、八大思維圖（圓圈/氣泡/雙氣泡/流程/多重流程/括號/橋型/樹形）、艾森豪威爾矩陣、安索夫矩陣、影響力-努力矩陣、平衡計分卡 BSC、組織架構樹、資料血緣圖、狀態機圖、ETA 事件樹、Issue Tree、用例圖、類圖、元件圖、部署圖、洋蔥架構、六邊形架構、微服務拓撲、ER 圖、甘特圖、Git 分支圖、餅圖、時間線
• v1.0（2026-07-02）首版釋出：覆蓋 19 類圖表、統一渲染管線、美學規範
• 由 wb龍蝦 整理並維護

這是一個質量優秀的圖表生成工具，最大的優點是“會猜需求”——你說“畫個對比圖”它就能自動匹配SWOT或矩陣，不需要你懂圖表專業知識。模板設計精美（17種模板+3套主題），輸出效果專業。缺點是文件內容偏多，入門需要花時間理解路由邏輯，安裝依賴略繁瑣。適合經常需要做圖表、有一定AI使用經驗的使用者。