fireworks-tech-graph
来源：GitHub · ⭐ 1788 stars
项目简介
在软件开发、系统架构设计和AI智能体（Agent）领域，清晰、专业的架构图和技术图表是沟通思想、记录设计和进行技术评审不可或缺的工具。然而，绘制一张既美观又准确的技术图往往耗时费力，需要开发者同时具备技术理解力和一定的图形设计能力。传统的绘图工具（如draw.io、Visio）依赖手动操作，而简单的代码生成工具（如Graphviz）又常常在表现力和美观度上有所欠缺。
fireworks-tech-graph 项目正是为了解决这一痛点而生。它是一个基于 Anthropic Claude 模型的代码技能（Code skill），旨在通过自然语言描述，一键生成可直接用于生产环境的高质量 SVG 和 PNG 格式技术图表。其核心价值在于将开发者从繁琐的绘图工作中解放出来，通过AI深度理解技术领域知识（特别是AI/Agent领域），将文本描述自动转化为符合工程标准的可视化图表，极大地提升了技术文档和设计稿的输出效率与专业性。
核心特性
- 多图表类型支持：项目支持生成8种常见的软件工程图表，包括但不限于：系统架构图、序列图、流程图、类图、状态图、实体关系图（ERD）、部署图以及C4模型图。这覆盖了从高层级上下文到低层级代码设计的全链条可视化需求。
- 丰富的视觉风格：提供5种开箱即用的视觉样式，例如经典的“草图”风格、专业的“IBM Carbon”风格、简洁的“Google Material”风格等。用户可以根据文档风格或汇报场景，轻松切换图表主题，无需手动调整颜色、字体和线条样式。
- 深度领域知识集成：该项目并非简单的文本转图形工具。其背后的Claude技能经过专门训练，对AI/Agent领域的技术栈（如LangChain、LlamaIndex、向量数据库、各种模型提供商）、组件和交互模式有深刻理解。当描述涉及这些概念时，它能生成更准确、更地道的符号表示。
- 生产级输出质量：直接生成矢量格式（SVG）和位图格式（PNG）文件。SVG格式可无限缩放，便于嵌入网页、文档和演示文稿；PNG格式则方便即时分享和预览。生成的图表元素布局合理，样式统一，达到了可直接放入技术提案、设计文档或产品手册的标准。
技术实现
fireworks-tech-graph 的技术实现巧妙地结合了大型语言模型（LLM）的语义理解能力与专业的图表渲染引擎，构成了一个高效的“描述 -> 中间代码 -> 渲染”管道。
- Claude Code Skill 作为核心引擎：项目的核心是一个为 Claude 模型（特别是 Claude 3 系列）定制的 Code Skill。Code Skill 允许 Claude 在对话中调用特定的代码能力。当用户提出绘图需求时，Claude 首先利用其强大的自然语言理解和领域知识，将模糊的需求（如“画一个展示用户请求通过LangChain Agent调用OpenAI和向量数据库的序列图”）解析为结构化的图表描述。
- 中间代码生成（Mermaid.js）：项目选择 Mermaid.js 作为图表定义的中间语言。Claude Skill 会将结构化描述转换为精确的 Mermaid 语法代码。Mermaid 是一种基于文本的图表生成工具，语法简洁，且支持项目所需的大部分图表类型。使用 Mermaid 作为中间层是一个关键设计，它使得项目不依赖于某个固定的图形库，且生成的文本代码可读、可版本化管理。
- 渲染与样式化：生成 Mermaid 代码后，项目调用 Python 的
mermaid库或通过无头浏览器（如 Playwright）来执行渲染。5种视觉风格是通过预定义的 Mermaid 主题（Theme） 文件实现的。这些主题文件定义了图表中所有元��（节点、连线、文本）的颜色、边框、间距等CSS属性。渲染引擎将 Mermaid 代码与选定的主题结合，最终输出样式化的 SVG/PNG。 - 技术栈：项目主体用 Python 编写，负责流程编排、API调用和文件处理。核心依赖包括：与 Claude API 交互的 SDK、
mermaid渲染库、以及可能的playwright用于高质量PNG渲染。项目结构清晰，将技能定义、主题管理、渲染逻辑分离，便于维护和扩展新的图表类型或风格。
快速上手
使用 fireworks-tech-graph 主要有两种方式：通过其集成的在线演示界面，或本地运行其Python脚本。
以下是一个通过本地脚本快速生成架构图的示例：
- 克隆项目并安装依赖：
```bash
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git
cd fireworks-tech-graph
pip install -r requirements.txt
```
你需要配置 Anthropic Claude 的 API 密钥。
- 使用提供的脚本生成图表：
项目提供了示例脚本。你可以修改或创建一个简单的 Python 脚本：
```python
# generate_diagram.py
from fireworks_tech_graph.core import DiagramGenerator
generator = DiagramGenerator(api_key="your-claude-api-key")
description = """
生成一个微服务架构图，包含以下组件：
- 客户端（Web和Mobile）
- API Gateway (Kong)
- 用户服务 (Node.js)，连接 PostgreSQL 数据库
- 订单服务 (Python/Flask)，连接 Redis 缓存
- 产品服务 (Java/Spring)
所有服务都通过 API Gateway 与客户端通信，并且将日志发送到一个中央 ELK 栈。
使用“Carbon”风格。
"""
# 生成图表
svg_content = generator.generate_diagram(
description=description,
diagram_type="架构图", # 或 “graph”
style="carbon"
)
# 保存为SVG文件
with open('microservice_architecture.svg', 'w') as f:
f.write(svg_content)
print("图表已生成并保存为 'microservice_architecture.svg'")
```
运行此脚本，即可在本地得到一个名为 microservice_architecture.svg 的专业架构图。
应用场景
- 敏捷设计与评审：在技术方案初步设计阶段，架构师或开发者可以快速将脑海中的想法用文字描述出来，立即生成可视化的架构图或序列图。这张图可以马上用于团队内部讨论、评审，快速迭代设计方案，避免在绘图工具上消耗过多时间。
- 自动化文档生成：在 CI/CD 流水线或文档生成工具链中集成
fireworks-tech-graph。例如，可以从代码中的特定注释、OpenAPI 规范或基础设施即代码（IaC）文件中提取信息，自动生成并更新系统部署图、组件关系图，确保文档与代码始终保持同步。 - AI/Agent 项目演示与汇报：对于当前火热的 AI 应用和智能体项目，其技术栈和交互逻辑复杂。在制作项目介绍、技术分享PPT或项目文档时，可以直接用自然语言描述智能体的工作流（如“用户问题 -> 查询改写 -> 向量检索 -> 提示构建 -> 大模型调用 -> 结果解析”），生成准确且美观的流程图或序列图，让听众和读者一目了然。
总结
fireworks-tech-graph 是一个极具实用价值的工具，它精准地抓住了开发者在技术可视化方面的效率痛点。通过将顶尖LLM的语义理解能力与成熟的图表渲染技术相结合，它实现了从自然语言到生产级图表的“端到端”自动化。该项目特别适合全栈工程师、系统架构师、技术布道师以及所有AI/Agent领域的研究和开发人员使用。它不仅能提升个人工作效率，更有潜力被集成到团队的知识管理和文档工程实践中，成为提升整体技术沟通质量的基础设施。随着其支持的图表类型和领域知识的不断丰富，其应用前景将更加广��。