前言¶
在开发协作中，架构描述、数据流向和状态变迁通常更适合用图表而非纯文本。DeepSeek Harness (DSH) 的理念是「一切皆插件」，dsh-mermaid-comm 是其中专注于图表生成的插件。它解决的核心问题是：让 AI 在对话中默认优先输出 Mermaid 图表，同时通过语法校验和输出门机制保证图表可用且安全。
是什么¶
dsh-mermaid-comm 是一个由开发者 kp-z 维护的模型推理插件。它通过注入系统提示词引导 AI 在特定场景下使用 Mermaid 语法，并注册了 mermaid_validate 工具进行校验。渲染工作由 dsh-mermaid 插件完成，本插件负责引导、校验和安全性控制。
核心功能¶
1. 行为引导¶
插件会注入 systemPrompt.section。在架构、数据流、序列图、状态图等话题中，AI 会被引导为「先画图，再给简短解释」的输出模式。
2. 语法验证¶
插件注册了 mermaid_validate 工具。校验流程分为两步：首先扫描危险字符，随后调用与 dsh-mermaid 同版本的 mermaid-runtime 进行实际解析。
3. 输出门¶
插件监听助手消息事件。它会自动修复 Mermaid 代码中的 Unicode 箭头和危险标签；如果图表无法通过校验，会将其从可见界面移除，而不是让用户看到渲染失败的内容。
4. Mermaid Vault¶
这是图表持久化的核心。插件将经过验证的图表保存到 <workspace>/.dsh/mermaid/ 目录。文件结构包含：
* INDEX.md：图表索引（主题/类型/版本/更新时间）。
* <name>.mmd：当前活跃版本。
* <name>.history.md：版本演变历史。
安装与启用¶
在安装本插件前，需要确保已安装 dsh-mermaid 插件，否则 mermaid_validate 会明确失败，而不会静默通过。
dsh plugin --profile web add dsh-mermaid-comm
dsh plugin --profile web add dsh-mermaid
安装完成后重启 dsh web。
典型用法¶
AI 默认会根据上下文选择合适的 Mermaid 图表类型：
- 架构 / 模块关系 →
flowchart或classDiagram - 调用链 / 请求序列 →
sequenceDiagram - 状态 / 生命周期 →
stateDiagram-v2 - 数据模型 / 表关系 →
erDiagram - 分支策略 / Git 历史 →
gitGraph - 计划 / 甘特图 →
gantt
Mermaid Vault 工具¶
Vault 目录下提供了四个工具供模型调用：
mermaid_vault_list：列出索引，可选按类型筛选。mermaid_vault_read：读取某个主题的当前代码及历史记录。mermaid_vault_save：保存或更新图表，强制要求通过真实解析器校验。mermaid_vault_delete：删除某个主题。
当某个主题已存在时，系统提示词会引导模型读取历史并使用 save 进行迭代（v2, v3…），而不是从零重绘，确保对话中的图表演进具有连续性。
安全与限制¶
- 命名安全：主题名称会被清理为
[a-zA-Z0-9-_]，防止路径遍历攻击。 - 目录锁定：所有写入操作被限制在 Vault 目录内部。
- 原子写入：文件写入采用原子操作，避免中途损坏。
- 大小限制：通过大小和版本限制防止目录无限增长。
总结¶
dsh-mermaid-comm 通过 Prompt 注入、工具注册和输出拦截，解决了 AI 生成 Mermaid 图表不稳定的问题，并提供了 Vault 机制让图表成为可管理的资产。
