PlantUML 时序图 → Visio VSDX 转换器

将 PlantUML 时序图源码转换为甲方可直接打开的原生 Visio .vsdx 文件。所有元素均为 Visio Shape 对象（非图片），可在 Visio 中自由编辑、拖动、改色。

前置条件

1. Windows + Microsoft Visio — 必须已安装 Visio（任何版本）
2. Python + pywin32 — 检查 python -c "import win32com.client"，若无则 pip install pywin32
3. .puml 文件 — 用户提供的 PlantUML 时序图源码文件

使用方式

方式一：直接运行脚本（推荐，最稳定）

python scripts/puml_to_visio.py <input.puml> [output.vsdx]

• 不指定输出路径时，自动保存为同目录同名 .vsdx
• 脚本会自动检测 Visio 中已打开的同名文档并关闭，避免"只读"冲突

方式二：在代码中调用

from scripts.puml_to_visio import PumlParser, VisioSequenceRenderer

with open("diagram.puml", "r", encoding="utf-8") as f:
    parser = PumlParser(f.read())

renderer = VisioSequenceRenderer(
    parser.get_participants(),
    parser.actions,
    "output.vsdx",
    page_width=22.0,    # 可选，自动计算
    page_height=34.0,   # 可选，自动计算
)
renderer.render()

支持的 PUML 语法

以上所有类型都支持四种写法："显示名" as 别名 / 名称 as 别名 / "显示名" / 名称。若别名未绑定（如 actor 用户 as user），消息中使用的别名会被误当成独立参与者，显示名会变成 user 而非 用户。
| A ->> B: 消息 | 实线实心箭头 | 异步调用 / 请求 |
| A -> B: 消息 | 实线开放箭头 | 用户操作 / 简单调用 |
| A --> B: 消息 | 虚线开放箭头 | 返回 / 响应 |
| A -->> B: 消息 | 虚线实心箭头 | 异步返回 |
| == 标题 == | 阶段分隔条 | 浅蓝背景 + 深蓝文字 |
| alt 标签 / else 标签 / end | 条件分支帧 | 灰色圆角矩形 + 左上角标签 |
| loop 标签 / end | 循环帧 | 金色边框 + loop 前缀标签 |
| 嵌套 alt/loop | 自动缩进 | 支持任意深度嵌套 |
| note right/left/over A : 文本 | 注释框 | 淡黄色矩形；支持 of A 写法（note right of A），over A 会定位到参与者列 |
| <color:red>...</color> | 富文本染色 | 消息/注释文本内嵌 PlantUML 颜色标记，标签剥离后仅对应文字染该色；支持颜色名（red/blue/orange…）与 #RRGGBB，颜色名映射表见脚本 COLOR_NAMES |

生成的 Visio 图表结构

底层（SendToBack）：
  ├── 生命线 — 灰色虚线，贯穿整个时序，SendToBack 置底
  ├── alt/loop 帧 — 圆角矩形框 + 左上角标签
  └── 阶段分隔条 — 浅蓝背景条

中层：
  └── 激活条 — 浅蓝细长矩形，标记参与者"正在处理"的时间段

顶层（BringToFront）：
  ├── 消息箭头线 — 按类型分实线/虚线、实心/开放箭头
  └── 参与者头部 — 按类型区分（全部 BringToFront 置顶）：
      ├── participant / entity / queue / ... — 蓝色圆角矩形 + 白色文字
      ├── database — 钢色立体圆柱（顶盖径向渐变 + 主体横向线性渐变 + 底沿），文字在主体内
      └── actor — 现代简约扁平化商务人物图标（头圆 + 肩弧 + 主体）+ 右侧名称标签

关键技术要点（踩过的坑）

1. Z-order 是生命线可见性的关键

问题：生命线先绘制但被后画的消息/帧盖住，看起来"没有生命线"。

解决：绘制完成后显式调用 SendToBack()（生命线）和 BringToFront()（头部），确保层级正确。

2. 箭头必须精确落在生命线 X 坐标上

问题：箭头端点使用估算坐标，导致箭头"悬空飘着"，读者无法判断从哪个服务发出。

解决：每个参与者有精确的 PX[name] X 坐标，箭头严格从 PX[from] 画到 PX[to]。

3. Char.Bold 等单元格可能不存在

问题：shape.Cells("Char.Bold") 报错 pywintypes.com_error: 意外的文件尾。

解决：使用 _safe() 包装所有 Cells() 调用，忽略不存在的单元格，不中断流程。

4. 文件被 Visio 锁住导致 SaveAs 失败

问题：DOS 无效句柄 / [只读] — 同名文档已在 Visio 中打开（可能处于只读状态），或存在多个 Visio 进程。

解决：保存前遍历 visio.Documents，先 d.Saved = True 抑制“是否保存”弹窗，再关闭所有 FullName 匹配的文档，最后删除旧文件、执行 SaveAs。若仍有异常，检查是否有多个 VISIO.EXE 进程（Get-Process VISIO），关掉多余的进程后重试。

