Draw.io 转 Visio 转换器

要解决的问题

把 .drawio 文件转成 Visio 的 .vsdx 时，常见坑包括：导出的包不是合法的 OPC 文档、文本标签丢失、转换过程偷偷联网，或者用 PDF 改后缀冒充 VSDX。这些在需要归档、交付或进团队仓库时会直接踩雷。

技能如何工作

该技能围绕一个固定的 diagrams.net VSDX 导出器（26.0.16）运行，先把 diagrams.net 缓存到本地，再通过一个受控的临时 127.0.0.1 源加载你的画布内容，全程屏蔽其他 HTTP 源、WebSocket 和服务工作者。

核心流程如下：

• 确认输入是已存在的 .drawio 或 Draw.io XML 文件。
• 显式指定 .vsdx 输出路径；除非你明确要求覆盖，否则拒绝覆盖已有输出。
• 运行随附的转换器，生成 VSDX 包。
• 对需要保证的关键文本，使用可重复的 --expect 参数做断言，例如检查指定短语必须出现在 VSDX 里。
• 汇报输出路径、验证数量，以及仍存在的视觉验证限制。

转换后会自动运行 validate_vsdx.py，它要求输出：是 ZIP/OPC 包而非改后缀的 PDF；有合法的 OPC 内容类型与关系 XML；存在完整的 Visio 文档-页面-页面关系链和命名空间；在被引用的页面里至少有一个 Visio 形状；并且你通过 --expect 指定的每个短语都出现在被引用页面某个形状的文本里。

适用边界与注意点

包验证和 diagrams.net 的兼容性并不等于 Microsoft Visio 的像素级渲染。高风险交付场景，如果本机装有 Visio，还应在客户端里再打开确认一次。只有在你真的打开过 Visio 客户端检查后，才能声称做过 Visio 检查。

首次使用时，在加载你的文件前，它可能会把固定的官方 diagrams.net tag 从 GitHub 克隆到本地缓存；之后运行会同时校验固定 commit 和缓存的干净 worktree。缓存存在后，可以用 --no-download 完全离线运行。

多文件转换时，它会逐一列出精确的源/输出对，每个文件运行一次封装器。遇到第一个失败就停止，保留已完成的输出，并分别报告成功与失败的文件。除非你明确授权，绝不追加 --force。