Codex 自主调用 Visio 绘图完整教程

Codex 自主调用 Visio 绘图完整教程

本文说明如何在一台新的 Windows 电脑上，让 Codex 自主调用本机 Microsoft Visio 绘图，并生成可编辑的 .vsdx、可插入报告的 .pdf/.emf/.svg/.png 文件。

推荐路线：

Codex -> PowerShell 脚本 -> Windows COM 自动化 -> Microsoft Visio 桌面版

这条路线的核心思想很简单：Codex 负责理解需求、生成或修改脚本、运行脚本；PowerShell 负责调用 Visio 的 COM 接口；Visio 负责生成真正可编辑的原生图形文件。

---

1. 适用场景

适合这些任务：

• 让 Codex 自动绘制流程图、技术路线图、模型关系图、系统架构图。
• 生成可编辑的 Visio 文件 .vsdx。
• 同时导出报告可用的 .pdf、.emf、.svg、.png。
• 用户打开 Visio 后，可以实时看到 Codex 绘图过程。
• 需要高质量报告插图，而不是临时截图或不可编辑图片。

不适合这些任务：

• 只想调用 Visio 内置 AI。Visio 或 Office 里的 AI 功能通常依赖账号、会员权限和 UI 状态，不一定暴露稳定本地 API。
• 需要跨平台运行。Windows COM 自动化只适用于 Windows 桌面环境。
• 没有安装 Microsoft Visio 桌面版。网页版 Visio 不能用这种方式被本地 COM 控制。

---

2. 新电脑准备清单

2.1 安装软件

新电脑需要安装：

• Windows 10 或 Windows 11。
• Microsoft Visio 桌面版，建议 Visio Professional 或 Microsoft 365 中带桌面 Visio 的版本。
• Codex 可运行环境。
• PowerShell，Windows 自带即可。

可选但推荐：

• Microsoft Word，用于把导出的 EMF/SVG/PDF 插入专业报告。
• VS Code 或其他编辑器，用于查看脚本和 Markdown 文件。

2.2 确认 Visio 是桌面版

按 Win + S 搜索 Visio。

如果打开后是桌面软件窗口，基本可以继续。

如果只跳到浏览器网页，那不是本教程需要的桌面 COM 自动化路线。

---

3. 检查 Visio COM 自动化是否可用

打开 PowerShell，执行：

$visio = New-Object -ComObject Visio.Application
$visio.Visible = $true
$visio.Version
$visio.Quit()

预期结果：

• Visio 会被打开。
• PowerShell 输出一个版本号，例如 16.0。
• Visio 随后关闭。

如果这一步成功，说明 Codex 也可以通过 PowerShell 控制 Visio。

---

4. 检查 Visio 快捷方式

有些时候你希望 Codex 从指定快捷方式启动 Visio，例如：

<你的桌面路径>\Visio.lnk

检查快捷方式目标：

$lnk = '<你的桌面路径>\Visio.lnk'
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut($lnk)
$shortcut.TargetPath
$shortcut.Arguments

典型输出：

C:\Program Files\Microsoft Office\root\Office16\VISIO.EXE

注意：快捷方式不是必须的。真正控制 Visio 的关键是 Visio.Application 这个 COM 对象。

---

5. 建议目录结构

在新电脑上建议建一个固定工作目录，例如：

D:\CodexVisio\
  scripts\
    Test-VisioCom.ps1
    New-VisioFlowchart.ps1
  output\
  AGENTS.md
  README.md

含义：

• scripts\：放 PowerShell 绘图脚本。
• output\：放 Visio、PDF、图片等输出文件。
• AGENTS.md：告诉 Codex 遇到 Visio 绘图任务时怎么做。
• README.md：给人看的项目说明。

---

6. 最小可用测试脚本

创建文件：

D:\CodexVisio\scripts\Test-VisioCom.ps1

内容如下：

$ErrorActionPreference = 'Stop'

$visio = $null
$doc = $null

