fireworks-tech-graph Documentation

Technical Documentation: yizhiyanhua-ai/fireworks-tech-graph

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

English | 中文

Release history · Changelog

fireworks-tech-graph

Stop drawing diagrams by hand. Describe your system in English or Chinese — get geometry-safe SVG, PNG, focused SVG-to-GIF motion, and offline interactive technical diagrams.

Output quality Copy Chapter

The current checkout adds complete-text reporting and stronger supporting text across the default themes. Add "text_policy": "strict" to reject visible truncation before output is written; reports preserve the full source label and explain how to recover. Chinese descriptions use the available second line. See visual quality for theme-specific guidance and measurement limits.

python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920

version reports the package, actual Skill root and Git state when available. doctor distinguishes SVG/HTML support from optional PNG/GIF dependencies. PNG export checks the root canvas, bounds image size, writes atomically and reads the resulting pixel dimensions back. The browser PNG exporter remains available for Chromium fidelity. The showcase GIFs below are the published 1.2.0 references; this unreleased upgrade preserves their motion contracts.

Overview Copy Chapter

fireworks-tech-graph is one Agent Skill that works unchanged in Codex and Claude Code. It turns natural language descriptions into polished, geometry-checked SVG diagrams, high-resolution PNGs, validated SVG-to-GIF semantic motion, and offline interactive HTML. The focused animation path accepts a generated semantic SVG and emits one compact, probed GIF. It ships with 11 generator-backed styles and 1 AI-authored style (Dark Luxury). Four engineering-first styles add executable contracts for C4 reviews, cloud deployments, event streams, and reliability investigations, alongside deep AI/Agent domain patterns and all 14 UML diagram types.

User: "Generate a Mem0 memory architecture diagram, dark style"
  → Skill classifies: Memory Architecture Diagram, Style 2
  → Generates SVG with swim lanes, cylinders, semantic arrows
  → Exports 1920px PNG
  → Reports: mem0-architecture.svg / mem0-architecture.png

Sponsors Copy Chapter

Interested in becoming a sponsor? Contact: [email protected]

Work With the Builder Copy Chapter

This project is also a proof surface for a broader capability: turning vague AI/devtool workflows into constrained, reusable systems with validation, documentation, export paths, and product-facing polish.

If you are building agent infrastructure, AI IDEs, internal copilots, developer tools, technical documentation systems, or applied AI workflow products, I am open to scoped paid sprints, design-partner work, and founding engineer conversations.

• Founder-facing profile: https://bradzhang.dev/en
• Commercial case study: https://bradzhang.dev/en/case-studies/fireworks-tech-graph
• Work with me: https://bradzhang.dev/en/work-with-me

Showcase Copy Chapter

The animated previews use the user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960px wide at 20fps / 115 frames; the 3×4 overview is an optimized 1200px preview. Lossless 1920px PNGs remain in assets/samples/ as static regression baselines.

The v1.2.0 overview above and every full-size animated sample below come from the approved regression set. Each style keeps a distinct scenario while sharing the same geometry, text-fit, wire-routing, and semantic-motion quality gates.

Style 1 — Flat Icon (default) Copy Section

Mem0 Memory Architecture — personal-memory extraction, conflict resolution, storage, and retrieval

Style 2 — Dark Terminal Copy Section

Tool Call Flow — dark terminal execution, source grounding, retrieval, and answer synthesis

Style 3 — Blueprint Copy Section

Microservices Architecture — engineering grid, domain services, data stores, events, and telemetry

Style 4 — Notion Clean Copy Section

Agent Memory Types — minimal hierarchy from sensory and working context to durable memory

Style 5 — Glassmorphism Copy Section

Multi-Agent Collaboration — coordinator, specialists, shared state, review, and synthesis

Style 6 — Claude Official Copy Section

System Architecture — warm interface, runtime, safety, memory, tools, and operations layers

Style 7 — OpenAI Official Copy Section

API Integration Flow — clean SDK, prompt, model, tool, delivery, and release stages

Style 8 — Dark Luxury *(AI-authored)* Copy Section

Agent Runtime Architecture — control plane, execution and state layers, champagne-gold structure, semantic color buckets

Style 9 — C4 Review Canvas Copy Section

Checkout Container Review — one abstraction level, explicit responsibilities, technologies, and protocols

Style 10 — Cloud Fabric Copy Section

Active–Active Checkout Deployment — global ingress, regions, VPC ownership, and cross-region replication

Style 11 — Event Transit Copy Section

Checkout Event Line — topics as rails, processors as stations, a declared junction, DLQ, and state projection

Style 12 — Ops Pulse Copy Section

Checkout Reliability Pulse — golden signals, one critical path, OTel export, and a correlated trace

Stable Prompt Recipe Copy Chapter

The public showcase keeps a distinct domain scene for every style. They remain comparable because every fixture passes the same executable composition contract. A same-topology regression set remains internal under fixtures/quality-baseline/.

Draw the scenario assigned to style N:
1 Mem0 Memory Architecture; 2 Tool Call Flow; 3 Microservices Architecture;
4 Agent Memory Types; 5 Multi-Agent Collaboration; 6 System Architecture;
7 API Integration Flow; 8 Agent Runtime Architecture; 9 C4 Checkout Review;
10 Active–Active Cloud Deployment; 11 Checkout Event Line; 12 Checkout Reliability Pulse.
Preserve the scenario-specific nodes, sections, and reading direction.
Apply the showcase composition contract: zero crossings, zero bridge jumps, at most two bends per edge,
at most eight bends overall, at least 40px between nodes, at least 20px container gutter,
short orthogonal segments, and labels kept clear of nodes, routes, and section headers.
Preserve the selected style's typography, palette, card material, and brand details.

For the four engineering-first styles, use one of these prompt fingerprints so
the router selects the domain contract as well as the visual theme:

Style 9 · C4 review board: show one C4 level, responsibilities, technologies, review state, and relationship protocols.
Style 10 · Multi-region deployment map: show global ingress, Region/VPC ownership, neutral cloud glyphs, deployment mode, and named boundary mechanisms.
Style 11 · Event metro map: show thin topic rails, numbered processor stations, declared junctions, consumer groups, DLQ, and state projections.
Style 12 · Reliability pulse: show one observation window, four golden signals per service, numbered critical hops, telemetry export, and one correlated trace.

Replace N with 1–12. Style 8 remains AI-authored and loads references/style-8-dark-luxury.md; Styles 9–12 also enforce their engineering semantic contract. All styles load references/composition-quality-contract.md.

Features Copy Chapter

• 12 visual styles — 11 generator-backed profiles + 1 AI-authored style (Dark Luxury)
• Engineering semantic contracts — C4 abstraction levels, deployment ownership, event-rail topology, and exact golden signals fail closed before rendering
• Executable style system — style guides are encoded into the generator, not only documented in markdown
• Shared composition-quality contract — every official style enforces zero crossings/bridges, ≤2 bends per edge, route-stretch, spacing, gutter, micro-segment, and label-clearance budgets
• 14 diagram types — Full UML support (Class, Component, Deployment, Package, Composite Structure, Object, Use Case, Activity, State Machine, Sequence, Communication, Timing, Interaction Overview, ER Diagram) plus AI/Agent domain diagrams
• AI/Agent domain patterns — RAG, Agentic Search, Mem0, Multi-Agent, Tool Call, and more built-in
• Semantic shape vocabulary — LLM = double-border rect, Agent = hexagon, Vector Store = ringed cylinder
• Semantic arrow system — color + dash pattern encode meaning (write vs read vs async vs loop)
• Geometry-safe routing — deterministic orthogonal routes, exact waypoints, distinct ports, automatic legend relocation, labels kept inside the canvas, and verified bridge jumps for unavoidable crossings
• Versioned diagram IR — legacy JSON normalizes to schema v1; duplicate IDs, dangling references, malformed waypoints, and non-finite geometry fail before rendering
• Structured SVG validation — XML and marker integrity plus semantic node, reserved-region, label, canvas, edge-overlap, and edge-crossing checks
• Unified CLI + interactive export — render, validate, inspect, and export one offline HTML file with pan/zoom, themes, copy, and SVG/PNG/JPEG/WebP output up to 4×
• Focused semantic GIF motion — generated SVG in, validated GIF out; connectors begin absent and draw in semantic order. All twelve style contracts are user-approved. The shared +2s-settled-flow timing revision is also user-approved, so the default 5.75s/115-frame loop holds full settled flow on frames 38–109, then resets on 110–114
• Visual review gate — exported PNGs are inspected for clipping, overlap, label placement, and routing regressions before delivery
• Product icons — 40+ products with brand colors: OpenAI, Anthropic, Pinecone, Weaviate, Kafka, PostgreSQL…
• Swim lane grouping — automatic layer labeling for complex architectures
• SVG + PNG output — SVG for editing, 1920px PNG for embedding
• Renderer-friendly — pure inline SVG, no external font fetching; renders cleanly in cairosvg, rsvg-convert, and headless Chrome

Loop Engineering Copy Chapter

The first render is treated as a candidate, not an automatic final result. fireworks-tech-graph uses an agent-driven, bounded validation feedback loop to move each diagram toward a verified deliverable:

Prompt
  → Diagram Contract
  → Semantic IR
  → Style Spec
  → Route Planner
  → SVG Build
  → Structural Validation
  → PNG Visual Readback
  → Targeted Revision
  → Verified SVG + PNG

The loop follows five design principles:

1. Evaluate, don't assert — completion is backed by validator and render evidence, not by the model saying the diagram looks correct.
2. Deterministic checks first — XML structure, marker integrity, path geometry, arrow-component collisions, and renderability are checked before visual judgment.
3. Perceptual validation second — the exported PNG is read back to inspect clipping, label collisions, hierarchy, whitespace, and routing quality that syntax checks cannot see.
4. Targeted correction — each pass changes only the diagnosed labels, coordinates, corridors, or spacing, then reruns validation and rendering.
5. Bounded convergence — visual review allows at most two focused correction passes by default, preventing an unbounded self-editing loop.

The loop is observable in the final status:

validation: passed
visual_review: passed

If the runtime cannot read images, the skill reports visual_review: skipped (image reader unavailable) explicitly. The workflow remains bounded and auditable; it does not claim visual verification without image evidence.

Installation Copy Chapter

Recommended: install the complete skill for both runtimes Copy Section

Use the real nested skill path. The final /skills/fireworks-tech-graph segment is required because a bare repository install can select only the root SKILL.md in current versions of skills CLI.

npx -y [email protected] add \
  yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy

This creates complete copies at ~/.agents/skills/fireworks-tech-graph for Codex and ~/.claude/skills/fireworks-tech-graph for Claude Code, including scripts, schemas, fixtures, templates, tests, references, and metadata.

Editable Git checkout for Codex Copy Section

mkdir -p ~/.agents/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph

Codex discovers personal skills from ~/.agents/skills and reads the optional agents/openai.yaml metadata included in this repository.

Editable Git checkout for Claude Code Copy Section

mkdir -p ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

Claude Code discovers personal skills from ~/.claude/skills and ignores the Codex-only UI metadata.

One editable checkout shared by Codex and Claude Code Copy Section

For a fresh install with Claude Code 2.1.203 or newer, keep one checkout and link both discovery paths to it. Move any existing destinations aside before creating the links.

mkdir -p ~/.local/share/agent-skills ~/.agents/skills ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph

This keeps SKILL.md, references, scripts, templates, and future updates identical in both agents. The npm registry is a separate distribution channel and may lag GitHub Releases. For the current Skill version, use the nested GitHub path above; the npm page remains available for package metadata:

https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph

Update Copy Chapter

For a skills CLI copy, rerun the recommended nested-path command. For Git installations, update whichever checkout you installed:

git -C ~/.agents/skills/fireworks-tech-graph pull
# or
git -C ~/.claude/skills/fireworks-tech-graph pull
# or, for the shared checkout
git -C ~/.local/share/agent-skills/fireworks-tech-graph pull

After the first install, restart Codex and Claude Code so both discover the skill. Later SKILL.md edits are detected automatically; restart the runtime after changing bundled scripts or references if the update is not visible.

The shell commands above target macOS, Linux, WSL, and Git Bash. On native Windows, use the equivalent %USERPROFILE%\.agents\skills and %USERPROFILE%\.claude\skills paths. Python 3.9+ is required; the optional Puppeteer path requires Node.js 22.12+.

Unified CLI Copy Chapter

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

python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
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"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

The HTML export is one offline file. It sanitizes the SVG, adds pan/zoom/reset, light and dark themes, SVG source copy, and SVG/PNG/JPEG/WebP downloads at 1×–4×.

