Drawio

Draw.io Diagramming Skill

核心功能: 通过MCP协议程序化控制Draw.io，实现架构图、流程图、系统设计图的自动生成和管理

禁止使用 Emoji 图标

核心原则: 生成的图表必须保持专业、简洁，避免 AI 生成痕迹

规则

1. 文本内容禁止 emoji: 所有形状的 text 参数中不得包含任何 emoji 字符
2. 标题禁止 emoji: 图表标题、区域标题、组件名称均不使用 emoji
3. 注释禁止 emoji: 连线标签、说明文字不使用 emoji

正确示例

# 正确 - 纯文本
text: "API Gateway"
text: "订单服务"
text: "用户认证 | 权限管理"
text: "数据库<br>MySQL"

# 错误 - 包含 emoji
text: "🔐 API Gateway"
text: "📦 订单服务"
text: "🛡️ 用户认证"

替代方案

• 使用文字符号: | · - > 代替装饰性 emoji
• 使用层级缩进: <br> 换行分隔功能点
• 使用颜色区分: 通过 fillColor 区分组件类型，而非 emoji

禁止嵌套文本框

这是最重要的规则，必须严格遵守！

错误模式（绝对禁止）

创建空的形状，然后在上面叠加独立的文本框：

<!-- 错误：空矩形 + 独立文本框 -->
<mxCell id="data-format" value="" style="rounded=1;..." />
<mxCell id="df-title" value="开放表格式" style="text;..." />
<mxCell id="df-content" value="详细内容..." style="text;..." />

正确模式（必须使用）

文本直接设置在形状的 value 属性或 text 参数中：

<!-- 正确：文本直接在 value 属性 -->
<mxCell id="data-format" value="开放表格式&lt;br&gt;详细内容..." style="rounded=1;..." />

实际操作规则

1. 调用 add-rectangle 时：必须设置 text 参数，不要创建空矩形
2. 调用 add-cell-of-shape 时：必须设置 text 参数
3. 多行文本：使用 <br> 标签，不要创建多个文本框
4. 绝不单独创建 style="text;..." 的文本框来标注形状

正确示例

# 单行文本
add-rectangle:
  x: 100, y: 100
  width: 200, height: 80
  text: "API Gateway"
  style: "rounded=1;fillColor=#667eea;fontColor=#ffffff;"

# 多行文本 - 使用 <br> 标签
add-rectangle:
  x: 100, y: 200
  width: 200, height: 100
  text: "数据服务<br>- 数据存储<br>- 数据查询<br>- 数据分析"
  style: "rounded=1;fillColor=#4caf50;fontColor=#ffffff;"

适用场景

• 系统架构设计: 生成微服务架构、云架构、网络拓扑图
• 流程图设计: 业务流程、数据流、工作流可视化
• 技术文档: 为代码库自动生成架构图、组件关系图
• 图表编辑: 程序化添加、修改、删除图表元素

快速开始

1. 安装浏览器扩展（必需）

Chrome用户:

1. 访问 Chrome Web Store
2. 搜索 "Draw.io MCP Extension"
3. 点击 "Add to Chrome"

Firefox用户:

1. 访问 Firefox Add-ons
2. 搜索 "Draw.io MCP Extension"
3. 点击 "Add to Firefox"

验证安装:

• 打开 https://app.diagrams.net
• 扩展图标应显示绿色信号（表示连接正常）
• 如果显示红色，刷新页面或重启浏览器

2. 验证MCP连接

# 检查MCP服务器状态
codex mcp list

# 预期输出：
# drawio: npx -y drawio-mcp-server - ✓ Connected

如果显示 ✗ Failed to connect:

• 确保浏览器扩展已安装
• 打开 Draw.io 网页版（https://app.diagrams.net）
• 确保扩展显示绿色连接状态
• 重启Codex会话

可用工具 (9个)

检查工具 (5个)

1. get-selected-cell

获取当前选中单元格的属性信息

使用示例:

"查看我选中的这个矩形的属性"
"获取当前选中图形的样式信息"

2. get-shape-categories

检索Draw.io所有可用的形状类别

使用示例:

"列出所有可用的形状分类"
"我想看看有哪些AWS图标可以用"

3. get-shapes-in-category

按类别查询特定形状列表

参数: category - 形状类别名称

使用示例:

"显示AWS类别下的所有形状"
"列出流程图分类的所有图形"

4. get-shape-by-name

按名称查找特定形状的详细信息

