drawio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io Diagram Skill (Unified)

Draw.io 图表技能（统一版）

Unified draw.io diagram skill. You are responsible for aesthetics, structure, and content — not just mechanically generating XML. Every diagram should look like it was designed by someone who cares about visual communication.

统一的draw.io图表技能。你需要负责美观度、结构和内容——而非机械地生成XML。每一张图表都应看起来出自注重视觉传达的设计者之手。

Philosophy

设计理念

Aesthetics — diagrams should be visually clear, not just technically correct
Structure — logical grouping, meaningful containment, consistent spacing
Content — accurate labels, proper shape choices, meaningful colors

美观性——图表应视觉清晰，而非仅在技术层面正确
结构性——逻辑分组、合理的包含关系、一致的间距
内容性——准确的标签、恰当的形状选择、有意义的配色

Aesthetic principles

美学原则

Color with purpose: same-function elements share colors, different functions get distinct colors
Consistent sizing: elements of the same type get the same dimensions
Meaningful shapes: databases get cylinders, decisions get diamonds, external actors get stick figures
Balanced layout: distribute nodes evenly across the canvas, avoid clusters in one corner with empty space elsewhere
Readable labels: concise text that fits within the shape, no truncation
Consistent spacing: use the rigid grid —
```
x = col * 180 + 40
```
,
```
y = row * 120 + 40
```

配色有目的：功能相同的元素使用相同颜色，不同功能的元素使用区分度高的颜色
尺寸一致：同类元素使用相同尺寸
形状表意：数据库用圆柱体，决策用菱形，外部参与者用简笔画人形
布局均衡：节点均匀分布在画布上，避免一角拥挤而其他区域空白
标签易读：简洁的文本能容纳在形状内，无截断
间距一致：使用固定网格——
```
x = col * 180 + 40
```
，
```
y = row * 120 + 40
```

Workflow

工作流程

Follow this 6-step workflow for every diagram request:

① Receive → ② Read references → ③ Model → ④ Generate → ⑤ Validate → ⑥ Deliver

处理每一个图表请求时，请遵循以下6步流程：

① 接收 → ② 查阅参考资料 → ③ 建模 → ④ 生成 → ⑤ 验证 → ⑥ 交付

Step 1: Receive

步骤1：接收

Identify the request:

Diagram type (flowchart, architecture, ER, sequence, etc.)
Format preference (XML or Mermaid — default to Mermaid for standard types)
Special requirements (specific shapes, colors, export format)

明确请求内容：

图表类型（流程图、架构图、ER图、序列图等）
格式偏好（XML或Mermaid——标准类型默认使用Mermaid）
特殊要求（特定形状、颜色、导出格式）

Step 2: Read references

步骤2：查阅参考资料

Before generating, read the appropriate reference files. All paths are relative to this SKILL.md file.

XML diagrams:
```
references/xml-reference.md
```
Mermaid diagrams:
```
references/mermaid-reference.md
```
Style properties:
```
references/style-reference.md
```

生成前，阅读对应的参考文件。所有路径均相对于本SKILL.md文件。

XML图表：
```
references/xml-reference.md
```
Mermaid图表：
```
references/mermaid-reference.md
```
样式属性：
```
references/style-reference.md
```

Step 3: Model

步骤3：建模

Plan the diagram structure before writing XML:

Identify nodes, edges, and groups
Decide on grouping (swimlanes, containers, or flat)
Assign semantic IDs (see "ID Naming Convention" below)
Choose color assignments from the draw.io palette
Sketch the grid layout mentally

编写XML前规划图表结构：

确定节点、连线和分组
决定分组方式（泳道、容器或平铺）
分配语义化ID（见下文“ID命名规范”）
从draw.io调色板中选择配色
在脑海中勾勒网格布局

Step 4: Generate

步骤4：生成

Produce the diagram. See "Creating a diagram" below for format and backend details.

