dsh-plugin-mermaid
dsh-plugin-mermaid
Draws ```mermaid code blocks in DSH replies as diagrams — including while the reply is still streaming.
dsh-plugin-mermaid — 把回复里的 ```mermaid 代码块画成图表，边流式输出边画
中文说明（点开） —— 不用等一轮回复结束才看到图
它是什么：模型在回复里写 ```mermaid 围栏，你看到的是图，不是代码。图上方一条细栏写着 Mermaid，右边是 复制 和 源码/图表 开关。
为什么不是"等回复结束再画"：DSH 渲染流式回复时，已完成的块只解析一次、React 元素被缓存，每个 token 只重建尾部那一块。所以规则只有一条：源文本静止 220ms 才画。token 在流 → 计时器一直被重置 → 什么都不画；围栏一闭、后面的正文开始到达 → 块冻结 → 图立刻出现。模型在围栏里停顿时不会画出半张图。
复制：图模式复制一张 PNG（2–3 倍尺寸、铺了代码块自己的底色，粘到文档里就是一张图）；源码模式复制 Mermaid 文本。浏览器剪贴板不收 SVG，所以图是先栅格化再写的 —— 这也是 Mermaid 跑在 htmlLabels: false 的原因：<foreignObject> 里的 HTML 在"SVG 当图片"时会消失。
认不出来就不画：Mermaid 解析失败的块原样保留，不插任何东西。
装法：Plugin Manager 的 Add plugin 填 github:kjx-talesofai/dsh-plugin-mermaid#v0.2.1，或指向本地目录。装完重启 app（Host 半边开机才加载资产路由），页面再 ⌘R。
它没有做什么：不改 Markdown 渲染器、不占槽位、不加工具。只在代码块的 data-code-block-content 里加一个节点，用一条 :has() 规则把源码 <pre> 藏起来。
What it does
The model writes a fenced block:
```mermaid
flowchart LR
A["工作区"] --> B["暂存区"] --> C["仓库"]
```
You see the diagram, under a small bar that names it and offers 源码
(source) and copy. The block's own "Code block" banner is hidden while the
diagram is shown, because the plugin never touches the <pre> React owns — it
adds a sibling and hides the original with CSS.
Copy follows the view. With the diagram on screen the button puts a PNG on
the clipboard (2–3× the drawn size, on the block's own surface colour, so it
pastes into a document without a transparent-background surprise); with the
source on screen it copies the Mermaid text. Browser clipboards will not take an
SVG reliably, so the diagram is drawn through a canvas first — which is also why
Mermaid runs with htmlLabels: false: foreignObject HTML does not survive that
trip.
Why this is not a Markdown plugin
There is no slot between "Markdown" and "code block". The only seat a plugin can
take is the whole assistant-step node, and taking it would mean re-implementing
Markdown — file links, image lightboxes, KaTeX, syntax highlighting, copy
buttons, sticky banners — to add one block type.
So the plugin decorates the primitive's own markup instead:
div.md-code-block
div.bannerWrap ← hidden while a diagram is shown
div[data-code-block-banner] ← language label + copy
div[data-code-block-content]
pre ← the source (left in place, hidden by CSS)
div.dsh-mermaid ← the one node the plugin adds
The coupling is that markup. tests/dom.test.mjs drives a stand-in with the same
shape in a real browser, so a change to it fails loudly here instead of silently
drawing nothing.
Why streaming needs care
DSH renders a live reply with an incremental Markdown renderer: every completed
block is parsed once and its React elements are cached, so only the growing tail
is re-rendered on each token. That gives one precise rule:
never draw the tail; draw only a source that has stopped changing.
A block is drawn after its source has been unchanged for 220 ms. While tokens
flow the timer keeps resetting; when the fence closes and the next prose starts,
the block freezes, and the diagram appears mid-reply — no waiting for the turn to
end. A pause inside an open fence that lasts longer than 220 ms will draw
whatever has arrived; if the source then keeps growing, the panel is dropped and
redrawn, and a source Mermaid rejects leaves the code block exactly as it was.
Rendered diagrams are cached by source + theme, so a re-render (React rebuilding
the message, a theme switch) costs no Mermaid work.
Where Mermaid comes from
The browser half asks the Host for /api/mermaid.asset.js; the Host serves the
mermaid.min.js from this package's own dependency tree over the same
authenticated, same-origin channel as the rest of the Web UI. The build is found
by Node's own resolution (createRequire), not by a fixed
./node_modules/… path: pnpm — which the Plugin Manager uses — keeps a
package's dependencies beside it, so a fixed path would 404 on every install
from Git while working perfectly in a linked checkout. It is a 3.4 MB
script, so it is fetched the first time a diagram is seen, not on every page
load, and revalidated with an ETag.
Limits
- Diagrams are rendered in the browser only. A DSH client without the plugin (a
phone on an old tab,
--no-client tooling) shows the code block.
- Mermaid's
strict security level is used: HTML labels are sanitized, and
click-to-activate links are not available.
- A diagram Mermaid rejects is not decorated at all. The reason is logged to the
browser console (
[mermaid] …); there is no inline error row, because during
streaming an incomplete diagram would flash one.
- No per-block history: the panel is a view of the file's Markdown, not a record.
Install
Use DSH's own Add plugin dialog. No npm account, no publishing.
| Field | Value |
|---|
| GitHub | github:kjx-talesofai/dsh-plugin-mermaid#v0.2.1 |
| Local directory | an absolute path, e.g. /path/to/dsh-plugin-mermaid |
Restart the desktop app afterwards: the Host half owns the asset route and is
only loaded at startup. The browser half reloads with the page (⌘R).
This plugin is not published to npm, and npm install is not the install
path. Its one runtime dependency (the Mermaid build the Host serves) is installed
from the repository's package.json.
Tests
npm ci
npm test # 18: classifier, loader contract, patch/manifest consistency, the Host route, module resolution
npm run test:dom # 33 in headless Chrome over CDP: `:has()`, real Mermaid output, the streaming sequence, both clipboard flavours
test:dom skips when no Chrome or Chromium is installed.
Licence
MIT.
