Fireworks Tech Graph 脚本工具链：SVG 图表生成、自动验证与动效导出的实战指南

• 桌面应用
• AI 应用

本文基于 fireworks-tech-graph Skill 的scripts/脚本集（见 .agents/skills/fireworks-tech-graph/scripts/README.md），系统讲解如何用脚本化的方式稳定产出高质量 SVG 技术图表：从 XML 语法校验、箭头碰撞检测、语义几何契约检查，到模板化 JSON 生成、PNG 导出与 SVG→GIF 语义动效。读完本文，你将掌握一整套可在 Codex / Claude Code 工作流中直接复用的「生成—验证—导出—动效」命令管线，并理解其背后的源码级实现原理。

Fireworks Tech Graph 12 种图表风格总览

一、脚本集全景：四个核心脚本与统一 CLI

scripts/目录是整套 Skill 的可执行层，围绕「稳定性和效率」两个目标设计。目录中除本文档外，包含以下关键文件（完整结构见 目录结构）：

从源码看，validate_svg.py采用纯 Python 标准库实现（xml.etree.ElementTree+ 手写几何计算），刻意不引入额外运行时依赖（validate_svg.py 文件头注释明确说明这一点），这让 Skill 在全新环境安装后即可直接运行验证。而fireworks.py则在脚本之上统一了命令面：doctor子命令会一次性探测 Python、cairosvg、rsvg-convert、node、ffmpeg 与动效渲染器是否就绪并输出 JSON 报告（fireworks.py）。

二、validate-svg.sh：六道关卡守门 SVG 质量

2.1 用法与检查项

验证脚本的用法非常直观：

./validate-svg.sh <svg-file>

脚本set -euo pipefail严格退出，逐项打印✓ Pass/✗ Fail，任何一项失败都会汇总错误数并以非零码退出。对照 validate-svg.sh 源码，实际执行的是六道检查（而非文档表面上列出的三项）：

