用途:用 Mermaid(flowchart、sequenceDiagram、stateDiagram-v2、erDiagram、class、pie 等)或 Graphviz DOT 写“图即代码”,让图首次渲染即通过解析器,并且可读,而非“箭头汤”。
主要能力与约束:按想法形态选图型——步骤用 flowchart LR,时间上多方交换消息用 sequenceDiagram(≤7 位参与者),状态用 stateDiagram-v2,表用 erDiagram,依赖树用 DOT;分层用带 subgraph 的 flowchart TB。源文件用 config: frontmatter 固定(theme: base、look: classic、layout: dagre 及设计系统 themeVariables),带 accTitle/accDescr,id 用字母数字,含标点的标签一律双引号,边标签写清动词和载荷,每图 ≤12 节点 / 20 边,用一处 classDef 强调承载要点的元素,超出上限就拆成两张图。
工作流:先明确 takeaway、目的地与实体(≤12,实体只能来自给定代码或文本,不得虚构);再按模板写源文件;用 diagram-review 的 mermaid_lint.py 做毫秒级 lint,修所有 ERROR、保留或说明每个 WARN;对 flowchart、sequence、pie、class、state 用 npx -y @probelabs/maid@0.0.29 diagram.mmd 真实解析器校验(ER、gantt 等未经 maid 校验,需标注“未校验”);再用 beautiful-mermaid 或 Graphviz 按设计系统渲染 PNG,渲染器忽略 config: frontmatter 且不支持 gantt、pie、mindmap、C4,这些改用 mmdc;然后调用 diagram-review 做保真度检查,最多再复核一次。
预算与限制:每次请求最多三次源文件改动(lint 修复、解析错误修复、按 brief 重生成各计一次);一次评审加最多一次复核;每次改动后都重新 lint、可用时重新渲染;达到上限就交付现有结果与遗留问题,不再循环。不提交、不推送。首次渲染需 --allow-install 安装固定 npm 包,未允许联网则跳过。Mermaid 12 改了默认布局与外观,必须固定配置;README 中避免最新图型;不要将私有图贴入托管编辑器或 kroki.io。lint 脚本无法运行时按失败关闭处理,标注 UNVALIDATED。
前提:该技能建立在 diagram-skills 的 diagram-design/brief、diagram-review 等配套脚本与规范之上,且未在本资料中给出完整独立安装说明;具体命令与参数以资料原文为准。