参数: shapeName - 形状的精确名称

使用示例:

"查找名为'Database'的形状"
"获取AWS S3图标的信息"

5. list-paged-model

分页查看图表中的所有单元格和连线

参数:

• page - 页码（默认: 0）
• pageSize - 每页数量（默认: 10）

使用示例:

"显示当前图表的所有元素"
"列出图表中的所有连接线"

修改工具 (4个)

1. add-rectangle

创建矩形图形

参数:

• x, y - 位置坐标
• width, height - 尺寸
• text - 显示文本 [必须设置，禁止创建空矩形]
• style - 样式定制（可选）

[重要规则]:

• 必须在创建矩形时直接设置 text 参数
• 禁止先创建空矩形再添加文本框
• 多行文本使用 <br> 标签："标题<br>详细内容"

使用示例:

"在(100, 100)位置添加一个200x80的矩形，文本为'API Gateway'"
"创建一个蓝色矩形，显示'Database'文字"

多行文本示例:

text = "服务名称<br>功能1<br>功能2<br>功能3"

样式参数:

style = "fillColor=#1ba1e2;strokeColor=#006EAF;fontColor=#ffffff;rounded=1;"

2. add-edge

连接两个图形单元格

参数:

• sourceId - 起点单元格ID
• targetId - 终点单元格ID
• edgeStyle - 连线样式（可选）

使用示例:

"连接单元格A和单元格B"
"在API和Database之间添加箭头连线"

样式参数:

edgeStyle = "edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;exitX=1;exitY=0.5;entryX=0;entryY=0.5;"

3. delete-cell-by-id

删除指定ID的单元格

参数: cellId - 要删除的单元格ID

使用示例:

"删除ID为'cell-123'的图形"
"移除这个矩形"

4. add-cell-of-shape

从形状库添加特定类型的图形

参数:

• shapeName - 形状名称
• x, y - 位置
• text - 显示文本 [强烈建议设置，避免创建无标签图形]

[重要规则]:

• 必须在创建形状时直接设置 text 参数
• 禁止先创建空形状再叠加文本框

使用示例:

"添加一个AWS Lambda图标在(200, 150)位置，文本为'处理函数'"
"在中心位置放置一个数据库图标，标注'用户数据'"

最佳实践

0. 文本设置原则（最重要）

核心规则:
  [正确]: 创建形状时直接设置 text 参数
  [错误]: 先创建空形状，再叠加独立文本框

多行文本处理:
  [正确]: text = "标题<br>内容1<br>内容2"
  [错误]: 创建多个 text 类型的 mxCell 覆盖在形状上

复杂布局处理:
  [正确]: 一个形状包含所有相关文本（用<br>分隔）
  [错误]: 一个空形状 + 多个独立文本框

唯一例外:
  - 连线上的标签（edgeLabel）可以作为独立元素
  - 这是 Draw.io 的标准做法

1. 架构图生成工作流

Step 1 - 规划布局:
  - 确定图表类型（架构图、流程图、时序图）
  - 设计图形位置和层次关系

Step 2 - 创建主要组件:
  - 使用add-rectangle或add-cell-of-shape添加核心组件
  - [重要] 必须在创建时设置 text 参数，包含所有需要显示的文本
  - 多行内容使用 <br> 标签分隔

Step 3 - 建立连接:
  - 使用add-edge连接相关组件
  - 设置箭头方向表示数据流向

Step 4 - 样式美化:
  - 统一配色方案（使用fillColor、strokeColor）
  - 添加圆角（rounded=1）提升视觉效果
  - 使用不同颜色区分组件类型

2. 增量式图表构建

不要一次性生成完整图表，而是:
  1. 先创建核心组件（1-3个）
  2. 验证位置和样式
  3. 逐步添加次要组件
  4. 最后添加连接线和注释

优势:
  - 更容易调试和修改
  - 用户可以实时查看进度
  - 减少错误和返工

3. 坐标和布局建议

位置规划:
  - 起始点: (50, 50)
  - 组件间距: 水平150-200px，垂直100-150px
  - 层次结构: 从上到下或从左到右

尺寸标准:
  - 小图标: 60x60
  - 标准矩形: 120x60
  - 大容器: 200x100

现代化设计系统（必须遵循）

设计原则

核心理念:
  - 简洁现代: 避免过度装饰，突出信息层次
  - 视觉一致: 统一配色、字体、间距
  - 层次分明: 通过颜色、大小、阴影区分层级
  - 专业美观: 使用柔和渐变、适当阴影、圆角设计

