@drunkcoding/agents-and-skills 0.0.44 → 0.0.46

package/plugins/tech-graph/skills/tech-graph/SKILL.md

@@ -1,263 +0,0 @@
----
-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 <svg-file>
-```
-- 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: `<rect fill="canvas_bg" opacity="0.95"/>` 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 `<style>font-family: ...</style>` — no external `@import` (cairosvg / rsvg-convert cannot fetch external URLs)
-- `<defs>`: arrow markers, gradients, filters, clip paths
-- Text: minimum 12px, prefer 13-14px labels, 11px sub-labels, 16-18px titles
-- All arrows: `<marker>` with `markerEnd`, sized `markerWidth="10" markerHeight="7"`
-- Drop shadows: `<feDropShadow>` in `<filter>`, 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 `<clipPath>` if text might overflow a node box
-
-## SVG Generation & Error Prevention
-
-**MANDATORY: Python List Method** (ALWAYS use this):
-```python
-python3 << 'EOF'
-lines = []
-lines.append('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 700">')
-lines.append('  <defs>')
-# ... each line separately
-lines.append('</svg>')
-
-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 `</svg>` 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)

package/plugins/tech-graph/skills/tech-graph/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Fireworks Tech Graph"
-  short_description: "Generate polished SVG and PNG technical diagrams"
-  default_prompt: "Turn the user's system or workflow description into a polished SVG diagram and export a PNG."

package/plugins/tech-graph/skills/tech-graph/fixtures/agent-memory-types-style4.json

@@ -1,181 +0,0 @@
-{
-  "template_type": "memory",
-  "style": 4,
-  "width": 1120,
-  "height": 760,
-  "title": "Agent Memory Types",
-  "subtitle": "Five memory systems an AI agent can use — characteristics, storage backends, and persistence",
-  "containers": [
-    {
-      "x": 18,
-      "y": 32,
-      "width": 1084,
-      "height": 696,
-      "label": "",
-      "subtitle": "",
-      "stroke": "#e5e7eb",
-      "fill": "none",
-      "rx": 6
-    }
-  ],
-  "nodes": [
-    {
-      "id": "sensory",
-      "kind": "rect",
-      "x": 56,
-      "y": 118,
-      "width": 266,
-      "height": 106,
-      "label": "Raw input, very short-lived",
-      "sublabel": "\"Current image / audio\"",
-      "type_label": "SENSORY MEMORY",
-      "fill": "#ffffff",
-      "stroke": "#e5e7eb",
-      "flat": true,
-      "tags": [
-        { "label": "RAM / context", "fill": "#eff6ff", "stroke": "#bfdbfe", "text_fill": "#3b82f6" }
-      ]
-    },
-    {
-      "id": "working",
-      "kind": "rect",
-      "x": 56,
-      "y": 308,
-      "width": 266,
-      "height": 106,
-      "label": "Active context, session-scoped",
-      "sublabel": "\"Current conversation\"",
-      "type_label": "WORKING MEMORY",
-      "fill": "#ffffff",
-      "stroke": "#e5e7eb",
-      "flat": true,
-      "tags": [
-        { "label": "Context Window", "fill": "#eff6ff", "stroke": "#bfdbfe", "text_fill": "#3b82f6" }
-      ]
-    },
-    {
-      "id": "episodic",
-      "kind": "rect",
-      "x": 56,
-      "y": 498,
-      "width": 266,
-      "height": 106,
-      "label": "Past interactions, retrievable",
-      "sublabel": "\"Last week's chat summary\"",
-      "type_label": "EPISODIC MEMORY",
-      "fill": "#ffffff",
-      "stroke": "#e5e7eb",
-      "flat": true,
-      "tags": [
-        { "label": "Vector DB + timestamp", "fill": "#eff6ff", "stroke": "#bfdbfe", "text_fill": "#3b82f6" }
-      ]
-    },
-    {
-      "id": "agent",
-      "kind": "hexagon",
-      "x": 492,
-      "y": 324,
-      "width": 118,
-      "height": 90,
-      "label": "Agent",
-      "sublabel": "LLM + Planner",
-      "type_label": "CORE",
-      "fill": "#ffffff",
-      "stroke": "#3b82f6",
-      "stroke_width": 1.6,
-      "flat": true
-    },
-    {
-      "id": "semantic",
-      "kind": "rect",
-      "x": 810,
-      "y": 218,
-      "width": 266,
-      "height": 106,
-      "label": "Facts & knowledge, long-term",
-      "sublabel": "\"User prefers Python\"",
-      "type_label": "SEMANTIC MEMORY",
-      "fill": "#ffffff",
-      "stroke": "#e5e7eb",
-      "flat": true,
-      "tags": [
-        { "label": "Vector DB + Graph DB", "fill": "#eff6ff", "stroke": "#bfdbfe", "text_fill": "#3b82f6" }
-      ]
-    },
-    {
-      "id": "procedural",
-      "kind": "rect",
-      "x": 810,
-      "y": 408,
-      "width": 266,
-      "height": 106,
-      "label": "Skills & how-to, persistent",
-      "sublabel": "\"How to call Stripe API\"",
-      "type_label": "PROCEDURAL MEMORY",
-      "fill": "#ffffff",
-      "stroke": "#e5e7eb",
-      "flat": true,
-      "tags": [
-        { "label": "Code store / fine-tune", "fill": "#eff6ff", "stroke": "#bfdbfe", "text_fill": "#3b82f6" }
-      ]
-    }
-  ],
-  "arrows": [
-    {
-      "source": "agent",
-      "target": "sensory",
-      "source_port": "left",
-      "target_port": "right",
-      "flow": "read",
-      "label": "read/write",
-      "route_points": [[432, 360], [386, 360], [386, 172], [322, 172]],
-      "label_dx": -18,
-      "label_dy": -8
-    },
-    {
-      "source": "agent",
-      "target": "working",
-      "source_port": "left",
-      "target_port": "right",
-      "flow": "read",
-      "label": "read/write",
-      "route_points": [[432, 369], [404, 369], [322, 360]],
-      "label_dx": -6,
-      "label_dy": -6
-    },
-    {
-      "source": "agent",
-      "target": "episodic",
-      "source_port": "left",
-      "target_port": "right",
-      "flow": "read",
-      "label": "read/write",
-      "route_points": [[432, 394], [386, 430], [386, 552], [322, 552]],
-      "label_dx": -18,
-      "label_dy": -6
-    },
-    {
-      "source": "agent",
-      "target": "semantic",
-      "source_port": "right",
-      "target_port": "left",
-      "flow": "read",
-      "label": "read/write",
-      "route_points": [[668, 360], [726, 360], [726, 271], [810, 271]],
-      "label_dx": 10,
-      "label_dy": -8
-    },
-    {
-      "source": "agent",
-      "target": "procedural",
-      "source_port": "right",
-      "target_port": "left",
-      "flow": "read",
-      "label": "read/write",
-      "route_points": [[668, 388], [740, 404], [810, 461]],
-      "label_dx": 8,
-      "label_dy": -8
-    }
-  ],
-  "footer": ""
-}

