---
title: "mermaid-draw"
url: "https://claudemods.dev/zh-tw/builds/mermaid-draw-5f700a"
source: "https://github.com/galElmalah/claude-mods/tree/main/claude-mermaid"
source_type: "github"
repo: "https://github.com/galElmalah/claude-mods/tree/main/claude-mermaid"
author: "galElmalah"
author_handle: "galElmalah"
stars: 4
category: "主題與外觀"
categories: ["themes"]
tags: ["diagrams", "hooks", "mermaid", "plugin", "rendering", "terminal"]
permission_level: 2
scan_complete: true
install: "claude plugin marketplace add galElmalah/claude-mods\nclaude plugin install mermaid-draw@gal-mods"
added: "2026-10-12T04:04:56.414Z"
updated: "2026-10-10T12:54:13Z"
locale: "zh-tw"
content_locale: "zh-tw"
---

# mermaid-draw

Claude Code 中的 Mermaid 圖表：Claude 撰寫的每個 ```mermaid 區塊都會在轉錄中圍欄所在的位置以彩色方框藝術形式繪製。需要函式掛鉤（早期存取）和互動式終端。

## Description

# mermaid-draw

Claude Code 中的 Mermaid 圖表。Claude 撰寫的每個 ```` ```mermaid ```` 區塊
都會在轉錄中圍欄所在的位置以彩色方框藝術形式繪製。
不花費任何 token：外掛在本機繪製，螢幕上不出現其他內容——沒有窗格，沒有按鈕。

```
❯ how does a prompt become a reply?

⏺ A prompt flows through understanding and a decision point before a reply.

  ┌────────┐     ┌────────────┐     ◇────────────◇     ┌───────┐
  │        │     │            │     │            │     │       │
  │ Prompt ├────►│ Understand ├────►│ Use Tools? ├─Yes►│ Reply │
  │        │     │            │     │            │     │       │
  └────────┘     └────────────┘     ◇────────────◇     └───────┘
```

流程圖、狀態圖、序列圖、類別圖和 ER 圖以及 xy 圖表都會被繪製；
其他類型（甘特圖、圓餅圖、心智圖……）保留其圍欄。當適合且不損失任何內容時，
自上而下的流程圖或狀態圖會從左到右佈局
（終端中的列很寶貴：5 列而不是 30 列），並且狀態圖的
`[*]` 開始和結束（渲染器將其繪製為空方框）會被省略。

一個 mod：一個基於 Claude Code **函式掛鉤** 建構的外掛，TypeScript 在
Claude Code 自己的行程中執行。早期存取，因此需要下面的環境變數，
並且 API 可能會在版本之間變化。

## 需求