现代配色方案（强制使用）

主色调系统（选择一个作为主题色）:

蓝紫渐变（科技感，推荐）:
  - 主色: #667eea (紫蓝)
  - 辅色: #764ba2 (深紫)
  - 浅色背景: #f5f7fa
  - 文字: #2d3436 (深灰)

清新蓝（企业风）:
  - 主色: #0984e3 (蓝)
  - 辅色: #74b9ff (浅蓝)
  - 浅色背景: #f8f9fa
  - 文字: #2d3436

翠绿色（数据/环保）:
  - 主色: #00b894 (翠绿)
  - 辅色: #55efc4 (浅绿)
  - 浅色背景: #f0fff4
  - 文字: #2d3436

功能色（固定）:
  - 成功/数据库: #00b894 / #55efc4
  - 警告/队列: #fdcb6e / #ffeaa7
  - 错误/重要: #d63031 / #ff7675
  - 信息/服务: #0984e3 / #74b9ff
  - 中性/基础: #636e72 / #b2bec3

视觉规范（强制）

圆角（必须使用）:
  - 标准圆角: rounded=1 (8px效果)
  - 大圆角容器: rounded=1;arcSize=12;
  - 圆形图标: ellipse=1;

阴影（提升层次感）:
  - 主要组件: shadow=1;
  - 容器/区域: shadow=0; (不加阴影)
  - 悬浮效果: shadow=1;shadowColor=#00000020;

边框:
  - 主要组件: strokeWidth=2;
  - 容器边框: strokeWidth=3;
  - 无边框卡片: strokeColor=none;

字体大小:
  - 主标题: fontSize=24; fontStyle=1; (加粗)
  - 区域标题: fontSize=20; fontStyle=1;
  - 组件标题: fontSize=16; fontStyle=1;
  - 描述文字: fontSize=12; fontStyle=0;
  - 小标签: fontSize=11;

布局网格系统（强制）

画布设置:
  - 推荐尺寸: 1400x900 或 1600x1000
  - 边距: 左右各 50px，上下各 50px
  - 网格对齐: 所有元素坐标为 10 的倍数

组件尺寸标准:
  - 小卡片: 160x80
  - 标准卡片: 200x100
  - 大卡片: 280x120
  - 容器区域: 根据内容，最小 300x200
  - 图标: 48x48 或 60x60

间距规范:
  - 同级组件水平间距: 40px
  - 同级组件垂直间距: 30px
  - 容器内边距: 20px
  - 容器间距: 50px
  - 层级间距: 80-100px

对齐原则:
  - 同一行组件: y 坐标相同
  - 同一列组件: x 坐标相同
  - 居中对齐: 计算中心点

层次结构模板

三层架构（从上到下）:
  Layer 1 - 入口层 (y=50-150):
    - 用户、客户端、API Gateway
    - 颜色: 主题色

  Layer 2 - 服务层 (y=200-400):
    - 微服务、业务逻辑
    - 颜色: 功能色（蓝、绿、橙等区分）

  Layer 3 - 数据层 (y=450-600):
    - 数据库、缓存、消息队列
    - 颜色: 统一绿色系

底部基础设施条 (y=700-800):
  - K8s、云服务、监控
  - 颜色: 深灰 #37474f
  - 文字: 白色

现代样式模板库

玻璃态/毛玻璃风格（推荐）

// 主容器 - 玻璃态背景
"rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#667eea;strokeWidth=3;shadow=1;opacity=95;"

// 标题栏 - 渐变效果
"rounded=1;whiteSpace=wrap;html=1;fillColor=#667eea;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=20;fontStyle=1;"

// 功能卡片 - 浅色填充
"rounded=1;whiteSpace=wrap;html=1;fillColor=#e8eaf6;strokeColor=#667eea;strokeWidth=2;shadow=1;fontSize=14;"

// 信息卡片 - 柔和阴影
"rounded=1;whiteSpace=wrap;html=1;fillColor=#f8f9fa;strokeColor=none;shadow=1;fontSize=12;"

现代渐变风格

// 紫蓝渐变标题
"rounded=1;whiteSpace=wrap;html=1;fillColor=#667eea;gradientColor=#764ba2;gradientDirection=east;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=24;fontStyle=1;"

// 蓝绿渐变卡片
"rounded=1;whiteSpace=wrap;html=1;fillColor=#0984e3;gradientColor=#00b894;gradientDirection=south;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=16;fontStyle=1;"

