Fireworks Tech Graph v1.1.0 工程化版本深度解析:语义契约、几何安全路由与统一 CLI

原创2026-09-22 23:25:021,640 阅读
文章标签:AI 技能数据可视化开发工具图表库人工智能代码生成

Fireworks Tech Graph v1.1.0 工程化版本深度解析:语义契约、几何安全路由与统一 CLI

导读

本篇文章围绕 docs/releases/v1.1.0.md 发布说明展开,深入剖析 Fireworks Tech Graph 从"能出图的绘图技能"升级为"工程级图表系统"的关键技术落地:新增 Style 9–12 四个工程化风格及其可执行语义契约、几何安全正交路由与 fail-closed 组合门禁、版本化 Diagram IR 与统一 CLI、离线交互式 HTML 导出,以及完整的嵌套 Agent Skill 分发与校验和归档。读完本文,你将理解这套系统如何保证"渲染通过 = 语义与构图双双达标",并掌握用统一 CLI 完成 validate → render → check → export-html 全链路操作的实战方法。

版本定位:一次把 12 种风格统一到同一质量契约下的工程化发布

v1.1.0 的核心主张是:在保留全部 12 种风格差异化视觉语言的同时,把项目改造成一个 engineering-grade 图表系统。此前 v1.0.x 仅具备结构化 SVG 校验能力(见 CHANGELOG.md 中 1.0.5 的"Codex metadata, Style 8 reference assets, and structural SVG validation"),而 v1.1.0 一次性补齐了四块地基:

  1. 四个"工程优先"风格(Style 9–12)及各自可执行语义契约;
  2. 几何安全路由 + 构图质量契约(composition-quality contract);
  3. 版本化 Diagram IR(schema v1)与统一 CLI;
  4. 可复现发布产物(嵌套 Skill、tgz/zip 归档、SHA256SUMS)。

12 种风格各自对应一个独立工程场景的官方画廊

画廊刷新是本次发布对外可见度最高的变化:官方画廊从 8 个场景扩充到 12 个独立工程场景,每个风格配固定宽度 1920px 的回归渲染图(静态基线保存在 assets/samples/),保证风格对比可复现。

新增的四个工程化风格与其语义契约

v1.1.0 的关键创新在于:Style 9–12 不是"换皮",而是为每种工程场景定义了可执行语义契约——图表在进入布局渲染之前,必须先通过领域语义校验,否则直接失败(fail closed)。语义契约的完整实现位于 scripts/semantic_contracts.py,四个校验器分别对应四个 profile,且每个风格在 scripts/semantic_contracts.py 中绑定默认 profile(STYLE_DEFAULT_PROFILES:9→c4-review、10→cloud-fabric、11→event-transit、12→ops-pulse)。

Style 9 · C4 Review Canvas(c4-review)

面向 C4 context / container / component 视图的评审画布,用于 ADR 与设计评审。其契约(实现于 _validate_c4,见 scripts/semantic_contracts.py)要求:

  • diagram_type: "c4",且必须且只能声明一个 c4_level(context/container/component);
  • 必须提供 scope、title、整数 rough_seed 和非空 legend;
  • 每个节点必须携带 c4_type、label、description;container/component 节点还必须给出 technology,且卡片尺寸至少 170×96;
  • 每条关系必须有 label 和显式 protocol;
  • 禁止混层:在 container 视图中放入 component 节点会直接触发 C4_MIXED_ABSTRACTION 错误;引用未知 boundary parent 会触发 C4_PARENT 错误;节点越出所属边界 20px 内衬会触发 C4_BOUNDARY_ESCAPE。

rough_seed 的设计颇具巧思:它在不破坏几何的前提下生成稳定的"铅笔复描"装饰层——装饰元素带 data-graph-role="decoration" 标记,语义边始终只有一条普通的正交路径,装饰不会参与路由计算,因此同一个 seed 可跨运行产出字节级一致的 SVG。完整视觉 token 与签名清单见 references/style-9-c4-review-canvas.md,可复用的示例 fixture 为 fixtures/c4-review-canvas-style9.json(一个确定性 seed、100 分 showcase 构图得分的结账容器评审)。

Style 10 · Cloud Fabric(cloud-fabric)

