fireworks-tech-graph——当技术架构图从"手绘"变成"结构化语言"

> 项目: fireworks-tech-graph | Claude Code Skill > 作者: 一支烟花AI（Brad Zhang） > 仓库: https://github.com/yizhiyanhua-ai/fireworks-tech-graph > Stars: ~6.8k | License: MIT > 安装: npx skills add yizhiyanhua-ai/fireworks-tech-graph

---

一、问题：为什么AI画不好技术架构图？

LLM能写代码、能写文档、能解释系统，但让它"画一张RAG架构图"，结果通常是：

Mermaid语法错误，渲染失败
draw.io导出后字体丢失
Excalidraw手绘风不适合正式文档
每次重画风格都不一致

根本矛盾：自然语言的模糊性 vs 视觉表示的精确性。

fireworks-tech-graph 的解法不是让LLM直接画SVG（那太不稳定了），而是让LLM生成结构化JSON描述，再由一个专门的Python渲染器转换成生产级SVG+PNG。

---

二、核心架构：三层分离

自然语言描述 → JSON中间表示 → Python渲染器 → SVG+PNG
     ↑              ↑              ↑
   用户输入      LLM生成        确定性输出

第一层：自然语言 → JSON

用户说："画一个Mem0记忆架构图，扁平风格"

LLM（由SKILL.md指导）生成：

{
  "template_type": "memory",
  "style": 1,
  "title": "Mem0 Memory Architecture",
  "containers": [...],
  "nodes": [...],
  "arrows": [...],
  "legend": [...]
}

第二层：JSON → SVG（Python渲染器）

generate-from-template.py（1500+行）执行： 1. 分类：识别图类型（architecture/memory/sequence/class...） 2. 加载风格：从8套预定义风格中选择配色、字体、阴影 3. 布局计算：节点位置、箭头路由、泳道分组 4. 形状映射：语义概念→固定形状 5. SVG生成：纯内联SVG，无外联资源

第三层：SVG → PNG

三种导出方式：

工具	质量	场景
cairosvg	✅ 好	默认推荐，pip一键安装
rsvg-convert	⚠️ 一般	无Python环境时的fallback
puppeteer	✅✅ 最佳	浏览器级渲染，但重(~150MB Chromium)

---

三、真正创新的三个设计

1. 语义形状词汇（Semantic Shape Vocabulary）

不是"随便画个框"，每个形状都有固定含义：

概念	形状	说明
LLM / Model	双边框圆角矩形	带brain/spark渐变
Agent / Orchestrator	六边形	信号"主动控制器"
Vector Store	带网格线圆柱	持久化存储
Graph DB	三圆重叠	图数据库
Memory (短期)	虚线边框圆角矩形	易失性
Tool / Function	齿轮形矩形	可调用工具
API / Gateway	单边框六边形	网关
Queue / Stream	水平管道	消息队列

这种约定让团队成员"看图即懂"，不需要图例解释。

2. 语义箭头系统（Semantic Arrow System）

颜色和线型编码含义，不是装饰：

流类型	颜色	线型	含义
主数据流	蓝 `#2563eb`	2px实线	请求/响应主路径
控制/触发	橙 `#ea580c`	1.5px实线	系统触发
内存读取	绿 `#059669`	1.5px实线	从存储检索
内存写入	绿 `#059669`	1.5px虚线	写入/存储
异步/事件	灰 `#6b7280`	1.5px虚线	非阻塞事件
反馈/循环	紫 `#7c3aed`	1.5px曲线	迭代推理

关键设计：凡使用2+种箭头类型，必须带图例（legend）。这是论文级别的规范意识。

3. 可执行风格系统（Executable Style System）

风格不是"写几行文档让AI看着办"，而是编码进渲染器的确定性配置：