For motion, say “Generate a GIF”, “Animate this diagram”, 生成 GIF, 制作 GIF, or 让这张图动起来. The command accepts a generated semantic SVG that carries one of the twelve approved motion contracts. Exact source bytes are not pinned, so validated title and content variants of a supported topology work; missing or changed role/stage/order coverage, route direction, required colors, or geometry fails closed. GIF is the only motion media format, and the default command also writes <output>.motion.json as its verification report. The approved default is 960px, 5.75 seconds, 20fps, and 115 frame-center samples. All twelve scenes start connector-free, draw routes on frames 1–36, fade live flow on 36–38, hold full settled flow on 38–109, and reset on 110–114. Their approved identities include the packet heads, terminal evidence trace, Blueprint registration beads, 14×10 Notion memory cards, and the eight scene-specific signatures listed below. Default packages report both the style contract and shared +2s-settled-flow timing revision as user-approved. Timelines of 75 frames or fewer remain all-unique. Longer timelines allow non-adjacent repeated rasters inside the full-opacity interval; frame 110 is the sole boundary exception because its unchanged reset opacity is exactly 1.00, and such evidence is classified as intentional_reset_boundary_repeat. Frames 111–114 remain globally distinct. Long timelines require at least 75 unique rasters and forbid adjacent duplicates. The all-style 75-vs-115 gate counts binary-exact and decoded-RGBA-exact frames separately; compositor-only fallback is accepted only at AE ≤ 128, normalized RMSE ≤ 0.001, with components no thicker than 2px and confined to edge or node borders. DOM and signature geometry remain strict-exact. Explicit 3.75s/75-frame and 2.75s/55-frame calls remain supported. See Focused SVG-to-GIF Motion.

Requirements Copy Chapter

The bundled SVG/PNG scripts require cairosvg (recommended) or rsvg-convert. Optional SVG-to-GIF export requires FFmpeg/FFprobe, Chrome/Chromium, and puppeteer or puppeteer-core.

# Recommended: cairosvg (best CSS support)
python3 -m pip install cairosvg

# Fallback: rsvg-convert (system package; may drop CSS / <foreignObject>)
brew install librsvg                   # macOS
sudo apt install librsvg2-bin          # Ubuntu/Debian

# Optional semantic motion export. Install beside every copied Skill because the
# renderer intentionally does not load modules from the caller's directory.
brew install ffmpeg                    # macOS; use your system package manager elsewhere
for SKILL_ROOT in \
  "$HOME/.agents/skills/fireworks-tech-graph" \
  "$HOME/.claude/skills/fireworks-tech-graph"
do
  [ -d "$SKILL_ROOT" ] || continue
  npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false [email protected]
  python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
done

# Verify either supported script renderer
python3 -c "import cairosvg; print(cairosvg.__version__)"
rsvg-convert --version

Why Not Mermaid or draw.io? Copy Chapter

Mermaid is great for quick inline diagrams in markdown. draw.io is great for manual polishing. fireworks-tech-graph is optimized for describing a system and getting a polished diagram immediately, without writing DSL syntax or clicking around a GUI.

Usage Copy Chapter

Trigger phrases Copy Section

The skill auto-triggers on:

generate diagram / draw diagram / create chart / visualize
architecture diagram / flowchart / sequence diagram / data flow
Generate a GIF / animate this diagram / animate this SVG as a GIF / 生成 GIF / 制作 GIF / 让这张图动起来 / 把刚才的 SVG 转成 GIF

Basic usage Copy Section

Draw a RAG pipeline flowchart

Generate an Agentic Search architecture diagram

Specify style Copy Section

Draw a microservices architecture diagram, style 2 (dark terminal)

Draw a multi-agent collaboration diagram --style glassmorphism

Specify output path Copy Section

Generate a Mem0 architecture diagram, output to ~/Desktop/

Create a tool call flow diagram --output /tmp/diagrams/

Example Prompts by Scenario Copy Chapter

AI/Agent Systems Copy Section

Compare Agentic RAG vs standard RAG in a feature matrix, Notion clean style

→ Comparison matrix: RAG vs Agentic RAG, covering retrieval strategy, agent loop, tool use

Generate a Mem0 memory architecture diagram with vector store, graph DB, KV store, and memory manager

→ Memory Architecture with swim lanes: Input → Memory Manager → Storage tiers → Retrieval

Draw a Multi-Agent diagram: Orchestrator dispatches 3 SubAgents (search / compute / code execution), results aggregated

→ Agent Architecture with hexagons, tool layers, and result aggregation

Visualize the Tool Call execution flow: LLM → Tool Selector → Execution → Parser → back to LLM

→ Flowchart with decision loop showing tool invocation cycle

Draw the 5 agent memory types: Sensory, Working, Episodic, Semantic, Procedural

→ Mind map or layered architecture showing memory tiers from sensory to procedural

Infrastructure & Cloud Copy Section

Draw a microservices architecture: Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL + Redis

→ Architecture diagram with horizontal layers, swim lanes per service cluster

Generate a data pipeline diagram: Kafka → Spark processing → write to S3 → Athena query

→ Data flow diagram with labeled arrows (stream / batch / query)

Draw a Kubernetes deployment: Ingress → Service → [Pod × 3] → ConfigMap + PersistentVolume

→ Architecture with dashed containers per namespace, solid arrows for traffic flow

API & Sequence Flows Copy Section

Draw an OAuth2 authorization code flow sequence diagram: User → Client → Auth Server → Resource Server

→ Sequence diagram with vertical lifelines and activation boxes

Draw the ChatGPT Plugin call sequence diagram

→ Sequence: User → ChatGPT → Plugin Manifest → API → Response chain

Decision & Process Flows Copy Section

Draw a pre-launch QA flowchart for an AI app: Code Review → Security Scan → Performance Test → Manual Approval → Deploy

→ Flowchart with diamond decision nodes and parallel branches

Generate a feature comparison matrix: RAG vs Fine-tuning vs Prompt Engineering

→ Comparison matrix with checked/unchecked cells across cost, latency, accuracy, flexibility

Concept Maps Copy Section

Visualize the LLM application tech stack: from foundation model to SDK to app framework to deployment

→ Layered architecture or mind map from model layer to product layer

Draw an AI Agent capability map: Perception / Memory / Reasoning / Action / Learning

→ Mind map with central "AI Agent" node and 5 radial branches

12 Styles Copy Chapter

Each style has a dedicated reference file in references/ with exact color tokens and SVG patterns. Styles 1–7 and 9–12 are generator-backed; Style 8 uses AI-authored composition plus a static regression fixture.
The generator consumes structure fields such as containers, semantic nodes[].kind, arrows[].flow, and explicit port anchors. Styles 9–12 additionally validate domain-specific fields before layout.

Useful high-leverage fields for style-specific polish:

• style_overrides to nudge title alignment or palette tokens without forking a full style
• containers[].header_prefix / containers[].header_text for blueprint-style numbered section headers such as 01 // EDGE
• containers[].side_label for Claude-style left layer labels
• window_controls, meta_left, meta_center, meta_right for terminal / document chrome
• blueprint_title_block for engineering title boxes in style 3

Style Selection Guide Copy Section

For UML Diagrams:

• Class/Component/Package: Style 1 (Flat Icon) or Style 4 (Notion Clean) — clear structure, easy to read
• Sequence/Timing: Style 2 (Dark Terminal) — monospace fonts help with alignment
• State Machine/Activity: Style 3 (Blueprint) — engineering aesthetic fits process flows
• Use Case/Interview: Style 1 (Flat Icon) — colorful, accessible

For AI/Agent Diagrams:

• RAG/Agentic Search: Style 2 (Dark Terminal) or Style 5 (Glassmorphism) — tech-forward aesthetic
• Memory Architecture: Style 3 (Blueprint) — emphasizes layered storage tiers
• Multi-Agent: Style 5 (Glassmorphism) — frosted cards distinguish agent boundaries

For Documentation:

• Internal docs: Style 4 (Notion Clean) — minimal, wiki-friendly
• Blog posts: Style 1 (Flat Icon) — colorful, engaging
• GitHub README: Style 2 (Dark Terminal) — matches dark theme
• Presentations: Style 5 (Glassmorphism) or Style 6 (Claude Official) — polished

For Engineering Reviews:

• C4/ADR review: Style 9 (C4 Review Canvas) — one declared abstraction level with responsibilities and protocols
• Cloud deployment review: Style 10 (Cloud Fabric) — explicit region/network ownership and cross-boundary mechanisms
• Event-driven system review: Style 11 (Event Transit) — topic rails, processors, consumer groups, state, and DLQ
• Reliability/incident review: Style 12 (Ops Pulse) — golden signals, one critical path, and a correlated trace

Brand-Specific:

• Anthropic/Claude projects: Style 6 (Claude Official) — warm cream background, brand colors
• OpenAI projects: Style 7 (OpenAI Official) — clean white, OpenAI palette
• Premium editorial diagrams: Style 8 (Dark Luxury) — deep black canvas, champagne-gold hierarchy, semantic color buckets

Diagram Types Copy Chapter

UML Diagram Support (14 Types) Copy Section

AI/Agent Domain Patterns Copy Chapter

Built-in pattern knowledge:

RAG Pipeline         → Query → Embed → VectorSearch → Retrieve → LLM → Response
Agentic RAG          → adds Agent loop + Tool use
Agentic Search       → Query → Planner → [Search/Calc/Code] → Synthesizer
Mem0 Memory Layer    → Input → Memory Manager → [VectorDB + GraphDB] → Context
Agent Memory Types   → Sensory → Working → Episodic → Semantic → Procedural
Multi-Agent          → Orchestrator → [SubAgent×N] → Aggregator → Output
Tool Call Flow       → LLM → Tool Selector → Execution → Parser → LLM (loop)

Shape Vocabulary Copy Chapter

Shapes encode semantic meaning consistently across all styles:

Arrow Semantics Copy Chapter

File Structure Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Product Icon Coverage Copy Chapter

AI/ML: OpenAI, Anthropic/Claude, Google Gemini, Meta LLaMA, Mistral, Cohere, Groq, Hugging Face

AI Frameworks: Mem0, LangChain, LlamaIndex, LangGraph, CrewAI, AutoGen, DSPy, Haystack

Vector DBs: Pinecone, Weaviate, Qdrant, Chroma, Milvus, pgvector, Faiss

Databases: PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Neo4j, Cassandra

Messaging: Kafka, RabbitMQ, NATS, Pulsar

Cloud: AWS, GCP, Azure, Cloudflare, Vercel, Docker, Kubernetes

Observability: Grafana, Prometheus, Datadog, LangSmith, Langfuse, Arize

Troubleshooting Copy Chapter

License Copy Chapter

MIT © 2025 fireworks-tech-graph contributors

Overview (`examples/README.md`) Copy Section

Interactive example

Open interactive-architecture.html directly in a browser. It is a single offline file generated from fixtures/api-flow-style7.json and contains no remote runtime dependencies.

Regenerate it with:

tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
tmp_svg="$tmp_dir/api-flow.svg"
python3 scripts/fireworks.py render architecture fixtures/api-flow-style7.json "$tmp_svg"
python3 scripts/fireworks.py export-html "$tmp_svg" examples/interactive-architecture.html --title "API Integration Flow" --slug api-integration-flow

Overview (`scripts/README.md`) Copy Section

Fireworks Tech Graph - Scripts

辅助脚本集合，用于提高 SVG 图表生成的稳定性和效率。

脚本列表 Copy Chapter

1. validate-svg.sh Copy Section

SVG 验证脚本，检查 SVG 语法并报告详细错误。

用法：

./validate-svg.sh <svg-file>

检查项目：

• XML 结构、属性语法和实体转义（使用 XML parser，避免把 top_k=5 之类的文本误判为属性）
• marker-start / marker-mid / marker-end 引用完整性
• 箭头与组件碰撞（支持绝对/相对 M/L/H/V/Q/C/S/T 路径，曲线路径采样检测）
• 渲染验证（cairosvg 优先，rsvg-convert 兜底）

示例：

./validate-svg.sh /path/to/diagram.svg

2. generate-diagram.sh Copy Section

SVG 图表生成脚本，提供自动验证和 PNG 导出。

用法：

./generate-diagram.sh [OPTIONS]

选项：

• -t, --type TYPE - 图表类型（见脚本帮助）
• -s, --style STYLE - 风格编号（1-12，默认：1）
• -o, --output PATH - 输出路径（默认：当前目录）
• -w, --width WIDTH - PNG 宽度（像素，默认：1920）
• --no-validate - 跳过验证
• -h, --help - 显示帮助

示例：

# 生成架构图（Style 1）
./generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

# 生成流程图（Style 2，2400px 宽）
./generate-diagram.sh -t flowchart -s 2 -w 2400

注意： SVG 内容需要先准备好；这个脚本只负责验证与导出。

3. generate-from-template.py Copy Section

基于风格配置和 JSON 数据生成 SVG。当前版本不再只是简单塞入 nodes/arrows，
而是会执行 style guide 中的部分可计算规则，例如：

