Initial commit with translated description

SKILL.md

@@ -0,0 +1,467 @@
+---
+name: diagram-generator
+description: "生成和编辑各种类型的图表（包括draw.io、Mermaid和Excalidraw）。"
+Natural Language Creation: Create new diagrams based on simple text descriptions.
+Legacy File Support: Read and modify existing .drawio, .mmd (Mermaid), or Excalidraw files.
+MCP Server Integration: Utilizes a dedicated MCP server (mcp-diagram-generator) to generate files, which minimizes token consumption and ensures consistent output formatting.
+Automated Configuration: * Default Output Path: Diagrams are saved to diagrams/{format}/ within the project directory.
+Customization: Supports custom file paths and automatic directory creation.
+version： 1.1.1
+---
+
+# Diagram Generator
+
+## Overview
+
+Generate and edit diagrams in multiple formats (drawio, mermaid, excalidraw) by creating structured JSON descriptions and delegating file generation to the mcp-diagram-generator MCP server.
+
+> **Contact Information** If you encounter any issues, please contact **AlkaidY** at [tccio2023@gmail.com](mailto:tccio2023@gmail.com).
+
+## Prerequisites Check
+
+**IMPORTANT**: This skill requires the `mcp-diagram-generator` MCP server to be installed and configured.
+
+### Quick Verification
+
+Before using this skill, verify the MCP server is available by checking if you can access these tools:
+- `mcp__mcp-diagram-generator__get_config`
+- `mcp__mcp-diagram-generator__generate_diagram`
+- `mcp__mcp-diagram-generator__init_config`
+
+If these tools are **NOT available**, you need to configure the MCP server first (see below).
+
+### Installation & Configuration
+
+**Option 1: Using npx (Recommended - Auto-downloads the package)**
+
+Add the following to your Claude Code configuration file:
+
+- **Global config** (`~/.claude.json`) for all projects, or
+- **Project config** (`.claude.json`) for specific project
+
+```json
+{
+  "mcpServers": {
+    "mcp-diagram-generator": {
+      "command": "npx",
+      "args": ["-y", "mcp-diagram-generator"]
+    }
+  }
+}
+```
+
+After adding this configuration:
+1. Restart Claude Code
+2. The MCP server will auto-download via npx on first use
+3. No manual installation needed
+
+**Option 2: Local Development (For developers)**
+
+If you're developing the MCP server locally:
+
+```json
+{
+  "mcpServers": {
+    "mcp-diagram-generator": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]
+    }
+  }
+}
+```
+
+### Verification Steps
+
+After configuration, verify it works:
+
+1. Check configuration: Call `get_config()` tool
+2. If successful, you'll see current paths and initialization status
+3. If the tool doesn't exist, check your configuration file syntax
+
+### Common Issues
+
+**Issue**: "Tool not found" error
+- **Solution**: MCP server not configured. Follow installation steps above.
+
+**Issue**: Configuration looks correct but tools still not available
+- **Solution**: Restart Claude Code to reload MCP server configuration
+
+## Quick Start
+
+### First Time Use
+
+On first use, the MCP server will automatically:
+1. Create default configuration file (`.diagram-config.json`)
+2. Create default output directories if they don't exist
+3. Use sensible defaults: `diagrams/{format}/`
+
+You can customize paths at any time using the `init_config` tool.
+
+### Basic Usage
+
+**Simple example** - just provide diagram spec, let the server handle the rest:
+
+```
+User: "创建一个网络拓扑图"
+```
+
+Skill will:
+1. Generate JSON spec
+2. Call `generate_diagram` with only `diagram_spec` parameter
+3. Server auto-creates directories and saves to `diagrams/{format}/{title}-{date}.{ext}`
+
+## Workflow
+
+### Step 1: Understand Requirements
+
+Extract from user's natural language:
+- **Diagram type**: flowchart, sequence diagram, class diagram, ER diagram, mindmap, architecture diagram, network topology
+- **Content**: nodes, relationships, nested structure (for network topology)
+- **Style/theme**: if mentioned (e.g., "clean style", "detailed")
+- **Output preferences**: specific filename? custom path?
+
+### Step 2: Choose Format
+
+Use [format-selection-guide.md](references/format-selection-guide.md) to decide:
+
+| Format | Best For |
+|--------|----------|
+| **drawio** | Complex diagrams, network topology with nested containers, fine-grained styling, manual editing |
+| **mermaid** | Quick generation, code-friendly, version control, documentation |
+| **excalidraw** | Hand-drawn style, creative/diagrammatic flexibility, informal sketches |
+
+### Step 3: Generate Structured JSON
+
+Create a JSON description following the [JSON Schema](references/json-schema-guide.md). Key structure:
+
+```json
+{
+  "format": "drawio",
+  "title": "diagram name",
+  "elements": [
+    {
+      "id": "unique-id",
+      "type": "container|node|edge",
+      "name": "display name",
+      "level": "environment|datacenter|zone|device", // for network topology
+      "style": {...},
+      "geometry": {...},
+      "children": [...] // for nested containers
+    }
+  ]
+}
+```
+
+**Important**: Use unique IDs for all elements. For nested structures, maintain parent-child relationships.
+
+### Step 4: Call MCP Server
+
+**Option A: Use defaults (recommended)**
+
+```json
+{
+  "diagram_spec": <the JSON object created above>
+  // output_path is optional - server will use configured default
+  // filename is optional - server will auto-generate based on title and date
+}
+```
+
+The MCP server will:
+- Validate the JSON schema
+- Generate the appropriate XML/JSON/markdown
+- Auto-create output directories if needed
+- Save to configured default path (e.g., `diagrams/drawio/network-topology-2025-02-03.drawio`)
+
+**Option B: Specify custom path**
+
+```json
+{
+  "diagram_spec": <the JSON object>,
+  "output_path": "custom/path/to/diagram.drawio",
+  "filename": "my-custom-name" // optional, overrides auto-generated filename
+}
+```
+
+**Option C: Just provide filename, use default directory**
+
+```json
+{
+  "diagram_spec": <the JSON object>,
+  "filename": "my-diagram.drawio"
+  // Saves to diagrams/{format}/my-diagram.drawio
+}
+```
+
+### Step 5: Editing Existing Diagrams
+
+1. **Read the existing file** to understand structure
+2. **Parse** the diagram (use MCP tool if available, or read raw file)
+3. **Modify** the JSON description based on user's change request
+4. **Generate** new diagram (overwrite or create new file)
+
+## Configuration Management
+
+### Initialize Configuration
+
+**Initialize with defaults:**
+```
+Call: init_config()
+Result: Creates .diagram-config.json with default paths
+```
+
+**Initialize with custom paths:**
+```
+Call: init_config({
+  paths: {
+    drawio: "output/diagrams/drawio",
+    mermaid: "output/diagrams/mermaid",
+    excalidraw: "output/diagrams/excalidraw"
+  }
+})
+```
+
+### View Current Configuration
+
+```
+Call: get_config()
+Returns: Current paths and initialization status
+```
+
+### Update Single Path
+
+```
+Call: set_output_path({
+  format: "drawio",
+  path: "custom/drawio-path"
+})
+```
+
+## Supported Diagram Types
+
+### Flowchart
+- Simple process flows, decision trees
+- Use **mermaid** for quick output
+- Use **drawio** for complex layouts with multiple branches
+
+### Sequence Diagram
+- Show interactions over time between components
+- **mermaid** recommended (native support)
+- Use **drawio** if custom styling needed
+
+### Class Diagram
+- Show classes, methods, relationships
+- **mermaid** recommended (compact, standard UML)
+- **drawio** for detailed diagrams with many classes
+
+### ER Diagram
+- Database schema, entity relationships
+- **mermaid** recommended
+- **drawio** for complex schemas with many relationships
+
+### Mindmap
+- Hierarchical ideas, brainstorming
+- **mermaid** recommended (native support)
+- **excalidraw** for creative/hand-drawn style
+
+### Architecture Diagram
+- System architecture, component relationships
+- **drawio** recommended for complex systems
+- **mermaid** for high-level overviews
+
+### Network Topology
+- Network environments, datacenters, zones, devices
+- **Must use drawio** (4-layer nesting: environment → datacenter → zone → device)
+- See [network-topology-examples.md](references/network-topology-examples.md) for patterns
+
+## Network Topology Special Notes
+
+Network topology diagrams require a 4-level hierarchical structure:
+
+```
+Environment (level="environment")
+  └── Datacenter (level="datacenter")
+        └── Zone (level="zone")
+              └── Device (type="node")
+```
+
+**Style conventions**:
+- **Environment**: `fillColor: #e1d5e7`, `strokeColor: #9673a6` (purple)
+- **Datacenter**: `fillColor: #d5e8d4`, `strokeColor: #82b366` (green)
+- **Zone**: `fillColor: #fff2cc`, `strokeColor: #d6b656` (yellow)
+- **Device**: Based on device type (router, switch, firewall, etc.)
+
+**Device types and styles**:
+- Router: `strokeColor: #607D8B` (blue-gray)
+- Switch: `strokeColor: #4CAF50` (green)
+- Firewall: `strokeColor: #F44336` (red)
+- PC/Server: `strokeColor: #607D8B` (blue-gray)
+
+## Common Patterns
+
+### Pattern 1: Simple Flowchart (Mermaid)
+
+User: "画一个用户登录流程图，包含登录验证、重定向、错误处理"
+
+Generate JSON:
+```json
+{
+  "format": "mermaid",
+  "title": "用户登录流程",
+  "elements": [
+    {"type": "node", "id": "start", "name": "开始", "geometry": {"x": 0, "y": 0}},
+    {"type": "node", "id": "login", "name": "输入用户名密码", "geometry": {"x": 0, "y": 100}},
+    {"type": "node", "id": "validate", "name": "验证", "geometry": {"x": 0, "y": 200}},
+    {"type": "node", "id": "success", "name": "登录成功", "geometry": {"x": -100, "y": 300}},
+    {"type": "node", "id": "error", "name": "显示错误", "geometry": {"x": 100, "y": 300}},
+    {"type": "edge", "source": "start", "target": "login"},
+    {"type": "edge", "source": "login", "target": "validate"},
+    {"type": "edge", "source": "validate", "target": "success", "label": "成功"},
+    {"type": "edge", "source": "validate", "target": "error", "label": "失败"}
+  ]
+}
+```
+
+Call MCP:
+```
+generate_diagram({
+  diagram_spec: <above JSON>,
+  format: "mermaid"
+  // No output_path needed - auto-saves to diagrams/mermaid/
+})
+```
+
+### Pattern 2: Network Topology (Drawio)
+
+User: "创建一个网络拓扑图，包含省中心机房（上联区、汇聚区、终端区），连接到生产网"
+
+Generate JSON with nested containers (see [json-schema-guide.md](references/json-schema-guide.md) for details).
+
+Call MCP:
+```
+generate_diagram({
+  diagram_spec: <network topology JSON>,
+  filename: "省中心网络拓扑" // Optional, for custom filename
+})
+```
+
+## Resources
+
+### references/
+- **format-selection-guide.md**: When to use drawio vs mermaid vs excalidraw
+- **json-schema-guide.md**: Complete JSON schema with examples for all diagram types
+- **network-topology-examples.md**: Example JSON for network topology patterns
+
+### assets/
+- No templates needed - MCP server handles all generation
+
+### scripts/
+- Not used - all generation delegated to MCP server
+
+## Troubleshooting
+
+### MCP Server Setup
+
+If `mcp-diagram-generator` is not available, you need to install it.
+
+**Option 1: Using npx (Recommended)**
+
+Add to your Claude Code/OpenCode settings:
+
+```json
+{
+  "mcpServers": {
+    "diagram-generator": {
+      "command": "npx",
+      "args": ["-y", "mcp-diagram-generator"]
+    }
+  }
+}
+```
+
+**Option 2: Local Development**
+
+1. Install dependencies: `cd mcp-diagram-generator && npm install`
+2. Build: `npm run build`
+3. Configure with local path:
+```json
+{
+  "mcpServers": {
+    "diagram-generator": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-diagram-generator/dist/index.js"]
+    }
+  }
+}
+```
+
+### Invalid JSON Schema
+
+If MCP server returns validation error:
+1. Check [json-schema-guide.md](references/json-schema-guide.md)
+2. Verify all required fields are present
+3. Ensure all IDs are unique
+4. Check parent-child relationships
+
+### Directory Not Found
+
+**Old behavior**: Error if directory doesn't exist
+**New behavior**: Directory is created automatically ✅
+
+If you still see directory errors:
+1. Check write permissions for the project directory
+2. Verify configuration with `get_config()`
+3. Reinitialize with `init_config()`
+
+### Wrong File Extension
+
+The server automatically uses the correct extension based on format:
+- drawio → `.drawio`
+- mermaid → `.md`
+- excalidraw → `.excalidraw`
+
+You don't need to specify extension in filename parameter.
+
+### Nested Container Issues (Network Topology)
+
+- Verify `level` field matches hierarchy (environment/datacenter/zone)
+- Check `parent` IDs are correct in child elements
+- Ensure geometry coordinates are relative to parent container
+
+## Best Practices
+
+### 1. Use Default Paths
+
+Let the server manage output paths for consistency:
+
+```json
+{
+  "diagram_spec": <spec>
+  // Don't specify output_path unless necessary
+}
+```
+
+### 2. Provide Descriptive Titles
+
+Titles are used for auto-generated filenames:
+
+```json
+{
+  "title": "生产环境网络拓扑-亦庄与西五环",
+  // Generates: 生产环境网络拓扑-亦庄与西五环-2025-02-03.drawio
+}
+```
+
+### 3. Use Configuration for Custom Paths
+
+Instead of specifying output_path every time, configure once:
+
+```
+First time: init_config({ paths: { drawio: "custom/path" } })
+After that: Just use generate_diagram() without output_path
+```
+
+### 4. Check Configuration When Troubleshooting
+
+```
+get_config() // Shows all paths and status
+```

