Fireworks Tech Graph

Fireworks Tech Graph 快速入门：把「描述系统」变成可校验的图

这是什么？适合谁？

Fireworks Tech Graph（yizhiyanhua-ai/fireworks-tech-graph，MIT，Python）是一个以 Agent Skill 形态分发的技术图生成器——它不是 GUI、也不是 SaaS，而是「同一个技能目录」在 Codex 与 Claude Code 里原样安装、原样运行，同时自带一套可以脱离宿主单独调用的统一 CLI。

它的口号是「别再手动画图了」：用中文或英文描述系统，拿到一张几何安全（geometry-safe）的 SVG、一张高清 PNG、可选的语义 GIF 动效，以及一份离线可交互 HTML。真正让它区别于「让模型随便画一张」的是那道验证闸门——渲染前先校验输入 IR（schema v1 归一化；重复 ID、悬空引用、非法 waypoint、非有限几何都会在渲染前失败），渲染后 check 再校验 XML 与 marker 完整性、节点/保留区/标签/画布/边重叠/边交叉，最后才谈导出。

按仓库当前版本（npm 包 1.2.0，main 上还有一个未发版的 quality upgrade）的自我描述：11 个生成器驱动的风格 + 1 个 AI 自作风格（Dark Luxury），覆盖 14 类 UML 图与 AI/Agent 领域模式（RAG、Agentic Search、Mem0、Multi-Agent、Tool Call 等）。其中 9–12 号风格是「工程优先」的，各自绑定一份可执行语义契约：C4 评审画布、云部署归属、事件地铁图、可靠性黄金信号。

这套东西最值得称道的是「拒绝假装」：check 真的算交叉与桥接，doctor 把 svg/html/png/gif 四个能力分开报，text_policy 默认只报告截断而设成 strict 就直接拒绝出图，动效导出要求输入是带契约的语义 SVG 而不是任意图片。用项目自己的话说：Evaluate, don’t assert——完成与否由校验器和渲染证据背书，不是模型嘴上说「画好了」。

横向对比同类工具：

• Mermaid：手写 DSL，适合塞进 Markdown 的轻量内联图；没有自然语言入口、没有风格体系、没有几何校验与动效。
• draw.io / diagrams.net：手动精修最灵活，但靠拖拽，出图慢，也没有「生成即生产级」的约束。
• Structurizr：C4 专用、模型严谨，但通用架构图与 AI 域图不在射程内。
• Excalidraw 与 Eraser 一类 AI 白板：灵活、协作好，产物是手绘风位图或自由画布，缺少确定性路由与结构校验。

适合谁：架构师与技术负责人（评审用 C4 图、部署拓扑、可靠性视图）；需要批量产出统一风格图的技术文档工程师；在编码 Agent 里写完代码顺手出图的团队；以及想把「出图」接进脚本或 CI、要求可复现的工程团队。

不适合谁：需要像素级自由创作的设计师（它的产物是语义化 SVG，不是自由画布）；只要一张随手流程图的人（Mermaid 更快）；完全不想碰命令行、也不想用编码 Agent 的人。

本站实测（2026-11-01，Windows，真实跑通）

这一节是本站真跑出来的，不是转述。环境：Windows 11 + Hermes 环境自带 Python 3.14.7；技能装在 skills/creative/fireworks-tech-graph，puppeteer-core 25.3.0 在技能目录内，Chrome 与 FFmpeg 系统级可用。

渲染时它还顺手给了两组可以直接引用的读数：

• 对比度（默认不透明画布的文本 token，阈值 4.5）：主文本 12.1、次文本 10.46、弱化文本 8.32、区块副标题 8.32——全部过线，且报告明确写了「这不是完整的渲染态无障碍审计」。
• 文本完整性：complete_text: true、truncated: []；同一份报告也提醒「宽度是启发式估算，实际字体要看渲染结果」。

效果图（本站渲染的原样输出，不是官方宣传图）