try {
    $visio = New-Object -ComObject Visio.Application
    $visio.Visible = $true

    $doc = $visio.Documents.Add('')
    $page = $doc.Pages.Item(1)

    $rect = $page.DrawRectangle(1, 1, 4, 2)
    $rect.Text = 'Codex 已成功调用 Visio'
    $rect.CellsU('Char.Size').FormulaU = '16 pt'
    $rect.CellsU('Para.HorzAlign').FormulaU = '1'
    $rect.CellsU('VerticalAlign').FormulaU = '1'

    $outDir = 'D:\CodexVisio\output'
    New-Item -ItemType Directory -Force -Path $outDir | Out-Null

    $vsdx = Join-Path $outDir 'visio-com-test.vsdx'
    $png = Join-Path $outDir 'visio-com-test.png'

    $doc.SaveAs($vsdx)
    $page.Export($png)

    Write-Output "VSDX=$vsdx"
    Write-Output "PNG=$png"
}
finally {
    # 调试阶段建议先不要自动关闭 Visio，方便你实时看效果。
    # 如果希望脚本结束后关闭 Visio，可以取消下面两行注释。
    # if ($doc) { $doc.Close() }
    # if ($visio) { $visio.Quit() }
}

运行：

powershell -ExecutionPolicy Bypass -File D:\CodexVisio\scripts\Test-VisioCom.ps1

成功后检查：

D:\CodexVisio\output\visio-com-test.vsdx
D:\CodexVisio\output\visio-com-test.png

---

7. 高质量流程图脚本模板

创建文件：

D:\CodexVisio\scripts\New-VisioFlowchart.ps1

这个模板适合让 Codex 后续改造成论文流程图、模型关系图、技术路线图。

$ErrorActionPreference = 'Stop'

$OutputDir = 'D:\CodexVisio\output'
$BaseName = 'codex-visio-flowchart'

New-Item -ItemType Directory -Force -Path $OutputDir | Out-Null

$VsdxPath = Join-Path $OutputDir "$BaseName.vsdx"
$PdfPath  = Join-Path $OutputDir "$BaseName.pdf"
$PngPath  = Join-Path $OutputDir "$BaseName.png"
$SvgPath  = Join-Path $OutputDir "$BaseName.svg"
$EmfPath  = Join-Path $OutputDir "$BaseName.emf"

$visio = $null
$doc = $null
$basic = $null

function Set-CellFormula {
    param(
        [Parameter(Mandatory = $true)] $Shape,
        [Parameter(Mandatory = $true)] [string] $Cell,
        [Parameter(Mandatory = $true)] [string] $Formula
    )

    try {
        $Shape.CellsU($Cell).FormulaU = $Formula
    } catch {
        # 部分 Visio 图形没有某些可选单元格，忽略即可。
    }
}

function Style-Shape {
    param(
        [Parameter(Mandatory = $true)] $Shape,
        [Parameter(Mandatory = $true)] [string] $Text,
        [double] $FontSize = 11,
        [string] $Fill = 'RGB(255,255,255)',
        [string] $Line = 'RGB(52,64,78)',
        [string] $TextColor = 'RGB(28,38,50)'
    )

    $Shape.Text = $Text
    Set-CellFormula $Shape 'FillForegnd' $Fill
    Set-CellFormula $Shape 'FillPattern' '1'
    Set-CellFormula $Shape 'LineColor' $Line
    Set-CellFormula $Shape 'LineWeight' '1.25 pt'
    Set-CellFormula $Shape 'Char.Size' "$FontSize pt"
    Set-CellFormula $Shape 'Char.Font' '"Microsoft YaHei"'
    Set-CellFormula $Shape 'Char.Color' $TextColor
    Set-CellFormula $Shape 'Para.HorzAlign' '1'
    Set-CellFormula $Shape 'VerticalAlign' '1'
    Set-CellFormula $Shape 'TxtMarginLeft' '0.12 in'
    Set-CellFormula $Shape 'TxtMarginRight' '0.12 in'
    Set-CellFormula $Shape 'TxtMarginTop' '0.06 in'
    Set-CellFormula $Shape 'TxtMarginBottom' '0.06 in'
}

function Drop-Shape {
    param(
        [Parameter(Mandatory = $true)] $Page,
        [Parameter(Mandatory = $true)] $Masters,
        [Parameter(Mandatory = $true)] [string] $MasterName,
        [Parameter(Mandatory = $true)] [double] $X,
        [Parameter(Mandatory = $true)] [double] $Y,
        [Parameter(Mandatory = $true)] [double] $Width,
        [Parameter(Mandatory = $true)] [double] $Height,
        [Parameter(Mandatory = $true)] [string] $Text,
        [double] $FontSize = 11,
        [string] $Fill = 'RGB(255,255,255)',
        [string] $Line = 'RGB(52,64,78)'
    )

    $shape = $Page.Drop($Masters.ItemU($MasterName), $X, $Y)
    Set-CellFormula $shape 'PinX' "$X in"
    Set-CellFormula $shape 'PinY' "$Y in"
    Set-CellFormula $shape 'Width' "$Width in"
    Set-CellFormula $shape 'Height' "$Height in"
    Style-Shape $shape $Text $FontSize $Fill $Line
    return $shape
}