1. XML 结构与属性语法：调用validate_svg.py --check xml，使用真正的 XML parser 解析，因此top_k=5这类带下划线的文本不会被误判为属性；同时检查属性转义（&、<、"等）。
2. marker 引用完整性：检查marker-start/marker-mid/marker-end三属性中url(#id)引用的每个 id 是否都有对应的<marker>定义，缺定义即报missing marker: <id>（实现见 validate_svg.py 的marker_references()）。
3. 箭头与组件碰撞检测：这是最复杂的部分。脚本把带 marker 的<line>/<polyline>/<path>视为边，把<rect>/<circle>/<ellipse>/<polygon>视为障碍物，逐段做线段-矩形求交。find_collisions()完整支持绝对/相对M/L/H/V/Q/C/S/T路径命令，对二次、三次贝塞尔曲线按 12/16 步采样，对椭圆弧A命令做了端点到中心参数化的完整换算后采样（sample_arc()）。
4. 语义几何契约（geometry）：仅针对标注了data-graph-role语义角色的元素审计——节点/标签是否越出 viewBox、边是否正交（生成器产物强制）、边与节点是否相交、边与边是否重叠、交叉处是否有合法 bridge mask 且绘制顺序正确、标签是否与障碍物/其他标签/边相交（geometry_check()）。
5. 构图质量预算（composition）：从 SVG 根节点读取data-quality-profile与data-max-bends-per-edge、data-min-node-gap、data-min-label-clearance等属性构造契约，审计每条边的弯折数、总弯折数、路由拉伸、桥接交叉数与标签间距是否超标（composition_check()）。
6. 渲染验证：优先探测 Python 环境是否有 cairosvg，其次回退到rsvg-convert，两者都没有则直接判失败并提示安装命令；渲染过程写入临时文件，成功后自动清理。

2.2 角色标注：让启发式让位于显式语义

对于启发式难以区分的形状，可以在 SVG 元素上显式声明语义角色，这是几何与构图检查的重要输入：

<rect>./generate-diagram.sh [OPTIONS]

源码中VALID_TYPES明确定义了 14 种受支持类型：architecture |># 生成架构图（Style 1） ./generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg # 生成流程图（Style 2，2400px 宽） ./generate-diagram.sh -t flowchart -s 2 -w 2400

脚本内部会自动：

1. 在references/下按style-<N>-*.md查找对应风格参考文件，找不到即报错；
2. 若 SVG 已存在则先跑validate-svg.sh，验证通过再调用fireworks.py export-png按指定宽度导出 PNG。

⚠️ 注意：SVG 内容本身需要先由 Codex / Claude Code 准备好；generate-diagram.sh只负责验证与导出，不负责内容创作。脚本运行时会明确打印这一提示。

四、generate-from-template.py：JSON 驱动的模板化生成器

这是「内容生成」的真正实现者。它早已不是简单地把nodes/arrows塞进模板，而是会执行 style guide 中的可计算规则，让输出尽量贴近 showcase 样例质量。

4.1 命令格式

python3 ./generate-from-template.py <template-type> <output-path> [data-json]

例如：

python3 ./generate-from-template.py architecture ./output/arch.svg '{"style":1,"title":"My Diagram","containers":[],"nodes":[],"arrows":[]}'

4.2 JSON 数据契约

对照 generate-from-template.py 源码与 mem0-style1.json 真实 fixture，可用的核心字段如下：

生成器内部为 12 种风格预置了完整的视觉档案（STYLE_PROFILES）：每种风格都定义了字体族、背景色、节点填充/描边/圆角、阴影、标题对齐与字号、箭头宽度与七种 flow 的颜色映射、文字层级色等几十个参数。例如 Style 2 Dark Terminal 使用等宽字体'SF Mono', 'Fira Code', Menlo、背景#0f172a；Style 3 Blueprint 使用#082f49深蓝背景并叠加网格 pattern；Style 11 Event Transit 使用#e4475b控制色与 2.8px 加粗箭头。所有<marker>的大小、refX/refY、箭头多边形形状也按风格差异化生成（render_defs()）。

完整示例（Mem0 记忆架构，Style 1，节选自 mem0-style1.json）：

python3 ./generate-from-template.py memory ./output/mem0.svg '{ "style": 1, "title": "Mem0 Memory Architecture", "containers": [ {"x":30,"y":90,"width":900,"height":90,"label":"Input Layer","header_prefix":"01"} ], "nodes": [ {"id":"manager","kind":"double_rect","x":360,"y":220,"width":300,"height":72,"label":"Memory Manager"}, {"id":"vector","kind":"cylinder","x":90,"y":360,"width":140,"height":110,"label":"Vector Store"} ], "arrows": [ {"source":"manager","target":"vector","flow":"write","dashed":true} ] }'

4.3 特殊说明：Style 8 不走模板

Style 8（Dark Luxury）是AI 手绘风格：AI 读取 style-8-dark-luxury.md 后直接手写 SVG，generate-from-template.py对其会抛出明确的 ValueError，提示加载风格参考后手工创作（源码_AI_AUTHORED_STYLES与_AI_AUTHORED_MSG）。相应地，test-all-styles.sh对 Style 8 使用静态 SVG fixture（fixtures/dark-luxury-style8.svg）而非 JSON fixture。

五、test-all-styles.sh：12 风格批量回归测试

当需要验证整套风格体系没有回归时，直接运行：

./test-all-styles.sh

脚本流程（对照 test-all-styles.sh 源码）：

1. 按STYLES=(1..12)遍历全部 12 种风格，检查对应风格参考文件是否存在；
2. 扫描fixtures/下所有*.json，解析每个 fixture 的style字段与当前风格匹配；Style 1–7 与 9–12 从 JSON fixture 生成，AI 手绘的 Style 8 使用静态 SVG fixture——任何风格缺少回归 fixture 都会使批测失败；
3. 对 JSON fixture 调用generate-from-template.py渲染 SVG（模板类型取 fixture 内的template_type），静态 SVG fixture 则直接复制；
4. 对每个 SVG 运行validate-svg.sh验证；
5. 调用fireworks.py export-png导出 1920px 宽 PNG 到test-output/目录（文件带_YYYYmmdd_HHMMSS时间戳）；
6. 汇总输出通过/失败统计。

测试输出位置可通过环境变量覆盖：TEST_OUTPUT_DIR（默认test-output/）。批量验证失败时会抓取✗|Error|intersects|missing marker关键行缩进打印，方便定位问题。

六、语义动效：SVG → 校验 → 逐帧渲染 → GIF

从 v1.2.0 起，脚本集支持把「带语义契约的生成器 SVG」转成经过验收的动效 GIF。动效由fireworks.py animate、motion.py与svg2gif.js协作完成：

1. 输入必须是生成器语义 SVG——携带 12 套已验收 role/stage/order 契约之一；精确源文件字节不锁定，但任意同风格拓扑不会自动套用动效；
2. 媒体输出只允许经过验证的 GIF，默认还会生成同名.motion.json报告（可用--report改路径）；
3. 运行时需要 FFmpeg/FFprobe、Chrome/Chromium，以及 Skill 安装位置可解析到的puppeteer或puppeteer-core（Node.js 22.12+）；当前工作目录中的同名模块不会被隐式执行——这是刻意的安全设计。

依赖安装与最简命令：

for SKILL_ROOT in \ "$HOME/.agents/skills/fireworks-tech-graph" \ "$HOME/.claude/skills/fireworks-tech-graph" do [ -d "$SKILL_ROOT" ] || continue npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false puppeteer-core@25.3.0 done SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}" python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

