visio-image-rebuilder

Visio 图像重建

核心规则

将参考图重建为可编辑的 Visio 内容。不要通过将整张参考图插入页面来满足重建请求。只有将参考图作为临时锁定的描摹图层，并在交付前移除或隐藏，才允许嵌入参考图；最终的 .vsdx 必须保留为原生形状、文本、连接线和组合。

将 .vsdx 视为事实来源。只有在 Visio 页面完成重建或样式调整，并确认其可原生编辑后，才能导出 PNG、SVG、PDF 或 PPTX。

工作流

1. 检查输入。

   • 确认目标 .vsdx、参考图、所需输出格式和输出目录的路径。
   • 如果目标文件已存在，编辑前先将当前 Visio 页面导出为 PNG。
   • 检查 .vsdx 包中的页面、媒体条目和形状数量。
   • 写入前备份目标文件。
   • 如果 Visio 已打开，只关闭目标文档；若进程卡住，则先询问再终止。

2. 解读参考图。

   • 确定页面方向、面板边界、模块颜色、说明文字、文本层级、箭头、虚线和重复图案。
   • 建立对象清单：容器、标题、流程框、图标、图表、图形、公式、连接线和说明文字。
   • 先校准画布，再使用明确的左上角边界或四个角点校准每个主要面板或子面板。
   • 如果图中包含密集的多面板内容，面板内部优先使用面板局部归一化坐标绘制。
   • 判断任务属于完整重建、颜色／样式迁移、局部编辑还是仅导出。
   • 对于密集的科学图表，先绘制粗略的面板布局图，再绘制面板内部内容。不要从小型装饰细节开始。

3. 原生编辑优先使用 Visio 自动化。

   • 在安装了 Visio 的 Windows 上使用 COM 自动化。
   • 仅对小型源素材使用 DrawRectangle、DrawOval、DrawLine、Page.Import，并使用 FillForegnd、LineColor、LineWeight、Char.Size、Char.Color、Rounding 等形状单元格。
   • 对易出错的编辑使用明确的坐标和 ID。
   • 保持组合结构清晰且有意义：主要面板、子模块、重复区块和图例。
   • 对于嵌套模块，使用 RectRel、TextRel、LineRel 和 OvalRel 等辅助函数，使子形状受其已校准的父面板约束。

4. 仅对范围有限且确定的更改使用包 XML 编辑。

   • XML 修补适用于为现有形状重新着色、替换字体表或更改已知单元格值。
   • 保留 Visio XML 顺序：形状级别的 Cell 节点必须位于 Section、Text 或子级 Shapes 之前。
   • 除非无法使用 COM 自动化，否则避免通过原始 XML 重建复杂几何图形。

5. 从已验证的 Visio 源文件导出所需格式。

   • 对于仅导出的任务，使用 scripts/visio_page_tools.ps1。
   • 对于需要立即生成交付文件的重建任务，使用 scripts/visio_rebuild_scaffold.ps1 和 -ExportFormats。
   • 矢量网页／稿件交付优先使用 SVG，审阅／打印优先使用 PDF，演示文稿优先使用 PPTX。
   • 对于 PPTX，如可用则使用 PowerPoint COM；生成的幻灯片包含 Visio 页面渲染图，通常从 SVG 插入。

6. 验证时不要过度依赖单一信号。

   • 编辑后尽可能至少导出一张预览图。
   • 检查 .vsdx 包，确认 visio/media 中没有残留完整尺寸的参考 PNG/JPG。
   • 检查形状数量和有代表性的文本标签。
   • 检查主要面板是否重叠，以及子形状是否位于预期面板边界内。
   • 检查每个所需输出文件是否存在且非空。
   • 如果 Visio 自动化挂起，请安全停止，尽可能关闭文档，并报告文件是否确实已修改。

实现模式

对于完整重建，请生成一个脚本，用于：

• 使用 Visio COM 打开目标 .vsdx。
• 保存带时间戳或描述性名称的备份。
• 根据用户偏好清空页面或复制页面。
• 设置页面大小，使其与参考图的宽高比一致。
• 将左上角参考坐标转换为 Visio 坐标，并绘制原生形状。
• 为复杂区域定义经过校准的面板边界，并使用面板局部坐标绘制内部元素。
• 添加可复用的辅助函数，用于绘制矩形、文本框、椭圆、直线、箭头、迷你图表、图形节点和类似图像的堆叠元素。
• 保存文档并导出所需格式。

开始编写完整重建脚本时，请从 scripts/visio_rebuild_scaffold.ps1 开始。将其复制到工作区，并自定义 Draw-ReferenceFigure 函数，而不要编辑技能副本。

对于样式迁移，请生成一个脚本，用于：

• 读取现有形状 ID、文本、大致几何信息、填充颜色和线条颜色。
• 根据文本和组上下文，将已知模块映射到目标配色方案。
• 为现有形状应用填充、边框、文本颜色、线条样式和字体更改。
• 除非用户要求更改布局，否则不要重新定位形状。
• 只有在 .vsdx 保存并检查后才导出。

对于仅导出的请求，请运行：

powershell -ExecutionPolicy Bypass -File scripts\visio_page_tools.ps1 `
  -VsdxPath "C:\path\figure.vsdx" `
  -ExportFormats svg,pdf,pptx `
  -OutputDir "C:\path\exports" `
  -InspectPackage

对于重建并导出多种格式的请求，请运行：

powershell -ExecutionPolicy Bypass -File scripts\visio_rebuild_scaffold.ps1 `
  -VsdxPath "C:\path\figure.vsdx" `
  -PageW 16 `
  -PageH 9 `
  -RefW 1600 `
  -RefH 900 `
  -PreviewPath "C:\path\exports\figure.png" `
  -ExportFormats svg,pdf,pptx `
  -OutputDir "C:\path\exports"

安全检查清单

• 在工作区之外写入文件前先备份。
• 直接编辑程序包前，关闭所有会锁定目标文件的已打开 Visio 文档。
• 切勿删除或还原与任务无关的用户文件。
• 如果先前的尝试嵌入了参考图像，请从备份还原，或在继续前移除图像形状。
• 明确告知用户最终文件是可原生编辑的形状，还是扁平化的嵌入图像。
• 如果 PPTX 导出的是渲染后的幻灯片，而非原生 PowerPoint 形状，请告知用户。

验收标准

只有满足以下条件，Visio 重建才可接受：

• 乍看之下，主要面板位置、流程方向、说明文字和模块层级均与参考图一致。
• 主要面板与校准后的边界对齐，子模块没有明显偏移、碰撞或跨面板重叠。
• 文本仍可编辑，并使用统一的学术字体，通常为 Times New Roman。
• 重复图案使用可复用的原生形状表示，而不是粘贴的栅格图像裁剪。
• 最终 .vsdx 程序包的 visio/media 中没有整页栅格参考图像。
• 所需的 PNG/SVG/PDF/PPTX 交付文件均从保存后的 .vsdx 导出，且文件非空。
• 已执行预览导出或程序包检查；若跳过验证，最终回复须明确说明原因。

实用资源

使用 scripts/visio_page_tools.ps1 执行常见检查、备份、预览导出、多格式导出和程序包检查。自定义任务脚本需要可复用的导出辅助函数时，使用 scripts/visio_export_formats.ps1。编写原生形状绘制脚本时，请从 scripts/visio_rebuild_scaffold.ps1 开始；其中包含全局左上角辅助函数和面板局部校准辅助函数。需要完整重建图形或谨慎地一对一匹配科学示意图时，请阅读 references/rebuild-guidelines.md。