@ia-ccun/code-agent-cli 0.0.47 → 0.0.49-beta.0

package/config/agent/skills/fireworks-tech-graph/references/style-7-openai.md

@@ -0,0 +1,215 @@
+# Style 7: OpenAI Official
+
+Clean, modern aesthetic matching OpenAI's documentation and research diagrams — minimal but precise.
+
+## Color Palette
+
+```
+Background:     #ffffff  (pure white)
+Primary text:   #0d0d0d  (near black)
+Secondary text: #6e6e80  (muted gray)
+Border:         #e5e5e5  (light gray)
+
+Accent colors (reserved):
+Green accent:   #10a37f  (OpenAI brand green)
+Blue accent:    #1d4ed8  (links, actions)
+Orange accent:  #f97316  (highlights, warnings)
+Gray accent:    #71717a  (secondary elements)
+```
+
+## Typography
+
+```
+font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica Neue, sans-serif
+font-size:   16px node labels, 13px descriptions, 12px arrow labels
+font-weight: 600 for titles, 500 for labels, 400 for descriptions
+letter-spacing: -0.01em (tight)
+```
+
+No custom fonts. System font stack only for maximum compatibility.
+
+## Node Boxes
+
+Clean, minimal boxes with subtle borders:
+
+```xml
+<!-- Standard node -->
+<rect x="100" y="100" width="180" height="80" rx="8" ry="8"
+      fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+
+<!-- Accent node (with green left border) -->
+<rect x="100" y="100" width="180" height="80" rx="8" ry="8"
+      fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+<rect x="100" y="100" width="4" height="80" rx="2" ry="2"
+      fill="#10a37f"/>
+```
+
+**Key techniques:**
+1. White fill with light gray border (no shadows)
+2. Optional colored left-border accent strip (4px wide)
+3. `rx="8"` for subtle rounding
+4. `stroke-width: 1.5` — thin, precise borders
+5. No gradients, no shadows, no decorative elements
+
+## Arrows
+
+Thin, precise arrows with subtle colors:
+
+```xml
+<defs>
+  <!-- Default arrow (gray) -->
+  <marker id="arrow-oai" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+    <polygon points="0 0, 10 3.5, 0 7" fill="#71717a"/>
+  </marker>
+
+  <!-- Accent arrow (green) -->
+  <marker id="arrow-oai-green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+    <polygon points="0 0, 10 3.5, 0 7" fill="#10a37f"/>
+  </marker>
+</defs>
+
+<!-- Default connection -->
+<line x1="280" y1="140" x2="400" y2="140"
+      stroke="#71717a" stroke-width="1.5" marker-end="url(#arrow-oai)"/>
+
+<!-- Accent connection -->
+<line x1="280" y1="140" x2="400" y2="140"
+      stroke="#10a37f" stroke-width="1.5" marker-end="url(#arrow-oai-green)"/>
+```
+
+**Arrow guidelines:**
+- Prefer straight lines (orthogonal routing with right angles)
+- `stroke-width: 1.5` — thin and precise
+- Filled polygon arrowheads (not stroke-based)
+- Gray for default, green for primary/accent flows
+- Dashed (`stroke-dasharray="4,3"`) for optional/async flows
+
+## Arrow Labels
+
+Minimal, small labels:
+
+```xml
+<text x="340" y="133" text-anchor="middle" fill="#6e6e80" font-size="12">
+  label
+</text>
+```
+
+Labels should be:
+- 12px, gray color (`#6e6e80`)
+- No background rect (white background is default)
+- Short, technical language
+- Midpoint of arrow
+
+## Database Shapes
+
+Clean cylinders with thin borders:
+
+```xml
+<ellipse cx="200" cy="100" rx="50" ry="12" fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+<path d="M 150,100 L 150,140 Q 200,155 250,140 L 250,100"
+      fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+<ellipse cx="200" cy="140" rx="50" ry="12" fill="none" stroke="#e5e5e5" stroke-width="1.5"/>
+```
+
+## Grouping Containers
+
+Dashed rect containers for logical grouping:
+
+```xml
+<rect x="80" y="80" width="400" height="200" rx="8" ry="8"
+      fill="none" stroke="#e5e5e5" stroke-width="1" stroke-dasharray="4,3"/>
+<text x="90" y="97" fill="#6e6e80" font-size="12" font-weight="500">
+  Group Label
+</text>
+```
+
+## Node Content
+
+Clean, minimal text layout:
+
+```xml
+<rect x="100" y="100" width="180" height="80" rx="8" ry="8"
+      fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+<text x="190" y="130" text-anchor="middle" fill="#0d0d0d"
+      font-size="16" font-weight="600">
+  Component Name
+</text>
+<text x="190" y="150" text-anchor="middle" fill="#6e6e80"
+      font-size="13">
+  Brief description
+</text>
+```
+
+**Content guidelines:**
+- 1-2 lines per box
+- Main label: 16px, font-weight: 600, near-black
+- Description: 13px, font-weight: 400, gray
+- Center-aligned text within boxes
+
+## Layout Principles
+
+**Precise, grid-aligned layout:**
+- Snap all coordinates to 8px grid
+- Consistent 100px horizontal spacing
+- Consistent 120px vertical spacing
+- Generous whitespace (40px+ margins)
+- No decorative elements
+
+**OpenAI minimalism:**
+- Only use color when semantically meaningful (brand green for primary flow)
+- White boxes on white background — differentiation through border and label only
+- Avoid: shadows, gradients, patterns, icons, decorative elements
+- Prefer: straight lines, orthogonal routing, thin strokes
+
+## SVG Template
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" width="960" height="600">
+  <style>
+    text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+  </style>
+  <defs>
+    <marker id="arrow-oai" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#71717a"/>
+    </marker>
+    <marker id="arrow-oai-green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#10a37f"/>
+    </marker>
+  </defs>
+
+  <!-- White background -->
+  <rect width="960" height="600" fill="#ffffff"/>
+
+  <!-- Title -->
+  <text x="480" y="30" text-anchor="middle" fill="#0d0d0d"
+        font-size="20" font-weight="600">Diagram Title</text>
+
+  <!-- Standard node -->
+  <rect x="100" y="70" width="180" height="80" rx="8" ry="8"
+        fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
+  <text x="190" y="100" text-anchor="middle" fill="#0d0d0d"
+        font-size="16" font-weight="600">Component</text>
+  <text x="190" y="120" text-anchor="middle" fill="#6e6e80"
+        font-size="13">Description</text>
+
+  <!-- Connection -->
+  <line x1="280" y1="110" x2="400" y2="110"
+        stroke="#71717a" stroke-width="1.5" marker-end="url(#arrow-oai)"/>
+  <text x="340" y="103" text-anchor="middle" fill="#6e6e80" font-size="12">label</text>
+</svg>
+```
+
+## Design Philosophy
+
+OpenAI Official style emphasizes:
+- **Minimalism**: White on white, only essential visual elements
+- **Precision**: Thin strokes, sharp corners (rx=8), grid-aligned
+- **Clarity**: Content-first, no visual noise
+- **Brand consistency**: `#10a37f` green used sparingly for primary flows
+
+Avoid:
+- Shadows and gradients
+- Colorful fills (white fill only)
+- Thick borders (>2px)
+- Decorative elements (icons, patterns, textures)
+- Custom fonts (system stack only)

