fireworks-tech-graph

Fireworks Tech Graph

生成生产级的 SVG 技术图表，并通过 cairosvg（推荐）、rsvg-convert 或 puppeteer 导出为 PNG 图片。

安装来源

从 GitHub 安装此 Skill：

npx skills add yizhiyanhua-ai/fireworks-tech-graph

npm 公开包页面：

https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph

注意：请勿直接将 @yizhiyanhua-ai/fireworks-tech-graph 传给 skills add 命令，因为该 CLI 仅支持 GitHub 或本地仓库源。

更新命令：

npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y

辅助脚本（推荐）

scripts/ 目录中提供了四个辅助脚本，用于实现稳定的 SVG 生成与校验：

1. generate-diagram.sh - 校验 SVG 并导出 PNG

./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

• 校验现有的 SVG 文件
• 校验通过后导出 PNG
• 示例：./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

2. generate-from-template.py - 根据模板创建基础 SVG

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

• 加载内置的 SVG 模板
• 根据输入的 JSON 数据渲染节点（nodes）、箭头（arrows）和图例项（legend entries）
• 转义文本内容，确保输出符合 XML 语法规范

3. validate-svg.sh - 校验 SVG 语法

./scripts/validate-svg.sh <svg-file>

• 检查 XML 语法
• 校验标签闭合情况
• 校验 marker 标记引用
• 检查属性完整性
• 校验路径（path）数据

4. test-all-styles.sh - 批量测试所有样式

./scripts/test-all-styles.sh

• 测试多种图表尺寸
• 校验所有生成的 SVG 文件
• 生成测试报告

何时使用脚本：

• 生成复杂的 SVG 时建议使用脚本，以避免语法错误
• 脚本提供自动校验与错误回报机制
• 生产环境图表推荐使用脚本

何时直接生成 SVG：

• 元素较少的简单图表
• 快速原型设计
• 需要完全掌控 SVG 底层结构时

工作流（请务必严格按此顺序执行）

1. 分类：确定图表类型（参见下文“图表类型与布局规则”）
2. 提取结构：从用户的描述中识别层级、节点、边（连线）、流程以及语义分组
3. 规划布局：应用对应图表类型的布局规则
4. 加载样式参考：除非用户另有指定，否则默认加载 references/style-1-flat-icon.md；加载对应的 references/style-N.md 以获取准确的颜色 Token 和 SVG 模式
5. 节点映射至形状：参考下文的“形状词汇表”
6. 检查图标需求：加载 references/icons.md 获取已知产品的图标
7. 编写 SVG：使用自适应生成策略（参见下文“SVG 生成策略”）
8. 语法校验：运行 python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" 检查 XML 语法
9. 导出 PNG：推荐使用 cairosvg。全面方法对比见下文 SVG → PNG 转换 章节
10. 报告路径：输出已生成的图像文件路径
11. （可选）视觉自检：如果你的运行环境支持读取图片，请将导出的 PNG 加载回来进行检查。仅靠语法正确无法保证视觉效果：连线箭头可能会穿过组件内部、文本标签可能与生命线或其它标签重叠、框体之间可能重叠、分支框（alt-frame）文本可能会压在消息连线上、图例可能会遮挡主体内容。一旦发现这些问题，请修补 SVG 并重新导出，重复此过程直到渲染图片干净整洁。常见修补手段：
    • 调整箭头路由路径，使其从框体间的缝隙穿过，切勿穿过框体内部
    • 将箭头文本标签向外移动 6-8px（优先采用偏移量调整）；仅当偏移仍不够用时再添加背景矩形遮罩
    • 加宽行间距/列间距，为同层连线腾出清晰的通道
    • 将重复的跨层连线合并为一条位于主内容区外的“向下委托”干线轴
    • 将图例/注释移出任何可能落入箭头或标签的区域
    • 适当增大 viewBox 的宽度/高度，而不是强行挤在一起
    • 如果带有滤镜效果（如阴影 drop-shadow、模糊 blur）的元素边缘缺失，将其往 viewBox 内部移动 ≥30px，或者直接移除滤镜，依靠色彩/对比度进行视觉分隔
      如果运行环境不支持读取图片，请直接静默跳过此步骤——切勿盲目凭空猜测。

图表类型与布局规则

架构图 (Architecture Diagram)

节点 = 服务/组件。按水平层级（自上而下或自左向右）进行分组。

