Fireworks Tech Graph

这是什么？适合谁？

Fireworks Tech Graph（https://github.com/yizhiyanhua-ai/fireworks-tech-graph，10.7k+ Stars、870+ Forks，MIT 协议）是一个以「Agent Skill」形态分发的技术架构图生成器——它不是一个独立的 GUI 或 SaaS，而是同一个技能文件，在 Codex CLI 和 Claude Code 里原样安装、原样运行。核心口号直白：别再手动画图了，用中文或英文描述你的系统，就能得到一张几何安全（geometry-safe）的 SVG、一张高清 PNG，以及可选的 SVG 转 GIF 语义动效和离线可交互 HTML。

它最突出的能力是「工程化的生成闭环」，而不是简单的「让模型画一张图」。生成流程严格走 Prompt → Diagram Contract → Semantic IR → Style Spec → Route Planner → SVG Build → Structural Validation → PNG Visual Readback → Targeted Revision，最终产出经过验证的 SVG + PNG。用项目自己的话说：Evaluate, don’t assert——完成与否由校验器和渲染证据背书，而不是模型嘴上说「画好了」。

横向对比同类工具，定位差异非常清晰：Mermaid 需要手写 DSL 语法，不支持自然语言输入，也没有 AI/Agent 领域的内置图模式；draw.io 适合手动精修，但完全靠拖拽，出图慢；Structurizr 专注 C4 模型，通用架构图支持有限；Eraser、Excalidraw 是白板式工具，灵活但缺乏「生成即生产级」的约束。Fireworks Tech Graph 的唯一卖点就是描述即出图：不写 DSL、不点 GUI，一句话拿到可直接嵌入文档的 1920px PNG。

适合人群：架构师和技术负责人（快速产出评审用 C4 图、部署拓扑图、可靠性脉搏图）；技术文档工程师（批量生成统一风格的架构图）；在 Codex CLI / Claude Code 里写代码、顺手出图的开发者团队。

不适合人群：需要像素级手绘自由度的设计师（SVG 是语义化产物，非自由画布）；只需要一句话流程图的轻量场景（用 Mermaid 更快更省）；完全不想接触命令行的用户（它依赖 AI 编码工具运行）。

准备工作

1. 宿主运行时（二选一或都装）：技能跑在 Codex CLI 或 Claude Code 里。Codex 走 OpenAI 账号，ChatGPT Plus 订阅 $20/月（或按量计费的 OpenAI API）；Claude Code 走 Anthropic 账号，Claude Pro $20/月、Claude Max $100/月（5 倍额度）或 $200/月（20 倍额度），也可接 Anthropic API 按 token 计费。技能本身 MIT 免费，成本全部来自你的 AI 编码工具订阅。
2. 安装命令（推荐 skills CLI，一次性装到两个 runtime）：

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

   ⚠️ 必须用嵌套路径 /skills/fireworks-tech-graph，裸仓库路径只会选中根 SKILL.md，丢掉 scripts/schemas/fixtures/references 等完整文件。
3. 渲染依赖：Python 3.9+ 必装；python3 -m pip install cairosvg（默认推荐，免费开源）。备用渲染器 rsvg-convert（brew install librsvg / sudo apt install librsvg2-bin，免费）。若需要 SVG 转 GIF 动效，再加 FFmpeg（免费）和 puppeteer-core@25.3.0（免费，需 Node.js 18+）。
4. 前置知识：不需要任何 DSL 语法；只要能清楚描述「有哪些组件、它们怎么连接」即可。懂一点 C4/UML 概念能让你提示词更精准，但不是必需。
5. 替代方案：当不想引入 Codex/Claude 时，Mermaid（纯文本 DSL）、draw.io（免费 GUI）、Structurizr（C4 专用）、Eraser（AI 白板）都可作为退路，但它们都无法做到「一句中文直接出 1920px 生产级 SVG+PNG + 几何校验」。

