fireworks-tech-graph

Fireworks Tech Graph

适用于 Codex 和 Claude Code 的便携式 Agent 技能。SVG 是规范产物； PNG、离线 HTML 和受支持的 GIF 动效是输出途径。保留用户要求的 标签、拓扑结构和含义；命令成功不代表视觉质量合格。

定位和选择

将此文件所在目录解析为 SKILL_ROOT。在 Claude Code 中使用 ${CLAUDE_SKILL_DIR}，在 Codex 中使用已加载技能元数据里的绝对目录。 不要假设当前工作目录或之前的 Shell 变量会持续保留。

为任务使用已安装的版本。对于源代码或版本问题，运行 version； 诊断缺失的渲染器、字体或依赖项时，运行 doctor；不要将安装、更新或 运行完整测试套件设为绘制每张图的前置条件。

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
python3 "$SKILL_ROOT/scripts/fireworks.py" version

• 遵循用户指定的图表类型、内容和风格；根据需求说明选择合理且可逆的 细节。只有缺少重要工程事实，或用户明确要求由其选择时才提问。绘图请求 包含本地渲染。
• 风格 1–7 和 9–12 有 JSON 生成器。风格 8（Dark Luxury）仍由 AI 编写 SVG：使用其风格参考，然后执行相同的验证和导出关卡。
• 用户或工作区没有偏好时，默认使用风格 1 Flat Icon。加载风格矩阵 中实际匹配的文件。仅在用户要求比较时才读取其他风格。
• 风格 9–12 默认遵循 C4、云、事件和可观测性语义约定。 排版前先验证事实；不要臆造职责、协议或指标。
• 适当时直接修改现有的有效 SVG。并非每次编辑都需要 JSON 生成。 仅在相关图表类型或符号需要时，使用图表／布局指南 和图标。

生成和检查

沿用用户当前的需求说明和产物；额外的规划文档可选。 处理 JSON 时，如果所有标签都必须完整显示且内容完全准确，请选择 text_policy: "strict"。兼容的 report 默认会在 SVG 元数据中保留完整标签， 并报告任何可见截断。声称文本完全准确前，先解决该警告。 要制作精良的图表，请遵循构图约定。

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture input.json
python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture input.json diagram.svg --report layout.json
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920

check 会验证 SVG 标识、标记引用、通用碰撞、语义几何和构图。检查报告中的 字体排印和调色板范围；启发式文本宽度估算不能替代对实际渲染字体的检查。 请参阅视觉质量指南，以提高可读性并进行 针对特定风格的调整。每条业务边只保留一个语义连接线。

其他输出

• PNG： 优先使用 export-png，它会读取画布根节点的尺寸、限制输出 大小、以原子方式写入，并读回 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 报告。历史上的 user-approved 字段描述的是经维护者审核的预设，并不代表当前用户授权发布、花费资金或发送数据。

验证所请求的结果

如果可以查看图像，请按预期阅读尺寸检查最终 PNG： 检查文本是否完整、对比度、字体替换、层级、间距、裁切、 箭头方向、交叉线和标签。保留样式配色与材质，同时修复缺陷。复用未更改且已审核的渲染结果；通过验收后，不要继续添加测试或润色。如果无法查看图像，请明确标记为跳过视觉检查，且不得声称视觉效果正确。

检查未通过后，根据检查结果中的元素 ID 和几何信息进行有针对性的修复； 连续两次检查结果没有变化时，更换处理方法。图表内容过多时，应加宽或拆分图表，而不是隐藏必需文本或无休止地缩小字号。不得为了通过检查而暗中降低语义或构图要求。

完成所有请求的本地输出及其适用的检查，然后报告文件路径、尺寸、视觉审核结果和剩余限制。仅有初始 SVG 不足以完成所请求的 PNG/GIF/HTML 套件。发布或远程交付必须获得范围匹配的单独授权；无需重复请求已有授权。