SVG 技术架构图布局最佳实践：fireworks-tech-graph 的通用布局规则与工程化校验指南

• AI 技能
• 数据可视化

本文是 fireworks-tech-graph 项目中svg-layout-best-practices.md布局规范的完整实战解读。无论你使用哪一种视觉风格（Flat Icon、Claude Warm、Blueprint 等），布局规则都是跨风格通用的硬性约束：组件间距、箭头路由、标签防碰撞、Z-Index 渲染顺序，以及最终通过校验器自动验收。读完本文，你将掌握一套可直接落地到任何 SVG 架构图（Agent 架构、微服务、时序、流程等）上的布局方法论，并能用仓库自带的validate_svg.py与validate-svg.sh把“美观”变成可度量、可自动检查的工程指标。

一、为什么布局规则需要“通用且可校验”

fireworks-tech-graph 的核心思路是：风格负责“好不好看”，布局负责“对不对、清不清楚”。风格参考文档（如 style-1-flat-icon.md）可以自由定制背景、配色、圆角、阴影、字体，但它们永远不能削弱几何与构图质量——这正是 composition-quality-contract.md 所定义的“风格身份边界”。

从源码结构看，这套理念被固化为两层独立的校验逻辑：

• 几何安全（geometry）：回答“图是否技术有效”，例如箭头是否穿过组件、连线是否互相交叉；
• 构图质量（composition）：回答“图是否达到交付标准”，例如弯曲次数、路线拉伸比、节点留白是否在预算之内。

因此本文先讲人可读、可手写的布局规则，再讲机器如何自动执行这些规则——两层相互印证，缺一不可。

二、通用布局规则：间距与留白预算

文档开篇就定义了所有风格共同遵守的最小间距预算，这些数值是后续所有路由计算的基础：

2.1 组件间距（Component Spacing）

• 最小净距 80px：两个组件“边缘到边缘”的距离不得低于 80px。Style-6 参考文档的 Layout Principles 也重申了这一点：“Minimum 80px between node edges”。
• 箭头路径与组件保持 60px 净距：路径本身不算障碍物，但它必须给组件留出呼吸空间，避免视觉上“擦着边框走”。
• 层与层之间 120px：水平分层架构（如 Input → Processing → Storage）每一层之间需要足够空间容纳跨层箭头。
• 同层组件 100–120px：同一排的组件间距比最小净距略宽，为箭头标签、并行连线预留位置。

在构图质量层面，showcase（官方精修）配置把“间距”进一步量化为硬指标：节点与节点的空白不小于 40px（min_node_gap）、节点到容器内边距不小于 20px（min_container_gutter）、标签与无关几何元素的净距不小于 4px（min_label_clearance）。这些数值定义在 composition_quality.py 的PROFILES["showcase"]中，会在composition校验时逐一检查。

2.2 一个可复制的间距经验值

在实际手写 SVG 时，建议把画布看成网格：组件宽约 180–220px、高约 60–90px，行间距 120px、列间距 100px。这组经验值既能满足上述预算，也符合 svg-layout-best-practices.md 中 Style-1 的 8px 网格对齐原则。

三、箭头连接点与路径路由

箭头是架构图中最容易“脏”的部分，文档给出了三条铁律：连中点、走正交、留安全距离。

3.1 连接点规则（Connection Points）

• 永远不要连接组件的角，一律使用边缘中点；
• 上下边缘入口/出口：cx ± offset，单箭头时 offset=0，多箭头时 ±30px；
• 左右边缘同理：cy ± offset；
• 连接点距组件角的最小距离20px。

这一规则的工程意义在于：角点连接会导致箭头斜穿相邻组件、且多个箭头在角部拥挤。测试用例test_insufficient_port_capacity_fails_instead_of_stacking（见 test_geometry_contracts.py）证明：当一条边需要挂接的箭头超过端口容量时，生成器会直接抛出PORT_CAPACITY错误，而不是把多个箭头堆叠在同一个坐标上——这正是“绝不把多个箭头头堆在一个坐标”这一布局语法的代码级实现。

3.2 路径路由：正交优先（Orthogonal Routing）