function Add-Line {
    param(
        [Parameter(Mandatory = $true)] $Page,
        [Parameter(Mandatory = $true)] [double] $X1,
        [Parameter(Mandatory = $true)] [double] $Y1,
        [Parameter(Mandatory = $true)] [double] $X2,
        [Parameter(Mandatory = $true)] [double] $Y2,
        [bool] $Arrow = $true
    )

    $line = $Page.DrawLine($X1, $Y1, $X2, $Y2)
    Set-CellFormula $line 'LineColor' 'RGB(52,64,78)'
    Set-CellFormula $line 'LineWeight' '1.25 pt'
    if ($Arrow) {
        Set-CellFormula $line 'EndArrow' '2'
    }
    return $line
}

try {
    $visio = New-Object -ComObject Visio.Application
    $visio.Visible = $true
    $visio.AlertResponse = 7

    $doc = $visio.Documents.Add('')
    $page = $doc.Pages.Item(1)

    Set-CellFormula $page.PageSheet 'PageWidth' '11 in'
    Set-CellFormula $page.PageSheet 'PageHeight' '8.5 in'

    $basicPaths = @(
        'C:\Program Files\Microsoft Office\root\Office16\Visio Content\2052\BASIC_M.VSSX',
        'C:\Program Files\Microsoft Office\root\Office16\Visio Content\1033\BASIC_M.VSSX',
        'C:\Program Files\Microsoft Office\root\Office16\Visio Content\2052\BASIC_U.VSSX',
        'C:\Program Files\Microsoft Office\root\Office16\Visio Content\1033\BASIC_U.VSSX'
    )

    $basicPath = $basicPaths | Where-Object { Test-Path -LiteralPath $_ } | Select-Object -First 1
    if (-not $basicPath) {
        throw '找不到 Visio 基础图形模板 BASIC_M.VSSX 或 BASIC_U.VSSX。'
    }

    $basic = $visio.Documents.OpenEx($basicPath, 1)
    $masters = $basic.Masters

    # 先画线，再放节点，避免线压住文字。
    Add-Line $page 5.50 7.20 5.50 6.75
    Add-Line $page 5.50 5.95 5.50 5.50
    Add-Line $page 5.50 4.70 5.50 4.25
    Add-Line $page 5.50 3.45 5.50 3.00

    Drop-Shape $page $masters 'Rounded Rectangle' 5.50 7.45 2.00 0.55 '开始' 12
    Drop-Shape $page $masters 'Parallelogram' 5.50 6.35 6.80 0.80 '输入数据：参数、边界条件、实验表格' 11 'RGB(246,250,253)' 'RGB(61,111,151)'
    Drop-Shape $page $masters 'Rectangle' 5.50 5.10 5.80 0.80 '建立统一模型框架' 12 'RGB(255,255,255)' 'RGB(61,111,151)'
    Drop-Shape $page $masters 'Diamond' 5.50 3.85 2.50 0.85 '是否满足判据？' 11.5 'RGB(255,255,255)' 'RGB(61,111,151)'
    Drop-Shape $page $masters 'Rounded Rectangle' 5.50 2.65 2.00 0.55 '结束' 12

    $doc.SaveAs($VsdxPath)

    try {
        $doc.ExportAsFixedFormat(1, $PdfPath, 1, 0)
    } catch {
        Write-Warning "PDF 导出失败：$($_.Exception.Message)"
    }

    $page.Export($PngPath)
    $page.Export($SvgPath)
    $page.Export($EmfPath)

    Write-Output "VSDX=$VsdxPath"
    Write-Output "PDF=$PdfPath"
    Write-Output "PNG=$PngPath"
    Write-Output "SVG=$SvgPath"
    Write-Output "EMF=$EmfPath"
}
finally {
    if ($basic) {
        try { $basic.Close() } catch {}
    }
}

运行：

powershell -ExecutionPolicy Bypass -File D:\CodexVisio\scripts\New-VisioFlowchart.ps1

---

8. 让 Codex 知道以后优先用 Visio

在项目根目录创建：

D:\CodexVisio\AGENTS.md

写入：

# 项目自动化规则