// 橙红渐变强调
"rounded=1;whiteSpace=wrap;html=1;fillColor=#fdcb6e;gradientColor=#e17055;gradientDirection=east;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=16;fontStyle=1;"

企业专业风格

// 服务节点 - 蓝色
"rounded=1;whiteSpace=wrap;html=1;fillColor=#0984e3;strokeColor=#0652DD;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

// 数据库 - 绿色
"rounded=1;whiteSpace=wrap;html=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

// 消息队列 - 橙色
"rounded=1;whiteSpace=wrap;html=1;fillColor=#fdcb6e;strokeColor=#f39c12;strokeWidth=2;shadow=1;fontColor=#2d3436;fontSize=14;fontStyle=1;"

// 缓存 - 紫色
"rounded=1;whiteSpace=wrap;html=1;fillColor=#a29bfe;strokeColor=#6c5ce7;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

// 外部服务 - 灰色
"rounded=1;whiteSpace=wrap;html=1;fillColor=#636e72;strokeColor=#2d3436;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

区域容器样式

// 主区域容器 - 白底彩边
"rounded=1;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#667eea;strokeWidth=3;shadow=1;verticalAlign=top;fontSize=20;fontStyle=1;fontColor=#667eea;"

// 次级区域 - 浅色填充
"rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f7fa;strokeColor=#b2bec3;strokeWidth=2;dashed=1;dashPattern=5 5;verticalAlign=top;fontSize=16;fontStyle=1;fontColor=#636e72;"

// 底部基础设施条
"rounded=1;whiteSpace=wrap;html=1;fillColor=#37474f;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=16;fontStyle=1;"

现代连线样式

// 主数据流 - 粗实线渐变色
"edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=3;strokeColor=#667eea;endArrow=blockThin;endFill=1;"

// 次级调用 - 细实线
"edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;strokeColor=#0984e3;endArrow=classic;endFill=1;"

// 异步消息 - 虚线
"edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;strokeColor=#fdcb6e;dashed=1;dashPattern=8 4;endArrow=classic;endFill=1;"

// 双向通信 - 双箭头
"edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;strokeColor=#00b894;startArrow=classic;endArrow=classic;startFill=1;endFill=1;"

// 弯曲连线 - 曲线
"edgeStyle=orthogonalEdgeStyle;curved=1;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;strokeColor=#667eea;endArrow=classic;endFill=1;"

标签和徽章

// 圆角徽章 - 强调
"rounded=1;whiteSpace=wrap;html=1;fillColor=#667eea;strokeColor=none;arcSize=50;fontColor=#ffffff;fontSize=11;fontStyle=1;"

// 状态标签 - 成功
"rounded=1;whiteSpace=wrap;html=1;fillColor=#00b894;strokeColor=none;arcSize=50;fontColor=#ffffff;fontSize=10;"

// 状态标签 - 警告
"rounded=1;whiteSpace=wrap;html=1;fillColor=#fdcb6e;strokeColor=none;arcSize=50;fontColor=#2d3436;fontSize=10;"

// 数字徽章
"ellipse;whiteSpace=wrap;html=1;fillColor=#d63031;strokeColor=none;fontColor=#ffffff;fontSize=12;fontStyle=1;"

完整样式速查表

快速复制模板

# 标题区域（必须有）
title_bar: "rounded=1;fillColor=#667eea;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=24;fontStyle=1;"

# 主容器
container: "rounded=1;fillColor=#ffffff;strokeColor=#667eea;strokeWidth=3;shadow=1;"

# 功能卡片（按颜色区分）
card_blue: "rounded=1;fillColor=#e8eaf6;strokeColor=#667eea;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#667eea;"
card_green: "rounded=1;fillColor=#e8f5e9;strokeColor=#00b894;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#00b894;"
card_orange: "rounded=1;fillColor=#fff4e6;strokeColor=#fdcb6e;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#e17055;"
card_purple: "rounded=1;fillColor=#f3e5f5;strokeColor=#a29bfe;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#6c5ce7;"

# 服务节点（实心填充）
service_blue: "rounded=1;fillColor=#0984e3;strokeColor=#0652DD;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"
service_green: "rounded=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"
service_orange: "rounded=1;fillColor=#fdcb6e;strokeColor=#f39c12;strokeWidth=2;shadow=1;fontColor=#2d3436;fontSize=14;fontStyle=1;"
service_purple: "rounded=1;fillColor=#a29bfe;strokeColor=#6c5ce7;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 底部条
footer_bar: "rounded=1;fillColor=#37474f;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=14;"

