前言¶
在 DeepSeek Harness（DSH）里和模型对话时，回复里经常出现 ```mermaid 围栏代码块。默认情况下你看到的是源码；要对照结构，往往得自己复制到别的工具里渲染，或者等整轮回复结束再想办法预览。
社区插件 dsh-plugin-mermaid（维护者 kjx-talesofai）走另一条路：不改 Markdown 渲染管线，只在现有代码块 DOM 上挂一层客户端装饰，把识别成功的 Mermaid 块画成图，并且在流式输出过程中、块内容稳定后就能出图，不必等一轮 turn 结束。
下面按「做什么、怎么装、怎么用、要注意什么」说明，事实均来自 GitHub 仓库 README 与 package.json。
这是什么¶
dsh-plugin-mermaid 是 DSH 的客户端（web）插件：当助手回复里出现语言标记为 mermaid 的围栏代码块时，在页面上渲染为 Mermaid 图表；解析失败则保持原代码块，不插入占位 UI。
分类上属于「客户端」侧能力：不占 Cordis 槽位、不给模型加工具，也不替换整段 Markdown 渲染器。
核心功能¶
图表视图与工具栏¶
模型写出例如下面的块时，你看到的是图，而不是整段源码占满屏幕：
```mermaid
flowchart LR
A["工作区"] --> B["暂存区"] --> C["仓库"]
```
图上方有一条细栏，标注 Mermaid，并提供 复制 与 源码 / 图表 切换。插件展示图表时会隐藏代码块自带的 banner（语言标签那一行），源码 <pre> 仍由 DSH 渲染，只是用 CSS（:has()）在看图时藏起来；插件在 data-code-block-content 里增加 div.dsh-mermaid 节点。
流式回复中的渲染策略¶
DSH 对流式回复做增量 Markdown 解析：已完成的块只解析一次，React 元素会缓存，每个 token 主要重建尾部块。因此插件约定：源文本连续 220ms 不变才触发绘制。token 还在涌入时计时器会被重置，避免对「尾巴」反复画半张图；围栏闭合、后续正文开始到达后块冻结，图可以在同一轮回复中途出现。若在未闭合的围栏内停顿超过 220ms，会先按当前内容画一次；若之后源码继续增长，面板会丢弃并重画。Mermaid 无法解析的块整段保持原样。
同一源码与主题下的渲染结果会缓存，消息重渲染或切换主题时不重复跑 Mermaid。
复制行为¶
复制内容与当前视图一致：图表模式复制 PNG（约为显示尺寸的 2–3 倍，并铺代码块底色，便于贴进文档）；源码模式复制 Mermaid 文本。浏览器剪贴板对 SVG 不可靠，因此图经 canvas 栅格化；Mermaid 使用 htmlLabels: false，避免 <foreignObject> 在栅格化时丢失。
Mermaid 脚本来源与安全¶
浏览器通过同源、经认证的 Host 路由请求 /api/mermaid.asset.js，由 Host 从插件依赖树解析并提供 mermaid.min.js（约 3.4 MB，首次需要出图时加载，带 ETag 再验证）。渲染在浏览器内完成，使用 Mermaid strict 安全级别：HTML 标签会被清理，不提供 click-to-activate 链接。
依赖与环境¶
- DSH：
>=0.2.0-rc.1（README 徽章与package.json的engines.dsh/peerDependencies一致，上界为<0.3.0-0）。 - Node（开发/测试）：
>=22。 - 运行时依赖：
mermaid^11.17.2。 - 许可证：MIT。
安装与启用¶
通过 DSH Plugin Manager 的 Add plugin 安装，无需 npm 发布账号；不要用 npm install 作为安装路径。
| 方式 | 填写内容 |
|---|---|
| GitHub | github:kjx-talesofai/dsh-plugin-mermaid#v0.2.1 |
| 本地目录 | 插件仓库的绝对路径，例如 /path/to/dsh-plugin-mermaid |
安装完成后重启桌面应用：Host 侧负责资产路由，只在启动时加载。浏览器侧刷新页面（macOS 上为 ⌘R）即可加载客户端脚本。
插件在目录站 SkillHub 插件页 有收录；社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
- 按上一节安装并重启 DSH，刷新对话页。
- 在对话中让模型输出带
```mermaid围栏的回复（流程图、序列图等 Mermaid 支持的语法）。 - 块内容稳定后查看自动渲染的图；需要改源码时用工具栏切到 源码，需要贴文档时用 复制 取 PNG 或文本。
维护者在 README 中给出的流式示例即上述 flowchart LR 三节点链路，可直接复现。
适用场景与注意¶
适合谁：经常在 DSH 里阅读或编写含 Mermaid 的助手回复、希望边流式输出边看图、又不愿接管整段 Markdown 渲染的开发者。
能力边界（README Limits）：
- 无插件的 DSH 客户端（例如旧标签页的手机端、
--no-client工具链）仍只显示代码块。 - 解析失败时控制台会有
[mermaid] …日志，界面不增加错误行（避免流式过程中不完整语法闪烁）。 - 不提供按块的历史记录；面板只是当前 Markdown 视图。
- 不做：不改 Markdown 渲染器、不占 assistant 槽位、不加模型工具。
安全与信任：插件随当前 DSH 进程与客户端环境运行，会从 Host 拉取并执行 Mermaid 脚本。安装前请自行查看 仓库源码 与 MIT 许可证，确认符合你的使用策略。
结尾¶
dsh-plugin-mermaid 用最小的 DOM 耦合，在 DSH 回复里把 mermaid 代码块变成可切换、可复制的图表，并针对流式缓存语义做了 220ms 静止再绘制的策略。需要安装时记住 GitHub 引用 github:kjx-talesofai/dsh-plugin-mermaid#v0.2.1 与重启应用这一步。
