dsh-web-mermaid

dsh-web-mermaid

DeepSeek Harness（DSH）Web 插件：把聊天 Markdown 中的 ```mermaid 围栏代码块自动渲染为 Mermaid 图表（SVG）。

• npm：dsh-web-mermaid@0.1.0（https://www.npmjs.com/package/dsh-web-mermaid）
• GitHub：https://github.com/vtxf/dsh-web-mermaid

完全离线：mermaid 运行时（vendor/mermaid.min.js，v11.16.1）随插件内置，由插件 Host 半通过同源路由提供，不依赖任何在线 CDN。

特性

• 助手回复中的 mermaid 围栏块在消息结束后自动渲染为可交互 SVG 图表（流式期间不渲染半截图）；
• 渲染失败（语法错误 / 资源缺失）时保留原始代码块，显示错误信息与「重试」按钮，复制按钮不受影响；语法错误不会被渲染成无法关闭的错误 SVG；
• 深浅色主题切换时已渲染图表跟随新主题自动重渲染；
• 零改动 DSH 核心源码，纯插件方式运行；
• 若在页面加载前执行 window.__DSH_MERMAID_ASSET__ = '…'，可覆盖 mermaid 资源地址（默认同源路由）。

工作原理

DSH 的 MarkdownText 把围栏代码块渲染为 <div class="md-code-block">（banner 里显示语言名，代码体为 <pre><code>；shiki 语言表不含 mermaid，因此 mermaid 块恒为纯文本代码体）。本插件在浏览器端用 MutationObserver 扫描 .md-code-block，判定语言名为 mermaid 后，用 mermaid.render 把代码体替换为 SVG 容器（保留 banner 与复制按钮），并对主题切换做重渲染。

维护提示：.md-code-block 结构来自 @deepseek-ai/dsh-client-ui-primitives 的 CodeBlock 组件；若 DSH 大版本升级改变该 DOM，本插件有文本回退判定（banner 文本 = mermaid），一般仍可工作，但建议升级后顺手验证。

安装（一条命令）

插件按 DSH 官方 bundle 机制打包（manifest 声明 dsh.bundle.patch，包内自带 cordis.patch.yml），用 DSH 自带的插件命令一键安装：

# 从 npm 安装（推荐）：
dsh plugin --profile web add dsh-web-mermaid

# 备选：从 GitHub 或本地目录安装：
dsh plugin --profile web add "github:vtxf/dsh-web-mermaid"
dsh plugin --profile web add "file:/path/to/dsh-web-mermaid"

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

安装或卸载后重启 dsh web 即可。

原理：dsh plugin 转发 pnpm 安装依赖，并自动把声明了 dsh.bundle.patch 的包加入 profile 的 dsh.profile.bundles 层；包内 cordis.patch.yml 即该层的 patch，随包自动注册插件行（- insert: [{ id: dsh-web-mermaid, name: dsh-web-mermaid }]）。无需 junction、无需手改任何配置文件。

手动兜底（不使用 dsh plugin 时）：把插件装进 profile 的 node_modules，并在 $DSH_HOME/profiles/web/cordis.patch.yml 追加 - insert: [{ id: dsh-web-mermaid, name: dsh-web-mermaid }]（见 cordis.patch.example.yml）。

使用

无需任何操作：在对话中让助手输出 ```mermaid 围栏块，消息结束后自动变成图表。例如：

```mermaid
graph TD
  A[开始] --> B{判断}
  B -->|是| C[继续]
  B -->|否| D[结束]
```

目录结构

dsh-web-mermaid/
├── package.json                  # npm 包声明（dsh.bundle + dsh.client + exports["./client"]）
├── index.js                      # Host 半：注册 /plugin-assets/dsh-web-mermaid/mermaid.min.js 路由
├── client.js                     # 浏览器半：渲染核心 + __ModuleLoader__.load 包装
├── cordis.patch.yml              # bundle patch：随 dsh plugin add 自动注册插件行
├── cordis.patch.example.yml      # 手动安装兜底示例
├── vendor/
│   ├── mermaid.min.js            # mermaid@11.16.1 UMD（离线内置）
│   ├── LICENSE                   # mermaid MIT 许可
│   └── SOURCE.md                 # 来源与升级记录
├── CHANGELOG.md                  # 版本历史
└── prototype/                    # 本地开发存档（.gitignore 排除，不随包发布）

已知限制

• 用户消息不渲染：DSH 用户消息是纯文本（非 Markdown），mermaid 只在助手消息中生效（DSH 现状，非本插件缺陷）；
• 流式期间不渲染：mermaid 块在消息结束后才出现图表（避免半截图）；
• 离线指 mermaid 运行时：图表内容若引用外部图片/链接仍由内容本身决定；
• 首图渲染需先加载内置的 mermaid.min.js（约 3.4MB，之后浏览器缓存）。

开发与发布

• 修改核心逻辑后：同步更新 client.js 与 prototype/dynamic-client-half.js（两者同源；prototype 仅本地存档，不发布）；
• 升级 mermaid：见 vendor/SOURCE.md；
• 变更记录：更新 CHANGELOG.md；
• 发布 npm：npm publish --registry https://registry.npmjs.org（无 TOTP 账号走浏览器 Passkey 认证，需在交互终端执行）；
• 保持 package.json 的 name: dsh-web-mermaid 不变（client 模块系统按包名关联 bundle id）。

版本历史

见 CHANGELOG.md。

许可

插件本体 MIT（见 LICENSE）；内置 mermaid 为 MIT（见 vendor/LICENSE）。