Mermaid 图表增强 pidongqianqian/dsh-mermaid-plus

dsh-mermaid-plus

给 DeepSeek Harness 用的 Mermaid 图表插件。默认按需渲染，所以哪怕整段对话里全是图表，只要你不点开，就一点开销都没有。

中文说明

截图

按需渲染，浅色主题。源码一直显示，直到你按下 Diagram 按钮：

一张 mermaid 卡片，显示源码和 Diagram 按钮

全屏查看器，浅色与深色。面板采用图表渲染时所用的配色，两种主题下标签都清晰可读：

浅色面板上的全屏 mermaid 查看器

深色面板上的全屏 mermaid 查看器

功能

对话里（或 Markdown 文件预览里）的
- 按需（默认）——源码保持可见，卡片头部有一个 Diagram 按钮。在你按下它之前，3.5 MB 的 Mermaid 运行时不会下载，也不会做任何布局计算。
- 可见时——卡片第一次滚动进入视野时渲染图表。
- 始终——代码块一出现就渲染（经典行为）。

每张渲染好的图表都能全屏打开，支持缩放和拖动。这正是重点所在：一张宽大的流程图挤在消息栏里根本没法看，同样的图按原始尺寸显示就没问题。

特性

- 渲染 mermaid、mermaidjs、mmd 代码块，以及以图表关键字开头的无标签代码块。
- 支持内置 Mermaid 构建自带的图表类型：flowchart/graph、sequenceDiagram、classDiagram、stateDiagram、erDiagram、gantt、pie、mindmap、journey、timeline、quadrantChart、xychart、gitGraph、requirementDiagram、C4、block-beta、packet-beta、sankey-beta、kanban、architecture-beta 等。
- 跟随主题：图表配色取自应用当前的设计 token，配色一变，只重渲染你正在看的那些图表。
- 流式安全：源码稳定之后才交给 Mermaid，所以写到一半的围栏不会闪出解析错误。
- 带缓存：渲染结果按源码 + 配色缓存，在 Code 和 Diagram 之间切换、或重新打开查看器，都不产生额外开销。
- 全屏查看器：滚轮缩放，拖动平移，双击适应窗口，Esc 关闭，对话框焦点锁定，关闭后恢复焦点和页面滚动。
- 图表解析失败时，回退到可见的源码，并显示一行简短错误信息。
- 卸载后，每个代码块都会恢复到会话记录中的原始位置。

安装

sh
dsh plugin --profile <profile> add dsh-mermaid-plus

也可以在 Settings → Plugins → Marketplace 里从目录安装（见 DSH 1024Store 列表）。装完重启应用，或刷新页面。

Mermaid 运行时打包在包里（vendor/mermaid.esm.min.mjs，Mermaid 11.17.0），由插件自己的 Host 路由提供，所以离线也能渲染，不会访问任何 CDN。全屏查看器和卡片都不会把图表源码发到任何地方。

配置

Settings → General → Mermaid diagrams 提供三种模式。选择按页面来源（origin）存储，并以包名做命名空间，因此不会和别的图表插件冲突。

兼容性

- 基于 DSH 0.2.0-rc.2（Desktop 2.0.17-next）构建并验证。
- DSH 还是开发者预览版：客户端插件契约、slot key、渲染出的 Markdown 都可能随版本变化。本插件装饰的是渲染后的 输出，这部分最容易变；如果某个版本把它弄坏了，卡片只是不再出现，代码块保持原样。
- 需要支持 IntersectionObserver（只在「when visible」模式下使用）和 DOMParser 的浏览器或 Electron 渲染进程。

工作原理

- Host 部分（index.js）挂载一个前缀路由，用来提供随包附带的 Mermaid ES 模块。路由由包名推导而来（/x-dsh-mermaid-plus），所以两个图表插件可以共存。
- 浏览器部分（client.js）是普通的 DSH 客户端 bundle：它在 shell.overlay 上注册一个根作用域的占位组件（该 slot 在任何会话之前就已存在），另外注册一行状态和一行配置。它从不导入 Harness 客户端包，也从不碰模型的上下文。
- 由于随附的 Markdown 渲染器没有暴露代码块扩展点，浏览器部分改为装饰渲染输出：把 mermaid 的 移进它自己管理的卡片，卸载时再放回去。原始 DOM 节点保留，所以会话记录、复制、选中都照常工作。

故障排查

浏览器部分会把生命周期事件上报给 Host 部分，Host 部分把它们追加到一个有大小上限的日志里：

<os tmp>/dsh-mermaid-plus/report.json

日志只记录生命周期事件——start、apply-ok、apply-throw、adopted、render-ok、render-error、blocks-unmatched——带计数，不含文档文本：没有图表源码，没有文件内容，也没有插件自身之外的路径。如果图表不再出现，这个文件加上浏览器控制台（导入失败）通常就能定位原因。

开发

插件自己的代码没有构建步骤：index.js 和 client.js 原样运行。只有 vendor/mermaid.esm.min.mjs 是生成的，而且只在随附的 Mermaid 版本变化时才生成。
sh
npm install # mermaid 11.17.0, esbuild, jsdom
node build.mjs # 重新构建 vendor/mermaid.esm.min.mjs
node test/run.mjs # Host 路由、真实 cordis 挂载、jsdom 浏览器半侧行为
node test/serve-e2e.mjs # 然后打开 http://127.0.0.1:8732/ 跑 35 个真实浏览器用例
node tools/doctor.mjs # 激活状态、安装模式、最近的浏览器事件
node tools/dev-sync.mjs # 把当前检出复制到 npm 安装的副本上

docs/development.md 讲调试流程、每种症状的含义，以及发布流程。

License

MIT。内置的 Mermaid 也是 MIT；见 vendor/mermaid.LICENSE。

中文说明

把对话（以及 Markdown 预览）里的 mermaid 代码块渲染成图表卡片。

默认按需渲染：代码块保持源码可见，卡片右上角有一个「图形」按钮；在你点它之前，Mermaid 那个约 3.5 MB 的运行时不会被下载，也不做任何布局计算。另外两种模式是「滚动可见」（卡片进入视口才渲染）和「立即」（出现即渲染）。

渲染后的图表可以全屏放大：滚轮缩放、拖动平移、双击适应窗口、Esc 关闭；全屏只克隆已有 SVG，不会重新渲染。

其他特性：

- 配色取自应用当前的 --dsw-* 设计令牌，明暗主题各自适配；主题切换只重绘你正在看的图。
- 流式输出期间不会渲染半截源码。
- 渲染结果按「配色 + 源码」缓存，切换「代码/图形」或重开全屏都是零成本。
- 解析失败时保留源码并给一行错误提示。
- 卸载时把每个代码块放回原位，不破坏对话内容。

模式开关在 设置 → 通用 → Mermaid 图表。Mermaid 运行时随包内置（11.17.0），由插件自己的 Host 路由提供，不访问 CDN、离线可用，图表源码不会发往任何地方。

兼容 DSH 0.2.0-rc.2。DSH 处于开发者预览阶段，客户端插件契约可能变化；本插件装饰渲染后的 ，是最容易受影响的一层——若某次升级后卡片不再出现，代码块本身仍然完好。

排障：浏览器半侧会把生命周期事件报告给 Host，写入 <系统临时目录>/dsh-mermaid-plus/report.json（start / adopted / render-ok / render-error / apply-ok / apply-throw）。