baoyu-diagram 流程图（Flowchart）SVG 绘制规范与实战指南
【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills
本文是基于 baoyu-skills 仓库中baoyu-diagram技能的 Flowchart 布局参考文档（skills/baoyu-diagram/references/flowchart.md）展开的深度实战指南。它系统讲解如何在 dark 主题下用纯 SVG 绘制专业流程图的形状词汇、布局算法、间距规范、判定分支标注与配色策略，并延伸到复杂流程图的分组技巧、输出到 @2x PNG 的完整工具链。读完本文，你既能照规范手写可复制的流程图 SVG，也能理解baoyu-diagram技能内部的完整设计系统与渲染原理。
Flowchart 在 baoyu-diagram 技能中的定位
baoyu-diagram是一个面向 AI Agent 的通用 SVG 图表生成技能，支持架构图、流程图、时序图、结构图、思维导图、时间轴、状态机等十余种图表类型。在 SKILL.md 中，Flowchart（流程图）被定位为"处理决策逻辑与流程步骤"的核心图表类型，其特征是：菱形决策节点、圆角流程步骤框、方向性流程箭头。
技能约定：开始绘制前，Agent 必须读取{baseDir}/references/下对应类型的参考文档（{baseDir}即SKILL.md所在目录），其中 Flowchart 对应的就是flowchart.md，文档内给出的关键点是：
- 主流程自上而下（top-to-bottom）
- 决策用菱形节点，出口箭头上标注 Yes/No
- 开始/结束用圆角矩形
- Happy path（主线路径）使用 Highlight（蓝色）强调色
所有输出均为单个自包含的.svg文件，内嵌样式与字体，不依赖任何外部资源（除 Google Fonts 导入外）。
形状词汇表：五种基本形状及其 SVG 实现
绘制流程图的第一步是掌握形状语义。flowchart.md定义了五种核心形状，每种形状都有固定的 SVG 元素实现方式：
| 形状 | 语义 | SVG 元素 |
|---|---|---|
| 大圆角矩形 | 开始 / 结束节点 | <rect rx="25"> |
| 普通矩形 | 流程步骤 / 动作 | <rect rx="6"> |
| 菱形 | 决策 / 分支 | 旋转 45° 的<polygon> |
| 平行四边形 | 输入 / 输出 | 带 skew 的<polygon> |
| 圆柱体 | 数据存储 | 椭圆 + 矩形组合 |
从源码角度看，决策菱形在 SKILL.md 中给出了标准的 70px 高实现模板：
<g transform="translate(CX, CY)"> <polygon points="0,-35 50,0 0,35 -50,0" fill="#0f172a"/> <polygon points="0,-35 50,0 0,35 -50,0" fill="rgba(120,53,15,0.3)" stroke="#fbbf24" stroke-width="1.5"/> <text y="4" fill="white" font-size="10" font-weight="600" text-anchor="middle">Condition?</text> </g>这里体现了一个贯穿全技能的双层绘制技巧：先画一个同形状、不透明背景色（#0f172a，即 slate-900 背景色）的"遮罩层"，再画半透明填充的"视觉层"。因为组件填充是半透明的，如果不先铺遮罩，底层的箭头和连线会透出来。数据存储圆柱体（Database Cylinder）同样遵循这一模式：不透明rect+ 上下两个ellipse构成遮罩，再用半透明紫（Tertiary 色系，rgba(76,29,149,0.4)+ 描边#a78bfa）绘制视觉层。
流程方向：主流程自上而下，分支左右展开
flowchart.md明确规定 Flowchart 的主流程方向为top to bottom（自上而下）：
- 主流程沿中心轴垂直向下延伸；
- 分支流程从决策节点向左右两侧展开。
这与架构图（支持 LTR 或 TTB 两种主方向）不同——流程图是"单主方向 + 横向分支"的混合布局。因此在实际绘制时，中心列始终留给主线，两侧空间预留给分支与回路。
布局算法：四步规划一张不重叠的流程图
flowchart.md给出了流程图布局的四步算法，它是整个绘制的骨架：
- 识别主路径（happy path / 最常走路径）：它沿中心轴直线向下贯穿整张图，是视觉上的主干；
- 从决策节点产生分支："Yes" 分支继续沿中心向下，"No" 分支向右（空间紧张时向左）展开；
- 合并路径：用 L 形连接器将分支路由回主路径；
- 回环（Loop-back）：在图表最左侧或最右侧，用曲线路径向上折返。
L 形连接器在 architecture.md 中有对应的路径模板，流程图的合并分支可以复用同样的手法：
<path d="M x1,y1 L midX,y1 L midX,y2" fill="none" stroke="#64748b" marker-end="url(#arrow)"/>即先沿 x 方向水平走一段（L midX,y1），再垂直折回主路径（L midX,y2），保证连线只走水平/垂直两段，不与组件相交。
间距规范：一张可复用的数值表
间距是防止节点重叠的硬性约束，flowchart.md给出的关键数值如下：
| 项目 | 数值 |
|---|---|
| 步骤之间垂直间距 | 60-80px（足够容纳箭头 + 可选标签） |
| 决策菱形高度（顶点到顶点） | 70px |
| 决策菱形宽度（顶点到顶点） | 100px |
| 分支相对中心的水平偏移 | 200px |
| 合并连接器的净空 | 距任何盒子 20px |
这些数值与 SKILL.md 的全局间距规则相互印证：标准组件盒高度 50-70px、组件间最小垂直间距 40px、水平间距 30px、箭头标签距盒边 10px、图例至少低于最低元素 20px、viewBox四周保留 30px 内边距。绘制完成后应统一校验：无重叠、图例在边界外、viewBox 足够大。
判定标签：Yes/No 出口箭头标注规范
决策节点出口箭头的标签是流程图可读性的关键。规范要求：将 "Yes" / "No"（或 "True" / "False"、"是" / "否"）直接放置在出口箭头上，距离菱形边缘 10px处。flowchart.md给出了完整的双分支标注示例（决策菱形中心位于 (400, 200)）：
<!-- Decision diamond at center (400, 200) --> <!-- Yes: downward --> <line x1="400" y1="235" x2="400" y2="300" stroke="#64748b" marker-end="url(#arrow)"/> <text x="412" y="260" fill="#34d399" font-size="8">Yes</text> <!-- No: rightward --> <line x1="450" y1="200" x2="550" y2="200" stroke="#64748b" marker-end="url(#arrow)"/> <text x="480" y="193" fill="#fb7185" font-size="8">No</text>该示例同时体现了配色策略的语义化运用：
- Yes / 主路径使用 emerald（
#34d399，Secondary 色）标注； - No / 异常分支使用 rose（
#fb7185，Alert 色）标注。
箭头引用了url(#arrow)标准箭头 marker。该 marker 在 SKILL.md 中定义如下：
<marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"> <polygon points="0 0, 10 3.5, 0 7" fill="#64748b"/> </marker>orient="auto"保证箭头方向随线段走向自动旋转；需要彩色箭头时，按相同结构复制出arrow-cyan、arrow-emerald等按色命名的 marker 即可。
配色策略：按角色分配语义色
流程图的配色按角色（actor / decision / process）而非按技术栈分配，这是baoyu-diagram对流程图和时序图的统一要求。flowchart.md的配色规则为：
| 元素 | 颜色 | 说明 |
|---|---|---|
| 开始/结束节点 | Highlight（蓝色#60a5fa） | 强调入口与出口 |
| 流程步骤 | Primary（cyan#22d3ee）或 Secondary（emerald#34d399） | 常规处理步骤 |
| 决策菱形 | Accent（amber#fbbf24） | 琥珀色天然吸引视线 |
| 错误/异常路径 | Alert（rose#fb7185）虚线箭头 | 警示语义 |
| 主路径箭头 | 比分支箭头更亮 | 通过stroke-opacity差值区分主次 |
在 SKILL.md 的全局色彩系统中，这些语义色有精确的 rgba 填充值与描边值：例如 Primary 填充rgba(8, 51, 68, 0.4)、描边#22d3ee；Accent 填充rgba(120, 53, 15, 0.3)、描边#fbbf24。绘制时决策菱形即直接使用 Accent 色填充 + 描边，流程步骤使用 Primary/Secondary，happy path 上的箭头可用stroke-opacity略高于分支箭头，形成清晰的主次视觉层级。
复杂流程图：10 步以上的三种扩展手法
当流程图超过 10 个步骤时，flowchart.md建议采用以下结构升级手段：
- 泳道（Swim lanes）：把相关步骤纵向分组成多条泳道，每条泳道是带标题栏的垂直列；
- 阶段行头（Phase row header）：在每条泳道顶部添加"阶段"行标题，标明该泳道负责的流程阶段；
- 复用架构图的区域边界模式：泳道边界使用 dashed outline 区域框，这与 architecture.md 中的 Region Boundary 完全同源。
区域边界在 SKILL.md 中的标准模板为：
<rect x="X" y="Y" width="W" height="H" rx="12" fill="none" stroke="#fbbf24" stroke-width="1" stroke-dasharray="8,4"/> <text x="X+12" y="Y+16" fill="#fbbf24" font-size="9" font-weight="600">AWS us-east-1</text>泳道场景下只需把标题文本换成阶段名（如 "订单创建"、"支付处理"、"履约发货"），并调整区域尺寸即可。多层嵌套时（如云厂商 → VPC → 可用区），还可以通过改变stroke-dasharray区分层级：外层12,4、中层8,4、内层4,4。
图层顺序：保证 SVG 正确叠放的关键
baoyu-diagram的 SVG 绘制顺序是硬性约定，流程图同样必须遵守（SVG 按从后到前绘制）：
- 背景填充 + 网格 pattern
- 区域/分组边界（虚线框）
- 连接箭头与连线
- 不透明遮罩矩形（与组件盒同位置，
fill="#0f172a"） - 组件盒（半透明填充 + 描边）
- 文本标签
- 图例（右下角或底部，位于所有边界之外）
- 标题块（左上角）
背景使用 slate-900（#0f172a）+ 40px 网格 pattern（网格线#1e293b，stroke-width="0.5"），这一深色底是整套 dark 主题设计系统的基础。
输出与交付：从 SVG 到 @2x PNG 的完整工具链
流程图 SVG 绘制完成后，baoyu-diagram技能通过 scripts/main.ts 将 SVG 转换为 @2x PNG 交付：
bun skills/baoyu-diagram/scripts/main.ts <svg-path> [options]脚本支持的选项（与 SKILL.md 中记录一致）：
-s, --scale <n>：缩放系数，默认 2；-o, --output <path>：自定义输出路径，默认<input>@2x.png；--json：以 JSON 格式输出结果（含 input、output、width、height）；-h, --help：显示帮助。
从源码看，该脚本的核心流程是：解析 SVG 的viewBox（正则viewBox="..."提取宽高，若缺失则回退读取width/height属性）→ 按scale计算目标像素尺寸 → 动态import("sharp")以density: 72 * scale栅格化 → 输出 PNG。两点值得注意：
- scale=1 时输出不带后缀（
getOutputPath中suffix = scale === 1 ? "" : "@2x"），只有非 1 的倍率才会生成@Nx后缀文件； - 运行时自动解析
${BUN_X}：若本机装了bun用bun，否则npx -y bun，都不行则提示安装 bun——这决定了即使没有全局 bun 也能运行。
输出规则方面，SKILL.md 还要求：viewBox四周保留 30px 内边距但不设固定width/height（让 SVG 响应式缩放）、根元素带xmlns="http://www.w3.org/2000/svg"、所有<style>/<defs>/marker/pattern 放在文件顶部、text-anchor="middle"保证文本居中。
中文字体与本地化标注
流程图中若出现中文标签（例如把 "Yes"/"No" 换成 "是"/"否"），必须遵循 SKILL.md 的中文支持规则：
font-family改为'JetBrains Mono', 'Noto Sans SC', 'PingFang SC', sans-serif；- 同步增大盒子宽度——CJK 字符比拉丁字符更宽，否则文本会溢出组件盒。
这一规则与flowchart.md中 "是 / 否" 标签的本地化示例相互呼应，也是国内场景绘制流程图时的常见坑点。
绘制自检清单
综合flowchart.md与 SKILL.md 的约束，一张合格的流程图 SVG 应通过以下检查：
- 布局：主路径沿中心垂直贯穿；分支左右展开；合并用 L 形连接器；回环走最外侧；
- 间距：步骤垂直间距 60-80px；菱形高 70px、宽 100px；分支偏移 200px；合并净空 20px；箭头标签距盒边 10px；
- 标签：Yes/No（或 True/False、是/否）放在出口箭头上、距菱形 10px，颜色语义正确（Yes=emerald、No=rose）；
- 配色：开始/结束用 Highlight 蓝，步骤用 Primary/Secondary，决策用 Accent 琥珀，异常路径用 Alert 玫红虚线，happy path 箭头
stroke-opacity更高； - 图层：遮罩层在连线之上、组件之下，防止半透明填充透出底层箭头；
- 文本：中文标签扩大盒宽、换用含 Noto Sans SC 的字体栈；
- 交付：保存为单文件 SVG，运行 main.ts 生成 @2x PNG，二者一并呈现给用户。
遵循这套规范，无论是 Agent 自动生成还是人工手写，都能产出布局稳定、语义清晰、可直接嵌入文档或演示文稿的深色主题流程图。
【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