_meta.json

@@ -0,0 +1,6 @@
+{
+  "ownerId": "kn708mx41rdseag4jyx648htns80ft79",
+  "slug": "diagram-generator",
+  "version": "1.1.1",
+  "publishedAt": 1770197321321
+}

package.json

@@ -0,0 +1,5 @@
+{
+  "name": "diagram-generator",
+  "version": "1.0.0",
+  "description": "Generate and edit diagrams (drawio, mermaid, excalidraw)."
+}

references/format-selection-guide.md

@@ -0,0 +1,166 @@
+# Format Selection Guide
+
+Choose the right diagram format based on your needs.
+
+## Quick Decision Matrix
+
+| Factor | Draw.io | Mermaid | Excalidraw |
+|--------|---------|---------|------------|
+| **Learning curve** | Low | Low | Low |
+| **Quick generation** | Medium | **High** | Medium |
+| **Manual editing** | **Excellent** (GUI) | Code-based | Good (GUI) |
+| **Version control** | XML (verbose) | **Markdown** (clean) | JSON |
+| **Code documentation** | Medium | **Excellent** | Poor |
+| **Complex nesting** | **Excellent** | Poor | Good |
+| **Custom styling** | **Excellent** | Limited | Good |
+| **Hand-drawn style** | No | No | **Yes** |
+| **Export options** | PDF, PNG, SVG, etc. | PNG, SVG | PNG, SVG, JSON |
+
+## When to Use Draw.io
+
+### Ideal For:
+- **Network topology diagrams** with nested environments/datacenters/zones
+- **Complex architecture diagrams** with many layers
+- **Diagrams requiring fine-grained control** over positioning and styling
+- **Professional technical diagrams** for documentation
+- **Diagrams that need manual refinement** after generation
+
+### Examples:
+- Enterprise network topology (environments → datacenters → zones → devices)
+- Microservices architecture with many components
+- System diagrams with custom icons and layouts
+- Production infrastructure maps
+
+### Strengths:
+- Best-in-class nested container support (swimlanes)
+- Powerful GUI editor for fine-tuning
+- Export to multiple formats (PDF, PNG, SVG)
+- Large library of pre-built shapes and icons
+- Supports multiple pages in one file
+
+### Weaknesses:
+- XML format is verbose (larger files)
+- Not ideal for quick iterations
+- Manual positioning can be time-consuming
+
+---
+
+## When to Use Mermaid
+
+### Ideal For:
+- **Documentation embedded in code** (Markdown files)
+- **Quick flowcharts and sequence diagrams**
+- **Version-controlled diagrams** (clean git diffs)
+- **Technical documentation** (README, API docs)
+- **Simple to moderately complex diagrams**
+
+### Examples:
+- User authentication flow
+- API sequence diagram
+- Class diagram for a module
+- ER diagram for a database
+- Git workflow visualization
+
+### Strengths:
+- Text-based, easy to version control
+- Can be embedded in Markdown
+- Renders in GitHub, GitLab, many markdown editors
+- Compact syntax
+- Good support for UML diagrams (class, sequence, state, activity)
+
+### Weaknesses:
+- Limited styling options
+- Poor support for complex nesting
+- Layout is auto-generated (less control)
+- No GUI editor (must edit code)
+
+---
+
+## When to Use Excalidraw
+
+### Ideal For:
+- **Hand-drawn / informal diagrams**
+- **Brainstorming sessions** and mindmaps
+- **Creative diagrams** with custom freeform elements
+- **Informal presentations** that feel more human
+
+### Examples:
+- Whiteboard-style architecture sketches
+- Meeting notes with diagrams
+- Brainstorming mindmaps
+- Informal process flows
+- Wireframes (basic)
+
+### Strengths:
+- Unique hand-drawn aesthetic
+- Freeform drawing capability
+- Excellent for creative/brainstorming scenarios
+- Can embed in web pages (ExcalidrawEmbed)
+- Good sharing and collaboration features
+
+### Weaknesses:
+- Not ideal for precise technical diagrams
+- JSON format is verbose and hard to edit manually
+- Limited support for complex relationships
+- Less standard in technical documentation
+
+---
+
+## Decision Tree
+
+```
+Start
+  │
+  ├─ Need hand-drawn style?
+  │   └─ Yes → Excalidraw
+  │   └─ No → Continue
+  │
+  ├─ Complex nesting (4+ levels)?
+  │   └─ Yes → Draw.io
+  │   └─ No → Continue
+  │
+  ├─ Need fine-grained positioning/styling?
+  │   └─ Yes → Draw.io
+  │   └─ No → Continue
+  │
+  ├─ Embedding in documentation/GitHub?
+  │   └─ Yes → Mermaid
+  │   └─ No → Continue
+  │
+  ├─ Quick iteration needed?
+  │   └─ Yes → Mermaid
+  │   └─ No → Draw.io
+```
+
+## Format Comparison by Diagram Type
+
+| Diagram Type | Recommended | Alternative |
+|--------------|--------------|-------------|
+| Simple Flowchart | **Mermaid** | Draw.io (if styling needed) |
+| Complex Flowchart (10+ nodes) | **Draw.io** | Mermaid (if auto-layout works) |
+| Sequence Diagram | **Mermaid** | Draw.io |
+| Class Diagram | **Mermaid** | Draw.io |
+| ER Diagram | **Mermaid** | Draw.io |
+| Mindmap | **Mermaid** | Excalidraw (for hand-drawn) |
+| Network Topology | **Draw.io** (required) | - |
+| System Architecture | **Draw.io** | Mermaid (for high-level) |
+| Whiteboard Sketch | **Excalidraw** | Draw.io (formal) |
+| Brainstorming | **Excalidraw** | Mermaid (structured) |
+
+## Migration Considerations
+
+### Draw.io → Mermaid
+- Remove nested containers (Mermaid doesn't support)
+- Simplify styling
+- Convert XML to Mermaid syntax
+- Use auto-layout (may need manual adjustment)
+
+### Mermaid → Draw.io
+- Import or recreate manually
+- Gain manual control over layout
+- Add nested containers if needed
+
+### Any Format → Excalidraw
+- Recreate manually in Excalidraw editor
+- Hand-drawn aesthetic adds informal feel
+- Good for brainstorming iterations

references/json-schema-guide.md

@@ -0,0 +1,481 @@
+# JSON Schema Guide
+
+Complete schema for diagram specification passed to `mcp-diagram-generator` MCP server.
+
+## Root Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["format", "elements"],
+  "properties": {
+    "format": {
+      "type": "string",
+      "enum": ["drawio", "mermaid", "excalidraw"],
+      "description": "Target diagram format"
+    },
+    "title": {
+      "type": "string",
+      "description": "Diagram title (used as page name in drawio, or header in other formats)"
+    },
+    "elements": {
+      "type": "array",
+      "items": {"$ref": "#/definitions/element"},
+      "description": "All diagram elements (containers, nodes, edges)"
+    }
+  },
+  "definitions": {
+    "element": {
+      "oneOf": [
+        {"$ref": "#/definitions/container"},
+        {"$ref": "#/definitions/node"},
+        {"$ref": "#/definitions/edge"}
+      ]
+    },
+    "container": {
+      "type": "object",
+      "required": ["id", "type", "name"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
+        "type": {"const": "container"},
+        "name": {"type": "string"},
+        "level": {
+          "type": "string",
+          "enum": ["environment", "datacenter", "zone", "other"],
+          "description": "Hierarchy level (for network topology)"
+        },
+        "style": {"$ref": "#/definitions/style"},
+        "geometry": {"$ref": "#/definitions/geometry"},
+        "children": {
+          "type": "array",
+          "items": {"$ref": "#/definitions/element"}
+        }
+      }
+    },
+    "node": {
+      "type": "object",
+      "required": ["id", "type", "name"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
+        "type": {"const": "node"},
+        "name": {"type": "string"},
+        "deviceType": {
+          "type": "string",
+          "enum": ["router", "switch", "firewall", "server", "pc", "database", "cloud", "other"],
+          "description": "Device type (for network topology styling)"
+        },
+        "shape": {
+          "type": "string",
+          "enum": ["rect", "ellipse", "diamond", "parallelogram", "rounded", "cylinder", "cloud", "other"],
+          "description": "Node shape (for flowcharts)"
+        },
+        "style": {"$ref": "#/definitions/style"},
+        "geometry": {"$ref": "#/definitions/geometry"}
+      }
+    },
+    "edge": {
+      "type": "object",
+      "required": ["type", "source", "target"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
+        "type": {"const": "edge"},
+        "source": {"type": "string", "description": "Source node ID"},
+        "target": {"type": "string", "description": "Target node ID"},
+        "label": {"type": "string", "description": "Edge label"},
+        "style": {"$ref": "#/definitions/edgeStyle"}
+      }
+    },
+    "style": {
+      "type": "object",
+      "properties": {
+        "fillColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
+        "strokeColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
+        "strokeWidth": {"type": "number", "minimum": 0},
+        "fontColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
+        "fontSize": {"type": "number", "minimum": 6},
+        "fontStyle": {"type": "string", "enum": ["normal", "bold", "italic"]},
+        "borderRadius": {"type": "number", "minimum": 0},
+        "dashPattern": {"type": "string", "description": "e.g., '5,5' for dashed line"}
+      }
+    },
+    "edgeStyle": {
+      "type": "object",
+      "properties": {
+        "strokeColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
+        "strokeWidth": {"type": "number", "minimum": 0},
+        "endArrow": {"type": "string", "enum": ["none", "arrow", "circle", "diamond"]},
+        "startArrow": {"type": "string", "enum": ["none", "arrow", "circle", "diamond"]},
+        "dashPattern": {"type": "string", "description": "e.g., '5,5' for dashed line"},
+        "lineStyle": {"type": "string", "enum": ["straight", "orthogonal", "curved"]}
+      }
+    },
+    "geometry": {
+      "type": "object",
+      "required": ["x", "y"],
+      "properties": {
+        "x": {"type": "number"},
+        "y": {"type": "number"},
+        "width": {"type": "number", "minimum": 10},
+        "height": {"type": "number", "minimum": 10}
+      }
+    }
+  }
+}
+```
+
+## Common Element Types
+
+### Container (for nested structures)
+
+Used for environments, datacenters, zones, or any grouping.
+
+```json
+{
+  "id": "env-1",
+  "type": "container",
+  "name": "省中心管理端",
+  "level": "environment",
+  "style": {
+    "fillColor": "#e1d5e7",
+    "strokeColor": "#9673a6",
+    "fontSize": 14,
+    "fontStyle": "bold"
+  },
+  "geometry": {
+    "x": 220,
+    "y": 750,
+    "width": 520,
+    "height": 450
+  },
+  "children": [...]
+}
+```
+
+### Node (individual elements)
+
+Used for devices, components, steps, etc.
+
+```json
+{
+  "id": "device-1",
+  "type": "node",
+  "name": "路由器1",
+  "deviceType": "router",
+  "style": {
+    "fillColor": "none",
+    "strokeColor": "#607D8B",
+    "strokeWidth": 2,
+    "fontColor": "#455A64",
+    "fontSize": 12,
+    "fontStyle": "bold"
+  },
+  "geometry": {
+    "x": 8,
+    "y": 25,
+    "width": 55,
+    "height": 25
+  }
+}
+```
+
+### Edge (connections)
+
+Used to connect nodes.
+
+```json
+{
+  "id": "edge-1",
+  "type": "edge",
+  "source": "device-1",
+  "target": "device-2",
+  "label": "专线连接",
+  "style": {
+    "strokeColor": "#FF3333",
+    "strokeWidth": 2,
+    "endArrow": "arrow",
+    "lineStyle": "straight"
+  }
+}
+```
+
+## Network Topology Example
+
+```json
+{
+  "format": "drawio",
+  "title": "新架构",
+  "elements": [
+    {
+      "id": "env-1",
+      "type": "container",
+      "name": "省中心管理端",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14,
+        "fontStyle": "bold"
+      },
+      "geometry": {"x": 220, "y": 750, "width": 520, "height": 450},
+      "children": [
+        {
+          "id": "dc-1",
+          "type": "container",
+          "name": "省中心机房",
+          "level": "datacenter",
+          "style": {
+            "fillColor": "#d5e8d4",
+            "strokeColor": "#82b366",
+            "fontSize": 12,
+            "fontStyle": "bold"
+          },
+          "geometry": {"x": 15, "y": 30, "width": 485, "height": 400},
+          "children": [
+            {
+              "id": "zone-1",
+              "type": "container",
+              "name": "上联区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10,
+                "fontStyle": "bold"
+              },
+              "geometry": {"x": 93.5, "y": 40, "width": 145, "height": 70},
+              "children": [
+                {
+                  "id": "router-1",
+                  "type": "node",
+                  "name": "路由器1",
+                  "deviceType": "router",
+                  "style": {
+                    "fillColor": "none",
+                    "strokeColor": "#607D8B",
+                    "strokeWidth": 2
+                  },
+                  "geometry": {"x": 8, "y": 25, "width": 55, "height": 25}
+                },
+                {
+                  "id": "router-2",
+                  "type": "node",
+                  "name": "路由器2",
+                  "deviceType": "router",
+                  "style": {
+                    "fillColor": "none",
+                    "strokeColor": "#607D8B",
+                    "strokeWidth": 2
+                  },
+                  "geometry": {"x": 68, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "edge-1",
+      "type": "edge",
+      "source": "router-1",
+      "target": "router-2",
+      "style": {
+        "strokeColor": "#333333",
+        "endArrow": "none"
+      }
+    }
+  ]
+}
+```
+
+## Flowchart Example (Mermaid)
+
+```json
+{
+  "format": "mermaid",
+  "title": "用户登录流程",
+  "elements": [
+    {
+      "id": "start",
+      "type": "node",
+      "name": "开始",
+      "shape": "rounded",
+      "geometry": {"x": 200, "y": 0}
+    },
+    {
+      "id": "input",
+      "type": "node",
+      "name": "输入用户名密码",
+      "shape": "parallelogram",
+      "geometry": {"x": 200, "y": 100}
+    },
+    {
+      "id": "validate",
+      "type": "node",
+      "name": "验证",
+      "shape": "diamond",
+      "geometry": {"x": 200, "y": 200}
+    },
+    {
+      "id": "success",
+      "type": "node",
+      "name": "登录成功",
+      "shape": "rounded",
+      "geometry": {"x": 100, "y": 350}
+    },
+    {
+      "id": "error",
+      "type": "node",
+      "name": "显示错误",
+      "shape": "rect",
+      "geometry": {"x": 300, "y": 350}
+    },
+    {
+      "id": "edge-1",
+      "type": "edge",
+      "source": "start",
+      "target": "input"
+    },
+    {
+      "id": "edge-2",
+      "type": "edge",
+      "source": "input",
+      "target": "validate"
+    },
+    {
+      "id": "edge-3",
+      "type": "edge",
+      "source": "validate",
+      "target": "success",
+      "label": "成功"
+    },
+    {
+      "id": "edge-4",
+      "type": "edge",
+      "source": "validate",
+      "target": "error",
+      "label": "失败"
+    }
+  ]
+}
+```
+
+## Sequence Diagram Example (Mermaid)
+
+```json
+{
+  "format": "mermaid",
+  "title": "API调用流程",
+  "elements": [
+    {
+      "id": "user",
+      "type": "node",
+      "name": "用户"
+    },
+    {
+      "id": "frontend",
+      "type": "node",
+      "name": "前端"
+    },
+    {
+      "id": "api",
+      "type": "node",
+      "name": "API服务"
+    },
+    {
+      "id": "db",
+      "type": "node",
+      "name": "数据库"
+    },
+    {
+      "id": "edge-1",
+      "type": "edge",
+      "source": "user",
+      "target": "frontend",
+      "label": "点击登录"
+    },
+    {
+      "id": "edge-2",
+      "type": "edge",
+      "source": "frontend",
+      "target": "api",
+      "label": "POST /login"
+    },
+    {
+      "id": "edge-3",
+      "type": "edge",
+      "source": "api",
+      "target": "db",
+      "label": "查询用户"
+    },
+    {
+      "id": "edge-4",
+      "type": "edge",
+      "source": "db",
+      "target": "api",
+      "label": "返回数据",
+      "style": {
+        "lineStyle": "dashed",
+        "endArrow": "none"
+      }
+    }
+  ]
+}
+```
+
+## Style Presets
+
+### Network Topology Levels
+
+| Level | fillColor | strokeColor | fontSize |
+|-------|-----------|-------------|----------|
+| environment | `#e1d5e7` | `#9673a6` | 14 |
+| datacenter | `#d5e8d4` | `#82b366` | 12 |
+| zone | `#fff2cc` | `#d6b656` | 10 |
+
+### Device Types
+
+| deviceType | strokeColor |
+|------------|-------------|
+| router | `#607D8B` |
+| switch | `#4CAF50` |
+| firewall | `#F44336` |
+| server | `#2196F3` |
+| pc | `#607D8B` |
+| database | `#9C27B0` |
+| cloud | `#9E9E9E` |
+
+### Flowchart Shapes
+
+| shape | Usage |
+|-------|-------|
+| `rect` | Process step |
+| `rounded` | Start/end |
+| `parallelogram` | Input/output |
+| `diamond` | Decision |
+| `cylinder` | Database |
+| `cloud` | External system |
+
+## Best Practices
+
+### ID Generation
+- Use descriptive prefixes: `env-`, `dc-`, `zone-`, `device-`, `edge-`
+- Keep IDs short but unique: `env-1`, `router-2`
+- Avoid spaces or special characters (except `_`, `-`)
+
+### Geometry for Network Topology
+- Container coordinates are relative to their parent
+- Device coordinates are relative to their containing zone
+- Standard device size: `55` x `25`
+- Leave padding: at least `10` units between elements
+
+### Edge Routing
+- For drawio: source/target can reference any node ID
+- Edges can cross container boundaries
+- Use `lineStyle: "orthogonal"` for clean routing in complex diagrams
+
+### Performance
+- Limit total elements to ~100 for good performance
+- Use containers to group related elements
+- For very large diagrams, split into multiple pages

references/network-topology-examples.md

@@ -0,0 +1,524 @@
+# Network Topology Examples
+
+Common patterns for network topology diagrams in Draw.io format.
+
+## Basic 3-Level Topology
+
+Simple structure: Environment → Datacenter → Zone → Device
+
+```json
+{
+  "format": "drawio",
+  "title": "基本网络拓扑",
+  "elements": [
+    {
+      "id": "env-1",
+      "type": "container",
+      "name": "生产环境",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14,
+        "fontStyle": "bold"
+      },
+      "geometry": {"x": 100, "y": 100, "width": 400, "height": 300},
+      "children": [
+        {
+          "id": "dc-1",
+          "type": "container",
+          "name": "主数据中心",
+          "level": "datacenter",
+          "style": {
+            "fillColor": "#d5e8d4",
+            "strokeColor": "#82b366",
+            "fontSize": 12,
+            "fontStyle": "bold"
+          },
+          "geometry": {"x": 20, "y": 30, "width": 360, "height": 250},
+          "children": [
+            {
+              "id": "zone-1",
+              "type": "container",
+              "name": "DMZ区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10,
+                "fontStyle": "bold"
+              },
+              "geometry": {"x": 30, "y": 30, "width": 140, "height": 100},
+              "children": [
+                {
+                  "id": "fw-1",
+                  "type": "node",
+                  "name": "防火墙1",
+                  "deviceType": "firewall",
+                  "style": {"strokeColor": "#F44336"},
+                  "geometry": {"x": 10, "y": 35, "width": 55, "height": 25}
+                },
+                {
+                  "id": "fw-2",
+                  "type": "node",
+                  "name": "防火墙2",
+                  "deviceType": "firewall",
+                  "style": {"strokeColor": "#F44336"},
+                  "geometry": {"x": 75, "y": 35, "width": 55, "height": 25}
+                }
+              ]
+            },
+            {
+              "id": "zone-2",
+              "type": "container",
+              "name": "应用区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10,
+                "fontStyle": "bold"
+              },
+              "geometry": {"x": 190, "y": 30, "width": 140, "height": 100},
+              "children": [
+                {
+                  "id": "app-1",
+                  "type": "node",
+                  "name": "应用服务器1",
+                  "deviceType": "server",
+                  "style": {"strokeColor": "#2196F3"},
+                  "geometry": {"x": 10, "y": 35, "width": 55, "height": 25}
+                },
+                {
+                  "id": "app-2",
+                  "type": "node",
+                  "name": "应用服务器2",
+                  "deviceType": "server",
+                  "style": {"strokeColor": "#2196F3"},
+                  "geometry": {"x": 75, "y": 35, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "edge-1",
+      "type": "edge",
+      "source": "fw-1",
+      "target": "app-1",
+      "style": {"strokeColor": "#333333", "endArrow": "none"}
+    },
+    {
+      "id": "edge-2",
+      "type": "edge",
+      "source": "fw-2",
+      "target": "app-2",
+      "style": {"strokeColor": "#333333", "endArrow": "none"}
+    }
+  ]
+}
+```
+
+## Multi-Environment Topology
+
+Multiple environments with cross-environment connections.
+
+```json
+{
+  "format": "drawio",
+  "title": "多环境网络拓扑",
+  "elements": [
+    {
+      "id": "env-prod",
+      "type": "container",
+      "name": "生产环境",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14
+      },
+      "geometry": {"x": 50, "y": 50, "width": 350, "height": 300},
+      "children": [
+        {
+          "id": "dc-prod",
+          "type": "container",
+          "name": "生产数据中心",
+          "level": "datacenter",
+          "style": {"fillColor": "#d5e8d4", "strokeColor": "#82b366"},
+          "geometry": {"x": 20, "y": 30, "width": 310, "height": 250},
+          "children": [
+            {
+              "id": "zone-prod-app",
+              "type": "container",
+              "name": "应用区",
+              "level": "zone",
+              "geometry": {"x": 20, "y": 20, "width": 120, "height": 80},
+              "children": [
+                {
+                  "id": "prod-app-1",
+                  "type": "node",
+                  "name": "应用服务器",
+                  "deviceType": "server",
+                  "style": {"strokeColor": "#2196F3"},
+                  "geometry": {"x": 10, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "env-dr",
+      "type": "container",
+      "name": "灾备环境",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14
+      },
+      "geometry": {"x": 450, "y": 50, "width": 350, "height": 300},
+      "children": [
+        {
+          "id": "dc-dr",
+          "type": "container",
+          "name": "灾备数据中心",
+          "level": "datacenter",
+          "style": {"fillColor": "#d5e8d4", "strokeColor": "#82b366"},
+          "geometry": {"x": 20, "y": 30, "width": 310, "height": 250},
+          "children": [
+            {
+              "id": "zone-dr-app",
+              "type": "container",
+              "name": "应用区",
+              "level": "zone",
+              "geometry": {"x": 20, "y": 20, "width": 120, "height": 80},
+              "children": [
+                {
+                  "id": "dr-app-1",
+                  "type": "node",
+                  "name": "应用服务器",
+                  "deviceType": "server",
+                  "style": {"strokeColor": "#2196F3"},
+                  "geometry": {"x": 10, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "edge-dr",
+      "type": "edge",
+      "source": "prod-app-1",
+      "target": "dr-app-1",
+      "label": "数据同步",
+      "style": {
+        "strokeColor": "#FF3333",
+        "strokeWidth": 2,
+        "dashPattern": "5,5"
+      }
+    }
+  ]
+}
+```
+
+## 4-Level Nested Topology
+
+Full hierarchy as shown in the 贵州.drawio example.
+
+```json
+{
+  "format": "drawio",
+  "title": "4层嵌套网络拓扑",
+  "elements": [
+    {
+      "id": "env-1",
+      "type": "container",
+      "name": "省中心管理端",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14
+      },
+      "geometry": {"x": 220, "y": 750, "width": 520, "height": 450},
+      "children": [
+        {
+          "id": "dc-1",
+          "type": "container",
+          "name": "省中心机房",
+          "level": "datacenter",
+          "style": {
+            "fillColor": "#d5e8d4",
+            "strokeColor": "#82b366",
+            "fontSize": 12
+          },
+          "geometry": {"x": 15, "y": 30, "width": 485, "height": 400},
+          "children": [
+            {
+              "id": "zone-1",
+              "type": "container",
+              "name": "上联区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10
+              },
+              "geometry": {"x": 93.5, "y": 40, "width": 145, "height": 70},
+              "children": [
+                {
+                  "id": "router-1",
+                  "type": "node",
+                  "name": "路由器1",
+                  "deviceType": "router",
+                  "style": {"strokeColor": "#607D8B"},
+                  "geometry": {"x": 8, "y": 25, "width": 55, "height": 25}
+                },
+                {
+                  "id": "router-2",
+                  "type": "node",
+                  "name": "路由器2",
+                  "deviceType": "router",
+                  "style": {"strokeColor": "#607D8B"},
+                  "geometry": {"x": 68, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            },
+            {
+              "id": "zone-2",
+              "type": "container",
+              "name": "汇聚区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10
+              },
+              "geometry": {"x": 93.5, "y": 165, "width": 145, "height": 70},
+              "children": [
+                {
+                  "id": "switch-1",
+                  "type": "node",
+                  "name": "汇聚交换机1",
+                  "deviceType": "switch",
+                  "style": {"strokeColor": "#4CAF50"},
+                  "geometry": {"x": 8, "y": 25, "width": 55, "height": 25}
+                },
+                {
+                  "id": "switch-2",
+                  "type": "node",
+                  "name": "汇聚交换机2",
+                  "deviceType": "switch",
+                  "style": {"strokeColor": "#4CAF50"},
+                  "geometry": {"x": 68, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            },
+            {
+              "id": "zone-3",
+              "type": "container",
+              "name": "终端区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10
+              },
+              "geometry": {"x": 315, "y": 90, "width": 145, "height": 150},
+              "children": [
+                {
+                  "id": "pc-1",
+                  "type": "node",
+                  "name": "管理端PC1",
+                  "deviceType": "pc",
+                  "style": {"strokeColor": "#607D8B"},
+                  "geometry": {"x": 8, "y": 110, "width": 55, "height": 25}
+                },
+                {
+                  "id": "pc-2",
+                  "type": "node",
+                  "name": "管理端PC2",
+                  "deviceType": "pc",
+                  "style": {"strokeColor": "#607D8B"},
+                  "geometry": {"x": 68, "y": 110, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "env-2",
+      "type": "container",
+      "name": "生产网",
+      "level": "environment",
+      "style": {
+        "fillColor": "#e1d5e7",
+        "strokeColor": "#9673a6",
+        "fontSize": 14
+      },
+      "geometry": {"x": 470, "y": 110, "width": 218, "height": 170},
+      "children": [
+        {
+          "id": "dc-2",
+          "type": "container",
+          "name": "西五环",
+          "level": "datacenter",
+          "style": {
+            "fillColor": "#d5e8d4",
+            "strokeColor": "#82b366",
+            "fontSize": 12
+          },
+          "geometry": {"x": 15, "y": 30, "width": 173, "height": 115},
+          "children": [
+            {
+              "id": "zone-4",
+              "type": "container",
+              "name": "内联接入区",
+              "level": "zone",
+              "style": {
+                "fillColor": "#fff2cc",
+                "strokeColor": "#d6b656",
+                "fontSize": 10
+              },
+              "geometry": {"x": 8, "y": 25, "width": 145, "height": 70},
+              "children": [
+                {
+                  "id": "router-3",
+                  "type": "node",
+                  "name": "路由器1",
+                  "deviceType": "router",
+                  "style": {"strokeColor": "#607D8B"},
+                  "geometry": {"x": 8, "y": 25, "width": 55, "height": 25}
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "edge-1",
+      "type": "edge",
+      "source": "router-1",
+      "target": "switch-1",
+      "style": {"endArrow": "none"}
+    },
+    {
+      "id": "edge-2",
+      "type": "edge",
+      "source": "router-1",
+      "target": "switch-2",
+      "style": {"endArrow": "none"}
+    },
+    {
+      "id": "edge-3",
+      "type": "edge",
+      "source": "router-2",
+      "target": "switch-1",
+      "style": {"endArrow": "none"}
+    },
+    {
+      "id": "edge-4",
+      "type": "edge",
+      "source": "router-2",
+      "target": "switch-2",
+      "style": {"endArrow": "none"}
+    },
+    {
+      "id": "edge-5",
+      "type": "edge",
+      "source": "switch-1",
+      "target": "switch-2",
+      "style": {"endArrow": "none"}
+    },
+    {
+      "id": "edge-6",
+      "type": "edge",
+      "source": "router-1",
+      "target": "router-3",
+      "label": "长途专线",
+      "style": {"strokeColor": "#FF3333"}
+    }
+  ]
+}
+```
+
+## Common Zone Types
+
+| Zone Name | Typical Devices | Use Case |
+|-----------|-----------------|----------|
+| 上联区 | Routers | External network connections |
+| 汇聚区 | Core Switches | Traffic aggregation |
+| 终端区 | Switches, PCs | End-user devices |
+| 彩银区 | Firewalls, Routers | Financial network integration |
+| 内联接入区 | Routers | Internal network connections |
+| 外联接入区 | Routers | External partner connections |
+| DMZ区 | Firewalls, Public Servers | Public-facing services |
+| 应用区 | Application Servers | Application deployment |
+| 数据区 | Database Servers | Data storage |
+| 管理区 | Management Servers | Administrative access |
+
+## Connection Patterns
+
+### Full Mesh (All-to-All)
+```json
+{"type": "edge", "source": "r1", "target": "r2"},
+{"type": "edge", "source": "r1", "target": "r3"},
+{"type": "edge", "source": "r2", "target": "r3"}
+```
+
+### Redundant Pair (Active/Active)
+```json
+{"type": "edge", "source": "fw-1", "target": "sw-1"},
+{"type": "edge", "source": "fw-1", "target": "sw-2"},
+{"type": "edge", "source": "fw-2", "target": "sw-1"},
+{"type": "edge", "source": "fw-2", "target": "sw-2"}
+```
+
+### Hierarchy (Upstream → Downstream)
+```json
+{"type": "edge", "source": "router", "target": "firewall"},
+{"type": "edge", "source": "firewall", "target": "switch"},
+{"type": "edge", "source": "switch", "target": "server"}
+```
+
+### Cross-Environment (Production → DR)
+```json
+{
+  "type": "edge",
+  "source": "prod-db",
+  "target": "dr-db",
+  "label": "数据同步",
+  "style": {
+    "strokeColor": "#FF3333",
+    "dashPattern": "5,5"
+  }
+}
+```
+
+## Layout Guidelines
+
+### Container Spacing
+- Environment to Environment: minimum 100px
+- Datacenter to Datacenter: minimum 50px
+- Zone to Zone: minimum 30px
+
+### Device Placement
+- Standard device size: 55 x 25
+- Horizontal spacing: 10-15px
+- Vertical spacing: 10-15px
+- Alignment: Top-left corner within zone
+
+### Edge Routing
+- Use `lineStyle: "orthogonal"` for clean connections
+- Avoid crossing over other devices when possible
+- Use different stroke colors for different connection types (e.g., red for cross-site links)