---
name: fireworks_tech_graph
description: 当需要创建技术图表时使用此规则——Fireworks技术图表生成规则，将自然语言描述转换为高质量SVG图表并导出PNG。包括：架构图、数据流图、流程图、Agent架构图、记忆架构图、序列图、对比矩阵、时间线、思维导图、UML类图、用例图、状态机图、ER图、网络拓扑图等14种图表类型；7种视觉样式（扁平图标、深色终端、蓝图、Notion简洁、玻璃态、Claude官方、OpenAI官方）；SVG生成与验证；布局规则与箭头语义。每当用户提及"画图"、"帮我画"、"生成图"、"做个图"、"架构图"、"流程图"、"可视化一下"、"出图"、"generate diagram"、"draw diagram"、"visualize"或任何需要图示化的系统/流程描述时触发。
license: MIT
---

# Fireworks Tech Graph

生成高质量SVG技术图表并通过`rsvg-convert`导出PNG。

## 辅助脚本（推荐）

本规则包含辅助脚本和样式参考文件，位于规则文件同级目录：

- `fireworks-tech-graph/scripts/` - 辅助脚本
- `fireworks-tech-graph/references/` - 样式参考文件

### 1. generate-diagram.sh - 验证SVG + 导出PNG

```bash
# 假设当前目录在 fireworks-tech-graph 同级
./fireworks-tech-graph/scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg
```

### 2. generate-from-template.py - 从模板创建SVG

```bash
python3 ./fireworks-tech-graph/scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'
```

### 3. validate-svg.sh - 验证SVG语法

```bash
./fireworks-tech-graph/scripts/validate-svg.sh <svg-file>
```

### 4. 样式参考文件

`references/`目录包含7种视觉样式参考：

- style-1-flat-icon.md - 扁平图标（默认）
- style-2-dark-terminal.md - 深色终端
- style-3-blueprint.md - 蓝图
- style-4-notion-clean.md - Notion简洁
- style-5-glassmorphism.md - 玻璃态
- style-6-claude-official.md - Claude官方
- style-7-openai.md - OpenAI官方
- icons.md - 图标参考
- style-diagram-matrix.md - 样式-图表类型适配矩阵
- svg-layout-best-practices.md - SVG布局最佳实践

## 工作流程（始终遵循此顺序）

1. **分类**图表类型
2. **提取结构** — 从用户描述中识别层、节点、边、流和语义组
3. **规划布局** — 应用图表类型的布局规则
4. **加载样式参考** — 默认加载style-1-flat-icon
5. **将节点映射到形状** — 使用形状词汇表
6. **检查图标需求**
7. **编写SVG** — 使用Python List方法（强制）
8. **验证**：运行`rsvg-convert file.svg -o /dev/null 2>&1`
9. **导出PNG**：`rsvg-convert -w 1920 file.svg -o file.png`
10. **报告**生成的文件路径
11. **（可选）视觉自查**

## 图表类型与布局规则

### 架构图

节点=服务/组件。分组为水平层（从上到下或从左到右）。

- 典型层：客户端 → 网关/负载均衡 → 服务 → 数据/存储
- 使用`<rect>`虚线容器将同一层的相关服务分组
- 箭头方向跟随数据/请求流
- ViewBox：`0 0 960 600`标准，`0 0 960 800`用于高堆栈

### 数据流图

强调数据移动到哪里。关注数据转换。

- 为每个箭头标注数据类型（如embeddings、query、context）
- 使用更宽的箭头（stroke-width: 2.5）表示主要数据路径
- 虚线箭头表示控制/触发流
- 按数据类别为箭头着色

### 流程图/过程流

顺序决策/过程步骤。

- 优先从上到下；宽流程从左到右
- 菱形表示决策，圆角矩形表示过程，平行四边形表示I/O
- 保持节点标签简短（≤3个词）
- 在网格上对齐节点：x位置对齐到120px间隔，y对齐到80px

### Agent架构图

展示AI代理如何推理、使用工具和管理记忆。

关键概念层：

- **输入层**：用户、查询、触发
- **Agent核心**：LLM、推理循环、规划器
- **记忆层**：短期（上下文窗口）、长期（向量/图数据库）、情景
- **工具层**：工具调用、API、搜索、代码执行
- **输出层**：响应、动作、副作用

使用循环箭头（循环弧）显示迭代推理。视觉上分离不同类型的记忆。

### 记忆架构图（Mem0、MemGPT风格）

专注于记忆操作的Agent图。

- 分别显示记忆写入路径和读取路径（不同箭头颜色）
- 记忆层级：工作记忆 → 短期 → 长期 → 外部存储
- 标注记忆操作：store()、retrieve()、forget()、consolidate()
- 使用堆叠矩形或分层圆柱体表示存储层级

### 序列图

参与者之间按时间排序的消息交换。

