企业官网建设流程全解析

• AI 应用
• 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.md，npm 安装时为本地副本mermaid-reference.md），作为单一事实来源拼入工具描述，让 LLM 在生成 Mermaid 源码时获得每个图类型的具体语法提示。

28 种类型的关键字清单（拼写必须精确）：

（完整的 28 种类型规范清单与对话框/ELK 文档以 draw.io 官方维护的规范列表为准，本文仅收录当前参考文档覆盖的类型与语法。）

二、通用规则：任何图类型都适用的雷区

无论哪种类型，以下规则来自 shared/mermaid-reference.md 的 "General rules" 一节，是保证解析不失败的前提：

1. 仔细挑选类型关键字。上表所列关键字务必原样书写；拼写错误（如flowchart写成flowchartt）只会得到空白图。
2. 节点 ID 结尾不要加标点。ID 是标识符（myNode、node_1、A）——空格、某些上下文中的连字符以及保留字（end、class、subgraph）都会破坏解析。需要展示的文本放进方括号或引号：A["User's Account"]。
3. 每条语句占一行。语句之间用换行分隔；;在 flowcharts 中可作分隔符，但并非处处可用。
4. 含特殊字符的标签要加引号（:、-、括号、非 ASCII 字符）。用双引号"，不要用单引号'。
5. 标签中的 HTML 只有少数标签可靠：<br>、<b>、<i>、<u>。样式中的颜色用#开头的十六进制，绝不用rgb()——这与 shared/style-reference.md 中 XML 样式的颜色约定（#RRGGBB十六进制）一致。
6. 部分类型支持标题块（title block），位于文档最顶部：

   --- title: My Diagram --- flowchart TD

7. 标签语言与用户语言保持一致——用户用德语、法语等书写时，图表标签也应使用对应语言，而不是机械地沿用英文示例。

三、流程图（Flowchart，最常见类型）

3.1 最小可运行示例

flowchart TD A[Start] --> B{Decision?} B -->|Yes| C[Do thing] B -->|No| D[Skip] C --> E((End)) D --> E

3.2 方向（Direction）

TD/TB（自上而下）、BT（自下而上）、LR（从左到右）、RL（从右到左）。

3.3 节点形状（按括号选择）

3.4 边（Edges）

• -->带箭头；---无箭头；-.->虚线箭头；==>粗线箭头；<-->双向箭头。
• 行内标签两种写法：A -- text --> B或A -->|text| B。

3.5 子图（Subgraphs）

subgraph Frontend A --> B end

子图内部节点自动聚组；保留字subgraph/end不能用作节点 ID。

四、复杂流程图的 ELK 分层布局

4.1 为什么要换 ELK

draw.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.js：

"draw.io's 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 TD

4.3 源码级实现：ELK 选择器是纯文本变换

在 drawio-mcp 中，Mermaid 的 ELK 选择不是服务端计算，而是一次文本变换。规范实现在 shared/mermaid-elk.js：

• withElkLayout(text)按三种放置规则写入config: { layout: elk }：
  • 无 frontmatter → 在最顶部补一个最小--- config: layout: elk ---块；
  • 有 frontmatter 但无config键 → 在收尾---之前追加一个 config 块，保留原有键；
  • 已有config块 → 把layout: elk作为第一个子键插入，缩进对齐已有子键（空 config 块则缩进一层更深）。
  • 若源码已显式声明 layout（config.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 在#create=type:mermaid链接背后转换 Mermaid 时自行执行 ELK 布局（新构建走 drawio-mermaid 的 ELK 选项，旧构建通过EditorUi.isMermaidElkFlowchart/applyMermaidElkPostPass重跑ElkLayout）。
• 工具侧会为 Mermaid 的#create=链接携带MERMAID_DEFAULTS_VERSION = "12"（mcp-tool-server/src/index.js）：draw.io 用 Mermaid 12 的默认值（ELK 布局、redux-color主题、多数类型neo外观）转换并写入图中，保证后续编辑保持该外观；旧版 draw.io 会忽略该版本号。
• app 服务器端的resolvePostLayout（mcp-app-server/src/shared.js）则体现了"方向取自流程图代码"的规则：对 Mermaid，通过isMermaidHorizontalFlowchart从flowchart TD/TB与LR/RL判断水平/垂直，而非使用direction参数——即流程方向永远跟随流程图代码，这与参考文档的结论完全一致。

4.5 何时不需要 ELK

• 非 flowchart 类型（sequence、class、ER、gantt 等）自行布局，忽略该设置；
• 简单流程图（线性链、节点 < 20、无分支或回边）也不需要——原生布局已足够。

五、流程图样式与颜色：三种方案

参考文档强调：三种方案任选其一，不要对同一节点混用。

方案一：节点级行内样式（style）

flowchart 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。

方案三：边样式（linkStyle）

linkStyle 0 stroke:#f00,stroke-width:3px linkStyle default stroke:#999