STYLE_PROFILES = {
    1: {  # Flat Icon
        "font_family": "'Helvetica Neue', Helvetica, Arial, 'PingFang SC', ...",
        "background": "#ffffff",
        "shadow": True,
        "node_fill": "#ffffff",
        "node_stroke": "#d1d5db",
        "arrow_colors": { "control": "#7c3aed", "write": "#10b981", ... },
        ...
    },
    2: {  # Dark Terminal
        "background": "#0f0f1a",
        "node_fill": "#1e1e2e",
        "title_fill": "#e2e8f0",
        ...
    },
    # ... 8套风格
}

这保证了"说扁平风就一定是扁平风"，不会因为LLM的随机性而变味。

---

四、八种风格一览

#	名称	背景	适用场景
1	Flat Icon (默认)	纯白	博客、文档、PPT
2	Dark Terminal	`#0f0f1a` 深黑	GitHub、开发者文章
3	Blueprint	`#0a1628` 蓝图蓝	架构文档
4	Notion Clean	白+极简	Notion页面
5	Glassmorphism	深色渐变+毛玻璃	产品站、 keynote
6	Claude Official	暖米 `#f8f6f3`	Anthropic风格
7	OpenAI Official	纯白 `#ffffff`	OpenAI风格
8	Dark Luxury (AI创作)	`#0a0a0a` 纯黑	高端编辑、架构文档

前7套是模板驱动，第8套"Dark Luxury"是AI-authored——由LLM从零设计的SVG风格。这本身就是一个有趣的元叙事：skill作者用LLM生成了一个LLM生成图用的风格。

---

五、14种图类型与AI/Agent内置模板

UML全覆盖

Class、Component、Deployment、Package、Composite Structure、Object、Use Case、Activity、State Machine、Sequence、Communication、Timing、Interaction Overview、ER Diagram——全部14种UML图。

AI/Agent领域专用模板

不是泛泛的"流程图"，而是懂业务的模板：

RAG Pipeline: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response
Agentic RAG: 在RAG基础上加Agent循环+Tool use
Agentic Search: Query → Planner → [Search/Calc/Code] → Synthesizer → Response
Mem0 / Memory Layer: Input → Memory Manager → [Write: VectorDB+GraphDB] / [Read: Retrieve+Rank] → Context
Multi-Agent: Orchestrator → [SubAgent A/B/C] → Aggregator → Output
Tool Call Flow: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)

这些模板编码在SKILL.md中，LLM生成JSON时直接调用。用户不需要从零描述，只需要说"RAG pipeline"，系统就知道该画什么。

---

六、与竞品的对比

Mermaid	draw.io	Excalidraw	fireworks-tech-graph
自然语言输入	✗	✗	✗	✅
AI/Agent领域模板	✗	✗	✗	✅
多视觉风格	✗	手动	有限	✅ 8套内置
高清PNG导出	✗	手动	手动	✅ 自动1920px
语义箭头颜色	✗	手动	手动	✅ 自动编码
无需在线工具	✅	✗	✗	✅
SVG纯内联	⚠️	✗	✗	✅ 无外联字体
可编辑性	⚠️	✅	✅	⚠️ SVG可编辑但无GUI

定位差异：

Mermaid = 快速内联markdown图表
draw.io = 手动精修
Excalidraw = AI生成后人工改
fireworks-tech-graph = 描述系统→立即出 polished 图，不写DSL不点GUI

---

七、技术细节：为什么它能稳定生成

1. Python列表法生成SVG（防截断）

lines = []
lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
lines.append('  <defs>')
# ... 每行独立
lines.append('</svg>')

LLM直接写SVG容易字符截断、属性缺失、标签不平衡。通过Python脚本逐行构建，每行独立可验证。

2. 箭头路由算法

优先正交路径（L形）减少交叉
锚定在组件边缘而非几何中心
并行箭头用不同y偏移分离
不可避免的交叉用跳线弧（jump-over arcs，5px半径）
强制规则：箭头绝不穿过组件内部

3. 三层绘制顺序（Z-order）

底层 → 顶层：
① 画布背景 → ② 虚线容器/区域背景 → ③ 箭头和连接线 
→ ④ 节点形状 → ⑤ 文本标签 → ⑥ 图例和覆盖层

箭头在文本之前绘制，确保文本可读。

4. 字体安全

SVG中内联