• style - 风格编号（1-12）或规范风格名
• semantic_profile - 可选语义契约；Style 9-12 默认分别启用 C4、云部署、事件流和可观测性契约
• containers - 泳道 / 分组容器
• containers[].header_prefix / containers[].header_text - 工程编号式分区标题
• containers[].side_label - 左侧 layer label
• nodes[].kind - 语义组件类型，例如 double_rect、cylinder、document、terminal、circle_cluster
• arrows[].flow - 语义箭头类型，例如 control、write、read、data
• source_port / target_port - 指定端口锚点
• route_points / corridor_x / corridor_y - 控制复杂图的走线质量
• style_overrides - 对现有 style 做局部覆盖
• window_controls / meta_* - 顶部终端 chrome
• blueprint_title_block - 工程蓝图右下角 title block

用法：

python3 ./generate-from-template.py architecture ./output/arch.svg '{"style":1,"title":"My Diagram","containers":[],"nodes":[],"arrows":[]}'

示例：

python3 ./generate-from-template.py memory ./output/mem0.svg '{
  "style": 1,
  "title": "Mem0 Memory Architecture",
  "containers": [
    {"x":30,"y":90,"width":900,"height":90,"label":"Input Layer","header_prefix":"01"}
  ],
  "nodes": [
    {"id":"manager","kind":"double_rect","x":360,"y":220,"width":300,"height":72,"label":"Memory Manager"},
    {"id":"vector","kind":"cylinder","x":90,"y":360,"width":140,"height":110,"label":"Vector Store"}
  ],
  "arrows": [
    {"source":"manager","target":"vector","flow":"write","dashed":true}
  ]
}'

4. test-all-styles.sh Copy Section

批量测试脚本覆盖 12 种风格。Style 1-7 与 9-12 从 JSON fixture 生成，AI 手绘的 Style 8 使用静态 SVG fixture；任何风格缺少回归 fixture 都会使批测失败。

用法：

./test-all-styles.sh

功能：