6.1 默认时间线与动效契约

• 默认输出：自动识别风格，5.75 秒、20fps、960px 宽、115 帧、无限循环 GIF；
• 帧段划分：第 1–36 帧保持既有 draw-on（连线按语义顺序绘制），第 36–38 帧淡入运行流，第 38–109 帧为完整稳定数据流（operating hold），第 110–114 帧按[1, .7575, .515, .2725, .03]五帧 opacity 系数 reset；
• 风格签名：Style 1–12 的 signature、速度、路径、几何与构建合同均为user-approved，包括persistent-data-flow-head、terminal-evidence-stream、blueprint-registration-bead、14×10notion-memory-card、glass-task-capsule、policy-seal、token-train、gem-tracer、review-cursor、region chevrons、event train 与 ops scanner；
• 共享时间修订：+2s-settled-flow已于 2026-07-17 验收，默认新包的review_status为user-approved；
• 兼容时间线：显式 3.75 秒/75 帧与 2.75 秒/55 帧继续支持。

6.2 帧唯一性与 raster 门禁

动效质量契约（详见 motion-effects.md）对帧做了严格约束：

• 75 帧及以下要求全部 raster 唯一；更长时间线允许非相邻重复出现在 full-opacity 区间；
• frame 110 是 reset opacity 为1.00的唯一例外，分类为intentional_reset_boundary_repeat；frame 111–114 必须全局不同；
• 至少保留 75 个唯一 raster 且相邻重复数为零；
• 75-vs-115 gate 分开统计 binary / decoded-RGBA / guarded-antialias 三类：guarded 等价要求 AE ≤ 128、normalized RMSE ≤ 0.001、component 宽或高不超过 2px 且只落在 edge/node border，而 DOM 与 signature geometry 仍须 strict-exact。

七、目录结构与角色标注约定

Skill 的完整目录结构如下（与 README.md 一致）：

fireworks-tech-graph/ ├── SKILL.md # Skill 主文档 ├── references/ # 风格参考文件 │ ├── style-1-flat-icon.md │ ├── style-2-dark-terminal.md │ └── ... ├── fixtures/ # 回归测试样例（JSON） │ ├── mem0-style1.json │ ├── tool-call-style2.json │ └── ... ├── scripts/ # 辅助脚本（本目录） │ ├── README.md # 本文档 │ ├── validate-svg.sh # SVG 验证 │ ├── generate-diagram.sh # SVG 验证与 PNG 导出 │ ├── generate-from-template.py # 模板化生成 SVG │ ├── motion.py # SVG 转 GIF 校验、编码与原子报告 │ ├── svg2gif.js # Chromium 手动时间轴逐帧渲染 │ └── test-all-styles.sh # 批量测试 └── test-output/ # 测试输出目录（自动创建）

角色标注的补充约定：对启发式难以区分的形状，可显式添加data-graph-role="node|container|legend|decoration|label|background"。node会强制纳入障碍物检测，其余角色会从组件障碍物中排除；legend组内的示例箭头也不会被当作业务流。

八、依赖安装

所有脚本需要至少一个 PNG 渲染器（推荐 cairosvg）：

• cairosvg（推荐）——SVG 转 PNG，CSS 支持最好：

  python3 -m pip install cairosvg

• rsvg-convert（备选）——系统包；复杂 SVG 可能丢失 CSS /<foreignObject>：

  brew install librsvg # macOS sudo apt install librsvg2-bin # Ubuntu/Debian

