fireworks-tech-graph 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

fireworks-tech-graph 是一个基于 Python 脚本实现的技术图生成项目，同时以 Agent Skill（智能体技能）的形式服务于 Codex 和 Claude Code。它接收中文或英文的自然语言系统描述，生成经过几何校验的 SVG（Scalable Vector Graphics，可缩放矢量图）、PNG、聚焦的 SVG 转 GIF 动效以及离线交互 HTML。

根据仓库提供的 GitHub 元信息，项目当前公开数据为 11460 个 Star、904 个 Fork，主要语言为 Python，默认分支为 main，许可证为 MIT。仓库的 package.json 将版本标为 1.2.0；README 同时说明，公开展示的 GIF 样例使用已发布的 1.2.0 参考版本，而当前工作树中的部分升级未必对应一个新的公开版本。

不用手画图了。用中文描述你的系统，直接得到通过几何门禁的 SVG、PNG、聚焦的 SVG 转 GIF 动效与离线交互技术图。
来源：README.zh.md

定位与目标用户

这个项目解决的是技术架构图、流程图和 UML 图制作中的重复绘制与格式转换问题。它的重点不是提供一个通用的图形编辑器，而是把自然语言输入、图类型识别、布局生成、几何检查和多格式导出组合成一条可执行流程。

目标用户包括需要快速产出架构说明的后端和平台工程师、需要维护技术文档的团队、使用 Codex 或 Claude Code 的开发者，以及希望把 Agent、模型、工具调用和记忆系统画成统一视觉样式的项目维护者。README 还列出 C4 评审、云部署、事件流和可靠性排查等工程场景，因此它也适合用于设计评审材料与故障分析文档的初稿制作。

• 输入侧：用中文或英文描述系统组件、数据流、职责和关系。
• 处理侧：识别图类型与视觉风格，并生成带有语义结构的图形。
• 校验侧：检查画布根节点、边界、文字适配、线束路由和动效媒体结果。
• 输出侧：写出 SVG、PNG、GIF 或离线 HTML，具体能力取决于调用路径和本地依赖。

核心功能

核心功能可以理解为“自然语言到技术图”的转换链，而不是单独的 SVG 绘图库。输入描述会先被归类为某种图类型和风格，再交给生成逻辑形成节点、泳道、存储体、箭头及文字，随后执行几何和输出质量检查。

自然语言生成技术图

README 给出的示例是“画一张 Mem0 的架构图，暗黑风格”。Skill 会将其识别为 Memory Architecture Diagram 和对应风格，再生成含泳道、圆柱体及语义箭头的 SVG，最后可以导出 1920 像素宽的 PNG。输入是自然语言，主要输出是语义化 SVG；PNG 则是后续导出物。

这种流程适合先表达系统关系，再由生成器处理位置和连接关系。具体的自然语言分类规则、完整提示词格式和所有可用字段，资料没有完整列出，使用时应以仓库中的 SKILL.md、schemas/ 和最新 README 为准。

多视觉风格与工程化场景

中文 README 展示了 12 种风格：扁平图标风、暗黑极客风、工程蓝图风、Notion 极简风、玻璃态卡片风、Claude 官方风格、OpenAI 官方风格、暗黑奢华风、C4 评审画布、Cloud Fabric、Event Transit 和 Ops Pulse。项目概述将其解释为 11 种生成器风格加 1 种 AI 手绘风格，其中 Dark Luxury 属于 AI-authored style（AI 手绘风格）。

风格不仅改变颜色和装饰，也会影响构图契约。例如 C4 评审画布强调单一抽象层级、职责、技术栈和协议；Event Transit 使用 Topic 轨道、处理站点、显式 Junction、DLQ 和状态投影；Ops Pulse 则围绕 Golden Signals、关键路径、OpenTelemetry 导出和关联 Trace 组织内容。资料没有提供每种风格的完整参数接口，因此不能把这些名称推断成可直接传入的配置字段。