文档明确要求避免斜线穿过组件，改用 L 形正交路由：

<!-- Bad: diagonal arrow crosses component --> <path d="M 200,100 L 600,400"/> <!-- Good: orthogonal routing around component --> <path d="M 200,100 L 200,250 L 600,250 L 600,400"/> <!-- Good: curved with safe control point --> <path d="M 200,100 Q 400,200 600,400"/> <!-- Control point (400,200) is 50px+ away from any component -->

补充规则：

• 曲线箭头：贝塞尔控制点距离任何组件边缘至少 40px；
• 复杂路由使用中间途经点：M x1,y1 L x2,y2 Q cx,cy x3,y3；
• 同一层之间的多条箭头：Y 坐标错开 15–20px，避免重叠。

这套“正交 + 途经点”规则在源码中是可验证的。从 fireworks_geometry.py 的源码结构看：

• route_is_orthogonal(points)逐段判断路径是否只有水平/垂直段；
• bend_count(points)统计转弯次数；
• segment_interaction()返回两段线段的 crossing / touch / overlap 关系，是交叉与重叠检测的几何基础；
• 校验器在geometry_check中对data-generator="fireworks-tech-graph"生成的图强制执行non_orthogonal检查（见 validate_svg.py），手写 SVG 则通过采样曲线（二次/三次贝塞尔、椭圆弧分别以 12/16/20 步采样）来近似检测斜线与障碍物的碰撞。

3.3 途经点的合法性

途经点并非随意放置。测试test_waypoint_inside_reserved_obstacle_is_rejected与test_waypoint_outside_canvas_is_rejected证明：途经点落在障碍物内部会抛waypoint...obstacle异常，落在画布之外会抛outside the canvas异常。也就是说，布局规则不仅约束结果，还约束路由算法的输入。

四、箭头标签放置（Arrow Label Placement）

标签是仅次于箭头的第二大“视觉污染源”，文档给出精确参数：

• 位置：箭头路径的中点，沿箭头方向的法线偏移5–10px；
• 优先偏移：先把标签垂直挪开 5–10px，避免压在线条上；
• 背景矩形兜底：仅当偏移仍无法避开其他视觉元素时使用，参数为：
  • Padding：水平 4px、垂直 2px；
  • 填充色：与背景一致；
  • 透明度：0.9–0.95；
• 安全距离：距任何组件边缘至少15px；
• 多箭头汇聚：标签沿垂直方向错开20px。

为什么偏移量要精确到像素？因为校验器会把标签当作有边界的实体来检测。在validate_svg.py中，role_bounds()对data-graph-role="label"的文本调用geometry.estimate_text_bounds()（来自 fireworks_geometry.py，它按字符宽度估算中英文混排文本的边界），随后geometry_check会生成label_obstacle（标签撞组件）、label_edge（标签压箭头）、label_overlap（标签互叠）三类告警；composition_check还会执行composition_label_clearance，检查标签扩展min_label_clearance像素后是否触及节点或他边。

测试test_composition_detects_near_miss_label_clearance（见 test_validate_svg.py）展示了这个“擦边球”场景：标签与箭头只有 6px 距离时，geometry检查通过（没有实际碰撞），但composition检查因不足 4px 净距而失败——肉眼看起来“还行”的排布，在工程上会被严格拦截。

五、组件重叠检测（Overlap Detection）

在最终定稿前，逐项自查：

1. 组件包围盒不得重叠（含 8px 安全边距）；
2. 箭头路径不得穿过组件内部（有意的“隧道穿行”除外——此时需使用虚线样式并声明桥接）；
3. 文本标签不得与组件或其他标签重叠。

这些自查在geometry_check中全部自动化：find_collisions()会把除背景/容器/装饰之外的形状当作障碍物，用segment_hits_bounds()（Liang–Barsky 式线段裁剪检测）判断路径每一段是否穿过障碍物包围盒。注意几个细节规则（均有测试佐证）：

