visio-skill

Visio 技能

工作流

如果已安装 Visio，且用户需要真实的 .vsdx 文件，请使用本地 Microsoft Visio COM 自动化。创建新图表时，优先使用随附脚本：

python "<skill>/scripts/New-VisioDiagram.py" "<diagram.json>" "<diagram.vsdx>"

先创建 JSON 规范，再运行脚本。将输出文件保存在用户指定的文件夹中；若未指定，则保存在当前工作区。

RTL / Verilog 逻辑框图

当用户提供 Verilog 源文件或要求绘制 FPGA / RTL 逻辑框图时，优先使用确定性 RTL 生成器，而不是手动编写 JSON 布局：

python "<skill>/scripts/verilog_to_visio.py" "<verilog-dir-or-top.v>" "<output.vsdx>" \
  --top top_module \
  --json "<output.json>" \
  --preview "<preview.png>"

阅读 references/rtl-verilog.md，了解支持的角色推断和布局规则。生成器会有意汇总全局时钟和复位扇出，以保持模块级图表清晰易读。对于不常见的设计，仅将生成的 JSON 用作后续自定义的备用方案。

从图像重建可编辑 Visio

当用户提供不可编辑的 PNG、JPG、屏幕截图、扫描流程图、架构图、时间线、表格或甘特图，并希望将其重建为可编辑 Visio 时，请使用：

python "<skill>/scripts/image_to_visio.py" "<input.png>" "<output.vsdx>" \
  --mode auto \
  --json "<output.json>" \
  --preview "<preview.png>"

阅读 references/image-reconstruction.md，了解完整工作流。本地解析器会提取形状、条形、采样颜色和线条几何信息。OCR 为可选项。对于文本较多或视觉上较复杂的图表，请检查用户提供的图像，并传入一个小型 --annotations JSON 覆盖层，以修正标签和语义连接，而无需手动重建整个页面。

JSON 规范

此技能支持两种图表类型：

1. 标准图表（流程图、架构图等）

阅读 references/spec-format.md，了解完整格式。最简示例：

{
  "title": "Example",
  "pages": [
    {
      "name": "Page-1",
      "nodes": [
        { "id": "start", "text": "Start", "x": 1, "y": 6, "w": 2, "h": 0.8 },
        { "id": "process", "text": "Process", "x": 4, "y": 6, "w": 2, "h": 0.8 }
      ],
      "connections": [
        { "from": "start", "to": "process", "text": "flow" }
      ]
    }
  ]
}

坐标单位为 Visio 英寸。x 和 y 是节点的左下角坐标；w 和 h 分别是宽度和高度。

使用 Visio 模具图标：

如需使用专业的 Visio 模具图标（网络设备、服务器、计算机等），请在 stencils 数组中声明：

{
  "stencils": [
    { "id": "network", "file": "NETSYM_M.VSSX" },
    { "id": "server", "file": "SERVER_M.VSSX" }
  ],
  "nodes": [
    { "id": "router1", "stencil": "network", "master": "路由器", "text": "Core Router", "x": 2, "y": 5 },
    { "id": "srv1", "stencil": "server", "master": "服务器", "text": "Web Server", "x": 5, "y": 5 }
  ]
}

查找模具图标：

• 快速参考（推荐）：references/stencil-reference.md — 包含常见网络/服务器/计算机模具及经过验证的主控件名称
• 完整目录：references/visio-stencil-index.md — 包含 Visio 内置的全部 362 个模具

最常用的模具：

• NETSYM_M.VSSX（24 个主控件）— 网络符号（路由器、工作组交换机、网桥、网关）
• SERVER_M.VSSX（17 个主控件）— 服务器（Web 服务器、数据库服务器、应用程序服务器）
• COMPS_M.VSSX（10 个主控件）— 计算机和显示器（PC、笔记本电脑、平板电脑）

2. 序列图（UML 交互图）

阅读 references/sequence-format.md，了解完整规范。最简示例：

{
  "type": "sequence",
  "title": "Login Flow",
  "actors": [
    { "id": "user", "name": "User", "type": "actor" },
    { "id": "api", "name": "API", "type": "system" },
    { "id": "db", "name": "Database", "type": "database" }
  ],
  "messages": [
    { "from": "user", "to": "api", "text": "POST /login", "type": "sync" },
    { "from": "api", "to": "db", "text": "Query user", "type": "sync" },
    { "from": "db", "to": "api", "text": "User record", "type": "return" },
    { "from": "api", "to": "user", "text": "JWT token", "type": "return" }
  ]
}

主要功能：

• 设置 "type": "sequence" 以启用序列图模式
• 定义 actors（参与者），可选类型包括 actor、system、database、external
• 定义 messages，包含 from、to、text 和 type（sync、async 或 return）
• 参与者从左到右排列，消息从上到下流动
• 自动绘制生命线和激活框

绘图指南

何时使用模具图标，何时使用基本形状

以下情况仅使用基本形状（不使用模具）：

