fireworks-tech-graph：用自然语言生成工程级技术图的 Agent Ski…

一、它解决什么痛点：别再手画架构图

写技术文档的人大多被同一件事折磨过：脑子里有清晰的系统结构，落到画图软件里却要和网格线、对齐、连线死磕半天。README 的开篇就一句话点题：Stop drawing diagrams by hand. 用中英文描述系统，就能拿到「几何安全」的 SVG、PNG，以及聚焦的 SVG 转 GIF 动效与离线交互图。

（一）Mermaid / draw.io 的短板

Mermaid 要你写 DSL 语法，draw.io 要你拖控件对齐。两者都不是「描述意图即出图」。README 自己做了对比：Mermaid 和 draw.io 在自然语言输入、AI/Agent 领域模式、多视觉风格、高清 PNG 导出、语义箭头着色上都是缺失或手动的；而 fireworks 这五项全为「是」。它不是要取代这两者，而是补上「你说、它画」这一环。

（二）fireworks 的差异化

真正的差异在「工程化」：它不靠模型「觉得画对了」就交付，而是把风格指南编码进生成器，再用确定性几何校验兜底。Overview 里说它「turns natural language descriptions into polished, geometry-checked SVG」，并且同一套风格系统共享一份组合质量契约（零交叉、每边至多两个弯等）。这让它在「好看」之外，还保证了「不出错」。

二、12 种视觉风格与 14 类图

（一）风格一览（含 AI 撰写的 Dark Luxury）

README 的 12 风格表把每种风格的背景、字体、最佳场景列得清清楚楚：

• Style 1 Flat Icon（默认，白底 Helvetica，适合博客 / 幻灯片）；
• Style 2 Dark Terminal（深底等宽字体，适合 GitHub README、技术文章）；
• Style 3 Blueprint（蓝图纸感，工程向）；
• Style 4 Notion Clean（极简，适合 wiki / 知识库）；
• Style 5 Glassmorphism（毛玻璃，产品官网 / 演讲）；
• Style 6 Claude Official / Style 7 OpenAI Official（两家官方审美）；
• Style 8 Dark Luxury：唯一由 AI 撰写的样式（深黑底、香槟金层级）；
• Style 9~12：C4 评审画布、多云部署、事件地铁、可靠性脉冲——四个「工程优先」风格，各自带可执行的领域契约。

样式选择指南还会按 UML / AI Agent / 文档 / 工程评审 / 品牌给出推荐，几乎把「什么图配什么皮」想透了。

▲ 12 种风格并非空名号，仓库里的画廊截图把它们并排摆出来，差异一目了然。

（二）图类型与全 UML 覆盖

它支持 Architecture（架构）、Data Flow（数据流）、Flowchart（流程图）、Agent Architecture、Memory Architecture、Sequence、Comparison、Mind Map 等通用类型；更关键的是完整 14 类 UML：Class、Component、Deployment、Package、Composite Structure、Object、Use Case、Activity、State Machine、Sequence、Communication、Timing、Interaction Overview、ER Diagram。README 还逐一标了每类 UML 的最佳风格，比如时序图配 Dark Terminal、状态机配 Blueprint。对要画标准 UML 的开发者，这份覆盖度很少见。

三、领域模式与语义体系

（一）AI/Agent 内置模式

它不是通用画图器，而是「懂 AI 系统」的画图器。README 把常见链路固化成模式：RAG Pipeline（Query→Embed→VectorSearch→Retrieve→LLM→Response）、Agentic RAG（加 Agent loop + Tool）、Agentic Search、Mem0 记忆层、Agent 记忆五型（Sensory→Working→Episodic→Semantic→Procedural）、Multi-Agent（Orchestrator→SubAgent×N→Aggregator）、Tool Call Flow（LLM→Tool Selector→Execution→Parser→LLM 循环）。你只要说「画个 Mem0 记忆架构」，它就知道该摆向量库、图数据库、KV 存储与记忆管理器。

（二）形状与箭头的语义

为了「看图即懂」，它定义了一套语义词汇：LLM 用双边框圆角矩形，Agent / 编排器用六边形，向量库用带内环的圆柱，外部服务用虚线边框。箭头则用颜色加虚线模式编码含义——主数据流是 2px 实线，内存写入是 5,3 虚线，异步 / 事件是 4,2 虚线，反馈循环是弯曲实线。这一层语义，让图在不写图例时也能自解释。

四、怎么装：Codex 与 Claude Code 双运行时

（一）推荐安装（npx skills）

README 推荐用 skills CLI 安装完整 skill（注意必须带嵌套路径 /skills/fireworks-tech-graph，否则某些版本只会选到根 SKILL.md）：

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

这条命令会同时在 Codex 的 ~/.agents/skills 与 Claude Code 的 ~/.claude/skills 下建立完整副本，含脚本、schema、fixtures、模板、测试与参考文档。

（二）Git 可编辑安装与更新

