--- name: tech-graph description: >- Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated. --- # Tech Graph Generate production-quality SVG technical diagrams exported as PNG via `cairosvg` (recommended), `rsvg-convert`, or `puppeteer`. ## Helper Scripts (Recommended) Four helper scripts in `scripts/` directory provide stable SVG generation and validation: ### 1. `generate-diagram.sh` - Validate SVG + export PNG ```bash ./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg ``` - Validates an existing SVG file - Exports PNG after validation - Example: `./scripts/generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg` ### 2. `generate-from-template.py` - Create starter SVG from template ```bash python3 ./scripts/generate-from-template.py architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}' ``` - Loads a built-in SVG template - Renders nodes, arrows, and legend entries from JSON input - Escapes text content to keep output XML-valid ### 3. `validate-svg.sh` - Validate SVG syntax ```bash ./scripts/validate-svg.sh ``` - Checks XML syntax - Verifies tag balance - Validates marker references - Checks attribute completeness - Validates path data ### 4. `test-all-styles.sh` - Batch test all styles ```bash ./scripts/test-all-styles.sh ``` - Tests multiple diagram sizes - Validates all generated SVGs - Generates test report **When to use scripts:** - Use scripts when generating complex SVGs to avoid syntax errors - Scripts provide automatic validation and error reporting - Recommended for production diagrams **When to generate SVG directly:** - Simple diagrams with few elements - Quick prototypes - When you need full control over SVG structure ## Workflow (Always Follow This Order) 1. **Classify** the diagram type (see Diagram Types below) 2. **Extract structure** — identify layers, nodes, edges, flows, and semantic groups from user description 3. **Plan layout** — apply the layout rules for the diagram type 4. **Load style reference** — always load [style-1-flat-icon](references/style-1-flat-icon.md) unless user specifies another; load the matching style-N file (e.g. [style-2-dark-terminal](references/style-2-dark-terminal.md), [style-3-blueprint](references/style-3-blueprint.md), [style-4-notion-clean](references/style-4-notion-clean.md), [style-5-glassmorphism](references/style-5-glassmorphism.md), [style-6-claude-official](references/style-6-claude-official.md), [style-7-openai](references/style-7-openai.md)) for exact color tokens and SVG patterns 5. **Map nodes to shapes** — use Shape Vocabulary below 6. **Check icon needs** — load [icons](references/icons.md) for known products 7. **Write SVG** with adaptive strategy (see SVG Generation Strategy below) 8. **Validate**: Run `python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')"` to check XML syntax 9. **Export PNG**: Use `cairosvg` (recommended). See **SVG → PNG Conversion** section below for full method comparison 10. **Report** the generated file paths 11. **(Optional) Visual self-review** — if your runtime can read images, load the exported PNG back and inspect it. Syntactic validity does not guarantee visual correctness: arrows may cross through component interiors, labels may collide with lifelines or other labels, boxes may overlap, alt-frame text may sit on top of a message, or a legend may cover content. If you see any of these, revise the SVG and re-export; repeat until the rendered image is clean. Common fixes: - Route arrows through gaps between boxes, not through box interiors - Add background rects behind arrow labels (opacity 0.95, matching canvas color) - Widen inter-row/inter-column gutters so same-layer arrows have clear corridors - Collapse repeated cross-layer arrows into a single "delegates down" rail outside the content area - Move legend/notes out of any region where arrows or labels land - Increase viewBox height/width rather than packing elements tighter Skip this step silently if image reading is unavailable — do not guess. ## Diagram Types & Layout Rules Per-type layout rules + UML coverage map: see [diagram-types](references/diagram-types.md). Covers Architecture, Data Flow, Flowchart, Agent, Memory, Sequence, Comparison, Timeline, Mind Map, Class (UML), Use Case (UML), State Machine (UML), ER, Network Topology, plus full UML-14 mapping. ## Shape Vocabulary Map semantic concepts to consistent shapes across all diagram types: | Concept | Shape | Notes | |---------|-------|-------| | User / Human | Circle + body path | Stick figure or avatar | | LLM / Model | Rounded rect with brain/spark icon or gradient fill | Use accent color | | Agent / Orchestrator | Hexagon or rounded rect with double border | Signals "active controller" | | Memory (short-term) | Rounded rect, dashed border | Ephemeral = dashed | | Memory (long-term) | Cylinder (database shape) | Persistent = solid cylinder | | Vector Store | Cylinder with grid lines inside | Add 3 horizontal lines | | Graph DB | Circle cluster (3 overlapping circles) | | | Tool / Function | Gear-like rect or rect with wrench icon | | | API / Gateway | Hexagon (single border) | | | Queue / Stream | Horizontal tube (pipe shape) | | | File / Document | Folded-corner rect | | | Browser / UI | Rect with 3-dot titlebar | | | Decision | Diamond | Flowcharts only | | Process / Step | Rounded rect | Standard box | | External Service | Rect with cloud icon or dashed border | | | Data / Artifact | Parallelogram | I/O in flowcharts | ## Arrow Semantics Always assign arrow meaning, not just color: | Flow Type | Color | Stroke | Dash | Meaning | |-----------|-------|--------|------|---------| | Primary data flow | blue `#2563eb` | 2px solid | none | Main request/response path | | Control / trigger | orange `#ea580c` | 1.5px solid | none | One system triggering another | | Memory read | green `#059669` | 1.5px solid | none | Retrieval from store | | Memory write | green `#059669` | 1.5px | `5,3` | Write/store operation | | Async / event | gray `#6b7280` | 1.5px | `4,2` | Non-blocking, event-driven | | Embedding / transform | purple `#7c3aed` | 1px solid | none | Data transformation | | Feedback / loop | purple `#7c3aed` | 1.5px curved | none | Iterative reasoning loop | Always include a **legend** when 2+ arrow types are used. ## Layout Rules & Validation **Spacing**: - Same-layer nodes: 80px horizontal, 120px vertical between layers - Canvas margins: 40px minimum, 60px between node edges - Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals **Arrow Labels** (CRITICAL): - MUST have background rect: `` with 4px horizontal, 2px vertical padding - Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge - Maintain 10px safety distance from nodes **Arrow Routing**: - Prefer orthogonal (L-shaped) paths to minimize crossings - Anchor arrows on component edges, not geometric centers - Route around dense node clusters, use different y-offsets for parallel arrows - Jump-over arcs (5px radius) for unavoidable crossings **Line Overlap Prevention** (CRITICAL - most common bug on Codex): When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap: - Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line - SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top - Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other - Never let two arrows' straight-line segments cross without a jump-over arc **Validation Checklist** (run before finalizing): 1. **Arrow-Component Collision**: Arrows MUST NOT pass through component interiors (route around with orthogonal paths) 2. **Text Overflow**: All text MUST fit with 8px padding (estimate: `text.length × 7px ≤ shape_width - 16px`) 3. **Arrow-Text Alignment**: Arrow endpoints MUST connect to shape edges (not floating); all arrow labels MUST have background rects 4. **Container Discipline**: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies ## SVG Technical Rules - ViewBox: `0 0 960 600` default; `0 0 960 800` tall; `0 0 1200 600` wide - Fonts: embed via `` — no external `@import` (cairosvg / rsvg-convert cannot fetch external URLs) - ``: arrow markers, gradients, filters, clip paths - Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles - All arrows: `` with `markerEnd`, sized `markerWidth="10" markerHeight="7"` - Drop shadows: `` in ``, apply sparingly (key nodes only) - Curved paths: use `M x1,y1 C cx1,cy1 cx2,cy2 x2,y2` cubic bezier for loops/feedback arrows - Clip content: use `` if text might overflow a node box ## SVG Generation & Error Prevention **MANDATORY: Python List Method** (ALWAYS use this): ```python python3 << 'EOF' lines = [] lines.append('') lines.append(' ') # ... each line separately lines.append('') with open('/path/to/output.svg', 'w') as f: f.write('\n'.join(lines)) print("SVG generated successfully") EOF ``` **Why mandatory**: Prevents character truncation, typos, and syntax errors. Each line is independent and easy to verify. **Pre-Tool-Call Checklist** (CRITICAL - use EVERY time): 1. ✅ Can I write out the COMPLETE command/content right now? 2. ✅ Do I have ALL required parameters ready? 3. ✅ Have I checked for syntax errors in my prepared content? **If ANY answer is NO**: STOP. Do NOT call the tool. Prepare the content first. **Error Recovery Protocol**: - **First error**: Analyze root cause, apply targeted fix - **Second error**: Switch method entirely (Python list → chunked generation) - **Third error**: STOP and report to user - do NOT loop endlessly - **Never**: Retry the same failing command or call tools with empty parameters **Validation** (run after generation): ```bash python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')" && echo "✓ Valid XML" # Or use cairosvg as a render-time check: python3 -c "import cairosvg; cairosvg.svg2png(url='file.svg', write_to='/tmp/test.png')" && echo "✓ Renders" && rm /tmp/test.png ``` **If using `generate-from-template.py`**: - Prefer `source` / `target` node ids in arrow JSON so the generator can snap to node edges - Keep `x1,y1,x2,y2` as hints or fallback coordinates, not the main routing primitive - Let the generator choose orthogonal routes; avoid hardcoding center-to-center straight lines unless the path is guaranteed clear **Common Syntax Errors to Avoid**: - ❌ `yt-anchor` → ✅ `y="60" text-anchor="middle"` - ❌ `x="390` (missing y) → ✅ `x="390" y="250"` - ❌ `fill=#fff` → ✅ `fill="#ffffff"` - ❌ `marker-end=` → ✅ `marker-end="url(#arrow)"` - ❌ `L 29450` → ✅ `L 290,220` - ❌ Missing `` at end ## Output - **Default**: `./[derived-name].svg` and `./[derived-name].png` in current directory - **Custom**: user specifies path with `--output /path/` or `输出到 /path/` - **PNG export**: see **SVG → PNG Conversion** below ## SVG → PNG Conversion Default `cairosvg` one-liner: ```bash python3 -c "import cairosvg; cairosvg.svg2png(url='input.svg', write_to='output.png', scale=2)" ``` Full method comparison (cairosvg / rsvg-convert / puppeteer), batch scripts, puppeteer renderer, and gotchas: see [svg-to-png](references/svg-to-png.md). ## Styles | # | Name | Background | Best For | |---|------|-----------|----------| | 1 | **Flat Icon** (default) | White | Blogs, docs, presentations | | 2 | **Dark Terminal** | `#0f0f1a` | GitHub, dev articles | | 3 | **Blueprint** | `#0a1628` | Architecture docs | | 4 | **Notion Clean** | White, minimal | Notion | | 5 | **Glassmorphism** | Dark gradient | Product sites, keynotes | | 6 | **Claude Official** | Warm cream `#f8f6f3` | Anthropic-style diagrams | | 7 | **OpenAI Official** | Pure white `#ffffff` | OpenAI-style diagrams | Load the matching style-N file in [references/](references/) for exact color tokens and SVG patterns. ## Style Selection **Default**: Style 1 (Flat Icon) for most diagrams. Load [style-diagram-matrix](references/style-diagram-matrix.md) for detailed style-to-diagram-type recommendations. These patterns appear frequently — internalize them: **RAG Pipeline**: Query → Embed → VectorSearch → Retrieve → Augment → LLM → Response **Agentic RAG**: adds Agent loop with Tool use between Query and LLM **Agentic Search**: Query → Planner → [Search Tool / Calculator / Code] → Synthesizer → Response **Mem0 / Memory Layer**: Input → Memory Manager → [Write: VectorDB + GraphDB] / [Read: Retrieve+Rank] → Context **Agent Memory Types**: Sensory (raw input) → Working (context window) → Episodic (past interactions) → Semantic (facts) → Procedural (skills) **Multi-Agent**: Orchestrator → [SubAgent A / SubAgent B / SubAgent C] → Aggregator → Output **Tool Call Flow**: LLM → Tool Selector → Tool Execution → Result Parser → LLM (loop)