• ✅ 流程图 / 流程图
• ✅ 过程图 / 过程图
• ✅ 决策树 / 决策树
• ✅ BPMN 图 / 业务流程图
• ✅ 状态机 / 状态机
• ✅ 思维导图 / 思维导图
• ✅ 组织结构图 / 组织结构图

以下情况使用模具图标（用户明确提到“图标”或特定设备时）：

• 🔧 网络拓扑图（路由器、交换机、防火墙）
• 🔧 基础设施图（服务器、存储、设备）
• 🔧 云架构图（Azure、AWS 服务）
• 🔧 数据中心布局图（机房布局）

默认行为：除非用户明确要求“图标”“专业图标”“网络设备”或“云服务”，否则仅使用基本形状。

标准图表

• 使用明确的坐标，确保布局可预测。
• 保持图表易读：将节点按行或列对齐，形状之间至少留出 0.6 至 1.0 英寸的间距，并采用从左到右或从上到下的走向，除非用户另有要求。
• ⚠️ 动态画布尺寸规则：不要仅为将大型图表塞进标准页面尺寸（例如 11x8.5 英寸）而压缩节点、缩小字体或减少间距。相反，应根据坐标和节点数量动态增大单页画布尺寸（pageWidth/pageHeight）（例如采用 A3 尺寸，或 15x11 英寸、18x12 英寸等自定义尺寸），确保节点和连接线周围有充足空间。每张图表都应保持在单页内，但页面画布尺寸必须随内容调整，确保布局美观。
• ⚠️ 流程图“结束”节点规则：在流程图和流程示意图（尤其是自上而下的垂直流程）中，最终的“结束”（End）节点必须始终放在图表最底部（即 y 坐标最低的位置）。不要将它放在侧边或与中间步骤并列，确保视觉流程在页面最低处清晰结束。
• 默认形状为 roundrect（圆角矩形）。默认填充色为高级浅蓝色 #EFF6FF，边框色为 #3B82F6。默认节点文字使用 Microsoft YaHei，字号为 11 pt。
• 默认连接线颜色为石板灰 #475569，文字字号为 10 pt，并自动使用 "textPinX": 0.35 和 "textOffsetY": 0.18 以避免重叠。
• 为不同层级／角色使用高级、低饱和度的柔和色彩（例如，主逻辑使用 #EFF6FF / #3B82F6，开始／成功使用 #ECFDF5 / #10B981，存储使用 #FEF3C7 / #D97706，外部 API 使用 #F5F3FF / #8B5CF6）。
• 对于带标签连接线的并排方框，至少留出 max(1.4 in, label characters * 0.12 in) 的水平间距，并预留箭头空间。
• 形状内部使用简短标签。较长的说明放在标注或外部备注中。
• 对于架构图，按层分组：客户端、边缘／API、服务、数据、外部系统。
• 对于流程图，使用从左到右的流程；如果步骤较多，则分行排列。
• 对于类似泳道的图表，可使用浅色填充的大矩形作为节点背景，或创建带泳道标签的独立行。
• 图章尺寸：使用图章母版时，w 和 h 为可选项；如果省略，将采用母版的默认尺寸。图章图标的典型尺寸为 1.0 至 1.5 英寸。

序列图

• 按逻辑顺序从左到右定义参与者，通常为：用户 → 前端 → 后端 → 数据库 → 外部服务。
• 使用描述性参与者名称，清楚标明每个参与者（例如，“用户”、“Web 应用”、“身份验证服务”、“PostgreSQL”）。
• 选择合适的参与者类型以自动设置颜色：
  • "actor" 表示用户／人员（蓝色）
  • "system" 表示内部服务（紫色）
  • "database" 表示数据存储（琥珀色）
  • "external" 表示第三方 API（绿色）
• 消息按时间顺序从上到下排列，体现实际执行流程。
• 方法调用／请求使用 "type": "sync"；响应使用 "type": "return"（显示为虚线箭头）。
• 消息标签应简洁且有意义（例如，“POST /login”、“查询用户”、“JWT 令牌”）。
• ⚠️ 序列图页面尺寸：对于包含大量消息或参与者的序列图，不要通过减小 actorSpacing 或 messageSpacing 来挤压参与者或消息。相反，应增大单页尺寸（pageWidth/pageHeight），为所有元素留出充裕的边距。
• 对于复杂流程，最多使用 4-6 个参与者；必要时拆分为多张图表。
• 默认间距通常合适；只有在图表过于拥挤或稀疏时，才覆盖 layout.actorSpacing 或 layout.messageSpacing。

验证

生成 .vsdx 后，确认文件存在且大小不为零。如果用户需要进行视觉 QA，请使用 Visio COM 打开文件，并可选择导出 PNG/PDF 预览。

如果 COM 创建失败，请检查是否已安装并注册 Visio：

import win32com.client
win32com.client.Dispatch("Visio.Application")

如果无法使用 Visio，请提供 Mermaid、SVG、draw.io 或其他可导入的格式，而不要假装已创建 .vsdx 文件。