Fireworks 技术图谱

它解决什么问题

给系统画技术图，多半要手写 SVG：矩形对不齐、标签压住连接线、箭头穿过组件内部、<marker> 引用忘了定义。语法上能过，渲染出来是错的，而且这类错误靠静态检查很难提前发现。Fireworks Tech Graph 把生成和校验绑在一起：每张图都要过 XML 语法、标签配平、marker 引用、属性完整性、路径数据这些关卡，最后再把导出的 PNG 读回来做一遍视觉复查。

核心能力与流程

SKILL.md 是共享入口，Codex 和 Claude Code 都能直接跑。执行任何脚本前先解析出 SKILL_ROOT：Claude Code 用 ${CLAUDE_SKILL_DIR}，Codex 用技能元数据里的绝对路径，不要假设 cwd 就是技能目录，也不要假设上一条 shell 的变量还留着。

生成走一条固定顺序：

1. 先分类图表类型（架构、数据流、流程图、Agent、记忆、时序、对比矩阵、时间线/甘特、思维导图、类图、用例图、状态机）
2. 抽取结构：层、节点、边、数据流、语义分组
3. 按类型规则规划布局，viewBox 有对应默认值
4. 载入 references/style-1-flat-icon.md，除非用户指定其他样式；样式 1-12 各有独立色板
5. 选语义契约（c4-review、cloud-fabric、event-transit、ops-pulse），工程事实缺失或矛盾直接 fail closed
6. 写 SVG，再跑 scripts/validate-svg.sh
7. 导出 PNG（推荐 cairosvg）
8. 需要动图时按 references/motion-effects.md 跑 fireworks.py animate
9. 视觉复查门：把 PNG 读回来看，箭头是否穿内部、标签是否压生命线、图例是否遮挡。最多两轮修正，然后回报 visual_review: passed 或 skipped；读不了图就明说跳过，不要猜

辅助脚本都在 scripts/ 下：generate-diagram.sh 校验并导出 PNG，generate-from-template.py 从模板生成起始 SVG 并自动转义文本，test-all-styles.sh 批量测试所有样式并出报告。复杂图建议一律走脚本。

边界与注意点

• 样式指导不能用来为不可读文字、缺失 marker、箭头穿内部开脱，几何关卡始终生效
• 动图只输出 GIF，默认 5.75s / 20fps / 960px，帧 38-109 全不透明、110-114 复位；拒绝栅格输入和其他动图格式
• 只有 12 套 motion contract 获批，不要声称任意同风格拓扑都支持
• 对比矩阵最多 5 列可读，超出就拆成两张
• 优先级顺序：用户明确的内容和样式要求 > 样式 token > 布局默认值