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

三种导出方式：

三、真正创新的三个设计

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

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

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

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

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

关键设计：凡使用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的随机性而变味。

四、八种风格一览

前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 = 快速内联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中内联<style>声明字体族，不使用外部@import（cairosvg/rsvg-convert无法获取外部URL）。支持CJK字体回退：PingFang SC、Microsoft YaHei、SimHei。

注意：cairosvg对CJK和emoji支持有限（依赖系统字体配置），可能渲染为□。解决方案：优先用SVG格式（浏览器原生支持CJK），或用puppeteer路径。

八、局限与适用边界

1. 不可交互：输出是静态SVG/PNG，不是可点击的交互图
2. 无GUI编辑：生成后修改需手动编辑SVG代码，不如Excalidraw友好
3. 风格固定：8套风格覆盖大部分场景，但自定义风格需要改Python代码
4. LLM依赖：JSON生成质量取决于LLM对SKILL.md的理解，复杂系统可能需要多轮迭代
5. 箭头路由仍有优化空间：密集架构图中箭头交叉和标签重叠是常见问题（SKILL.md已有专门的"优化箭头"指令和JSON覆盖字段）

九、对Agent生态的启示

fireworks-tech-graph 的价值不止于"画图"。它示范了一种AI工具的构建范式：

不要让LLM直接做它不擅长的事（生成精确SVG），而是让LLM生成结构化描述，再由确定性代码执行。

这与NLAH论文的思路异曲同工：LLM承载策略（画什么、什么风格），确定性代码承载机制（怎么渲染、怎么布局）。两层分离，各尽所长。

对于Agent基础设施作者来说，这个skill证明了：一个垂直领域的"AI-native工具"可以只用SKILL.md + Python脚本 + 模板文件就能达到生产级质量，不需要React前端、不需要Electron壳、不需要云服务。

十、快速上手

# 安装（Claude Code环境）
npx skills add yizhiyanhua-ai/fireworks-tech-graph

# 依赖
pip install cairosvg  # 推荐
# 或
brew install librsvg  # macOS
sudo apt install librsvg2-bin  # Ubuntu

# 使用（在Claude Code中）
# "画一个RAG pipeline架构图，暗色风格"
# "生成一个多Agent协作流程图，Notion风格"

参考

• GitHub: https://github.com/yizhiyanhua-ai/fireworks-tech-graph
• NPM: https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph
• 作者: https://bradzhang.dev/en
• 商业案例: https://bradzhang.dev/en/case-studies/fireworks-tech-graph

#工具 #AIAgent #技术可视化 #ClaudeCode #Skill #小凯