baoyu-diagram实战：生成可缩放、可核查的技术SVG图

当读者需要检查组件、箭头和关系时，位图并不够。baoyu-diagram 专门输出独立 SVG，用统一的暗色设计系统表达架构、流程、时序、结构、思维导图、时间线、状态机和数据流。

本文基于固定提交源码核对；案例为操作示例，非付费服务或账号实测。没有实际绘图、转换或发布。

一、场景与边界

适合系统架构、请求流程、服务关系、决策树、状态流转和技术文档中的结构图。SVG 是文本文件，能够缩放、被版本控制，也便于检查连接是否指向正确节点。

边界很明确：输出规则是单个自包含 .svg，仅允许 Google Fonts 导入作为外部依赖；默认还建议通过脚本生成 @2x PNG，但 PNG 是派生物，不替代 SVG 源文件。它不是 Mermaid 渲染器，也没有声明会读取 Mermaid 语法；让 Agent 直接描述参与者、顺序、关系和布局更稳妥。

需要真实数据看板或装饰性大图时，分别考虑信息图或文章配图。不要把流程图要求交给纯图片生成模型，因为技术标签、箭头和精确关系难以稳定验收。

二、前置依赖与按需安装

只生成 SVG 时，通常需要能写文件的 Agent，不需要图像模型。若要执行源码提供的 SVG 转 PNG 脚本，需要 bun，没有时源码指示使用 npx -y bun；脚本依赖 sharp，应由项目依赖环境提供。

仓库技能安装入口经 README 核实：

1	npx skills add jimliu/baoyu-skills --skill baoyu-diagram --agent codex

Claude Code 用户可将 codex 替换为 claude-code。

只选 baoyu-diagram 即可。若要使用项目级 Codex 发现机制，复制完整目录到 .agents/skills/baoyu-diagram/，保留 references/ 和 scripts/。本文不实际安装依赖；“按需安装”表示在用户确认后由其环境执行。

三、输入输出和结构约束

输入可以是一份 Markdown 技术说明、架构描述或自然语言关系清单。最小有效输入应有：节点名称、节点类型、连接方向、连接标签、分组边界和期望的图类型。模糊写“画一个好看的系统图”会迫使 Agent 猜测关键关系，不适合严肃文档。

输出规则包括：

一个带 xmlns 的根 <svg>。
viewBox 覆盖全部内容并四周留出 30px。
不设置固定 width、height，让 SVG 响应式缩放。
<style>、<defs>、箭头 marker 和网格 pattern 位于顶部。
绘制顺序依次是背景、分组、连线、遮挡矩形、节点、文字、图例和标题。
中文标签使用 JetBrains Mono、Noto Sans SC、PingFang SC 或 sans-serif，并增加盒宽。

输入是文件时默认保存到输入文件目录的 diagram/；粘贴内容则保存到项目 diagram/{topic-slug}/。

四、可复制的 Agent 请求

请使用 baoyu-diagram，把 api-flow.md 画成中文数据流图。
图类型是 data flow，方向从左到右：客户端、网关、订单服务、消息队列、数据库。
只使用我文件里出现的节点和关系；不补造云厂商、延迟和吞吐量。
节点按前端、服务、存储、消息和外部系统分组，箭头标注同步或异步。
先给出节点与布局计划，再写独立 SVG；检查中文不溢出、箭头不穿过节点、viewBox 有边距。
之后按源码脚本规则询问我是否需要生成 @2x PNG；不要发布文件。

如果只要源文件，补充“只输出 SVG，不执行 PNG 转换”。如果希望图进入 Hexo，应另外指定附件目录，而不是让 Agent 猜测发布系统如何复制文件。

五、案例：订单数据流图

先从原文抽取五类对象。客户端是 Primary，订单服务是 Secondary，数据库是 Tertiary，队列是 Connector，第三方支付可用 Neutral 或 Accent。颜色只是语义提示，不能代替箭头标签；“支付回调”仍需明确方向。

布局采用左到右：客户端位于左，网关和业务服务居中，队列与数据库位于右侧或下方。节点之间至少保留 30px 水平、40px 垂直间距；分组边界向内留 20px。连线先画，再用与背景同色的遮挡矩形盖在节点下面，最后画半透明节点，避免箭头从盒子内部穿出来。

中文标签会占更宽空间。不要只把英文字体大小替换成中文后仍沿用原宽度；先估算最长标签，再扩大组件。标题 16px，组件名约 11 至 12px，描述 9px，箭头小标签 7 至 8px，只是源码建议值，复杂图仍以可读性优先。

生成后逐层验收：是否有孤立节点，是否有反向箭头，是否把异步队列画成同步直连，图例是否压住边界，viewBox 是否截掉标题或底部。技术图必须可以反向阅读：任何一条线都应能在输入说明中找到依据。

若需要 PNG，源码脚本入口已经核实，形式如下（替换实际绝对路径）：

1	bun C:/path/to/baoyu-diagram/scripts/main.ts C:/path/to/diagram.svg --scale 2 --json

在 Windows 环境也可以按项目约定使用 npx -y bun 代替 bun。--scale 默认 2，--output 可以指定输出路径；--json 返回结果信息。此处不执行命令。

六、设计系统与修改策略

背景是 #0f172a，配细网格；Primary、Secondary、Tertiary、Accent、Alert、Connector、Neutral、Highlight 有固定语义色。流程图和时序图可以按角色而不是技术栈分色。统一规则比“每个节点随机一个颜色”更重要。

图形类型需先读对应参考：架构图强调层次和区域，流程图使用菱形判断并标注 Yes/No，时序图按时间向下、同步实线异步或返回虚线，结构图用组合、聚合和继承关系，状态机使用初始实心点、终止靶心和带事件的转移标签。任务不明确时先问图类型，不要直接套架构图。

修改时优先回到源 SVG。可以移动节点、改标签、调整 viewBox，再重新生成 PNG；不要只改派生 PNG。图例应放最低元素下方至少 20px，标题块距左上 20px。博客主题的图片路径需同时让 Obsidian 与 Hexo 可见，建议在同一附件目录保留 .svg 和可选 .png。

七、验收清单与排错

[ ] 图类型匹配问题，节点和连接均来自输入事实。
[ ] SVG 单文件可独立打开，根元素、样式、marker 和 viewBox 齐全。
[ ] 无节点重叠、连线穿盒、文字溢出和被裁切内容。
[ ] 中文字体回退链存在，缩放后标签仍可读。
[ ] PNG 若存在，是由当前 SVG 派生，尺寸和路径清楚。
[ ] Obsidian 与 Hexo 均按相对路径找到目标文件。

PNG 转换报找不到尺寸：检查 SVG 是否有有效 viewBox 或宽高，源码脚本会拒绝无法判断尺寸的输入。图在浏览器有字体、博客没有：依赖 Google Fonts 不适合离线发布，准备本地字体回退或接受系统字体差异。箭头显示在节点上方：检查图层顺序和背景遮挡矩形。长中文拥挤：扩大盒子和 viewBox，不要盲目缩小字体。转换脚本依赖缺失：只在用户允许时补装 Bun/项目依赖，SVG 本身仍可交付。