4 步核心流程

第 1 步：安装技能到 Codex / Claude Code

用上面的 npx skills add 命令安装后，技能会复制到 ~/.agents/skills/fireworks-tech-graph（Codex）和 ~/.claude/skills/fireworks-tech-graph（Claude Code），包含 scripts、schemas、fixtures、templates、tests、references 全套文件。也可以用 git clone 手动安装并保持可编辑：

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

安装完成后重启 Codex 和 Claude Code，让两个 runtime 发现这个技能。Windows 原生环境使用 %USERPROFILE%\.agents\skills 和 %USERPROFILE%\.claude\skills 等价路径。

预期产出：在 Codex 或 Claude Code 里输入「draw a RAG pipeline flowchart」，技能能自动触发（无需手动调用），开始生成图表。

第 2 步：准备渲染依赖

先做一次环境自检，技能自带 doctor 子命令会告诉你缺什么：

SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}"
python3 "$SKILL_ROOT/scripts/fireworks.py" doctor

默认渲染器 cairosvg 一条命令装好；若要 GIF 动效，还需在每个已复制的技能目录旁装 puppeteer-core（渲染器刻意不从调用方目录加载模块）：

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

预期产出：doctor 报告所有渲染链路就绪；验证 python3 -c "import cairosvg; print(cairosvg.__version__)" 能输出版本号。

第 3 步：用自然语言描述系统并生成图表

这是核心步骤。技能在 Codex/Claude Code 里通过触发短语自动激活（generate diagram、draw diagram、create chart、架构图、流程图、序列图 等）。可以直接粘贴这些可复制的提示词模板：

Generate a Mem0 memory architecture diagram with vector store, graph DB, KV store, and memory manager

Draw a microservices architecture: Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL + Redis

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

指定风格时用 style N（1–12）比用描述词更稳。12 种风格包括：Flat Icon（默认）、Dark Terminal、Blueprint、Notion Clean、Glassmorphism、Claude Official、OpenAI Official、Dark Luxury（AI 生成风格）、C4 Review Canvas、Cloud Fabric、Event Transit、Ops Pulse——后四种是「工程优先」风格，携带可执行的语义契约（C4 抽象层级、云部署归属、事件轨道拓扑、黄金信号）。

预期产出：同目录下生成 *.svg（可编辑源图）和 *.png（1920px 高清图），并在状态里报告 validation: passed。

第 4 步：校验、导出与生成动效

生成是闭环的，最后一步做校验和导出。统一 CLI 覆盖全流程：

python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture "$SKILL_ROOT/fixtures/api-flow-style7.json"
python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture "$SKILL_ROOT/fixtures/api-flow-style7.json" diagram.svg --report layout.json
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
python3 "$SKILL_ROOT/scripts/fireworks.py" export-html diagram.svg diagram.html --title "Agent Runtime Architecture"

要动效就直接在对话里说「让这张图动起来 / 生成 GIF / 把刚才的 SVG 转成 GIF」，命令接受携带已批准动效契约的语义 SVG，输出 960px、5.75 秒、20fps 的 GIF，并附 .motion.json 校验报告。export-html 产出的离线 HTML 单文件自带 pan/zoom、明暗双主题、SVG 源码复制，以及 1×–4× 的 SVG/PNG/JPEG/WebP 下载。

预期产出：一张通过结构化校验 + 视觉回读的 SVG + PNG，可选 GIF 动效和离线交互 HTML；状态显示 validation: passed 与 visual_review: passed。

常见踩坑（7 条）

踩坑 1：安装后技能不生效

• 症状：在 Codex/Claude Code 里说「draw diagram」没反应
• 原因：安装后没重启 runtime，技能未被发现
• 解决：安装后重启 Codex 和 Claude Code；后续改 SKILL.md 会自动被检测，改 scripts/references 后也需重启

踩坑 2：装了但缺脚本，报找不到 fireworks.py