# 连线
edge_main: "edgeStyle=orthogonalEdgeStyle;rounded=1;strokeWidth=3;strokeColor=#667eea;endArrow=blockThin;endFill=1;"
edge_normal: "edgeStyle=orthogonalEdgeStyle;rounded=1;strokeWidth=2;strokeColor=#0984e3;endArrow=classic;endFill=1;"
edge_dashed: "edgeStyle=orthogonalEdgeStyle;rounded=1;strokeWidth=2;strokeColor=#b2bec3;dashed=1;endArrow=classic;endFill=1;"

故障排查

问题1: MCP连接失败

症状: codex mcp list 显示 ✗ Failed to connect

解决方案:

1. 确保已安装浏览器扩展
2. 打开 https://app.diagrams.net
3. 检查扩展图标是否为绿色
4. 重启Codex会话
5. 刷新Draw.io网页

问题2: 无法添加图形

症状: 调用工具后没有图形出现

解决方案:

1. 确认Draw.io网页标签页处于激活状态
2. 检查坐标是否在可见范围内（建议从50, 50开始）
3. 验证形状名称是否正确（使用get-shape-by-name查询）
4. 检查浏览器控制台是否有错误信息

问题3: 图形位置不对

症状: 图形重叠或位置混乱

解决方案:

1. 使用list-paged-model查看所有元素的当前位置
2. 规划坐标系统（建立网格布局）
3. 使用更大的间距（推荐200px以上）
4. 先在纸上或脑海中规划布局再实现

实用案例

案例1: 现代化微服务架构图（完整示例）

场景: 为电商系统生成专业美观的微服务架构图

=== Step 1: 创建画布背景和标题 ===

# 浅灰背景（覆盖整个画布）
add-rectangle:
  x: 0, y: 0, width: 1400, height: 900
  text: ""
  style: "rounded=0;fillColor=#f5f7fa;strokeColor=none;"

# 渐变标题栏
add-rectangle:
  x: 400, y: 30, width: 600, height: 70
  text: "电商系统微服务架构"
  style: "rounded=1;fillColor=#667eea;gradientColor=#764ba2;gradientDirection=east;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=28;fontStyle=1;"

=== Step 2: 创建主要区域容器 ===

# 服务层容器
add-rectangle:
  x: 50, y: 130, width: 650, height: 350
  text: "服务层"
  style: "rounded=1;fillColor=#ffffff;strokeColor=#667eea;strokeWidth=3;shadow=1;verticalAlign=top;align=left;spacingLeft=20;fontSize=18;fontStyle=1;fontColor=#667eea;"

# AI能力层容器
add-rectangle:
  x: 720, y: 130, width: 630, height: 350
  text: "AI 能力层"
  style: "rounded=1;fillColor=#ffffff;strokeColor=#00b894;strokeWidth=3;shadow=1;verticalAlign=top;align=left;spacingLeft=20;fontSize=18;fontStyle=1;fontColor=#00b894;"

=== Step 3: 创建服务节点（带文本，禁止空节点） ===

# API Gateway - 入口服务
add-rectangle:
  x: 100, y: 180, width: 200, height: 80
  text: "API Gateway<br>路由 | 认证 | 限流"
  style: "rounded=1;fillColor=#667eea;strokeColor=#5a67d8;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 订单服务
add-rectangle:
  x: 100, y: 290, width: 180, height: 90
  text: "订单服务<br>创建订单<br>订单查询"
  style: "rounded=1;fillColor=#0984e3;strokeColor=#0652DD;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 商品服务
add-rectangle:
  x: 300, y: 290, width: 180, height: 90
  text: "商品服务<br>商品管理<br>库存管理"
  style: "rounded=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 用户服务
add-rectangle:
  x: 500, y: 290, width: 180, height: 90
  text: "用户服务<br>用户认证<br>用户信息"
  style: "rounded=1;fillColor=#a29bfe;strokeColor=#6c5ce7;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

=== Step 4: AI能力层节点 ===

# RAG引擎
add-rectangle:
  x: 770, y: 180, width: 180, height: 100
  text: "RAG 引擎<br>文档解析<br>向量检索"
  style: "rounded=1;fillColor=#e8eaf6;strokeColor=#667eea;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#667eea;"