UML 与 AI/Agent 图类型

仓库徽章标注支持 14 种图类型，README 明确写有全部 14 种 UML 图类型，并同时覆盖 AI/Agent Pattern（人工智能与智能体模式）。这意味着它可以用于表达类、时序、组件、状态或其他 UML 语义，但资料没有逐项列出 14 种图类型的名称及其命令参数。

在使用 UML 或 Agent 图时，输入应尽量明确参与者、边界、调用方向、状态变化和数据归属。图类型自动识别失败时，官方仓库未提供统一的错误码或调试协议，建议检查生成报告、参考仓库中的示例和 Schema 文件。

SVG、PNG、GIF 与离线 HTML 输出

SVG 是主要的结构化中间结果，PNG 导出器会检查根画布和边界图像尺寸，采用原子写入，并回读生成文件的实际像素宽高。README 还说明，浏览器 PNG 导出器仍然可用于需要 Chromium 还原效果的场景，但资料没有给出该导出器的完整命令签名。

GIF 路径是聚焦的 SVG-to-GIF（SVG 转 GIF）动效链路，只接收生成器产生的语义 SVG，并输出一个经过探测的紧凑 GIF。中文 README 给出的已验收样例采用 5.75 秒 settled-flow 时间线、20fps、115 帧和 960 像素宽；这些是样例回归基线，不应解读为所有输入的性能保证。

离线交互 HTML 用于在不依赖在线服务的情况下查看技术图。项目资料没有说明该 HTML 是否包含全部运行时依赖、浏览器最低版本或跨平台兼容矩阵，部署前应以具体生成结果和仓库文档为准。

系统架构与关键模块

从仓库结构和 README 描述看，项目由 Skill 描述层、生成与导出脚本、Schema 与模板、参考文档、示例及测试组成。以下分层依据公开文件名和 README 能力整理；其中模块之间的精确调用关系，若仓库源码未在资料中展开，则属于结构性说明而非源码级结论。

输入与分类层

SKILL.md 是面向 Codex 和 Claude Code 的 Skill 入口描述，负责约束自然语言任务的处理方式。用户输入系统组件、关系、风格或图类型后，Skill 需要把任务转为可生成的图形意图；README 示例显示，这一阶段至少会涉及图类型和 Style 编号的识别。

生成与语义模型层

schemas/、templates/ 和 references/ 从目录命名上承担结构约束、模板和质量参考职责。生成结果不是只包含像素的图片，而是包含节点、箭头、标签和布局信息的 SVG，这使得后续 PNG 导出、动效处理和文字检查可以围绕同一份结构化结果进行。

验证与报告层

README 提到完整文字报告、text_policy、几何门禁、文字适配、线束路由和媒体探测。设置 "text_policy": "strict" 后，系统会在写文件前拒绝可见文字截断；报告会保留完整源标签并说明恢复方式。中文描述会使用可用的第二行，这表示文字布局并非单纯按一行硬裁剪。

命令行与分发层

scripts/fireworks.py 是 package.json 中声明的命令入口，命令名为 fireworks-tech-graph。同一文件还声明了测试、项目一致性检查和示例命令，说明仓库把生成、检查和示例运行纳入了可重复的脚本流程。

依赖与运行环境

公开资料确认项目主要语言为 Python，命令示例使用 python3。同时，package.json 的 engines 字段声明 Node.js 版本要求为 >=22.12.0；这属于包元数据中的运行环境约束，但资料没有说明每个 Python 依赖的版本。

资料没有提供 requirements.txt、pyproject.toml 或容器配置，因此不能可靠地补写 Python 包安装命令。运行前应先执行 version 和 doctor，以确认实际 Skill 根目录、包版本、Git 状态以及 SVG、HTML、PNG、GIF 的条件。

快速开始（含最小可运行示例）