下面四张都是本站用仓库自带 fixture 在 Windows 上跑出来的原始产物，没有二次美化：前两张分别验证「通用架构风格」与「带证据契约的评审风格」，第三张验证事件流语义，最后一张是同一张图的语义动效。

风格 3 Blueprint · 微服务架构（fixture microservices-style3.json，export-png --width 1920 → 1920×1440）

风格 9 C4 Review Canvas · 结账容器评审（fixture c4-review-canvas-style9.json → 1920×1222）

风格 11 Event Transit · 结账事件线（fixture event-transit-style11.json，注意这条要 render flow 而不是 render architecture → 1920×1180）

风格 3 的语义动效 GIF（animate → 960×720 / 20fps / 115 帧 / 5.75 s，占位约 296 KB）

这四张图对应的判定：三张 PNG 的 check 全部 ok: true，文本完整性 complete_text: true、无截断；对比度最低值分别是 8.32（风格 3）、4.92（风格 9）、5.30（风格 11），都在 4.5 阈值以上。换句话说，上面看到的排版不是「挑出来最好看的一张」，而是通过校验的默认输出。

再补一个失败面实测，这才是它值钱的地方：把 fixture 里一个节点标签换成一整句超长英文、并把 text_policy 设为 strict 后重跑——

rc=1  {"ok": false, "error": "TEXT_FIT: text would be truncated; widen the card or split the view"}
输出目录里没有写出任何 SVG

也就是说 strict 是失败闭合的：宁可不给文件，也不给一张字被截掉的图。它给的处置建议也很具体——加宽卡片或拆图，而不是缩字号糊过去。

准备工作

1. 宿主（可选但推荐）：Codex CLI 或 Claude Code。技能以 Agent Skill 标准分发，两个宿主各自一份 SKILL.md；订阅价格以各自官网当期为准，本文不引用固定价格。不用宿主也能跑——统一 CLI 可以独立调用（本站上面那组实测就是在 Hermes 环境里直接跑 Python CLI，没经过任何编码 Agent）。

2. Python 3.9+ 的解释器：渲染、校验、导出、动效编排全部是 Python 脚本。

3. PNG 导出需要栅格化器（二选一）：cairosvg（pip install cairosvg，默认推荐）或 rsvg-convert（librsvg 的 CLI）。两个都没有时 doctor 的 png 能力为 false，SVG/HTML/GIF 不受影响。没有 Python 栅格化器也有退路：仓库自带浏览器路径 scripts/svg2png.js（走技能目录内的 puppeteer-core + 系统 Chrome），本站两条路径都实测出过 1920×1440 PNG。

4. GIF 动效需要：FFmpeg（含 ffprobe）、Node.js ≥ 22.12（package.json 的 engines 明确写了这条）、可被自动发现的 Chrome/Chromium，以及装在技能目录内的 puppeteer-core：

   npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false puppeteer-core@25.3.0
   

5. 前置知识：会描述「有哪些组件、它们怎么连」即可；懂一点 C4/UML 能让风格 9–12 的输入更准，但不是必需。全程不写 DSL。

6. 成本：技能 MIT 免费，渲染依赖全开源；唯一的钱是你要不要用付费的编码 Agent 来生成图。出图质量主要来自几何校验闭环而不是模型档位，用便宜模型也能出可用结果。

安装

推荐用 skills CLI（注意是嵌套路径，不是裸仓库）：

npx -y skills add yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy

手动安装（保持可编辑、可 git pull 更新）：

mkdir -p ~/.agents/skills ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

Windows 上的等价路径是 %USERPROFILE%\.agents\skills 与 %USERPROFILE%\.claude\skills；装到别的宿主（例如 Hermes 的 ${HERMES_HOME}/skills/<category>/）同样可行——CLI 只依赖 $SKILL_ROOT 这个绝对路径，不依赖宿主约定。

装完重启宿主，再用两条命令确认它真的可用：

SKILL_ROOT="$HOME/.agents/skills/fireworks-tech-graph"
python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" doctor