- 参与者作为垂直生命线（顶部标签 + 垂直虚线）
- 消息作为生命线之间的水平箭头，从上到下时间排序
- 激活框（生命线上的细填充矩形）显示活动处理
- 使用`<rect>`循环/alt框架分组，标签在左上角
- ViewBox高度 = 80 + (消息数 × 50)

### 对比/特性矩阵

方法、系统或组件的并排比较。

- 列标题=系统，行标题=属性
- 行高：40px；列宽：最小120px；标题行高：50px
- 已支持单元格：着色背景（如#dcfce7）+ ✓复选标记
- 交替行填充（#f9fafb / #ffffff）提高可读性
- 最大可读列数：5；超过则拆分为两个图表

### 时间线/甘特图

显示持续时间、阶段和里程碑的水平时间轴。

- X轴=时间（周/月/季度）；Y轴=项目/任务/阶段
- 条形：圆角矩形，按类别着色，内部或旁边标注
- 里程碑标记：特定x位置的菱形或填充圆，标签在上方
- ViewBox：0 0 960 400典型；更多时间段更宽：0 0 1200 400

### 思维导图/概念图

从中心概念的径向布局。

- 中心节点在cx=480, cy=280
- 一级分支：围绕中心均匀分布（360/N度）
- 二级分支：从一级分支以30-45°偏移分支
- 使用三次贝塞尔曲线<path>表示分支，而非直线

### 类图（UML）

显示类、属性、方法和关系的静态结构。

- **类框**：3分区矩形（名称/属性/方法），最小宽度160px
- **关系**：继承（实线+空心三角）、实现（虚线+空心三角）、关联（实线+开放箭头）、聚合（空心菱形）、组合（实心菱形）、依赖（虚线+开放箭头）
- ViewBox：0 0 960 600标准；0 0 960 800用于深层结构

### 用例图（UML）

从用户视角看系统功能。

- **参与者**：火柴人，放在系统边界外
- **用例**：椭圆，标签居中，最小140×60px
- **系统边界**：大矩形，虚线边框
- **关系**：包含（Include）、扩展（Extend）、泛化
- ViewBox：0 0 960 600标准

### 状态机图（UML）

实体的生命周期状态和转换。

- **状态**：圆角矩形带状态名，最小120×50px
- **初始状态**：实心黑色圆（r=8）
- **最终状态**：空心圆内的实心圆
- **转换**：箭头，可选标签event [guard] / action
- ViewBox：0 0 960 600标准

### ER图（实体关系）

数据库模式和数据关系。

- **实体**：矩形，标题区粗体显示实体名，下方属性
- **关系**：连接线上的菱形
- **基数标签**：1、N、0..1、0.._、1.._
- ViewBox：0 0 960 600标准；更多实体更宽：0 0 1200 600

### 网络拓扑

物理或逻辑网络基础设施。

- **设备**：路由器、交换机、服务器、防火墙、负载均衡器、云
- **连接**：有线（实线）、无线（虚线+WiFi）、VPN（虚线+锁）
- **子网/区域**：虚线矩形容器（DMZ、内部、外部）
- 布局：分层从上到下（互联网 → 边缘 → 核心 → 接入 → 端点）
- ViewBox：0 0 960 600标准

## 形状词汇表

将语义概念映射到一致的形状：

| 概念         | 形状                     | 备注           |
| ------------ | ------------------------ | -------------- |
| 用户/人类    | 圆形+身体路径            | 火柴人或头像   |
| LLM/模型     | 圆角矩形+大脑/火花图标   | 使用强调色     |
| Agent/编排器 | 六边形或双边框圆角矩形   | 表示活动控制器 |
| 短期记忆     | 虚线边框圆角矩形         | 短暂=虚线      |
| 长期记忆     | 圆柱体（数据库形状）     | 持久=实心圆柱  |
| 向量存储     | 带网格线的圆柱体         | 添加3条水平线  |
| 图数据库     | 圆形集群（3个重叠圆）    |                |
| 工具/函数    | 齿轮状矩形或扳手图标     |                |
| API/网关     | 六边形单边框             |                |
| 队列/流      | 水平管（管道形状）       |                |
| 文件/文档    | 折角矩形                 |                |
| 浏览器/UI    | 带3点标题栏的矩形        |                |
| 决策         | 菱形                     | 仅流程图       |
| 过程/步骤    | 圆角矩形                 | 标准框         |
| 外部服务     | 带云图标或虚线边框的矩形 |                |
| 数据/制品    | 平行四边形               | 流程图中的I/O  |

## 箭头语义

始终为箭头分配含义，不仅仅是颜色：