最小闭环可以分为获取仓库、运行版本检查、执行已有 SVG 的 PNG 导出和验证输出文件四步。由于资料没有给出独立的安装包安装命令，下面采用官方仓库检出方式，不假设额外的第三方依赖安装流程。

1. 获取仓库并检查入口

git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git
cd fireworks-tech-graph
python3 scripts/fireworks.py version
python3 scripts/fireworks.py doctor

version 根据 README 会报告包版本、实际 Skill 根目录以及可用的 Git 状态。doctor 会分别报告 SVG、HTML、PNG 和 GIF 的运行条件；这一步适合在本地环境刚准备好时完成。

2. 运行最小导出示例

下面的命令使用 README 明确给出的输入和参数，把当前目录中的 diagram.svg 导出为宽度 1920 的 PNG。该示例要求输入文件已经存在；资料没有提供生成 diagram.svg 的独立命令，因此不能把不存在的生成参数写入示例。

python3 scripts/fireworks.py export-png diagram.svg diagram.png --width 1920

如果仓库或当前工作目录中没有 diagram.svg，应先按照最新 README、示例目录或 Skill 指令生成语义 SVG。不要把任意外部 SVG 直接视为符合动效链路要求的输入，因为 README 明确说明聚焦动效路径只接收生成器产出的语义 SVG。

3. 验证输出

test -s diagram.png
file diagram.png
python3 scripts/fireworks.py version

第一条命令验证文件存在且非空，第二条命令查看本地文件类型，第三条命令再次确认当前调用的包和 Skill 根目录。README 已说明 PNG 导出器会回读实际像素宽高；具体宽高检查报告格式未在资料中给出。

配置说明

仓库资料只明确给出了一个输出策略字段 text_policy，没有提供完整的用户配置文件样例、环境变量清单或默认配置文件。下表因此同时列出实际存在于 package.json 的项目脚本和运行元数据，帮助维护者区分“可配置字段”和“包级声明”。

如果需要启用严格文字策略，应把 text_policy 放入仓库实际支持的输入或配置结构中；资料没有给出该字段的完整外层对象、命令行参数或配置文件路径。环境变量、端口、API Key 和服务端监听地址均未在资料中提供，不能据此推导。

进阶用法

进阶使用的重点是利用语义输入控制图的抽象层级，而不是通过手工修改输出坐标来修补所有问题。对于评审图，应明确边界、职责、协议和技术栈；对于事件流，应明确 Topic、处理站点、失败队列和状态投影。

• 架构评审：选择 C4 评审画布时，将系统、容器或组件的抽象层级控制在同一张图内，并写出每个节点的职责和技术栈。
• 云部署：描述全局入口、Region、VPC 归属、跨区复制和活动状态，适合表达 Active–Active Checkout Deployment 场景。
• 事件流：把生产者、Topic、处理站点、Junction、DLQ 和状态投影写清楚，避免只画一条没有语义的连接线。
• 可靠性排查：输入 Golden Signals、关键路径、OpenTelemetry 导出和关联 Trace，便于把指标、链路与服务拓扑放在同一视图中。
• 文字质量控制：对需要用于评审或发布的图使用 text_policy: strict，发现截断后依据报告调整标签或布局。

根据本文作者的经验判断，结构化输入比单纯增加形容词更有助于稳定布局。输入至少应包含参与者、方向、关系类型、数据或调用名称、边界和期望风格；这是写作和建模层面的建议，不是仓库声明的硬性接口。

可观测性与运维

项目提供的可观测性主要面向生成过程和文件产物，而不是在线服务监控。version 用于确认版本与 Skill 根目录，doctor 用于区分 SVG、HTML、PNG、GIF 的运行条件，生成报告则用于定位文字截断和输出质量问题。

建议的本地检查顺序

