Saan Mermaid

安装

npx skills add yishan/saankits --skill saan-mermaid

本地校验需要 Python 3；渲染本页全部示例需要 Mermaid CLI 12。

图示类型

架构图

流程图

其他图示

示例内容均为虚构。复制代码包含主题配置；Beta 语法需确认平台版本。

架构图 · 按阶段

%% saan: arch
flowchart LR
  classDef external fill:#8FB0FF,stroke:#8FB0FF,color:#1F2329
  subgraph contract[合同阶段]
    direction TB
    c1[合同台账]
    c2[合同变更]
  end
  subgraph settle[结算阶段]
    direction TB
    s1[产值结算]
    s2[支付管理]
  end
  subgraph ext[外部系统]
    direction TB
    fin[财务系统]:::external
  end
  contract --> settle
  s2 --> fin
架构图 · 按阶段示例：每个阶段有哪些模块，接哪些系统。

节点写能力，只画阶段之间和对外系统的连线。

架构图 · 按层

block-beta
  columns 3
  app["应用层"]:3
  a1["合同管理"] a2["结算管理"] a3["经营分析"]
  data["数据层"]:3
  d1["主数据"] d2["业务数据"] d3["指标数据"]
架构图 · 按层示例：平台由哪些层组成。

Beta 语法，放不下侧栏。要标注对外接口或体系约束，改用 Saan Diagram。

流程图

%% saan: approval
flowchart LR
  classDef core fill:#E2EBFF,stroke:#2B5FD8,color:#1F2329
  apply[提交申请] --> check{审核通过?}
  check -->|是| sign[签订合同]:::core
  check -->|否| fix[退回修改]
  fix -.-> apply
  sign --> archive[合同归档]
流程图示例：一条流程怎么走，在哪里判断和退回。

声明 saan: approval 后，缺判断或缺退回都会被查出来。退回用虚线。节点多时改成纵向。

流程图 · 泳道

%% saan: approval
swimlane-beta LR
  subgraph biz[业务部门]
    apply[发起付款申请]
    fix[修改申请]
  end
  subgraph fin[财务部门]
    audit{审核单据}
    pay[执行付款]
  end
  apply --> audit
  audit -->|通过| pay
  audit -->|退回| fix
  fix -.-> apply
流程图 · 泳道示例：多个角色之间怎么交接。

需要 Mermaid 12。泳道对齐，但线路和间距控制不了。泳道也是岗位分离检查的依据。

流程图 · 总览

%% saan: overview
flowchart LR
  classDef core fill:#E2EBFF,stroke:#2B5FD8,color:#1F2329
  classDef external fill:#8FB0FF,stroke:#8FB0FF,color:#1F2329
  subgraph hub[经营平台]
    direction LR
    p1[签订合同] --> p2[结算产值]:::core --> p3[归集成本]
  end
  bid[招采系统]:::external -->|中标结果| p1
  p3 -->|凭证数据| fin[财务系统]:::external
流程图 · 总览示例：跨系统看，业务从头到尾怎么走。

只画正向主线，出现回路会被查出来。审批和审计流程不用这张。

时序图

sequenceDiagram
  autonumber
  participant U as 业务人员
  participant P as 平台
  participant F as 财务系统
  U->>P: 提交结算
  P->>F: 推送凭证
  alt 校验通过
    F-->>P: 返回凭证号
  else 校验失败
    F-->>P: 返回错误
    P-->>U: 退回修改
  end
时序图示例：系统之间按什么顺序交互，失败时怎么走。

用 alt 写失败分支。消息文字避免冒号和分号。

状态图

stateDiagram-v2
  direction LR
  [*] --> 草稿
  草稿 --> 审批中: 提交
  审批中 --> 已生效: 通过
  审批中 --> 草稿: 退回
  已生效 --> 已归档: 归档
  已归档 --> [*]
状态图示例：一张单据有哪些状态，什么动作触发流转。