生成图表。关于格式和后端细节，请参阅下文“创建图表”。

Step 5: Validate (mandatory for XML)

步骤5：验证（XML必填）

Run the validation script after generating XML:

bash

node scripts/validate-mxfile.js <file.drawio>

If validation fails, fix the XML and re-validate. Do not deliver broken XML.

生成XML后运行验证脚本：

bash

node scripts/validate-mxfile.js <file.drawio>

如果验证失败，修复XML后重新验证。不得交付损坏的XML。

Step 6: Deliver

步骤6：交付

Present the result. See "Output format strategy" for delivery mode.

呈现结果。交付方式请参阅“输出格式策略”。

Quick decision guide

快速决策指南

Need	Use
Flowchart, sequence, ER, class, state, Gantt, mindmap, timeline	Mermaid — concise syntax, reliable
Custom positioning, exact colors, containers, layers, multi-layout	XML — full control
AWS/Azure/GCP/network/electrical/P&ID diagrams	XML + search_shapes
Edit an existing diagram	get_diagram → edit_diagram (session mode) or rewrite file (file mode)
Export to PNG/SVG/PDF	draw.io CLI (file mode) or export_diagram (session mode)

需求	使用方式
流程图、序列图、ER图、类图、状态图、甘特图、思维导图、时间线	Mermaid ——语法简洁、可靠
自定义定位、精确配色、容器/图层、多布局	XML ——完全可控
AWS/Azure/GCP/网络/电气/P&ID图表	XML + search_shapes
编辑现有图表	get_diagram → edit_diagram（会话模式）或重写文件（文件模式）
导出为PNG/SVG/PDF	draw.io CLI（文件模式）或export_diagram（会话模式）

Backend detection (run once per conversation)

后端检测（每次会话运行一次）

Check which tools are available and select the backend:

1. Session mode — next-ai-drawio MCP tools available (start_session, create_new_diagram, edit_diagram, get_diagram, export_diagram)
2. Inline mode — mcp-app-server create_diagram / search_shapes available
3. CLI mode — scripts/ available (search-shapes.js, open-drawio.js)
4. File mode — fallback, generate .drawio files via Write tool

If multiple backends are available, prefer session mode for interactive work, inline mode for quick previews, CLI mode for browser-based workflows, and file mode for persistent output.

检查可用工具并选择后端：

1. 会话模式 —— 可使用next-ai-drawio MCP工具（start_session、create_new_diagram、edit_diagram、get_diagram、export_diagram）
2. 内联模式 —— 可使用mcp-app-server的create_diagram / search_shapes
3. CLI模式 —— 可使用scripts/下的工具（search-shapes.js、open-drawio.js）
4. 文件模式 —— 备选方案，通过Write工具生成.drawio文件

如果有多个后端可用，优先选择会话模式进行交互式工作，内联模式用于快速预览，CLI模式用于基于浏览器的工作流，文件模式用于持久化输出。

Creating a diagram

创建图表

Step 1: Choose format

步骤1：选择格式

Default to Mermaid for standard diagram types (flowchart, sequence, ER, class, state, Gantt, mindmap, timeline, pie, quadrant, etc.)
Use XML when the user needs precise layout, custom styles, containers/layers, industry-specific shapes, or when the user explicitly asks for XML
If the user says "mermaid" or "xml" in the command, respect their choice

标准图表类型默认使用Mermaid（流程图、序列图、ER图、类图、状态图、甘特图、思维导图、时间线、饼图、四象限图等）
当用户需要精确布局、自定义样式、容器/图层、行业特定形状，或明确要求XML时，使用XML
如果用户在命令中提到“mermaid”或“xml”，请尊重其选择

Step 2: Generate content

步骤2：生成内容

Mermaid mode

Mermaid模式

Generate valid Mermaid syntax. Key rules:

Pick the correct type keyword:

flowchart

sequenceDiagram

classDiagram

stateDiagram-v2

erDiagram