1. 执行 python3 scripts/fireworks.py version，记录包版本、Skill 路径和 Git 状态。
2. 执行 python3 scripts/fireworks.py doctor，确认目标格式的运行条件。
3. 使用 text_policy 严格模式处理需要发布的文字内容，并保留报告。
4. 检查 SVG 的根画布、节点边界、文字是否截断，以及导出 PNG 的实际像素尺寸。
5. 如使用 GIF，确认输入来自生成器产出的语义 SVG，并检查最终媒体是否通过探测。

资料没有提供日志级别、日志文件路径、指标端点、端口、健康检查 URL 或 SLA。它也没有说明如何把报告接入 Prometheus、OpenTelemetry Collector 或其他监控系统，因此不应把项目描述成带有在线服务观测面的平台。

安全与合规边界

项目的公开功能集中在技术图生成、格式导出和离线展示，资料没有显示其包含爬虫、渗透、账号自动化、支付、模型越狱或未授权访问能力。安全边界的重点是输入内容、生成文件和本地执行环境的治理。

• 只处理具有合法授权的系统架构、流程和数据描述，不把第三方未公开系统信息输入到不受控环境。
• 如果自然语言描述包含密钥、令牌、个人信息或内部拓扑，应在生成前脱敏；仓库资料没有声明会如何处理或持久化这类数据。
• 在隔离的本地或测试目录中运行脚本，限制输入文件和输出目录权限，避免把生成的 HTML、SVG 或 PNG 当作可信执行内容。
• 对外分发图表前检查文字、节点名称、域名、IP、队列名和 Trace 标识，确认没有泄露内部信息。
• GIF、HTML 和 SVG 可能包含链接、文字或结构化内容；资料没有提供内容安全策略，因此发布前应进行人工审核。

上述边界是授权环境下的安全建议，不构成仓库对数据保留、隔离强度或合规认证的承诺。官方仓库未提供隐私政策、数据处理协议、审计报告或安全响应 SLA，相关要求应由使用组织自行评估。

许可证与商用条款

根据仓库中的 LICENSE 文件，项目采用 MIT License，版权标注为 2025 年 fireworks-tech-graph contributors。MIT 许可证允许获得软件的个人使用、复制、修改、合并、发布、分发、再许可和销售，但分发时需要遵守许可证文本中的条件。

• 复制或分发软件的全部或实质部分时，应保留版权声明。
• 应保留 MIT 许可证许可声明。
• 许可证明确按“原样”提供软件，不提供明示或默示担保。
• 许可证包含免责声明和责任限制条款。

因此，从许可证文本看，商业使用路径是被允许的，但具体产品还可能受到第三方模型、字体、浏览器、示例资产或其他依赖的独立许可约束。资料没有提供这些组件的完整许可证清单，集成和再分发时应以仓库 LICENSE、依赖包许可证及相关资产说明为准。

局限性与已知限制

项目强调几何安全和输出质量，但这不等于所有输入都能自动得到正确的架构语义。自然语言中的歧义、缺失关系和过密标签仍会影响结果；README 提供的是质量门禁和恢复提示，不是业务语义正确性的证明。

• 完整的 14 种 UML 图类型名称、触发方式和参数没有在给定资料中逐项列出。
• 12 种风格的可配置字段、默认风格选择规则和自定义主题接口没有完整公开在资料中。
• Python 依赖、PNG/GIF 可选依赖和 Chromium 的安装方式没有提供固定版本清单。
• 没有提供性能基准、并发能力、最大节点数、最大文字长度或 SLA，因此不能据此规划生产规模。
• 已给出的 5.75 秒、20fps、115 帧和 960 像素宽属于展示样例回归数据，不是所有输入的输出保证。
• 当前工作树存在未发布升级的说明，公开 1.2.0 样例与本地检出的实际状态可能存在差异。

遇到资料未覆盖的参数、错误码或兼容性问题，官方仓库未提供该信息，建议以最新 README、CHANGELOG、版本历史和源码中的测试为准。

适合谁

当团队需要把自然语言需求快速转成可审阅的技术图，并且能够接受生成后进行人工校验时，这个项目具有较明确的使用价值。以下信号可以帮助判断是否适合引入：

