图表渲染 denistv/dsh-mermaid

dsh-mermaid

在 DeepSeek Harness 聊天和 Markdown 预览里显示 Mermaid 图表。
本地渲染，跟随外壳主题，可展开到全尺寸。

聊天和 Markdown 预览中的 Mermaid 卡片

dsh-mermaid 是 DeepSeek Harness（DSH） 的插件包。每个闭合的

- 聊天 —— 包含该围栏的助手回答下方会出现一张图表卡片。
- Markdown 预览 —— 打开任意 .md 文件，Mermaid 围栏会在普通 Markdown 块之间就地渲染。

所有内容都打包进插件：不走 CDN，不调渲染服务，不发网络请求。图表跟随外壳的浅色和深色主题，使用界面字体，还能展开成可调整大小的全窗口视图。

状态：0.1.0 原型。 基于 DeepSeek Harness 0.2.1-rc.3 构建并测试。它用到的扩展点还不是稳定的公开 API，所以跨 harness 版本可能会有小改动。

功能

- 两个界面，一套运行时。 聊天和文档预览共用同一个 Mermaid 渲染器、主题 token 和卡片 UI。
- 卡片不碍事。 每张卡片都有 Expand、Source / Diagram 和 Copy 控件。Source 显示原始围栏；Copy 把它复制到剪贴板。
- 可展开视图。 Expand 打开居中模态框，背景变暗，带角部缩放手柄和 Maximize / Default size 切换。面板初始 1120×780，最小可缩到 420×300，在 localStorage 里记住你偏好的尺寸，窗口变化时重新收束。
- 跟随主题。 颜色取自外壳的 --dsw-alias- token，传给 Mermaid 的 base 主题；theme/change 时重新渲染图表。
- 不另起查看器。 内置 Markdown 预览保留自己的下拉入口——插件只替换它的正文，标题、代码高亮、表格、脚注和净化处理都保持原样。
- 天生离线。 mermaid、marked 和 DOMPurify 都编译进单个客户端产物。
- 失败也优雅。 图表出错时，在源码上方显示解析错误，而不是直接消失；空围栏会明确提示。

截图

聊天上方展开的图表模态框

同一张图表展开后：可调整大小的面板、最大化切换、按 Escape 或点击背景关闭。*

要求
- DeepSeek Harness 0.2.1-rc.3 或兼容版本。插件针对该版本的客户端扩展点。

用户无需构建：浏览器包已预构建，所有图表渲染都在插件内部完成。

安装

插件发布在 GitHub 上，直接从仓库安装——不用 npm 包，不用本地检出，不用构建： text https://github.com/denistv/dsh-mermaid

DSH 读取仓库，把它作为配置档包安装，并锁定安装时的 commit。

在桌面应用中

1. 在侧边栏打开 Plugins。
2. 点击 Add plugin。
3. 粘贴仓库 URL，按 Enter：

text
https://github.com/denistv/dsh-mermaid

4. 点击 Install，等待结果页。Host 读取仓库，把包安装到当前配置档。
5. 点击 Enable now。如果对话框已关闭，在 Installed plugins 下打开 dsh-mermaid 卡片，把它打开。
6. 如果页面提示，就重启 DSH；否则重新加载窗口。客户端包在页面加载时拉取，所以在那之前插件不会出现。

设置就这些——之后无需配置。插件对配置档内所有会话生效，包一打开就立即激活。

从 DSH 会话中

你也可以让智能体从同一 URL 安装：

Install the plugin from https://github.com/denistv/dsh-mermaid

智能体调用 plugin_manager，传入 action: install_bundle 和仓库 URL，执行与对话框相同的包安装和包选择。该调用需要 Full access 或审批。

检查是否生效

在侧边栏打开 demo/mermaid-demo.md：其中的 Mermaid 围栏会渲染成图表卡片。或者在聊天中请求一张图表，看回答下方是否出现卡片。

更新或移除

- 更新： 已安装的包锁定到某个 commit。在 Installed plugins 下打开它的卡片，选择 Uninstall，然后再次添加同一 URL，安装最新 commit。
- 移除： 在卡片上点 Uninstall；确认后移除依赖和包条目。

禁用或移除包会注销两个界面，并移除插件添加的所有样式规则。

用法

在聊天中

请求一张图表，或把围栏粘贴到任意消息里。回合结束后，围栏渲染成回答下方的卡片： markdown
flowchart LR
A[Question] --> B{Answer}
B --> C[Diagram card]