- Claude Code 2.1.270 或更高版本，並帶有 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`。
- 一個互動式終端工作階段，字型具有製表符繪製字元
  （如果沒有，使用 `/mermaid ascii on`）。在 `claude -p` 中不會繪製任何內容。

## 快速開始

1. 在 `~/.claude/settings.json` 中開啟函式掛鉤：

   ```json
   { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }
   ```

   或者對於單一工作階段：`CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude`。

2. 從複製載入外掛（儲存庫自己的 `.claude/settings.json`
   為在其中啟動的工作階段設定變數）：

   ```sh
   git clone https://github.com/galElmalah/claude-mods
   cd claude-mods
   claude --plugin-dir claude-mermaid
   ```

   或者從儲存庫的市場 `gal-mods` 安裝：

   ```sh
   claude plugin marketplace add galElmalah/claude-mods
   claude plugin install mermaid-draw@gal-mods
   ```

3. 向 Claude 請求一個圖表。它會在回覆中繪製。

從 `claude-mermaid@claude-mods` 升級？請遵循
[遷移說明](../README.md#migrating-from-the-old-names)。

## 使用

| 指令 | 作用 |
| --- | --- |
| `/mermaid` | 顯示目前設定 |
| `/mermaid ascii on\|off` | 使用純 `+--|` 藝術而不是製表符繪製字符（預設關閉） |
| `/mermaid color on\|off` | 邊框青色，箭頭黃色，線條暗淡（預設開啟） |
| `/mermaid lr on\|off` | 在不損失任何內容時，將自上而下的流程圖和狀態圖從左到右佈局（預設開啟） |
| `/mermaid reset` | 恢復預設值 |

設定會重繪螢幕上已有的圖表。設定會跨工作階段儲存在
外掛的儲存區中。

## 運作方式

- `hooks/register.ts` 是掛鉤模組。它掛鉤 `AssistantMessage` 的 `ui.render`：在終端機上開啟顏色時，它會回傳自己的樹狀結構（散文用 `Markdown`，每條圖表線用一個 `Text`，顏色作為其 span 上的 props），因為從 Claude Code 2.1.287 起，重寫後的 `props.text` 可能不帶任何跳脫序列；否則，它會將每個已關閉的 mermaid 圍欄替換為純文字藝術的文字圍欄。它也會為 `/mermaid` 掛鉤 `command.run`。
- `hooks/diagrams.ts` 是純粹的部分：尋找圍欄、渲染、選擇橫向版面配置（僅當由上而下渲染的每個字都保留時才保留，因為渲染器可能會覆寫反向延伸的邊的標籤）、符合寬度、序列化。`bun test` 涵蓋它。
- `hooks/vendor/mermaid-ascii.js` 是 [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) 的 ASCII 渲染器，由 `scripts/build-vendor.mjs` 打包（掛鉤模組在沒有 Node 的情況下執行，無法匯入套件）。此渲染器只輸出 ANSI，因此它在 truecolor 下針對哨兵顏色主題執行，跳脫序列會被解碼回角色（邊框、線、箭頭、文字），然後為終端機自己的 16 色調色盤上色，讓淺色和深色主題都能閱讀。
- 此套件修補了一件事：上游的 A* 邊路由器會搜尋無界網格，因此一個將邊的目標圍住的圖形執行了約 25 秒，並因 `Map maximum size exceeded` 而終止，這會耗盡掛鉤的全部預算。供應商副本限制了搜尋，並退回為直線段，因此同一個圖形在約 60 毫秒內繪製完成。渲染的藝術會依來源和字符集快取；掛鉤在首次繪製後幾毫秒內穩定。

## 開發

```sh
npm install                 # esbuild, beautiful-mermaid, aimock, bun types
npm run build:vendor        # rebuilds hooks/vendor/mermaid-ascii.js
npm test                    # unit tests of hooks/diagrams.ts
npm run test:plugin         # render-hook tests in Claude Code's plugin test kit
npm run test:e2e            # the plugin inside a real Claude Code (below)
npm run typecheck           # against ../.claude/types (run /plugin-types first)
npm run validate            # what the engine sees the module hook and call
```

型別檢查需要你的 Claude Code 建置的宣告：在儲存庫根目錄開啟一個工作階段，開啟函式掛鉤並執行 `/plugin-types`，它會寫入被 git 忽略的 `.claude/types/`。

外掛測試套件和 Bun 使用不同的執行環境。`test:plugin` 會將掛鉤和套件測試複製到暫存的外掛資料夾中，這樣 Claude 的執行器就不會嘗試載入 Bun 測試。`npm run test:all` 會用各自的執行器執行這兩個測試套件和端對端測試。

### 端對端測試

`tests/e2e` 在 tmux 窗格中驅動一個真實的互動式 Claude Code，其
回覆由 [aimock](https://github.com/CopilotKit/aimock) 腳本化（一個
在本機埠上的 Anthropic-API mock，`ANTHROPIC_BASE_URL` 指向它），
外掛從檢出目錄透過 `--plugin-dir` 載入。每個測試傳送一個
提示，等待螢幕顯示某個東西，並對擷取的文字進行斷言，
在顏色重要時使用 `-e`。它涵蓋每種已繪製的類型、顏色、
一則回覆中的兩個圖表、一個未繪製的類型、過去會
掛起的密集圖、清單項目內的圍欄、側向版面、每種 `/mermaid` 形式，以及一個
對圖形來說太窄的終端機。需要 PATH 上有 `tmux` 和 `claude`，並且檢出目錄
是 Claude Code 信任的資料夾；否則跳過。約 10 秒。

對 `hooks/` 的編輯會熱重載到正在執行的 `--plugin-dir` 工作階段中。使用
`--debug-file /tmp/mermaid.log` 啟動 Claude，以查看引擎拒絕了什麼。

## 限制

- beautiful-mermaid 不繪製的類型（gantt、pie、mindmap、gitGraph、
  journey、timeline、quadrant、C4、……）保留其圍欄。
- 比紀錄更寬的圖形在右側用 `…` 截斷，並有一行
  說明超出了多少；把終端機調寬即可。
- 顏色僅在終端機上繪製；桌面、VS Code 和行動裝置顯示
  一般圖形。如果一則回覆中圖表之間的散文超過 10000 個字元
  （一個 `Markdown` 元素的上限），也會以一般形式繪製。

## 授權

MIT。

## Install

```
claude plugin marketplace add galElmalah/claude-mods
claude plugin install mermaid-draw@gal-mods
```

## Original README

# mermaid-draw

Mermaid diagrams in Claude Code. Every ```` ```mermaid ```` block Claude writes
is drawn as box art, in colour, right where the fence was in the transcript.
Nothing costs a token: the plugin draws locally, and nothing else appears on
screen — no pane, no buttons.

