Workbuddy Visio — 兼容 Visio 的架构图

概述

采用双格式方式生成专业级架构图：.drawio 作为可编辑的源文件，再转换为可供 Visio 导入的 SVG 格式。该技能源自现有 Codex 技能（visio-drawio-svg-diagrams），此前尝试直接使用原生 SVG 生成器均告失败——Microsoft Visio 对 SVG 输入格式要求极为严苛，而 drawio_to_svg.py 转换器专为满足其特定需求而设计。

核心工作流：

1. 编写 Python 脚本生成 .drawio 文件（未压缩的内联 XML 格式）
2. 运行 drawio_to_svg.py 将其转换为 Visio 兼容的 SVG
3. 在 Visio 中打开该 SVG 文件；或在 draw.io 中打开 .drawio 文件进行进一步编辑

工作流

步骤 1：生成 .drawio

使用 xml.etree.ElementTree 编写 Python 脚本。draw.io 格式基于 元素：

• vertex="1" 表示形状/方框
• edge="1" 表示连接线

关键格式规则：

• Python 字符串中使用 n 实现多行文本（不可使用
标签）
• 原始 XML 中使用 作为换行符实体
• 除 id="0" 和 id="1" 外，每个 mxCell 均需指定 parent="1"
• 为确保连线位置稳定，请使用固定端点边（fixed point edges），即显式设置 sourcePoint/targetPoint

顶点（形状/方框）示例：

边（连接线）示例：

步骤 2：转换为 SVG

python /scripts/drawio_to_svg.py input.drawio output.svg

该转换器生成的 SVG 具备以下特性：

• 固定端点边，精确复现 draw.io 布局
• 为每个方框添加独立 clipPath，确保文本严格限制在边界内
• 响应式字体排版：按高度动态调整字号
  • ≤52px → 紧凑模式（标题 11pt，正文 10pt）
  • 52–70px → 13pt / 11pt
  • 70–90px → 15pt / 12pt
  • ≥90px → 18pt / 13pt
• 支持中日韩（CJK）与拉丁文混合的智能文本换行
• 支持箭头标记及虚线样式

步骤 3：验证

交付前请务必确认以下各项：

• .drawio 文件为合法 XML，且包含内联的 结构
• 所有 元素均使用 as="geometry"（而非 as_="geometry"）
• 中文标签保持 UTF-8 编码无损
• SVG 文件为合法 XML
• 渲染后的 SVG 中无文本溢出方框边界
• 连线布局与 draw.io 中完全一致

样式参数参考

分层模式（三层架构）

一种已在工业控制系统图中验证有效的布局模式：

┌──────────────────────────────────────────────────────────┐
│ [Layer 1: Controller]   ┌─────┐ ┌─────┐ ┌──────────┐   │
│   ┌─────────────────┐   │HMI  │ │IOC  │ │ Database │   │
│   │ Main Controller  │   └─────┘ └─────┘ └──────────┘   │
│   └─────────────────┘                                    │
├──────────────────────────────────────────────────────────┤
│ [Layer 2: EtherCAT Bus]                                 │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐      │
│  │AX8206│ │AX8206│ │Safe │ │EL1808│ │EL3124│ │EL2808│  │
│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘      │
├──────────────────────────────────────────────────────────┤
│ [Layer 3: Field Devices]                                │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ [Notes] │
│  │Motor │ │Encoder│ │Safety│ │Limit │ │PT100 │         │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘         │
└──────────────────────────────────────────────────────────┘

1. 标题栏 — 画布顶部居中文本
2. 分层背景 — 左侧带标签的浅色填充圆角矩形
3. 设备方框 — 各层内部的白色/浅色填充圆角矩形
4. 总线条 — 横贯总线层的细长条，代表通信主干
5. 连接线 — 层间垂直连线，并标注协议名称
6. 注释框 — 位于角落的工程说明

推荐配色方案

常见陷阱

1. ❌ 使用
实现换行 — Python 字符串中始终使用 n（原始 XML 中对应 ）。在 draw.io 和 SVG 中，
均会以可见文本形式呈现。
2. ❌ 小尺寸方框内文本溢出 — 转换器会对超出边界的文本进行裁剪。如需容纳多行内容，请增大方框高度（≥90px），或精简文本内容。
3. ❌ 缺失 parent="1" — 除 id="0" 和 id="1" 外，所有 mxCell 必须显式声明 parent="1"，否则 draw.io 将无法显示该元素。
4. ❌ 元素重叠 — 请谨慎规划 X/Y 坐标。draw.io 按 ID 顺序渲染，后出现的元素将覆盖在先出现的元素之上。
5. ❌ 使用编码/压缩的 drawio 文件 — 本转换器仅支持未压缩的内联 XML 格式。若 drawio 文件为 base64 编码，请先在 draw.io 桌面版中打开，再通过“文件 → 导出”导出为未压缩 XML。
6. ❌ Visio 导入 SVG 失败 — 若 Visio 拒绝导入 SVG，请改用 draw.io 桌面版打开 .drawio 文件，并通过“文件 → 导出”选择所需格式导出。

脚本

scripts/drawio_to_svg.py

核心转换器：将 draw.io XML 转换为 Visio 兼容 SVG。本脚本改编自 Codex 的 visio-drawio-svg-diagrams 技能，成功解决了标准 SVG 生成器无法处理的 Visio SVG 导入问题。

scripts/example_generator.py

用于程序化生成 draw.io 图表的模板脚本。修改坐标、文本和样式即可快速创建新图表。既可作为参考范例，也可直接用作开发起点。