package/config/agent/skills/fireworks-tech-graph/references/style-diagram-matrix.md

@@ -0,0 +1,135 @@
+# Style-to-Diagram-Type Adaptation Guide
+
+Not all styles work equally well for every diagram type. Use this guide to pick the best style.
+
+## Architecture Diagram
+| Style | Suitability | Notes |
+|-------|----------|
+| 1 Flat Icon | Excellent | Default choice; colorful node fills, clear layering |
+| 2 Dark Terminal | Excellent | Popular for dev blogs; use colored borders on dark bg |
+| 3 Blueprint | Excellent | Perfect for formal architecture docs |
+| 4 Notion Clean | Good | Minimal, works for inline docs |
+| 5 Glassmorphism | Good | Striking for presentations and product pages |
+| 6 Claude Official | Good | Warm aesthetic, Anthropic-style presentations |
+| 7 OpenAI Official | Good | Clean, precise; minimal borders, brand green accents |
+
+## Class Diagram / ER Diagram
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Good | Colored headers per class category |
+| 2 Dark Terminal | Good | High contrast for code-like diagrams |
+| 3 Blueprint | Excellent | Best for formal UML documentation |
+| 4 Notion Clean | Excellent | Clean, minimal; ideal for Notion-embedded diagrams |
+| 5 Glassmorphism | Poor | Glass effects distract from structural content |
+| 6 Claude Official | Excellent | Warm, readable; good for documentation |
+| 7 OpenAI Official | Excellent | Minimal aesthetic matches UML precision |
+
+## Sequence Diagram
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Good | Clear lifelines; activation boxes visible |
+| 2 Dark Terminal | Good | Good for dev articles; dashed lifelines visible |
+| 3 Blueprint | Excellent | Formal, technical documentation |
+| 4 Notion Clean | Excellent | Best for Notion-embedded sequence diagrams |
+| 5 Glassmorphism | Poor | Glass effects make lifelines hard to read |
+| 6 Claude Official | Excellent | Ward contrast |
+| 7 OpenAI Official | Excellent | Minimal, precise; ideal for API docs |
+
+## Flowchart / Process Flow
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Default; colorful decision diamonds |
+| 2 Dark Terminal | Good | Works well for dev workflow diagrams |
+| 3 Blueprint | Good | Formal process documentation |
+| 4 Notion Clean | Good | Clean for SOPs and inline docs |
+| 5 Glassmorphism | Good | Striking for product demos |
+| 6 Claude Official | Good | Warm aesthetic for presentations |
+| 7 OpenAI Official | Good | Clean and minimal |
+
+## Mind Map / Concept Map
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent branches, engaging |
+| 2 Dark Terminal | Good | Neon-like branches on dark bg |
+| 3 Blueprint | Poor | Blueprint grid conflicts with radial layout |
+| 4 Notion Clean | Excellent | Ideal for n brainstorming |
+| 5 Glassmorphism | Excellent | Stunning visual for presentations |
+| 6 Claude Official | Good | Warm, readable |
+| 7 OpenAI Official | Good | Clean and minimal |
+
+## Data Flow Diagram
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Color-coded arrows by data type |
+| 2 Dark Terminal | Excellent | Glowing data paths on dark bg |
+| 3 Blueprint | Excellent | Formal data flow documentation |
+| 4 Notion Clean | Good | Minimal, clean |
+| 5 Glassmorphism | Poor | Distracts from flow semantics |
+| 6 Claude Official | Good | Readable |
+| 7 OpenAI Official | Good | Precise, minimal |
+
+## Use Case Diagram
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Good | Colorful use case ellipses |
+| 2 Dark Terminal | Poor | Stick figures less visible on dark bg |
+| 3 rint | Excellent | Classic UML aesthetic |
+| 4 Notion Clean | Excellent | Perfect for product requirement docs |
+| 5 Glassmorphism | Poor | Unnecessary visual noise |
+| 6 Claude Official | Excellent | Warm, professional |
+| 7 OpenAI Official | Excellent | Clean, precise UML |
+
+## State Machine Diagram
+| Style | Suitability | Notes |
+|-------|------------|-------|
+Flat Icon | Good | Colorful states |
+| 2 Dark Terminal | Good | Glowing states and transitions |
+| 3 Blueprint | Excellent | Best for formal UML state machines |
+| 4 Notion Clean | Excellent | Clean for documentation |
+| 5 Glassmorphism | Poor | Distracts from state transitions |
+| 6 Claude Official | Excellent | Readable |
+| 7 OpenAI Official | Excellent | Minimal, precise |
+
+## Network Topology
+| Style | Suitabili |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Colorful device icons |
+| 2 Dark Terminal | Excellent | Cyberpunk-style network maps |
+| 3 Blueprint | Excellent | Ideal for infrastructure docs |
+| 4 Notion Clean | Good | Clean for IT documentation |
+| 5 Glassmorphism | Good | Striking for presentations |
+| 6 Claude Official | Good | Professional network diagrams |
+| 7 OpenAI Official | Good | Clean infrastructure diagrams |
+
+## Comparison / Feature Matrix
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Color-coded checkmarks |
+| 2 Dark Terminal | Good | Works for dev tool comparisons |
+| 3 Blor | Grid conflicts with table layout |
+| 4 Notion Clean | Excellent | Perfect for Notion-embedded tables |
+| 5 Glassmorphism | Poor | Distabular data |
+| 6 Claude Official | Excellent | Clean, warm |
+| 7 OpenAI Official | Excellent | Minimal, precise |
+
+## Timeline / Gantt
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Colorful bars by category |
+| 2 Dark Terminal | Good | Works for dev roadmaps |
+| 3 Blueprint | Good | Formal project plans |
+| 4 Notion Clean | Excellent | Ideal for Notion project docs |
+| 5 Glassmorphism | Good | Striking for keynote presentations |
+| 6 Claude Official | Good | Warm, professional |
+| 7 OpenAI Official | Good | Clean timeline |
+
+## Agent / Memory Architecture
+| Style | Suitability | Notes |
+|-------|------------|-------|
+| 1 Flat Icon | Excellent | Colorful layers, engaging |
+| 2 Dark Terminal | Excellent | Popular for AI/ML blog posts |
+| 3 Blueprint | Good | Formal AI system documentation |
+| 4 Notion Clean | Good | Clean for AI research notes |
+| 5 Glassmorphism | Excellent | Stunning for AI product presentations |
+| 6 Claude Official | Excellent | Anthropic AI aesthetic |
+| 7 OpenAI Official | Excellent | OpenAI AI aesthetic |