| 流类型    | 颜色        | 笔划      | 虚线 | 含义               |
| --------- | ----------- | --------- | ---- | ------------------ |
| 主数据流  | 蓝色#2563eb | 2px实线   | 无   | 主请求/响应路径    |
| 控制/触发 | 橙色#ea580c | 1.5px实线 | 无   | 一个系统触发另一个 |
| 记忆读取  | 绿色#059669 | 1.5px实线 | 无   | 从存储检索         |
| 记忆写入  | 绿色#059669 | 1.5px     | 5,3  | 写入/存储操作      |
| 异步/事件 | 灰色#6b7280 | 1.5px     | 4,2  | 非阻塞、事件驱动   |
| 嵌入/转换 | 紫色#7c3aed | 1px实线   | 无   | 数据转换           |
| 反馈/循环 | 紫色#7c3aed | 1.5px曲线 | 无   | 迭代推理循环       |

当使用2种以上箭头类型时，始终包含图例。

## 布局规则与验证

**间距**：

- 同层节点：80px水平，120px垂直层间
- 画布边距：最小40px，节点边缘间60px
- 对齐到8px网格：水平120px间隔，垂直120px间隔

**箭头标签**（关键）：

- 必须有背景rect：`<rect fill="canvas_bg" opacity="0.95"/>`，水平4px、垂直2px内边距
- 放在箭头中点，≤3个词，多个箭头汇聚时错开15-20px
- 与节点保持10px安全距离

**箭头路由**：

- 优先正交（L形）路径以最小化交叉
- 在组件边缘锚定箭头，而非几何中心
- 绕过密集节点集群，平行箭头使用不同y偏移
- 不可避免的交叉使用跳弧（5px半径）

**线重叠预防**（关键 - 最常见bug）：

- 两条箭头必须交叉时，始终使用跳弧防止视觉重叠
- 交叉水平箭头：添加小半圆弧（半径5px）跳过另一条线
- 多个交叉：错开弧半径（5px、7px、9px）

**验证清单**（完成前运行）：

1. **箭头-组件碰撞**：箭头不得穿过组件内部
2. **文本溢出**：所有文本必须在8px内边距内
3. **箭头-文本对齐**：箭头端点必须连接到形状边缘
4. **容器规则**：优先通过组件间的开放间隙进出

## SVG技术规则

- ViewBox：`0 0 960 600`默认；`0 0 960 800`高；`0 0 1200 600`宽
- 字体：通过`<style>font-family: ...</style>`嵌入 — 不使用外部`@import`
- `<defs>`：箭头标记、渐变、滤镜、剪切路径
- 文本：最小12px，推荐13-14px标签，11px子标签，16-18px标题
- 所有箭头：`<marker>`带`markerEnd`，尺寸`markerWidth="10" markerHeight="7"`
- 投影：`<feDropShadow>`在`<filter>`中，谨慎使用（仅关键节点）
- 曲线路径：使用`M x1,y1 C cx1,cy1 cx2,cy2 x2,y2`三次贝塞尔
- 剪切内容：文本可能溢出节点框时使用`<clipPath>`

## SVG生成与错误预防

**强制：Python List方法**（始终使用）：

```python
python3 << 'EOF'
lines = []
lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
lines.append('  <defs>')
# ... 每行单独
lines.append('</svg>')
with open('/path/to/output.svg', 'w') as f:
    f.write('\n'.join(lines))
print("SVG generated successfully")
EOF
```

**预调用清单**（关键 - 每次使用）：

1. ✅ 我能立即写出完整的命令/内容吗？
2. ✅ 我准备好所有必需参数了吗？
3. ✅ 我检查过准备内容的语法错误了吗？

**错误恢复协议**：

- 第一次错误：分析根本原因，应用针对性修复
- 第二次错误：完全切换方法（Python列表 → 分块生成）
- 第三次错误：停止并报告用户 — 不要无限循环

**验证**（生成后运行）：

```bash
rsvg-convert file.svg -o /tmp/test.png 2>&1 && echo "✓ Valid" && rm /tmp/test.png
```

## 样式

| #   | 名称                 | 背景          | 最佳用途           |
| --- | -------------------- | ------------- | ------------------ |
| 1   | **扁平图标**（默认） | 白色          | 博客、文档、演示   |
| 2   | **深色终端**         | #0f0f1a       | GitHub、开发文章   |
| 3   | **蓝图**             | #0a1628       | 架构文档           |
| 4   | **Notion简洁**       | 白色、极简    | Notion             |
| 5   | **玻璃态**           | 深色渐变      | 产品网站、主题演讲 |
| 6   | **Claude官方**       | 暖奶油#f8f6f3 | Anthropic风格图表  |
| 7   | **OpenAI官方**       | 纯白#ffffff   | OpenAI风格图表     |

## 常见模式

这些模式经常出现 — 内化它们：

- **RAG管道**：Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response
- **Agentic RAG**：在Query和LLM之间添加Agent循环和工具使用
- **Agentic Search**：Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response
- **Mem0 / 记忆层**：Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context
- **Agent记忆类型**：Sensory（原始输入） → Working（上下文窗口） → Episodic（过去交互） → Semantic（事实） → Procedural（技能）
- **Multi-Agent**：Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output
- **工具调用流**：LLM → Tool Selector → Tool Execution → Result Parser → LLM（循环）