5 步核心流程

第 1 步：把技能装到宿主（嵌套路径）

见上节。判据只有一条：scripts/fireworks.py 必须存在。只拿到根 SKILL.md 就是装错了（见踩坑 1）。

第 2 步：用 doctor 分能力自检

doctor 的输出是按能力分组的，不是一句「装好了没」：

• capabilities：svg / html / png / gif 四项布尔值；
• 依赖探测：cairosvg、rsvg-convert、ffmpeg、node、python，以及 Chrome 与 puppeteer-core 的实际解析路径。

所以「gif 能出」不等于「png 能出」。本站实测就是 svg/html/gif=true、png=false，原因是这台机器的 Python 解释器里没有 cairosvg。先看这四项，再决定要不要装东西，比事后对着报错猜快得多。

第 3 步：选风格、准备输入

两种输入形态，按需要选。

A. 自然语言（在宿主里说）：

Draw a microservices architecture: Client → API Gateway → [User / Order / Payment Service]
→ PostgreSQL + Redis, with an events lane and an observability strip, style 3

Draw a Multi-Agent diagram: Orchestrator dispatches 3 SubAgents (search / compute / code),
results aggregated and reviewed, style 5 (glassmorphism)

C4 review board for the checkout container: responsibilities, technologies, labeled protocols, style 9

B. JSON（schema v1）：需要确定性复现、或要进 CI 时用 JSON。核心字段是 schema_version、mode、style、motion_scene、quality_profile、width/height、title/subtitle、containers[]、nodes[]（节点带 id/kind/x/y/width/height/label/sublabel/fill/stroke）。仓库 fixtures/ 里 12 个风格各有一份可直接跑的样例。

风格速查（当前包）：

9–12 不是「换个皮肤」：它们绑定可执行的语义契约，缺对应证据时按设计退回通用风格，而不是编造区域、指标或协议。

第 4 步：渲染 + 结构校验

python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture input.json diagram.svg --report layout.json
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg

• render 产出 SVG 与 layout.json（含对比度、文本完整性、排版度量）；本站实测 790 ms。
• check 校验 SVG 身份、marker 引用、通用箭头/节点碰撞、语义几何与构图约束；本站实测 293 ms 且 ok: true。
• 失败时按报告里的 element id + 几何做定点修改；官方明确「不要为了让 check 过而削弱语义或构图约束」。

若要「文字一字不差可见」，在输入里加：

{ "text_policy": "strict" }

strict 下只要出现可见截断就以 rc=1 拒绝并完全不写 SVG（本站已实测），替代方案是加宽卡片或拆图。

第 5 步：导出 PNG / 离线 HTML / 语义 GIF

python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920
python3 "$SKILL_ROOT/scripts/fireworks.py" export-html diagram.svg diagram.html --title "Agent Runtime Architecture"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

• export-png：读根画布尺寸、有界导出、原子写入，并回读 PNG 的实际像素尺寸（本机因缺 cairosvg，这条路径未验证）。
• export-html：单文件离线交互页，带 pan/zoom、明暗主题、SVG 源码复制、1×–4× 的 SVG/PNG/JPEG/WebP 下载；本站实测 278 ms / 35,791 字节。
• animate：只接受带已批准动效契约的语义 SVG，输出 GIF 与 .motion.json 报告；默认 960px / 20fps / 5.75s / 115 帧（前 36 帧线路绘制、第 38 帧完整流动、38–109 保持 settled flow、110–114 复位），另支持 3.75s/75 帧与 2.75s/55 帧两档。本站实测 18.7 s，ffprobe 复核 960×720 / 20fps / 115 帧 / 5.750 s，与报告一致。

常见踩坑（10 条）

坑 1：装了但一跑就找不到 fireworks.py

现象：scripts/fireworks.py 不存在，或 references/、fixtures/、schemas/ 全是空。 原因：用裸仓库路径安装（.../fireworks-tech-graph），skills CLI 只挑中了根 SKILL.md。 解决：改用嵌套路径 yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph，或按上节 git clone 整仓。