• 检查所有风格的参考文件
• 渲染 fixtures/*.json 回归样例
• 验证生成出的 SVG 文件
• 导出 PNG 文件到 test-output/ 目录
• 生成测试报告

输出：

• 测试摘要（通过/失败统计）
• PNG 文件（带时间戳）
• 详细的验证错误信息

示例：

./test-all-styles.sh

依赖 Copy Chapter

所有脚本需要至少一个 PNG 渲染器（推荐 cairosvg）：

• cairosvg（推荐）- SVG 转 PNG，CSS 支持最好

  bash Copy

  python3 -m pip install cairosvg

• rsvg-convert（备选）- 系统包；复杂 SVG 可能丢失 CSS / <foreignObject>

  bash Copy

  brew install librsvg                # macOS
  sudo apt install librsvg2-bin       # Ubuntu/Debian

generate-diagram.sh 会优先调用 cairosvg，缺失时自动回退到 rsvg-convert。完整对比见 PNG 导出参考。

聚焦后的语义动效由 fireworks.py animate、motion.py 和 svg2gif.js 协作完成，只接收带有 12 套已验收 role/stage/order 契约之一的生成器语义 SVG。精确源文件字节不锁定，但任意同风格拓扑不会自动套用动效。媒体输出只允许经过验证的 GIF，默认还会生成同名 .motion.json 报告。运行时需要 FFmpeg/FFprobe、Chrome/Chromium，以及 Skill 安装位置可解析到的 puppeteer 或 puppeteer-core；当前工作目录中的同名模块不会被隐式执行。依赖安装与最简命令：

for SKILL_ROOT in \
  "$HOME/.agents/skills/fireworks-tech-graph" \
  "$HOME/.claude/skills/fireworks-tech-graph"
do
  [ -d "$SKILL_ROOT" ] || continue
  npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false [email protected]
done
SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

默认自动识别风格，输出 5.75 秒、20fps、960px 宽、115 帧无限循环 GIF。第 1–36 帧保持既有 draw-on，第 36–38 帧淡入运行流，第 38–109 帧为完整稳定数据流，第 110–114 帧按 [1,.7575,.515,.2725,.03] reset。Style 1–12 的 signature、速度、路径、几何和构建合同均为 user-approved，包括 persistent-data-flow-head、terminal-evidence-stream、blueprint-registration-bead、14×10 notion-memory-card、glass-task-capsule、policy-seal、token-train、gem-tracer、review-cursor、region chevrons、event train 与 ops scanner；共享 +2s-settled-flow 时间修订也已于 2026-07-17 验收，默认新包的 review_status 为 user-approved。显式 3.75 秒/75 帧和 2.75 秒/55 帧继续支持。75 帧及以下要求全部 raster 唯一；更长时间线允许非相邻重复出现在 full-opacity 区间，frame 110 是 reset opacity 为 1.00 的唯一例外并分类为 intentional_reset_boundary_repeat，frame 111–114 必须全局不同；至少保留 75 个唯一 raster 且相邻重复数为零。75-vs-115 gate 分开统计 binary / decoded-RGBA / guarded-antialias 三类；guarded 等价要求 AE ≤ 128、normalized RMSE ≤ 0.001、component 宽或高不超过 2px 且只落在 edge/node border，DOM 和 signature geometry 仍 strict-exact。完整约束见 动效参考。

• grep, sed, awk - 文本处理（macOS 自带）

目录结构 Copy Chapter

fireworks-tech-graph/
├── SKILL.md                    # Skill 主文档
├── references/                 # 风格参考文件
│   ├── style-1-flat-icon.md
│   ├── style-2-dark-terminal.md
│   └── ...
├── fixtures/                   # 回归测试样例（JSON）
│   ├── mem0-style1.json
│   ├── tool-call-style2.json
│   └── ...
├── scripts/                    # 辅助脚本（本目录）
│   ├── README.md              # 本文档
│   ├── validate-svg.sh        # SVG 验证
│   ├── generate-diagram.sh    # SVG 验证与 PNG 导出
│   ├── generate-from-template.py # 模板化生成 SVG
│   ├── motion.py              # SVG 转 GIF 校验、编码与原子报告
│   ├── svg2gif.js             # Chromium 手动时间轴逐帧渲染
│   └── test-all-styles.sh     # 批量测试
└── test-output/               # 测试输出目录（自动创建）

使用场景 Copy Chapter

场景 1：验证现有 SVG Copy Section

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
# SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
"$SKILL_ROOT/scripts/validate-svg.sh" /path/to/your-diagram.svg

场景 2：生成并验证图表 Copy Section

1. 使用 Codex 或 Claude Code 生成 SVG 内容
2. 运行验证和导出：
   bash Copy

   SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
   # SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
   "$SKILL_ROOT/scripts/generate-diagram.sh" -t architecture -s 1 -o ./output/arch.svg

场景 3：批量测试所有风格 Copy Section

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
# SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
"$SKILL_ROOT/scripts/test-all-styles.sh"

测试脚本会自动：

1. 读取 ../fixtures/*.json
2. 按 template_type + style 调用 generate-from-template.py
3. 运行 validate-svg.sh
4. 导出 PNG 到 ../test-output/

场景 4：validator 单元测试 Copy Section

python3 -m unittest discover -s tests -p 'test_validate_svg.py' -v

覆盖 marker 双端引用、文本等号、H/V 路径、曲线路径、虚线组件和容器排除等正反例。

对启发式难以区分的形状，可显式添加 data-graph-role="node|container|legend|decoration|label|background"。node 会强制纳入障碍物检测，其余角色会从组件障碍物中排除；legend 组内的示例箭头也不会被当作业务流。

查看测试输出：

ls -lh ../test-output/

故障排除 Copy Chapter

问题：找不到 PNG 渲染器 Copy Section

解决方案（任选其一，推荐 cairosvg）：

python3 -m pip install cairosvg        # 推荐
brew install librsvg                   # macOS 系统包
sudo apt install librsvg2-bin          # Ubuntu/Debian

问题：rsvg-convert 渲染缺框/缺文字 Copy Section

原因： rsvg-convert 对 <foreignObject>、CSS filter、复杂 <style> 块支持有限。

解决方案： 切换到 cairosvg：

python3 -m pip install cairosvg

脚本会自动优先使用 cairosvg。如果仍需要像素级还原（例如浏览器生成的 SVG），按 PNG 导出参考 使用 svg2png.js。

问题：权限被拒绝 Copy Section

解决方案：

chmod +x *.sh

问题：SVG 验证失败 Copy Section

解决方案：

1. 查看详细错误信息
2. 使用 Edit 工具修复语法错误
3. 重新运行验证

开发说明 Copy Chapter

添加新的验证规则 Copy Section

编辑 validate-svg.sh，在现有检查项后添加新的检查逻辑：

# Check N: Your new check
echo -n "Checking something... "
# Your validation logic here
if [ condition ]; then
    echo -e "${GREEN}✓ Pass${NC}"
else
    echo -e "${RED}✗ Fail${NC}"
fi

扩展支持的图表类型 Copy Section

编辑 generate-diagram.sh，在 --type 参数处理中添加新类型。

版本历史 Copy Chapter

• v1.2.0 (2026-07-17) - 语义动效与动态展示
  • 12 种已验收的 SVG→GIF 场景动效与 5.75 秒 settled-flow 默认时间线
  • README 全动态图集、GIF manifest、媒体回读与安装副本全风格门禁
  • 动效源 SVG 保持语义契约约束，不绑定标题和内容字节
• v1.1.0 (2026-07-15) - 几何与分发升级
  • Schema v1 与类型化 Diagram IR
  • 正交路由、端口分流、图例/标签避让、跨线桥与确定性布局报告
  • fireworks.py 统一 CLI 与离线交互 HTML 导出
  • 完整 npx Skill 镜像、CI、Release archive parity 与安装 canary
• v1.0.0 (2026-04-11) - 初始版本
  • SVG 验证脚本
  • 图表生成脚本
  • 批量测试脚本

许可证 Copy Chapter

MIT License - 与 fireworks-tech-graph skill 相同

Overview (`docs/releases/README.md`) Copy Section

Release history

This directory is the source of truth for the curated GitHub Release notes. Version dates describe when each version originally became available, not when a historical GitHub Release page was backfilled.

Historical provenance Copy Chapter

GitHub Release pages for v1.0.0 through v1.0.5 were backfilled on 2026-07-17. The npm packages were sometimes published from a working tree immediately before its matching commit: npm 1.0.2, 1.0.3, and 1.0.4 retain the preceding gitHead, while their complete published file sets match the subsequent commits shown in the Tag commit column. No fully committed tree reproduces every packaging change in npm 1.0.0 or 1.0.1; those tags use the registry source anchor, and their notes state the limitation.

Overview (`skills/fireworks-tech-graph/README.md`) Copy Section

English | 中文

Release history · Changelog

fireworks-tech-graph

Stop drawing diagrams by hand. Describe your system in English or Chinese — get geometry-safe SVG, PNG, focused SVG-to-GIF motion, and offline interactive technical diagrams.

Output quality Copy Chapter

The current checkout adds complete-text reporting and stronger supporting text across the default themes. Add "text_policy": "strict" to reject visible truncation before output is written; reports preserve the full source label and explain how to recover. Chinese descriptions use the available second line. See visual quality for theme-specific guidance and measurement limits.

python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920

version reports the package, actual Skill root and Git state when available. doctor distinguishes SVG/HTML support from optional PNG/GIF dependencies. PNG export checks the root canvas, bounds image size, writes atomically and reads the resulting pixel dimensions back. The browser PNG exporter remains available for Chromium fidelity. The showcase GIFs below are the published 1.2.0 references; this unreleased upgrade preserves their motion contracts.

Overview Copy Chapter

fireworks-tech-graph is one Agent Skill that works unchanged in Codex and Claude Code. It turns natural language descriptions into polished, geometry-checked SVG diagrams, high-resolution PNGs, validated SVG-to-GIF semantic motion, and offline interactive HTML. The focused animation path accepts a generated semantic SVG and emits one compact, probed GIF. It ships with 11 generator-backed styles and 1 AI-authored style (Dark Luxury). Four engineering-first styles add executable contracts for C4 reviews, cloud deployments, event streams, and reliability investigations, alongside deep AI/Agent domain patterns and all 14 UML diagram types.

User: "Generate a Mem0 memory architecture diagram, dark style"
  → Skill classifies: Memory Architecture Diagram, Style 2
  → Generates SVG with swim lanes, cylinders, semantic arrows
  → Exports 1920px PNG
  → Reports: mem0-architecture.svg / mem0-architecture.png

Sponsors Copy Chapter

Interested in becoming a sponsor? Contact: [email protected]

Work With the Builder Copy Chapter

This project is also a proof surface for a broader capability: turning vague AI/devtool workflows into constrained, reusable systems with validation, documentation, export paths, and product-facing polish.

If you are building agent infrastructure, AI IDEs, internal copilots, developer tools, technical documentation systems, or applied AI workflow products, I am open to scoped paid sprints, design-partner work, and founding engineer conversations.

• Founder-facing profile: https://bradzhang.dev/en
• Commercial case study: https://bradzhang.dev/en/case-studies/fireworks-tech-graph
• Work with me: https://bradzhang.dev/en/work-with-me

Showcase Copy Chapter

The animated previews use the user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960px wide at 20fps / 115 frames; the 3×4 overview is an optimized 1200px preview. Lossless 1920px PNGs remain in assets/samples/ as static regression baselines.

The v1.2.0 overview above and every full-size animated sample below come from the approved regression set. Each style keeps a distinct scenario while sharing the same geometry, text-fit, wire-routing, and semantic-motion quality gates.

Style 1 — Flat Icon (default) Copy Section

Mem0 Memory Architecture — personal-memory extraction, conflict resolution, storage, and retrieval

Style 2 — Dark Terminal Copy Section

Tool Call Flow — dark terminal execution, source grounding, retrieval, and answer synthesis

Style 3 — Blueprint Copy Section

Microservices Architecture — engineering grid, domain services, data stores, events, and telemetry

Style 4 — Notion Clean Copy Section

Agent Memory Types — minimal hierarchy from sensory and working context to durable memory

Style 5 — Glassmorphism Copy Section

Multi-Agent Collaboration — coordinator, specialists, shared state, review, and synthesis

Style 6 — Claude Official Copy Section

System Architecture — warm interface, runtime, safety, memory, tools, and operations layers

Style 7 — OpenAI Official Copy Section

API Integration Flow — clean SDK, prompt, model, tool, delivery, and release stages

Style 8 — Dark Luxury *(AI-authored)* Copy Section

Agent Runtime Architecture — control plane, execution and state layers, champagne-gold structure, semantic color buckets

Style 9 — C4 Review Canvas Copy Section

Checkout Container Review — one abstraction level, explicit responsibilities, technologies, and protocols

Style 10 — Cloud Fabric Copy Section

Active–Active Checkout Deployment — global ingress, regions, VPC ownership, and cross-region replication

Style 11 — Event Transit Copy Section

Checkout Event Line — topics as rails, processors as stations, a declared junction, DLQ, and state projection

Style 12 — Ops Pulse Copy Section

Checkout Reliability Pulse — golden signals, one critical path, OTel export, and a correlated trace

Stable Prompt Recipe Copy Chapter

The public showcase keeps a distinct domain scene for every style. They remain comparable because every fixture passes the same executable composition contract. A same-topology regression set remains internal under fixtures/quality-baseline/.

Draw the scenario assigned to style N:
1 Mem0 Memory Architecture; 2 Tool Call Flow; 3 Microservices Architecture;
4 Agent Memory Types; 5 Multi-Agent Collaboration; 6 System Architecture;
7 API Integration Flow; 8 Agent Runtime Architecture; 9 C4 Checkout Review;
10 Active–Active Cloud Deployment; 11 Checkout Event Line; 12 Checkout Reliability Pulse.
Preserve the scenario-specific nodes, sections, and reading direction.
Apply the showcase composition contract: zero crossings, zero bridge jumps, at most two bends per edge,
at most eight bends overall, at least 40px between nodes, at least 20px container gutter,
short orthogonal segments, and labels kept clear of nodes, routes, and section headers.
Preserve the selected style's typography, palette, card material, and brand details.

For the four engineering-first styles, use one of these prompt fingerprints so
the router selects the domain contract as well as the visual theme:

Style 9 · C4 review board: show one C4 level, responsibilities, technologies, review state, and relationship protocols.
Style 10 · Multi-region deployment map: show global ingress, Region/VPC ownership, neutral cloud glyphs, deployment mode, and named boundary mechanisms.
Style 11 · Event metro map: show thin topic rails, numbered processor stations, declared junctions, consumer groups, DLQ, and state projections.
Style 12 · Reliability pulse: show one observation window, four golden signals per service, numbered critical hops, telemetry export, and one correlated trace.

Replace N with 1–12. Style 8 remains AI-authored and loads references/style-8-dark-luxury.md; Styles 9–12 also enforce their engineering semantic contract. All styles load references/composition-quality-contract.md.

Features Copy Chapter

• 12 visual styles — 11 generator-backed profiles + 1 AI-authored style (Dark Luxury)
• Engineering semantic contracts — C4 abstraction levels, deployment ownership, event-rail topology, and exact golden signals fail closed before rendering
• Executable style system — style guides are encoded into the generator, not only documented in markdown
• Shared composition-quality contract — every official style enforces zero crossings/bridges, ≤2 bends per edge, route-stretch, spacing, gutter, micro-segment, and label-clearance budgets
• 14 diagram types — Full UML support (Class, Component, Deployment, Package, Composite Structure, Object, Use Case, Activity, State Machine, Sequence, Communication, Timing, Interaction Overview, ER Diagram) plus AI/Agent domain diagrams
• AI/Agent domain patterns — RAG, Agentic Search, Mem0, Multi-Agent, Tool Call, and more built-in
• Semantic shape vocabulary — LLM = double-border rect, Agent = hexagon, Vector Store = ringed cylinder
• Semantic arrow system — color + dash pattern encode meaning (write vs read vs async vs loop)
• Geometry-safe routing — deterministic orthogonal routes, exact waypoints, distinct ports, automatic legend relocation, labels kept inside the canvas, and verified bridge jumps for unavoidable crossings
• Versioned diagram IR — legacy JSON normalizes to schema v1; duplicate IDs, dangling references, malformed waypoints, and non-finite geometry fail before rendering
• Structured SVG validation — XML and marker integrity plus semantic node, reserved-region, label, canvas, edge-overlap, and edge-crossing checks
• Unified CLI + interactive export — render, validate, inspect, and export one offline HTML file with pan/zoom, themes, copy, and SVG/PNG/JPEG/WebP output up to 4×
• Focused semantic GIF motion — generated SVG in, validated GIF out; connectors begin absent and draw in semantic order. All twelve style contracts are user-approved. The shared +2s-settled-flow timing revision is also user-approved, so the default 5.75s/115-frame loop holds full settled flow on frames 38–109, then resets on 110–114
• Visual review gate — exported PNGs are inspected for clipping, overlap, label placement, and routing regressions before delivery
• Product icons — 40+ products with brand colors: OpenAI, Anthropic, Pinecone, Weaviate, Kafka, PostgreSQL…
• Swim lane grouping — automatic layer labeling for complex architectures
• SVG + PNG output — SVG for editing, 1920px PNG for embedding
• Renderer-friendly — pure inline SVG, no external font fetching; renders cleanly in cairosvg, rsvg-convert, and headless Chrome

Loop Engineering Copy Chapter

The first render is treated as a candidate, not an automatic final result. fireworks-tech-graph uses an agent-driven, bounded validation feedback loop to move each diagram toward a verified deliverable:

Prompt
  → Diagram Contract
  → Semantic IR
  → Style Spec
  → Route Planner
  → SVG Build
  → Structural Validation
  → PNG Visual Readback
  → Targeted Revision
  → Verified SVG + PNG

The loop follows five design principles:

1. Evaluate, don't assert — completion is backed by validator and render evidence, not by the model saying the diagram looks correct.
2. Deterministic checks first — XML structure, marker integrity, path geometry, arrow-component collisions, and renderability are checked before visual judgment.
3. Perceptual validation second — the exported PNG is read back to inspect clipping, label collisions, hierarchy, whitespace, and routing quality that syntax checks cannot see.
4. Targeted correction — each pass changes only the diagnosed labels, coordinates, corridors, or spacing, then reruns validation and rendering.
5. Bounded convergence — visual review allows at most two focused correction passes by default, preventing an unbounded self-editing loop.

The loop is observable in the final status:

validation: passed
visual_review: passed

If the runtime cannot read images, the skill reports visual_review: skipped (image reader unavailable) explicitly. The workflow remains bounded and auditable; it does not claim visual verification without image evidence.

Installation Copy Chapter

Recommended: install the complete skill for both runtimes Copy Section

Use the real nested skill path. The final /skills/fireworks-tech-graph segment is required because a bare repository install can select only the root SKILL.md in current versions of skills CLI.

npx -y [email protected] add \
  yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph \
  --agent codex claude-code -g -y --copy

This creates complete copies at ~/.agents/skills/fireworks-tech-graph for Codex and ~/.claude/skills/fireworks-tech-graph for Claude Code, including scripts, schemas, fixtures, templates, tests, references, and metadata.

Editable Git checkout for Codex Copy Section

mkdir -p ~/.agents/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph

Codex discovers personal skills from ~/.agents/skills and reads the optional agents/openai.yaml metadata included in this repository.

Editable Git checkout for Claude Code Copy Section

mkdir -p ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph

Claude Code discovers personal skills from ~/.claude/skills and ignores the Codex-only UI metadata.

One editable checkout shared by Codex and Claude Code Copy Section

For a fresh install with Claude Code 2.1.203 or newer, keep one checkout and link both discovery paths to it. Move any existing destinations aside before creating the links.

mkdir -p ~/.local/share/agent-skills ~/.agents/skills ~/.claude/skills
git clone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graph
ln -s ~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph

This keeps SKILL.md, references, scripts, templates, and future updates identical in both agents. The npm registry is a separate distribution channel and may lag GitHub Releases. For the current Skill version, use the nested GitHub path above; the npm page remains available for package metadata:

https://www.npmjs.com/package/@yizhiyanhua-ai/fireworks-tech-graph

Update Copy Chapter

For a skills CLI copy, rerun the recommended nested-path command. For Git installations, update whichever checkout you installed:

git -C ~/.agents/skills/fireworks-tech-graph pull
# or
git -C ~/.claude/skills/fireworks-tech-graph pull
# or, for the shared checkout
git -C ~/.local/share/agent-skills/fireworks-tech-graph pull

After the first install, restart Codex and Claude Code so both discover the skill. Later SKILL.md edits are detected automatically; restart the runtime after changing bundled scripts or references if the update is not visible.

The shell commands above target macOS, Linux, WSL, and Git Bash. On native Windows, use the equivalent %USERPROFILE%\.agents\skills and %USERPROFILE%\.claude\skills paths. Python 3.9+ is required; the optional Puppeteer path requires Node.js 22.12+.

Unified CLI Copy Chapter

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

python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
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"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

The HTML export is one offline file. It sanitizes the SVG, adds pan/zoom/reset, light and dark themes, SVG source copy, and SVG/PNG/JPEG/WebP downloads at 1×–4×.

For motion, say “Generate a GIF”, “Animate this diagram”, 生成 GIF, 制作 GIF, or 让这张图动起来. The command accepts a generated semantic SVG that carries one of the twelve approved motion contracts. Exact source bytes are not pinned, so validated title and content variants of a supported topology work; missing or changed role/stage/order coverage, route direction, required colors, or geometry fails closed. GIF is the only motion media format, and the default command also writes <output>.motion.json as its verification report. The approved default is 960px, 5.75 seconds, 20fps, and 115 frame-center samples. All twelve scenes start connector-free, draw routes on frames 1–36, fade live flow on 36–38, hold full settled flow on 38–109, and reset on 110–114. Their approved identities include the packet heads, terminal evidence trace, Blueprint registration beads, 14×10 Notion memory cards, and the eight scene-specific signatures listed below. Default packages report both the style contract and shared +2s-settled-flow timing revision as user-approved. Timelines of 75 frames or fewer remain all-unique. Longer timelines allow non-adjacent repeated rasters inside the full-opacity interval; frame 110 is the sole boundary exception because its unchanged reset opacity is exactly 1.00, and such evidence is classified as intentional_reset_boundary_repeat. Frames 111–114 remain globally distinct. Long timelines require at least 75 unique rasters and forbid adjacent duplicates. The all-style 75-vs-115 gate counts binary-exact and decoded-RGBA-exact frames separately; compositor-only fallback is accepted only at AE ≤ 128, normalized RMSE ≤ 0.001, with components no thicker than 2px and confined to edge or node borders. DOM and signature geometry remain strict-exact. Explicit 3.75s/75-frame and 2.75s/55-frame calls remain supported. See Focused SVG-to-GIF Motion.

Requirements Copy Chapter

The bundled SVG/PNG scripts require cairosvg (recommended) or rsvg-convert. Optional SVG-to-GIF export requires FFmpeg/FFprobe, Chrome/Chromium, and puppeteer or puppeteer-core.

# Recommended: cairosvg (best CSS support)
python3 -m pip install cairosvg

# Fallback: rsvg-convert (system package; may drop CSS / <foreignObject>)
brew install librsvg                   # macOS
sudo apt install librsvg2-bin          # Ubuntu/Debian

# Optional semantic motion export. Install beside every copied Skill because the
# renderer intentionally does not load modules from the caller's directory.
brew install ffmpeg                    # macOS; use your system package manager elsewhere
for SKILL_ROOT in \
  "$HOME/.agents/skills/fireworks-tech-graph" \
  "$HOME/.claude/skills/fireworks-tech-graph"
do
  [ -d "$SKILL_ROOT" ] || continue
  npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false [email protected]
  python3 "$SKILL_ROOT/scripts/fireworks.py" doctor
done

# Verify either supported script renderer
python3 -c "import cairosvg; print(cairosvg.__version__)"
rsvg-convert --version

Why Not Mermaid or draw.io? Copy Chapter

Mermaid is great for quick inline diagrams in markdown. draw.io is great for manual polishing. fireworks-tech-graph is optimized for describing a system and getting a polished diagram immediately, without writing DSL syntax or clicking around a GUI.

Usage Copy Chapter

Trigger phrases Copy Section

The skill auto-triggers on:

generate diagram / draw diagram / create chart / visualize
architecture diagram / flowchart / sequence diagram / data flow
Generate a GIF / animate this diagram / animate this SVG as a GIF / 生成 GIF / 制作 GIF / 让这张图动起来 / 把刚才的 SVG 转成 GIF

Basic usage Copy Section

Draw a RAG pipeline flowchart

Generate an Agentic Search architecture diagram

Specify style Copy Section

Draw a microservices architecture diagram, style 2 (dark terminal)

Draw a multi-agent collaboration diagram --style glassmorphism

Specify output path Copy Section

Generate a Mem0 architecture diagram, output to ~/Desktop/

Create a tool call flow diagram --output /tmp/diagrams/

Example Prompts by Scenario Copy Chapter

AI/Agent Systems Copy Section

Compare Agentic RAG vs standard RAG in a feature matrix, Notion clean style

→ Comparison matrix: RAG vs Agentic RAG, covering retrieval strategy, agent loop, tool use

Generate a Mem0 memory architecture diagram with vector store, graph DB, KV store, and memory manager

→ Memory Architecture with swim lanes: Input → Memory Manager → Storage tiers → Retrieval

Draw a Multi-Agent diagram: Orchestrator dispatches 3 SubAgents (search / compute / code execution), results aggregated

→ Agent Architecture with hexagons, tool layers, and result aggregation

Visualize the Tool Call execution flow: LLM → Tool Selector → Execution → Parser → back to LLM

→ Flowchart with decision loop showing tool invocation cycle

Draw the 5 agent memory types: Sensory, Working, Episodic, Semantic, Procedural

→ Mind map or layered architecture showing memory tiers from sensory to procedural

Infrastructure & Cloud Copy Section

Draw a microservices architecture: Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL + Redis

→ Architecture diagram with horizontal layers, swim lanes per service cluster

Generate a data pipeline diagram: Kafka → Spark processing → write to S3 → Athena query

→ Data flow diagram with labeled arrows (stream / batch / query)

Draw a Kubernetes deployment: Ingress → Service → [Pod × 3] → ConfigMap + PersistentVolume

→ Architecture with dashed containers per namespace, solid arrows for traffic flow

API & Sequence Flows Copy Section

Draw an OAuth2 authorization code flow sequence diagram: User → Client → Auth Server → Resource Server

→ Sequence diagram with vertical lifelines and activation boxes

Draw the ChatGPT Plugin call sequence diagram

→ Sequence: User → ChatGPT → Plugin Manifest → API → Response chain

Decision & Process Flows Copy Section

Draw a pre-launch QA flowchart for an AI app: Code Review → Security Scan → Performance Test → Manual Approval → Deploy

→ Flowchart with diamond decision nodes and parallel branches

Generate a feature comparison matrix: RAG vs Fine-tuning vs Prompt Engineering

→ Comparison matrix with checked/unchecked cells across cost, latency, accuracy, flexibility

Concept Maps Copy Section

Visualize the LLM application tech stack: from foundation model to SDK to app framework to deployment

→ Layered architecture or mind map from model layer to product layer

Draw an AI Agent capability map: Perception / Memory / Reasoning / Action / Learning

→ Mind map with central "AI Agent" node and 5 radial branches

12 Styles Copy Chapter

Each style has a dedicated reference file in references/ with exact color tokens and SVG patterns. Styles 1–7 and 9–12 are generator-backed; Style 8 uses AI-authored composition plus a static regression fixture.
The generator consumes structure fields such as containers, semantic nodes[].kind, arrows[].flow, and explicit port anchors. Styles 9–12 additionally validate domain-specific fields before layout.

Useful high-leverage fields for style-specific polish:

• style_overrides to nudge title alignment or palette tokens without forking a full style
• containers[].header_prefix / containers[].header_text for blueprint-style numbered section headers such as 01 // EDGE
• containers[].side_label for Claude-style left layer labels
• window_controls, meta_left, meta_center, meta_right for terminal / document chrome
• blueprint_title_block for engineering title boxes in style 3

Style Selection Guide Copy Section

For UML Diagrams:

• Class/Component/Package: Style 1 (Flat Icon) or Style 4 (Notion Clean) — clear structure, easy to read
• Sequence/Timing: Style 2 (Dark Terminal) — monospace fonts help with alignment
• State Machine/Activity: Style 3 (Blueprint) — engineering aesthetic fits process flows
• Use Case/Interview: Style 1 (Flat Icon) — colorful, accessible

For AI/Agent Diagrams:

• RAG/Agentic Search: Style 2 (Dark Terminal) or Style 5 (Glassmorphism) — tech-forward aesthetic
• Memory Architecture: Style 3 (Blueprint) — emphasizes layered storage tiers
• Multi-Agent: Style 5 (Glassmorphism) — frosted cards distinguish agent boundaries

For Documentation:

• Internal docs: Style 4 (Notion Clean) — minimal, wiki-friendly
• Blog posts: Style 1 (Flat Icon) — colorful, engaging
• GitHub README: Style 2 (Dark Terminal) — matches dark theme
• Presentations: Style 5 (Glassmorphism) or Style 6 (Claude Official) — polished

For Engineering Reviews:

• C4/ADR review: Style 9 (C4 Review Canvas) — one declared abstraction level with responsibilities and protocols
• Cloud deployment review: Style 10 (Cloud Fabric) — explicit region/network ownership and cross-boundary mechanisms
• Event-driven system review: Style 11 (Event Transit) — topic rails, processors, consumer groups, state, and DLQ
• Reliability/incident review: Style 12 (Ops Pulse) — golden signals, one critical path, and a correlated trace

Brand-Specific:

• Anthropic/Claude projects: Style 6 (Claude Official) — warm cream background, brand colors
• OpenAI projects: Style 7 (OpenAI Official) — clean white, OpenAI palette
• Premium editorial diagrams: Style 8 (Dark Luxury) — deep black canvas, champagne-gold hierarchy, semantic color buckets

Diagram Types Copy Chapter

UML Diagram Support (14 Types) Copy Section

AI/Agent Domain Patterns Copy Chapter

Built-in pattern knowledge:

RAG Pipeline         → Query → Embed → VectorSearch → Retrieve → LLM → Response
Agentic RAG          → adds Agent loop + Tool use
Agentic Search       → Query → Planner → [Search/Calc/Code] → Synthesizer
Mem0 Memory Layer    → Input → Memory Manager → [VectorDB + GraphDB] → Context
Agent Memory Types   → Sensory → Working → Episodic → Semantic → Procedural
Multi-Agent          → Orchestrator → [SubAgent×N] → Aggregator → Output
Tool Call Flow       → LLM → Tool Selector → Execution → Parser → LLM (loop)

Shape Vocabulary Copy Chapter

Shapes encode semantic meaning consistently across all styles:

Arrow Semantics Copy Chapter

File Structure Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Product Icon Coverage Copy Chapter

AI/ML: OpenAI, Anthropic/Claude, Google Gemini, Meta LLaMA, Mistral, Cohere, Groq, Hugging Face

AI Frameworks: Mem0, LangChain, LlamaIndex, LangGraph, CrewAI, AutoGen, DSPy, Haystack

Vector DBs: Pinecone, Weaviate, Qdrant, Chroma, Milvus, pgvector, Faiss

Databases: PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, Neo4j, Cassandra

Messaging: Kafka, RabbitMQ, NATS, Pulsar

Cloud: AWS, GCP, Azure, Cloudflare, Vercel, Docker, Kubernetes

Observability: Grafana, Prometheus, Datadog, LangSmith, Langfuse, Arize

Troubleshooting Copy Chapter

License Copy Chapter

MIT © 2025 fireworks-tech-graph contributors

Overview (`skills/fireworks-tech-graph/examples/README.md`) Copy Section

Interactive example

Open interactive-architecture.html directly in a browser. It is a single offline file generated from fixtures/api-flow-style7.json and contains no remote runtime dependencies.

Regenerate it with:

tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
tmp_svg="$tmp_dir/api-flow.svg"
python3 scripts/fireworks.py render architecture fixtures/api-flow-style7.json "$tmp_svg"
python3 scripts/fireworks.py export-html "$tmp_svg" examples/interactive-architecture.html --title "API Integration Flow" --slug api-integration-flow

Overview (`skills/fireworks-tech-graph/scripts/README.md`) Copy Section

Fireworks Tech Graph - Scripts

辅助脚本集合，用于提高 SVG 图表生成的稳定性和效率。

脚本列表 Copy Chapter

1. validate-svg.sh Copy Section

SVG 验证脚本，检查 SVG 语法并报告详细错误。

用法：

./validate-svg.sh <svg-file>

检查项目：

• XML 结构、属性语法和实体转义（使用 XML parser，避免把 top_k=5 之类的文本误判为属性）
• marker-start / marker-mid / marker-end 引用完整性
• 箭头与组件碰撞（支持绝对/相对 M/L/H/V/Q/C/S/T 路径，曲线路径采样检测）
• 渲染验证（cairosvg 优先，rsvg-convert 兜底）

示例：

./validate-svg.sh /path/to/diagram.svg

2. generate-diagram.sh Copy Section

SVG 图表生成脚本，提供自动验证和 PNG 导出。

用法：

./generate-diagram.sh [OPTIONS]

选项：

• -t, --type TYPE - 图表类型（见脚本帮助）
• -s, --style STYLE - 风格编号（1-12，默认：1）
• -o, --output PATH - 输出路径（默认：当前目录）
• -w, --width WIDTH - PNG 宽度（像素，默认：1920）
• --no-validate - 跳过验证
• -h, --help - 显示帮助

示例：

# 生成架构图（Style 1）
./generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg

# 生成流程图（Style 2，2400px 宽）
./generate-diagram.sh -t flowchart -s 2 -w 2400

注意： SVG 内容需要先准备好；这个脚本只负责验证与导出。

3. generate-from-template.py Copy Section

基于风格配置和 JSON 数据生成 SVG。当前版本不再只是简单塞入 nodes/arrows，
而是会执行 style guide 中的部分可计算规则，例如：

• style - 风格编号（1-12）或规范风格名
• semantic_profile - 可选语义契约；Style 9-12 默认分别启用 C4、云部署、事件流和可观测性契约
• containers - 泳道 / 分组容器
• containers[].header_prefix / containers[].header_text - 工程编号式分区标题
• containers[].side_label - 左侧 layer label
• nodes[].kind - 语义组件类型，例如 double_rect、cylinder、document、terminal、circle_cluster
• arrows[].flow - 语义箭头类型，例如 control、write、read、data
• source_port / target_port - 指定端口锚点
• route_points / corridor_x / corridor_y - 控制复杂图的走线质量
• style_overrides - 对现有 style 做局部覆盖
• window_controls / meta_* - 顶部终端 chrome
• blueprint_title_block - 工程蓝图右下角 title block

用法：

python3 ./generate-from-template.py architecture ./output/arch.svg '{"style":1,"title":"My Diagram","containers":[],"nodes":[],"arrows":[]}'

示例：

python3 ./generate-from-template.py memory ./output/mem0.svg '{
  "style": 1,
  "title": "Mem0 Memory Architecture",
  "containers": [
    {"x":30,"y":90,"width":900,"height":90,"label":"Input Layer","header_prefix":"01"}
  ],
  "nodes": [
    {"id":"manager","kind":"double_rect","x":360,"y":220,"width":300,"height":72,"label":"Memory Manager"},
    {"id":"vector","kind":"cylinder","x":90,"y":360,"width":140,"height":110,"label":"Vector Store"}
  ],
  "arrows": [
    {"source":"manager","target":"vector","flow":"write","dashed":true}
  ]
}'

4. test-all-styles.sh Copy Section

批量测试脚本覆盖 12 种风格。Style 1-7 与 9-12 从 JSON fixture 生成，AI 手绘的 Style 8 使用静态 SVG fixture；任何风格缺少回归 fixture 都会使批测失败。

用法：

./test-all-styles.sh

功能：

• 检查所有风格的参考文件
• 渲染 fixtures/*.json 回归样例
• 验证生成出的 SVG 文件
• 导出 PNG 文件到 test-output/ 目录
• 生成测试报告

输出：

• 测试摘要（通过/失败统计）
• PNG 文件（带时间戳）
• 详细的验证错误信息

示例：

./test-all-styles.sh

依赖 Copy Chapter

所有脚本需要至少一个 PNG 渲染器（推荐 cairosvg）：

• cairosvg（推荐）- SVG 转 PNG，CSS 支持最好

  bash Copy

  python3 -m pip install cairosvg

• rsvg-convert（备选）- 系统包；复杂 SVG 可能丢失 CSS / <foreignObject>

  bash Copy

  brew install librsvg                # macOS
  sudo apt install librsvg2-bin       # Ubuntu/Debian

generate-diagram.sh 会优先调用 cairosvg，缺失时自动回退到 rsvg-convert。完整对比见 PNG 导出参考。

聚焦后的语义动效由 fireworks.py animate、motion.py 和 svg2gif.js 协作完成，只接收带有 12 套已验收 role/stage/order 契约之一的生成器语义 SVG。精确源文件字节不锁定，但任意同风格拓扑不会自动套用动效。媒体输出只允许经过验证的 GIF，默认还会生成同名 .motion.json 报告。运行时需要 FFmpeg/FFprobe、Chrome/Chromium，以及 Skill 安装位置可解析到的 puppeteer 或 puppeteer-core；当前工作目录中的同名模块不会被隐式执行。依赖安装与最简命令：

for SKILL_ROOT in \
  "$HOME/.agents/skills/fireworks-tech-graph" \
  "$HOME/.claude/skills/fireworks-tech-graph"
do
  [ -d "$SKILL_ROOT" ] || continue
  npm install --prefix "$SKILL_ROOT" --ignore-scripts --no-save --package-lock=false [email protected]
done
SKILL_ROOT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}"
python3 "$SKILL_ROOT/scripts/fireworks.py" animate diagram.svg diagram.gif

默认自动识别风格，输出 5.75 秒、20fps、960px 宽、115 帧无限循环 GIF。第 1–36 帧保持既有 draw-on，第 36–38 帧淡入运行流，第 38–109 帧为完整稳定数据流，第 110–114 帧按 [1,.7575,.515,.2725,.03] reset。Style 1–12 的 signature、速度、路径、几何和构建合同均为 user-approved，包括 persistent-data-flow-head、terminal-evidence-stream、blueprint-registration-bead、14×10 notion-memory-card、glass-task-capsule、policy-seal、token-train、gem-tracer、review-cursor、region chevrons、event train 与 ops scanner；共享 +2s-settled-flow 时间修订也已于 2026-07-17 验收，默认新包的 review_status 为 user-approved。显式 3.75 秒/75 帧和 2.75 秒/55 帧继续支持。75 帧及以下要求全部 raster 唯一；更长时间线允许非相邻重复出现在 full-opacity 区间，frame 110 是 reset opacity 为 1.00 的唯一例外并分类为 intentional_reset_boundary_repeat，frame 111–114 必须全局不同；至少保留 75 个唯一 raster 且相邻重复数为零。75-vs-115 gate 分开统计 binary / decoded-RGBA / guarded-antialias 三类；guarded 等价要求 AE ≤ 128、normalized RMSE ≤ 0.001、component 宽或高不超过 2px 且只落在 edge/node border，DOM 和 signature geometry 仍 strict-exact。完整约束见 动效参考。

• grep, sed, awk - 文本处理（macOS 自带）

目录结构 Copy Chapter

fireworks-tech-graph/
├── SKILL.md                    # Skill 主文档
├── references/                 # 风格参考文件
│   ├── style-1-flat-icon.md
│   ├── style-2-dark-terminal.md
│   └── ...
├── fixtures/                   # 回归测试样例（JSON）
│   ├── mem0-style1.json
│   ├── tool-call-style2.json
│   └── ...
├── scripts/                    # 辅助脚本（本目录）
│   ├── README.md              # 本文档
│   ├── validate-svg.sh        # SVG 验证
│   ├── generate-diagram.sh    # SVG 验证与 PNG 导出
│   ├── generate-from-template.py # 模板化生成 SVG
│   ├── motion.py              # SVG 转 GIF 校验、编码与原子报告
│   ├── svg2gif.js             # Chromium 手动时间轴逐帧渲染
│   └── test-all-styles.sh     # 批量测试
└── test-output/               # 测试输出目录（自动创建）

使用场景 Copy Chapter

场景 1：验证现有 SVG Copy Section

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
# SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
"$SKILL_ROOT/scripts/validate-svg.sh" /path/to/your-diagram.svg

场景 2：生成并验证图表 Copy Section

1. 使用 Codex 或 Claude Code 生成 SVG 内容
2. 运行验证和导出：
   bash Copy

   SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
   # SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
   "$SKILL_ROOT/scripts/generate-diagram.sh" -t architecture -s 1 -o ./output/arch.svg

场景 3：批量测试所有风格 Copy Section

SKILL_ROOT=~/.agents/skills/fireworks-tech-graph # Codex
# SKILL_ROOT=~/.claude/skills/fireworks-tech-graph # Claude Code
"$SKILL_ROOT/scripts/test-all-styles.sh"

测试脚本会自动：

1. 读取 ../fixtures/*.json
2. 按 template_type + style 调用 generate-from-template.py
3. 运行 validate-svg.sh
4. 导出 PNG 到 ../test-output/

场景 4：validator 单元测试 Copy Section

python3 -m unittest discover -s tests -p 'test_validate_svg.py' -v

覆盖 marker 双端引用、文本等号、H/V 路径、曲线路径、虚线组件和容器排除等正反例。

对启发式难以区分的形状，可显式添加 data-graph-role="node|container|legend|decoration|label|background"。node 会强制纳入障碍物检测，其余角色会从组件障碍物中排除；legend 组内的示例箭头也不会被当作业务流。

查看测试输出：

ls -lh ../test-output/

故障排除 Copy Chapter

问题：找不到 PNG 渲染器 Copy Section

解决方案（任选其一，推荐 cairosvg）：

python3 -m pip install cairosvg        # 推荐
brew install librsvg                   # macOS 系统包
sudo apt install librsvg2-bin          # Ubuntu/Debian

问题：rsvg-convert 渲染缺框/缺文字 Copy Section

原因： rsvg-convert 对 <foreignObject>、CSS filter、复杂 <style> 块支持有限。

解决方案： 切换到 cairosvg：

python3 -m pip install cairosvg

脚本会自动优先使用 cairosvg。如果仍需要像素级还原（例如浏览器生成的 SVG），按 PNG 导出参考 使用 svg2png.js。

问题：权限被拒绝 Copy Section

解决方案：

chmod +x *.sh

问题：SVG 验证失败 Copy Section

解决方案：

1. 查看详细错误信息
2. 使用 Edit 工具修复语法错误
3. 重新运行验证

开发说明 Copy Chapter

添加新的验证规则 Copy Section

编辑 validate-svg.sh，在现有检查项后添加新的检查逻辑：

# Check N: Your new check
echo -n "Checking something... "
# Your validation logic here
if [ condition ]; then
    echo -e "${GREEN}✓ Pass${NC}"
else
    echo -e "${RED}✗ Fail${NC}"
fi

扩展支持的图表类型 Copy Section

编辑 generate-diagram.sh，在 --type 参数处理中添加新类型。

版本历史 Copy Chapter

• v1.2.0 (2026-07-17) - 语义动效与动态展示
  • 12 种已验收的 SVG→GIF 场景动效与 5.75 秒 settled-flow 默认时间线
  • README 全动态图集、GIF manifest、媒体回读与安装副本全风格门禁
  • 动效源 SVG 保持语义契约约束，不绑定标题和内容字节
• v1.1.0 (2026-07-15) - 几何与分发升级
  • Schema v1 与类型化 Diagram IR
  • 正交路由、端口分流、图例/标签避让、跨线桥与确定性布局报告
  • fireworks.py 统一 CLI 与离线交互 HTML 导出
  • 完整 npx Skill 镜像、CI、Release archive parity 与安装 canary
• v1.0.0 (2026-04-11) - 初始版本
  • SVG 验证脚本
  • 图表生成脚本
  • 批量测试脚本

许可证 Copy Chapter

MIT License - 与 fireworks-tech-graph skill 相同

Overview (`skills/fireworks-tech-graph/docs/releases/README.md`) Copy Section

Release history

This directory is the source of truth for the curated GitHub Release notes. Version dates describe when each version originally became available, not when a historical GitHub Release page was backfilled.

Historical provenance Copy Chapter

GitHub Release pages for v1.0.0 through v1.0.5 were backfilled on 2026-07-17. The npm packages were sometimes published from a working tree immediately before its matching commit: npm 1.0.2, 1.0.3, and 1.0.4 retain the preceding gitHead, while their complete published file sets match the subsequent commits shown in the Tag commit column. No fully committed tree reproduces every packaging change in npm 1.0.0 or 1.0.1; those tags use the registry source anchor, and their notes state the limitation.

CAPABILITIES (`docs/CAPABILITIES.md`) Copy Section

Capability contract

Input Copy Chapter

• Legacy JSON remains supported and normalizes to schema v1.
• Versioned input uses schema_version: 1 and a mode matching the selected renderer.
• Duplicate IDs, dangling references, non-finite coordinates, malformed waypoints, and unknown schema versions fail before layout.
• Style-specific fields and unknown renderer extensions are preserved.
• style and visual_theme resolve through one catalog covering Styles 1–12; unknown or conflicting selectors fail closed.

Engineering semantics Copy Chapter

• Style 9 defaults to c4-review: one C4 level, typed elements, responsibilities, technologies, and protocols.
• Style 10 defaults to cloud-fabric: acyclic deployment boundaries, explicit workload ownership, versioned neutral icons, and named cross-boundary mechanisms.
• Style 11 defaults to event-transit: ordered topic rails, declared junctions, consumer groups, state projections, and real DLQ targets.
• Style 12 defaults to ops-pulse: exact golden signals, one contiguous business critical path, separate telemetry semantics, and a valid trace tree.
• semantic_profile: "generic" keeps any generator-backed visual theme available for internal topology regression without pretending domain semantics are present.

Geometry Copy Chapter

• All generated business edges are rectilinear outside declared bridge arcs.
• route_points are exact ordered waypoints; every leg is routed safely.
• Nodes, section headers, legends, title blocks, footers, labels, and the canvas boundary participate in layout checks.
• Distinct ports are allocated deterministically for shared node sides.
• Collinear edge overlap is fatal. Proper crossings receive a visible bridge and background mask.
• Layout output and reports are deterministic for the same input.

Output Copy Chapter

• SVG is the canonical artifact and carries data-graph-role, style, diagram-type, semantic-profile, semantic-role, edge-kind, topic, flow, station-order, status, critical-hop, and trace-timing metadata.
• PNG export uses CairoSVG or rsvg-convert in the shell workflow.
• Optional motion export has one media contract: a generated semantic SVG carrying one of the 12 approved role/stage/order scene contracts becomes a validated GIF plus its JSON verification report. Exact source bytes are not pinned, but unsupported same-style topologies fail closed. The user-approved 5.75s/115-frame default keeps construction at 1–36, live fade at 36–38, full settled flow at 38–109, and reset at 110–114. Styles 1–12 and the shared +2s-settled-flow timing revision retain user-approved status. Timelines through 75 frames remain all-unique. Longer timelines require at least 75 unique rasters and zero adjacent duplicates. Repeats stay inside the full-opacity interval except frame 110, the sole intentional_reset_boundary_repeat allowed by its unchanged 1.00 reset opacity; frames 111–114 remain globally distinct. The 75-vs-115 compatibility report separates binary-exact, decoded-RGBA-exact, and guarded antialias-equivalent counts. The guarded tier requires AE ≤ 128, normalized RMSE ≤ 0.001, components no thicker than 2px, and edge/node-border-only scope while DOM and signature geometry remain strict-exact. Direction/source-DOM guards, FFprobe validation, infinite looping, and atomic GIF/report installation remain mandatory.
• The single-SVG offline HTML viewer remains independent of motion and supports pan, zoom, reset, themes, copy, and static SVG/PNG/JPEG/WebP export.
• Interactive export rejects active elements, event handlers, external references, foreignObject, and external CSS.

Distribution Copy Chapter

• Git clone and npm archives contain the complete skill.
• The committed skills/fireworks-tech-graph/ mirror supports deterministic npx skills add subpath installation for Codex and Claude Code.
• npm .tgz and GitHub release .zip are built from the same payload and checked by file hash.

ROADMAP (`docs/ROADMAP.md`) Copy Section

Roadmap

Shipped in 1.1 Copy Chapter

• Versioned diagram IR and schemas
• Geometry-safe renderer and artifact audit
• Deterministic layout reports
• Complete Agent Skill installer mirror
• Unified CLI and offline interactive export
• CI, release archives, parity checks, and public install canary

Next candidates Copy Chapter

• Incremental layout for diagrams above 100 edges
• Pluggable text metrics using browser font measurement
• Interactive edge/node inspection panels
• Optional theme token packs without changing diagram semantics
• Visual-diff baselines for browser engines and platform fonts

Roadmap items remain proposals until they have tests, a compatibility plan, and a measured maintenance cost.

Releases V1.0.0 (`docs/releases/v1.0.0.md`) Copy Section

Fireworks Tech Graph v1.0.0

The first public npm release established Fireworks Tech Graph as a reusable Agent Skill for generating polished technical diagrams from natural-language requirements.

Version information Copy Chapter

• Version: v1.0.0 / npm 1.0.0
• Version date: 2026-04-12; npm published at 2026-04-12T00:09:17.387Z
• Tag commit: 27f41d98
• npm registry gitHead: 27f41d98
• Previous version: initial public release
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.0

Highlights Copy Chapter

• Shipped seven built-in visual styles for architecture, flow, UML, ER, sequence, and related technical diagrams.
• Included SVG generation, high-resolution PNG export through rsvg-convert, validation scripts, and bilingual documentation.
• Included style references and the first seven-style showcase.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Of the 26 files in the published npm tarball, all 25 Git-backed files match the registry-recorded gitHead byte-for-byte; package.json was publication metadata that had not yet been committed. The tag is therefore the closest source provenance anchor, but GitHub's generated source archive is not byte-identical to the npm artifact.

Releases V1.0.1 (`docs/releases/v1.0.1.md`) Copy Section

Fireworks Tech Graph v1.0.1

This patch release tightened the diagram-quality prompt contract and corrected npm repository metadata.

Version information Copy Chapter

• Version: v1.0.1 / npm 1.0.1
• Version date: 2026-04-12; npm published at 2026-04-12T00:12:37.149Z
• Tag commit: 27f41d98
• npm registry gitHead: 27f41d98
• Previous version: v1.0.0
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.1

Highlights Copy Chapter

• Added an explicit validation checklist for connector-node collisions and orthogonal rerouting.
• Added text-overflow, endpoint-alignment, and connector-label background checks.
• Normalized the npm repository URL metadata.

Provenance Copy Chapter

The npm registry records the same gitHead for 1.0.0 and 1.0.1. The published tarball contains two working-tree-only changes relative to that commit: package.json and an expanded SKILL.md layout-validation checklist; the other 24 files match byte-for-byte. No historical commit exactly reproduces this npm artifact, so the backfilled tag records the registry provenance anchor.

Releases V1.0.2 (`docs/releases/v1.0.2.md`) Copy Section

Fireworks Tech Graph v1.0.2

This release introduced the style-driven generator and a reproducible fixture-and-template workflow for the original seven styles.

Version information Copy Chapter

• Version: v1.0.2 / npm 1.0.2
• Version date: 2026-04-12; npm published at 2026-04-12T13:24:35.073Z
• Tag commit: 921fb308, whose complete file set matches the npm tarball
• npm registry gitHead: fee15924
• Previous version: v1.0.1
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.2

Highlights Copy Chapter

• Added a Python style-driven generator, seven scenario fixtures, and ten reusable SVG diagram templates.
• Added formal npm package metadata for repository, license, files, runtime, and discovery keywords.
• Expanded the package payload to include fixtures/ and templates/.
• Refreshed all seven showcase renders and strengthened SVG validation and all-style test scripts.
• Added a style-to-diagram selection matrix for more reliable prompting.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Every one of the 44 files in the published npm tarball matches commit 921fb308 byte-for-byte. The registry records the preceding gitHead because publication occurred about 34 seconds before the packaging commit was created; the historical tag therefore uses the content-matching commit.

Releases V1.0.3 (`docs/releases/v1.0.3.md`) Copy Section

Fireworks Tech Graph v1.0.3

This patch release made the installation source explicit and separated the Agent Skill installer path from the npm distribution page.

Version information Copy Chapter

• Version: v1.0.3 / npm 1.0.3
• Version date: 2026-04-12; npm published at 2026-04-12T13:28:10.195Z
• Tag commit: c3726124, whose versioned content matches the npm tarball
• npm registry gitHead: 921fb308
• Previous version: v1.0.2
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.3

Highlights Copy Chapter

• Standardized installation on npx skills add yizhiyanhua-ai/fireworks-tech-graph.
• Clarified that skills add resolves the GitHub repository while npm provides package distribution and README discovery.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. npm 1.0.3 was published 13 seconds before the matching repository commit, so the registry retained the preceding gitHead. The historical tag uses the subsequent commit because its README, Chinese README, Skill instructions, and package.json match the published versioned content.

Releases V1.0.4 (`docs/releases/v1.0.4.md`) Copy Section

Fireworks Tech Graph v1.0.4

This patch release documented a deterministic update path for existing Skill installations.

Version information Copy Chapter

• Version: v1.0.4 / npm 1.0.4
• Version date: 2026-04-12; npm published at 2026-04-12T13:32:37.231Z
• Tag commit: c8668407, whose versioned content matches the npm tarball
• npm registry gitHead: c3726124
• Previous version: v1.0.3
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.4; this remains the npm registry's latest version for the legacy package line

Highlights Copy Chapter

• Added npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y as the documented update command.
• Synchronized the update workflow across the English README, Chinese README, and Skill instructions.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. npm 1.0.4 was published 11 seconds before the matching repository commit, so the registry retained the preceding gitHead. The historical tag uses the subsequent commit because its README, Chinese README, Skill instructions, and package.json match the published versioned content.

Releases V1.0.5 (`docs/releases/v1.0.5.md`) Copy Section

Fireworks Tech Graph v1.0.5

This repository release consolidated three months of diagram-quality work and made the Skill directly usable by both Codex and Claude Code.

Version information Copy Chapter

• Version: v1.0.5
• Version date: 2026-07-11
• Tag commit: 14be3ad3, the mainline merge of version commit 55916c55; both have the same tree
• Previous version: v1.0.4
• Runtime metadata: Node.js 14 or newer
• Distribution: repository version only; npm publishing stopped at 1.0.4

Highlights Copy Chapter

• Added shared Codex and Claude Code metadata, instructions, compatibility tests, and installation paths.
• Added Style 8 Dark Luxury while preserving the seven original style contracts.
• Added a bounded generate-validate-repair loop, structural SVG checks, and optional visual self-review.
• Improved connector routing, label placement, overlap prevention, filter and viewport clipping guidance, and CJK font fallbacks.
• Switched the default PNG renderer to CairoSVG, hardened helper scripts, and documented renderer edge cases.
• Added the first GitHub Pages product showcase.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Unlike npm versions 1.0.0 through 1.0.4, the v1.0.5 tag points to a committed mainline tree whose package.json declares 1.0.5; no npm 1.0.5 package was published.

Releases V1.1.0 (`docs/releases/v1.1.0.md`) Copy Section

Fireworks Tech Graph v1.1.0

This release turns the project into an engineering-grade diagram system while preserving the distinct scenarios and visual identity of all 12 styles.

Version information Copy Chapter

• Version: v1.1.0
• Version date: 2026-07-15
• Tag commit: 1c7ba0fe
• Previous version: v1.0.5
• Release channel: GitHub stable release; the npm registry remains on the legacy 1.0.4 package line.

Highlights Copy Chapter

• Adds Style 9 C4 Review Canvas, Style 10 Cloud Fabric, Style 11 Event Transit, and Style 12 Ops Pulse.
• Enforces semantic contracts for C4 abstraction, deployment ownership, event rails, Golden Signals, observation windows, critical paths, and correlated traces.
• Adds geometry-safe orthogonal routing, port fan-out, waypoint validation, label and reserved-region checks, bridge masks, and fail-closed composition gates.
• Adds a unified CLI, versioned Diagram IR, deterministic layout reports, and safe offline interactive HTML export.
• Refreshes the official gallery with 12 distinct engineering scenarios and fixed-width 1920px regression renders.
• Ships a complete nested Agent Skill payload for Codex and Claude Code, plus reproducible tgz/zip archives and SHA256SUMS.

Compatibility Copy Chapter

• Node.js 18 or newer is required.
• Python source compatibility is checked against Python 3.9 grammar; CI runs the test suite on Python 3.9 and 3.12.
• The npm registry is a separate distribution channel and may lag this GitHub Release. Install the current Skill from yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph.

See the v1.1.0 changelog for the full change list and the release assets below for checksum-verified archives.

Releases V1.2.0 (`docs/releases/v1.2.0.md`) Copy Section

Fireworks Tech Graph v1.2.0

This release adds a focused, production-validated SVG-to-GIF workflow while preserving the twelve distinct diagram styles and their engineering scenarios.

Version information Copy Chapter

• Version: v1.2.0
• Version date: 2026-07-17
• Tag commit: ea534c2d
• Previous version: v1.1.0
• Release channel: latest GitHub stable release; the npm registry remains on the legacy 1.0.4 package line.

Highlights Copy Chapter

• Adds user-approved semantic motion contracts for all 12 styles: connectors start absent, build in semantic order, then keep the completed topology alive with style-specific data flow.
• Makes the 5.75-second / 115-frame settled-flow timeline the default for natural-language GIF requests, while retaining explicit 3.75-second and 2.75-second compatibility timelines.
• Replaces every README showcase image with an approved GIF, including a synchronized 3×4 overview optimized below 2 MiB. Static 1920px PNGs remain available as regression baselines.
• Refreshes the GitHub Pages product site with the animated overview and all twelve per-style GIFs, while retaining static Open Graph media and reduced-motion fallbacks.
• Adds source-DOM immutability guards, bounded runtime probes, secure Puppeteer resolution, atomic GIF/report installation, FFprobe media checks, binary infinite-loop readback, and motion reports.
• Validates all 12 installed Skill styles in CI and before tag releases, including 852 Chromium compatibility comparisons across the extended timeline.
• Keeps motion reusable for valid title and content changes: the semantic topology, route roles, directions, stages, geometry, and style signature are pinned; the exact source SVG bytes are not.
• Includes the post-v1.1.0 SVG validator fixes for multi-subpath geometry and transformed bounds.

Compatibility Copy Chapter

• Python 3.9 or newer is required.
• Node.js 18 or newer is required for the optional Chromium motion renderer.
• GIF generation requires FFmpeg and [email protected]; static SVG/PNG/HTML workflows continue to work without them.
• The npm registry is a separate distribution channel and may lag the GitHub Release. Install the current Skill from yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph.

See the v1.2.0 changelog for the full change list and the release assets below for checksum-verified archives.

Skills Fireworks Tech Graph Docs CAPABILITIES (`skills/fireworks-tech-graph/docs/CAPABILITIES.md`) Copy Section

Capability contract

Input Copy Chapter

• Legacy JSON remains supported and normalizes to schema v1.
• Versioned input uses schema_version: 1 and a mode matching the selected renderer.
• Duplicate IDs, dangling references, non-finite coordinates, malformed waypoints, and unknown schema versions fail before layout.
• Style-specific fields and unknown renderer extensions are preserved.
• style and visual_theme resolve through one catalog covering Styles 1–12; unknown or conflicting selectors fail closed.

Engineering semantics Copy Chapter

• Style 9 defaults to c4-review: one C4 level, typed elements, responsibilities, technologies, and protocols.
• Style 10 defaults to cloud-fabric: acyclic deployment boundaries, explicit workload ownership, versioned neutral icons, and named cross-boundary mechanisms.
• Style 11 defaults to event-transit: ordered topic rails, declared junctions, consumer groups, state projections, and real DLQ targets.
• Style 12 defaults to ops-pulse: exact golden signals, one contiguous business critical path, separate telemetry semantics, and a valid trace tree.
• semantic_profile: "generic" keeps any generator-backed visual theme available for internal topology regression without pretending domain semantics are present.

Geometry Copy Chapter

• All generated business edges are rectilinear outside declared bridge arcs.
• route_points are exact ordered waypoints; every leg is routed safely.
• Nodes, section headers, legends, title blocks, footers, labels, and the canvas boundary participate in layout checks.
• Distinct ports are allocated deterministically for shared node sides.
• Collinear edge overlap is fatal. Proper crossings receive a visible bridge and background mask.
• Layout output and reports are deterministic for the same input.

Output Copy Chapter

• SVG is the canonical artifact and carries data-graph-role, style, diagram-type, semantic-profile, semantic-role, edge-kind, topic, flow, station-order, status, critical-hop, and trace-timing metadata.
• PNG export uses CairoSVG or rsvg-convert in the shell workflow.
• Optional motion export has one media contract: a generated semantic SVG carrying one of the 12 approved role/stage/order scene contracts becomes a validated GIF plus its JSON verification report. Exact source bytes are not pinned, but unsupported same-style topologies fail closed. The user-approved 5.75s/115-frame default keeps construction at 1–36, live fade at 36–38, full settled flow at 38–109, and reset at 110–114. Styles 1–12 and the shared +2s-settled-flow timing revision retain user-approved status. Timelines through 75 frames remain all-unique. Longer timelines require at least 75 unique rasters and zero adjacent duplicates. Repeats stay inside the full-opacity interval except frame 110, the sole intentional_reset_boundary_repeat allowed by its unchanged 1.00 reset opacity; frames 111–114 remain globally distinct. The 75-vs-115 compatibility report separates binary-exact, decoded-RGBA-exact, and guarded antialias-equivalent counts. The guarded tier requires AE ≤ 128, normalized RMSE ≤ 0.001, components no thicker than 2px, and edge/node-border-only scope while DOM and signature geometry remain strict-exact. Direction/source-DOM guards, FFprobe validation, infinite looping, and atomic GIF/report installation remain mandatory.
• The single-SVG offline HTML viewer remains independent of motion and supports pan, zoom, reset, themes, copy, and static SVG/PNG/JPEG/WebP export.
• Interactive export rejects active elements, event handlers, external references, foreignObject, and external CSS.

Distribution Copy Chapter

• Git clone and npm archives contain the complete skill.
• The committed skills/fireworks-tech-graph/ mirror supports deterministic npx skills add subpath installation for Codex and Claude Code.
• npm .tgz and GitHub release .zip are built from the same payload and checked by file hash.

Skills Fireworks Tech Graph Docs ROADMAP (`skills/fireworks-tech-graph/docs/ROADMAP.md`) Copy Section

Roadmap

Shipped in 1.1 Copy Chapter

• Versioned diagram IR and schemas
• Geometry-safe renderer and artifact audit
• Deterministic layout reports
• Complete Agent Skill installer mirror
• Unified CLI and offline interactive export
• CI, release archives, parity checks, and public install canary

Next candidates Copy Chapter

• Incremental layout for diagrams above 100 edges
• Pluggable text metrics using browser font measurement
• Interactive edge/node inspection panels
• Optional theme token packs without changing diagram semantics
• Visual-diff baselines for browser engines and platform fonts

Roadmap items remain proposals until they have tests, a compatibility plan, and a measured maintenance cost.

Skills Fireworks Tech Graph Docs Releases V1.0.0 (`skills/fireworks-tech-graph/docs/releases/v1.0.0.md`) Copy Section

Fireworks Tech Graph v1.0.0

The first public npm release established Fireworks Tech Graph as a reusable Agent Skill for generating polished technical diagrams from natural-language requirements.

Version information Copy Chapter

• Version: v1.0.0 / npm 1.0.0
• Version date: 2026-04-12; npm published at 2026-04-12T00:09:17.387Z
• Tag commit: 27f41d98
• npm registry gitHead: 27f41d98
• Previous version: initial public release
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.0

Highlights Copy Chapter

• Shipped seven built-in visual styles for architecture, flow, UML, ER, sequence, and related technical diagrams.
• Included SVG generation, high-resolution PNG export through rsvg-convert, validation scripts, and bilingual documentation.
• Included style references and the first seven-style showcase.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Of the 26 files in the published npm tarball, all 25 Git-backed files match the registry-recorded gitHead byte-for-byte; package.json was publication metadata that had not yet been committed. The tag is therefore the closest source provenance anchor, but GitHub's generated source archive is not byte-identical to the npm artifact.

Skills Fireworks Tech Graph Docs Releases V1.0.1 (`skills/fireworks-tech-graph/docs/releases/v1.0.1.md`) Copy Section

Fireworks Tech Graph v1.0.1

This patch release tightened the diagram-quality prompt contract and corrected npm repository metadata.

Version information Copy Chapter

• Version: v1.0.1 / npm 1.0.1
• Version date: 2026-04-12; npm published at 2026-04-12T00:12:37.149Z
• Tag commit: 27f41d98
• npm registry gitHead: 27f41d98
• Previous version: v1.0.0
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.1

Highlights Copy Chapter

• Added an explicit validation checklist for connector-node collisions and orthogonal rerouting.
• Added text-overflow, endpoint-alignment, and connector-label background checks.
• Normalized the npm repository URL metadata.

Provenance Copy Chapter

The npm registry records the same gitHead for 1.0.0 and 1.0.1. The published tarball contains two working-tree-only changes relative to that commit: package.json and an expanded SKILL.md layout-validation checklist; the other 24 files match byte-for-byte. No historical commit exactly reproduces this npm artifact, so the backfilled tag records the registry provenance anchor.

Skills Fireworks Tech Graph Docs Releases V1.0.2 (`skills/fireworks-tech-graph/docs/releases/v1.0.2.md`) Copy Section

Fireworks Tech Graph v1.0.2

This release introduced the style-driven generator and a reproducible fixture-and-template workflow for the original seven styles.

Version information Copy Chapter

• Version: v1.0.2 / npm 1.0.2
• Version date: 2026-04-12; npm published at 2026-04-12T13:24:35.073Z
• Tag commit: 921fb308, whose complete file set matches the npm tarball
• npm registry gitHead: fee15924
• Previous version: v1.0.1
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.2

Highlights Copy Chapter

• Added a Python style-driven generator, seven scenario fixtures, and ten reusable SVG diagram templates.
• Added formal npm package metadata for repository, license, files, runtime, and discovery keywords.
• Expanded the package payload to include fixtures/ and templates/.
• Refreshed all seven showcase renders and strengthened SVG validation and all-style test scripts.
• Added a style-to-diagram selection matrix for more reliable prompting.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Every one of the 44 files in the published npm tarball matches commit 921fb308 byte-for-byte. The registry records the preceding gitHead because publication occurred about 34 seconds before the packaging commit was created; the historical tag therefore uses the content-matching commit.

Skills Fireworks Tech Graph Docs Releases V1.0.3 (`skills/fireworks-tech-graph/docs/releases/v1.0.3.md`) Copy Section

Fireworks Tech Graph v1.0.3

This patch release made the installation source explicit and separated the Agent Skill installer path from the npm distribution page.

Version information Copy Chapter

• Version: v1.0.3 / npm 1.0.3
• Version date: 2026-04-12; npm published at 2026-04-12T13:28:10.195Z
• Tag commit: c3726124, whose versioned content matches the npm tarball
• npm registry gitHead: 921fb308
• Previous version: v1.0.2
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.3

Highlights Copy Chapter

• Standardized installation on npx skills add yizhiyanhua-ai/fireworks-tech-graph.
• Clarified that skills add resolves the GitHub repository while npm provides package distribution and README discovery.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. npm 1.0.3 was published 13 seconds before the matching repository commit, so the registry retained the preceding gitHead. The historical tag uses the subsequent commit because its README, Chinese README, Skill instructions, and package.json match the published versioned content.

Skills Fireworks Tech Graph Docs Releases V1.0.4 (`skills/fireworks-tech-graph/docs/releases/v1.0.4.md`) Copy Section

Fireworks Tech Graph v1.0.4

This patch release documented a deterministic update path for existing Skill installations.

Version information Copy Chapter

• Version: v1.0.4 / npm 1.0.4
• Version date: 2026-04-12; npm published at 2026-04-12T13:32:37.231Z
• Tag commit: c8668407, whose versioned content matches the npm tarball
• npm registry gitHead: c3726124
• Previous version: v1.0.3
• Runtime metadata: Node.js 14 or newer
• Distribution: npm package 1.0.4; this remains the npm registry's latest version for the legacy package line

Highlights Copy Chapter

• Added npx skills add yizhiyanhua-ai/fireworks-tech-graph --force -g -y as the documented update command.
• Synchronized the update workflow across the English README, Chinese README, and Skill instructions.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. npm 1.0.4 was published 11 seconds before the matching repository commit, so the registry retained the preceding gitHead. The historical tag uses the subsequent commit because its README, Chinese README, Skill instructions, and package.json match the published versioned content.

Skills Fireworks Tech Graph Docs Releases V1.0.5 (`skills/fireworks-tech-graph/docs/releases/v1.0.5.md`) Copy Section

Fireworks Tech Graph v1.0.5

This repository release consolidated three months of diagram-quality work and made the Skill directly usable by both Codex and Claude Code.

Version information Copy Chapter

• Version: v1.0.5
• Version date: 2026-07-11
• Tag commit: 14be3ad3, the mainline merge of version commit 55916c55; both have the same tree
• Previous version: v1.0.4
• Runtime metadata: Node.js 14 or newer
• Distribution: repository version only; npm publishing stopped at 1.0.4

Highlights Copy Chapter

• Added shared Codex and Claude Code metadata, instructions, compatibility tests, and installation paths.
• Added Style 8 Dark Luxury while preserving the seven original style contracts.
• Added a bounded generate-validate-repair loop, structural SVG checks, and optional visual self-review.
• Improved connector routing, label placement, overlap prevention, filter and viewport clipping guidance, and CJK font fallbacks.
• Switched the default PNG renderer to CairoSVG, hardened helper scripts, and documented renderer edge cases.
• Added the first GitHub Pages product showcase.

Provenance Copy Chapter

This GitHub Release was backfilled on 2026-07-17. Unlike npm versions 1.0.0 through 1.0.4, the v1.0.5 tag points to a committed mainline tree whose package.json declares 1.0.5; no npm 1.0.5 package was published.

Skills Fireworks Tech Graph Docs Releases V1.1.0 (`skills/fireworks-tech-graph/docs/releases/v1.1.0.md`) Copy Section

Fireworks Tech Graph v1.1.0

This release turns the project into an engineering-grade diagram system while preserving the distinct scenarios and visual identity of all 12 styles.

Version information Copy Chapter

• Version: v1.1.0
• Version date: 2026-07-15
• Tag commit: 1c7ba0fe
• Previous version: v1.0.5
• Release channel: GitHub stable release; the npm registry remains on the legacy 1.0.4 package line.

Highlights Copy Chapter

• Adds Style 9 C4 Review Canvas, Style 10 Cloud Fabric, Style 11 Event Transit, and Style 12 Ops Pulse.
• Enforces semantic contracts for C4 abstraction, deployment ownership, event rails, Golden Signals, observation windows, critical paths, and correlated traces.
• Adds geometry-safe orthogonal routing, port fan-out, waypoint validation, label and reserved-region checks, bridge masks, and fail-closed composition gates.
• Adds a unified CLI, versioned Diagram IR, deterministic layout reports, and safe offline interactive HTML export.
• Refreshes the official gallery with 12 distinct engineering scenarios and fixed-width 1920px regression renders.
• Ships a complete nested Agent Skill payload for Codex and Claude Code, plus reproducible tgz/zip archives and SHA256SUMS.

Compatibility Copy Chapter

• Node.js 18 or newer is required.
• Python source compatibility is checked against Python 3.9 grammar; CI runs the test suite on Python 3.9 and 3.12.
• The npm registry is a separate distribution channel and may lag this GitHub Release. Install the current Skill from yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph.

See the v1.1.0 changelog for the full change list and the release assets below for checksum-verified archives.

Skills Fireworks Tech Graph Docs Releases V1.2.0 (`skills/fireworks-tech-graph/docs/releases/v1.2.0.md`) Copy Section

Fireworks Tech Graph v1.2.0

This release adds a focused, production-validated SVG-to-GIF workflow while preserving the twelve distinct diagram styles and their engineering scenarios.

Version information Copy Chapter

• Version: v1.2.0
• Version date: 2026-07-17
• Tag commit: ea534c2d
• Previous version: v1.1.0
• Release channel: latest GitHub stable release; the npm registry remains on the legacy 1.0.4 package line.

Highlights Copy Chapter

• Adds user-approved semantic motion contracts for all 12 styles: connectors start absent, build in semantic order, then keep the completed topology alive with style-specific data flow.
• Makes the 5.75-second / 115-frame settled-flow timeline the default for natural-language GIF requests, while retaining explicit 3.75-second and 2.75-second compatibility timelines.
• Replaces every README showcase image with an approved GIF, including a synchronized 3×4 overview optimized below 2 MiB. Static 1920px PNGs remain available as regression baselines.
• Refreshes the GitHub Pages product site with the animated overview and all twelve per-style GIFs, while retaining static Open Graph media and reduced-motion fallbacks.
• Adds source-DOM immutability guards, bounded runtime probes, secure Puppeteer resolution, atomic GIF/report installation, FFprobe media checks, binary infinite-loop readback, and motion reports.
• Validates all 12 installed Skill styles in CI and before tag releases, including 852 Chromium compatibility comparisons across the extended timeline.
• Keeps motion reusable for valid title and content changes: the semantic topology, route roles, directions, stages, geometry, and style signature are pinned; the exact source SVG bytes are not.
• Includes the post-v1.1.0 SVG validator fixes for multi-subpath geometry and transformed bounds.

Compatibility Copy Chapter

• Python 3.9 or newer is required.
• Node.js 18 or newer is required for the optional Chromium motion renderer.
• GIF generation requires FFmpeg and [email protected]; static SVG/PNG/HTML workflows continue to work without them.
• The npm registry is a separate distribution channel and may lag the GitHub Release. Install the current Skill from yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph.

See the v1.2.0 changelog for the full change list and the release assets below for checksum-verified archives.

--- METRICS ---

• Files Extracted: 28
• Estimated Token Budget: ~33299 tokens
• Canonical Reference: https://codewiki.google/github.com/yizhiyanhua-ai/fireworks-tech-graph