本文要点
- diagram-design 当前导出说明给出的 PNG 默认设备缩放比例是 2；例如，宽高为 1280 × 720 的 viewBox 按比例导出后是 2560 × 1440 像素。([官方导出说明](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md))
- 症状：浏览器预览没问题，但 SVG 或 PNG 文件缺字、被裁切，或者连线关系可疑。
- 最快解法：先核对源 HTML 和图的语义，再分别检查 SVG 结构与 PNG 渲染；不能把预览正确当成交付正确。
- 这篇文章适合要把 AI 架构图放进文档、演示或代码库的工程师；负责检查多格式文件的文档维护者；以及希望把导出验证纳入自动化流程的平台人员。
diagram-design 当前导出说明给出的 PNG 默认设备缩放比例是 2；例如，宽高为 1280 × 720 的 viewBox 按比例导出后是 2560 × 1440 像素。(官方导出说明)
症状：浏览器预览没问题，但 SVG 或 PNG 文件缺字、被裁切，或者连线关系可疑。 最快解法：先核对源 HTML 和图的语义，再分别检查 SVG 结构与 PNG 渲染；不能把预览正确当成交付正确。
这篇文章适合要把 AI 架构图放进文档、演示或代码库的工程师；负责检查多格式文件的文档维护者；以及希望把导出验证纳入自动化流程的平台人员。
diagram-design SVG PNG 导出验收：先定位异常首次出现在哪一层
预览、源文件和导出文件不是同一份验收证据。diagram-design 的官方仓库与导出说明显示，SVG 导出从 HTML 中提取图形节点；PNG 则通过浏览器自动化对图形截图。两条路径经过的处理不同，不能因为其中一种格式正确，就推断另一种也通过。
先记下源 HTML、导出命令、输出路径、工具版本和目标文档，再对照原始文件、浏览器预览与最终交付物，判断异常最早在哪一步出现。下面这张表用来区分问题类型，避免一上来就重画图或盲目重跑。
| 看到的症状 | 优先检查 | 可能的故障层 | 下一步 |
|---|---|---|---|
| HTML 正常，SVG 颜色或文字异常 | SVG 中的样式、引用和 ID | SVG 提取或样式转移 | 检查原始 HTML 与导出 SVG 的对应节点 |
| HTML 与 SVG 正常，PNG 缺字或边缘被切 | 字体、缩放、视口与容器溢出 | 浏览器渲染或截图范围 | 固定环境复测，保存 PNG 和日志 |
| 三种文件都画出了相同但可疑的关系 | 节点、箭头与事实来源 | 图表语义 | 对照代码、接口约定或设计说明 |
| 流水线偶发缺图，开发机正常 | 依赖、运行版本、字体加载与输出路径 | 构建环境或任务执行 | 固定输入并复现流水线命令 |
SVG 导出要检查结构、样式与引用是否完整
检查 SVG 时，不要只看文件能否打开。至少核对根 <svg> 节点、xmlns 命名空间和 viewBox 是否存在；文字内容、样式规则和 <defs> 中被引用的渐变、裁剪路径或箭头标记是否保留；id 是否重复，以及引用是否仍指向正确目标。W3C 的 SVG 结构规范要求 SVG 树中的 id 唯一；diagram-design 的导出说明也把命名空间、视图范围、样式转移和 ID 处理列为导出步骤。
样式是常见盲点。SVG 可以包含内嵌 <style>，但如果图形依赖 HTML 外部的 CSS 文件或页面选择器，导出成独立文件后就可能无法沿用原先的样式。检查 HTML 里的规则是否被带进 SVG，不要只凭预览时的颜色判断导出成功；可对照 MDN 关于 SVG <style> 元素的说明。
当前官方导出文档说明 SVG 辅助脚本会处理 CSS 转移和 defs ID 命名空间，并对仍有 class、却没有对应图表 CSS 规则的结果设置检查门槛。你应以项目仓库当前说明和实际生成文件为准；不要把这些步骤扩写成未声明的兼容承诺。
| 验收对象 | 通过条件 | 失败时如何定位 |
|---|---|---|
| 根节点与视图范围 | 有 SVG 命名空间，viewBox 与图形范围相符 | 回到源 HTML，对比提取前后的根节点属性 |
| 样式 | 独立打开后颜色、线宽、文字样式仍符合预期 | 搜索外部 CSS 依赖及缺失的内嵌规则 |
| defs 与引用 | 渐变、标记、裁剪路径等引用存在且指向正确对象 | 检查 url(#...)、href 与定义的 ID 是否匹配 |
| 唯一标识 | 不同元素的 id 不重复 | 检查多图合并或复用时是否发生命名冲突 |
| 可访问描述 | 原有标题与描述未无故丢失 | 对照源图中的 <title>、<desc> 等文本 |
PNG 不一致时，把字体、缩放和裁切分开复测
PNG 是像素图，文字最终外观受渲染环境影响。源 HTML 可能依赖外部字体，截图环境却没有成功加载；设备缩放比例不同也会改变像素尺寸；此外，父容器的 overflow 设置可能裁掉图形边缘。diagram-design 当前导出说明要求 PNG 走浏览器渲染，并特别提示字体加载和裁切祖先可能影响截图。
先固定同一份 HTML、同一导出命令与缩放参数，在本地和目标流水线各跑一次，再逐项比较字体、画布尺寸、留白、边缘和颜色。浏览器截图工具会区分 CSS 像素与设备像素，因此比较结果时要一并记录缩放设置，不能只比较两张图片的文件大小；相关概念可参照 Playwright 页面截图接口说明。
当前仓库命令说明列出的 PNG --scale 参数可用值为 1、2、3，默认比例为 2；但这只是该工具当前命令的参数，不等于所有浏览器或截图工具都采用同样默认值。若目标是特定像素尺寸，先确认源图 viewBox 的宽高比例，再确定导出倍率，避免靠裁切补救比例不匹配。具体参数以导出命令文档为准。
架构关系有疑问时，回到事实来源而非视觉效果
导出的图即使完整、清晰，也可能把组件关系画错。比如，一张服务调用图把异步消息画成同步请求，或者把“可选依赖”画成必需依赖；这些错误不会因为 SVG 通过结构检查、PNG 没有裁切就自动消失。
可以把每条连线拆成独立事实：起点是什么组件、终点是什么组件、方向表示什么、关系是已实现还是计划中。然后逐条对照代码调用、接口定义、需求文档或已确认的架构说明。找不到依据的部分标成“待核实假设”，不要让 Agent 用看起来合理的组件或关系补齐缺失信息。
这种复核不必覆盖每个像素，重点是会影响读者判断的边界：调用方向、数据流方向、同步与异步、信任边界、组件归属，以及图例对线型或颜色的解释。若来源彼此矛盾，先让负责人确认事实版本，再更新图表；不要选外观最整齐的版本作为结论。
用六步流程把导出验收纳入交付
- 冻结输入。保留生成后的 HTML，记录导出命令、相关版本、输出路径与运行环境；后续复测不要覆盖唯一源文件。
- 单独核验源 HTML。确认预期图形实际存在、文字完整，并检查页面中的图形是否受父级滚动容器、隐藏状态或外部资源影响。
- 复核 SVG。对照根节点、
viewBox、文字、样式、defs 引用和唯一 ID；除视觉打开外，还应检查文件能否作为 XML 解析。 - 复测 PNG。使用同一份输入在本地和流水线分别导出，确认字体加载状态、截图范围和缩放参数；将 PNG 与 SVG、HTML 并排查看，留存差异截图。
- 做语义核查。对关键节点和连线逐条附上代码、接口约定或设计说明依据；无法证实的关系明确标为假设，而不是当作已验收事实。
- 设定流水线门槛。自动判断命令是否成功、输出文件是否存在且非空、SVG 是否能解析、图片尺寸是否符合项目要求；把源 HTML、日志和导出结果作为流水线产物保存，供失败后复现。工作流产物适合保存构建输出、测试结果与截图，但它们本身不能代替人工对图意的确认；可参照 GitHub Actions 工作流产物说明。
如果你用的是该仓库命令，当前说明支持通过 --svg-only 或 --png-only 指定格式；没有格式标记时按默认行为生成两种图像。建议将参数写进流水线配置并保存实际命令行，而不是只留一句“导出失败”，这样开发机和目标环境才有可比条件。
当图表需要与远程 Agent 生成的代码或文档一起验收时，你可以把 HTML、导出图和运行日志放进同一交付记录。若你还在评估 kvmboot 的远程工作流程，可先阅读关于 kvmboot 的服务说明，并通过帮助中心确认适用场景；远程 Mac 更适合需要复现特定 macOS 环境或隔离测试的工作，不是所有导出故障的修复手段。与本地临时环境相比，它可能减少机器环境不一致和共享开发机的干扰，但仍需核对字体、依赖和导出器版本；如果你已有稳定环境、无需远程协作，直接在现有机器完成复测通常更简单。租用 kvmboot 的 Mac 可以作为临时复现与交付环境选项，而不应取代对源图、导出结果和架构事实的验收。
常见问题
HTML 预览正常、PNG 却不一样时，先判断什么？
先确认截图实际使用的浏览器与字体是否就绪，再比较缩放比例、截图范围和父级容器的裁切设置。相同输入在本地和流水线复测，若 HTML 一致而 PNG 差异稳定出现，问题更可能位于渲染条件；记录参数并保存输出，才能让其他人复现。
怎样快速确认 SVG 是否完整？
不仅要检查能否打开，还要核对 viewBox、命名空间、文字和样式，以及 <defs> 中的引用目标。检查重复 ID 和外部 CSS 依赖，再将单独打开的 SVG 与原 HTML 对照；结构检查通过，只能说明文件层面较完整，不能证明架构关系正确。
架构图的线看着正常，但含义错了怎么办？
暂停发布并回到代码、接口约定或明确的设计说明，分别确认连线两端、方向和关系类型。没有来源支持的边标记为待核实，不能因为绘图工具成功生成或导出文件通过检查就视为事实。
怎样把 diagram-design 的图表导出检查放进 CI？
在流水线中运行固定的导出命令，检查任务退出状态、目标文件、SVG 解析结果和项目要求的图像尺寸，并保存源 HTML、日志与导出文件。自动化负责文件与生成流程，人眼和代码证据负责可读性及关系含义；任何一类失败都应阻止交付或进入人工复核。
在真实 Mac 环境中复核架构图导出
通过 kvmboot 租用独享 M4 云端 Mac，在 macOS 桌面中检查 SVG 结构与 PNG 渲染效果。
用规格驱动开发把验收条件、验证步骤和交付证据串起来 · AI 结构化输出的验收方法：用 JSON Schema 检查数据契约 · 梳理 AI Agent 架构中的模型、工具契约与执行边界