gantt

mindmap

timeline

pie

quadrantChart

sankey-beta

xychart-beta

block-beta

C4Context

C4Container

C4Component

architecture-beta

radar-beta

packet-beta

venn-beta

treemap-beta

treeView-beta

ishikawa-beta

kanban

zenuml

No trailing punctuation on node IDs. Use brackets for display text:
```
A["User's Account"]
```
One statement per line. Quote labels with special characters
Match label language to user's language

生成有效的Mermaid语法。核心规则：

选择正确的类型关键字：

flowchart

、

sequenceDiagram

、

classDiagram

、

stateDiagram-v2

、

erDiagram

、

gantt

、

mindmap

、

timeline

、

pie

、

quadrantChart

、

sankey-beta

、

xychart-beta

、

block-beta

、

C4Context

C4Container

C4Component

、

architecture-beta

、

radar-beta

、

packet-beta

、

venn-beta

、

treemap-beta

、

treeView-beta

、

ishikawa-beta

、

kanban

、

zenuml

节点ID后无尾随标点。使用括号包裹显示文本：
```
A["User's Account"]
```
每行一个语句。包含特殊字符的标签需加引号
标签语言与用户语言匹配

XML mode

XML模式

Generate mxfile XML. Key rules:

Use the full
```
<mxfile>
```
wrapper (see "XML format" below)
Use the rigid grid:
```
x = col * 180 + 40
```
,
```
y = row * 120 + 40
```
Node sizes: rectangles 140x60, diamonds 140x80, circles 60x60, cylinders 100x70

Every edge must have

<mxGeometry relative="1" as="geometry" />

child

Edge routing is automatic — just declare
```
source
```
and
```
target
```
Use
```
html=1
```
in all cell styles
Use semantic IDs (see "ID Naming Convention")
No XML comments. Escape
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
in attributes

生成mxfile XML。核心规则：

使用完整的
```
<mxfile>
```
包裹（见下文“XML格式”）
使用固定网格：
```
x = col * 180 + 40
```
，
```
y = row * 120 + 40
```
节点尺寸：矩形140x60，菱形140x80，圆形60x60，圆柱体100x70

每条连线必须包含

<mxGeometry relative="1" as="geometry" />

子元素

连线路由自动处理——只需声明
```
source
```
和
```
target
```
所有单元格样式中使用
```
html=1
```
使用语义化ID（见“ID命名规范”）
无XML注释。属性中的
```
&amp;
```
、
```
&lt;
```
、
```
&gt;
```
、
```
&quot;
```
需转义

Step 3: Render or save

步骤3：渲染或保存

Session mode (MCP)

会话模式（MCP）

Call
```
start_session
```
to open browser with draw.io
Call
```
create_new_diagram
```
with the XML
For Mermaid: convert to XML first, then create (session mode only accepts XML)
For editing later: call
```
get_diagram
```
to fetch current state, then
```
edit_diagram
```
with operations

调用
```
start_session
```
在浏览器中打开draw.io
调用
```
create_new_diagram
```
并传入XML
若为Mermaid：先转换为XML，再创建（会话模式仅接受XML）
如需后续编辑：调用
```
get_diagram
```
获取当前状态，再调用
```
edit_diagram
```
并传入操作指令

Inline mode (MCP)

内联模式（MCP）

Call
```
create_diagram
```
with the XML (renders inline in chat)
For shape search: call
```
search_shapes
```
before
```
create_diagram
```
when industry icons are needed

调用
```
create_diagram
```
并传入XML（在聊天中内联渲染）
如需搜索形状：当需要行业图标时，在调用
```
create_diagram
```
前先调用
```
search_shapes
```

CLI mode (scripts)

CLI模式（脚本）

Open in browser:

node scripts/open-drawio.js --xml <file>

--mermaid <file>

Search shapes:

node scripts/search-shapes.js "aws lambda" 10

Validate XML:

