drawio

name	drawio
description	Professional diagramming and architecture visualization using Draw.io MCP server. Create, modify, and manage system diagrams, flowcharts, and technical documentation visuals programmatically.
version	0.1.0
source	fork
checksum	04e8e9dce2ea393dda4ac9e81fc0b35d924d5dc993cf8cd07ac440963da27099
updated_at	2026-02-11T01:29:29.000Z
layer	utility

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: 

---

故障排查

问题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: 
   



         
   
   

   



         
   
   



         
   
   



         
   
   



         
   
   

   



         
   
   



         
   
   

   



         
   
   


         
   
   


         
   
   



         
   
   



         
   
   

   


         
   
   

   


 
 

[]
       
   
     
   
      

案例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/字

边距预留:
      
      

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

小容器 (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
  - 最大���文字数: 
     

  
    
    
    

文本溢出解决策略

策略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:
  -  
   
   

流程图专用规则

流程图中的方法名处理:

# 错误做法 - 把完整方法名放在流程框内
框内文本: "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图表生成集成到项目文档工作流中，每次架构变更时自动更新图表，保持文档与代码同步！