• 大容器不算障碍物、小虚线节点算障碍物（test_small_dashed_node_is_an_obstacle_but_large_container_is_not）：接近画布 90% 以上尺寸或占画布 45% 以上面积的矩形被识别为容器，不参与碰撞；
• 边界相接不算碰撞（test_boundary_to_boundary_connection_is_not_a_collision）：箭头终点精确落在目标组件边缘是合法连接；
• 图例内的示例箭头不算碰撞，但图例对业务箭头仍是硬障碍（test_legacy_legend_remains_an_obstacle_for_business_edges）；
• 多子路径按实际绘制线段检查，不会把 M 移动命令连接的线段误判为实线（test_multi_subpath_checks_drawn_segments_without_connecting_moves）。

六、Z-Index 图层顺序（SVG 渲染顺序）

SVG 中“后写的元素渲染在上层”。文档给出标准渲染顺序（从上到下即从后到前）：

<!-- Render order (top to bottom = back to front): --> 1. Background rect 2. Grouping containers (dashed rects) 3. Arrow paths 4. Arrow label background rects when collision fallback is needed 5. Components (boxes, cylinders, etc.) 6. Component text 7. Arrow label text 8. Legend

关键点在于：箭头画在组件之下、组件文字与标签之上——这样箭头被组件遮挡不美观的问题被规避，同时标签背景矩形又位于箭头之上，能正确“盖住”被压住的线条。

当必须跨越其他连线时（无法避免的交叉），文档与源码允许使用“桥接（bridge）”：在 fireworks_geometry.py 的path_with_bridges()中，会在声明点处插入半径为 5px 的确定性圆弧。但桥接必须满足三个条件，否则校验失败（见test_declared_jump_requires_a_bridge_mask、test_declared_jump_requires_effective_paint_order）：

1. 交叉点已在data-bridges属性中声明；
2. 存在data-graph-role="bridge-mask"的遮罩层，且其d路径与属主边完全一致；
3. 遮罩的渲染顺序必须介于被跨边与属主边之间（paint_order检查）。

这解释了文档中“箭头路径不得穿过组件内部（除有意的隧道穿行外）”的例外机制在工程上是如何被严格管理的。

七、风格化增强：Style-1 与 Style-6 的布局差异

布局规则通用，但两种代表风格在“像素级执行”上有明确差异，本文档给出了对照：

7.1 Style-1: Flat Icon Clean

• 完美对齐：所有坐标对齐到8px 网格；
• 锐利圆角：圆角矩形统一rx="8" ry="8"；
• 细箭头：线宽 1.5–2px，使用实心多边形箭头标记；
• 无阴影：扁平化设计原则。

参考 style-1-flat-icon.md 可以得到完整配色：背景#ffffff、盒描边#d1d5db、主文本#111827；语义箭头色按流程类型区分（主流程#2563eb、备选#dc2626、数据#16a34a、异步#9333ea）。注意其 SVG 模板明确禁止@import外部字体——因为cairosvg/rsvg-convert无法获取外部 URL，这也是布局可复现性的前提。

7.2 Style-6: Claude Official Warm

• 柔和阴影：<feDropShadow dx="0" dy="2" stdDeviation="6" flood-color="#00000008"/>；
• 更圆润：圆角rx="12" ry="12"（比 Style-1 更圆）；
• 中等粗细箭头：2px，标记克制。

参考 style-6-claude-official.md：暖米色背景#f8f6f3、节点按语义着色（输入/源#a8c5e6、Agent/处理#9dd4c7、基础设施#f4e4c1、存储#e8e6e3）、描边统一#4a4a4a2.5px。其箭头语义表给出了不同线型的含义：实线 2px 表示主数据流与读操作，虚线5,3表示写操作，3,2细虚线表示控制/触发。

需要强调：两种风格的差异全部落在“风格身份边界”内（配色、圆角、阴影、线宽），而共享的结构属性——拓扑、对齐、端口分配、走廊位置、交叉/弯曲/拉伸/间距预算——完全一致。这正是 composition-quality-contract.md 中“风格可自由变化 / 结构必须共享”的对立统一。

八、用校验器强制执行布局质量

手写 SVG 难免疏漏，仓库提供了两套工具把本文所有规则变成可重复执行的检查。

8.1 validate_svg.py 的五类检查