generate-diagram.sh会优先调用 cairosvg，缺失时自动回退到 rsvg-convert；validate-svg.sh的渲染验证同理。完整对比见 PNG 导出参考（其中还说明：需要浏览器级像素还原时，可用svg2png.js走 Puppeteer + Chromium 渲染，适合含 CJK/emoji 回退或<foreignObject>的场景）。文本处理仅需 macOS / Linux 自带的grep、sed、awk。

九、典型使用场景

场景 1：验证现有 SVG

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex # SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code "$SKILL_ROOT/scripts/validate-svg.sh" /path/to/your-diagram.svg

场景 2：生成并验证图表

1. 使用 Codex 或 Claude Code 生成 SVG 内容；
2. 运行验证和导出：

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex # SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code "$SKILL_ROOT/scripts/generate-diagram.sh" -t architecture -s 1 -o ./output/arch.svg

场景 3：批量测试所有风格

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex # SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code "$SKILL_ROOT/scripts/test-all-styles.sh"

测试脚本会自动：读取fixtures/*.json→ 按template_type + style调用generate-from-template.py→ 运行validate-svg.sh→ 导出 PNG 到test-output/。

场景 4：validator 单元测试

python3 -m unittest discover -s tests -p 'test_validate_svg.py' -v

测试覆盖 marker 双端引用、文本等号、H/V路径、曲线路径、虚线组件和容器排除等正反例（对应 tests/test_validate_svg.py）。查看测试输出：

ls -lh ../test-output/

十、故障排除

问题：找不到 PNG 渲染器

解决方案（任选其一，推荐 cairosvg）：

python3 -m pip install cairosvg # 推荐 brew install librsvg # macOS 系统包 sudo apt install librsvg2-bin # Ubuntu/Debian

问题：rsvg-convert 渲染缺框/缺文字

原因：rsvg-convert 对<foreignObject>、CSSfilter、复杂<style>块支持有限。解决方案：切换到 cairosvg：

python3 -m pip install cairosvg

脚本会自动优先使用 cairosvg。如果仍需要像素级还原（例如浏览器生成的 SVG），按 PNG 导出参考 使用svg2png.js。

问题：权限被拒绝

chmod +x *.sh

问题：SVG 验证失败

1. 查看详细错误信息（validate-svg.sh会逐项打印失败原因与相关行）；
2. 使用编辑工具修复语法或几何问题（缺 marker 定义补<marker>，碰撞则调整走线或标注data-graph-role）；
3. 重新运行验证。

十一、开发说明：如何扩展脚本集

添加新的验证规则：编辑 validate-svg.sh，在现有检查项后追加检查逻辑：

# Check N: Your new check echo -n "Checking something... " # Your validation logic here if [ condition ]; then echo -e "${GREEN}✓ Pass${NC}" else echo -e "${RED}✗ Fail${NC}" FAILURES=$((FAILURES + 1)) fi

对应地，validate_svg.py中每个--check分支都是一个独立函数（run_check()分发），新规则可以在该模块中按同样模式注册。

扩展支持的图表类型：编辑 generate-diagram.sh，在--type参数处理的VALID_TYPES列表中添加新类型，并在generate-from-template.py的DEFAULT_VIEWBOX中补充该类型的默认画布尺寸。

十二、版本历史

• v1.2.0(2026-07-17) —— 语义动效与动态展示
  • 12 种已验收的 SVG→GIF 场景动效与 5.75 秒 settled-flow 默认时间线；
  • README 全动态图集、GIF manifest、媒体回读与安装副本全风格门禁；
  • 动效源 SVG 保持语义契约约束，不绑定标题和内容字节。
• v1.1.0(2026-07-15) —— 几何与分发升级
  • Schema v1 与类型化 Diagram IR；
  • 正交路由、端口分流、图例/标签避让、跨线桥与确定性布局报告；
  • fireworks.py统一 CLI 与离线交互 HTML 导出；
  • 完整 npx Skill 镜像、CI、Release archive parity 与安装 canary。
• v1.0.0(2026-04-11) —— 初始版本
  • SVG 验证脚本、图表生成脚本、批量测试脚本。

许可证

MIT License——与 fireworks-tech-graph skill 相同（见 LICENSE）。

• 桌面应用
• AI 应用