commit 29e0b51edd1068973af136ecda9cdcd6e03e81b5 Author: zlei9 Date: Sun Mar 29 13:03:23 2026 +0800 Initial commit with translated description diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..94e425e --- /dev/null +++ b/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": + // 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": , + "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": , + "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: , + 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: , + 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": + // 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 +``` diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..113bf95 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn708mx41rdseag4jyx648htns80ft79", + "slug": "diagram-generator", + "version": "1.1.1", + "publishedAt": 1770197321321 +} \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..5cec6e5 --- /dev/null +++ b/package.json @@ -0,0 +1,5 @@ +{ + "name": "diagram-generator", + "version": "1.0.0", + "description": "Generate and edit diagrams (drawio, mermaid, excalidraw)." +} diff --git a/references/format-selection-guide.md b/references/format-selection-guide.md new file mode 100644 index 0000000..f28a321 --- /dev/null +++ b/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 diff --git a/references/json-schema-guide.md b/references/json-schema-guide.md new file mode 100644 index 0000000..a49deac --- /dev/null +++ b/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 diff --git a/references/network-topology-examples.md b/references/network-topology-examples.md new file mode 100644 index 0000000..17481cc --- /dev/null +++ b/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)