Mermaid 图表渲染AKS1st/dsh-mermaid

dsh-mermaid

English

在 DSH Web 会话消息中把
效果预览

| 亮色主题 · 会话内（未放大） | 暗色主题 · 会话内（未放大） |
| --- | --- |
| 亮色主题会话内渲染 | 暗色主题会话内渲染 |

| 亮色主题 · 放大浮层 | 暗色主题 · 放大浮层 |
| --- | --- |
| 亮色主题放大浮层 | 暗色主题放大浮层 |

放大浮层自动适配屏幕（接近全屏、四周留白），滚轮缩放，按住左键/中键可拖动平移；theme: auto 时图表颜色跟随 GUI 亮/暗主题。

工作方式

- Host 半部（src/index.ts）：注册 webServer 前缀路由 /mermaid-dist，从插件自己的 node_modules/mermaid 惰性提供 UMD 构建，并提供固定的 config.json 端点。
- Client 半部（src/client/）：监听会话 DOM，把 infostring 为 mermaid 的围栏渲染为 SVG：
1. 只处理已定格的围栏（流式输出期间不渲染）；
2. 首次遇到围栏才惰性加载 mermaid（浏览器缓存一次）；
3. 视口驱动渲染：围栏进入视口（带 300px 预加载余量）才开始渲染，滚到哪渲染到哪；还在排队/加载中离开视口的图会停止渲染，回到视口再继续；
4. 异步队列渲染：多图时逐个渲染并在渲染之间让出主线程，页面不卡顿；首次渲染期间围栏位置显示加载动画，渲染完成后替换为 SVG；
5. mermaid.render() 产出 SVG，替换围栏的  主体，语言横幅与复制按钮保留（复制仍复制源码）；
6. securityLevel 恒为 strict，标签经 mermaid 内置 DOMPurify 消毒，且从不绑定点击处理；
7. 主题跟随 GUI：theme: auto 读取 body[data-ds-dark-theme]，属性翻转时自动重渲染视口内的既有图表（视口外的图在重新进入视口时更新）；
8. 横幅放大按钮打开全屏浮层：图表打开时自动适配屏幕（接近全屏、四周留白、垂直/水平居中），滚轮在此基础上缩放，按住左键或中键拖动可平移画面（不放大也能拖，边界自动限制不让图跑丢），背景点击或 Esc 关闭；
9. 渲染失败可见化：首次渲染失败时保留源码块，并在图框下方显示错误摘要（超长自动截断、悬停查看全文），支持一键复制报错或发送给 AI 修复（自动把报错+源码填入输入框并发送，模拟用户将报错发给 AI）。

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

安装

从 GitHub 仓库安装（构建在 prepare 脚本里自动执行）：
sh
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 后重试即可。

本地开发（先构建再安装）：
sh
npm install
npm run build
dsh plugin --profile web add .
dsh web

卸载：
sh
dsh plugin --profile web remove dsh-mermaid

配置

组合包默认生效以下配置：
yaml
- insert:
- id: mermaid
name: 'dsh-mermaid'
config:
theme: auto
maxTextSize: 50000
maxEdges: 2000
securityLevel: strict

| 配置项         | 默认值    | 说明                                                        |
| -------------- | --------: | ----------------------------------------------------------- |
| theme        | auto    | 图表主题：auto（跟随亮/暗）、default、dark、neutral、forest、base |
| maxTextSize  | 50000     | 单图文本上限（防超大图拖垮渲染）                             |
| maxEdges     | 2000      | 边数守卫                                                    |
| securityLevel| strict  | 固定为 strict，不接受 loose                             |

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

安全模型

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

已知限制

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