AI 时代的开源架构作图利器：对比 oh-my-mermaid、architecture-diagram-generator 与 fireworks-tech-graph

引言

在软件开发与系统设计中，一图胜千言。然而，维护技术文档和架构图历来是开发者的痛点——不仅费时费力，而且代码一旦迭代，手绘的图表就会迅速落后过时。

随着大语言模型（LLM）与 AI 编程助手（如 Claude Code、Cursor、Windsurf）的爆发，**“文字/代码与图表的自动转换”**迎来了技术拐点。AI 能够以极高的效率阅读上下文，并生成结构化的图表描述，或者直接将现有代码逆向为可视化拓扑。

在这一背景下，开源社区涌现出了三款极具代表性、且与 AI 深度集成的制图利器：

1. oh-my-mermaid (OMM)：专注于代码库的递归逆向与文档自动生成。
2. architecture-diagram-generator (ADG)：专注于高颜值、暗黑极简风格的系统级与云基础设施拓扑。
3. fireworks-tech-graph (FTG)：专注于 AI Agent 智能 Prompt 驱动的通用技术绘图与工作流可视化。

本文将通过具体的生成实例，深度拆解这三款工具的核心机制、应用场景、技术差异，以及如何将它们协同应用到日常开发中。

三大作图工具的核心定位、特性与生成实例

为了更好地理解它们，我们来看每款工具的核心设计哲学以及实际运行输出的图表实例：

1. oh-my-mermaid：代码库的“递归式逆向透视镜”

GitHub 地址： oh-my-mermaid/oh-my-mermaid

oh-my-mermaid 的核心目的是**“从现有 codebase 逆向生成可交互的 Mermaid 架构图和关联文档”。它在大型复杂项目中采用递归（Recursive）节点解析**，避免把所有目录堆在一张图里，而是允许层层向下钻取（Drill-down）。

💡 生成实例：

当你运行 /omm-scan 扫描多模块项目时，它会自动在你的文档库中生成类似下面的递归导向图（Interactive Map）。在支持 Markdown 交互的阅读器中，用户可以直接点击模块跳转到更深层级的子视图中：

graph TD
    subgraph Project_Root ["Project: AgentUpdate (Root)"]
        direction LR
        Admin["/admin (Astro API & Dashboard)"]
        Website["/website (Astro Frontend)"]
        Database["/database (Prisma & Schema)"]
        Crawler["/crawler (LLM News Processor)"]
        
        Admin -->|Uses Client| Database
        Website -->|Uses Client| Database
        Crawler -->|Writes DB| Database
    end
    
    click Admin href "/docs/omm/admin.md" "查看 Admin 内部架构"
    click Crawler href "/docs/omm/crawler.md" "查看 Crawler 内部架构"

2. architecture-diagram-generator：高颜值的“暗黑极简蓝图”

GitHub 地址： Cocoon-AI/architecture-diagram-generator

相较于 OMM 关注于代码逻辑，architecture-diagram-generator 则专注于**“系统物理/逻辑拓扑的高保真渲染”**。它拥有极强的视觉审美主张，默认采用现代科技感的暗黑主题，并支持免依赖的纯 HTML/SVG 矢量图导出。

💡 生成实例：

该工具的输入是一个极简的 YAML 配置文件。例如，定义一个典型的云端 Web 服务的组件与调用流：

# ADG Input DSL Example
title: "AgentUpdate Cloud Production Topology"
theme: "dark"

components:
  - id: "client"
    label: "Web Clients (Browser)"
    type: "client"
    color: "cyan"
  - id: "alb"
    label: "AWS Load Balancer"
    type: "network"
    color: "amber"
  - id: "api"
    label: "Astro Server Container"
    type: "server"
    color: "cyan"
  - id: "postgres"
    label: "PostgreSQL Database"
    type: "database"
    color: "violet"

connections:
  - from: "client"
    to: "alb"
    label: "HTTPS / Route 53"
  - from: "alb"
    to: "api"
    label: "Target Group"
  - from: "api"
    to: "postgres"
    label: "Prisma Connection"

ADG 引擎在读取该配置后，会应用其内置的视觉系统（青/紫/黄等语义色彩与 JetBrains Mono 字体），渲染输出一张暗黑主题的系统架构图。其渲染出的逻辑与视觉效果如下：

graph TD
    classDef client fill:#06b6d4,stroke:#0891b2,color:#fff;
    classDef network fill:#f59e0b,stroke:#d97706,color:#fff;
    classDef database fill:#8b5cf6,stroke:#7c3aed,color:#fff;
    
    Client["💻 Web Clients (Browser)"]:::client
    ALB["🔀 AWS Load Balancer"]:::network
    API["⚙️ Astro Server Container"]:::client
    DB["🗄️ PostgreSQL Database"]:::database
    
    Client -->|HTTPS / Route 53| ALB
    ALB -->|Target Group| API
    API -->|Prisma Connection| DB

3. fireworks-tech-graph：AI Agent 的“全能绘图师”