坑 2：装完宿主里没反应

现象：在 Codex / Claude Code 里说「draw diagram」不触发。 原因：宿主启动时扫描技能目录，新装的需要重启才可见。 解决：重启宿主；之后改 SKILL.md 多数会被热加载，但改 scripts/、references/ 仍建议重启。

坑 3：doctor 说 png: false，但 GIF 明明能出

现象：以为渲染链路全坏，其实只是 PNG 路径缺栅格化器。 原因：doctor 的四项能力相互独立——GIF 走 Chrome + puppeteer，PNG 走 cairosvg / rsvg-convert。 解决：pip install cairosvg（本站做法：装在独立 venv 里，避免污染宿主解释器），或装 librsvg 的 rsvg-convert；两者都没有时用仓库自带的浏览器路径 node scripts/svg2png.js <目录>（本站实测 1.76 s 出 1920×1440），或先导出离线 HTML 再截。

坑 4：animate 报 Node 版本或找不到 Chromium

现象：动效导出直接失败，或输出空 GIF。 原因：package.json 要求 Node ≥ 22.12；Chrome 需可被自动发现；puppeteer-core 必须装在技能目录内（渲染器刻意不从调用方 cwd 解析模块）。 解决：node -v 先过 22.12，再 npm install --prefix "$SKILL_ROOT" ... puppeteer-core@25.3.0，然后 doctor 看 motion_renderer 与 Chrome 路径有没有被解析出来。

坑 5：风格 9–12 写不出「证据」，出图退回通用风格

现象：指定了 style 9，结果还是普通架构图。 原因：这四种风格要求声明式证据（一个 C4 层级 + 职责/技术/协议、区域与网络归属、topic/processor/DLQ、固定窗口与四黄金信号）。证据缺失时按契约退回通用风格，而不是瞎编。 解决：把证据补进描述或 JSON；确实没有证据时别硬上 9–12，用 1–7 更省事。

坑 6：默认 text_policy 下字被截断，却以为没问题

现象：SVG 里某个卡片标题被截，报告里只有一行提示。 原因：默认是 report 策略——保留完整标签在元数据里并报告可见截断，不阻断输出。 解决：要逐字可见就设 "text_policy": "strict"（会以 rc=1 拒写，逼你加宽或拆图）；不改 strict 时，至少把报告里的 truncated 读完再交付。

坑 7：长中文/长英文标签硬塞进小卡片

现象：strict 模式直接失败，或默认模式出一张挤在一起的图。 原因：折行是 CJK 感知的，但折行次数与卡片标题都有上界，字号也不是无限可缩。 解决：加宽容器、把内容拆成两张图、或把细节挪到 sublabel——官方给的处置就是「widen or split」，不是缩字号。

坑 8：交叉线/桥接「看起来还行」就放过

现象：图能出，但多条语义边互相压着、箭头指错。 原因：check 默认会算边交叉与桥接、边重叠与保留区，但报告要你读；构图契约还要求节点间距 ≥40px、容器间隙 20px、每条边最多两次弯折、同一业务边不重复画。 解决：按报告里的 element id 改几何，不要靠视觉印象跳过。

坑 9：拿位图或手绘 SVG 去 animate

现象：动效导出报输入不支持。 原因：1.2.0 起动效路径只接受生成的语义 SVG（带语义拓扑、路由角色与风格签名），会拒绝栅格输入与非 SVG。 解决：先 render 出语义 SVG 再 animate；不要拿别的工具导出的 SVG 硬转。

坑 10：render 的第一个参数写错，报 mode 冲突

