dsh-mermaid-comm

dsh plugin --profile web add dsh-mermaid-comm

dsh-mermaid-comm

让 AI 在开发交流中默认、优先用 Mermaid 图表达。渲染由 dsh-mermaid 负责，本插件专注于提示词、校验和输出安全闸。


功能

能力 · 作用

A. 行为引导 · 注入 systemPrompt.section：架构、数据流、时序、状态、依赖等开发话题优先用 Mermaid，先图后简短解释。由对话输入框的勾选按钮控制，默认关（见下）。

B. 语法校验 · 注册 mermaid_validate 工具，先做危险字符扫描，再调用 dsh-mermaid 同版本 mermaid-runtime 真解析。

C. 输出闸 · 监听 assistant 消息落盘事件；对 Mermaid 围栏自动修复 Unicode 箭头/危险标签，无法确认通过时从可见 surface 摘除坏图。

D. 图库（Mermaid Vault） · 把验证通过的图持久化到 <workspace>/.dsh/mermaid/，形成同主题多版本资产：<name>.mmd（当前版）+ <name>.history.md（演进历史）+ INDEX.md。索引注入系统提示，后续对话基于旧图演进而非从零重画。

注入开关——对话输入框的勾选按钮

0.3.0 起，prompt 注入默认关闭，由对话输入框工具行左侧的勾选按钮控制：

状态 · 行为

未勾选（默认） · 不注入 guidance，也不注入图库索引——模型看不到任何 Mermaid 引导

勾选 · 从下一轮开始注入；system prompt 每轮实时重算，改动立刻生效

真值住在 host（ctx.settings，namespace mermaid-comm-inject），全局粘性：勾一次所有会话都生效，重启后仍在。输入框里那颗按钮只是这台开关的遥控器——它挂在 per-session 插槽上，切换会话会重挂载（官方 renderer 明确要求组件局部状态不得跨会话泄漏），所以状态不能放在组件里。

promptLevel 三态：toggle（默认，由按钮控制）/ global（恒定注入，按钮自动隐藏）/ off（从不注入，按钮自动隐藏）。

工具（mermaid_validate + 图库四件套）与输出闸不受开关影响，始终可用——注入是「引导模型画」，工具是「画的时候帮你把关」，两件事解耦。

图库（Mermaid Vault）——图的持久化与演进

0.2.0 新增。值得长期保留的图——架构、数据模型、核心流程——会保存到图库，形成同主题版本化系列：

<workspace>/.dsh/mermaid/
├── INDEX.md                 # 图库索引（主题/类型/版本/更新时间）
├── payment-flow.mmd         # 当前活跃版（始终可渲染）
└── payment-flow.history.md  # v1/v2/... 各版本变更说明

4 个模型可见工具：

• mermaid_vault_list — 列出图库索引（可选按类型过滤）
• mermaid_vault_read — 读某主题：当前源码 + 演进历史
• mermaid_vault_save — 保存/更新一张图（强制真解析校验，语法错拒绝保存，图库里永远是能渲染的图）
• mermaid_vault_delete — 删除某主题（主文件 + 历史 + 索引项）

图库索引会注入系统提示（只注入轻量表格，图内容按需用 mermaid_vault_read 读取）。当某主题已在库中时，模型被引导先读历史再 save 演进（生成 v2/v3/...），而不是从零重画——这样后续对话能看到图的持续变化，并与之前的工作保持一致。

安全边界：主题名 sanitize 为 [a-zA-Z0-9-_]（杜绝路径穿越）、写入锁定在 vault 目录内、原子写、大小与版本上限防止无限膨胀。

安装

dsh plugin --profile web add dsh-mermaid-comm dsh-mermaid

一条命令装两个包。 两个包各有分工，缺一不可：

包 · 管什么 · 为什么必须单独装

dsh-mermaid-comm · prompt 注入、mermaid_validate、图库、输出闸 · 就是本插件

dsh-mermaid · 把对话流里的 mermaid 围栏渲染成图 · 必须进 dsh.profile.bundles 才会被挂载

dsh-mermaid 也已声明为本插件的普通依赖，所以只装本插件它也会被 pnpm 装上（代码在 node_modules 里）；但「装上」不等于「挂载」——dsh 只应用 dsh.profile.bundles 里各包的 cordis.patch.yml，不在名册里的包不会被挂载，图表也就不会渲染。所以要把它一并加进名册。

为什么本插件不替你把 dsh-mermaid 挂上？试过（v0.3.0 的 carrier 方案），必然启动失败：dsh-mermaid 自带 dsh.bundle.patch，只要它成为 profile 顶层依赖就会被自动提升进 bundles，于是它与本插件的插入行撞同一个 entry id ui-mermaid，而 cordis 对重复 loader entry id 是硬失败（整棵树起不来，报错不点名任何插件）：重复的 loader 条目 id "ui-mermaid"。这不是能靠文档规避的边界，而是设计冲突，故 v0.3.1 撤销，改为上面这条两包命令。

重启 dsh web（插件名册与客户端 bundle 均在启动时加载）。可自查组合结果：dsh --profile web --dump-config，ui-mermaid 与 mermaid-comm 各出现 1 次即为正常。

使用

涉及以下内容时，模型会默认优先输出 Mermaid：

• 架构 / 模块关系 → flowchart 或 classDiagram
• 调用链 / 请求时序 → sequenceDiagram
• 状态 / 生命周期 → stateDiagram-v2
• 数据模型 / 表关系 → erDiagram
• 分支策略 / Git 历史 → gitGraph
• 计划 / 排期 → gantt

校验规则

mermaid_validate 返回：

• ok：当前代码是否通过；
• built：规则修复后的代码；
• fixes：执行过的修复；
• errors：危险字符、运行时缺失或解析错误；
• mode: "true-runtime"：兼容旧调用方的模式标记。

输出闸支持 `mermaid 与 `mermaidd 围栏。每个坏块会被独立复评；能通过同款运行时解析的修正版会替换原块，仍失败的块会替换为安全提示，不会交给渲染器。

安全边界

• Unicode 箭头、未配对引号、subgraph 特殊字符会先被扫描/修复；
• 真解析直接使用 dsh-mermaid 的 lib/mermaid-runtime.js，不再依赖容易误判的 .hash 错误字段；
• 原始事件仍保留在 transcript，修正版通过 surface replace 覆盖可见消息；
• 输出闸只处理 assistant/message 的 append 事件，并通过 gateFixed 标记防止重复处理。

开发

pnpm install
pnpm --filter dsh-mermaid-comm build
pnpm --filter dsh-mermaid-comm typecheck

从 checkout 安装：

dsh plugin --profile web add file:/path/to/packages/dsh-mermaid-comm

许可证

MIT