罗老师 Mermaid 验证器

解决什么问题

在文档、评审记录和 Agent 对话里，Mermaid 代码块越来越常见。但它有两个容易被忽略的问题：语法看起来对，渲染平台却报错；语法通过了，图里的逻辑却是错的——漏了分支、箭头方向反了、终点没有着落。团队协作时还会踩到环境坑：有的渲染器版本不同，本地编译工具也没配好。

lls-mermaid-validator 就是处理这些环节的技能。它不负责帮你写流程，而是负责把已经写好的图变成一份能真正编译通过、且语义上站得住的产物。

核心能力与关键步骤

按内容选图类型：流程走步骤用 flowchart；系统间消息用 sequenceDiagram；对象状态与转换用 stateDiagram-v2；结构关系用 classDiagram / erDiagram。选错类型是很多图看不懂的根因。

规范写法：中文标签、括号、标点较多的文本统一加双引号；不把 end、subgraph 这类保留词当裸 ID；ID 保持稳定简短，展示文案单独写；超过约 12 个核心节点就拆图，而不是继续塞内容。

真实编译：脚本优先使用本机 mmdc，找不到时退到当前项目里已安装的 npx --no-install mmdc，不会在验证时偷偷联网装依赖。编译失败时会缩小到最小失败片段再逐段恢复，而不是直接放弃。

语义复核：编译通过不等于逻辑正确。需要检查分支条件是否写清、是否存在反向箭头、责任归属是否清楚、终止状态是否完整，并对图中的 Token、客户名、内网地址做脱敏。

交付物完整：.mmd 源文件、渲染后的 SVG/PNG、验证报告，以及一份纯文字版说明，让无法渲染 Mermaid 的环境也能看懂流程。

适用边界

• 它不做图的美学优化。样式是最后一步，靠 CSS 掩盖结构问题不是它的路线。
• 不同平台语法版本有差异时，它记录编译器版本，并提供文字版作为兜底。
• 找不到 mmdc 时会明确报告 tool_missing，不会把「未验证」写成「通过」。
• 它只验证图的语法与语义，流程本身该不该这么设计，仍然需要人来判断。