前言¶
DeepSeek Harness (DSH) 的核心设计理念是「一切皆插件」。在开发基于模型的智能体或工作流时，让模型直接生成图表（如流程图、时序图）是一个常见需求。传统做法通常依赖模型输出 Markdown 代码块，然后由用户或脚本手动解析渲染，这增加了交互成本且不够直观。
butterhost69/dsh-mermaid-diagram 是一个 DSH 插件，它为模型提供了一个名为 mermaid 的工具，并负责在 Web UI 中将模型生成的图表渲染为交互式的卡片。这个插件通过直接在对话流中展示图表，解决了模型输出文本图表代码难以即时预览的问题。
核心功能¶
该插件主要提供以下能力：
- 模型工具集成：为模型提供
mermaid工具。该工具接受source参数（图表源码）和可选的title参数。 - 全类型图表支持：支持渲染 Mermaid 支持的多种图表类型，包括流程图、序列图、类图、状态图、ER 图、甘特图、饼图等。
- 主题感知与自适应：图表渲染会自动适配宿主 Web UI 的浅色/深色主题。当主题切换时，卡片会自动重新渲染以匹配新主题。
- 流式处理：在流式输出过程中显示进度，并在参数接收完整后进行渲染。
- 会话回溯：图表卡片是会话事件的一部分，可以从日志中派生，支持刷新页面或翻页后的重放。
- 容错机制：如果渲染失败，卡片会自动降级显示源代码视图，并附带错误提示，而不是显示破损的卡片。
- 本地化支持：卡片文本支持英文和简体中文，跟随宿主语言设置。
- 本地化运行：插件内置 Mermaid 运行时，不依赖外部 CDN，从插件自身的路由提供资源。
- 按需加载：Mermaid 运行时约 3.5 MB，仅在第一次出现图表时才加载，不影响启动速度。
安装与启用¶
安装前请确保环境满足以下要求：
* DSH 版本：0.2.1-alpha.1 或兼容版本。
* Node.js：^22.19 或 >=24。
* 运行环境：必须使用 Web 配置（即 dsh web），因为图表卡片依赖 Web 界面渲染。
执行以下命令安装插件：
dsh plugin --profile web add -w github:ButterHost69/dsh-mermaid-diagram
安装完成后，重启 dsh web 服务或刷新浏览器页面。
典型用法¶
在对话中向模型提问，请求生成图表。模型检测到需求后，会调用 mermaid 工具。
例如，你可以输入：
绘制一个发布流程的流程图。
模型会调用该工具，结果会以卡片形式出现在对话流中。该卡片包含以下交互功能：
* Diagram / Code 切换：查看渲染后的 SVG 图表或原始源码。
* Copy：一键复制图表源码到剪贴板。
* 错误回退：如果源码有误，默认打开 Code 视图，并在顶部显示错误提示。
适用场景与注意¶
- 适用场景：适用于需要模型直接生成架构图、算法流程图、数据模型等场景的开发者。
- 字符限制：图表源码超过 50,000 字符会被工具拦截，不会发送到浏览器（这是为了防止同步解析导致性能问题）。
- 渲染安全：卡片使用 Mermaid 的
strict安全级别渲染，标签会被自动清理。 - 交互限制：非常高的图表会在卡片内部滚动，而不会撑开整个对话记录。
总结¶
dsh-mermaid-diagram 通过将 mermaid 工具标准化集成到 DSH 生态中，为模型提供了直接绘图的能力。它解决了从文本代码到可视化的即时转化问题，配合流式输出和主题自适应功能，提升了交互体验。