• 典型层级：客户端 (Client) → 网关/负载均衡 (Gateway/LB) → 服务层 (Services) → 数据/存储层 (Data/Storage)
• 使用虚线 <rect> 容器将同层级的关联服务包裹分组
• 箭头方向顺应数据/请求的流动方向
• ViewBox 尺寸：标准采用 0 0 960 600，较深的纵向堆叠架构采用 0 0 960 800

数据流图 (Data Flow Diagram)

突出强调数据流动的具体路径与去向。重点放在数据转换过程上。

• 每一条箭头都要标注对应的数据类型（如 "embeddings"、"query"、"context"）
• 主数据通道使用更粗的连线 (stroke-width: 2.5)
• 控制流/触发流使用虚线箭头
• 根据数据分类为箭头上色（不仅限于 Agent/RAG，要结合业务语义）

流程图 / 过程流 (Flowchart / Process Flow)

展示顺序决策与处理步骤。

• 优先选择自上而下的布局；较宽的流程可选择自左向右
• 决策节点用菱形，处理过程用圆角矩形，输入/输出用平行四边形
• 保持节点标签精简（≤3 个词）；详细说明放入子标签中
• 节点网格对齐：X 轴坐标按 120px 间距对齐，Y 轴坐标按 80px 间距对齐

Agent 架构图 (Agent Architecture Diagram)

展示 AI Agent 如何思考、调用工具以及管理记忆。
必须重点考虑的关键概念层级：

• 输入层 (Input layer)：用户、查询、触发器
• Agent 核心 (Agent core)：LLM、推理循环 (reasoning loop)、规划器 (planner)
• 记忆层 (Memory layer)：短期记忆（上下文窗口）、长期记忆（向量/图数据库）、情景记忆 (Episodic)
• 工具层 (Tool layer)：工具调用、API、搜索、代码执行
• 输出层 (Output layer)：响应、行动、侧效应 (side-effects)
  使用环形箭头（循环弧线）展示迭代推理过程。在视觉上对不同记忆类型进行明确区分。

记忆架构图 (Memory Architecture Diagram, Mem0/MemGPT 风格)

专门用于展现记忆操作细节的 Agent 架构图。

• 将记忆的写入路径与读取路径分开展示（使用不同颜色的箭头）
• 记忆层级：工作记忆 (Working Memory) → 短期记忆 → 长期记忆 → 外部存储
• 标注具体的记忆操作接口：store()、retrieve()、forget()、consolidate()
• 存储层级使用堆叠矩形或分层圆柱体表示

时序图 (Sequence Diagram)

按时间顺序展示参与者之间的消息交互。

• 参与者作为垂直生命线（顶部绘制标签 + 垂直虚线）
• 消息作为生命线之间的水平箭头，按自上而下的时间顺序排列
• 激活框（生命线上的细长填充矩形）表示正在进行处理
• 使用带有左上角标签的 <rect> loop/alt 矩形框进行逻辑分组
• ViewBox 高度 = 80 + (消息数量 × 50)

对比 / 功能矩阵图 (Comparison / Feature Matrix)

对多种方案、系统或组件进行横向对比。

• 列标题 = 各系统，行标题 = 各项指标/特性
• 行高：40px；列宽：最小 120px；标题行高：50px
• 支持/勾选单元格：浅色背景（如 #dcfce7）+ ✓ 勾选标记；不支持单元格：#f9fafb 填充
• 交替行填充颜色（#f9fafb / #ffffff）提升可读性
• 最佳可读列数：最多 5 列；若超过 5 列，请拆分为两张图表

时间线 / 甘特图 (Timeline / Gantt)

用水平时间轴展示持续时间、阶段与里程碑。

• X 轴 = 时间（周/月/季度）；Y 轴 = 项目/任务/阶段
• 进度条：圆角矩形，按分类上色，标签写在内部或旁边
• 里程碑标记：在特定 X 位置绘制菱形或实心圆，上方附带标签
• ViewBox 尺寸：典型为 0 0 960 400；跨度较长时可加宽为 0 0 1200 400

思维导图 / 概念图 (Mind Map / Concept Map)

从核心概念向外放射扩展的布局。

• 中心节点位于 cx=480, cy=280
• 一级分支：围绕中心均匀分布（360/N 度）
• 二级分支：在一级分支基础上以 30-45° 偏移角度延伸
• 分支连线使用三次贝塞尔曲线 <path>，避免使用直线

类图 (Class Diagram, UML)