• 0表示按定义顺序的第一条边；default作用于所有未设置样式的边。

可用的样式属性：fill、stroke、stroke-width、stroke-dasharray、color（文字颜色）。注意全部使用十六进制色值而非rgb()——这也是 draw.io 全系（含 XML 样式，见 shared/style-reference.md 的fillColor/strokeColor/fontColor等属性）的统一约定。

六、序列图（Sequence diagram）

sequenceDiagram participant U as User participant S as Server U->>S: Request S-->>U: Response Note right of S: Logged

• 箭头：->（无箭头头）、->>（实线箭头）、-->>（虚线箭头）、-x（X 形末端）、--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 diagram）

classDiagram 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 diagram）

stateDiagram-v2 [*] --> Idle Idle --> Running : start Running --> Idle : stop Running --> [*] state Running { [*] --> Working Working --> Waiting : block Waiting --> Working : unblock }

• 必须用stateDiagram-v2，stateDiagram（v1）是旧版。
• [*]视方向不同代表起点（source）或终点（target）。
• state X { ... }嵌套复合状态；state fork1 <<fork>>、<<join>>、<<choice>>标记汇合/分支节点。
• 转移标签写法：A --> B : event [guard] / action。

九、ER 图（Entity relationship diagram）

erDiagram 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 用户旅程图（Journey）

journey 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 饼图（Pie）

pie showData title Browser share "Chrome" : 60 "Firefox" : 20 "Safari" : 20

showData可选（渲染具体数值）；标签加引号，冒号后跟数值。

10.3 甘特图（Gantt）

gantt 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, 5d

• dateFormat必填。
• 任务行：Name : [id,] [after id | YYYY-MM-DD], duration[d/w]（时长单位d天 /w周）。
• 状态标签：done、active、crit放在 id 之前（如crit a1）。

10.4 Git 分支图（Gitgraph）

gitGraph 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 思维导图（Mindmap）

mindmap root((Project)) Frontend React CSS Backend Node DB

• 缩进（2 空格递增）定义层级。
• 根节点形状：((circle))、[rect]、(rounded)、))cloud((、)hexagon(、{{hexagon}}。
• 无显式边——层级由嵌套隐含。

10.6 时间线（Timeline）

timeline title Company history section 2020s 2021 : Founded 2022 : Series A : Launched product section 2030s 2030 : IPO

冒号分隔年份/标签；同一年份下的多个:行添加子事件。

10.7 象限图（Quadrant chart）

quadrantChart 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 diagram）

requirementDiagram 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 桑基图（Sankey）

sankey-beta Source,Intermediate,10 Source,Direct,5 Intermediate,Sink,10

CSV 风格：source,target,value；无表头；不支持title（需用 frontmatter）。

10.10 XY 图（xychart-beta）

xychart-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-beta）

block-beta columns 3 A B C D["Wide"]:2 E A --> D

columns 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-beta）

architecture-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-beta）

radar-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-beta）

packet-beta 0-15: "Source Port" 16-31: "Dest Port" 32-63: "Seq Number"

start-end表示位区间，或单比特N；标题需用 frontmatter。

10.16 韦恩图（venn-beta）

venn-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-beta）

treemap-beta "Category" "Leaf 1": 40 "Leaf 2": 60

数值表示面积权重；缩进（2 个以上空格）表达层级。

10.18 树视图（treeView-beta）

treeView-beta "Root" "Child 1" "Grandchild" "Child 2"

纯缩进层级，无数值。

10.19 石川图 / 鱼骨图（ishikawa-beta）

ishikawa-beta Main Problem Category Cause Sub-cause Another Category Cause

头部之后第一行是问题本身；顶层缩进为类别（Materials、Methods、Machinery 等——按需命名即可），类别下再缩进写原因。

10.20 看板（kanban）

kanban 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-beta）

wardley-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-beta；title可选。
• 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 Modeling）

eventmodeling 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、P&ID、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.md
• ELK 选择器实现与测试：shared/mermaid-elk.js、mcp-tool-server/test/mermaid-elk.test.js
• 工具参数定义与处理流程：mcp-tool-server/src/index.js、mcp-tool-server/AGENTS.md
• ELK 引擎桥接：mcp-tool-server/src/elk-engine.js
• 浏览器端方向解析：mcp-app-server/src/shared.js
• 命令行转换实操（桌面 CLI 将 Mermaid 转为 .drawio）：plugins/claude-code/skills/drawio/SKILL.md

记住三条最重要的口诀：头关键字拼写精确决定成败；复杂流程图（≥ ~20 节点 / ≥ 3 决策菱形 / 回边 / ≥ 3 终点）用postLayout: "elk"或 frontmatterconfig: { layout: elk }换取分层布局；样式颜色一律十六进制、标签特殊字符一律双引号。遵循本文的规则，你生成的 Mermaid 在 draw.io 中即可稳定、正确地渲染。

• AI 应用
• MCP 服务
• 交互助手