package/config/agent/skills/fireworks-tech-graph/references/svg-layout-best-practices.md

@@ -0,0 +1,100 @@
+# SVG Technical Diagram Layout Best Practices
+
+## Universal Layout Rules (Apply to All Styles)
+
+### 1. Component Spacing
+- **Minimum clearance between components**: 80px (edge to edge)
+- **Minimum clearance for arrow paths**: 60px from component edges
+- **Layer vertical spacing**: 120px between horizontal layers
+- **Same-layer horizontal spacing**: 100-120px between components
+
+### 2. Arrow Routing & Connection Points
+
+#### Connection Point Rules
+- **Never connect arrows to component corners** - use midpoints of edges
+- **Entry/exit points**: 
+  - Top edge: `cx ± offset` where offset = 0 for single arrow, ±30px for multiple
+  - Bottom edge: same rule
+  - Left/right edges: `cy ± offset`
+- **Clearance from corners**: minimum 20px
+
+#### Arrow Path Routing
+- **Avoid diagonal lines crossing components** - use orthogonal routing (L-shaped paths)
+- **For curved arrows**: 
+  - Control point should be at least 40px away from any component edge
+  - Use intermediate waypoints for complex routing: `M x1,y1 L x2,y2 Q cx,cy x3,y3`
+- **Multiple arrows between same layers**: stagger Y-coordinates by 15-20px to avoid overlap
+
+#### Arrow Overlap Prevention
+```svg
+<!-- Bad: diagonal arrow crosses component -->
+<path d="M 200,100 L 600,400"/>
+
+<!-- Good: orthogonal routing around component -->
+<path d="M 200,100 L 200,250 L 600,250 L 600,400"/>
+
+<!-- Good: curved with safe control point -->
+<path d="M 200,100 Q 400,200 600,400"/>
+<!-- Control point (400,200) is 50px+ away from any component -->
+```
+
+### 3. Arrow Label Placement
+- **Position**: midpoint of arrow path, offset by 5-10px perpendicular to arrow direction
+- **Background rect**: ALWAYS include, with:
+  - Padding: 4px horizontal, 2px vertical
+  - Fill: match ckground color
+  - Opacity: 0.9-0.95
+- **Safety distance**: 15px minimum from any component edge
+- **Multiple converging arrows**: stagger label positions vertically by 20px
+
+### 4. Component Overlap Detection
+Before finalizing SVG, check:
+- No component bounding boxes overlap px safety margin)
+- No arrow paths pass through component interiors (except intentional tunneling with dashed style)
+- No text labels overlap with components or other labels
+
+### 5. Z-Index Layering (SVG render order)
+```svg
+<!-- Render order (top to bot back to front): -->
+1. Background rect
+2. Grouping coners (dashed rects)
+3. Arrow paths
+4. Arrow label background rects
+5. Components (boxes, cylinders, etc.)
+6. Component text
+7. Arrow label text
+8. Legend
+```
+
+## Style-Specific Enhancements
+
+### Style-1: Flat Icon Clean- **Perfect alignment**: snap all coordinates to 8px grid
+- **Sharp corners**: rx="8" ry="8" for rounded rects (consistent)
+- **Arrows**: thin (1.5-2px), filled polygon markers
+- **No shadows**: flat design principle
+
+### Style-6: Claude Official Warm
+- **Soft shadows**: `<feDropShadow dx="0" dy="2" stdDeviation="6" flood-color="#00000008"/>`
+- **Rounded corners**: rx="12" ry="12" (more rounded than Style-1)
+- **Arrows**: medium weight (2px), subtle markers
+
+## Validation Checklist
+
+Before exporting PNG, verify:
+- [ ] No arrow-component overlaps (visual inspection)
+- [ ] All arrow labels have background rects
+- [ ] Minimum 60px clearance for all arrow paths
+- [ ] Component spacing ≥ 80px
+- [ ] Arrow connection points avoid corners (≥20px from corner)
+- [ ] Multiple arrows between layers are staggered
+- [ ] Legend is readable and doesn't overlap content
+- [ ] SVG validates with `rsvg-convert`
+
+## Common Anti-Patterns to Avoid
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Arrow crosses component | Use orthogonal routingase control point distancelabel overlaps component | Add background rect + increase offset |
+| Components too close | Increase spacing to 80px minimum |
+| Arrow connects to corner | Move connection point to edge midpoint offset |
+| No z-index planning | Follow render order: arrows -> components -> text |