展示类、属性、方法及其关系的静态结构图。

• 类框图：三段式矩形（类名 / 属性 / 方法），最小宽度 160px
  • 顶层段：类名，加粗居中（抽象类用 斜体）
  • 中间段：带有可见性修饰符的属性（+ 公有，- 私有，# 受保护）
  • 底层段：方法签名，使用相同的可见性符号
• 类关系表示：
  • 继承 (extends)：实线 + 空心三角形箭头，子类 → 父类
  • 实现 (interface)：虚线 + 空心三角形，实现类 → 接口
  • 关联 (Association)：实线 + 开口箭头，标注重数（如 1, 0.., 1..）
  • 聚合 (Aggregation)：实线 + 容器端的空心菱形
  • 组合 (Composition)：实线 + 容器端的实心菱形
  • 依赖 (Dependency)：虚线 + 开口箭头
• 接口 (Interface)：类名上方标注 <<interface>> 构造型，或使用圆圈/棒棒糖记号
• 枚举 (Enum)：带有 <<enumeration>> 构造型的三段式矩形，枚举值放在底层段
• 布局规则：父类在上方，子类在下方；接口置于实现者的左侧/右侧
• ViewBox 尺寸：标准采用 0 0 960 600；深层继承树采用 0 0 960 800

用例图 (Use Case Diagram, UML)

从用户视角展示系统功能。

• 参与者 (Actor)：火柴人图形（圆圈头部 + 身体连线），置于系统边界之外
  • 标签置于图形下方，字号 13-14px
  • 主要参与者在左侧，次要/辅助参与者在右侧
• 用例 (Use case)：椭圆形，标签在内部居中，最小尺寸 140×60px
  • 名称保持动宾短语形式：例如 "创建订单"、"处理支付"
• 系统边界 (System boundary)：大型虚线框矩形，左上角标注系统名称
• 关系表示：
  • 包含 (Include)：从基础用例指向被包含用例的 <<include>> 虚线箭头
  • 扩展 (Extend)：从扩展用例指向基础用例的 <<extend>> 虚线箭头
  • 泛化 (Generalization)：实线 + 空心三角形（具体指向抽象/通用）
• 布局规则：系统边界居中，参与者在两侧外部，用例在边界内部
• ViewBox 尺寸：标准采用 0 0 960 600

状态机图 (State Machine Diagram, UML)

展示实体的生命周期状态与状态流转。

• 状态 (State)：圆角矩形，带有状态名称，最小尺寸 120×50px
  • 内部活动：小字标注 entry/ action、exit/ action、do/ activity
  • 初始状态：实心黑圆（r=8），带有一条发出的连线箭头
  • 终止状态：实心圆（r=8）外套一层空心圆（r=12）
  • 判断节点 (Choice)：小型空心菱形，发出的箭线上标注条件守护 [condition]
• 状态转移 (Transition)：箭头，带可选标签 event [guard] / action
  • 守护条件写在方括号中
  • 动作写在 / 之后
• 复合/嵌套状态：包含子状态的大型矩形，带有名称标签页
• 分叉/汇合 (Fork/join)：粗黑的水平或垂直线条（同步线条）
• 布局规则：初始状态在左上方，终止状态在右下方，整体流向自上而下
• ViewBox 尺寸：标准采用 0 0 960 600

ER 图 / 实体关系图 (Entity-Relationship)

展示数据库模式与数据实体间的关系。

• 实体 (Entity)：矩形，顶部标题栏加粗显示实体名，下方放置属性列表
  • 主键属性：加下划线
  • 外键属性：斜体或标记 (FK)
  • 最小宽度：160px；属性字号：12px
• 关系 (Relationship)：连线中间的菱形
  • 菱形内部标签："拥有"、"属于"、"选修" 等
  • 实体附近的基数/重数标注：1、N、0..1、0..*、1..*
• 弱实体 (Weak entity)：双边框矩形，搭配双边框菱形关系
• 结合实体 (Associative entity)：菱形与矩形的结合体（矩形内含菱形）
• 连线样式：标识性关系用实线，非标识性关系用虚线
• 布局规则：实体分 2-3 行排列，关系置于关联实体之间
• ViewBox 尺寸：标准采用 0 0 960 600；实体较多时加宽为 0 0 1200 600

网络拓扑图 (Network Topology)

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

• 设备 (Devices)：图标化的矩形或圆角矩形
  • 路由器 (Router)：圆形