mermaid 和 mmd 两种 info string 都会被识别。其他语言保持普通代码块。只有闭合的围栏才渲染——消息还在流式输出时，未完成的围栏仍是普通代码块。

聊天卡片从回合的持久数据（closing.finalNode.blocks）读取，不从 DOM 抓取，所以流式输出、虚拟化重渲染、分页和会话切换都不会让它们错位。

在 Markdown 预览中在侧边栏打开 .md / .markdown 文件。Mermaid 围栏会就地变成图表卡片；文档其余部分走 harness 自带的 MarkdownText，所以排版、语法高亮、净化处理都和内置预览一致。

demo/mermaid-demo.md 是现成的示例文件，包含流程图、时序图、类图、状态图、甘特图和饼图，另有一个非 Mermaid 围栏，以及会被剥离的不安全 HTML。

控件

| 控件 | 位置 | 作用 |
| Expand | 卡片 | 在模态视图中打开图表。 |
| Source / Diagram | 卡片 | 在渲染后的 SVG 和原始围栏之间切换。 |
| Copy | 卡片 | 把图表源码复制到剪贴板。 |
| Maximize / Default size | 模态标题栏 | 填满可用框架，或恢复保存的尺寸。 |
| Close | 模态标题栏 | 关闭模态；按 Escape 和点击背景效果相同。 |

展开视图注册在根级 shell.overlay 层，而不是放在对话记录里。对话记录会裁剪溢出内容，还可能带 transform 动画——两者都会困住 fixed 定位的子元素。打开时焦点移入对话框，关闭时回到触发元素。

工作原理 mermaid
flowchart LR
turn[Assistant turn] -->|closing text blocks| card[Chat card]
file[.md document] -->|Markdown body override| preview[Preview cards]
card --> render[Mermaid render]
preview --> render
render --> svg[(SVG)]
card -. Expand .-> modal[Full-window modal]

| 界面 | 扩展点 | 说明 |
| 聊天 | conversation.chat.turnTail（order 35） | 每轮一个单元格；读取持久化的消息块。 |
| 文档 | sidebar.right.tab.document | 以自己的 key、在优先级 -1 上遮蔽自带的 Markdown 正文，这样查看器下拉菜单里仍只有一个 Markdown 条目。 |
| 模态 | shell.overlay | 点击穿透层；overlay 根节点重新启用指针事件。 |

整个客户端是一个 bundle：mermaid、marked、DOMPurify 都编译进去，只有 React 保持外部依赖，因为 harness 会提供它。运行时不再拉取任何东西，所以图表可以离线渲染。

如果 harness 以后不再暴露 MarkdownText，文档正文会回退到打包的 marked + DOMPurify 渲染器，而不是变成空白。如果未来的 harness 提供公开的代码围栏渲染器注册表，正文覆盖就应该换成它。

所有注册都放在 effect 里，包括样式表，所以禁用插件会移除它的卡片、它的 overlay，以及它添加的每一条规则。

兼容性与限制

- 聊天卡片是追加的，不是替换的。 这个 harness 版本没有公开的围栏渲染器，所以原始代码块仍显示在图表上方。替换整个助手步骤会遮蔽自带的消息 UI。
- 只处理闭合的围栏。 未完成的围栏在结束行到达之前一直是代码块。
- 预览覆盖对版本敏感。 它针对的是自带的
- Markdown 正文 id。 如果将来某个 harness 重命名了这个 id，或者改动了正文约定，覆盖就会失效，未改动过的内置查看器会重新接管。
- Frontmatter 会原样显示在一个小代码块里，而不是内置的字段列表。
- 在围栏边界处切分可能破坏引用式链接或脚注定义，因为它们位于图表的另一侧。
- 展开视图会把图表适配到面板大小：目前还不支持平移和增量缩放。调整大小的手柄只支持指针操作；标题栏的 Maximize 按钮是键盘友好的操作路径。
- 超大图表布局时可能要等一会儿，因为渲染会串行执行，以保护 Mermaid 共享的布局状态。
- 共存。 另一个会追加图表卡片的聊天插件（例如 @baconbao/dsh-mermaid-image-preview）会为同一个围栏再加一张卡片。请只启用其中一个。在文档侧没有第二个查看器入口会与之冲突。

License

MIT © dsh-mermaid contributors。