---
title: "用 Claude Fable 開發 Super Mermaid：VS Code Mermaid 圖表的美化與高解析匯出"
description: "整理我用 Claude 開發 Super Mermaid 這款 VS Code 擴充套件的經驗。它針對 VS Code 內建 Mermaid 的兩個不足，預設樣式不易閱讀、匯出流程斷裂，做了自動上色與一鍵高解析匯出。"
canonical_url: "https://blog.markkulab.net/post/super-mermaid-beautify-export"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2026-06-13 11:26:06 +0800"
category: "AI"
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---

# 用 Claude Fable 開發 Super Mermaid：VS Code Mermaid 圖表的美化與高解析匯出

## 前言

Mermaid 是「圖表即程式碼」（Diagram as Code）常見的工具，GitHub 上累積超過 85,000 顆星，使用者眾多。這一兩年它多了一個新身分：開發者跟 AI 協作時，用來描述系統架構與流程的共同語言。

不過寫過 Mermaid 的人大概都遇過兩個狀況：預設樣式在深色模式下不太好讀，以及想拿到一張能用的 PNG，往往得把程式碼複製到外部網站去轉，解析度也容易糊掉。

2026 年 5 月，VS Code 1.121 已經把 Mermaid 渲染內建到 Markdown 預覽，基礎渲染算是標配了。但美化與匯出這一段還是空白，這也是我開發 [Super Mermaid](https://marketplace.visualstudio.com/items?itemName=mark-ku.super-mermaid) 的起點。

## 為什麼 Mermaid 是最適合人與 AI 協作的圖表工具

先講結論：在所有畫圖的工具裡，Mermaid 大概是唯一一個「人跟 AI 都用原生格式看同一份東西」的。這句話聽起來很小，實際用起來差很多。

### 同一份東西，人看到圖，AI 看到字

Draw.io、Figma、Visio 畫出來的是圖檔。要拿給 AI 看，只能截圖丟進去，它得先認圖，認完也只能用講的告訴你哪裡怪，改不了。

Mermaid 剛好反過來：它本體就是幾行純文字，渲染之後才變成圖。你看到的是圖，AI 讀到的是文字，但兩邊指的是同一份原始碼。中間不需要翻譯，也不會有「你講的那張圖」跟「我看到的那張圖」對不起來的問題。

### 省 token 這件事，比想像中有感

token 可以想成 AI 的閱讀量：它一次能讀進去多少東西有上限，讀了多少也直接反映在帳單上。

同一份系統架構，用純文字一句一句描述「使用者按下結帳之後，前端呼叫訂單 API，訂單 API 再去問庫存服務，庫存不足就發補貨通知……」，大概要 2,000 個 token 上下；同樣的資訊寫成 Mermaid，400 到 500 個 token 就講完了，差不多省下 3 到 6 倍：

**純文字描述（約 2,000 tokens）**

```text
使用者在購物車頁按下結帳之後，前端會先呼叫訂單服務，
訂單服務要先向庫存服務確認這批商品的庫存是否足夠。
如果庫存足夠，就建立一筆訂單，接著呼叫金流 API 進行扣款；
如果庫存不足，就不建立訂單，改為發送補貨通知給採購。
金流扣款完成後，若付款成功，訂單狀態改為成立，
並通知倉庫出貨；若付款失敗，則要把先前預扣的庫存釋放回去。
（以上還只是主要流程，各種例外分支要再往下寫好幾段）
```

**Mermaid 語法（約 450 tokens）**

```text
flowchart LR
  A([使用者下單]) --> B[購物車結帳]
  B --> C{庫存足夠?}
  C -- 是 --> D[建立訂單] --> F[呼叫金流 API]
  C -- 否 --> E[發送補貨通知]
  F --> G{付款成功?}
  G -- 是 --> H[訂單成立] --> J([通知出貨])
  G -- 否 --> I[釋放庫存]
```

省下來的額度不會憑空消失，它會變成 AI 拿去多讀你幾支程式碼的空間。在動輒要餵十幾個檔案的對話裡，這個差距會一路累積。

### AI 改得動，不必重新畫一次

架構調整的時候，如果圖是截圖或 `.drawio` 檔，只能請人重開工具重畫。Mermaid 只要改一行 `A --> B`，圖就跟著變，而這件事 AI 自己就能做完。

這也是為什麼跟 AI 討論架構時用 Mermaid 會比較順：你請它「把快取那層拆出來」，它回你的不是一段解釋，而是一份可以直接貼回檔案的新圖。

### 圖表跟程式碼一起進版控

因為是純文字，Mermaid 圖表可以跟程式碼放進同一個 commit，diff 一看就知道這次架構動了哪裡。文件圖表最常見的死法是跟現實脫節，放進 repo、讓 AI 改 code 時順手改圖，至少能把這一天往後推很久。

## VS Code 內建 Mermaid 之後，還缺的兩件事

### 一、預設樣式與閱讀性

VS Code 內建渲染沿用 Mermaid 預設主題，在深色模式下「淺灰配白底」的線條與文字不太容易辨識。Cursor 論壇上有開發者分享，在比較多人的工程會議裡展示 Mermaid 圖表時，因為對比度偏低而不太好讀。GitHub Discussions、Obsidian 論壇也有不少「深色模式下難以閱讀」的回報。

```mermaid theme=auto
---
title: 訂單處理流程
---
flowchart LR
  subgraph 客戶端
    A([使用者下單]) --> B[購物車結帳]
  end
  C{庫存足夠?}
  subgraph 後端服務
    D[建立訂單]
    E[發送補貨通知]
    F[呼叫金流 API]
  end
  G{付款成功?}
  subgraph 金流
    H[訂單成立]
    I[釋放庫存]
  end
  J([通知出貨])
  B --> C
  C -- 是 --> D
  C -- 否 --> E
  D --> F
  F --> G
  G -- 是 --> H
  G -- 否 --> I
  H --> J
```

Mermaid 官方在 v11.14.0 新增了 `look: handDrawn`（基於 rough.js）與 Neo 風格，但需要手動在每張圖表加上 `%%{init}%%` 設定區塊，門檻不算低，文件裡圖表一多就變成重複工作。

### 二、匯出流程

想要一張 PNG，多數工具的做法是：複製程式碼 → 開瀏覽器 → 貼到 mermaid.live → 下載圖片。這個流程會打斷在 VS Code 裡的節奏，而且匯出的預設解析度只有 1x，放進簡報或技術文件容易偏糊。簡報場景一般建議至少用 4x（約 384 DPI）渲染。

### 市場現況

| 擴充套件 / 工具 | 安裝量 | 限制 |
|---|---|---|
| Mermaid Chart（官方） | 84 萬 | 免費版僅 5 張圖、需雲端帳號、評分約 3/5 |
| beautiful-mermaid | GitHub 10.4K ⭐ | 獨立渲染器，非 VS Code 擴充 |
| Markdown Preview Mermaid Support | 490 萬（已棄用） | VS Code 1.121 內建後標記為棄用 |

現有方案多半是功能受限，或沒辦法直接整合進 VS Code 的工作流程。

## Super Mermaid 的做法：自動上色與一鍵高解析匯出

### 自動套用高對比主題

不需手動設定，Super Mermaid 會自動為圖表套上高對比、依 subgraph 與節點類型上色的 Colorful 主題，深色或淺色模式下都比預設好讀一些。同樣一張「訂單處理流程」圖，套用後結構會比較清楚：

```mermaid theme=colorful
---
title: 訂單處理流程
---
flowchart LR
  subgraph 客戶端
    A([使用者下單]) --> B[購物車結帳]
  end
  C{庫存足夠?}
  subgraph 後端服務
    D[建立訂單]
    E[發送補貨通知]
    F[呼叫金流 API]
  end
  G{付款成功?}
  subgraph 金流
    H[訂單成立]
    I[釋放庫存]
  end
  J([通知出貨])
  B --> C
  C -- 是 --> D
  C -- 否 --> E
  D --> F
  F --> G
  G -- 是 --> H
  G -- 否 --> I
  H --> J
```

自動上色不只適用於流程圖，循序圖、ER 圖、甘特圖、心智圖、圓餅圖等也都會套上配色：

```mermaid theme=colorful
mindmap
  root((新產品規劃))
    商業模式
      訂閱制
      企業授權
    風險
      競品壓力
      開發時程
    目標客群
      中小企業
      自由工作者
    核心功能
      API 整合
      即時協作
      範本庫
```

如果偏好白板手繪的風格，在工具列切換主題就能套用 Sketch 手繪風，適合教學或腦力激盪：

```mermaid theme=sketch
---
title: 訂單處理流程
---
flowchart LR
  subgraph 客戶端
    A([使用者下單]) --> B[購物車結帳]
  end
  C{庫存足夠?}
  subgraph 後端服務
    D[建立訂單]
    E[發送補貨通知]
    F[呼叫金流 API]
  end
  G{付款成功?}
  subgraph 金流
    H[訂單成立]
    I[釋放庫存]
  end
  J([通知出貨])
  B --> C
  C -- 是 --> D
  C -- 否 --> E
  D --> F
  F --> G
  G -- 是 --> H
  G -- 否 --> I
  H --> J
```

### 一鍵高解析匯出，不離開 VS Code

預覽介面直接提供 `Export as PNG` 和 `Export as SVG` 按鈕，可以一鍵產生 4x 高解析度（約 384 DPI）、透明背景的圖片，放進簡報或技術文件比較夠用。過程不需要切換視窗，也不用另外開瀏覽器。

![Super Mermaid 的預覽面板：工具列內建主題切換、匯出、分享連結等按鈕，全程不需離開 VS Code](https://blog.markkulab.net/content/markku/posts/super-mermaid-beautify-export/images/preview-panel.webp)

### 給常用者的幾個功能

- Export All：一份 Markdown 文件裡有十幾張 Mermaid 圖時，可以一次匯出，不用逐張處理
- 簡報模式：直接在 VS Code 裡全螢幕展示圖表，會議時比較方便
- 圖表搜尋：文件一長、圖表一多時，快速定位到要看的那張
- 分享連結：產生可分享的連結，讓沒裝擴充套件的同事也能看圖

![Gallery 縮圖牆：一份文件裡的所有圖表一次總覽，點縮圖就能定位，搭配 Export All 一次匯出](https://blog.markkulab.net/content/markku/posts/super-mermaid-beautify-export/images/gallery.webp)

## 開發過程：和 Claude Fable 5 一起做這個擴充套件

這次開發我用了 [Claude Fable 5](https://www.anthropic.com/claude/fable)，Anthropic 的第五代模型，定位在比較長時間的自主編碼任務，2026 年 6 月已在 GitHub Copilot 上開放使用。以下記錄幾個過程中的環節。

### 從目標到實作

我把核心目標描述給 Fable 5：「做一個 VS Code 擴充套件，攔截並美化 Mermaid 渲染，並提供高解析度圖片匯出」。它很快抓到方向，透過 Markdown-It 的渲染管線注入自訂樣式，再用 Puppeteer 無頭瀏覽器做高解析截圖。

### 樣板程式碼交給 AI

VS Code 擴充套件有不少樣板：`package.json` 的 contributes 設定、Extension Host 的生命週期管理、跟 Markdown-It 渲染引擎的串接。這些 Fable 5 大致都能生成可用的基礎架構，讓我比較能專注在主題引擎與匯出品質的調整。

### 一起處理技術細節

做「4x 高解析匯出」時，關鍵在 Puppeteer 的 `deviceScaleFactor`。我和 Fable 5 討論了幾種渲染策略，最後採用的做法是在無頭瀏覽器裡以 4 倍縮放渲染 SVG，再截取圖表區域：

```typescript
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();

await page.setViewport({
  width: 1280,
  height: 800,
  deviceScaleFactor: 4, // 4x 高解析渲染，約 384 DPI
});

// 注入 Mermaid SVG 並等待渲染完成
await page.setContent(htmlWithMermaidSvg);
const svgElement = await page.$('svg');

// 截取 SVG 元素，自動裁切到圖表邊界
const pngBuffer = await svgElement.screenshot({
  type: 'png',
  omitBackground: true, // 透明背景
});
```

思路不複雜：用 `deviceScaleFactor: 4` 讓瀏覽器以 4 倍像素密度渲染，再用 `omitBackground: true` 拿到透明背景。產出的 PNG 放進簡報，文字和線條會比 1x 清楚一些。

## 延伸：把同一套體驗做成 React 元件 react-super-mermaid

VS Code 擴充套件解決的是「在編輯器裡看圖、匯出圖」，但我自己跑部落格、做後台，也常常需要在網頁上直接渲染 Mermaid。於是我把 Super Mermaid 的核心體驗抽出來，另外做了一個開源的 React 元件庫 [react-super-mermaid](https://blog.markkulab.net/tools/react-super-mermaid)，發佈到 npm。

用法就是一行：

```tsx
import { MermaidViewer } from 'react-super-mermaid'

<MermaidViewer code={mermaidCode} theme="colorful" />
```

它把擴充套件那套功能搬到瀏覽器端：內建 colorful / sketch 主題、平移縮放（svg-pan-zoom）、圖內搜尋，以及 1x / 2x / 4x 的 SVG / PNG 高解析匯出。設計上盡量輕量，`mermaid` 與 `svg-pan-zoom` 都是 optional peer dependencies、不會打包進 bundle，也做了 SSR 安全（Next.js `'use client'`）、完整 TypeScript 型別與 ref 命令式 API，授權是 MIT。

簡單說，VS Code 用 [Super Mermaid](https://marketplace.visualstudio.com/items?itemName=mark-ku.super-mermaid)，網頁就用 [react-super-mermaid](https://blog.markkulab.net/tools/react-super-mermaid)，兩邊看到的圖會是同一種風格。介紹頁與安裝指令都放在 [/tools/react-super-mermaid](https://blog.markkulab.net/tools/react-super-mermaid)。

## 結論

Super Mermaid 主要是補上 VS Code 原生 Mermaid 在美化與匯出這兩段的不足，把比較瑣碎的步驟自動化。對常常用 Mermaid 跟 AI 溝通架構的人來說，一張清楚、好分享的圖，通常比一段長文字更省事，也更容易對齊彼此的理解。

有興趣的話可以到 [VS Code Marketplace 下載 Super Mermaid](https://marketplace.visualstudio.com/items?itemName=mark-ku.super-mermaid)，或到 [GitHub](https://github.com/markku636/vs-code-extension-super-mermaid) 提 Issue、貢獻程式碼。

## 參考資料

- [Mermaid GitHub — 85K+ stars](https://github.com/mermaid-js/mermaid)
- [VS Code 1.121 內建 Mermaid 渲染](https://medium.com/codex/vs-code-renders-mermaid-diagrams-natively-a5bb3db0e406)
- [Mermaid + Claude Code 語境壓縮 — 3-6x token 效率](https://www.mindstudio.ai/blog/mermaid-diagrams-claude-code-skills-context-compression/)
- [Mermaid 圖表可讀性差 — Cursor 論壇](https://forum.cursor.com/t/mermaid-diagrams-are-hard-to-read-poor-contrast/153850)
- [Claude Fable 5（Anthropic 官方）](https://www.anthropic.com/claude/fable)
- [Fable 5 在 GitHub Copilot 全面開放](https://github.blog/changelog/2026-06-09-claude-fable-5-is-generally-available-for-github-copilot/)

---

## 關於本文與作者

本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/super-mermaid-beautify-export)

授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結

### 關於作者

**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — Software Solution Provider

- 10+ 年資深軟體工程師，現為 AI 應用 Builder
- 專注大型平台架構設計，從北美電商到AI SaaS訂閱收費系統
- 結合 AI Agent 與自動化，打造高效可演進的產品技術基礎

### 作者開發的免費工具

以下工具皆可免費使用：

- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸與比對同步、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、Kafka 訊息瀏覽與監控告警；繁中 / 英文雙語介面，內建 AI 助手（自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 <MermaidViewer> 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附叢集管理 REST API，一行 Docker Compose 啟動。免費開源（MIT）。
- [特教專案](https://blog.markkulab.net/education): 為特殊教育學生製作的學習教材

### 每日 Podcast

- [科技新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml

### 電子報

[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。