node scripts/validate-mxfile.js <file.drawio>

Use the returned
```
style
```
strings directly in XML cells

在浏览器中打开：

node scripts/open-drawio.js --xml <file>

或

--mermaid <file>

搜索形状：

node scripts/search-shapes.js "aws lambda" 10

验证XML：

node scripts/validate-mxfile.js <file.drawio>

将返回的
```
style
```
字符串直接用于XML单元格

File mode (fallback)

文件模式（备选）

If Mermaid: generate XML directly for the same diagram type
Write XML to a
```
.drawio
```
file using the Write tool

Validate:

node scripts/validate-mxfile.js <file.drawio>

— fix errors before delivering

Post-process (optional): if
```
npx @drawio/postprocess
```
is available, run it on the .drawio file. Skip silently if unavailable
If export format requested (png, svg, pdf), use draw.io CLI to export
Open the result for viewing

若为Mermaid：直接生成对应图表类型的XML
使用Write工具将XML写入
```
.drawio
```
文件

验证：

node scripts/validate-mxfile.js <file.drawio>

——交付前修复错误

后处理（可选）：若
```
npx @drawio/postprocess
```
可用，在.drawio文件上运行该命令。若不可用则跳过
若请求导出格式（png、svg、pdf），使用draw.io CLI导出
打开结果进行查看

Editing an existing diagram

编辑现有图表

Session mode (preferred)

会话模式（首选）

Call
```
get_diagram
```
to fetch current XML including any manual edits
Analyze current cell IDs and structure
Call
```
edit_diagram
```
with operations:
- ```
add
```
  : new cell with unique
```
cell_id
```
  and complete
```
new_xml
```
- ```
update
```
  : replace existing cell by
```
cell_id
```
  with updated
```
new_xml
```
- ```
delete
```
  : remove cell by
```
cell_id
```
Repeat as needed — the browser updates in real-time

调用
```
get_diagram
```
获取包含所有手动编辑的当前XML
分析当前单元格ID和结构
调用
```
edit_diagram
```
并传入操作指令：
- ```
add
```
  ：添加带有唯一
```
cell_id
```
  和完整
```
new_xml
```
  的新单元格
- ```
update
```
  ：通过
```
cell_id
```
  替换现有单元格为更新后的
```
new_xml
```
- ```
delete
```
  ：通过
```
cell_id
```
  删除单元格
根据需要重复操作——浏览器会实时更新

File mode

文件模式

Read the existing .drawio file
Modify the XML as needed (add/update/remove cells)
Write the updated XML back to the file

Validate:

node scripts/validate-mxfile.js <file.drawio>

Re-open if needed

读取现有.drawio文件
根据需要修改XML（添加/更新/删除单元格）
将更新后的XML写回文件

验证：

node scripts/validate-mxfile.js <file.drawio>

如需重新打开

Shape search

形状搜索

When to search:

Cloud architecture (AWS, Azure, GCP)
Network topology (Cisco, rack equipment)
P&ID (valves, instruments, vessels)
Electrical/circuit diagrams
Kubernetes resources
BPMN with specific task types

When NOT to search:

Standard diagrams using basic shapes (flowcharts, UML, ERD, org charts, mind maps, wireframes)
User explicitly asks for basic/simple shapes

How to use:

MCP: Call

search_shapes

with

{ query: "keywords", limit: 10 }

CLI:

node scripts/search-shapes.js "aws lambda" 10

Use the returned

style

string directly in the mxCell

style

attribute. Set appropriate

and

from search results.

何时搜索：

云架构（AWS、Azure、GCP）
网络拓扑（思科、机架设备）
P&ID（阀门、仪表、容器）
电气/电路图
Kubernetes资源
带有特定任务类型的BPMN

何时不搜索：

使用基础形状的标准图表（流程图、UML、ERD、组织结构图、思维导图、线框图）
用户明确要求使用基础/简单形状

使用方法：

