前言¶

在 DSH Web 里和模型对话时，助手经常在回复里输出 ```mermaid 代码围栏——流程图、时序图、类图等。默认情况下，这些围栏只是纯文本代码块，需要你自己复制到外部工具才能看图。

如果你希望会话消息里直接看到图表，又不想把 Mermaid 运行时塞进前端启动包、拖慢首屏加载，就需要一个按需加载、只在出现围栏时才工作的渲染插件。下面介绍社区插件 dsh-mermaid（维护者 AKS1st），它把 DSH Web 会话中的 Mermaid 围栏就地渲染为 SVG，并针对长对话做了视口驱动和异步队列优化。

这是什么¶

dsh-mermaid 是一个 DSH 客户端插件（当前版本 0.5.0，MIT 许可证）。安装到 web profile 后，它会监听会话 DOM，把 infostring 为 mermaid 的代码围栏渲染为 SVG 图表，同时保留语言横幅和复制按钮（复制仍复制源码）。

插件在 SkillHub 社区目录 上架，分类为客户端；源码托管于 GitHub: AKS1st/dsh-mermaid。

工作方式¶

插件分为 Host 半部和 Client 半部，各自职责明确。

Host 半部（src/index.ts）注册 webServer 前缀路由 /mermaid-dist，从插件自己的 node_modules/mermaid 惰性提供 UMD 构建，并提供固定的 config.json 端点。

Client 半部（src/client/）在浏览器侧完成实际渲染，主要行为如下：

1. 只处理已定格的围栏——流式输出期间不渲染，等助手回复完成后再动手；
2. 首次遇到 Mermaid 围栏才惰性加载 mermaid 库（浏览器缓存一次）；
3. 视口驱动渲染：围栏进入视口（带 300px 预加载余量）才开始渲染；离开视口的图停止渲染，回到视口再继续；
4. 异步队列渲染：多图时逐个渲染并在渲染之间让出主线程，首次渲染期间显示加载动画，完成后替换为 SVG；
5. securityLevel 恒为 strict，标签经 mermaid 内置 DOMPurify 消毒，且从不绑定点击处理；
6. theme: auto 时图表颜色跟随 GUI 亮/暗主题，属性翻转时自动重渲染视口内的既有图表；
7. 代码块横幅上的放大按钮可打开全屏浮层，支持滚轮缩放、左键/中键拖动平移，背景点击或 Esc 关闭；
8. 渲染失败时保留源码块，在图框下方显示错误摘要，支持一键复制报错或发送给 AI 修复。

client 包体积约 10 KB（gzip ~4 KB）；mermaid（~700 KB）只在真正出现 mermaid 围栏时才按需加载，不进入 boot 图。

安装与启用¶

从 GitHub 仓库安装，构建在 prepare 脚本里自动执行：

dsh plugin --profile web add github:AKS1st/dsh-mermaid
dsh web   # 重启 web 服务使 profile 生效

若 pnpm 提示 git 依赖需要执行构建脚本（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），按提示把包加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试即可。

本地开发时，先构建再安装：

npm install
npm run build
dsh plugin --profile web add .
dsh web

卸载：

dsh plugin --profile web remove dsh-mermaid

配置¶

组合包默认通过 cordis.patch.yml 注入以下配置：

- insert:
    - id: mermaid
      name: 'dsh-mermaid'
      config:
        theme: auto
        maxTextSize: 50000
        maxEdges: 2000
        securityLevel: strict

在 profile 的 cordis.patch.yml 里以 - set: 或 - update: 覆盖即可。

典型用法¶

安装并重启 web 服务后，无需额外操作。当助手在会话消息里输出 Mermaid 围栏时，插件会自动接管渲染。例如助手回复中包含：

```mermaid
flowchart LR
  A[用户提问] --> B[DSH Web]
  B --> C[dsh-mermaid]
  C --> D[SVG 图表]
```

围栏定格并进入视口后，上述代码会被渲染为 SVG 流程图。你可以点击代码块横幅上的放大按钮在全屏浮层中查看，滚轮缩放、拖动平移；也可以直接复制源码或把渲染报错一键发给 AI 修复。

安全模型与已知限制¶

安全模型：

• 助手输出不可信：securityLevel 锁定 strict，标签中的 HTML 由 mermaid 内部 DOMPurify 消毒；不调用 bindFunctions，点击处理保持惰性。
• 渲染失败时保留原纯文本代码块（绝不渲染错误 HTML），并在图框下方显示错误摘要；控制台同时输出完整错误。

已知限制：

• 依赖主前端 CodeBlock 的稳定钩子（字面量类 md-code-block 与 infostring 文本）；上游渲染器重构时需要同步更新选择器。
• 流式输出期间不渲染，定格后才渲染。
• securityLevel: strict 下 mermaid 的点击交互不可用。

适用场景与注意¶

适合谁：

• 经常在 DSH Web 会话里让模型画流程图、架构图、时序图，希望就地看图而不是反复切换工具；
• 关注首屏性能，希望 Mermaid 运行时按需加载、不污染 boot 图；
• 需要亮/暗主题自动跟随、长对话视口驱动渲染的场景。

安装前注意：

DSH 的理念是「一切皆插件」，社区目录 SkillHub 是独立站点，与 DeepSeek / 幻方无官方从属关系。插件以当前 dsh 进程权限运行，安装前应检查 源码 与 MIT 许可证，确认符合你的安全要求。插件要求 Node.js ^22.19 || >=24。

链接¶

• 社区目录：https://www.skillhub.cn/plugins/AKS1st/dsh-mermaid
• GitHub 仓库：https://github.com/AKS1st/dsh-mermaid