Fireworks Tech Graph 是一个可移植的 Agent Skill，面向 Codex 与 Claude Code，用于创建精确的 SVG 技术图表，并导出 PNG 或离线 HTML，同时可将受支持的语义 SVG 动画化为 GIF。其核心定位是：SVG 是规范产物，PNG、离线 HTML 和受支持的 GIF 动态是输出途径。
用途与适用场景 可承载架构图、UML、Agent、云等图表类型（名称中的“…”表示资料未完整列出）。强调保留用户要求的标签、拓扑与含义，并提示“成功执行命令并不等于视觉质量合格”。
定位与选择 需要将包含本文件的目录解析为 SKILL_ROOT：在 Claude Code 中使用 ${CLAUDE_SKILL_DIR}，在 Codex 的已加载 skill 元数据中使用绝对目录。不要假设 cwd 或之前的 shell 变量会持续存在。使用已安装版本执行任务；版本来源问题运行 version，诊断缺失渲染器、字体或依赖时运行 doctor；不把安装、更新或完整测试套件作为每张图表的先决条件。
风格与生成 风格 1–7 与 9–12 有 JSON 生成器；风格 8（Dark Luxury）仍由 AI 撰写 SVG，使用其风格参考，再经过相同的验证与导出关卡。无用户或工作区偏好时默认使用风格 1 Flat Icon。从风格矩阵加载实际匹配文件，仅在需要比较时读取其他风格。风格 9–12 默认使用 C4、cloud、event 与 observability 语义契约。布局前先验证事实，不虚构职责、协议或指标。适当时可直接改编已有有效 SVG；并非每次编辑都需要 JSON 生成。
生成与检查 复用用户当前的需求与产物，额外的规划文档是可选的。JSON 工作中，当所有标签必须精确可见时选择 text_policy: "strict"；兼容报告默认在 SVG 元数据中保留完整标签并报告任何可见截断，在声称完整精确文本前应解决该警告。精致作品需应用 composition 契约。check 会验证 SVG 身份、标记引用、通用冲突、语义几何与 composition。检查报告的排版与配色范围；启发式文本宽度不能替代对实际渲染字体的检查。保留每个业务边一个语义连接器。
附加输出 PNG：优先使用 export-png，它读取根画布尺寸、限制输出大小、原子写入并回读 PNG 尺寸。HTML：fireworks.py export-html diagram.svg diagram.html，生成一个经过清理的离线文件，提供平移/缩放、源码复制与静态图片下载。GIF：当用户说“Generate a GIF”“Animate this diagram”“生成 GIF”“制作 GIF”“让这张图动起来”时，选择已有语义 SVG 的动态路线。风格 1–12 已为文档化的场景契约启用；不承诺任意同风格拓扑。加载动效并运行 fireworks.py animate diagram.svg diagram.gif，默认 960px、20fps、5.75s，使用 +2s-settled-flow 预设并生成 .motion.json 报告。历史用户批准字段描述的是维护者审阅过的预设，而非当前用户发布、花费或发送数据的授权。
验证结果 在可用时按预期阅读尺寸检查最终 PNG：文本完整性、对比度、字体替换、层级、间距、裁切、箭头方向、交叉与标签。在修复缺陷的同时保留风格配色与材质。在通过验收后复用未更改的已审阅渲染，不要继续增加测试或打磨。若无法查看，明确标记视觉检查已跳过，且不声称视觉正确。
失败处理 检查失败后，利用其元素 ID 与几何信息进行聚焦修复；两次相同失败未解决问题后改变方法。扩大/拆分过满的图表，而不是隐藏必需文案或无限缩小字号。不要为了让结果通过而暗中削弱语义或 composition 约束。
完成与限制 完成所有要求的本地输出及其适用检查后，报告文件路径、尺寸、视觉审阅与遗留限制。一个初始 SVG 并不构成完整的 PNG/GIF/HTML 交付包。发布或远程交付需要其自身范围匹配的授权；已有授权不会被二次请求。