MCP：调用

search_shapes

并传入

{ query: "关键字", limit: 10 }

CLI：

node scripts/search-shapes.js "aws lambda" 10

将返回的

style

字符串直接用于mxCell的

style

属性。根据搜索结果设置合适的

和

。

Export

导出

Session mode (MCP)

会话模式（MCP）

Call

export_diagram

with

path

(e.g.,

./diagram.drawio

./diagram.png

./diagram.svg

调用

export_diagram

并传入

path

（例如

./diagram.drawio

、

./diagram.png

、

./diagram.svg

）。

File mode (draw.io CLI)

文件模式（draw.io CLI）

Locate the CLI:

Environment	Path
macOS	`/Applications/draw.io.app/Contents/MacOS/draw.io`
Linux	`drawio` (on PATH)
Windows	`"C:\Program Files\draw.io\draw.io.exe"`
WSL2	`/mnt/c/Program Files/draw.io/draw.io.exe`

Detect WSL2:

grep -qi microsoft /proc/version 2>/dev/null

Export command:

bash

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

Key flags:

-x

export,

-f

format (png/svg/pdf),

-e

embed diagram XML,

-b 10

border

After successful export, delete the intermediate

.drawio

file — the exported file contains the full diagram.

定位CLI：

环境	路径
macOS	`/Applications/draw.io.app/Contents/MacOS/draw.io`
Linux	`drawio` （在PATH中）
Windows	`"C:\Program Files\draw.io\draw.io.exe"`
WSL2	`/mnt/c/Program Files/draw.io/draw.io.exe`

检测WSL2：

grep -qi microsoft /proc/version 2>/dev/null

导出命令：

bash

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

核心参数：

-x

导出，

-f

格式（png/svg/pdf），

-e

嵌入图表XML，

-b 10

边框

导出成功后，删除中间的

.drawio

文件——导出的文件包含完整图表。

Opening the result

打开结果

Environment	Command
macOS	`open <file>`
Linux	`xdg-open <file>`
WSL2	`cmd.exe /c start "" "$(wslpath -w <file>)"`
Windows	`start <file>`

环境	命令
macOS	`open <file>`
Linux	`xdg-open <file>`
WSL2	`cmd.exe /c start "" "$(wslpath -w <file>)"`
Windows	`start <file>`

ID naming convention

ID命名规范

Use descriptive, semantic IDs instead of bare numbers. This makes the XML readable, debuggable, and editable.

Pattern:

<domain>__<role>

Examples:

```
user__login-form
```
instead of
```
2
```
```
aws__lambda-order
```
instead of
```
3
```
```
db__primary
```
instead of
```
4
```
```
edge__login-to-validate
```
instead of
```
5
```
```
lane__customer
```
instead of
```
6
```

Rules:

Lowercase with hyphens as separators
Double-underscore
```
__
```
separates domain from role
IDs must be unique within the diagram
The structural cells
```
id="0"
```
and
```
id="1"
```
always keep their numeric IDs

使用描述性的语义化ID而非纯数字。这会让XML更易读、易调试、易编辑。

模式：

<domain>__<role>

示例：

```
user__login-form
```
而非
```
2
```
```
aws__lambda-order
```
而非
```
3
```
```
db__primary
```
而非
```
4
```
```
edge__login-to-validate
```
而非
```
5
```
```
lane__customer
```
而非
```
6
```

规则：

小写，使用连字符分隔
双下划线
```
__
```
分隔领域和角色
图表内的ID必须唯一
结构单元格
```
id="0"
```
和
```
id="1"
```
始终保留其数字ID

HTML entity rules

HTML实体规则

No HTML named entities in
```
value
```
attributes: use
```
→
```
not
```
&rarr;
```
,
```
×
```
not
```
&times;
```
,
```
•
```
not
```
&bull;
```
Only 5 safe XML entities:
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
,
```
&#39;
```
Superscript/subscript: use HTML tags:
```
hv
```
,
```
CO2
```
Named entities cause XML parsing failures in strict parsers — UTF-8 literals are universally safe

value
属性中禁止使用HTML命名实体：使用
```
→
```
而非
```
&rarr;
```
，
```
×
```
而非
```
&times;
```
，
```
•
```
而非
```
&bull;
```
仅使用5种安全的XML实体：
```
&amp;
```
、
```
&lt;
```
、
```
&gt;
```
、
```
&quot;
```
、
```
&#39;
```
上标/下标：使用HTML标签：
```
hv
```
、
```
CO2
```
命名实体会导致严格解析器的XML解析失败——UTF-8字面量是通用安全的

Output format strategy

输出格式策略

User intent	Action
"Draw a flowchart"	Default to Mermaid if backend supports it, XML otherwise
"Architecture with specific layout"	Use XML — full positioning control
"Draw with AWS/GCP shapes"	XML + `search_shapes` first
"Export as PNG"	Generate XML → write .drawio → validate → CLI export
"Edit existing diagram"	Session mode `get_diagram` → `edit_diagram` , or file read+write
"Make it look nice"	Apply color palette, consistent sizing, proper shapes
"View in browser"	`node scripts/open-drawio.js --xml <file>`

用户意图	操作
"绘制流程图"	若后端支持则默认使用Mermaid，否则使用XML
"带有特定布局的架构图"	使用XML——完全控制定位
"使用AWS/GCP形状绘制"	先使用XML + `search_shapes`
"导出为PNG"	生成XML → 写入.drawio → 验证 → CLI导出
"编辑现有图表"	会话模式 `get_diagram` → `edit_diagram` ，或文件读写
"让图表看起来美观"	应用调色板、统一尺寸、恰当形状
"在浏览器中查看"	`node scripts/open-drawio.js --xml <file>`

File naming

文件命名

Descriptive name based on diagram content:
```
login-flow
```
,
```
database-schema
```
Lowercase with hyphens for multi-word names

Export uses double extension:

name.drawio.png

name.drawio.svg

name.drawio.pdf

基于图表内容的描述性名称：
```
login-flow
```
、
```
database-schema
```
多词名称使用小写和连字符

导出使用双扩展名：

name.drawio.png

、

name.drawio.svg

、

name.drawio.pdf

Interaction tone

交互语气

When receiving: "I'll create a [type] diagram with [N] nodes, [brief layout description]."
When generating: generate silently — do not narrate XML construction
When validating: if errors found, fix silently and re-validate. Only mention validation if errors persist
When delivering: "Diagram created: [brief description of what it shows and any design choices]"
When iterating: "Updating the diagram: [describe the specific change]"

接收请求时：“我将创建一张[type]图表，包含[N]个节点，[简要布局描述]。”
生成时：静默生成——不要叙述XML构建过程
验证时：若发现错误，静默修复并重新验证。仅在错误持续存在时提及验证
交付时：“图表已创建：[简要描述图表内容及设计选择]”
迭代时：“正在更新图表：[描述具体变更]”

XML format (mxfile)

XML格式（mxfile）

Every diagram must use the mxfile wrapper:

xml

<mxfile host="Electron" agent="Claude" version="26.0.16">
  <diagram name="描述性名称" id="unique_id">
    <mxGraphModel dx="0" dy="0" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="827" pageHeight="1169"
                  adaptiveColors="auto">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

For MCP session/inline mode, bare

<mxGraphModel>

is also accepted (the server extracts the model internally).

Common shapes:

Rectangle:
```
rounded=1;whiteSpace=wrap;html=1;
```
Diamond:
```
rhombus;whiteSpace=wrap;html=1;
```
Cylinder (DB):
```
shape=cylinder3;whiteSpace=wrap;html=1;
```

Edge:

edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;

每张图表必须使用mxfile包裹：

xml

<mxfile host="Electron" agent="Claude" version="26.0.16">
  <diagram name="描述性名称" id="unique_id">
    <mxGraphModel dx="0" dy="0" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="827" pageHeight="1169"
                  adaptiveColors="auto">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

对于MCP会话/内联模式，也可接受裸

<mxGraphModel>

（服务器会在内部提取模型）。

常见形状：

矩形：
```
rounded=1;whiteSpace=wrap;html=1;
```
菱形：
```
rhombus;whiteSpace=wrap;html=1;
```
圆柱体（数据库）：
```
shape=cylinder3;whiteSpace=wrap;html=1;
```

连线：

edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;

Mermaid format (quick reference)

Mermaid格式（快速参考）

Flowchart:

flowchart TD/LR

, edges

-->

, shapes

[rect]

{diamond}

((circle))

[(cylinder)]

Sequence:

sequenceDiagram

, arrows

->>

-->>

, activate/deactivate, alt/loop/opt blocks Class:

classDiagram

, relations

<|--

*--

o--

-->

ER:

erDiagram

, cardinality

||--o{

, entity blocks State:

stateDiagram-v2

[*]

start/end, nested

state X {}

For complete Mermaid syntax and all 26 diagram types, read

references/mermaid-reference.md

流程图：

flowchart TD/LR

，连线

-->

, 形状

[rect]

{diamond}

((circle))

[(cylinder)]

序列图：

sequenceDiagram

，箭头

->>

-->>

, activate/deactivate, alt/loop/opt块类图：

classDiagram

，关系

<|--

*--

o--

-->

ER图：

erDiagram

，基数

||--o{

, 实体块状态图：

stateDiagram-v2

[*]

开始/结束, 嵌套

state X {}

完整的Mermaid语法及所有26种图表类型，请阅读

references/mermaid-reference.md

。

CRITICAL: XML well-formedness

关键注意事项：XML格式正确性

NEVER include XML comments (

) in output
Escape special characters:
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
Use unique
```
id
```
values for each
```
mxCell
```

Every edge must have

<mxGeometry relative="1" as="geometry" />

child element

Validate after generation:

node scripts/validate-mxfile.js <file.drawio>

输出中绝对不能包含XML注释(

)
转义特殊字符：
```
&amp;
```
,
```
&lt;
```
,
```
&gt;
```
,
```
&quot;
```
为每个
```
mxCell
```
使用唯一的
```
id
```
值

每条连线必须包含

<mxGeometry relative="1" as="geometry" />

子元素

生成后必须验证：

node scripts/validate-mxfile.js <file.drawio>

Troubleshooting

故障排除

Problem	Solution
draw.io CLI not found	Keep .drawio file, tell user to install draw.io desktop app
Export empty/corrupt	Run `validate-mxfile.js` , fix errors, re-export
Blank diagram	Run `validate-mxfile.js` — check for missing root cells, self-closing edges
Edges not rendering	Add `<mxGeometry relative="1" as="geometry" />` to every edge
Mermaid blank	Check type keyword spelling, verify node ID format
Session not available	Fall back to CLI or file mode
search-index.json not found	Run `cd shape-search && npm run generate` , or install from GitHub
Named entities broken	Replace `→` etc. with UTF-8 literals ( `→` )

问题	解决方案
未找到draw.io CLI	保留.drawio文件，告知用户安装draw.io桌面应用
导出为空/损坏	运行 `validate-mxfile.js` ，修复错误后重新导出
图表空白	运行 `validate-mxfile.js` ——检查是否缺少根单元格、自闭合连线
连线未渲染	为每条连线添加 `<mxGeometry relative="1" as="geometry" />`
Mermaid图表空白	检查类型关键字拼写，验证节点ID格式
会话不可用	回退到CLI或文件模式
未找到search-index.json	运行 `cd shape-search && npm run generate` ，或从GitHub安装
命名实体失效	将 `→` 等替换为UTF-8字面量( `→` )