每条流转都写触发动作。

实体关系图

erDiagram
  direction LR
  合同 ||--o{ 结算单 : 产生
  结算单 ||--|{ 付款单 : 拆分
  供应商 ||--o{ 合同 : 签订
实体关系图示例：有哪些业务对象，彼此几对几。

默认画到概念层。用户要字段时才写字段。

甘特图

gantt
  title 上线计划（示例）
  dateFormat YYYY-MM-DD
  axisFormat %m-%d
  todayMarker off
  section 准备
  需求确认 :done, a1, 2026-09-01, 15d
  方案评审 :done, a2, after a1, 7d
  section 实施
  开发 :a3, after a2, 30d
  联调测试 :a4, after a3, 14d
  上线 :milestone, m1, after a4, 0d
甘特图示例：任务排期和前后依赖。

用 after 写依赖，改一个任务的工期，后续任务自动顺延。

时间线

timeline
  title 平台里程碑（示例）
  第一季度 : 需求确认
  第二季度 : 合同模块上线 : 数据迁移
  第三季度 : 结算模块上线
时间线示例：关键节点什么时候到。

只表达时间，不表达计划和实际的偏差。要看偏差，改用 Saan Diagram。

四象限图

%%{init: {"quadrantChart": {"pointTextPadding": 14}}}%%
quadrantChart
  title 优先级（示例）
  x-axis 低投入 --> 高投入
  y-axis 低价值 --> 高价值
  quadrant-1 大项目
  quadrant-2 先做
  quadrant-3 暂缓
  quadrant-4 慎做
  经营预警: [0.3, 0.8]
  智能问答: [0.7, 0.6]
  报表换肤: [0.25, 0.2]
四象限图示例：一组事项在两个维度上该先做哪个。

坐标是相对位置，不代表测算结果，标签要短。

鱼骨图

ishikawa-beta
  付款延迟
  流程
    审批层级多
    退回无时限
  数据
    单据不齐
  系统
    接口失败
鱼骨图示例：一个结果背后有哪些原因。

Beta 语法，版本要求高。先确认文档平台能渲染。

流程审查

先确定控制点清单，再审查流程。优先使用你提供的清单；从同一份资料提取时，结果会标明“不是独立依据”。

controls.txt，制度要求
source: user
control: 财务复核
must_pass: 执行付款 through 审核单据
separate: 提交付款申请 | 审核单据
一张能渲染的付款流程
%% saan: approval
swimlane-beta LR
  subgraph biz[业务部门]
    apply[提交付款申请]
    audit{审核单据}
  end
  subgraph fin[财务部门]
    pay[执行付款]
  end
  apply --> audit
  audit --> pay
  apply -->|小额| pay
check_mermaid.py 的实际输出
必须修改 [CP1] 控制点清单里的『财务复核』不在图上。补上节点，或告诉用户它为什么不用画
业务发现 [RT1] 1 个审批判断没有退回分支，资料或流程要写明未通过怎么走：审核单据
业务发现 [P1] 可以绕过『审核单据』到达『执行付款』
业务发现 [P5] 『提交付款申请』与『审核单据』都由『业务部门』执行，违反岗位分离
图的声明或清单项检查什么
saan: flowP2 走不到 · P3 死路 · P4 判断只有一个出口
saan: approval / audit再加 AP1 没有判断节点 · RT1 审批判断没有退回
saan: overview再加 OV1 总览出现回路
saan: archAR1 架构图里混入判断节点
controlCP1 清单里的控制点不在图上
must_passP1 可以绕过控制点
separateP5 不相容的两步由同一泳道执行

业务发现要报告给你，不会为了通过校验而删线。确认属实又确实要保留的，写 %% accept P1: 原因，脚本会标为已确认。

工具对比

Saan MermaidSaan Diagram
产出Mermaid 代码，可做 diff图片、HTML、飞书画板
适合README、Markdown、设计文档汇报、对外交付、飞书画板
排版自动布局，泳道能对齐，线路控制不了引擎精确控制
质量保证按控制点清单审查、配色校验、真实渲染、人工看图几何、对比度和业务规则校验
独有的图时序图、状态图、甘特图IDEF0、组织架构与数据隔离

绘图规则

画法规则

  • 只画来源支持的内容，假设写在图外。
  • 确实有分支才加判断节点。
  • 总览只画正向主线。审批和审计流程必须保留判断和退回，否则会藏掉控制风险。
  • 交接不是重点时，不写内部角色泳道。
  • 默认实线，虚线只留给退回或可选路径。
  • 核心节点最多高亮 3 个。
  • 一张流程图约 15 个节点，超过就拆成总览加细节。
  • 节点文字要短，功能清单写在正文里。

常见语法错误

  • 文字含标点或括号时加引号：A["合同(草稿)"]
  • 节点 ID 用英文，中文写在标签里：apply[提交申请]
  • 不要用小写 end 作节点 ID。
  • 分组内要纵向排列时，写 direction TB。
  • 流程图标签换行用 <br/>。
  • 时序图消息文字避免 : 和 ;。

主题配置

放在每张图最顶部，换一个平台也不用重新配。页面有深色模式时，要再看一眼效果。

业务节点默认，不用写
hub汇聚枢纽
core核心节点，最多 3 个
system内部系统
external外部系统
aiAI 能力

和 Saan Diagram 同一套色值。自造颜色、用 style 单独改色、核心节点超过 3 个，校验都不放行。

frontmatter
---
config:
  theme: base
  themeVariables:
    fontFamily: "PingFang SC, Microsoft YaHei, Noto Sans CJK SC, sans-serif"
    primaryColor: "#E3E5EA"
    primaryTextColor: "#1F2329"
    primaryBorderColor: "#E3E5EA"
    secondaryColor: "#E9ECF1"
    tertiaryColor: "#F5F6F8"
    lineColor: "#4E5563"
    textColor: "#1F2329"
    clusterBkg: "#F5F6F8"
    clusterBorder: "#D5D8DE"
    edgeLabelBackground: "#FFFFFF"
    dropShadow: "none"
    cScale0: "#E3E5EA"
    cScale1: "#E2EBFF"
    cScale2: "#E9ECF1"
    cScale3: "#F5F6F8"
---

交付检查

脚本会一起检查错误占位图和图宽，宽度超过 1200 就提醒。自动布局可能挤成一团，所以每张图还要看一眼。

mmdc -i diagram.mmd -o diagram.svg -b white -q
python3 check_mermaid.py --controls controls.txt diagram.mmd diagram.svg
  1. 能读每个标签都看得清，没有重叠。
  2. 顺向主线朝一个方向走，避开能避免的交叉。
  3. 不漏流程要求的判断和退回都在。
  4. 不编每个节点和连线都来自来源或写明的假设。

调一两次仍然缠在一起，就拆图。需要精确摆放，就换 Saan Diagram。

兼容性与限制

泳道依赖 Mermaid 12

swimlane-beta 能对齐泳道，但泳道之间没有分隔，线路也可能绕到外侧。低版本平台只能退回分组框，各列对不齐。

平台版本不同

每个平台内置的 Mermaid 版本不同。本页的图用 Mermaid CLI 12.2 渲染，还没在 GitHub 或飞书文档里测过。

只查结构和清单

它不判断业务本身对不对，清单之外的问题也查不出。清单如果和图出自同一个人，独立性就很弱。时序图等类型只查配色。

不保证画得更好

一次小样本匿名对比中，用它画图的总分没有超过不用它。它的价值在审查，不在画图本身。

Beta 类型风险最大

swimlane-beta、block-beta 和 ishikawa-beta 在旧版本上可能无法显示。要跨平台的文档，优先用稳定类型。

请求示例