Mermaid 图表 kjx-talesofai/dsh-plugin-mermaid

dsh-plugin-mermaid

把 DSH 回复里的

= 0.2.0-rc.1">

dsh-plugin-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() 规则把源码 藏起来。

它做什么

模型写一个围栏块： text
flowchart LR
A["工作区"] --> B["暂存区"] --> C["仓库"]

你看到的是图，图上方一条小栏标出名字，并提供 源码 和复制。显示图表时，代码块自带的「Code block」横幅会隐藏，因为插件从不碰 React 掌管的 —— 它加一个兄弟节点，再用 CSS 把原来的藏起来。

复制跟着当前视图走。 屏幕上显示图表时，按钮往剪贴板放一张 PNG（2–3 倍绘制尺寸，铺代码块自己的底色，粘进文档不会出现透明背景的意外）；屏幕上显示源码时，复制 Mermaid 文本。浏览器剪贴板收 SVG 不可靠，所以图表先经 canvas 画一遍 —— 这也是 Mermaid 跑在 htmlLabels: false 的原因：foreignObject 里的 HTML 过不了这一趟。

为什么它不是 Markdown 插件

「Markdown」和「代码块」之间没有槽位。插件能占的唯一位置是整个 assistant-step 节点，占了就意味着重新实现 Markdown —— 文件链接、图片灯箱、KaTeX、语法高亮、复制按钮、吸顶横幅 —— 只为了加一种块类型。

所以插件改为装饰基础组件自己的标记：

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

耦合点就是这套标记。tests/dom.test.mjs 在真实浏览器里驱动一个同形状的替身，所以一旦标记变了，测试会在这里大声失败，而不是悄悄什么都不画。

流式输出为什么需要小心处理

DSH 用增量 Markdown 渲染器渲染实时回复：每个已完成的块只解析一次，React 元素缓存下来，因此每个 token 到来时只重新渲染不断增长的那段尾部。由此得到一条精确的规则：

绝不绘制尾部；只绘制已经停止变化的源码。

一个块的源码连续 220 ms 不变后才绘制。token 流动期间计时器不断重置；围栏闭合、下一段正文开始时，块冻结，图表在回复中途就出现 —— 不必等整轮结束。围栏内部的停顿如果超过 220 ms，会绘制已经到达的内容；如果源码随后继续增长，面板被丢弃并重绘；Mermaid 拒绝的源码则让代码块保持原样。

渲染出的图表按源码 + 主题缓存，所以重新渲染（React 重建消息、切换主题）不产生任何 Mermaid 开销。

Mermaid 从哪来

浏览器端向 Host 请求 /api/mermaid.asset.js；Host 从本包自己的依赖树里取出 mermaid.min.js，走与 Web UI 其余部分相同的已认证同源通道提供。构建产物由 Node 自身的解析机制（createRequire）定位，而不是写死的 ./node_modules/… 路径：插件管理器使用的 pnpm 会把包的依赖放在它旁边，所以写死路径会让每次从 Git 安装都 404，而在链接式检出里却完全正常。这是个 3.4 MB 的脚本，所以只在第一次看到图表时获取，而不是每次页面加载都取，并用 ETag 重新校验。

限制

- 图表只在浏览器里渲染。没有插件的 DSH 客户端（旧标签页上的手机、--no-client 工具链）显示代码块。
- 使用 Mermaid 的 strict 安全级别：HTML 标签会被净化，点击激活的链接不可用。
- Mermaid 拒绝的图表完全不做装饰。原因会记录到浏览器控制台（[mermaid] …）；没有行内错误行，因为流式输出期间不完整的图表会让它闪一下。
- 没有逐块历史：面板是文件 Markdown 的视图，不是记录。

安装

使用 DSH 自带的 Add plugin 对话框。不需要 npm 账号，不需要发布。

| 字段 | 值 |
| GitHub | github:kjx-talesofai/dsh-plugin-mermaid#v0.2.1 |
| 本地目录 | 绝对路径，例如 /path/to/dsh-plugin-mermaid |

装完要重启桌面应用：Host 那一半负责资源路由，只在启动时加载。浏览器那一半随页面刷新重新加载（⌘R）。

这个插件没有发布到 npm，npm install 不是安装方式。它唯一的运行时依赖（Host 提供的 Mermaid 构建产物）从仓库的 package.json 安装。

测试

bash
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

没装 Chrome 或 Chromium 时，test:dom 会跳过。

许可

MIT。