visio-automation

Visio 自动化

通过 COM 自动化控制真正的 Microsoft Visio，创建和修改图表。目标产物是可编辑的 .vsdx，使用 Visio 内置母版、原生动态连接线、粘附端点和可在手动编辑后保留的 ShapeSheet 设置。

关键词

Visio、.vsdx、Visio COM、模具、母版、NameU、ShapeSheet、动态连接线、GlueToPos、连接线布线、连接线粘附、流程图、BPMN、UML、网络图、组织结构图、DFD、VSM、Mermaid、draw.io、截图重建、白板重建、原生可编辑图表。

默认规则

• 默认以可见的前台模式执行面向用户的 Visio 工作，让用户能看到图表逐步生成。只有用户明确要求在后台或无头模式下运行，或仅进行范围有限的内部发现／验证且不会绘制面向用户的文档时，才使用 New-InvisibleVisioApplication。
• 优先使用 Visio 内置模具和 NameU 母版。只有在没有语义母版或用户需要有意绘制通用草图时，才使用基本图元。
• 对于非简单图表、转换、图像重建，或坐标不明确的任务，绘图前先构建轻量级图模型。
• 使用 Visio 连接线母版和 GlueToPos；对于应随形状移动的关系，不要绘制未粘附的线条。
• 保留用户要求或观察到的连接线路由方式：直角连接线保持直角，直线保持直线，曲线保持曲线。
• 保存 .vsdx，在有用时导出 PNG 预览，然后验证生成的文档，再报告完成情况。

选择要阅读的内容

只阅读当前请求所需的文件：

任务	阅读
选择图表类型、模具或母版	references/diagram-selection.md，如有需要再读 references/master-catalog.md
查找未知或本地化的母版／模具	references/master-discovery.md
自然语言母版查找、中文／英文别名、重复编辑	references/semantic-search-and-cache.md
渲染规划好的图、自动布局、自然语言流程、箭头文本流程、Mermaid 或 draw.io	references/graph-model-and-conversion.md
重建截图、白板、PDF 裁剪图或草图	references/image-reconstruction.md
验证路由、粘附、ShapeSheet 单元格和输出文件	references/verification.md
需要 Visio COM、VBA 或 ShapeSheet API 详细信息	references/official-docs.md

始终加载辅助脚本，不要重新输入 COM 样板代码：

. "$env:USERPROFILE\.codex\skills\visio-automation\scripts\visio_helpers.ps1"

对于非 Codex Agent，将 .codex\skills 部分替换为该 Agent 的技能目录。

常用辅助函数包括：

• Visio 应用／文档：New-VisibleVisioApplication、New-InvisibleVisioApplication、Get-OpenVisioDocumentByPath
• 模具／母版：Open-VisioStencilReadOnly、Get-VisioEnvironment、Build-VisioMasterIndex、Find-VisioMasters、Find-SemanticVisioMaster
• 图渲染／转换：Render-VisioGraphModel、Invoke-VisioGraphLayout、Convert-NaturalLanguageFlowToVisio、Convert-TextFlowToVisio、Convert-MermaidToVisio、Convert-DrawIOToVisio、Convert-ImageReconstructionToVisio
• 形状／连接线编辑：Set-VisioTextStyle、Set-VisioShapeFill、Set-VisioShapeBounds、Connect-VisioShapesOrthogonal、Connect-VisioShapesStraight、Connect-VisioShapesCurved
• 路由策略：Resolve-VisioRoutingIntent、Resolve-VisioRouteDecision、Get-VisioRoutingDefault、Resolve-VisioLoopbackGlue
• 会话缓存：Get-VisioSessionCache、Update-VisioSessionCache、Add-VisioSessionRecentMaster

核心工作流

1. 根据用户的意图判断图表类型。
2. 阅读上表中相关的参考文件。
3. 通过目录、语义搜索或本地发现来选择原生模具／母版。
4. 如果结构包含的不只是几个手动放置的形状，则将图表规范化为图模型。
5. 默认使用可见的 Visio 进行渲染，并使用原生母版和粘附式动态连接线。
6. 保存 .vsdx，在有用时导出预览，验证输出和连接线行为，然后总结结果。

实用说明

• 对包含 UTF-8 中文文本的脚本使用 pwsh。如果没有 BOM，Windows PowerShell 5 可能会错误解析 UTF-8 文件。
• 使用 OpenEx(..., 66) 将模具以隐藏／只读方式打开，以避免保存提示。
• 除非用户明确要求，否则不要关闭用户可见的 Visio 窗口。
• 对于可编辑图表，避免生成原始 .vsdx XML；这通常缺少用户所重视的原生母版和连接线行为。
• 如果后续可能需要编辑，请将任务脚本保留在工作区中。