fireworks-tech-graph 中文教程：先固定 v1.2.0，再做结构和视觉两轮检查
fireworks-tech-graph 是给 Codex 和 Claude Code 使用的技术制图 Skill，也提供 Python CLI。它把描述转成结构化 IR，再生成 SVG、PNG、离线 HTML 或带验证报告的 GIF。当前稳定版是 v1.2.0。
1. 安装前先核对归档
Release 提供 tgz/zip 和 SHA256SUMS。下载后先校验，再把归档中的 nested skills/fireworks-tech-graph 复制到代理技能目录。另一种做法是 clone 后检出固定 tag；不要在生产环境直接执行浮动版本的 npx -y 安装。
sha256sum -c SHA256SUMS
# 固定 tag 的 Git 路径
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git
git -C fireworks-tech-graph checkout v1.2.02. 静态图和 GIF 的依赖不同
| 输出 | 需要 |
|---|---|
| SVG、离线 HTML | Python 3.9+ |
| PNG | CairoSVG，或 rsvg-convert |
| GIF 动画 | Chrome/Chromium、puppeteer-core 25.3.0、FFmpeg/FFprobe |
先只安装静态路径。浏览器和媒体工具扩大供应链与运行面，只有明确需要动画时再加。
3. 先运行 version 和 doctor
SKILL_ROOT="$HOME/.agents/skills/fireworks-tech-graph"
python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" doctorversion 会报告包版本、实际 Skill 根目录和可用 Git 状态；doctor 会区分基础 SVG/HTML、PNG 和 GIF 路径。把输出放进项目日志，避免不同代理读取到不同副本。
4. 用官方 fixture 跑完整静态链
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"validate 检查 schema 和工程语义，render 生成图并写布局报告，check 再检查 SVG 结构、画布、标签和连线。每一步失败都应停止，不要把出图当作通过。
5. 自动校验后必须打开图片
人工检查标题、节点文字、方向、关键关系、颜色含义、裁切、重叠和阅读顺序。官方 v1.2.0 会在运行时缺少读图能力时写出 visual_review: skipped (image reader unavailable)。这是一条诚实的状态，不是通过结果。
6. GIF 是一条独立验收链
v1.2.0 的默认 GIF 为 960px、5.75 秒、20fps 和 115 个帧中心采样。工具会输出 motion.json，并检查阶段、方向、DOM、像素与媒体属性。内容可以变，但场景拓扑和运动契约不能随意改变。简单演示不需要承担这套依赖与验收成本。
7. 和 Mermaid 怎么选
相比 Mermaid，fireworks-tech-graph 更强调固定视觉样式、几何检查、高分辨率导出和动画报告；Mermaid 使用可读 DSL，适合直接放进 Markdown、文档站和代码审查。结构关系要轻量维护时选 Mermaid，需要成品插图或受检动画时再用本项目。
8. 商业推广与流量判断
官方 README 有 AIGoCode 赞助广告，包含订阅宣传、专属邀请链接和首次充值 10% 赠额，属于明显商业漏斗。教程只讲开源本地路径，不引导充值。
9. 验证状态与边界
验证边界：未验证布局、SVG/PNG/HTML/GIF、几何规则、852 次兼容比较、像素阈值和最终视觉质量。命令来自官方文档，需要在固定版本与隔离目录中实际运行。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
它把自然语言画图从单次生成升级为结构化 IR、确定性布局、几何校验、导出和报告链，并在 v1.2.0 为 12 种样式加入可验证的 SVG 到 GIF 动画契约。
适合谁用
适合生成架构评审图、云部署图、事件流、可靠性排查图、UML 和技术文档插图，并用检查报告做版本回归。简单 Markdown 内联关系图用 Mermaid 更轻；需要自由拖拽和人工排版时，draw.io 更合适。
采用建议
需要可重复的高分辨率技术插图和严格导出检查时，这个 Skill 有明确价值。先固定 v1.2.0、从静态 SVG 跑通 fixture，再按需求增加 PNG 或 GIF 依赖；把自动校验当作审图辅助，最终内容和可读性仍由人确认。
原教程未展开的系统信息
核心功能
版本化 Diagram IR
生成器先校验节点、边、端口和领域字段，再进入布局；重复 ID、悬空引用、非法 waypoint 与非有限坐标会提前失败。
几何和语义校验
检查画布、标签、保留区域、边交叉、端口扇出和特定工程样式契约，失败时不继续合成。
多格式离线导出
CLI 可生成 SVG、PNG 和单文件交互 HTML；HTML 在本地提供缩放、主题、复制及多种位图下载。
受约束的 GIF 动画
v1.2.0 为 12 个场景定义时间线、方向、阶段、几何和像素探针，输出 motion.json 验证报告。
架构与数据流
Skill 先把描述映射到样式与领域结构，再由 schemas 和 IR 校验器规范化输入。Python 生成器执行布局、正交路由、端口与标签检查，输出语义 SVG 和 layout report；PNG 由 CairoSVG、rsvg-convert 或浏览器路径渲染。交互导出对 SVG 做清理后打包成单一 HTML。可选动画路径使用 Chromium/Puppeteer 逐帧渲染，FFmpeg 合成，再用 FFprobe、DOM/签名/像素探针和 motion report 验收。
常见问题
fireworks-tech-graph 当前应该安装哪个版本？
当前稳定 Release 是 v1.2.0。官方说明 npm registry 仍停在 1.0.4，因此应使用 v1.2.0 Release 归档或固定 tag 下的 nested Skill 路径，并核对 SHA256SUMS。
只生成 SVG 也需要安装 Chromium 和 FFmpeg 吗？
不需要。静态 SVG 和离线 HTML 使用 Python 工具链；PNG 需要 CairoSVG 或 rsvg-convert。Chromium、Puppeteer、FFmpeg/FFprobe 只用于可选的 GIF 动画路径。
validation: passed 是否等于图已经好看？
不等于。结构和几何校验能发现悬空引用、越界、交叉等问题，但视觉判断仍需要读图。没有图像读取能力时，工具会报告 visual_review: skipped，不能把它写成已完成视觉复核。
README 的充值赠额赞助链接是运行必需的吗？
不是。赞助商推广与本地 Skill、Python CLI、CairoSVG、Puppeteer 或 FFmpeg 安装没有技术依赖。