poxiaoxi博客让AI生成一张技术架构图并不困难，真正麻烦的是图能不能直接使用。节点名称可能溢出，连接线可能穿过组件，箭头方向不清楚，复杂架构还容易出现大量交叉线。即使生成结果看起来完整，放进技术文档或评审材料后，也可能因为结构混乱而需要重新手工调整。
Fireworks Tech Graph试图解决的正是这类问题。它并不是一个普通的在线画图网站，也不是输入提示词后直接生成一张不可编辑图片的图像模型，而是一套可以安装到Codex和Claude Code中的Agent Skill。项目把自然语言理解、图结构生成、SVG渲染、几何检查和多格式导出组合成一条相对完整的技术制图流程。
Fireworks Tech Graph是什么
fireworks-tech-graph是一个开源技术图生成项目，主要用于软件架构、数据流、流程图、UML、ER图、云部署、事件流、可观测性分析以及AI Agent系统等工程场景。
用户可以用中文或英文描述需要展示的系统，例如：
画一张RAG系统架构图，包含用户查询、向量检索、重排序、上下文组装和大模型回答流程。
Skill会先判断图表类型，再提取节点、分层、连接关系和数据流，选择对应的视觉风格，最终生成SVG，并根据运行环境继续导出PNG、GIF或离线交互HTML。
项目当前同时适配Codex和Claude Code，两端共用同一套SKILL.md、脚本、模板和参考资料。对于已经使用AI编程工具的开发者来说，它更接近一套可以反复调用的制图能力，而不是需要单独打开和操作的桌面软件。
重点不只是生成
许多AI制图方案将“文件成功输出”视为任务完成，但Fireworks Tech Graph把首轮结果当作候选版本。官方设计了一条受限的生成、验证和修正流程：
Prompt → Diagram Contract → Semantic IR → Style Spec → Route Planner → SVG Build → Structural Validation → PNG Visual Readback → Targeted Revision → Verified SVG + PNG
自然语言首先被整理为图表契约和语义结构，再进入样式选择、路径规划与SVG构建。文件生成后，工具还会检查XML结构、箭头标记、路径几何、节点碰撞、标签位置、画布边界和构图预算。
如果运行环境具备图片读取能力，Agent还会重新查看导出的PNG，检查仅靠代码难以发现的问题，例如文字被裁切、标签压在线路上、图例遮挡内容或者连接线穿过节点。
这种流程的价值在于，它不完全依赖模型自己判断“这张图已经很好看了”，而是尽量用可执行规则和实际渲染结果验证输出。默认视觉修正轮次也受到限制，避免系统在没有明确改善方向的情况下反复修改。
12种风格并不只是换配色
项目提供12种视觉风格，其中11种由生成器驱动，Dark Luxury风格由AI按照样式文档绘制。不同风格不仅在颜色、字体和卡片样式上有所区别，部分风格还绑定了特定工程语义。
扁平图标风适合常规架构说明和技术文章；
暗黑极客风偏向工具调用、终端流程和开发者场景；
工程蓝图风适合微服务、基础设施和复杂系统结构；
Notion极简风强调清晰层级和较少的视觉干扰；
玻璃态卡片风适合展示Multi-Agent协作关系；
Claude与OpenAI风格用于呈现对应视觉语言的AI系统；
Dark Luxury采用深色背景和香槟金结构线；
C4 Review Canvas面向C4架构评审；
Cloud Fabric面向多区域云部署和网络边界；
Event Transit把Topic、处理器和消费者组织为事件轨道；
Ops Pulse用于展示Golden Signals、Trace和可靠性调查路径。
其中后四种风格更接近工程模板。它们要求输入包含对应领域的必要信息，例如C4层级、服务职责、Region与VPC归属、Topic和Consumer Group、遥测数据与关键调用路径。如果描述缺少关键事实，验证过程可能直接失败，而不是用看似合理的内容自动补齐。
这种“失败关闭”机制会降低随意生成的自由度，但也能减少在技术评审中出现架构层级混用、部署边界不清或监控指标缺失等问题。
可以生成哪些技术图
从Skill说明和内置规则来看，Fireworks Tech Graph覆盖的重点并不限于传统流程图。
软件架构图和分层架构图；
数据流图、业务流程图和决策流程图；
Agent、RAG、Mem0和多Agent协作架构；
序列图、状态机图、类图和用例图；
组件图、部署图、包图和对象图；
ER图、网络拓扑和技术概念图；
C4评审图、多区域云部署图；
事件驱动架构和可靠性排查图；
技术时间线、功能矩阵和工程关系图。
项目内置了一套语义形状规则。例如，LLM可以使用双边框矩形，Agent使用六边形，向量存储使用带内环的圆柱体。箭头也可以通过颜色和虚线形式区分读取、写入、异步调用与循环关系。
这种做法可以让同一套文档中的技术图保持较稳定的视觉语言。读者看到形状和线路样式时，不必每次重新理解它们代表什么。
输出不只是一张PNG
Fireworks Tech Graph的基础输出是SVG。相比直接生成位图，SVG更适合技术文档，因为它可以继续编辑、放大，并能在网页和Markdown文档中保持清晰。
项目还支持以下输出形式：
SVG：保留结构和矢量信息，适合继续编辑或嵌入网页；
PNG：官方示例通常导出为1920像素宽，适合文章、演示和文档；
离线HTML：单文件保存，支持平移、缩放、主题切换、复制SVG以及多倍尺寸导出；
GIF：将受支持的语义SVG转换为具有线路构建和数据流效果的动画。
离线HTML不需要依赖在线服务，适合通过本地文件、邮件或内部文档系统分享。打开后可以查看细节，并导出SVG、PNG、JPEG或WebP。
GIF功能则有更严格的限制。它并不是通用的图片转动画工具，只接受由项目生成、并且符合语义结构要求的SVG。目前动画输出格式限定为GIF，不支持把任意PNG、照片或外部SVG直接转换为同样的动效。
统一CLI能做什么
仓库提供了统一的Python命令行入口scripts/fireworks.py，将环境检查、验证、渲染、检查和导出操作集中在一起。
python3 scripts/fireworks.py doctor python3 scripts/fireworks.py validate architecture input.json python3 scripts/fireworks.py render architecture input.json diagram.svg python3 scripts/fireworks.py check diagram.svg python3 scripts/fireworks.py inspect diagram.svg python3 scripts/fireworks.py export-html diagram.svg diagram.html python3 scripts/fireworks.py animate diagram.svg diagram.gif
doctor用于检查Python、CairoSVG、rsvg-convert、Node.js、FFmpeg和动画渲染环境；validate检查图表JSON和语义结构；render生成SVG；check检查SVG的结构与几何问题；inspect读取图中的语义元数据；export-html生成离线交互页面；animate负责输出经过验证的GIF。
这套CLI使项目不仅能被Agent自动调用，也可以被开发者放进本地脚本、文档构建流程或持续集成任务中。
如何安装到Codex和Claude Code
官方推荐通过skills命令安装完整Skill，并明确要求使用仓库中的嵌套路径：
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文件，无法完整复制脚本、Schema、Fixture和参考资料。
需要直接修改源码或持续跟踪仓库更新时，也可以使用Git克隆到对应的Skill目录：
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git \ ~/.agents/skills/fireworks-tech-graph
Claude Code的默认发现目录则是~/.claude/skills/fireworks-tech-graph。在macOS、Linux、WSL和Git Bash环境中可以使用官方提供的Shell命令；原生Windows需要将路径替换为用户目录下对应的.agents\skills或.claude\skills目录。
运行环境并非完全零配置
项目本身以Agent Skill和Python脚本为主，但不同导出能力依赖不同的本地组件。
基础脚本要求Python 3.9或更高版本；
PNG导出推荐安装CairoSVG，也可以使用rsvg-convert；
项目声明的Node.js运行基线为18或更高版本；
GIF动画需要FFmpeg、FFprobe、Chrome或Chromium；
浏览器渲染还需要Puppeteer或Puppeteer Core。
只需要生成和检查SVG时，环境相对简单。需要高质量PNG、离线交互导出或GIF动效时，安装步骤会明显增加。团队在引入项目前，最好先通过doctor命令确认本机或CI环境是否满足要求。
适合放进哪些工作流程
技术文档与开发者内容
技术文章经常需要解释系统结构、调用链和数据流。使用自然语言生成初稿，再通过SVG校验和PNG回读，可以减少手工摆放节点和调整箭头的时间。SVG文件还可以继续修改，不必在发现一个错别字后重新生成整张位图。
架构评审与方案讨论
C4、Cloud Fabric、Event Transit和Ops Pulse等工程风格适合团队围绕架构层级、部署归属、事件流和可靠性问题进行讨论。语义契约会要求输入更具体的信息，也能反过来暴露方案中没有讲清楚的部分。
AI与Agent系统说明
项目内置RAG、Agentic Search、Mem0、Multi-Agent和Tool Call等领域模式。需要展示模型、工具、记忆、向量数据库和外部服务之间的关系时，可以直接使用对应的图形和箭头语义。
离线交付和内部分享
单文件HTML适合无法部署在线服务的场景。接收者不需要安装编辑器，就可以缩放查看复杂图表，并根据需要导出不同格式。
版本与开源许可
根据项目更新日志，1.2.0版本发布于2026年7月17日，主要增加了语义SVG转GIF流程、12种风格动画签名、动画验证报告和跨平台回归检查。此前的1.1.0版本则加入了四种工程风格、版本化Diagram IR、统一CLI、离线HTML导出和更严格的几何验证。
项目采用MIT许可证，允许使用、复制、修改、合并、发布和分发代码，但需要保留许可证与版权声明。许可证同时说明软件按现状提供，不附带适销性、特定用途适用性等担保，生产环境使用者仍需自行验证生成结果。
精彩评论