前言¶
用 DSH（DeepSeek Harness）做智能体开发时，模型回复里经常出现 mermaid 代码块，用来描述流程、架构或状态流转。DSH web 客户端默认把它当普通代码块处理：有 Shiki 语法高亮，有 Copy 按钮，但图看不到。想核对图画得对不对，只能把源码复制到外部工具里渲染，来回切换很打断排查节奏。
dsh-plugin-mermaid 针对的就是这个问题：它在聊天消息内把 mermaid 代码块渲染成图表，源码视图仍然保留，随时可以切回去。下面介绍它的功能、原理、安装与使用。
这是什么¶
dsh-plugin-mermaid 是一个 DeepSeek Harness（DSH）web 客户端插件，由 lj970926 维护，采用 MIT 许可证。它做三件事：
- 在聊天消息中将 mermaid 代码块渲染为图表；
- 提供「源码 / 图表」切换，在 Mermaid 源码与渲染后的 SVG 之间来回切换；
- 跟随 DSH 的深色/浅色主题自动切换 Mermaid 主题，主题变更后所有块实时重新渲染。
几个设计上的取舍：Mermaid v11 按需从 CDN 加载，避免打包膨胀；插件零构建步骤，浏览器入口为手写的工厂形式 CJS，符合 DSH client-modules 服务的要求；代码块横幅原生集成在 DSH 界面里，按钮紧邻内置 Copy 按钮，源码视图保留 Shiki 高亮与复制。
核心功能¶
- 在聊天消息中将 mermaid 代码块渲染为图表；
- 「源码 / 图表」切换，随时在 Mermaid 源码与渲染后的 SVG 之间切换；
- 跟随 DSH 深色/浅色主题自动切换 Mermaid 主题；
- Mermaid v11 按需从 CDN 加载，不增加打包体积；
- 原生集成 DSH 代码块横幅：按钮紧邻内置 Copy 按钮，源码视图保留 Shiki 高亮与复制；
- 提供「重渲染」按钮，流式输出或 CDN 异常后可强制重新渲染。
实现方式¶
插件的浏览器端入口是 lib/client.js。加载后它做三件事：
- 通过
window.__ModuleLoader__.load({id, factory})注册自身，并注入样式； - 识别 mermaid 块：读取 DSH 横幅的
.infostring文本，并以code[class*='language-mermaid']作为前向兼容回退； - 安装 MutationObserver 处理流式输出中的代码块，配合 500 ms 防抖，避免流式 token 频繁触发渲染。
安装与启用¶
推荐直接从 GitHub 安装。这个包随仓库发布预构建的 lib/ 文件并声明了 dsh.bundle，可以直接装入 DSH web profile：
dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid
安装后需要重启 dsh web，并在浏览器强制刷新（Cmd+Shift+R）。
如果需要固定版本以保证可复现，追加 commit SHA 或 tag：
dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid#<commit-or-tag>
开发调试时，也可以从本地 checkout 以链接 bundle 的方式安装：
dsh plugin --profile web add /absolute/path/to/dsh-plugin-mermaid
仓库还保留了遗留脚本 install.sh，直接把文件复制进已有的 web profile：
git clone https://github.com/lj970926/dsh-plugin-mermaid.git
bash dsh-plugin-mermaid/install.sh
脚本做两件事：把文件夹复制到 $DSH_HOME/profiles/web/node_modules/dsh-plugin-mermaid/（默认 ~/.dsh/profiles/web/...），再向 $DSH_HOME/profiles/web/cordis.patch.yml 追加一条 insert 条目（幂等）。之后同样重启 dsh web 并强制刷新浏览器。
两点补充说明：
- 已发布文件就在
lib/中，包没有prepare构建步骤，不需要 pnpmallowBuilds授权；如果你 fork 后加入了构建步骤，需按 DSH 打包文档，在 profile 的pnpm-workspace.yaml中把包名加入allowBuilds。 - 推荐用
dsh plugin add而不是手动改补丁文件：它会把 bundle 记录到 profile manifest，profile 更新后仍保持启用。另外，较新的 DSH 版本要求 profile 的cordis.patch.yml能解析为顶层 YAML 数组，文件没有条目时保持为[]。
典型用法¶
经过上面的安装与重启步骤，发送任意包含 fenced mermaid 块的消息即可，例如：
```mermaid
flowchart LR
A[Input] --> B[Process] --> C[Output]
```
DSH 会先把它渲染成代码块，插件随后增强这个块：
- 点击「源码 / 图表」按钮，在 Mermaid 源码与渲染后的 SVG 之间切换；
- 流式输出结束或 CDN 异常后，如果图没有出来，点「重渲染」强制重新渲染；
- 在 Settings → Appearance 切换主题后，所有块会按匹配的 Mermaid 主题重新渲染。
开发与定制¶
浏览器端文件是纯 JavaScript，没有构建步骤。修改 lib/client.js 后，需要重新同步进 profile 并重启 dsh web：
bash install.sh
默认 web profile 中 DSH 的 client-hmr 插件是禁用的，文件改动不会自动热重载。如果你从源码运行 DSH（pnpm run dev:web）并重新启用 client-hmr，则对 lib/client.js 的修改可以热重载，无需重启。
另一个可定制点是 Mermaid 的加载来源。首次渲染需要访问 cdn.jsdelivr.net，之后浏览器会缓存 Mermaid；如需本地化，把 lib/client.js 中的 MERMAID_CDN 改为本地 URL 即可。
卸载¶
- 从
~/.dsh/profiles/web/cordis.patch.yml移除对应的块； - 删除目录：
rm -rf ~/.dsh/profiles/web/node_modules/dsh-plugin-mermaid； - 重启
dsh web。
适用场景与注意¶
插件适合所有在 DSH web 客户端里查看含 mermaid 图回复的用户：架构梳理、流程说明、智能体工作流调试，图直接在对话里看，不用再切换外部工具。
使用前注意：
- 要求 DSH
>= 0.1.0-rc.6（在 rc.6 上测试通过）； - 首次渲染需要网络访问
cdn.jsdelivr.net，离线环境先按上文方式本地化； - 和所有 DSH 插件一样，插件以当前 dsh 进程的权限运行，安装前建议先阅读源码与许可证（MIT），确认无误再装入 profile。
相关链接¶
dsh-plugin-mermaid 补齐了 DSH 聊天界面里「图能直接看」这一环：零构建、按需加载、跟随主题，装上即可用。目录页与源码仓库如下：
- 目录页：https://www.skillhub.cn/plugins/lj970926/dsh-plugin-mermaid
- GitHub：https://github.com/lj970926/dsh-plugin-mermaid
（社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系。）