当用户要求绘制流程图、模型关系图、技术路线图、系统架构图，并明确希望使用 Visio 时：

1. 优先使用 PowerShell 通过 `Visio.Application` COM 自动化控制 Microsoft Visio。
2. 生成可编辑 `.vsdx`，并按需要导出 `.pdf/.emf/.svg/.png`。
3. 绘图时先画连接线，再画节点，避免线条压住文字。
4. 节点文字字号不得过小。报告插图正文建议不低于 10.5 pt，标题建议 16 pt 以上。
5. 导出后必须检查预览图，重点检查文字遮挡、连线穿字、字体缺失、图形越界。
6. 如果同名 `.vsdx` 正在 Visio 中打开，不要直接覆盖。改用新文件名，或先确认关闭旧文档。
7. 默认保留 Visio 窗口可见，让用户可以实时观察绘图过程。

这样 Codex 进入这个目录工作时，会更容易遵守你的 Visio 绘图习惯。

---

9. 可选：创建一个个人 Skill

如果你希望在任何项目里都能复用这套规则，可以创建个人 skill。

建议路径：

C:\Users\<你的用户名>\.codex\skills\visio-automation\SKILL.md

示例内容：

---
name: visio-automation
description: Use when the user asks Codex to draw, edit, export, or verify Microsoft Visio diagrams through local Windows desktop automation.
---

# Visio Automation

当用户要求使用 Visio 绘图、修改 `.vsdx`、导出流程图、技术路线图、模型关系图时，优先使用本技能。

## 默认路线

Codex -> PowerShell -> `Visio.Application` COM -> Microsoft Visio 桌面版

## 执行规则

1. 先检查 `New-Object -ComObject Visio.Application` 是否可用。
2. 让 `$visio.Visible = $true`，方便用户实时观察。
3. 优先生成 `.vsdx`，再导出 `.pdf/.emf/.svg/.png`。
4. 先画连接线，再放节点，避免线条盖住文字。
5. 报告图中文字不得过小，正文节点建议 10.5 pt 以上。
6. 导出后检查 PNG 或 PDF 页面，确认无文字压线、重叠、越界、乱码。
7. 遇到文件占用时不要强行覆盖，使用带版本号的新文件名。

以后你可以对 Codex 说：

使用 visio-automation skill，把这个模型流程画成 Visio 图，并导出 PDF 和 EMF。

---

10. Codex 任务提示词模板

以后换电脑后，可以直接这样对 Codex 下任务：

调用本机 Microsoft Visio 桌面版绘制一张专业报告可用的模型关系流程图。

要求：
1. 使用 PowerShell + Visio.Application COM 自动化。
2. Visio 窗口保持可见，我要实时查看过程。
3. 输出可编辑 .vsdx。
4. 同时导出 .pdf、.emf、.svg、.png。
5. 字号适合 Word 报告插图，正文节点不低于 10.5 pt。
6. 连接线不能穿过文字。
7. 导出后检查 PNG 预览，发现压线、重叠、太小、越界要继续修。
8. 文件保存到当前项目的 output 或 流程图输出 文件夹。

如果你有具体内容，再加：

图中内容如下：
......

---

11. 实时观察 Codex 绘图

如果脚本里有：

$visio.Visible = $true

你就可以打开屏幕实时看到 Visio。

需要注意：

• Codex 通过 COM 操作时，很多动作会瞬间完成，不一定像人工一样逐字输入。
• 如果绘图很复杂，可能是几秒或几十秒后突然出现完整图。
• 如果你正在手动操作同一个 Visio 文档，可能和脚本冲突。
• 如果同名文件已经打开，保存时容易报文件占用或句柄错误。

---

12. 文件导出建议

不同格式的用途：

格式	用途	推荐程度
.vsdx	可编辑 Visio 原文件	必须保留
.emf	插入 Word/WPS 报告，缩放清晰	强烈推荐
.svg	矢量图，适合新版 Word 和网页	推荐
.pdf	定稿预览、论文附件、交付检查	推荐
.png	快速预览、聊天发送	仅作预览

正式报告优先插入 .emf 或 .svg。

不要优先用低分辨率 .png，因为放进 Word 后容易发糊。

---

13. 常见故障排查

13.1 找不到 COM 对象

报错类似：

Cannot create ActiveX component

排查：

New-Object -ComObject Visio.Application

可能原因：

• 没安装 Visio 桌面版。
• 安装的是网页版或精简版。
• Office 安装损坏。
• 当前用户没有正常注册 Visio COM。