想改样式或追新，可以 git clone 到对应目录；两个运行时还能用软链接共用一份 checkout。更新只需在对应目录 git pull。Windows 原生路径对应 %USERPROFILE%\.agents\skills 与 %USERPROFILE%\.claude\skills；Python 需 3.9+，可选 Puppeteer 路径需 Node.js 22.12+。装完重启一次运行时即可被发现。

五、怎么用：触发词与统一 CLI

（一）自然语言触发

它会在你说 generate diagram / draw diagram / create chart / visualize / architecture diagram / flowchart 等时自动触发；中文「生成 GIF / 制作 GIF / 让这张图动起来」也能唤起动效。日常用法极其口语化：

Draw a RAG pipeline flowchart
Generate an Agentic Search architecture diagram
Draw a microservices architecture diagram, style 2 (dark terminal)
Generate a Mem0 architecture diagram, output to ~/Desktop/

（二）脚本化：doctor / validate / render / animate

除了对话触发，它还提供统一 CLI scripts/fireworks.py：doctor 检查渲染器依赖，validate 校验图 IR，render 渲染 SVG 并出布局报告，check 做结构化校验，export-html 导出一个离线交互页，animate 把 SVG 转成 GIF。这条 CLI 路径让它能无缝进 CI 或批处理流水线。

六、核心机制：闭环校验与几何安全

（一）Loop Engineering：候选 → 校验 → 修订

README 把出图定义为一条有界闭环：Prompt→Diagram Contract→Semantic IR→Style Spec→Route Planner→SVG Build→Structural Validation→PNG Visual Readback→Targeted Revision→Verified SVG+PNG。它强调五条原则：用证据评估而非断言、确定性检查优先、感知校验其次、针对性修正、有界收敛（默认最多两轮聚焦修正，防止无限自改）。最终状态会明确打印 validation: passed 与 visual_review: passed；若环境读不了图，则如实标注 skipped，绝不假装已验证。

（二）几何约束与失败即止

「几何安全」不是口号。共享的组合质量契约要求零交叉 / 零桥跳、每边至多两个弯、整体至多八个弯、节点间距 ≥40px、容器留白 ≥20px、标签避开节点与连线。工程优先的 Style 9~12 还会在执行前校验专属领域字段，缺失或错误直接 fail closed（失败即止），而不是画出一张似是而非的图。这种「宁可报错也不交付脏图」的取向，是它区别于玩具级生成器的地方。

七、SVG 转 GIF 动效与离线 HTML

除了静态图，它支持「聚焦语义 GIF 动效」：输入一张语义 SVG，输出一段校验过的 GIF——连线从无到有、按语义顺序逐条画出。README 把默认时间线定得很细：960px、5.75 秒、20fps、115 帧，前 36 帧画路由、38 帧淡入实时流、38~109 帧保持完整稳态、110~114 帧复位。HTML 导出则是单个离线文件，带缩放 / 重置、明暗主题、SVG 源码复制，以及 1×~4× 的 SVG/PNG/JPEG/WebP 下载。这意味着你交付的不只是图，而是能演示、能交互的资产。

八、局限与注意事项

（一）依赖与渲染器

SVG/PNG 脚本需要 cairosvg（推荐）或 rsvg-convert；GIF 动效还要 FFmpeg/FFprobe、Chrome/Chromium 与 puppeteer。README 的对比表很诚实：cairosvg 质量好、一条 pip 命令搞定，是默认选择；rsvg-convert 在 CSS / foreignObject 上会丢东西；puppeteer 像素最准但最重。排错表也点名了常见坑——SVG 里写了 @import url() 外部字体，cairosvg 和 rsvg 都拉不到，会出空白或黑图，应改用系统字体栈。

（二）工程风格需要领域字段

Style 9~12 不是换个皮肤那么简单：C4 评审要你给「一个抽象层级 + 职责 + 技术 + 协议」，多云部署要「全局入口、Region/VPC 归属、跨区复制」，事件地铁要「主题轨道、处理器、消费者组、DLQ」。如果 prompt 没覆盖这些角色 / 阶段 / 顺序，它会直接 fail closed。换句话说，越专业的风格，对你描述精度的要求越高。

九、总结

fireworks-tech-graph 的价值，不在于「AI 会画图」这个噱头，而在于把画图这件事工程化了：语义词汇让图自解释，12 风格 + 14 类 UML 覆盖绝大多数技术写作场景，而有界闭环与几何契约保证了「交付的图是干净、可验证的」。对写架构文档、做技术分享、产 AI 系统示意图的开发者，它基本能做到「说一句、出一张能直接用的图」。代价是要接受它的依赖栈与工程风格的字段要求——但只要你的描述够清楚，回报是显著的效率提升。

在撰写本文的过程中，我主要参考了以下来源：GitHub 仓库 yizhiyanhua-ai/fireworks-tech-graph 的 README（Overview、Features、Loop Engineering、Installation、Unified CLI、Why Not Mermaid、Usage、12 Styles、Diagram Types、Patterns、Shapes、Arrows、Troubleshooting、License），以及仓库 meta.json（stars / license / language）。文中数据以仓库公开信息为准，可能随版本更新而变化。