现象：render architecture fixtures/event-transit-style11.json ... 报 {"ok": false, "error": "mode 'flow' conflicts with template type 'architecture'"}，且不产出 SVG。 原因：render 的第一个位置参数是 mode，必须与 fixture 里的 mode 字段一致；事件流这一类（style 11）是 flow，不是 architecture。本站实测就踩了一次：同一批 fixture 里 style 3 / 9 是 architecture，style 11 是 flow。 解决：先看 fixture 的 mode（或 template_type）再决定参数；不确定时用 validate <mode> <json> 先过一遍，它会把冲突直接报出来。

初级用法

1. 评审用 C4 图：style 9 + 声明一个 C4 层级与各容器的职责/技术/协议，产出可直接贴进 ADR 的评审画布。
2. 部署拓扑：style 10 + 区域/VPC 归属与跨区复制机制，输出多区域部署图，而不是把 VPC 框当装饰。
3. 事件流：style 11，topic 当轨、processor 当站，标出 DLQ 与状态投影，适合 Kafka 拓扑评审。
4. 事故复盘图：style 12 + 固定时间窗与四个黄金信号，出一张「关键链路 + 指标窗口」的排查视图。

高级玩法

1. 进 CI 做可复现图：把 JSON 输入与 render → check → export-png 写进流水线，图随代码变；check 非零即阻断，等于给架构图加了回归测试。
2. 一套输入多风格出图：同一份 JSON 换 style 生成 2–3 个版本——评审用 Blueprint（3）、对外用 Glassmorphism（5）、博客用 Dark Terminal（2）。
3. 离线可交互交付：export-html 给客户或同事一个不联网也能 pan/zoom、切主题、复制 SVG 源码、按 1×–4× 下载的单文件页面。
4. 动效做讲解材料：animate 出的 GIF 先画线路再流动，适合放进 release note 或文档首页；.motion.json 里带帧数/时长/宽度，可直接核对有没有被人手工改过。

六个小技巧

1. 先跑 doctor 再谈出图：四项能力一眼看清，省掉「为什么只有 GIF 能用」的排查。
2. 风格用编号：style N 比「深色/极简」这类词稳；9–12 还要补对应证据指纹（C4 review board / deployment topology / event metro map / reliability pulse）。
3. 要交付就设 strict：宁可被拒一次，也不要交一张字被截的图给评审。
4. 失败只看 element id：check 与 TEXT_FIT 的报错都指向具体元素与几何，改那一处，别整图重来。
5. 复用 fixtures 当模板：12 个风格各有一份能跑通的 JSON，改 label 比从零写 IR 快得多。
6. GIF 别反复生成：一次渲染多次复用同一个语义 SVG；动效导出本身要十几到二十秒（本站 18.7 s），频繁重跑很浪费时间。

常见问题 FAQ

Q1：它和 Mermaid、draw.io 到底怎么选？

A：三种场景三种工具。要「写进 Markdown、随时改的轻量内联图」用 Mermaid；要「手工精修、自由拖拽」用 draw.io；要「描述系统 → 直接拿到几何校验过的生产级 SVG/PNG，还带动效与离线 HTML」用它。差别不在能不能画，而在出图后有没有结构校验——Mermaid 与 draw.io 都不会告诉你有几条边交叉、字有没有被截。

Q2：必须装 Codex 或 Claude Code 吗？

A：不必须。它的入口是统一 CLI（validate / render / check / export-png / export-html / animate / doctor / version），本站的实测就是在 Hermes 环境里直接调用 Python CLI 完成的，没有任何编码 Agent 参与。装宿主的价值是「一句话触发」与让 Agent 自己判断风格、自己修 check 报错。

Q3：免费吗？钱花在哪？

A：技能 MIT 免费，渲染依赖（cairosvg、FFmpeg、Chrome、puppeteer-core）全部开源或免费。唯一的钱是你要不要用付费的编码 Agent 来生成图；由于质量主要来自几何校验闭环而不是模型档位，用便宜模型也能出可用结果。

Q4：支持中文吗？中文标签会被截断吗？