5. 激活条用栈管理嵌套调用

问题：A调用B，B又调用C，B的激活条应该在C返回后才结束。

解决：每个参与者维护一个激活栈。实线箭头（->> / ->）压栈（开始激活），虚线箭头（--> / -->>）弹栈（结束激活），栈式管理天然支持嵌套。

6. participant 别名的 Key 一致性

问题：PUML 中 participant "HTTP网关\nosg-scp0001" as HTTP网关，动作序列中用短名 HTTP网关，但 PX 字典的 key 是带换行的全名 → KeyError。

解决：维护两个字典 — alias_map（别名→显示名）用于解析，绘制时用显示名作为统一 key。

7. 从右往左画线导致文字颠倒

问题：返回消息（如 支付中心 --> 智能处理服务）是从右往左画线，Visio 会自动翻转文字方向到线下方，视觉上文字"颠倒"。

解决：始终从左往右画线（x_left < x_right），通过交换 BeginArrow/EndArrow 来保证箭头指向正确方向。

8. 箭头嵌入激活条而非接触边缘

问题：箭头端点画在生命线 X 坐标上，但激活条有宽度（默认 0.14"），箭头会穿入激活条内部而非刚好接触边缘。

解决：计算激活条半宽 act_half = act_w / 2，箭头两端各收缩 act_half，使箭头刚好接触激活条边缘。

9. alt/loop 帧遮盖下方流程

问题：帧的填充色 FillForegndTrans=0.15 仍不够透明，浅色背景会遮盖下方的消息线和文字。

解决：使用 FillPattern=0（完全无填充），只保留边框线。标签用文字白底（TxtBkgnd=1）保证可读性。

10. 参与者头部超出画布右边缘

问题：参与者定位算法把第一个/最后一个头部中心放在页面边缘，导致头部矩形一半超出画布。

解决：布局计算时预留头部半宽，第一个参与者从 margin_left + header_half 开始，最后一个在 page_width - margin_right - header_half 结束。

11. 生命线颜色太浅看不清

问题：生命线颜色 RGB(130,130,130) 在白色背景上对比度不足。

解决：改为 RGB(80,80,80) 深灰色，线宽从 1 pt 增加到 1.25 pt。

12. 相对路径导致文件保存到错误目录

问题：SaveAs 传入相对路径时，Visio（独立 COM 进程）用它自己记住的工作目录解析，文件被保存到别的目录，而非 puml 所在目录。

解决：main() 中先 os.path.abspath(output_path) 转成绝对路径再交给 Visio。

13. actor / database 等参与者类型必须显式解析

问题：原始解析器只认 participant 和无引号的 actor，actor 用户 as user、database "..." as rds 会被漏掉——别名未绑定，消息里的 user/rds 被自动发现成显示名为 user/rds 的独立参与者。

解决：用统一正则 (participant|actor|database|entity|queue|control|boundary|collections) 匹配带引号/不带引号、带/不带别名的四种写法；名字正则用 ([^\s-]\S*) 防止把 control --> x 消息误判为定义。头部按 actor（火柴人）和 database（圆柱体）区分渲染。

14. <color:...> 富文本染色必须最后应用且索引要对准

问题：直接把 <color:red>...</color> 原样写入 shape.Text 会把标签当文字显示；先设全局 Char.Color 再设片段颜色会被全局值覆盖；消息文本里的 \n 换行经 Visio 归一化后，按 Python 字符串长度算 Characters.Begin/End 会错位导致染错字符。

解决：_plain_text() 先剥离标签、_apply_color_spans() 再按 Visio 字符 run 染色，且必须在所有全局 Char 格式（Char.Size/Char.Color/TxtBkgnd）设置之后调用；染色前读取 shape.Text 实际存储文本，归一化换行后建立"归一化索引→原始索引"映射，保证 Begin/End 精确落在染色片段上。坑：本版 Visio 类型库 Characters 没有 Char 属性（win32com 会报 AttributeError <unknown>.Char）；正确做法是 Characters.CharProps(visCharacterColor, 0)（只写属性，对选中范围写入色值即触发 Visio 新建字符 run 行）→ Characters.CharPropsRow(0) 取回该 run 的 Character 行号 → Shape.CellsSRC(visSectionCharacter, row, visCharacterColor).FormulaU = "RGB(r,g,b)" 写自定义 RGB（CharProps 本身只接受调色板索引 0~23）。支持颜色名（COLOR_NAMES）与 #RRGGBB。

puml-to-visio/
├── SKILL.md                        ← 本文件
└── scripts/
    └── puml_to_visio.py            ← 完整转换脚本（~500行）
        ├── PumlParser              ← PUML 解析器（正则逐行解析）
        └── VisioSequenceRenderer   ← Visio 绘制引擎（COM 自动化）

自定义样式

所有样式参数集中在 VisioSequenceRenderer 构造函数中，常用调整：

颜色方案在 _draw_* 方法中定义，全局搜索 RGB( 即可修改。