处理：

• 打开 Visio 一次，完成首次启动配置。
• 运行 Office 修复。
• 重新安装 Visio 桌面版。

13.2 基础图形模板找不到

报错类似：

找不到 Visio 基础图形模板 BASIC_M.VSSX 或 BASIC_U.VSSX。

查找模板：

Get-ChildItem 'C:\Program Files\Microsoft Office\root\Office16\Visio Content' -Recurse -Filter 'BASIC*.VSSX'

常见路径：

C:\Program Files\Microsoft Office\root\Office16\Visio Content\2052\BASIC_M.VSSX
C:\Program Files\Microsoft Office\root\Office16\Visio Content\1033\BASIC_M.VSSX

2052 通常是中文资源，1033 通常是英文资源。

13.3 保存时报文件占用

常见原因：

• 同名 .vsdx 已经在 Visio 中打开。
• 上一次脚本生成的 Visio 进程还在。
• 文件同步软件正在锁定文件。

检查进程：

Get-Process VISIO -ErrorAction SilentlyContinue

稳妥处理：

• 使用新文件名，例如加 _v2、_终稿。
• 手动关闭旧 Visio 文档。
• 不要用脚本强制杀进程，除非确认没有未保存的重要文件。

13.4 文字压线或卡到形状边框

处理原则：

• 先画线，再画节点，让节点覆盖线条。
• 连接线不要穿过文字区域。
• 标签不要直接放在线上，放在线旁边。
• 增大图形宽高和文字边距。
• 正文节点字号不要低于 10.5 pt。

关键设置：

Set-CellFormula $shape 'TxtMarginLeft' '0.12 in'
Set-CellFormula $shape 'TxtMarginRight' '0.12 in'
Set-CellFormula $shape 'TxtMarginTop' '0.06 in'
Set-CellFormula $shape 'TxtMarginBottom' '0.06 in'

13.5 中文字体显示异常

优先设置：

Set-CellFormula $shape 'Char.Font' '"Microsoft YaHei"'

如果新电脑没有微软雅黑，可以换成：

Set-CellFormula $shape 'Char.Font' '"SimSun"'

或：

Set-CellFormula $shape 'Char.Font' '"DengXian"'

13.6 PowerShell 不允许运行脚本

临时运行：

powershell -ExecutionPolicy Bypass -File D:\CodexVisio\scripts\New-VisioFlowchart.ps1

只对当前用户放宽：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

13.7 Visio 弹窗卡住

脚本里设置：

$visio.AlertResponse = 7

这可以自动响应一部分保存覆盖、关闭确认等弹窗。

但涉及登录、许可证、首次启动、宏安全等弹窗时，仍建议人工先打开 Visio 处理一次。

---

14. 高质量绘图规范

给报告用的 Visio 图，建议遵守：

• 标题 16 到 20 pt。
• 节点正文 10.5 到 12 pt。
• 少用大段文字。节点里只放关键词，详细解释放正文。
• 横向图适合宽页面，纵向图适合 Word 单栏插图。
• 连接线必须避开文字。
• 同一层级节点尺寸保持一致。
• 同一类型节点使用同一形状，例如输入用平行四边形，判断用菱形，过程用矩形。
• 输出文件名使用稳定命名，例如 模型关系流程图_报告版_终稿.vsdx。
• 每次导出后必须看 PNG 或 PDF 预览。

---

15. 最佳工作流程

建议你让 Codex 按这个流程干活：

1. 读取需求和正文口径
2. 先写绘图脚本
3. 调用 Visio 生成 .vsdx
4. 导出 .png/.pdf/.emf/.svg
5. 查看预览图
6. 检查文字是否压线、字号是否过小、图形是否越界
7. 修脚本
8. 重新生成
9. 交付最终文件

这样比"直接手工拖图形"稳定得多，因为脚本可以重复运行，也方便后续批量修改。

---

16. 一句话总结

换电脑后，只要完成三件事，就能让 Codex 自主调用 Visio 绘图：

安装 Visio 桌面版 -> 确认 Visio.Application COM 可用 -> 让 Codex 运行 PowerShell 绘图脚本

真正推荐长期使用的是：

项目 AGENTS.md 规则 + scripts 目录模板 + output 输出目录 + 每次导出后视觉核查

这样你就能在新电脑上复现"Codex 自动打开 Visio、绘制专业流程图、导出报告插图"的完整工作流。