drawio-mcp Mermaid 生成指南：28 种图类型语法、ELK 布局与样式实战

AI 应用MCP 服务交互助手【免费下载链接】drawio-mcp项目地址https://gitcode.com/gh_mirrors/dr/drawio-mcp点击查看免费下载本篇指南以 drawio-mcp 仓库中面向 LLM 的 shared/mermaid-reference.md 为骨架系统讲解在 draw.io 中生成可正确渲染的 Mermaid 图的全部要点从 28 种图类型的头关键字选择、通用语法规则到最常见流程图flowchart的节点形状、边、子图、ELK 分层布局与三种样式方案再到序列图、类图、ER 图、Gantt、C4、看板、ZenUML、Wardley 图等其余各类型的可复制示例。读完本文你将能直接向 drawio-mcp 的open_drawio_mermaid工具或 draw.io 桌面 CLI提交语法正确的 Mermaid 源码并掌握在何时为复杂流程图开启 ELK 布局、何时改用 XML 编写图表的决策依据。一、概览draw.io 的 Mermaid 解析器与 28 种图类型draw.io 内置的 Mermaid 解析器覆盖 28 种图类型头关键字header keyword出现在第一条非指令non-directive行决定解析器选择哪一种图类型。首行关键字拼错产出的将是空白图——这是最常见的失败原因。在 drawio-mcp 中这份参考被直接注入open_drawio_mermaid工具的描述文本。见 mcp-tool-server/src/index.js工具定义明确支持 flowcharts、sequence diagrams、class diagrams、state diagrams、entity relationship diagrams 及更多 Mermaid.js 语法启动时通过双路径查找读取参考文件仓库内shared/mermaid-reference.mdnpm 安装时为本地副本mermaid-reference.md作为单一事实来源拼入工具描述让 LLM 在生成 Mermaid 源码时获得每个图类型的具体语法提示。28 种类型的关键字清单拼写必须精确关键字图类型graph/flowchart流程图classDiagram类图stateDiagram-v2状态图erDiagram实体关系图sequenceDiagram序列图gitGraphGit 分支图journey用户旅程图pie饼图gantt甘特图mindmap思维导图timeline时间线quadrantChart象限图requirementDiagram需求图sankey-beta桑基图xychart-betaXY 折线/柱状图block-beta块图c4Context/C4Container/C4ComponentC4 图architecture-beta架构图radar-beta雷达图packet-beta数据包位图venn-beta韦恩图treemap-beta矩形树图treeView-beta树视图ishikawa-beta石川鱼骨图kanban看板zenumlZenUML 序列图wardley-betaWardley 战略图eventmodeling事件建模完整的 28 种类型规范清单与对话框/ELK 文档以 draw.io 官方维护的规范列表为准本文仅收录当前参考文档覆盖的类型与语法。二、通用规则任何图类型都适用的雷区无论哪种类型以下规则来自 shared/mermaid-reference.md 的 General rules 一节是保证解析不失败的前提仔细挑选类型关键字。上表所列关键字务必原样书写拼写错误如flowchart写成flowchartt只会得到空白图。节点 ID 结尾不要加标点。ID 是标识符myNode、node_1、A——空格、某些上下文中的连字符以及保留字end、class、subgraph都会破坏解析。需要展示的文本放进方括号或引号A[Users Account]。每条语句占一行。语句之间用换行分隔;在 flowcharts 中可作分隔符但并非处处可用。含特殊字符的标签要加引号:、-、括号、非 ASCII 字符。用双引号不要用单引号。标签中的 HTML 只有少数标签可靠br、b、i、u。样式中的颜色用#开头的十六进制绝不用rgb()——这与 shared/style-reference.md 中 XML 样式的颜色约定#RRGGBB十六进制一致。部分类型支持标题块title block位于文档最顶部--- title: My Diagram --- flowchart TD标签语言与用户语言保持一致——用户用德语、法语等书写时图表标签也应使用对应语言而不是机械地沿用英文示例。三、流程图Flowchart最常见类型3.1 最小可运行示例flowchart TD A[Start] -- B{Decision?} B --|Yes| C[Do thing] B --|No| D[Skip] C -- E((End)) D -- E3.2 方向DirectionTD/TB自上而下、BT自下而上、LR从左到右、RL从右到左。3.3 节点形状按括号选择括号写法形状[rect]矩形(rounded)圆角矩形([stadium])跑道形体育场形[[subroutine]]子程序形[(cylinder)]圆柱形数据库((circle))圆形{rhombus}菱形决策{{hexagon}}六边形[/parallelogram/]平行四边形[\parallelogram alt\]反向平行四边形[/trapezoid\]梯形asymmetric]非对称形3.4 边Edges--带箭头---无箭头-.-虚线箭头粗线箭头--双向箭头。行内标签两种写法A -- text -- B或A --|text| B。3.5 子图Subgraphssubgraph Frontend A -- B end子图内部节点自动聚组保留字subgraph/end不能用作节点 ID。四、复杂流程图的 ELK 分层布局4.1 为什么要换 ELKdraw.io 的 Mermaid 解析器自带布局但一旦图具备一定结构复杂度结果就会变得拥挤或失衡。参考文档给出的切换阈值——满足任意一条即应改用 ELK 分层布局与 draw.io 的Arrange ▸ Layout ▸ Vertical/Horizontal Flow同一引擎节点数 ≥ ~20 个或决策菱形{...}形状≥ 3 个或存在任何回边/反馈边指回更早节点的边——例如错误路径循环回重试节点或不同的终点endpoint≥ 3 个。4.2 两种请求方式方式一调用参数postLayout: elk如果所用工具提供该字段。在 drawio-mcp 中open_drawio_mermaid的postLayout参数枚举值正是elk见 mcp-tool-server/src/index.jsdraw.ios native Mermaid parser does its own layout, but it produces cramped or unbalanced output once the diagram has any structural complexity — request elk whenever ANY of these holds: ~20 nodes, OR 3 decision diamonds ...方式二在源码最顶部写入 YAML frontmatter 块。draw.io 无论在哪里转换 Mermaid编辑器、打开链接、桌面 CLI都会识别它--- config: layout: elk --- flowchart TD A[Start] -- B{Retry?}config.layout键可以与title:共存——二者是同一个 frontmatter 块的两个键--- title: My Diagram config: layout: elk --- flowchart TD4.3 源码级实现ELK 选择器是纯文本变换在 drawio-mcp 中Mermaid 的 ELK 选择不是服务端计算而是一次文本变换。规范实现在 shared/mermaid-elk.jswithElkLayout(text)按三种放置规则写入config: { layout: elk }无 frontmatter → 在最顶部补一个最小--- config: layout: elk ---块有 frontmatter 但无config键 → 在收尾---之前追加一个 config 块保留原有键已有config块 → 把layout: elk作为第一个子键插入缩进对齐已有子键空 config 块则缩进一层更深。若源码已显式声明 layoutconfig.layout或携带旧式指令%%{init: {flowchart: {defaultRenderer: elk}}}%%则原样返回、不重复写入——这保证了幂等与向后兼容。mermaidDiagramType(text)是 drawio-devEditorUi.getMermaidDiagramType的逐字移植跳过空行与%%注释再跳过 frontmatter 块取第一条内容行的首个单词小写作为类型。isFlowchartSource(text)只对flowchart与其旧拼写graph返回 true——ELK 布局仅对流程图有意义序列图、类图、ER、gantt 等自带布局并忽略该设置。这些行为在 mcp-tool-server/test/mermaid-elk.test.js 中逐条验证包括无 frontmatter 生成最小块、已有 title 键时保留、已有 config 块时插入子键、CRLF frontmatter 不重复、已选布局的源码原样不动以及写出的选择器能触发 draw.io 的 ELK 触发器firesDrawioTrigger模拟 drawio-dev 的EditorUi.isMermaidElkFlowchart判定。4.4 工具侧的接线与兼容性服务端在 mcp-tool-server/src/index.js 中处理先isFlowchartSource(content)判断是流程图才调用withElkLayout非流程图则回注一条 postLayout only applies to Mermaid flowcharts 说明。draw.io 在#createtype:mermaid链接背后转换 Mermaid 时自行执行 ELK 布局新构建走 drawio-mermaid 的 ELK 选项旧构建通过EditorUi.isMermaidElkFlowchart/applyMermaidElkPostPass重跑ElkLayout。工具侧会为 Mermaid 的#create链接携带MERMAID_DEFAULTS_VERSION 12mcp-tool-server/src/index.jsdraw.io 用 Mermaid 12 的默认值ELK 布局、redux-color主题、多数类型neo外观转换并写入图中保证后续编辑保持该外观旧版 draw.io 会忽略该版本号。app 服务器端的resolvePostLayoutmcp-app-server/src/shared.js则体现了方向取自流程图代码的规则对 Mermaid通过isMermaidHorizontalFlowchart从flowchart TD/TB与LR/RL判断水平/垂直而非使用direction参数——即流程方向永远跟随流程图代码这与参考文档的结论完全一致。4.5 何时不需要 ELK非 flowchart 类型sequence、class、ER、gantt 等自行布局忽略该设置简单流程图线性链、节点 20、无分支或回边也不需要——原生布局已足够。五、流程图样式与颜色三种方案参考文档强调三种方案任选其一不要对同一节点混用。方案一节点级行内样式styleflowchart LR A[Start] -- B[End] style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff style B fill:#bbf,stroke:#f66,stroke-dasharray:5 5方案二可复用类classDef:::flowchart LR A:::happy -- B:::sad classDef happy fill:#dfd,stroke:#0a0 classDef sad fill:#fdd,stroke:#a00或批量应用到多个节点class A,B,C happy。方案三边样式linkStylelinkStyle 0 stroke:#f00,stroke-width:3px linkStyle default stroke:#9990表示按定义顺序的第一条边default作用于所有未设置样式的边。可用的样式属性fill、stroke、stroke-width、stroke-dasharray、color文字颜色。注意全部使用十六进制色值而非rgb()——这也是 draw.io 全系含 XML 样式见 shared/style-reference.md 的fillColor/strokeColor/fontColor等属性的统一约定。六、序列图Sequence diagramsequenceDiagram participant U as User participant S as Server U-S: Request S--U: Response Note right of S: Logged箭头-无箭头头、-实线箭头、--虚线箭头、-xX 形末端、--x虚线 X 形末端。激活/释放activate S/deactivate S或缩写S-S2: call/S2---S: return激活、-释放。消息块alt/else/end、opt/end、loop/end、par/and/end、critical/option/end。注释Note left of A、Note over A,B: text。头部后加可选的autonumber可为消息自动编号。七、类图Class diagramclassDiagram class Animal { String name int age eat() void } class Dog Animal |-- Dog : inherits Dog 1 -- * Bone : has关系|--继承、*--组合、o--聚合、--关联、..依赖、..|实现、--双向。可见性公有、-私有、#受保护、~包内。注解interface、abstract、enumeration写在类块内或用Animal interface形式标注在类名行。多重性箭头两侧的引号字符串1、0..*、*。八、状态图State diagramstateDiagram-v2 [*] -- Idle Idle -- Running : start Running -- Idle : stop Running -- [*] state Running { [*] -- Working Working -- Waiting : block Waiting -- Working : unblock }必须用stateDiagram-v2stateDiagramv1是旧版。[*]视方向不同代表起点source或终点target。state X { ... }嵌套复合状态state fork1 fork、join、choice标记汇合/分支节点。转移标签写法A -- B : event [guard] / action。九、ER 图Entity relationship diagramerDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER { string name string email PK }基数符号|o零或一、||恰好一、}o零或多、}|一或多两侧镜像书写如||--o{。属性块列出type name [PK|FK|UK]后接可选的双引号注释。实体名惯例为大写UPPERCASE。十、其余图类型速查10.1 用户旅程图Journeyjourney title Morning routine section Wake up Coffee: 5: Me Read news: 3: Me section Commute Drive: 2: Me, Traffic每条任务Name: score(1-5): Actor[, Actor...]section标题对任务分组。10.2 饼图Piepie showData title Browser share Chrome : 60 Firefox : 20 Safari : 20showData可选渲染具体数值标签加引号冒号后跟数值。10.3 甘特图Ganttgantt title Project timeline dateFormat YYYY-MM-DD section Phase 1 Design : a1, 2025-01-01, 7d Build : after a1, 14d section Phase 2 Test : 2025-01-25, 5ddateFormat必填。任务行Name : [id,] [after id | YYYY-MM-DD], duration[d/w]时长单位d天 /w周。状态标签done、active、crit放在 id 之前如crit a1。10.4 Git 分支图GitgraphgitGraph commit branch develop checkout develop commit commit checkout main merge develop命令commit [id: x] [tag: v1]、branch name、checkout name、merge name、cherry-pick id: x。10.5 思维导图Mindmapmindmap root((Project)) Frontend React CSS Backend Node DB缩进2 空格递增定义层级。根节点形状((circle))、[rect]、(rounded)、))cloud((、)hexagon(、{{hexagon}}。无显式边——层级由嵌套隐含。10.6 时间线Timelinetimeline title Company history section 2020s 2021 : Founded 2022 : Series A : Launched product section 2030s 2030 : IPO冒号分隔年份/标签同一年份下的多个:行添加子事件。10.7 象限图Quadrant chartquadrantChart title Reach vs Engagement x-axis Low -- High y-axis Low -- High quadrant-1 Stars quadrant-2 Question Marks quadrant-3 Dogs quadrant-4 Cash Cows Campaign A: [0.3, 0.6] Campaign B: [0.75, 0.85]数据点坐标为[0..1, 0..1]区间内的浮点数。10.8 需求图Requirement diagramrequirementDiagram requirement req1 { id: 1 text: The system shall... risk: high verifymethod: test } element user_story { type: story } user_story - satisfies - req1需求类型requirement、functionalRequirement、performanceRequirement、interfaceRequirement、physicalRequirement、designConstraint。关系contains、copies、derives、satisfies、verifies、refines、traces。10.9 桑基图Sankeysankey-beta Source,Intermediate,10 Source,Direct,5 Intermediate,Sink,10CSV 风格source,target,value无表头不支持title需用 frontmatter。10.10 XY 图xychart-betaxychart-beta title Revenue x-axis [jan, feb, mar, apr] y-axis USD 0 -- 10000 bar [2500, 5000, 7500, 9000] line [3000, 4500, 6500, 8500]bar [...]与line [...]可叠加顺序决定覆盖层级后写的覆盖在先写的之上。10.11 块图block-betablock-beta columns 3 A B C D[Wide]:2 E A -- Dcolumns N设定网格宽度Name:N横跨 N 列边沿用流程图箭头语法。10.12 C4 图C4Context Person(user, User) System(app, App, Does things) Rel(user, app, Uses)变体C4Context、C4Container、C4Component、C4Dynamic、C4Deployment。元素辅助函数Person、System、System_Ext、Container、ComponentDb、Boundary(id, label, type)等参数按位置传递(id, label, [type/tech], [description])。UpdateElementStyle(tag, $bgColor#…)与AddElementTag微调外观。10.13 架构图architecture-betaarchitecture-beta group cloud(cloud)[Cloud] service api(server)[API] in cloud service db(database)[DB] in cloud api:R -- L:db内置图标cloud、server、database、disk、internet。边端点用后缀:T、:B、:L、:R选择连接侧。group id(icon)[Label]后服务用in groupId放入分组。10.14 雷达图radar-betaradar-beta title Skills axis js[JS], py[Python], go[Go] curve alice[Alice]{80, 60, 70} curve bob[Bob]{50, 90, 65}坐标轴与曲线按位置对齐——按轴顺序列出数值取值 0–100。10.15 数据包位图packet-betapacket-beta 0-15: Source Port 16-31: Dest Port 32-63: Seq Numberstart-end表示位区间或单比特N标题需用 frontmatter。10.16 韦恩图venn-betavenn-beta set A [Set A] set B [Set B] union A,B text A [only A] text A,B [shared]需要为每个计划标注区域的union组合定义text A,B [...]将文本放入交集区域。10.17 矩形树图treemap-betatreemap-beta Category Leaf 1: 40 Leaf 2: 60数值表示面积权重缩进2 个以上空格表达层级。10.18 树视图treeView-betatreeView-beta Root Child 1 Grandchild Child 2纯缩进层级无数值。10.19 石川图 / 鱼骨图ishikawa-betaishikawa-beta Main Problem Category Cause Sub-cause Another Category Cause头部之后第一行是问题本身顶层缩进为类别Materials、Methods、Machinery 等——按需命名即可类别下再缩进写原因。10.20 看板kanbankanban todo[To Do] task1[Write spec]{ assigned: Alice, priority: High } doing[In progress] task2[Build feature] done[Done]列是 0 缩进的id[Label]卡片是列内id[Label]{ metadata }。元数据键assigned、priority取值Very Low/Low/Medium/High/Very High、ticket。10.21 ZenUML 序列图zenuml Actor User Boundary Web Control Service User - Web: request Web - Service: process() Service - Web: result参与者角色Actor、Boundary、Control、Entity、Database。消息用-加冒号分隔标签。支持if/else、while、par等与序列图类似的块结构。10.22 Wardley 战略图wardley-betawardley-beta title Tea Shop anchor Business [0.95, 0.63] component Cup of Tea [0.79, 0.61] component Kettle [0.43, 0.35] (inertia) Business - Cup of Tea Cup of Tea - Kettle evolve Kettle 0.62头关键字wardley或wardley-betatitle可选。anchor/component Name [visibility, evolution]——坐标为[0..1, 0..1]y 为价值链可见度x 为从 Genesis 到 Commodity 的演化阶段。组件演化标记写在括号里(inertia)、(build)、(buy)、(outsource)、(market)。连接A - B表示依赖A B表示流动。evolve Name x添加演化目标evolution Genesis - Custom - Product - Commodity重命名 x 轴阶段。附加元素note text [x,y]、annotation N,[x,y] text、accelerator/deaccelerator text [x,y]。10.23 事件建模Event Modelingeventmodeling tf 01 ui CartUI tf 02 cmd AddItem tf 03 evt ItemAdded tf 04 rmo Cart每条tf id type Name是一个时间帧列。类型ui/pcr处理器、cmd/command、rmo/readmodel、evt/event——分别落在 UI/Automation、Command/Read-Model 与 Events 泳道上。用-连线帧tf 04 evt ItemChanged - 02 - 03将帧 04 连回 02 与 03。Namespace.Name把帧分组为切片如Order.ChangeOrder。data id { ... }块附带载荷行内用[[id]]引用tf 02 cmd AddItem [[AddItem01]]。十一、何时优先用 XML 而不是 Mermaid参考文档明确了 Mermaid 力所不及、应改用 XML 的场景需要精确坐标 / 自定义位置需要 draw.io 原生形状库AWS、Azure、GCP、PID、Cisco、电气符号混合多个形状库或复杂的多层图需要对每个元素做大量颜色变体精确着色——Mermaid 的样式能实现但规模一大XML 更易推理维护。这一点在仓库中得到了呼应shared/xml-reference.md 的postLayout一节指出流程图、状态图、决策树、管道等方向性/层级图应该很少手写为 XML——优先 Mermaid插件技能 plugins/claude-code/skills/drawio/SKILL.md 也给出了同样的决策表标准类型优先写 Mermaid解析器自动布局自定义样式、精确手摆、专用形状库AWS、Azure、网络、UML 细节或未安装桌面 CLI 时才走 XML。默认决策上述标准类型一律使用 Mermaid只有 Mermaid 语法确实无法表达需求时才转向 XML。十二、结语与仓库导航本文覆盖了 shared/mermaid-reference.md 的全部内容并以仓库源码佐证了关键机制。想要继续深入可以在当前仓库中按需查阅语法参考本体shared/mermaid-reference.md、shared/xml-reference.md、shared/style-reference.mdELK 选择器实现与测试shared/mermaid-elk.js、mcp-tool-server/test/mermaid-elk.test.js工具参数定义与处理流程mcp-tool-server/src/index.js、mcp-tool-server/AGENTS.mdELK 引擎桥接mcp-tool-server/src/elk-engine.js浏览器端方向解析mcp-app-server/src/shared.js命令行转换实操桌面 CLI 将 Mermaid 转为 .drawioplugins/claude-code/skills/drawio/SKILL.md记住三条最重要的口诀头关键字拼写精确决定成败复杂流程图≥ ~20 节点 / ≥ 3 决策菱形 / 回边 / ≥ 3 终点用postLayout: elk或 frontmatterconfig: { layout: elk }换取分层布局样式颜色一律十六进制、标签特殊字符一律双引号。遵循本文的规则你生成的 Mermaid 在 draw.io 中即可稳定、正确地渲染。赞分享AI 应用MCP 服务交互助手【免费下载链接】drawio-mcp项目地址https://gitcode.com/gh_mirrors/dr/drawio-mcp点击查看免费下载相关推荐drawio-mcp 的 Codex drawio 技能全解用 Mermaid 或 XML 生成原生 .drawio 图表、ELK 自动布局与多格式导出drawio mcp 的 Codex drawio 技能全解用 Mermaid 或 XML 生成原生 .drawio 图表、ELK 自动布局与多格式导出 本文AI 应用MCP 服务交互助手drawio-skill Mermaid 写作指南从 .mmd 文本到可编辑原生 .drawio 的两步转换与 ELK 布局drawio skill Mermaid 写作指南从 .mmd 文本到可编辑原生 .drawio 的两步转换与 ELK 布局 本指南聚焦 drawio skiAI 技能数据可视化diagram-design 布局语法扩展实录解读 ADR 0007 中 28 → 38 的十种新图形类型diagram design 布局语法扩展实录解读 ADR 0007 中 28 → 38 的十种新图形类型 本仓库 diagram design 是一个为AI 技能数据可视化上一篇CardSlider终极指南打造专业级iOS卡片滑动界面的完整方案下一篇douyin-downloader贴个链接批量存下无水印作品创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考