Mermaid 渲染 sijidoubi/dsh-plugin-mermaid

dsh-tool-mermaid

仓库名 dsh-plugin-mermaid，npm 包名 dsh-tool-mermaid。

DeepSeek Harness (dsh) 插件：提供一个 mermaid_render 工具，让 agent 把 Mermaid 图源码渲染成 SVG 图片。

完全在进程内完成（mermaid 11 + jsdom），不需要浏览器、不需要联网。

它解决什么问题

dsh 目前没有 Mermaid 渲染工具。模型的回答里只能贴 Mermaid 源码，用户看不到图。
装上这个插件后，agent 写完图会调用 mermaid_render，拿到一张可直接嵌进回答的 data:image/svg+xml 图片（以及原始 SVG 文本）。

工具：mermaid_render

| 参数 | 类型 | 必填 | 说明 |
| code | string | 是 | Mermaid 图源码（flowchart / sequenceDiagram / classDiagram / pie / stateDiagram / erDiagram ...） |
| title | string | 否 | 图的标题，会带进返回结果 |

返回（canonical value）：

{
"format": "svg",
"title": "可选标题", "svg": "...", "width": 127, "height": 77, "url": "http://127.0.0.1:3080/dsh-mermaid/m1.svg", "dataUri": "data:image/svg+xml;base64,..." }

width/height 来自最终 viewBox（像素）。url 是 dsh Web 服务器托管的绝对 http 地址（Web 聊天的 markdown 渲染器只显示 http(s) 图片，模型把这张图嵌进回答后用户就能直接看到）；无 Web 服务器时（headless 运行）url 缺失，用 dataUri 作为兜底。渲染失败时工具以 isError 返回，错误消息包含 Mermaid 解析器给出的行号和期望 token，方便模型自己修图重试。

模型看到的内容（render）：一行摘要 + 可嵌入回答的图片（优先 title，无 url 时退回 data URI）+ 原始 SVG（便于保存到文件）。

安装

插件是标准 dsh bundle（npm 包 + dsh.bundle 声明 + cordis.patch.yml 配置层）。
构建产物在 lib/（TypeScript 源码在 src/），prepare 脚本会从源码构建。

从 GitHub 安装（推荐）

dsh plugin --profile web add github:sijidoubi/dsh-plugin-mermaid
dsh web

pnpm ≥10 默认拒绝执行 git 依赖的 prepare 构建脚本。首次 add 失败时，
把 pnpm 提示的包 key 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 一节（参考本仓库 README 的 dsh-side-panel 示例），再重试 add。
只对源码可信的包授权，并可用 # 锁定版本。

从本地目录安装

git clone git@github.com:sijidoubi/dsh-plugin-mermaid.git
cd dsh-plugin-mermaid
pnpm install # 运行 prepare，构建 lib/
dsh plugin --profile web add .
dsh web

卸载

dsh plugin --profile web remove dsh-tool-mermaid

配置

bundle 默认启用以下配置（可在 profile 的 cordis.patch.yml 覆盖整行）：

- insert:
- id: tool-mermaid
name: dsh-tool-mermaid
config:
theme: default # default | dark | neutral | forest
securityLevel: strict # strict(默认,消毒标签内 HTML) | loose(原样渲染)

开发

pnpm install
pnpm run build # tsc → lib/(类型声明 + JS 产物)
pnpm test # node --test 渲染管线单元测试(无需 dsh 运行时)
node demo/run-demo.mjs # E2E: 用真实 dsh 服务链(SystemPrompt + ToolRuntime)
挂载本插件, 走 ctx.tools.execute() 完整工具管道

工作原理与已知限制

- 渲染管线：mermaid 11 在 Node 里需要 DOM；插件用 jsdom 提供，并补上 jsdom 缺失的 SVG 文本测量（getBBox/getComputedTextLength）和 HTML 标签测量（getBoundingClientRect）。宽度按逐字符宽度模型估算（CJK/全角/ emoji 约 1em，拉丁约 0.5em），高度按行数 × 1.5 行高估算，因此中英文混合与多行标签都能装进方框；极端字体下仍可能与浏览器真实渲染有轻微出入。
- 已实测的图类型：flowchart、sequenceDiagram、classDiagram、pie 渲染正常。强依赖浏览器交互/Canvas 的类型（如部分 mindmap/gantt 交互）可能渲染不完美或报错——遇到时模型应改用已支持的图类型。
- 进程副作用：首次渲染时会在宿主 Node 进程安装一组 jsdom DOM 全局（window/document 等）。对 dsh 宿主是安全的，但与其它也设置 DOM 全局的库同时使用时需注意。
- 串行渲染：渲染共享 mermaid 模块的全局状态，工具默认排他执行（未声明 isConcurrencySafe），同一时刻只跑一次渲染。
- 图片显示：Web 聊天的 markdown 渲染器只显示绝对 http(s) 图片。插件在存在 webServer 服务时注册 /dsh-mermaid/.svg 前缀路由，把每个渲染结果发布为 http URL；SVG 保存在进程内存（上限 100 张，超出淘汰最旧），
dsh 重启后旧 URL 会 404，属预期行为——重启后模型会重新渲染。无 Web
服务器（headless）时退回 dataUri，但此类环境没有聊天界面可显示。

🔍 配套推荐：搭配 dsh-image-zoom 使用，点击渲染出的图片即可原地放大查看细节。

License

MIT