package/config/agent/skills/fireworks-tech-graph/scripts/README.md

@@ -0,0 +1,244 @@
+# Fireworks Tech Graph - Scripts
+
+辅助脚本集合，用于提高 SVG 图表生成的稳定性和效率。
+
+## 脚本列表
+
+### 1. validate-svg.sh
+
+SVG 验证脚本，检查 SVG 语法并报告详细错误。
+
+**用法：**
+```bash
+./validate-svg.sh <svg-file>
+```
+
+**检查项目：**
+- 标签平衡（开标签 vs 闭标签）
+- 属性引号完整性
+- 特殊字符转义
+- Marker 引用完整性
+- 闭合标签 `</svg>`
+- rsvg-convert 验证
+
+**示例：**
+```bash
+./validate-svg.sh /path/to/diagram.svg
+```
+
+### 2. generate-diagram.sh
+
+SVG 图表生成脚本，提供自动验证和 PNG 导出。
+
+**用法：**
+```bash
+./generate-diagram.sh [OPTIONS]
+```
+
+**选项：**
+- `-t, --type TYPE` - 图表类型（见脚本帮助）
+- `-s, --style STYLE` - 风格编号（1-7，默认：1）
+- `-o, --output PATH` - 输出路径（默认：当前目录）
+- `-w, --width WIDTH` - PNG 宽度（像素，默认：1920）
+- `--no-validate` - 跳过验证
+- `-h, --help` - 显示帮助
+
+**示例：**
+```bash
+# 生成架构图（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
+
+基于风格配置和 JSON 数据生成 SVG。当前版本不再只是简单塞入 `nodes/arrows`，
+而是会执行 style guide 中的部分可计算规则，例如：
+
+- `style` - 风格编号（1-7）
+- `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
+
+**用法：**
+```bash
+python3 ./generate-from-template.py architecture ./output/arch.svg '{"style":1,"title":"My Diagram","containers":[],"nodes":[],"arrows":[]}'
+```
+
+**示例：**
+```bash
+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
+
+批量测试脚本，测试 7 种风格的回归样例图。
+
+**用法：**
+```bash
+./test-all-styles.sh
+```
+
+**功能：**
+- 检查所有风格的参考文件
+- 渲染 `fixtures/*.json` 回归样例
+- 验证生成出的 SVG 文件
+- 导出 PNG 文件到 `test-output/` 目录
+- 生成测试报告
+
+**输出：**
+- 测试摘要（通过/失败统计）
+- PNG 文件（带时间戳）
+- 详细的验证错误信息
+
+**示例：**
+```bash
+./test-all-styles.sh
+```
+
+## 依赖
+
+所有脚本需要以下工具：
+
+- **rsvg-convert** - SVG 转 PNG
+  ```bash
+  brew install librsvg
+  ```
+
+- **grep, sed, awk** - 文本处理（macOS 自带）
+
+## 目录结构
+
+```
+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
+│   └── test-all-styles.sh     # 批量测试
+└── test-output/               # 测试输出目录（自动创建）
+```
+
+## 使用场景
+
+### 场景 1：验证现有 SVG
+
+```bash
+cd ~/.claude/skills/fireworks-tech-graph/scripts
+./validate-svg.sh /path/to/your-diagram.svg
+```
+
+### 场景 2：生成并验证图表
+
+1. 使用 Claude Code 生成 SVG 内容
+2. 运行验证和导出：
+   ```bash
+   ./generate-diagram.sh -t architecture -s 1 -o ./output/arch.svg
+   ```
+
+### 场景 3：批量测试所有风格
+
+```bash
+cd ~/.claude/skills/fireworks-tech-graph/scripts
+./test-all-styles.sh
+```
+
+测试脚本会自动：
+1. 读取 `../fixtures/*.json`
+2. 按 `template_type + style` 调用 `generate-from-template.py`
+3. 运行 `validate-svg.sh`
+4. 导出 PNG 到 `../test-output/`
+
+查看测试输出：
+```bash
+ls -lh ../test-output/
+```
+
+## 故障排除
+
+### 问题：rsvg-convert 未找到
+
+**解决方案：**
+```bash
+brew install librsvg
+```
+
+### 问题：权限被拒绝
+
+**解决方案：**
+```bash
+chmod +x *.sh
+```
+
+### 问题：SVG 验证失败
+
+**解决方案：**
+1. 查看详细错误信息
+2. 使用 Edit 工具修复语法错误
+3. 重新运行验证
+
+## 开发说明
+
+### 添加新的验证规则
+
+编辑 `validate-svg.sh`，在现有检查项后添加新的检查逻辑：
+
+```bash
+# 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
+```
+
+### 扩展支持的图表类型
+
+编辑 `generate-diagram.sh`，在 `--type` 参数处理中添加新类型。
+
+## 版本历史
+
+- **v1.0.0** (2026-04-11) - 初始版本
+  - SVG 验证脚本
+  - 图表生成脚本
+  - 批量测试脚本
+
+## 许可证
+
+MIT License - 与 fireworks-tech-graph skill 相同