面向多区域 / VPC / 网络归属的部署拓扑视图,回答"它运行在哪里",而不是贴满厂商图标。契约(_validate_cloud,scripts/semantic_contracts.py)要求:

  • diagram_type: "deployment",platform_profile 限定为 provider-neutral/aws/azure/gcp/kubernetes;
  • icon_manifest_version 必须与内置清单一致(当前为 2026.07-neutral.1,清单位于 assets/icons/cloud/manifest-v1.json),版本不匹配直接触发 CLOUD_ICON_VERSION;
  • 至少一个 deployment_kind: "region" 的边界(否则 CLOUD_BOUNDARY);
  • 每个节点必须声明 deployment_id 与 manifest 支持的 icon_id,未知 icon 触发 CLOUD_ICON_UNKNOWN——绝不虚构厂商服务 logo;
  • 跨 deployment 的边必须给出非空 via(如 peering、transit gateway、service mesh)。

边界语义上还有一组硬约束:边界 parent 必须构成无环树(CLOUD_BOUNDARY_CYCLE)、嵌套深度上限 4 层(CLOUD_BOUNDARY_DEPTH)、子边界相对父边界至少内衬 16px、节点相对所属 deployment 至少内衬 20px、同级边界间距至少 16px。校验通过后,运行时会自动为节点补全 icon_badge、icon_color、glyph、deployment_path 等派生字段。示例见 fixtures/cloud-fabric-style10.json(双区域 active-active 结账部署)。完整说明见 references/style-10-cloud-fabric.md。

Style 11 · Event Transit(event-transit)

用"地铁图"隐喻事件驱动系统:Topic 是轨道、处理步骤是站点、声明的 junction 是分支点、死信(DLQ)有独立可见的路线。契约(_validate_event,scripts/semantic_contracts.py)要求:

  • diagram_type: "event_stream",1–4 个 Topic,每个 Topic 必须有唯一 id 与 color;
  • 每个节点声明 transit_role(producer/station/junction/consumer/dlq/state_store),station/junction 必须有 operation,consumer 必须有 consumer_group;
  • rail 边必须是同一 Topic 上 station_order 连续递增的两个节点,共享同一条水平中心线(误差 ≤ 1e-6,否则 EVENT_RAIL_ALIGNMENT),站点间距至少 64px(EVENT_RAIL_LENGTH),且必须使用 right→left 端口(EVENT_RAIL_PORT);
  • dead_letter 边必须指向真实 dlq 节点;分支边只能从 junction 出发;同一节点出现多条 rail 出边而它又不是 junction 时触发 EVENT_BRANCH_JUNCTION。

语义轨道使用 ≤2.8px 描边与固定 user-space 箭头,保证箭头不随线宽缩放。示例见 fixtures/event-transit-style11.json,完整视觉契约见 references/style-11-event-transit.md。

Style 12 · Ops Pulse(ops-pulse)

面向事故复盘与可靠性评审的视图,融合服务拓扑、四个黄金信号、一条关键请求路径与关联的 trace 瀑布。契约(_validate_ops,scripts/semantic_contracts.py)是四个 profile 中最严格的:

  • diagram_type: "observability",1–12 个 ops_role: "service" 节点;
  • 每个服务必须恰好声明 latency、traffic、errors、saturation 四个信号(多一个少一个都触发 OPS_GOLDEN_SIGNALS),每个信号必须有 value、unit、window、status,且 window 必须与整图 observation_window 一致(OPS_OBSERVATION_WINDOW);
  • 服务卡片至少 180×108 且带可见 status_label;
  • critical_path 必须是非空的有序业务边 id 列表:不允许重复边、不允许 telemetry 边混入、必须连续(不连续触发 OPS_CRITICAL_PATH)、不允许重复访问服务节点;校验通过后运行时自动为关键边打上 critical、critical_hop、critical_hops 标记;
  • business 边与 telemetry 边必须使用不同 flow token(OPS_FLOW_SEMANTICS);
  • trace 必须存在(OPS_TRACE_REQUIRED),span id 唯一,duration 为正,子 span 必须被父 span 的时间窗口完全覆盖(OPS_SPAN_COVERAGE),整棵瀑布有且仅有一个根 span(OPS_SPAN_ROOT),并且每个 span 的 x/width 必须精确编码其 start_ms/duration_ms 在根时间尺度上的位置(OPS_SPAN_SCALE)。

示例见 fixtures/ops-pulse-style12.json(四个服务卡片 + OTel collector + 四 span 关联 trace 的降级结账路径),视觉契约见 references/style-12-ops-pulse.md。

profile 的解析与别名路由

