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": "<svg ...>...</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>)，无 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。 只对源码可信的包授权，并可用 #<commit> 锁定版本。

从本地目录安装

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/<id>.svg 前缀路由，把每个渲染 结果发布为 http URL；SVG 保存在进程内存（上限 100 张，超出淘汰最旧）， dsh 重启后旧 URL 会 404，属预期行为——重启后模型会重新渲染。无 Web 服务器（headless）时退回 dataUri，但此类环境没有聊天界面可显示。

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

License

MIT