# 推理服务
add-rectangle:
  x: 970, y: 180, width: 180, height: 100
  text: "推理服务<br>模型网关<br>负载均衡"
  style: "rounded=1;fillColor=#e8f5e9;strokeColor=#00b894;strokeWidth=2;shadow=1;fontSize=14;fontStyle=1;fontColor=#00b894;"

=== Step 5: 数据层 ===

# 数据库组
add-rectangle:
  x: 100, y: 520, width: 180, height: 80
  text: "订单 DB<br>MySQL"
  style: "rounded=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

add-rectangle:
  x: 300, y: 520, width: 180, height: 80
  text: "商品 DB<br>MongoDB"
  style: "rounded=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

add-rectangle:
  x: 500, y: 520, width: 180, height: 80
  text: "用户 DB<br>PostgreSQL"
  style: "rounded=1;fillColor=#00b894;strokeColor=#009432;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 向量数据库
add-rectangle:
  x: 770, y: 520, width: 180, height: 80
  text: "向量库<br>Milvus"
  style: "rounded=1;fillColor=#a29bfe;strokeColor=#6c5ce7;strokeWidth=2;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

# 缓存
add-rectangle:
  x: 970, y: 520, width: 180, height: 80
  text: "缓存<br>Redis"
  style: "rounded=1;fillColor=#fdcb6e;strokeColor=#f39c12;strokeWidth=2;shadow=1;fontColor=#2d3436;fontSize=14;fontStyle=1;"

=== Step 6: 底部基础设施条 ===

add-rectangle:
  x: 50, y: 650, width: 1300, height: 60
  text: "基础设施层: Kubernetes | 对象存储 (S3) | 监控告警 (Prometheus) | 日志系统 (ELK)"
  style: "rounded=1;fillColor=#37474f;strokeColor=none;shadow=1;fontColor=#ffffff;fontSize=14;fontStyle=1;"

=== Step 7: 添加连线 ===

# 使用现代连线样式
edge_style_main: "edgeStyle=orthogonalEdgeStyle;rounded=1;strokeWidth=3;strokeColor=#667eea;endArrow=blockThin;endFill=1;"
edge_style_normal: "edgeStyle=orthogonalEdgeStyle;rounded=1;strokeWidth=2;strokeColor=#0984e3;endArrow=classic;endFill=1;"

[核心规则]:
  1. 每个 add-rectangle 必须直接包含 text 参数
  2. 禁止创建空形状后叠加文本框
  3. 多行内容使用 <br> 分隔
  4. 统一使用现代配色方案
  5. 所有组件添加 shadow=1 和 rounded=1

案例2: 生成数据流图

场景: 展示用户注册流程

步骤:
  1. 起点: 用户 (50, 100)
  2. 前端表单 (250, 100)
  3. 后端API (450, 100)
  4. 数据库 (650, 100)
  5. 邮件服务 (450, 250)
  6. 用实线箭头连接主流程
  7. 用虚线箭头连接异步操作（邮件发送）

进阶技巧

1. 批量创建图形

使用循环或列表批量生成图形，适合创建重复结构：

场景: 创建Kubernetes集群图

思路:
  - 定义Pod模板样式
  - 使用循环创建多个Pod（位置自动计算）
  - 批量添加连接线

2. 图层管理

分层策略:
  Layer 1 - 基础设施层: 网络、存储、计算资源
  Layer 2 - 服务层: 微服务、API、中间件
  Layer 3 - 应用层: 前端、后端、移动端
  Layer 4 - 数据层: 数据库、缓存、消息队列

实现: 使用Y坐标区分层次
  - 基础设施: y=400-500
  - 服务层: y=250-350
  - 应用层: y=100-200
  - 数据层: y=500-600

3. 智能命名

为单元格ID使用有意义的命名:
  [错误]: cell-1, cell-2, cell-3
  [正确]: api-gateway, order-service, user-db

优势:
  - 更容易查找和引用
  - 代码可读性更高
  - 便于后续修改

设计质量检查清单（生成图表前必检）

结构规范检查

□ 文本设置:
  - [ ] 所有形状的 text 参数都已设置（禁止空形状）
  - [ ] 多行文本使用 <br> 标签分隔
  - [ ] 没有创建独立的 text 类型文本框覆盖形状

□ 层次结构:
  - [ ] 有明确的标题区域
  - [ ] 使用容器区分不同功能模块
  - [ ] 层级从上到下或从左到右清晰排列
  - [ ] 底部有基础设施条（如需要）

视觉规范检查