GitHub 地址： yizhiyanhua-ai/fireworks-tech-graph

fireworks-tech-graph 是一个基于 Python 开发的 Prompt-to-SVG/PNG 绘图引擎。它的核心定位是作为 AI Agent（例如 Claude Code、AutoGPT 等）的“制图外挂”，帮助 AI 将抽象的算法、协作逻辑和工作流瞬间实例化为时序图或流程图。

💡 生成实例：

当你在终端向 AI Agent 发出一条绘图指令：

开发者/Agent： *"画一张我们定时新闻抓取与重写（Crawler & LLM Rewriter）工作流的时序图。展示 Cron 触发抓取、获取 HTML、发送给 Gemini 3.5 Flash 重写。如果遇到 429 报错，降级到 Gemini 3.1 Flash-Lite，最后把成功的内容写入 PostgreSQL。" *

AI Agent 就会自动组织参数并调用 FTG 引擎，自动生成并保存一张无损的矢量 SVG 图（并调用 cairosvg 输出高 DPI 的 PNG 图片）。生成的时序图表现如下：

sequenceDiagram
    autonumber
    actor System as Cron Trigger
    participant Crawler as News Crawler
    participant LLM as Gemini Flash
    participant Fallback as Gemini Flash-Lite
    participant DB as PostgreSQL
    
    System->>Crawler: Trigger Crawl Job
    Crawler->>Crawler: Fetch Raw HTML
    Crawler->>LLM: Send content for rewrite (responseMimeType: JSON)
    alt Success
        LLM-->>Crawler: Return Clean JSON Summary
    else 429 Rate Limit
        Crawler->>Fallback: Retry request to Backup
        Fallback-->>Crawler: Return Clean JSON Summary
    end
    Crawler->>DB: Write Upserted Article row
    DB-->>System: Job Finished

三大工具的核心差异对比

这三款工具在技术路线和应用侧重点上有着明显的区别：

区别与联系：如何构建你的“超级制图流”？

这三者虽然都是“作图”工具，但它们绝非彼此对立的竞争关系，而是处于一条完整的技术图表生成价值链中。

让我们通过一个具体的软件开发流程，来看看如何将它们串联使用：

graph TD
    A[系统设计阶段] -->|使用 FTG / ADG| B[绘制系统物理/逻辑拓扑]
    B --> C[代码实现阶段: 产出 codebase]
    C -->|使用 OMM 逆向分析| D[自动生成代码级文档与函数调用图]
    D -->|使用 FTG| E[在 README / 博客中绘制 Agent 核心算法流与 UML]
    E --> F[全自动、免手绘的技术文档闭环]

1. 系统设计阶段（Topology Design）： 在系统动工前，你和 AI 助手可以通过 architecture-diagram-generator (ADG) 确定云服务分区、微服务分布以及 VPC 网络拓扑，产出规范的暗黑风系统物理蓝图。
2. 算法与流程说明（Process Detail）： 对于系统内一些复杂的逻辑块（例如多 Agent 协作决策机制、三方支付回调时序），你可以在终端向 Claude Code 发出指令，调用 fireworks-tech-graph (FTG) 以自然语言自动输出几幅精致的工作流 SVG 插图，直接嵌入设计文档。
3. 代码逆向与演进审计（Reverse Engineering & Maintenance）： 当项目真正实现并沉淀出庞大的 codebase 后，使用 oh-my-mermaid (OMM) 进行递归分析，自动为你的复杂系统梳理出数据流、调用流，并在本地生成可层层向下钻取（Drill-down）的交互式文档，告别落后于代码的“口传心授”式旧架构图。

【AgentUpdate 深度解析】

从 AI 编程工程化（Agentic Engineering）的发展来看，这三款制图神器的流行揭示了一个核心范式——“图表即代码”（Diagrams as Code）与“数据源透明化”的不可逆趋势。

传统的作图（如使用 Visio、Draw.io、Figma）是由人类在画布上拖拽、摆放组件并进行硬编码排版。这种方式对 AI Agent 而言非常不友好，因为 AI 擅长逻辑思考与文本输出，但不擅长通过微操鼠标去对齐像素。

• OMM 解决了 “输入透明”：将不可读的二进制目录关系转化为 AI 可理解、可编辑的 Mermaid 拓扑文本。
• ADG 解决了 “标准输出”：通过强约束的样式和颜色，让 AI 只需生成纯数据维度的拓扑关系，剩下的排版、美化、对齐全部交给渲染器，保证了生成的图表永远具有生产环境级别的专业美感。
• FTG 解决了 “命令边界扩展”：让 CLI 工具（如 Claude Code）在纯终端环境下，也能随时产出直观的图片作为输出反馈。

未来，优秀的技术项目必然走向 “文档完全自治”。随着这三类工具的融合，未来的编译器甚至可能在检测到代码变动时，自动运行逆向分析、调用主题生成器，在 CI/CD 流程中将最新的架构图默默更新到你的 README 中。这正是 AI 赋予开发运维的全新想象力。