# fireworks-tech-graph

> 来源：[GitHub](https://github.com/yizhiyanhua-ai/fireworks-tech-graph) · ⭐ 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）的语义理解能力与专业的图表渲染引擎，构成了一个高效的“描述 -> 中间代码 -> 渲染”管道。

1.  **Claude Code Skill 作为核心引擎**：项目的核心是一个为 Claude 模型（特别是 Claude 3 系列）定制的 Code Skill。Code Skill 允许 Claude 在对话中调用特定的代码能力。当用户提出绘图需求时，Claude 首先利用其强大的自然语言理解和领域知识，将模糊的需求（如“画一个展示用户请求通过LangChain Agent调用OpenAI和向量数据库的序列图”）解析为结构化的图表描述。
2.  **中间代码生成（Mermaid.js）**：项目选择 **Mermaid.js** 作为图表定义的中间语言。Claude Skill 会将结构化描述转换为精确的 Mermaid 语法代码。Mermaid 是一种基于文本的图表生成工具，语法简洁，且支持项目所需的大部分图表类型。使用 Mermaid 作为中间层是一个关键设计，它使得项目不依赖于某个固定的图形库，且生成的文本代码可读、可版本化管理。
3.  **渲染与样式化**：生成 Mermaid 代码后，项目调用 Python 的 `mermaid` 库或通过无头浏览器（如 Playwright）来执行渲染。5种视觉风格是通过预定义的 Mermaid **主题（Theme）** 文件实现的。这些主题文件定义了图表中所有元��（节点、连线、文本）的颜色、边框、间距等CSS属性。渲染引擎将 Mermaid 代码与选定的主题结合，最终输出样式化的 SVG/PNG。
4.  **技术栈**：项目主体用 **Python** 编写，负责流程编排、API调用和文件处理。核心依赖包括：与 Claude API 交互的 SDK、`mermaid` 渲染库、以及可能的 `playwright` 用于高质量PNG渲染。项目结构清晰，将技能定义、主题管理、渲染逻辑分离，便于维护和扩展新的图表类型或风格。

## 快速上手

使用 `fireworks-tech-graph` 主要有两种方式：通过其集成的在线演示界面，或本地运行其Python脚本。

以下是一个通过本地脚本快速生成架构图的示例：

1.  **克隆项目并安装依赖**：
    ```bash
    git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git
    cd fireworks-tech-graph
    pip install -r requirements.txt
    ```
    你需要配置 Anthropic Claude 的 API 密钥。

2.  **使用提供的脚本生成图表**：
    项目提供了示例脚本。你可以修改或创建一个简单的 Python 脚本：
    ```python
    # generate_diagram.py
    from fireworks_tech_graph.core import DiagramGenerator

    generator = DiagramGenerator(api_key="your-claude-api-key")

    description = """
    生成一个微服务架构图，包含以下组件：
    1. 客户端（Web和Mobile）
    2. API Gateway (Kong)
    3. 用户服务 (Node.js)，连接 PostgreSQL 数据库
    4. 订单服务 (Python/Flask)，连接 Redis 缓存
    5. 产品服务 (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` 的专业架构图。

## 应用场景

1.  **敏捷设计与评审**：在技术方案初步设计阶段，架构师或开发者可以快速将脑海中的想法用文字描述出来，立即生成可视化的架构图或序列图。这张图可以马上用于团队内部讨论、评审，快速迭代设计方案，避免在绘图工具上消耗过多时间。
2.  **自动化文档生成**：在 CI/CD 流水线或文档生成工具链中集成 `fireworks-tech-graph`。例如，可以从代码中的特定注释、OpenAPI 规范或基础设施即代码（IaC）文件中提取信息，自动生成并更新系统部署图、组件关系图，确保文档与代码始终保持同步。
3.  **AI/Agent 项目演示与汇报**：对于当前火热的 AI 应用和智能体项目，其技术栈和交互逻辑复杂。在制作项目介绍、技术分享PPT或项目文档时，可以直接用自然语言描述智能体的工作流（如“用户问题 -> 查询改写 -> 向量检索 -> 提示构建 -> 大模型调用 -> 结果解析”），生成准确且美观的流程图或序列图，让听众和读者一目了然。

## 总结

`fireworks-tech-graph` 是一个极具实用价值的工具，它精准地抓住了开发者在技术可视化方面的效率痛点。通过将顶尖LLM的语义理解能力与成熟的图表渲染技术相结合，它实现了从自然语言到生产级图表的“端到端”自动化。该项目特别适合**全栈工程师、系统架构师、技术布道师以及所有AI/Agent领域的研究和开发人员**使用。它不仅能提升个人工作效率，更有潜力被集成到团队的知识管理和文档工程实践中，成为提升整体技术沟通质量的基础设施。随着其支持的图表类型和领域知识的不断丰富，其应用前景将更加广��。