□ 配色:
  - [ ] 使用统一的主题色（推荐紫蓝 #667eea）
  - [ ] 功能色区分不同类型组件（蓝、绿、橙、紫）
  - [ ] 文字颜色与背景形成足够对比
  - [ ] 深色背景用白色文字，浅色背景用深色文字

□ 样式:
  - [ ] 所有组件都有圆角（rounded=1）
  - [ ] 主要组件添加阴影（shadow=1）
  - [ ] 边框宽度统一（strokeWidth=2 或 3）
  - [ ] 字体大小层次分明（标题大、内容小）

□ 布局:
  - [ ] 坐标为 10 的倍数（网格对齐）
  - [ ] 同级组件间距一致（40px 水平，30px 垂直）
  - [ ] 同一行组件 y 坐标相同
  - [ ] 同一列组件 x 坐标相同

专业度检查

□ 完整性:
  - [ ] 有渐变标题栏
  - [ ] 有区域容器划分
  - [ ] 有连线表示关系
  - [ ] 有底部基础设施说明（如适用）

□ 美观性:
  - [ ] 整体配色和谐
  - [ ] 没有元素重叠
  - [ ] 间距均匀美观
  - [ ] 文字居中或对齐

快速自检口诀

一看文本在不在形状里，二看圆角阴影加没加
三看配色统不统一，四看间距齐不齐
五看标题够不够大，六看层次分不分明

文本溢出防止规则（极其重要）

核心原则：文本必须适配容器

这是生成美观图表的关键规则，必须严格遵守！

文本宽度计算公式

最大安全字符数 = (容器宽度 - 左右边距) / 平均字符宽度

中文字符宽度估算（按字号）:
  - fontSize=7:  约 7px/字
  - fontSize=8:  约 8px/字
  - fontSize=9:  约 9px/字
  - fontSize=10: 约 10px/字
  - fontSize=11: 约 11px/字
  - fontSize=12: 约 12px/字
  - fontSize=14: 约 14px/字
  - fontSize=16: 约 16px/字

英文字符宽度估算（约为中文的 0.5-0.6 倍）:
  - fontSize=8:  约 4-5px/字
  - fontSize=10: 约 5-6px/字
  - fontSize=12: 约 6-7px/字

边距预留:
  - 最小左右边距: 10px (共 20px)
  - 推荐左右边距: 15px (共 30px)

容器尺寸与文本长度对照表

小容器 (60-80px 宽):
  - 推荐字号: 7-8px
  - 最大中文字数: 5-7字/行
  - 示例: "数据库", "缓存", "API"

标准容器 (80-120px 宽):
  - 推荐字号: 8-10px
  - 最大中文字数: 6-10字/行
  - 示例: "用户服务", "订单处理"

中等容器 (120-160px 宽):
  - 推荐字号: 10-12px
  - 最大中文字数: 8-12字/行
  - 示例: "API Gateway", "消息队列服务"

大容器 (160-200px 宽):
  - 推荐字号: 12-14px
  - 最大���文字数: 10-14字/行
  - 示例: "电商系统架构", "用户认证服务"

超大容器 (200px+ 宽):
  - 推荐字号: 14-16px
  - 最大中文字数: 12-16字/行
  - 示例: "企业级微服务架构图"

文本溢出解决策略

策略1: 简化文本标签

# 错误 - 文本太长导致溢出
text: "@editverse/editor-core"
text: "useEditorProtocol Hook"
text: "captureSelection 方法"

# 正确 - 简化为核心词汇
text: "editor-core"
text: "Editor Hook"
text: "选区捕获"

策略2: 使用符号代替文字

# 流程步骤使用圆圈数字
text: "①②③" 代替 "1. xxx 2. xxx 3. xxx"

# 分隔使用简洁符号
text: "A | B | C" 代�� "A 功能 / B 功能 / C 功能"

# 层级使用箭头
text: "A → B → C" 代替 "A 调用 B 调用 C"

策略3: 详细内容外置

核心模块内只放简短标识，详细说明放到注释区:

# 主流程框
text: "① 捕获"      # 简短标识
text: "② 推送"
text: "③ 接收"

# 右侧注释区（详细说明）
text: "① captureSelection()<br>② pushChatContext()<br>③ receiveChatResponse()"

策略4: 智能换行分布

# 错误 - 单行过长
text: "用户服务 | 订单服务 | 商品服务 | 支付服务"

# 正确 - 多行分布
text: "用户服务 | 订单服务<br>商品服务 | 支付服务"