package/plugins/tech-graph/skills/tech-graph/fixtures/api-flow-style7.json

@@ -1,40 +0,0 @@
-{
-  "template_type": "architecture",
-  "style": 7,
-  "width": 1100,
-  "height": 680,
-  "title": "API Integration Flow",
-  "subtitle": "OpenAI-style clean integration diagram with precise control and response stages",
-  "containers": [
-    { "x": 40, "y": 118, "width": 1020, "height": 104, "label": "ENTRY", "subtitle": "", "stroke": "#e2e8f0", "fill": "none" },
-    { "x": 40, "y": 252, "width": 1020, "height": 154, "label": "MODEL + TOOLS", "subtitle": "", "stroke": "#e2e8f0", "fill": "none" },
-    { "x": 40, "y": 438, "width": 1020, "height": 154, "label": "DELIVERY", "subtitle": "", "stroke": "#e2e8f0", "fill": "none" }
-  ],
-  "nodes": [
-    { "id": "app", "kind": "rect", "x": 90, "y": 146, "width": 176, "height": 56, "label": "Application", "type_label": "CLIENT", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true },
-    { "id": "sdk", "kind": "double_rect", "x": 350, "y": 142, "width": 196, "height": 64, "label": "OpenAI SDK Layer", "type_label": "SDK", "fill": "#ffffff", "stroke": "#10a37f" },
-    { "id": "prompt", "kind": "rect", "x": 114, "y": 300, "width": 188, "height": 60, "label": "Prompt Builder", "type_label": "INPUT", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true },
-    { "id": "model", "kind": "double_rect", "x": 418, "y": 292, "width": 236, "height": 76, "label": "Model Runtime", "type_label": "REASONING", "fill": "#ffffff", "stroke": "#10a37f" },
-    { "id": "tools", "kind": "rect", "x": 782, "y": 300, "width": 188, "height": 60, "label": "Tool Calls", "type_label": "ACTIONS", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true },
-    { "id": "formatter", "kind": "rect", "x": 148, "y": 486, "width": 198, "height": 60, "label": "Response Formatter", "type_label": "OUTPUT", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true },
-    { "id": "obs", "kind": "rect", "x": 470, "y": 486, "width": 176, "height": 60, "label": "Observability", "type_label": "METRICS", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true },
-    { "id": "release", "kind": "rect", "x": 770, "y": 486, "width": 176, "height": 60, "label": "Release Control", "type_label": "CONFIG", "fill": "#ffffff", "stroke": "#dce5e3", "flat": true }
-  ],
-  "arrows": [
-    { "source": "app", "target": "sdk", "source_port": "right", "target_port": "left", "flow": "control" },
-    { "source": "sdk", "target": "prompt", "source_port": "bottom", "target_port": "top", "flow": "read", "label": "prepare", "route_points": [[370,232], [236,232], [236,300]] },
-    { "source": "sdk", "target": "model", "source_port": "bottom", "target_port": "top", "flow": "control", "corridor_x": [520] },
-    { "source": "model", "target": "tools", "source_port": "right", "target_port": "left", "flow": "read", "label": "tool use" },
-    { "source": "model", "target": "formatter", "source_port": "bottom", "target_port": "top", "flow": "control", "corridor_x": [278] },
-    { "source": "model", "target": "obs", "source_port": "bottom", "target_port": "top", "flow": "feedback", "dashed": true },
-    { "source": "obs", "target": "release", "source_port": "right", "target_port": "left", "flow": "control" }
-  ],
-  "legend": [
-    { "flow": "control", "label": "Primary integration path" },
-    { "flow": "read", "label": "Prompt / tool context" },
-    { "flow": "feedback", "label": "Operational feedback" }
-  ],
-  "legend_position": "bottom-left",
-  "legend_y": 612,
-  "footer": ""
-}