语义 profile 不是手工配置在 JSON 里的唯一途径——运行时会先从 style / visual_theme 选择器解析风格(resolve_style_index,支持数字、英文名、中文别名如 C4 评审画布、事件地铁图、可靠性脉冲,见 scripts/semantic_contracts.py),再通过 PROFILE_ALIASES 把自然语言提示词(kafka、otel、cloud landing zone map 等)归一化到对应 profile(scripts/semantic_contracts.py)。风格与主题声明冲突(如 style: 9 同时 visual_theme: 10)会直接报 STYLE_SELECTOR_CONFLICT——这些行为在 tests/test_semantic_contracts.py 中有对应用例覆盖。

几何安全路由与组合质量契约

v1.1.0 的另一半地基是构图门禁。所有官方风格共享同一份 references/composition-quality-contract.md,它定义了 showcase 档位的可量化预算:

指标 Showcase 上限
边交叉(Edge crossings) 0
桥跳(Bridge jumps) 0
单边弯折(Bends on one edge) ≤ 2
六节点参考拓扑总弯折 ≤ 8
路由长度 / 曼哈顿直线长度 ≤ 1.35
最短路由段 ≥ 16px
节点间距 ≥ 40px
节点到容器内衬(gutter) ≥ 20px
边标签与无关几何的最小间距 ≥ 4px

文档同时给出布局语法九条规则(references/composition-quality-contract.md):先定容器与节点行再布线、同行节点对齐同一 y、预留层间走廊、主水平流先布、多边共享一侧时使用不同端口且禁止箭头堆叠同一坐标、优先单调正交路由、把标题/图例/页脚都视为有界的障碍物、图例避开业务走廊、长标题必须适配卡片宽度。官方参考拓扑当前得 100 分:4 个总弯折、0 交叉、0 桥跳、路由拉伸最大值 1.0、50px 节点间距、20px 容器 gutter。

v1.1.0 引入的路由能力还包括:正交路由(deterministic orthogonal routing)、端口扇出(port fan-out)、必经点校验(waypoint validation)、标签与保留区域检查(label/reserved-region checks)、交叉桥接掩码(bridge masks)以及图例自动搬迁(legend relocation)。风格身份边界在此处被明确隔离:风格可以自由变背景、配色、字体、卡片质感、圆角与品牌细节,但必须共享拓扑、方向、端口分配、走廊位置以及全部弯折/间距预算——这正是"12 个风格可横向对比"的结构性前提。装饰层(铅笔复描、轨道外壳、关键路径辉光)一律使用 data-graph-role="decoration" + data-owner,绝不允许产生第二条业务连接线。

版本化 Diagram IR:输入先归一化再渲染

在语义契约之上,v1.1.0 增加了版本化中间表示(Diagram IR)。实现位于 scripts/diagram_ir.py:normalize_diagram 把历史 JSON 形状归一化到 schema v1,产出类型化的 DiagramIR(内含 NodeIR、EdgeIR 不可变数据类),并在此阶段完成数值有限性、重复 ID、悬空引用、畸形 waypoint、非有限几何等检查——任何一项不通过都会在任何布局代码运行前失败。schema 定义见 schemas/architecture-v1.schema.json 等四个版本化 JSON Schema(architecture / diagram / sequence / workflow)。语义校验结果(style、visual_theme、profile、details)会被记录到 semantic_report 并贯穿渲染与校验流程。

统一 CLI:validate → render → check → export-html

v1.1.0 将零散的脚本入口收敛为一个统一 CLI:scripts/fireworks.py,子命令由 scripts/fireworks.py 的 build_parser 定义:

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

# 环境体检:python/cairosvg/rsvg-convert/node/ffmpeg/motion 渲染器
python3 "$SKILL_ROOT/scripts/fireworks.py" doctor

# 校验并归一化 JSON(schema v1 + 语义契约 + 风格解析)
python3 "$SKILL_ROOT/scripts/fireworks.py" validate architecture "$SKILL_ROOT/fixtures/api-flow-style7.json"

# 渲染 SVG,并输出确定性布局报告
python3 "$SKILL_ROOT/scripts/fireworks.py" render architecture "$SKILL_ROOT/fixtures/api-flow-style7.json" diagram.svg --report layout.json

# 对 SVG 产物做结构化校验(默认 xml/markers/geometry/composition)
python3 "$SKILL_ROOT/scripts/fireworks.py" check diagram.svg

# 导出单文件离线交互式 HTML
python3 "$SKILL_ROOT/scripts/fireworks.py" export-html diagram.svg diagram.html --title "Agent Runtime Architecture"

# 查看 SVG 内嵌语义元数据(data-generator / schema-version / style-id / roles)
python3 "$SKILL_ROOT/scripts/fireworks.py" inspect diagram.svg