validate_svg.py 的 CLI 用法：

python3 scripts/validate_svg.py diagram.svg --check xml python3 scripts/validate_svg.py diagram.svg --check markers python3 scripts/validate_svg.py diagram.svg --check collisions python3 scripts/validate_svg.py diagram.svg --check geometry python3 scripts/validate_svg.py diagram.svg --check composition

对应五道关卡：

其中geometry对data-generator="fireworks-tech-graph"产出的图强制正交路由（non_orthogonal），因为生成器内部的路由算法（见 generate-from-template.py 中build_orthogonal_route）本身就是正交的；对手写 SVG 则放宽该约束，仅做碰撞检测。

8.2 validate-svg.sh：一键全流程

validate-svg.sh 依次执行上述五关，并追加渲染验证：优先尝试cairosvg，找不到时回退到rsvg-convert，两者都没有则报错并提示python3 -m pip install cairosvg。任何一关失败都会导致非零退出码——这意味着你可以把布局质量直接接入 CI 流水线。

bash scripts/validate-svg.sh diagram.svg

8.3 从标准到 showcase：两档构图预算

composition_quality.py 定义了两种质量档位：

• standard（默认）：宽松预算，适合工程压力测试图；
• showcase：官方样例与交付级产物，预算极严——单边最多 2 个弯、全图最多 8 个弯、零桥接交叉、路线拉伸比 ≤ 1.35、最短路由段 ≥ 16px、节点空白 ≥ 40px、容器留白 ≥ 20px、标签净距 ≥ 4px。

当前六节点参考拓扑在 showcase 档下的实测成绩为：总分 100，全图 4 个弯、0 交叉、0 桥接、路线拉伸最大 1.0、最小节点间距 50px、最小容器留白 20px（见 composition-quality-contract.md）。测试test_all_template_styles_share_the_showcase_composition_baseline进一步证明：11 个生成器支持的风格（Style 1–7、9–12）在共享的 Agent Runtime 拓扑上得分全部为 100，且各项指标完全一致——风格可以变，布局质量基线不能变。

构图得分的计算方式是惩罚制：每项违规扣 12 分、每个桥接扣 8 分、超出边数的多余弯曲每个扣 2 分，score = max(0, 100 - penalty)。

九、导出 PNG 前的验证清单

在最终导出 PNG 之前，逐项核对（全部可借助上述校验器自动化）：

• 无箭头-组件重叠（目检 +collisions/geometry检查）
• 箭头标签已从线条偏移；背景矩形兜底仅在必要时使用
• 所有箭头路径最小净距 ≥ 60px
• 组件间距 ≥ 80px
• 箭头连接点避开角点（距角 ≥ 20px）
• 层间多箭头已错位（15–20px）
• 图例可读且不与内容重叠
• SVG 可被cairosvg（或rsvg-convert兜底）干净渲染

渲染与导出的细节可参考 png-export.md 与 motion-effects.md。

十、常见反模式对照表

对照表中的每一项都能在测试中找到对应回归用例，例如test_edge_edge_crossing_is_reported（交叉）、test_collinear_edge_overlap_is_reported（重叠）、test_route_through_reserved_legend_is_reported（穿图例）、test_text_clipping_is_reported（文本出画布）。这保证了这些最佳实践不是“一次性文档”，而是被持续守护的契约。

结语

布局质量在 fireworks-tech-graph 中不是玄学，而是一套“通用规则 + 风格化参数 + 机器校验”的三层体系：先按 80px 间距、正交路由、中点连接、标签偏移、Z-Index 顺序把图画清楚，再用validate-svg.sh把几何安全与构图预算自动守死。当拓扑无法满足 showcase 预算时，契约文档的建议是：简化构图、拆分为聚焦的小图，或显式降级到 standard 档位——这本身就是一条值得所有画图者遵循的工程原则。

继续深入可阅读仓库内的 style-diagram-matrix.md 了解 12 种风格的能力矩阵，以及 svg-layout-best-practices.md 的姊妹篇 composition-quality-contract.md 了解完整的构图语法与交付门槛。

• AI 技能
• 数据可视化