Mermaid 图表 ButterHost69/dsh-mermaid-diagram

dsh-mermaid-diagram

DeepSeek Harness（dsh）插件，给模型一个 Mermaid 图表工具，并把每张图表渲染成 Web UI 会话里的一张卡片。

模型调用 mermaid 并传入图表源码；这次调用会渲染成一张可交互卡片，带 Diagram / Code 切换、复制操作，渲染失败时回退到源码。图表就是普通的会话事件，所以卡片能从日志里重放。

功能

- 一个面向模型的工具 mermaid，参数有 source 和可选的 title。
- 渲染 Mermaid 支持的所有图表类型：流程图、时序图、类图、状态图、ER 图、甘特图、饼图等等。
- 跟随主题：图表跟随宿主明暗主题，主题变化时重新渲染。
- 流式安全：调用流式输出期间卡片显示进度，参数完整后渲染。
- 重放安全：源码从记录的调用参数里读取，所以卡片在刷新和翻历史后依然存在。
- 失败安全：源码无效时回退到源码视图并给出提示，而不是显示一张坏卡片。
- 卡片文案本地化（英文和简体中文），跟随宿主语言。
- 本地打包 Mermaid，从插件自己的宿主路由提供；渲染时不依赖 CDN，也不依赖网络。
- 约 3.5 MB 的 Mermaid 运行时只在第一张图表出现后才加载，所以启动时零开销。

要求

- dsh 0.2.1-alpha.1（已验证）或兼容版本。
- Node.js ^22.19 || >=24。
- 卡片需要 Web 配置档（dsh web）。工具本身在没有 Web 服务器的配置档里也会注册。

安装

从本仓库安装（git 安装会在安装过程中构建包）：

dsh plugin --profile web add -w github:ButterHost69/dsh-mermaid-diagram

pnpm ≥10 在获得允许前会拒绝运行 git 依赖的 prepare 脚本。如果第一次 add 失败，把 pnpm 打印出的确切包键复制到配置档的 pnpm-workspace.yaml 里的 allowBuilds：

allowBuilds:
dsh-mermaid-diagram: true

然后重新运行 add。把这项允许视为授权在你的机器上运行这个包的构建。

从本地检出安装：

dsh plugin --profile web add -w /absolute/path/to/dsh-mermaid-diagram

安装后重启 dsh web（或刷新页面）。

用法

让模型画一张图，例如：

Draw a flowchart of our release process.

模型会调用 mermaid 工具，结果以卡片形式出现：

- Diagram 显示渲染后的 SVG（默认）。
- Code 显示图表源码。
- Copy source 把源码复制到剪贴板。

源码无法渲染时，卡片以 Code 打开，源码上方显示渲染错误。

工作原理

| 部分 | 职责 |
| src/index.ts（宿主端） | 注册 mermaid 工具，并从 /dsh-mermaid-diagram/mermaid-runtime.js 提供打包好的 Mermaid 运行时。 |
| src/diagram.ts | 参数归一化、大小上限，以及面向模型的摘要。两端共用。 |
| src/client/index.ts | 为 mermaid 线上工具注册一条带键的 tool.call.toolview 条目。 |
| src/client/MermaidCard.tsx | 从调用中读取图表，懒加载运行时，渲染 SVG，并管理卡片状态。 |
| src/client/mermaid-runtime.ts | 每个页面加载一次运行时资源，并缓存到 globalThis.mermaid。 |

工具的调用和结果都是普通会话事件，所以卡片完全从日志推导：记录的 call.argsRaw 提供源码，不需要 result.meta。

限制

- 源码超过 50,000 个字符时，工具会在它到达浏览器之前拒绝，因为 Mermaid 同步解析和布局。
- 卡片以 Mermaid 的 strict 安全级别渲染；标签由 Mermaid 做净化处理。
- 过高的图表在卡片内部滚动，不会撑开对话记录。

开发

npm install
npm run build # tsc declarations + tsdown bundles + the Mermaid runtime asset
npm test # vitest: host logic, card model, and card component
npm run typecheck

构建产物落在 lib/：index.js（宿主端）、client.js（浏览器端，已包装以适配 DSH 客户端模块加载器），以及 mermaid-runtime.js（打包好的 Mermaid UMD 资源，附带其许可声明）。

许可

MIT。见 LICENSE。

打包的 Mermaid 运行时是 Mermaid，MIT 许可；其声明随资源一起放在 lib/mermaid-runtime.js.LEGAL.txt。

先例：MrmoLabs/dsh-mermaid 通过增强对话记录 DOM 来渲染 Mermaid 围栏代码块。本插件改走文档化的工具视图接缝，因此这项能力是显式的模型工具，而不是 Markdown 改写。