各子命令的行为与边界在 scripts/fireworks.py 中值得注意的几点:

  • validate 与 render 走同一条"渲染边界":Style 8(Dark Luxury)是 AI 手写风格,JSON 校验会被拒绝,因为根本不存在对应的 JSON 渲染路径(见 scripts/fireworks.py 与 tests/test_semantic_contracts.py 的测试);
  • render 的 --report 会生成确定性布局报告(JSON),让路由与间距结果可审计、可回归;
  • check 支持 --check 指定单个门(xml/markers/collisions/geometry/composition);
  • export-html 输出单个离线文件:净化 SVG、内置平移/缩放/重置、明暗主题切换、SVG 源码复制,以及 1×–4× 的 SVG/PNG/JPEG/WebP 下载能力(实现位于 scripts/interactive_html.py,示例产物见 examples/interactive-architecture.html)。

examples 子命令可直接列出仓库内置 fixture:

python3 "$SKILL_ROOT/scripts/fireworks.py" examples

语义 SVG 元数据与双重校验门

渲染产物不只是"画对",还要"可审计"。生成的 SVG 根元素会写入 data-generator、data-schema-version、data-style-id、data-visual-theme、data-diagram-type、data-semantic-profile、data-semantic-valid 等语义元数据,inspect 子命令可一键读取;元素级的 data-graph-role 让验证器能区分语义边与装饰层。

交付前的双门禁可直接用脚本执行:

python3 scripts/validate_svg.py diagram.svg --check geometry
python3 scripts/validate_svg.py diagram.svg --check composition

scripts/validate-svg.sh 会自动依次执行两者;scripts/validate_svg.py 是 XML、marker、transform、路径碰撞等检查的实现主体(v1.1.0 之后还修复了多子路径几何与 transform 边界问题,见 docs/releases/v1.2.0.md)。正如 references/composition-quality-contract.md 所强调:"一次成功渲染而没有跑这些门,仍然只是草稿。"

分发与兼容性:嵌套 Agent Skill 与可校验归档

v1.1.0 的发布工程化同样完整:

  • 嵌套 Agent Skill:仓库内提供完整可用的物理镜像 skills/fireworks-tech-graph/,包含 scripts、schemas、fixtures、templates、tests、references 与元数据,可用 npx skills add 直接安装到 Codex(~/.agents/skills)与 Claude Code(~/.claude/skills),Codex 的 UI 元数据见 agents/openai.yaml;
  • 可复现归档:发布附带 tgz/zip 压缩包与 SHA256SUMS 校验文件,配合 CI、归档一致性检查与隔离安装 canary(见 tools/ 与 tests/test_skill_compatibility.py)保证产物可复现、可验证;
  • 兼容性基线:Node.js 18+ 为运行时下限;Python 源码按 3.9 语法检查,CI 同时在 Python 3.9 与 3.12 上跑测试套件;npm registry 是独立分发渠道,可能滞后于 GitHub Release,当前 Skill 以嵌套 GitHub 路径为准。

从 v1.1.0 到 v1.2.0:这条工程化路径的延续

需要指出的是,v1.1.0 是"静态工程图"的基线,其语义契约、IR 与 CLI 骨架在后续版本被完整复用:v1.2.0(见 docs/releases/v1.2.0.md)在此之上新增了聚焦的 SVG-to-GIF 语义动效管线——12 个风格的动效契约同样"用户批准"、默认 5.75s/115 帧 settled-flow 时间线,并继续复用 v1.1.0 的语义拓扑、路由角色、stage、几何与风格签名作为"允许变体"的钉扎依据,而不是钉死源 SVG 字节。这说明 v1.1.0 确立的"语义驱动 + 可执行门禁"架构具有可扩展性,而非一次性补丁。

上手路径小结

  1. 通读四份风格契约:references/style-9-c4-review-canvas.md、references/style-10-cloud-fabric.md、references/style-11-event-transit.md、references/style-12-ops-pulse.md,理解每个 profile 的必填字段;
  2. 直接以 fixtures/ 下的对应 JSON 为模板改出自己的图,用 python3 scripts/fireworks.py validate architecture <your.json> 先过语义门;
  3. render 出 SVG 后用 check 过结构化门,再 export-html 得到可交付的离线交互页面;
  4. 如需静态 1920px PNG 基线,参考 references/png-export.md 的渲染器选择(cairosvg 推荐 / rsvg-convert 备选 / puppeteer 高保真路径)。

这套"先语义、后几何、再渲染"的三段式门禁,正是 v1.1.0 最值得借鉴的工程范式:它让 AI 生成的图表从"看起来像"变成了"可验证地正确"。

登录后查看全文
fireworks-tech-graph