```
❯ how does a prompt become a reply?

⏺ A prompt flows through understanding and a decision point before a reply.

  ┌────────┐     ┌────────────┐     ◇────────────◇     ┌───────┐
  │        │     │            │     │            │     │       │
  │ Prompt ├────►│ Understand ├────►│ Use Tools? ├─Yes►│ Reply │
  │        │     │            │     │            │     │       │
  └────────┘     └────────────┘     ◇────────────◇     └───────┘
```

Flowcharts, state, sequence, class and ER diagrams and xy charts are drawn;
other kinds (gantt, pie, mindmap, …) keep their fence. A top-down flowchart
or state diagram is laid out left to right when that fits and loses nothing
(rows are dear in a terminal: 5 rows instead of 30), and a state diagram's
`[*]` start and end, which the renderer draws as empty boxes, are left out.

A mod: a plugin built on Claude Code **function hooks**, TypeScript that runs
inside Claude Code's own process. Early access, so it needs the environment
variable below and the API can change between releases.

## Requirements

- Claude Code 2.1.270 or later with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`.
- An interactive terminal session with a font that has box-drawing
  characters (`/mermaid ascii on` for one that does not). Nothing draws in
  `claude -p`.

## Quick start

1. Turn function hooks on, in `~/.claude/settings.json`:

   ```json
   { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }
   ```

   Or for one session: `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude`.

2. Load the plugin from a clone (the repo's own `.claude/settings.json`
   sets the variable for sessions started inside it):

   ```sh
   git clone https://github.com/galElmalah/claude-mods
   cd claude-mods
   claude --plugin-dir claude-mermaid
   ```

   Or install it from the repo's marketplace, `gal-mods`:

   ```sh
   claude plugin marketplace add galElmalah/claude-mods
   claude plugin install mermaid-draw@gal-mods
   ```

3. Ask Claude for a diagram. It is drawn in the reply.

Upgrading from `claude-mermaid@claude-mods`? Follow the
[migration instructions](../README.md#migrating-from-the-old-names).

## Use

| command | what it does |
| --- | --- |
| `/mermaid` | shows the current settings |
| `/mermaid ascii on\|off` | plain `+--|` art instead of box-drawing glyphs (default off) |
| `/mermaid color on\|off` | borders cyan, arrows yellow, lines dim (default on) |
| `/mermaid lr on\|off` | lay top-down flowcharts and state diagrams out left to right when nothing is lost (default on) |
| `/mermaid reset` | the defaults again |

A setting redraws the diagrams already on screen. Settings are kept in the
plugin's store across sessions.

## How it works

- `hooks/register.ts` is the hooks module. It hooks `ui.render` of
  `AssistantMessage`: with colour on, on the terminal, it returns a tree of its
  own (`Markdown` for the prose, one `Text` per diagram line, the colours as
  props on its spans), since a rewritten `props.text` may carry no escape
  sequence from Claude Code 2.1.287 on; otherwise it swaps each closed mermaid
  fence for a text fence of plain art. It also hooks `command.run` for
  `/mermaid`.
- `hooks/diagrams.ts` is the pure part: finding fences, rendering, choosing
  the sideways layout (kept only when every word of the top-down render
  survives, since the renderer can overwrite the label of an edge that runs
  back the other way), fitting to a width, serializing. `bun test` covers it.
- `hooks/vendor/mermaid-ascii.js` is [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid)'s
  ASCII renderer bundled by `scripts/build-vendor.mjs` (hooks modules run
  with no Node and cannot import packages). The renderer only emits ANSI, so
  it is run in truecolor against a theme of sentinel colours and the escapes
  are decoded back into roles (border, line, arrow, text), then coloured for
  the terminal's own 16-colour palette so light and dark themes both read.
- The bundle patches one thing: upstream's A* edge router searches an
  unbounded grid, so a graph that fences an edge's target in ran for ~25 s
  and died on `Map maximum size exceeded`, which would burn the hook's whole
  budget. The vendored copy caps the search and falls back to a straight
  segment, so the same graph draws in ~60 ms. Rendered art is cached per
  source and glyph set; a hook settles in a few ms after the first draw.

## Develop

```sh
npm install                 # esbuild, beautiful-mermaid, aimock, bun types
npm run build:vendor        # rebuilds hooks/vendor/mermaid-ascii.js
npm test                    # unit tests of hooks/diagrams.ts
npm run test:plugin         # render-hook tests in Claude Code's plugin test kit
npm run test:e2e            # the plugin inside a real Claude Code (below)
npm run typecheck           # against ../.claude/types (run /plugin-types first)
npm run validate            # what the engine sees the module hook and call
```

Typechecking needs the declarations of your Claude Code build: open a
session in the repository root with function hooks on and run `/plugin-types`,
which writes the git-ignored `.claude/types/`.

The plugin test kit and Bun use different runtimes. `test:plugin` copies the
hooks and kit tests into a temporary plugin folder so Claude's runner does
not try to load the Bun tests. `npm run test:all` runs both suites and the
end-to-end tests with their respective runners.

### End-to-end tests

`tests/e2e` drives a real interactive Claude Code in a tmux pane, its
replies scripted by [aimock](https://github.com/CopilotKit/aimock) (an
Anthropic-API mock on a local port, `ANTHROPIC_BASE_URL` pointed at it), the
plugin loaded from the checkout with `--plugin-dir`. Each test sends a
prompt, waits for the screen to show a thing, and asserts on the captured
text, with `-e` where colour matters. It covers every drawn kind, colours,
two diagrams in one reply, an undrawn kind, the dense graph that used to
hang, a fence inside a list item, the sideways layout, every `/mermaid` form, and a terminal too
narrow for the art. Needs `tmux` and `claude` on PATH, and the checkout to
be a folder Claude Code trusts; skipped otherwise. About 10 s.

Edits to `hooks/` hot-reload into a running `--plugin-dir` session. Start
Claude with `--debug-file /tmp/mermaid.log` to see what the engine refused.

## Limits

- Kinds beautiful-mermaid does not draw (gantt, pie, mindmap, gitGraph,
  journey, timeline, quadrant, C4, …) keep their fence.
- Art wider than the transcript is cut at the right with `…` and a line
  saying by how much; make the terminal wider.
- Colours are drawn on the terminal alone; desktop, VS Code and mobile show
  plain art. A reply whose prose between diagrams runs past 10000 characters
  (one `Markdown` element's cap) is drawn plain too.

## License

MIT.