Skill - 从自然语言到可发布架构图：fireworks-tech-graph 的工程化拆解

文章目录

• 一、为什么技术图一直是工程团队的隐形债务
• [二、项目概览：一个能同时跑在 Codex 和 Claude Code 上的 Agent Skill](#二、项目概览：一个能同时跑在 Codex 和 Claude Code 上的 Agent Skill)
• 三、设计支柱之一：可执行的风格系统
• 四、设计支柱之二：语义化的形状与箭头词汇表
• [五、设计支柱之三：Diagram IR 与结构化校验](#五、设计支柱之三：Diagram IR 与结构化校验)
• 六、设计支柱之四：几何安全的路由与组合质量契约
• [七、设计支柱之五：Loop Engineering------有界的验证反馈闭环](#七、设计支柱之五：Loop Engineering——有界的验证反馈闭环)
• [八、语义动效：从静态 SVG 到经过验证的 GIF](#八、语义动效：从静态 SVG 到经过验证的 GIF)
• [九、上手：安装、依赖与 CLI](#九、上手：安装、依赖与 CLI)
• • 推荐安装方式
  • [可编辑的 Git 检出](#可编辑的 Git 检出)
  • 一份检出，两端共享
  • 渲染器依赖
  • [统一 CLI](#统一 CLI)
• 十、实战：按场景写提示词
• • [AI / Agent 系统](#AI / Agent 系统)
  • 基础设施与云
  • 工程评审场景的提示词指纹
  • 风格选择速查
  • 产品图标覆盖
• [十一、与 Mermaid、draw.io 的定位差异](#十一、与 Mermaid、draw.io 的定位差异)
• 十二、排错手册
• 十三、可迁移的方法论
• 十四、边界与适用范围
• 十五、结语

一句话概括：它不是又一个画图工具，而是把「图好不好看」这件主观的事，改写成了一组可执行、可校验、可回归的工程契约。

一、为什么技术图一直是工程团队的隐形债务

写过设计文档的人都清楚一件事：文字部分往往一两个小时就能交付，卡住进度的经常是那张架构图。

真实的困境大致分三类。

第一类是工具与表达之间的落差。Mermaid 的语法足够轻，写在 Markdown 里随手可渲染，但它的布局引擎是自动的，你几乎无法精确控制一条边绕开哪个节点；一旦节点数超过十几个，连线就开始打结。draw.io 反过来，控制力极强，但每一个像素都要手工拖拽，改一次命名要点开七八个框，评审会上临时加一个服务就意味着重新排版半小时。

第二类是一致性问题。同一个系统，架构师画出来是蓝底白线，后端同学画出来是彩色圆角矩形，SRE 画出来又是另一套记号。数据库有时是圆柱体，有时是方框；异步调用有时用虚线，有时用不同颜色的实线。读者每看一张新图，都要重新学习一次视觉约定。图越多，认知负担越重。

第三类，也是最容易被忽略的一类：图没有验收标准。代码有单元测试、有 lint、有 CI；图只有「我看着还行」。箭头穿过了组件内部、标签压在连线上、图例盖住了内容、导出 PNG 底部被裁掉一截------这些问题往往到了 PPT 投屏那一刻才被发现。

fireworks-tech-graph 值得拆开来看的原因，正在于它对第三类问题给出了一个相当彻底的回答：把图当作构建产物，配一条带校验门禁的流水线。

二、项目概览：一个能同时跑在 Codex 和 Claude Code 上的 Agent Skill

这个项目由「一支烟花 AI 社区」维护，MIT 协议，目前 GitHub 上约 9.6k star、800+ fork，主体由 Python、JavaScript、HTML 和 Shell 构成。

它的形态是 Agent Skill ------不是 CLI 工具，也不是 SaaS，而是一份可以被编码智能体加载的能力包。同一份代码在 Codex 与 Claude Code 中原样运行：SKILL.md 是共享入口，捆绑资源全部使用相对路径，agents/openai.yaml 提供 Codex 专用的 UI 元数据，Claude Code 会直接忽略这个文件。

它的核心能力可以概括成一条链路：

自然语言描述
  → 几何校验通过的 SVG
  → 1920px 高分辨率 PNG
  → 经过验证的 SVG-to-GIF 语义动效
  → 可离线打开的交互式 HTML

一个最小示例长这样：

用户：生成一张 Mem0 记忆架构图，暗色风格
  → 技能分类：Memory Architecture Diagram，Style 2
  → 生成带泳道、圆柱体、语义箭头的 SVG
  → 导出 1920px PNG
  → 返回：mem0-architecture.svg / mem0-architecture.png

当前版本提供 12 种视觉风格 （11 种由生成器驱动 + 1 种 AI 自主排版）、14 种图类型（覆盖完整 UML 体系）以及一批 AI/Agent 领域的内建图式。

三、设计支柱之一：可执行的风格系统

多数「多主题」画图工具的做法是：写一份风格指南，然后指望使用者遵守。这种约定在人类手里就已经容易走样，交给大模型更是必然漂移。

这里的处理方式不同------风格被编码进生成器，而不是只写在 Markdown 里 。每个风格在 references/ 下有独立的参考文件，规定精确的色值 token 与 SVG 图案；生成阶段直接消费这些定义。

12 种风格及其定位：

#	名称	背景	字体	适用场景
1	Flat Icon（默认）	#ffffff	Helvetica	博客、幻灯片、文档
2	Dark Terminal	#0f0f1a	SF Mono / Fira Code	GitHub README、开发者文章
3	Blueprint	#0a1628	Courier New	架构文档、工程蓝图
4	Notion Clean	#ffffff	system-ui	Notion、Confluence、Wiki
5	Glassmorphism	#0d1117 渐变	Inter	产品站、主题演讲
6	Claude Official	#f8f6f3	system-ui	Anthropic 风格、暖色调
7	OpenAI Official	#ffffff	system-ui	OpenAI 风格、干净现代
8	Dark Luxury（AI 排版）	#0a0a0a	Georgia + system-ui	高端文档、README 头图、大会 slide
9	C4 Review Canvas	#f7f2e8	Avenir / system-ui	C4 评审、ADR、职责界定
10	Cloud Fabric	#edf5fb	Inter / system-ui	多区域部署、VPC/网络归属
11	Event Transit	#fbf7ee	Avenir / system-ui	Kafka 事件流、消费组、DLQ
12	Ops Pulse	#07111f	SF Mono / Fira Code	SRE 复盘、黄金信号、关键链路

真正有意思的是 9 到 12 这四种「工程优先」风格 。它们不只提供配色，还附带领域语义契约：

• Style 9（C4 评审）：必须声明单一抽象层级，标注职责、技术选型、评审状态与关系协议。混层会被判失败。
• Style 10（云部署）：必须表达全局入口、Region/VPC 归属、部署模式与跨边界机制。
• Style 11（事件流）：主题是细轨道，处理器是编号站点，还需声明汇合点、消费组、死信队列与状态投影。
• Style 12（可靠性）：必须给出一个观测窗口、每个服务的四项黄金信号、编号的关键跳数、遥测导出路径，以及一条被关联的 trace。

这些字段在布局之前就会被 fireworks.py validate 检查，缺失或自相矛盾的工程事实直接 fail closed。换句话说，你没法用它画出一张「看起来像 C4 但实际上把容器和组件混在一层」的图------契约不允许。

这一步的价值超出了美观范畴。它把「画图」从表达行为变成了建模行为：你被迫先把系统事实说清楚，才能拿到图。

四、设计支柱之二：语义化的形状与箭头词汇表

一致性靠的不是自觉，而是词汇表。形状与线条被赋予固定含义，跨风格保持稳定。

形状部分：

概念	形状
用户 / 人	圆形 + 身体
LLM / 模型	双边框圆角矩形，带 ⚡
Agent / 编排器	六边形
短期记忆	虚线边框圆角矩形
长期记忆	实心圆柱
向量库	带内环的圆柱
图数据库	三圆簇
工具 / 函数	带 ⚙ 的矩形
API / 网关	单边框六边形
队列 / 流	横向管道
文档 / 文件	折角矩形
浏览器 / UI	带三点标题栏的矩形
判定	菱形
外部服务	虚线边框矩形

这里的记号选择是有讲究的：短暂用虚线、持久用实体，是一条几乎不需要图例就能被读者内化的规则；向量库在圆柱里加内环，与普通数据库形成最小差异但足够可辨的区分。

箭头部分把「颜色 + 线型」组合成语义编码：

流类型	颜色	线宽	虚线	含义
主数据流	蓝 #2563eb	2px 实线	无	主请求/响应路径
控制 / 触发	橙 #ea580c	1.5px 实线	无	A 触发 B
记忆读	绿 #059669	1.5px 实线	无	从存储检索
记忆写	绿 #059669	1.5px	5,3	写入/落库
异步 / 事件	灰 #6b7280	1.5px	4,2	非阻塞
嵌入 / 变换	紫 #7c3aed	1px 实线	无	数据变换
反馈 / 循环	紫 #7c3aed	1.5px 曲线	无	迭代推理

注意「记忆读」和「记忆写」共用绿色，只靠虚线区分------这是刻意的设计：同一语义家族共享色相，家族内部用线型细分。这样读者的第一层判断（这是不是记忆操作）成本极低，第二层判断（读还是写）再看线型。

还有一条硬规则：只要用到两种以上箭头类型，必须出图例。

五、设计支柱之三：Diagram IR 与结构化校验

从自然语言直接生成 SVG 字符串，是最容易出问题的路径------模型可能写出未闭合标签、引用不存在的 marker、给出非有限的坐标。这个项目在中间插了一层版本化的图中间表示（Diagram IR）。

scripts/diagram_ir.py 负责把输入规范化到 schema v1，历史遗留的 JSON 也会被归一。在这一层，以下问题会在渲染之前被拦下：

• 重复 ID
• 悬空引用（边指向不存在的节点）
• 畸形的路径 waypoint
• 非有限的几何数值（NaN、Infinity）

通过 IR 之后，还有一道结构化 SVG 校验 （validate_svg.py），检查项包括 XML 结构、marker 完整性、语义节点、保留区域、标签、画布边界、边重叠与边交叉。

生成器消费的结构字段是显式的：containers（容器分组）、nodes[].kind（节点语义类型）、arrows[].flow（流语义）以及明确的端口锚点。还有几个高杠杆字段，能在不 fork 整套风格的前提下做局部微调：

• style_overrides：微调标题对齐或调色板 token
• containers[].header_prefix / header_text：蓝图风格的编号段头，例如 01 // EDGE
• containers[].side_label：Claude 风格的左侧层级标签
• window_controls、meta_left、meta_center、meta_right：终端/文档外框装饰
• blueprint_title_block：Style 3 的工程标题栏

把这层 IR 加进来的收益是结构性的：模型的自由度被限制在「填字段」而不是「写 XML」，可校验面积因此大幅增加。这是所有 LLM 生成结构化产物的通用经验------不要让模型直接产出最终格式，让它产出可校验的中间表示。

六、设计支柱之四：几何安全的路由与组合质量契约

图之所以难看，八成不是配色问题，而是连线问题。

路由这块采用确定性正交布线：精确 waypoint、独立端口、图例自动避让、标签强制留在画布内，对无法避免的交叉使用经过验证的跨线桥（bridge jump）。

更值得关注的是那份共享组合质量契约 （references/composition-quality-contract.md），它给出的是可量化的预算：

零交叉、零桥跳
每条边最多 2 个折点
整图最多 8 个折点
节点间距 ≥ 40px
容器内边距 ≥ 20px
避免过短的正交线段
标签必须远离节点、路线与段头

布局规则同样具体：同层节点水平间距 80px，层间垂直间距 120px；画布外边距至少 40px，节点边缘之间 60px；坐标吸附到 8px 网格。序列图的画布高度直接给公式：80 + 消息数 × 50。心智图的中心节点固定在 cx=480, cy=280，一级分支按 360/N 度均分。

箭头标签有一条被标记为 CRITICAL 的规则，很值得单独说：

• 偏移优先：水平箭头的标签放在线上方 6--8px，垂直箭头放在左右 8px，绝不压线
• 背景兜底：只有当偏移后仍与其他元素冲突时，才加背景矩形
• 标签放在箭头中段，不超过 3 个词；多条箭头汇聚时错开 15--20px

为什么是「偏移优先」而不是「一律加白底」？因为白底色块会在深色风格里割裂背景，在密集区域会遮挡相邻连线。先用空间解决问题，实在不行才用遮挡解决------这个优先级顺序本身就是排版经验的沉淀。

七、设计支柱之五：Loop Engineering------有界的验证反馈闭环

这是整个项目最具方法论价值的部分。

首次渲染的结果被当作候选，而不是自动定稿。完整链路如下：

Prompt
  → Diagram Contract
  → Semantic IR
  → Style Spec
  → Route Planner
  → SVG Build
  → Structural Validation
  → PNG Visual Readback
  → Targeted Revision
  → Verified SVG + PNG

背后是五条设计原则：

1. 求证，而非断言（Evaluate, don't assert）------完成状态由校验器和渲染证据支撑，而不是模型自己说「看起来没问题」。
2. 确定性检查优先------XML 结构、marker 完整性、路径几何、箭头与组件的碰撞、可渲染性，全部先于视觉判断执行。
3. 感知校验其次------把导出的 PNG 读回来，检查裁切、标签碰撞、层级关系、留白与走线质量。这些是语法检查看不见的东西。
4. 定向修正------每一轮只改被诊断出的标签、坐标、走线通道或间距，然后重跑校验与渲染。
5. 有界收敛------视觉复核默认最多两轮定向修正，杜绝无限自我编辑。

最终状态是可观测的：

validation: passed
visual_review: passed

如果运行时没有读图能力，它会明确报告 visual_review: skipped (image reader unavailable)，而不是含糊带过。不谎报视觉验证------这一条在 AI 工具里比听上去更稀有。

视觉复核阶段的常见修正手法也被固化成了清单：

• 让箭头走盒子之间的空隙，不穿过组件内部
• 标签先偏移 6--8px，不够再加背景矩形
• 加宽行/列间距，给同层箭头留出走线通道
• 把重复的跨层箭头收敛成一条位于内容区外侧的「delegates down」总线
• 把图例/注释移出箭头与标签的落点区域
• 优先增大 viewBox，而不是把元素压得更紧
• 带滤镜（阴影、模糊）的元素若缺了一侧边框，把它移离该侧画布边缘 ≥30px，或者干脆去掉滤镜，用颜色对比来区隔

这套「有界闭环」的思路可以直接迁移到任何 AI 生成任务：先做确定性校验，再做感知校验，每轮只改被诊断的部分，并且给循环设上限。它同时解决了两个方向的失败------模型过早宣布成功，以及模型陷入无休止的自我修改。

八、语义动效：从静态 SVG 到经过验证的 GIF

动效在这里不是装饰，而是受契约约束的语义表达。

触发方式很直接：说「生成 GIF」「制作 GIF」「让这张图动起来」「把刚才的 SVG 转成 GIF」，或英文的 Generate a GIF / Animate this diagram。

输入必须是已生成的语义 SVG，且需满足 12 条已批准的动效契约之一。它不锁定源文件字节，因此同一拓扑的标题与内容变体可以通过；但角色/阶段/顺序覆盖、路线方向、必需颜色、几何形状一旦缺失或改变，直接 fail closed 。GIF 是唯一的动效媒介格式，默认命令还会同时输出 .motion.json 作为验证报告。

默认时间线参数是经过审批的固定值：

• 960px 宽、5.75 秒、20fps、115 个帧中心采样
• 所有场景以「无连接线」开场
• 第 1--36 帧：路线按语义顺序依次绘入
• 第 36--38 帧：实时流淡入
• 第 38--109 帧：保持完整的稳态流动
• 第 110--114 帧：复位

帧唯一性规则相当严格：75 帧及以下的时间线要求全部唯一；更长的时间线允许在全不透明区间内出现非相邻 的重复栅格；第 110 帧是唯一的边界例外------它的复位不透明度恰好等于 1.00，这类证据被归类为 intentional_reset_boundary_repeat；第 111--114 帧必须全局互异。长时间线至少要有 75 个唯一栅格，且禁止相邻重复。

75 帧与 115 帧的兼容门禁分两级计数：先比对二进制精确帧，再比对解码后 RGBA 精确帧；仅当合成器差异满足 AE ≤ 128、归一化 RMSE ≤ 0.001、每个差异分量不超过 2px 宽高、且差异全部落在边或节点边框上时，才接受抗锯齿等价回退。DOM 与签名几何保持严格精确。除默认时间线外，3.75s/75 帧与 2.75s/55 帧仍受支持。

每种风格有各自的「活体签名」：

风格	预设	动效签名
5	agent-orchestration	玻璃任务胶囊 + 协调器光晕
6	governed-runtime	治理线程 + 策略印章
7	token-stream	API 轨道 + 三格 token 列车
8	golden-circuit	奢华电路轨 + 宝石游标
9	review-trace	评审轨道 + 移动评审光标
10	cloud-flow	区域人字纹 + 复制胶囊
11	event-transit	事件列车 + 异常/投影车厢
12	ops-pulse	心电/导出头 + trace 揭示 + 瀑布扫描

把动画参数精确到帧号和 RMSE 阈值，看上去有些偏执。但换个角度看，这正是「让动效可回归」的必要条件：没有确定的帧时间线，就没有办法在 CI 里判断一次改动有没有破坏视觉输出。

九、上手：安装、依赖与 CLI

推荐安装方式

必须使用嵌套的技能路径，末尾的 /skills/fireworks-tech-graph 不能省略------当前版本的 skills CLI 在仓库根路径安装时只会选中根目录的 SKILL.md。

npx -y skills@1.5.17 add \
  yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy

这会在 ~/.agents/skills/fireworks-tech-graph（Codex）与 ~/.claude/skills/fireworks-tech-graph（Claude Code）各创建一份完整副本，含脚本、schema、fixture、模板、测试、参考文件与元数据。

可编辑的 Git 检出

# Codex
mkdir -p ~/.agents/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph

# Claude Code
mkdir -p ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

一份检出，两端共享

Claude Code 2.1.203 及以上版本可以用软链接共用同一份检出（先把已存在的目标目录挪开）：

mkdir -p ~/.local/share/agent-skills ~/.agents/skills ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph

这样 SKILL.md、references、scripts、templates 与后续更新在两个 agent 中始终一致。需要注意：npm 是独立的分发渠道，版本可能落后于 GitHub Release，追新请用上面的 GitHub 嵌套路径。

首次安装后重启 Codex 与 Claude Code 以完成发现；之后 SKILL.md 的改动会被自动检测，但改动捆绑脚本或参考文件后如果没生效，需要再重启一次运行时。

以上命令针对 macOS、Linux、WSL 与 Git Bash；原生 Windows 请换成 %USERPROFILE%\\.agents\\skills 与 %USERPROFILE%\\.claude\\skills。运行环境要求 Python 3.9+，可选的 Puppeteer 路径需要 Node.js 18+。

渲染器依赖

# 推荐：cairosvg（CSS 支持最好）
python3 -m pip install cairosvg

# 备选：rsvg-convert（系统包，可能丢失 CSS / foreignObject）
brew install librsvg                   # macOS
sudo apt install librsvg2-bin          # Ubuntu/Debian

# 可选：语义动效导出
brew install ffmpeg
for SKILL_ROOT in \
  "$HOME/.agents/skills/fireworks-tech-graph" \
  "$HOME/.claude/skills/fireworks-tech-graph"
do
  [ -d "$SKILL_ROOT" ] || continue
  npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false puppeteer-core@25.3.0
  python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
done

三种渲染器的取舍：

渲染器	质量	安装成本	何时使用
cairosvg	好	一条 pip 命令	默认选择，平衡最佳
rsvg-convert	一般	系统包	无 Python 环境、简单扁平图
puppeteer	最佳	Node + Chromium	D3、Mermaid 或像素级精确输出

注意 npm install 要装在每一份技能副本旁边------渲染器有意不从调用方目录加载模块。

统一 CLI

SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}"

python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture "$SKILL_ROOT/fixtures/api-flow-style7.json"
python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture "$SKILL_ROOT/fixtures/api-flow-style7.json" diagram.svg --report layout.json
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
python3 "$SKILL_ROOT/scripts/fireworks.py" export-html diagram.svg diagram.html --title "Agent Runtime Architecture"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

export-html 产出的是单个离线文件：内部会对 SVG 做净化处理，附带平移/缩放/复位、明暗主题、SVG 源码复制，以及 1×--4× 的 SVG/PNG/JPEG/WebP 下载。评审场景里这个格式相当好用------发一个文件出去，对方双击就能放大看细节，不需要装任何东西。

十、实战：按场景写提示词

触发词很宽松，中英文都能识别：

generate diagram / draw diagram / create chart / visualize
architecture diagram / flowchart / sequence diagram / data flow
生成 GIF / 制作 GIF / 让这张图动起来 / 把刚才的 SVG 转成 GIF

指定风格与输出路径也很自然：

画一张微服务架构图，style 2（暗色终端）
画一张多智能体协作图 --style glassmorphism
生成 Mem0 架构图，输出到 ~/Desktop/

AI / Agent 系统

内建的领域图式让这类图几乎不用解释细节：

RAG Pipeline         → Query → Embed → VectorSearch → Retrieve → LLM → Response
Agentic RAG          → 增加 Agent 循环 + 工具使用
Agentic Search       → Query → Planner → [Search/Calc/Code] → Synthesizer
Mem0 Memory Layer    → Input → Memory Manager → [VectorDB + GraphDB] → Context
Agent Memory Types   → Sensory → Working → Episodic → Semantic → Procedural
Multi-Agent          → Orchestrator → [SubAgent×N] → Aggregator → Output
Tool Call Flow       → LLM → Tool Selector → Execution → Parser → LLM（循环）

几个可直接复制的提示词：

用 Notion clean 风格做一张 Agentic RAG 与标准 RAG 的能力对比矩阵，
覆盖检索策略、Agent 循环、工具使用

生成 Mem0 记忆架构图，包含向量库、图数据库、KV 存储和记忆管理器

→ 带泳道的记忆架构：Input → Memory Manager → 存储分层 → Retrieval

画一张多智能体图：Orchestrator 派发 3 个 SubAgent（搜索/计算/代码执行），结果聚合

→ 六边形节点 + 工具层 + 结果聚合

绘制 Agent 架构图时，它会固定考虑五个概念层：输入层（用户、查询、触发）、Agent 核心（LLM、推理循环、规划器）、记忆层（短期上下文窗口、长期向量/图库、情景记忆）、工具层（工具调用、API、搜索、代码执行）、输出层（响应、动作、副作用）。迭代推理用环形弧线表示，不同记忆类型在视觉上强制区分。

记忆架构图还有额外约束：读路径与写路径必须用不同颜色分开画 ，存储分层按 Working → Short-term → Long-term → External Store 排列，记忆操作要标注成 store()、retrieve()、forget()、consolidate()。

基础设施与云

画微服务架构：Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL + Redis

生成数据管道图：Kafka → Spark 处理 → 写入 S3 → Athena 查询

画 Kubernetes 部署：Ingress → Service → [Pod × 3] → ConfigMap + PersistentVolume

工程评审场景的提示词指纹

对 9--12 这四种风格，用下面的措辞能让路由器同时选中领域契约与视觉主题：

Style 9 · C4 评审板：展示单一 C4 层级、职责、技术栈、评审状态与关系协议
Style 10 · 多区域部署图：展示全局入口、Region/VPC 归属、中性云图标、部署模式与命名边界机制
Style 11 · 事件地铁图：展示细主题轨道、编号处理器站点、声明的汇合点、消费组、DLQ 与状态投影
Style 12 · 可靠性脉搏：展示单一观测窗口、每服务四项黄金信号、编号关键跳、遥测导出与一条关联 trace

风格选择速查

• UML 类图/组件图/包图：Style 1 或 4，结构清晰易读
• 序列图/时序图：Style 2，等宽字体有助于对齐
• 状态机/活动图：Style 3，工程美学契合流程表达
• RAG / Agentic Search：Style 2 或 5
• 记忆架构：Style 3，强调分层存储
• 多智能体：Style 5，磨砂卡片天然区隔 agent 边界
• 内部文档 ：Style 4；博客 ：Style 1；GitHub README ：Style 2；演讲：Style 5 或 6
• Anthropic 项目 ：Style 6；OpenAI 项目 ：Style 7；高端编辑向图：Style 8

产品图标覆盖

内建 40+ 品牌色图标，省去手动找 logo 的功夫：

• AI/ML：OpenAI、Anthropic/Claude、Google Gemini、Meta LLaMA、Mistral、Cohere、Groq、Hugging Face
• AI 框架：Mem0、LangChain、LlamaIndex、LangGraph、CrewAI、AutoGen、DSPy、Haystack
• 向量库：Pinecone、Weaviate、Qdrant、Chroma、Milvus、pgvector、Faiss
• 数据库：PostgreSQL、MySQL、MongoDB、Redis、Elasticsearch、Neo4j、Cassandra
• 消息：Kafka、RabbitMQ、NATS、Pulsar
• 云：AWS、GCP、Azure、Cloudflare、Vercel、Docker、Kubernetes
• 可观测性：Grafana、Prometheus、Datadog、LangSmith、Langfuse、Arize

十一、与 Mermaid、draw.io 的定位差异

	Mermaid	draw.io	fireworks-tech-graph
自然语言输入	✗	✗	✅
AI/Agent 领域图式	✗	✗	✅
多视觉风格	✗	手动	✅ 内建 12 种
高分辨率 PNG 导出	✗	手动	✅ 自动 1920px
语义化箭头配色	✗	手动	✅ 自动
无需在线工具	✅	✗	✅

这张表容易被误读成「谁更强」，实际上三者服务的是不同环节。

Mermaid 的优势在于源码内联：它和代码住在同一个仓库、同一份 Markdown 里，改代码顺手改图，diff 可读。做 README 里的小流程图，它依然是最省事的选择。

draw.io 的优势在于最终控制权：需要逐像素调整的正式交付物，人手拖拽仍然不可替代。

fireworks-tech-graph 瞄准的是中间那段最痛的距离------你脑子里有一个系统，需要马上得到一张能直接放进文档、README 或幻灯片的成品图，既不想学 DSL，也不想在 GUI 里点半小时。它的输出是 SVG，所以后续仍可以扔进 draw.io 或 Figma 做最后微调，这条退路是通的。

十二、排错手册

常见问题基本集中在渲染环节：

症状	原因	处理
PNG 全空白或全黑	SVG 里有 @import url()，cairosvg 和 rsvg-convert 都无法抓取外部字体	去掉 @import，改用系统字体栈
PNG 没生成	没装渲染器	python3 -m pip install cairosvg，或 brew install librsvg / apt install librsvg2-bin
PNG 里边框或文字缺失	用 rsvg-convert 渲染含 CSS 的 SVG	换 cairosvg，CSS 支持强得多
图底部被裁掉	viewBox 高度不够	调大 viewBox="0 0 960 ..." 的高度值
文字溢出方框	标签太长	加 text-anchor="middle" 或缩短标签

第一条尤其值得记住：在需要脚本化渲染的 SVG 里永远不要写 @import。浏览器能拿到字体，无头渲染器拿不到，结果就是一片空白。项目本身遵守了这条约束------所有输出使用纯内联 SVG，不做外部字体请求，因此在 cairosvg、rsvg-convert 和无头 Chrome 下都能干净渲染。

十三、可迁移的方法论

抛开画图这个具体场景，这个项目沉淀了四条对任何 AI 工程都成立的经验。

第一，把风格与规范写进代码，而不是写进文档。 只写在 Markdown 里的规范，人和模型都会漂移；编码进生成器的规范才有约束力。这也是为什么「executable style system」这个说法比「style guide」更准确。

第二，让模型产出中间表示，而不是最终格式。 直接生成 SVG/HTML/SQL 这类最终产物，校验面积极小，出错难以定位。加一层带 schema 的 IR，重复 ID、悬空引用、非有限数值这些问题就能在渲染前拦下来。

第三，验收必须分两级：确定性检查在前，感知检查在后。 语法正确不等于视觉正确------箭头可以合法地穿过组件内部，标签可以合法地压在生命线上。只有把导出的位图读回来检查，才能捕获这一类缺陷。同样重要的是：读不了图就诚实地报 skipped，而不是假装通过。

第四，反馈循环必须有界。 默认最多两轮定向修正，既避免过早收工，也避免模型陷入无休止的自我编辑。每轮只改被诊断出的部分，而不是整体重写------这一点同时保证了收敛速度与可解释性。

第四条尤其容易被低估。很多 agent 工具的失败模式不是「做不好」，而是「不知道什么时候算做完」。给出可观测的终态（validation: passed / visual_review: passed）加上明确的迭代上限，这个问题就变成了工程问题而非玄学问题。

十四、边界与适用范围

讲清楚它不做什么，同样重要。

技能定义里明确排除了三类内容：照片、栅格美术作品、以及定量数据图表 。也就是说，柱状图、折线图、散点图这类需要精确映射数值的可视化不在服务范围内------那是 matplotlib、ECharts 或 D3 的领域。它处理的是结构与关系 的可视化，不是数量的可视化。

动效方面同样有硬边界：只接受生成的语义 SVG 作为输入，拒绝栅格动画输入与非 GIF 的动效输出；同一风格的任意拓扑并不都被支持，只有满足已批准契约的才通过。

其他需要注意的现实约束：

• 依赖 Codex 或 Claude Code 这类支持 Agent Skill 的运行时，不是独立可用的 CLI 工具链
• 视觉复核依赖运行时的读图能力，缺失时会降级
• 对比矩阵最多 5 列，超过就得拆成两张图
• 流程图节点标签建议不超过 3 个词，细节放子标签
• Style 8 是 AI 自主排版 + 静态回归 fixture，与其余 11 种生成器驱动的风格机制不同

十五、结语

把这个项目仅仅看作「AI 画图工具」，会错过它真正的价值。

它真正做的事情，是给一个长期被当作主观审美问题的领域，装上了软件工程的那一整套基础设施：schema、validator、契约、回归 fixture、CI 门禁、有界迭代、可观测终态。图不再是「画完了」，而是「通过了」。

这套思路的适用面远不止画图。任何 AI 生成结构化产物的场景------生成配置、生成 SQL、生成前端组件、生成测试用例------都面临同一个核心问题：如何在没有人类逐项检查的前提下，判断一次生成是否可交付。答案不是把模型换得更大，而是把「可交付」拆解成一组机器能判定的条件，然后让模型在这些条件的约束下迭代收敛。

下一次你在设计文档前卡住半小时排版一张架构图时，可以换个角度想想：真正该被自动化的，不是画线这个动作，而是「这张图对不对」这个判断。

---

项目地址 ：github.com/yizhiyanhua-ai/fireworks-tech-graph · MIT 协议