A：支持中文描述与中文标签，折行是 CJK 感知的，字体栈含 Microsoft YaHei / SimHei 一类系统字体（本站 Windows 实测渲染正常，没有豆腐块）。但折行与卡片标题都有上界：长中文标签仍可能被截，判据是报告里的 truncated 与 complete_text；要强约束就开 strict。

Q5：能画哪些图？

A：14 类 UML 图（类、组件、部署、包、组合结构、对象、用例、活动、状态机、序列、通信、时序、交互概览、ER），加上 AI/Agent 领域模式（RAG、Agentic Search、Mem0、Multi-Agent、Tool Call 等）。它不做照片、位图或统计图表——那些不在射程内。

Q6：Windows 上有什么特别注意的？

A：三件：① 路径用 %USERPROFILE% 而不是 ~；② 解释器别用 WindowsApps 的 python3 存根（会打开商店），换成真实的 Python；③ Node 必须 ≥22.12 才能跑动效，且 puppeteer-core 要装在技能目录内而不是全局。

进阶学习建议

1. 先读 references/style-diagram-matrix.md：它把「风格 × 图类型」的适配度、9–12 的证据要求与禁止混搭项写成表格，选风格前读一页能省掉大半返工。
2. 再读 references/composition-quality-contract.md：节点间距 40px、容器间隙 20px、每边最多两次弯折、同一业务边不重复画——这些正是 check 在算的东西。
3. 读 references/visual-quality.md：讲每个主题的排版与对比度测量边界，并明确「启发式宽度不等于真实字体渲染」，这条能解释「看起来很挤但分数很高」。
4. 需要 PNG 就翻 references/png-export.md：cairosvg / rsvg-convert / Chromium 三条路径的差异与兜底顺序都在里面。
5. 要动效就读 references/motion-effects.md：哪些风格与拓扑可动、帧段怎么分配、为什么手绘 SVG 不行。
6. 把 schemas/ 与 fixtures/ 当 API 文档：IR 的字段与约束以 schema 为准，12 个 fixture 是最短的可运行样例。

免责声明

本文基于官方仓库（中英双语 README、CHANGELOG、references/、SKILL.md）与本站实测整理，AI 辅助生成。

已实测：2026-11-01 在 Windows 环境跑通 version、doctor、render（790 ms）、check（293 ms，ok）、export-html（278 ms）、animate（18.7 s，GIF 经 ffprobe 独立复核 960×720 / 20fps / 115 帧 / 5.750 s）、text_policy: strict 的失败闭合（rc=1，不写 SVG），两条 PNG 导出路径：export-png 经 cairosvg 2.9.1（849 ms，1920×1440，尺寸回读通过）与 scripts/svg2png.js 经 Chromium（1.76 s，1920×1440）；以及风格 3 / 9 / 11 三份 fixture 的渲染与 check（全部 ok: true，对比度最低 4.92，高于 4.5 阈值）。文中四张效果图均为上述命令的原样产物。

未实测：AI 端到端「自然语言描述 → 出图」的质量与风格命中率（本次走的是官方 fixture 的确定性路径）、12 个风格的逐风格视觉验收、9–12 号工程风格在真实项目证据下的产出、以及在 Codex / Claude Code 宿主内的自动触发行为（本站只在 CLI 层验证）。另：doctor 默认解释器下仍报 png=false，那是因为 cairosvg 只装在独立 venv 里，不是功能缺失。仓库指标（stars/forks/最近推送）取自 GitHub API，采集于 2026-11-01。

参考链接

• GitHub 仓库：源码、fixtures、references、releases
• 官方中文 README
• CHANGELOG：1.0.x → 1.2.0 的能力演进与未发版质量升级
• 发布历史
• 官方展示站：12 风格 GIF 与静态样例
• npm 包：bin 暴露 fireworks-tech-graph，engines.node >=22.12
• GitHub API 仓库元数据：11,905 stars / 935 forks / 1 个未关闭 issue / 最近推送 2026-10-21（核验于 2026-11-01）
• MIT 许可证
• 对照工具：Mermaid、draw.io、Excalidraw