• 团队已经使用 Codex 或 Claude Code，希望把架构图生成能力嵌入现有 Agent 工作流。
• 项目文档需要同时维护 SVG、PNG、GIF 或离线 HTML，而不是只保存单一位图。
• 系统包含 AI/Agent、记忆、工具调用、事件流、云部署或可靠性排查等 README 已展示的场景。
• 评审流程重视节点边界、箭头路由、文字完整性和固定视觉风格。
• 团队能够在本地安装并验证 Python、Node.js 及所需的可选导出能力。

不适合谁

如果目标是严格的所见即所得人工绘图、复杂的多人协作编辑或经过认证的生产监控系统，当前资料不足以证明项目能够覆盖这些需求。下面的情况应谨慎采用，或先保留现有工具链。

• 要求在没有人工审核的情况下，把图直接作为合规架构、灾备设计或安全审计结论。
• 需要明确的并发上限、节点规模、延迟、可用性 SLA 或厂商级技术支持承诺。
• 团队不能接受自然语言歧义、文字截断处理或风格参数尚未完全文档化。
• 需要实时多人编辑、权限审批、在线资产管理或服务端 API，而仓库资料只确认了 Agent Skill、CLI 和离线 HTML 等能力。
• 运行环境不能满足仓库声明的 Node.js >=22.12.0，或不能自行确认 Python 与可选媒体依赖。

常见问题与排查（FAQ / Troubleshooting）

排查原则是先确认调用的是哪一份 Skill，再确认目标格式的依赖条件，最后检查语义输入与输出报告。项目提供的 version 和 doctor 命令是最直接的本地诊断入口。

为什么执行命令后找不到 PNG 或 GIF 依赖

README 明确说明 doctor 会区分 SVG、HTML、PNG、GIF 的运行条件，PNG 和 GIF 可能需要额外依赖。给定资料没有提供这些依赖的名称和安装命令，因此应先查看 doctor 输出，并按照当前仓库文档补齐环境。

为什么文字没有被自动截断

如果输入中设置了 "text_policy": "strict"，可见文字截断会在写文件前被拒绝，报告会保留完整源标签并说明恢复方式。应根据报告缩短标签、利用中文第二行或调整布局，而不是把截断后的图片直接发布。

为什么浏览器导出的 PNG 与普通导出结果不同

README 区分了普通 PNG 导出和浏览器 PNG 导出器，并指出后者用于 Chromium fidelity（Chromium 还原效果）。两条路径的具体命令和版本要求未在资料中提供，不能据此断言哪条路径在所有主题下都更准确。

可以直接把任意 SVG 转成项目 GIF 吗

不能从资料得出这个结论。README 明确写的是聚焦动效路径只接收生成器产出的语义 SVG，因此外部手写或其他工具生成的普通 SVG 可能不满足该链路要求。

如何确认当前运行的不是错误目录中的脚本

执行 python3 scripts/fireworks.py version，查看它报告的包版本、实际 Skill 根目录和 Git 状态。若输出与当前检出的仓库不一致，应检查工作目录、脚本路径和命令入口是否指向同一份代码。

仓库是否提供 Docker、端口或 API 服务

给定资料没有提供 Dockerfile、Compose 文件、监听端口或服务端 API 说明。官方仓库未提供该信息，建议以最新 README 和实际目录内容为准，不要根据 CLI 和离线 HTML 能力推断存在在线服务。

项目地址与资源

以下链接均来自项目元数据、README 或 README 中引用的官方文档入口。版本历史和更新日志适合用于核对当前工作树与已发布版本之间的差异。

• fireworks-tech-graph GitHub 仓库
• fireworks-tech-graph 官网与文档
• fireworks-tech-graph 版本发布页
• fireworks-tech-graph 更新日志
• Codex Skill 构建文档
• Claude Code Skill 文档