dsh-plugin-mermaid

dsh-plugin-mermaid

DSH 网页聊天中的 mermaid 内联渲染插件:把助手消息里定稿的 ```mermaid 代码块原位替换为 SVG 图表,并跟随应用浅色/深色主题;每张图带 下载 SVG / 下载 PNG 按钮。mermaid 版本 11.17.0(浏览器从 jsdelivr → fastly.jsdelivr → unpkg 三级 CDN 加载,securityLevel: 'strict')。

按官方规范 打包与安装插件 打包为可安装的 组合包(bundle)。

目录结构

mermaid/
├── package.json          # dsh.bundle + dsh.client 双 manifest
├── cordis.patch.yml      # bundle 层:插入 ui-mermaid 行
├── index.js              # node 半(空 apply,仅让 Loader 挂载该行)
├── scripts/build-client.mjs  # prepare:把浏览器半包装成 ModuleLoader bundle
├── src/client/index.js   # 浏览器半源码(纯 JS,无依赖,内联 CSS)
├── lib/client.js         # 预构建的浏览器 bundle(已随包分发)
└── README.md

安装(bundle)

本包声明 dsh.bundle,用 dsh plugin 装进 profile 即激活:

# 本地 checkout
dsh plugin --profile <name> add /path/to/mermaid

# 先验证层再启动
dsh --profile <name> --dump-config   # 应出现 "# == dsh-plugin-mermaid" 层
dsh --profile <name>

# 卸载(同时移除依赖与层)
dsh plugin --profile <name> remove dsh-plugin-mermaid

分发方式(三选一):

# 1. tarball(无需构建授权,推荐):作者 `pnpm pack` 后
dsh plugin --profile <name> add ./dsh-plugin-mermaid-1.1.0.tgz

# 2. npm 注册表(发布时 lib/ 已构建)
dsh plugin --profile <name> add dsh-plugin-mermaid

# 3. git 安装(源码;pnpm 会运行本包的 prepare 构建 lib/client.js)
dsh plugin --profile <name> add github:you/dsh-plugin-mermaid#<commit-sha>
# 首次会因 pnpm ≥10 的构建授权失败,按提示在该 profile 的
# pnpm-workspace.yaml 加 allowBuilds: { dsh-plugin-mermaid: true } 后重试

加载顺序:profile bundles(先 @deepseek-ai/dsh-base,再本包)→ profile 自己的 cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch。用户可在自己的层按 id: ui-mermaid 覆盖或删除本行(删除该行即关闭内联渲染,围栏恢复为普通代码块)。

工作原理

• 发现:宿主 clientModules 扫描 Loader 活跃行,本行声明 dsh.client.platform: web 且导出 ./client,于是进入 window.__DSH_BOOT__ 引导图,宿主以 /plugins/dsh-plugin-mermaid/client.js 提供预构建 bundle。
• 识别:Markdown 代码块渲染为 div.md-code-block,横幅显示语言名;流式输出期间语言名为空,消息定稿后才出现 mermaid,因此只替换完整代码块。
• 替换:MutationObserver + 350ms 防抖扫描,把 <pre> 原位替换为 SVG;React 若因重渲染恢复 <pre>(例如点击复制),观察器自动重新替换(自愈)。
• 主题:读取 theme 服务 ThemeSnapshot.active.colorScheme 并监听 theme/change,切换后按 mermaid default/dark 重绘。
• 下载:每张图下方有 "下载 SVG"(矢量原图)与 "下载 PNG"(2× 画布栅格化,按当前明暗主题填充背景)两个按钮,blob URL 下载后自动回收。
• 清理:插件停止时断开 observer、移除脚本/样式标签、还原所有源码。

已知限制

• 依赖浏览器能访问上述 CDN;完全离线环境需改为 Host 路由代理脚本。
• 图表宽度超出容器时横向滚动,无缩放交互。