# 或者使用列表格式
text: "核心服务<br>- 用户<br>- 订单<br>- 商品"

字号与容器匹配规则（强制）

自动字号选择规则:

宽度 < 70px:
  - 使用 fontSize=7 或 8
  - 文本限制 4-5 字
  - 只放核心标识

宽度 70-100px:
  - 使用 fontSize=8 或 9
  - 文本限制 6-8 字
  - 可放简短描述

宽度 100-150px:
  - 使用 fontSize=9 或 10
  - 文本限制 8-12 字
  - 可放标准标签

宽度 150-200px:
  - 使用 fontSize=10 或 11
  - 文本限制 12-16 字
  - 可放详细标签

宽度 > 200px:
  - 使用 fontSize=12-14
  - 文本可相对自由
  - 注意保持美观

流程图专用规则

流程图中的方法名处理:

# 错误做法 - 把完整方法名放在流程框内
框内文本: "1. captureSelection()\n2. pushChatContext()\n3. handleResponse()"

# 正确做法 - 使用编号 + 外部注释
框内文本: "①②③"
注释区文本: "① captureSelection()<br>② pushChatContext()<br>③ handleResponse()"

优势:
  - 流程框保持简洁
  - 详细信息不丢失
  - 视觉更加整洁

包关系图专用规则

包关系图中的包名处理:

# 错误做法 - 使用完整包名
text: "@editverse/editor-core"
text: "@editverse/app-shared"

# 正确做法 - 使用简短名称
text: "editor-core"
text: "app-shared"

目录/文件列表处理:

# 错误做法 - 完整路径
text: "hooks/useEditorProtocol.ts<br>hooks/useChatProtocol.ts"

# 正确做法 - 只显示文件名
text: "useEditorProtocol.ts<br>useChatProtocol.ts"

注释框文本规则

长说明文本处理:

# 错误做法 - 单行长文本
text: "Protocol Store 是核心状态管理，基于 Zustand 实现跨包状态共享"

# 正确做法 - 合理换行
text: "Protocol Store<br>核心状态管理<br>基于 Zustand<br>跨包状态共享"

换行原则:
  - 每行不超过 10-12 个中文字符
  - 在语义断点换行（短语、概念之间）
  - 保持每行长度相近

文本溢出检查清单

□ 创建每个形状前:
  - [ ] 计算容器宽度能容纳多少字符
  - [ ] 检查文本长度是否超出
  - [ ] 必要时简化文本或增大容器

□ 文本内容检查:
  - [ ] 包名是否已简化（去掉 @scope/）
  - [ ] 方法名是否用编号代替
  - [ ] 路径是否只保留文件名
  - [ ] 长说明是否已换行

□ 字号匹配检查:
  - [ ] 小容器使用小字号 (7-9px)
  - [ ] 标准容器使用中等字号 (9-11px)
  - [ ] 大容器使用正常字号 (11-14px)

□ 最终视觉检查:
  - [ ] 文本是否完全在框内
  - [ ] 左右是否有适当边距
  - [ ] 多行文本间距是否合理

快速参考：常见场景处理

场景1 - 模块名太长:
  原: "@editverse/editor-core"
  改: "editor-core"

场景2 - Hook名称太长:
  原: "useEditorProtocol"
  改: "Editor Hook" 或放到注释区

场景3 - 方法调用序列:
  原: "1. captureSelection() 2. pushContext()"
  改: "①②" + 外部注释

场景4 - 文件列表:
  原: "src/hooks/useProtocol.ts"
  改: "useProtocol.ts"

场景5 - 功能描述太长:
  原: "基于 Zustand 的跨包状态管理方案"
  改: "Zustand 状态管理<br>支持跨包共享"

相关资源

• Draw.io官网: https://app.diagrams.net
• MCP服务器GitHub: https://github.com/lgazo/drawio-mcp-server
• Draw.io形状库: https://www.drawio.com/blog/shape-libraries
• Draw.io快捷键: https://www.drawio.com/shortcuts

核心价值

• 自动化: 程序化生成架构图，节省手动绘制时间
• 一致性: 统一样式和布局，提升文档专业性
• 可维护: 代码化的图表更容易版本控制和修改
• 智能化: AI理解项目结构，自动设计合理布局
• 集成化: 与代码库同步，确保文档实时更新

最佳实践: 将Draw.io图表生成集成到项目文档工作流中，每次架构变更时自动更新图表，保持文档与代码同步！