skills/matthewyin_diagram-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit with translated description

Browse Source
This commit is contained in:
zlei9
2026-03-29 13:03:23 +08:00
commit 29e0b51edd
6 changed files with 1649 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

481
references/json-schema-guide.md Normal file
View File

@@ -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