• 症状：scripts/fireworks.py 不存在或功能残缺
• 原因：用了裸仓库路径安装，只拉到根 SKILL.md
• 解决：改用嵌套路径 yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph 重装

踩坑 3：GIF 动效报错或输出空白

• 症状：animate 失败，或生成的 GIF 无内容
• 原因：缺 FFmpeg/Chromium 或 puppeteer-core 没装到技能目录旁
• 解决：npm install --prefix "$SKILL_ROOT" ... puppeteer-core@25.3.0 装到每个已复制技能目录，再跑 doctor 自检

踩坑 4：rsvg-convert 渲染丢样式

• 症状：导出的 PNG 丢失 CSS 样式或 foreignObject 内容
• 原因：rsvg-convert 是备选渲染器，CSS 支持弱
• 解决：默认改用 cairosvg（pip install cairosvg），仅在没有 Python 的环境才退回 rsvg

踩坑 5：状态显示 visual_review: skipped

• 症状：报告里 visual_review: skipped (image reader unavailable)
• 原因：当前 runtime 无法读图（视觉能力不可用）
• 解决：换用支持视觉回读的 runtime 再跑；这是显式的诚实降级，不是报错，但此时视觉质量未经验证

踩坑 6：风格指定不生效

• 症状：说「暗色风格」但出图仍是默认风格
• 原因：触发词命中的是风格描述而非编号，路由不确定
• 解决：用 style N（1–12）显式指定；工程风格（9–12）还需写对场景指纹（如 C4 review board）

踩坑 7：Windows 下路径找不到技能

• 症状：命令报 skill 目录不存在
• 原因：照抄了 macOS/Linux 的 ~/.agents/skills 路径
• 解决：Windows 用 %USERPROFILE%\.agents\skills 和 %USERPROFILE%\.claude\skills

常见问题 FAQ

Q1：Fireworks Tech Graph 免费吗？ A：技能本身 MIT 免费。成本来自宿主——Codex CLI（ChatGPT Plus $20/月或 API 按量）或 Claude Code（Pro $20/月、Max $100–200/月或 API），加上本地渲染依赖（cairosvg、FFmpeg 均免费开源）。参考：官方 README。

Q2：和 Mermaid、draw.io 到底怎么选？ A：Mermaid 适合「写进 Markdown 的轻量内联图」，draw.io 适合「手动精修」，Fireworks Tech Graph 适合「描述系统立即拿到生产级图」。它支持自然语言输入、12 种内置风格、自动 1920px PNG 导出、语义箭头配色——这三样 Mermaid/draw.io 都要手动或根本不支持。官方 README 有完整对比表：Why Not Mermaid or draw.io?。

Q3：必须同时装 Codex 和 Claude Code 吗？ A：不用，二选一即可。它是同一个 SKILL.md，在两者中原样运行；两个都装可以共享一份 checkout（用符号链接），但只是图方便，不是必需。

Q4：支持中文吗？能画哪些图？ A：完全支持中文描述（触发短语含「架构图」「流程图」「生成 GIF」等中文）。图类型覆盖 14 类——完整 UML（类图、组件图、部署图、序列图、状态机、活动图、时序图、ER 图等）加 AI/Agent 领域图（RAG、Agentic Search、Mem0、Multi-Agent、Tool Call 等）。

Q5：怎么控制成本 / 用便宜模型？ A：出图质量来自几何校验闭环而非昂贵模型，用 DeepSeek 等低价 API 作为 Codex/Claude 的底层模型即可显著降本；流程本身不依赖任何在线绘图 SaaS，本地渲染零额外费用。追求极致时用离线 HTML 导出替代反复生成。

参考链接

• Fireworks Tech Graph GitHub 仓库
• 官方主页 / 在线文档
• npm 包 @yizhiyanhua-ai/fireworks-tech-graph
• 英文 README

---

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。