excalidraw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excalidraw Diagram Generator (MCP Edition)

Excalidraw 图表生成器（MCP 版）

Create diagrams on a live Excalidraw canvas using MCP tools. The canvas runs in a browser and updates in real time.

使用MCP工具在实时Excalidraw画布上创建图表。该画布在浏览器中运行并实时更新。

Mental Model

思维模型

You are placing shapes on a 2D canvas and drawing arrows between them.

(0,0) ────────── x increases ──────────►
  │
  │   ┌──────────┐      ┌──────────┐
  │   │  Box A   │─────►│  Box B   │
  │   └──────────┘      └──────────┘
  │         │
  y         ▼
  increases ┌──────────┐
  │         │  Box C   │
  ▼         └──────────┘

Everything is (x, y, width, height). That's it.

你需要在2D画布上放置图形并在图形之间绘制箭头。

(0,0) ────────── x轴向右递增 ──────────►
  │
  │   ┌──────────┐      ┌──────────┐
  │   │  图形A   │─────►│  图形B   │
  │   └──────────┘      └──────────┘
  │         │
  y         ▼
  轴向 ┌──────────┐
  下递 │  图形C   │
  增   └──────────┘

**所有元素都由(x, y, width, height)定义。**就是这么简单。

The 5 Tools You Actually Need

你实际需要的5个工具

Tool	What It Does	When to Use
`read_diagram_guide`	Returns color palette + sizing rules	First call. Read once, use throughout.
`batch_create_elements`	Create many shapes + arrows at once	Main workhorse. Create your whole diagram in 1-2 calls.
`get_canvas_screenshot`	Take a photo of the current canvas	After every batch. Verify it looks right.
`clear_canvas`	Wipe everything	Start fresh before a new diagram.
`export_to_image`	Save as PNG or SVG	Final step if user wants an image file.

Other useful tools:

describe_scene

(text description of canvas),

create_from_mermaid

(quick diagram from Mermaid syntax),

export_scene

(save as .excalidraw JSON file),

set_viewport

(zoom/pan to fit),

export_to_excalidraw_url

(shareable link).

工具	功能	使用场景
`read_diagram_guide`	返回调色板、尺寸规则	首次调用。读取一次，全程使用。
`batch_create_elements`	批量创建多个图形和箭头	主要工具。1-2次调用即可创建完整图表。
`get_canvas_screenshot`	截取当前画布的截图	每次批量操作后。验证图表显示是否正确。
`clear_canvas`	清空画布所有内容	创建新图表前重置画布。
`export_to_image`	保存为PNG或SVG格式	用户需要图片文件时的最终步骤。

其他实用工具：

describe_scene

（画布的文本描述）、

create_from_mermaid

（通过Mermaid语法快速生成图表）、

export_scene

（保存为.excalidraw JSON文件）、

set_viewport

（缩放/平移以适配内容）、

export_to_excalidraw_url

（生成可分享链接）。

How Shapes Work

图形的使用方式

A shape has: type, position (x, y), size (width, height), colors, and label text.

json

{
  "type": "rectangle",
  "id": "my-box",
  "x": 100,
  "y": 100,
  "width": 180,
  "height": 70,
  "backgroundColor": "#a5d8ff",
  "strokeColor": "#1971c2",
  "roughness": 0,
  "text": "My Service\nPort 8080"
}

Key points:

```
text
```
puts a label directly inside the shape (MCP handles the binding for you)
```
roughness: 0
```
= clean lines.
```
roughness: 1
```
= hand-drawn look.
Use
```
\n
```
for multi-line labels
Shapes:
```
rectangle
```
,
```
ellipse
```
,
```
diamond
```
,
```
text
```
(standalone)

一个图形包含：类型、位置(x, y)、尺寸(width, height)、颜色和标签文本。

json

{
  "type": "rectangle",
  "id": "my-box",
  "x": 100,
  "y": 100,
  "width": 180,
  "height": 70,
  "backgroundColor": "#a5d8ff",
  "strokeColor": "#1971c2",
  "roughness": 0,
  "text": "我的服务\n端口 8080"
}

关键点：

```
text
```
用于在图形内部直接添加标签（MCP会自动处理绑定）
```
roughness: 0
```
= 线条清晰。
```
roughness: 1
```
= 手绘风格。
使用
```
\n
```
实现多行标签
支持的图形类型：
```
rectangle
```
（矩形）、
```
ellipse
```
（椭圆）、
```
diamond
```
（菱形）、
```
text
```
（独立文本）

How Arrows Work

箭头的使用方式

Arrows connect shapes by ID. The MCP server auto-routes them to shape edges.

json

{
  "type": "arrow",
  "x": 0,
  "y": 0,
  "startElementId": "my-box",
  "endElementId": "other-box",
  "strokeColor": "#1971c2",
  "text": "HTTP"
}

Key points:

```
startElementId
```
/
```
endElementId
```
= the
```
id
```
of the shape to connect to
The arrow auto-routes to the nearest edges. You do NOT calculate edge points.
```
x, y
```
are still required but can be approximate — binding overrides them
```
text
```
adds a label on the arrow
```
strokeStyle: "dashed"
```
= async/optional flows.
```
"dotted"
```
= weak dependency.

startArrowhead

endArrowhead

"arrow"

"dot"

"triangle"

"bar"

, or

null

箭头通过ID连接图形。MCP服务器会自动将其路由到图形边缘。

json

{
  "type": "arrow",
  "x": 0,
  "y": 0,
  "startElementId": "my-box",
  "endElementId": "other-box",
  "strokeColor": "#1971c2",
  "text": "HTTP"
}

关键点：

```
startElementId
```
/
```
endElementId
```
= 要连接的图形的
```
id
```
箭头会自动路由到最近的边缘，你无需计算边缘点。
仍需填写
```
x, y
```
但可以是近似值——绑定设置会覆盖它们
```
text
```
用于在箭头上添加标签
```
strokeStyle: "dashed"
```
= 异步/可选流程。
```
"dotted"
```
= 弱依赖。
```
startArrowhead
```
/
```
endArrowhead
```
= 可选值：
```
"arrow"
```
（箭头）、
```
"dot"
```
（圆点）、
```
"triangle"
```
（三角形）、
```
"bar"
```
（短杠）或
```
null
```

Step-by-Step Workflow

分步工作流程

Step 1: Understand What to Draw

步骤1：明确要绘制的内容

Read the codebase. Identify:

Components (services, databases, APIs, queues, frontends)
Connections (which components talk to which, and how)
Layers (group related components into rows or zones)

When a sample diagram is provided (ASCII art, text mockup, screenshot, etc.):

Preserve ALL text and detail from the sample by default. Do not simplify, summarize, or omit labels, annotations, bullet points, or sublabels present in the sample.
Extract every node's full text (titles, subtitles, tool names, metrics, details) and reproduce it verbatim in shape labels using
```
\n
```
for multiline.
Preserve section headers, status annotations (e.g. "Fail = Stop & Notify"), and arrow labels exactly as written.
Size boxes large enough to fit the full text (increase height/width beyond defaults as needed).
The sample is the source of truth for content — you may improve layout, colors, and styling, but never drop information.

读取代码库，识别：

组件（服务、数据库、API、队列、前端）
连接关系（哪些组件之间存在通信，以及通信方式）
层级（将相关组件分组为行或区域）

当提供示例图表时（ASCII图、文本草稿、截图等）：

默认保留示例中的所有文本和细节。请勿简化、总结或省略示例中存在的标签、注释、项目符号或子标签。
提取每个节点的完整文本（标题、副标题、工具名称、指标、细节），并使用
```
\n
```
实现多行文本，在图形标签中逐字重现。
完全保留章节标题、状态注释（如“失败=停止并通知”）和箭头标签的原始内容。
调整图形尺寸以容纳完整文本（必要时超出默认值增加高度/宽度）。
示例是内容的唯一可信来源——你可以优化布局、颜色和样式，但绝不能遗漏信息。

Step 2: Read the Design Guide

步骤2：阅读设计指南

mcp__excalidraw__read_diagram_guide()

This returns the color palette, sizing rules, and layout best practices. Use it.

mcp__excalidraw__read_diagram_guide()

该调用会返回调色板、尺寸规则和布局最佳实践，请遵循这些规则。

Step 3: Clear and VERIFY the Canvas

步骤3：清空并验证画布

mcp__excalidraw__clear_canvas()
mcp__excalidraw__get_canvas_screenshot()  // MUST verify empty!

Critical: Previous diagrams can leave ghost elements. Always screenshot after clearing to confirm the canvas is truly empty before creating new elements. If elements remain, clear again.

mcp__excalidraw__clear_canvas()
mcp__excalidraw__get_canvas_screenshot()  // 必须验证画布为空！

**关键提示：**之前的图表可能会留下残留元素。创建新元素前，务必在清空后截图确认画布确实为空。如果仍有元素残留，请再次清空。

Step 4: Plan Your Layout on Paper

步骤4：在脑中规划布局

Before calling any create tool, sketch the layout mentally:

Vertical flow (most common):
  Row 1 (y=0):    Zone backgrounds (large dashed rectangles)
  Row 2 (y=60):   Entry points / Users
  Row 3 (y=350):  Middle layer (APIs, services)
  Row 4 (y=650):  Data layer (databases, storage)

  Columns: x = 40, 440, 840  (spaced 400px apart for labeled arrows)
  Box size: 230 x 160 (standard)  |  200 x 120 (for decision diamonds)
  Spacing between rows: ~200px gap after accounting for box height
  Spacing between boxes in a row: 180px gap (for arrow labels)

调用任何创建工具前，先在脑中勾勒布局：

垂直流（最常见）：
  第1行(y=0)： 区域背景（大虚线矩形）
  第2行(y=60)： 入口点/用户
  第3行(y=350)： 中间层（API、服务）
  第4行(y=650)： 数据层（数据库、存储）

  列间距：x = 40, 440, 840 （带标签的箭头间距为400px）
  图形尺寸：230x160（标准） | 200x120（决策菱形）
  行间距：约200px（包含图形高度后的间隙）
  同行图形间距：180px（用于箭头标签）

Step 5: Create Everything in One Batch

步骤5：批量创建所有元素

Call

batch_create_elements

with ALL elements at once. This ensures arrow bindings resolve correctly (arrows can reference shape IDs created in the same batch).

Order of elements in the array:

Zone backgrounds (large dashed rectangles) — so they render behind everything
Shapes (rectangles, ellipses, diamonds) — with
```
id
```
set for arrow references
Arrows — using
```
startElementId
```
/
```
endElementId
```
Standalone text labels (titles, annotations)

调用

batch_create_elements

一次性创建所有元素。这样可以确保箭头绑定正确解析（箭头可以引用同一批中创建的图形ID）。

元素数组的顺序：

区域背景（大虚线矩形）——确保渲染在所有元素后方
图形（矩形、椭圆、菱形）——设置
```
id
```
以便箭头引用
箭头——使用
```
startElementId
```
/
```
endElementId
```
独立文本标签（标题、注释）

Step 6: Screenshot and Verify

步骤6：截图并验证

mcp__excalidraw__get_canvas_screenshot()

Look at the image. Check:

Are all labels readable?
Are arrows connecting the right shapes?
Is spacing even?
Are zones encompassing their children?

mcp__excalidraw__get_canvas_screenshot()

查看截图，检查：

所有标签是否清晰可读？
箭头是否连接了正确的图形？
间距是否均匀？
区域是否完整包含其子元素？

Step 7: Fix and Adjust

步骤7：修复和调整

Use

update_element

to tweak positions, colors, or text. Use

delete_element

create_element

for bigger changes. Then screenshot again.

使用

update_element

调整位置、颜色或文本。使用

delete_element

create_element

进行较大改动。然后再次截图验证。

Step 8: Zoom to Fit

步骤8：缩放以适配内容

mcp__excalidraw__set_viewport({ scrollToContent: true })

mcp__excalidraw__set_viewport({ scrollToContent: true })

Step 9: Export (if requested)

步骤9：导出（如果用户要求）

mcp__excalidraw__export_to_image({ format: "png", filePath: "/path/to/output.png" })
mcp__excalidraw__export_scene({ filePath: "/path/to/output.excalidraw" })
mcp__excalidraw__export_to_excalidraw_url()  // shareable link

mcp__excalidraw__export_to_image({ format: "png", filePath: "/path/to/output.png" })
mcp__excalidraw__export_scene({ filePath: "/path/to/output.excalidraw" })
mcp__excalidraw__export_to_excalidraw_url()  // 生成可分享链接

Complete Example: 3-Layer Architecture

完整示例：三层架构

This shows exactly what to pass to

batch_create_elements

json

{
  "elements": [
    // --- ZONE BACKGROUNDS (render behind everything) ---
    {
      "type": "rectangle", "id": "zone-frontend",
      "x": 0, "y": 0, "width": 500, "height": 160,
      "backgroundColor": "#e9ecef", "strokeColor": "#868e96",
      "strokeStyle": "dashed", "opacity": 40, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 10,
      "text": "Frontend Layer", "fontSize": 14, "strokeColor": "#868e96"
    },
    {
      "type": "rectangle", "id": "zone-backend",
      "x": 0, "y": 200, "width": 500, "height": 160,
      "backgroundColor": "#eebefa", "strokeColor": "#9c36b5",
      "strokeStyle": "dashed", "opacity": 30, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 210,
      "text": "Backend Layer", "fontSize": 14, "strokeColor": "#9c36b5"
    },

    // --- SHAPES (give each an id so arrows can reference them) ---
    {
      "type": "rectangle", "id": "react-app",
      "x": 40, "y": 50, "width": 180, "height": 70,
      "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
      "text": "React App\nFrontend"
    },
    {
      "type": "rectangle", "id": "api-server",
      "x": 40, "y": 250, "width": 180, "height": 70,
      "backgroundColor": "#d0bfff", "strokeColor": "#7048e8", "roughness": 0,
      "text": "API Server\nExpress.js"
    },
    {
      "type": "rectangle", "id": "database",
      "x": 280, "y": 250, "width": 180, "height": 70,
      "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44", "roughness": 0,
      "text": "PostgreSQL\nDatabase"
    },

    // --- ARROWS (connect shapes by ID) ---
    {
      "type": "arrow", "x": 130, "y": 120,
      "startElementId": "react-app", "endElementId": "api-server",
      "strokeColor": "#1971c2", "text": "REST API"
    },
    {
      "type": "arrow", "x": 220, "y": 285,
      "startElementId": "api-server", "endElementId": "database",
      "strokeColor": "#2f9e44", "text": "SQL"
    },

    // --- TITLE ---
    {
      "type": "text", "x": 100, "y": -40,
      "text": "System Architecture", "fontSize": 24, "strokeColor": "#1e1e1e"
    }
  ]
}

以下展示了传递给

batch_create_elements

的完整参数：

json

{
  "elements": [
    // --- 区域背景（渲染在所有元素后方） ---
    {
      "type": "rectangle", "id": "zone-frontend",
      "x": 0, "y": 0, "width": 500, "height": 160,
      "backgroundColor": "#e9ecef", "strokeColor": "#868e96",
      "strokeStyle": "dashed", "opacity": 40, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 10,
      "text": "前端层", "fontSize": 14, "strokeColor": "#868e96"
    },
    {
      "type": "rectangle", "id": "zone-backend",
      "x": 0, "y": 200, "width": 500, "height": 160,
      "backgroundColor": "#eebefa", "strokeColor": "#9c36b5",
      "strokeStyle": "dashed", "opacity": 30, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 210,
      "text": "后端层", "fontSize": 14, "strokeColor": "#9c36b5"
    },

    // --- 图形（为每个图形设置id以便箭头引用） ---
    {
      "type": "rectangle", "id": "react-app",
      "x": 40, "y": 50, "width": 180, "height": 70,
      "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
      "text": "React应用\n前端"
    },
    {
      "type": "rectangle", "id": "api-server",
      "x": 40, "y": 250, "width": 180, "height": 70,
      "backgroundColor": "#d0bfff", "strokeColor": "#7048e8", "roughness": 0,
      "text": "API服务器\nExpress.js"
    },
    {
      "type": "rectangle", "id": "database",
      "x": 280, "y": 250, "width": 180, "height": 70,
      "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44", "roughness": 0,
      "text": "PostgreSQL\n数据库"
    },

    // --- 箭头（通过ID连接图形） ---
    {
      "type": "arrow", "x": 130, "y": 120,
      "startElementId": "react-app", "endElementId": "api-server",
      "strokeColor": "#1971c2", "text": "REST API"
    },
    {
      "type": "arrow", "x": 220, "y": 285,
      "startElementId": "api-server", "endElementId": "database",
      "strokeColor": "#2f9e44", "text": "SQL"
    },

    // --- 标题 ---
    {
      "type": "text", "x": 100, "y": -40,
      "text": "系统架构", "fontSize": 24, "strokeColor": "#1e1e1e"
    }
  ]
}

Complete Example: Data Flow Diagram (Parameter Threading)

完整示例：数据流图（参数传递）

Shows a parameter traced through 5 layers with split/converge paths, decision node, and side annotations:

json

{
  "elements": [
    // --- TITLE ---
    {"type": "text", "x": 20, "y": 10, "text": "Data Flow: parameter_name Threading", "fontSize": 24, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 20, "y": 48, "text": "Subtitle describing the trace", "fontSize": 16, "strokeColor": "#868e96"},

    // --- WHY SECTION (top-right, first-principles context) ---
    {"type": "rectangle", "id": "why-bg", "x": 460, "y": 80, "width": 440, "height": 310,
     "backgroundColor": "#e9ecef", "strokeColor": "#868e96", "roughness": 0},
    {"type": "text", "x": 480, "y": 95, "text": "WHY: The Problem", "fontSize": 20, "strokeColor": "#e03131"},
    {"type": "text", "x": 480, "y": 135, "text": "1. What currently happens", "fontSize": 16, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 480, "y": 195, "text": "2. Why it's expensive/wrong", "fontSize": 16, "strokeColor": "#e03131"},
    {"type": "text", "x": 480, "y": 275, "text": "3. Gap in current design", "fontSize": 16, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 480, "y": 335, "text": "Solution: what this change does", "fontSize": 16, "strokeColor": "#2f9e44"},

    // --- FLOW BOXES (center column, 150px vertical pitch) ---
    {"type": "rectangle", "id": "l1", "x": 60, "y": 420, "width": 300, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "Entry Point\nfile/path.py"},

    // Split into two paths
    {"type": "rectangle", "id": "l2a", "x": -100, "y": 570, "width": 290, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "Path A\nfile/path_a.py"},
    {"type": "rectangle", "id": "l2b", "x": 230, "y": 570, "width": 290, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "Path B\nfile/path_b.py"},

    // Converge point
    {"type": "rectangle", "id": "l4", "x": 60, "y": 720, "width": 300, "height": 65,
     "backgroundColor": "#eebefa", "strokeColor": "#9c36b5", "roughness": 0,
     "text": "Convergence Point\nfile/path_merge.py"},

    // Decision
    {"type": "diamond", "id": "dec", "x": 110, "y": 870, "width": 200, "height": 120,
     "backgroundColor": "#fff3bf", "strokeColor": "#fab005", "roughness": 0,
     "text": "condition?"},

    // Outcome branches
    {"type": "rectangle", "id": "yes", "x": -100, "y": 1080, "width": 260, "height": 65,
     "backgroundColor": "#ffc9c9", "strokeColor": "#e03131", "roughness": 0,
     "text": "Expensive Operation"},
    {"type": "rectangle", "id": "no", "x": 250, "y": 1080, "width": 220, "height": 65,
     "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44", "roughness": 0,
     "text": "Skip / Fast Path"},

    // --- ARROWS (bound by ID, auto-routed) ---
    {"type": "arrow", "x": 150, "y": 485, "startElementId": "l1", "endElementId": "l2a",
     "text": "Path A label", "strokeColor": "#1971c2"},
    {"type": "arrow", "x": 280, "y": 485, "startElementId": "l1", "endElementId": "l2b",
     "text": "Path B label", "strokeColor": "#1971c2"},
    {"type": "arrow", "x": 45, "y": 635, "startElementId": "l2a", "endElementId": "l4",
     "text": "data form", "strokeColor": "#9c36b5"},
    {"type": "arrow", "x": 375, "y": 635, "startElementId": "l2b", "endElementId": "l4",
     "text": "data form", "strokeColor": "#1971c2", "strokeStyle": "dashed"},
    {"type": "arrow", "x": 210, "y": 785, "startElementId": "l4", "endElementId": "dec",
     "strokeColor": "#2f9e44"},
    {"type": "arrow", "x": 150, "y": 990, "startElementId": "dec", "endElementId": "yes",
     "text": "True", "strokeColor": "#e03131"},
    {"type": "arrow", "x": 270, "y": 990, "startElementId": "dec", "endElementId": "no",
     "text": "False", "strokeColor": "#2f9e44"},

    // --- LAYER LABELS (left column, gray) ---
    {"type": "text", "x": -100, "y": 420, "text": "Layer 1\nEntry", "fontSize": 14, "strokeColor": "#868e96"},
    {"type": "text", "x": -210, "y": 570, "text": "Layer 2\nBackend", "fontSize": 14, "strokeColor": "#868e96"},

    // --- DATA FORM ANNOTATIONS (right column, orange) ---
    {"type": "text", "x": 570, "y": 440, "text": "Data form: Python bool", "fontSize": 14, "strokeColor": "#e8590c"},
    {"type": "text", "x": 570, "y": 590, "text": "Data form: JSON / arg", "fontSize": 14, "strokeColor": "#e8590c"},
    {"type": "text", "x": 570, "y": 740, "text": "Data form: Dataclass", "fontSize": 14, "strokeColor": "#e8590c"}
  ]
}

展示了一个参数经过5个层级的传递路径，包含分支/汇聚路径、决策节点和侧边注释：

json

{
  "elements": [
    // --- 标题 ---
    {"type": "text", "x": 20, "y": 10, "text": "数据流：parameter_name 传递轨迹", "fontSize": 24, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 20, "y": 48, "text": "轨迹描述副标题", "fontSize": 16, "strokeColor": "#868e96"},

    // --- 原因说明区（右上角，底层逻辑背景） ---
    {"type": "rectangle", "id": "why-bg", "x": 460, "y": 80, "width": 440, "height": 310,
     "backgroundColor": "#e9ecef", "strokeColor": "#868e96", "roughness": 0},
    {"type": "text", "x": 480, "y": 95, "text": "原因：存在的问题", "fontSize": 20, "strokeColor": "#e03131"},
    {"type": "text", "x": 480, "y": 135, "text": "1. 当前现状", "fontSize": 16, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 480, "y": 195, "text": "2. 问题的影响（成本高/错误）", "fontSize": 16, "strokeColor": "#e03131"},
    {"type": "text", "x": 480, "y": 275, "text": "3. 当前设计的缺陷", "fontSize": 16, "strokeColor": "#1e1e1e"},
    {"type": "text", "x": 480, "y": 335, "text": "解决方案：本次改动的作用", "fontSize": 16, "strokeColor": "#2f9e44"},

    // --- 流程图形（中间列，垂直间距150px） ---
    {"type": "rectangle", "id": "l1", "x": 60, "y": 420, "width": 300, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "入口点\nfile/path.py"},

    // 分支为两条路径
    {"type": "rectangle", "id": "l2a", "x": -100, "y": 570, "width": 290, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "路径A\nfile/path_a.py"},
    {"type": "rectangle", "id": "l2b", "x": 230, "y": 570, "width": 290, "height": 65,
     "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2", "roughness": 0,
     "text": "路径B\nfile/path_b.py"},

    // 汇聚点
    {"type": "rectangle", "id": "l4", "x": 60, "y": 720, "width": 300, "height": 65,
     "backgroundColor": "#eebefa", "strokeColor": "#9c36b5", "roughness": 0,
     "text": "汇聚点\nfile/path_merge.py"},

    // 决策节点
    {"type": "diamond", "id": "dec", "x": 110, "y": 870, "width": 200, "height": 120,
     "backgroundColor": "#fff3bf", "strokeColor": "#fab005", "roughness": 0,
     "text": "条件判断?"},

    // 结果分支
    {"type": "rectangle", "id": "yes", "x": -100, "y": 1080, "width": 260, "height": 65,
     "backgroundColor": "#ffc9c9", "strokeColor": "#e03131", "roughness": 0,
     "text": "高成本操作"},
    {"type": "rectangle", "id": "no", "x": 250, "y": 1080, "width": 220, "height": 65,
     "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44", "roughness": 0,
     "text": "跳过/快速路径"},

    // --- 箭头（通过ID绑定，自动路由） ---
    {"type": "arrow", "x": 150, "y": 485, "startElementId": "l1", "endElementId": "l2a",
     "text": "路径A标签", "strokeColor": "#1971c2"},
    {"type": "arrow", "x": 280, "y": 485, "startElementId": "l1", "endElementId": "l2b",
     "text": "路径B标签", "strokeColor": "#1971c2"},
    {"type": "arrow", "x": 45, "y": 635, "startElementId": "l2a", "endElementId": "l4",
     "text": "数据格式", "strokeColor": "#9c36b5"},
    {"type": "arrow", "x": 375, "y": 635, "startElementId": "l2b", "endElementId": "l4",
     "text": "数据格式", "strokeColor": "#1971c2", "strokeStyle": "dashed"},
    {"type": "arrow", "x": 210, "y": 785, "startElementId": "l4", "endElementId": "dec",
     "strokeColor": "#2f9e44"},
    {"type": "arrow", "x": 150, "y": 990, "startElementId": "dec", "endElementId": "yes",
     "text": "是", "strokeColor": "#e03131"},
    {"type": "arrow", "x": 270, "y": 990, "startElementId": "dec", "endElementId": "no",
     "text": "否", "strokeColor": "#2f9e44"},

    // --- 层级标签（左列，灰色） ---
    {"type": "text", "x": -100, "y": 420, "text": "层级1\n入口", "fontSize": 14, "strokeColor": "#868e96"},
    {"type": "text", "x": -210, "y": 570, "text": "层级2\n后端", "fontSize": 14, "strokeColor": "#868e96"},

    // --- 数据格式注释（右列，橙色） ---
    {"type": "text", "x": 570, "y": 440, "text": "数据格式：Python布尔值", "fontSize": 14, "strokeColor": "#e8590c"},
    {"type": "text", "x": 570, "y": 590, "text": "数据格式：JSON / 参数", "fontSize": 14, "strokeColor": "#e8590c"},
    {"type": "text", "x": 570, "y": 740, "text": "数据格式：数据类", "fontSize": 14, "strokeColor": "#e8590c"}
  ]
}

Color Palette (Quick Reference)

调色板（快速参考）

Component Type	Background	Stroke	When to Use
Frontend/UI	`#a5d8ff`	`#1971c2`	React, Next.js, web apps
Backend/API	`#d0bfff`	`#7048e8`	API servers, processors
Database	`#b2f2bb`	`#2f9e44`	PostgreSQL, Redis, MongoDB
Storage	`#ffec99`	`#f08c00`	S3, file systems
AI/ML	`#e599f7`	`#9c36b5`	ML models, AI services
External API	`#ffc9c9`	`#e03131`	Third-party services
Queue/Event	`#fff3bf`	`#fab005`	Kafka, RabbitMQ, SQS
Cache	`#ffe8cc`	`#fd7e14`	Redis cache, Memcached
Decision/Gate	`#ffd8a8`	`#e8590c`	Conditionals, routers
Zone/Group	`#e9ecef`	`#868e96`	Logical groupings

Rule: Same-role shapes get same colors. Limit to 3-4 fill colors per diagram.

组件类型	背景色	边框色	使用场景
前端/UI	`#a5d8ff`	`#1971c2`	React、Next.js、Web应用
后端/API	`#d0bfff`	`#7048e8`	API服务器、处理器
数据库	`#b2f2bb`	`#2f9e44`	PostgreSQL、Redis、MongoDB
存储	`#ffec99`	`#f08c00`	S3、文件系统
AI/ML	`#e599f7`	`#9c36b5`	ML模型、AI服务
外部API	`#ffc9c9`	`#e03131`	第三方服务
队列/事件	`#fff3bf`	`#fab005`	Kafka、RabbitMQ、SQS
缓存	`#ffe8cc`	`#fd7e14`	Redis缓存、Memcached
决策/网关	`#ffd8a8`	`#e8590c`	条件判断、路由器
区域/分组	`#e9ecef`	`#868e96`	逻辑分组

**规则：**同一角色的图形使用相同颜色。每张图表最多使用3-4种填充色。

Sizing Rules

尺寸规则

Err on the side of too much space. Tight spacing is the #1 mistake — arrows and their labels get hidden when boxes are too close. When in doubt, double the gap you think you need. Diagrams that feel "too spread out" in your head almost always look right on screen.

CRITICAL: Arrow labels need ~120px of clear space between boxes to be visible. If an arrow has a text label (e.g. "auto deploy", "All pass"), the gap between the two connected boxes MUST be at least 150px. Arrows without labels still need 100px minimum.

Property	Value	Why
Box width	200-240px	Fits multiline labels with breathing room
Box height	120-160px	Fits 3-4 line labels comfortably
Horizontal gap (labeled arrows)	150-200px	Arrow labels are ~80-120px wide, need clearance on both sides
Horizontal gap (unlabeled arrows)	100-120px	Just the arrow line + breathing room
Column spacing (labeled)	400px	220px box + 180px gap
Column spacing (unlabeled)	340px	220px box + 120px gap
Row spacing	280-350px	150px box + 150px gap for arrows + annotations
Font size (labels)	16px	Default, readable
Font size (titles)	20-24px	Stands out as header
Font size (zone labels)	14px	Subtle, doesn't compete
Zone opacity	25-40	Background, not foreground
Zone padding	50-60px around children	Zone borders must NOT hug inner boxes
Section header to box gap	40px	Headers need clearance from boxes below

Zone sizing rule: Calculate zone dimensions as: leftmost child x - 50 to rightmost child x + child width + 60 (horizontal), topmost child y - 55 to bottommost child y + child height + 60 (vertical). Always verify the zone fully wraps ALL children with visible padding on every side.

Arrow visibility test: Before finalizing, mentally check every labeled arrow — if the label text is longer than half the gap between boxes, increase the gap. Common offenders: "auto deploy", "rollback on failure", "All pass" — these labels are 80-150px wide and get clipped when gaps are <150px.

**宁可空间过大，不要空间不足。**间距过紧是最常见的错误——当图形间距过小时，箭头及其标签会被遮挡。如有疑问，将你认为需要的间距加倍。你觉得“过于分散”的布局，在屏幕上几乎总是看起来恰到好处。

**关键提示：**箭头标签需要图形之间有大约120px的空白空间才能显示清晰。如果箭头带有文本标签（如“自动部署”、“全部通过”），则两个连接图形之间的间距必须至少为150px。无标签的箭头仍需要至少100px的间距。

属性	值	原因
图形宽度	200-240px	容纳多行标签并留有呼吸空间
图形高度	120-160px	舒适容纳3-4行标签
水平间距（带标签箭头）	150-200px	箭头标签宽度约80-120px，两侧需要留白
水平间距（无标签箭头）	100-120px	仅需箭头线条+呼吸空间
列间距（带标签）	400px	220px图形 + 180px间距
列间距（无标签）	340px	220px图形 + 120px间距
行间距	280-350px	150px图形 + 箭头和注释所需的150px间距
标签字体大小	16px	默认值，清晰可读
标题字体大小	20-24px	作为标题突出显示
区域标签字体大小	14px	风格低调，不与主内容冲突
区域透明度	25-40	作为背景，不抢占前景注意力
区域内边距	子元素周围50-60px	区域边框绝不能紧贴内部图形
章节标题与图形的间距	40px	标题需要与下方图形保持留白

**区域尺寸规则：**计算区域尺寸的方式为：水平方向=最左侧子元素x坐标-50 至最右侧子元素x坐标+子元素宽度+60；垂直方向=最顶部子元素y坐标-55 至最底部子元素y坐标+子元素高度+60。务必验证区域完全包裹所有子元素，且每侧都有可见的内边距。

**箭头可见性测试：**最终确定前，逐一检查每个带标签的箭头——如果标签文本长度超过图形间距的一半，请增加间距。常见的长标签：“自动部署”、“失败时回滚”、“全部通过”——这些标签宽度为80-150px，当间距<150px时会被截断。

Layout Patterns

布局模式

Vertical Flow (default for most diagrams)

垂直流（大多数图表的默认选择）

Title (y = -40)

[Zone 1: y=0, height=260]
  [Box A: x=40]    [Box B: x=440]    [Box C: x=840]

[Zone 2: y=350, height=260]
  [Box D: x=40]    [Box E: x=440]

[Zone 3: y=700, height=260]
  [Box F: x=240]

Arrows flow top to bottom. Cross-layer arrows use dashed style.

标题 (y = -40)

[区域1: y=0, 高度=260]
  [图形A: x=40]    [图形B: x=440]    [图形C: x=840]

[区域2: y=350, 高度=260]
  [图形D: x=40]    [图形E: x=440]

[区域3: y=700, 高度=260]
  [图形F: x=240]

箭头从上到下流动。跨层级箭头使用虚线样式。

Horizontal Pipeline

水平流水线

[Source] ──► [Transform 1] ──► [Transform 2] ──► [Output]
  x=40        x=440             x=840             x=1240

All at same

. Arrows flow left to right. Use 400px column spacing for labeled arrows, 340px for unlabeled.

[源] ──► [转换1] ──► [转换2] ──► [输出]
  x=40        x=440             x=840             x=1240

所有图形位于同一

坐标。箭头从左到右流动。带标签的箭头使用400px列间距，无标签的使用340px。

Hub and Spoke

中心辐射模式

         [Consumer A]
              ▲
              │
[Producer] ──► [Event Bus] ──► [Consumer B]
              │
              ▼
         [Consumer C]

Central shape at (300, 300). Spokes at ~200px radius.

         [消费者A]
              ▲
              │
[生产者] ──► [事件总线] ──► [消费者B]
              │
              ▼
         [消费者C]

中心图形位于(300, 300)。辐射图形位于中心图形周围约200px半径处。

Data Flow Diagram (parameter threading, call chains)

数据流图（参数传递、调用链）

Best for: tracing a parameter/request through architectural layers, showing data transformations at each boundary.

 Layer Labels        Main Flow Column          Side Annotations
 (left, gray)        (center, colored)         (right, orange)

  Layer 1      ┌─────────────────────┐         Data form: Python bool
  User API     │  Entry Point        │
               │  file/path.py       │
               └──────┬──────┬───────┘
                      │      │
              ┌───────┘      └────────┐
              ▼                       ▼
  Layer 2  ┌──────────┐    ┌──────────┐        Data form: JSON / bool
  Backend  │ Path A   │    │ Path B   │
           └────┬─────┘    └────┬─────┘
                │               │  (dashed = direct)
                ▼               │
  Layer 3  ┌──────────┐        │               Data form: Dataclass
  HTTP     │ Server   │        │
           └────┬─────┘        │
                └──────┬───────┘  (converge)
                       ▼
  Layer 4  ┌─────────────────────┐             Data form: IPC message
  Manager  │  Manager            │
           └──────┬──────────────┘
                  ▼
  Layer 5  ┌─────────────────────┐             Data form: Conditional
  Executor │  Executor           │
           └──────┬──────────────┘
                  ▼
               ◇ Decision? ◇
              / \
         True/   \False
            ▼     ▼
         [Yes]  [No]

Golden coordinates (validated):

Element	x	y	width	height
Main boxes	60	+150 per row	300	65
Split left	-100	row_y	290	65
Split right	230	row_y	290	65
Decision diamond	110	row_y	200	120
Layer labels	-100 to -50	aligned to box	—	fontSize: 14
Annotations	570	aligned to box	—	fontSize: 14
WHY section	460, y=80	—	440	310

Three-column structure:

Left column (x < 0): Layer numbers + names in gray (
```
#868e96
```
, fontSize 14)
Center column (x: 60–360): Flow boxes with
```
ComponentName\nfile/path.py
```
Right column (x: 570): Data form annotations in orange (
```
#e8590c
```
, fontSize 14)

Color by layer role:

Blue (
```
#a5d8ff
```
/
```
#1971c2
```
): User-facing API layers
Purple (
```
#eebefa
```
/
```
#9c36b5
```
): Internal processing layers
Green (
```
#b2f2bb
```
/
```
#2f9e44
```
): Execution layer + "skip/success" outcomes
Yellow (
```
#fff3bf
```
/
```
#fab005
```
): Decision nodes
Red (
```
#ffc9c9
```
/
```
#e03131
```
): Expensive/dangerous operations
Gray (
```
#e9ecef
```
/
```
#868e96
```
): Annotations, zones

Split and converge pattern:

Split: Two arrows from one box, angled down-left and down-right
Direct skip: Use
```
strokeStyle: "dashed"
```
for paths that skip layers
Converge: Two arrows from different paths into one box below

"WHY" annotation box (first-principles context): Place a gray-background rectangle (top-right,

x: 460

) with 3-4 text items explaining the motivation. Use red stroke for the problem, green stroke for the solution.

最适用于：追踪参数/请求在架构层级中的传递路径，展示每个边界处的数据转换。

 层级标签        主流程列          侧边注释
  (左列，灰色)      (中列，彩色)        (右列，橙色)

  层级1      ┌─────────────────────┐         数据格式：Python布尔值
  用户API     │  入口点        │
               │  file/path.py       │
               └──────┬──────┬───────┘
                      │      │
              ┌───────┘      └────────┐
              ▼                       ▼
  层级2  ┌──────────┐    ┌──────────┐        数据格式：JSON / 布尔值
  后端  │ 路径A   │    │ 路径B   │
           └────┬─────┘    └────┬─────┘
                │               │  (虚线=直接传递)
                ▼               │
  层级3  ┌──────────┐        │               数据格式：数据类
  HTTP     │ 服务器   │        │
           └────┬─────┘        │
                └──────┬───────┘  (汇聚)
                       ▼
  层级4  ┌─────────────────────┐             数据格式：IPC消息
  管理器  │  管理器            │
           └──────┬──────────────┘
                  ▼
  层级5  ┌─────────────────────┐             数据格式：条件判断
  执行器 │  执行器           │
           └──────┬──────────────┘
                  ▼
               ◇ 条件判断? ◇
              / \
         是/   \否
            ▼     ▼
         [是分支]  [否分支]

经过验证的标准坐标：

元素	x坐标	y坐标	宽度	高度
主流程图形	60	每行增加150	300	65
分支左图形	-100	当前行y坐标	290	65
分支右图形	230	当前行y坐标	290	65
决策菱形	110	当前行y坐标	200	120
层级标签	-100至-50	与图形对齐	—	字体大小:14
侧边注释	570	与图形对齐	—	字体大小:14
原因说明区	460, y=80	—	440	310

三列结构：

**左列(x < 0)：**层级编号+名称，灰色(
```
#868e96
```
，字体大小14)
**中列(x: 60–360)：**流程图形，格式为
```
组件名称\nfile/path.py
```
**右列(x: 570)：**数据格式注释，橙色(
```
#e8590c
```
，字体大小14)

按层级角色设置颜色：

蓝色(
```
#a5d8ff
```
/
```
#1971c2
```
)：面向用户的API层级
紫色(
```
#eebefa
```
/
```
#9c36b5
```
)：内部处理层级
绿色(
```
#b2f2bb
```
/
```
#2f9e44
```
)：执行层级+“跳过/成功”结果
黄色(
```
#fff3bf
```
/
```
#fab005
```
)：决策节点
红色(
```
#ffc9c9
```
/
```
#e03131
```
)：高成本/危险操作
灰色(
```
#e9ecef
```
/
```
#868e96
```
)：注释、区域

分支与汇聚模式：

分支：从一个图形引出两个箭头，分别向左下和右下方向
直接跳过：对跳过层级的路径使用
```
strokeStyle: "dashed"
```
汇聚：从不同路径引出两个箭头，指向下方的同一个图形

“原因”注释框（底层逻辑背景）： 在右上角放置一个灰色背景的矩形(x:460)，包含3-4条文本说明动机。使用红色边框标注问题，绿色边框标注解决方案。

Common Mistakes and Fixes

常见错误与修复方案

Mistake	Fix
Ghost elements from previous diagram	Always `get_canvas_screenshot()` after `clear_canvas()` . If old elements visible, clear again
Arrows don't connect	Set `startElementId` / `endElementId` to valid shape `id` values
Shapes overlap	Increase spacing. Use 240px column gap, 140px row gap
Labels cut off	Make boxes wider (200px+) or use shorter text
Can't tell layers apart	Add zone background rectangles with dashed stroke + low opacity
Too many colors	Limit to 3-4 fill colors. Same role = same color
Diagram too cluttered	Split into multiple diagrams, or use `create_from_mermaid` for quick drafts
Arrows cross messily	Rearrange shapes so related ones are adjacent. Vertical flow reduces crossings
Annotations overlap with flow	Use 3-column layout: labels (x<0), flow (x:60-360), annotations (x:570+)
Lost detail from sample diagram	Sample is source of truth for content. Reproduce ALL text verbatim — titles, subtitles, tool lists, metrics, annotations. Size boxes larger if needed

错误	修复方案
之前的图表留下残留元素	每次调用 `clear_canvas()` 后务必调用 `get_canvas_screenshot()` 验证。如果仍有旧元素可见，请再次清空
箭头未正确连接图形	将 `startElementId` / `endElementId` 设置为有效的图形 `id` 值
图形重叠	增加间距。使用240px列间距、140px行间距
标签被截断	加宽图形（200px以上）或缩短文本
无法区分层级	添加带虚线边框和低透明度的区域背景矩形
颜色过多	限制为3-4种填充色。同一角色使用相同颜色
图表过于杂乱	拆分为多个图表，或使用 `create_from_mermaid` 快速生成草稿
箭头交叉混乱	重新排列图形，使相关图形相邻。垂直流布局可减少交叉
注释与流程重叠	使用三列布局：标签(x<0)、流程(x:60-360)、注释(x:570+)
丢失示例图表中的细节	示例是内容的唯一可信来源。逐字重现所有文本——标题、副标题、工具列表、指标、注释。必要时增大图形尺寸

Quick Start Templates

快速入门模板

"Draw me a diagram of X"

“帮我绘制X的图表”

python

undefined

python

undefined

1. Read the code to understand components and connections

1. 读取代码以理解组件和连接关系

2. Read the design guide

2. 读取设计指南

mcp__excalidraw__read_diagram_guide()

3. Clear canvas

3. 清空画布

mcp__excalidraw__clear_canvas()

4. Create everything in one batch

4. 批量创建所有元素

mcp__excalidraw__batch_create_elements(elements=[...])

5. Zoom to fit

5. 缩放以适配内容

mcp__excalidraw__set_viewport(scrollToContent=True)

6. Screenshot to verify

6. 截图验证

mcp__excalidraw__get_canvas_screenshot()

7. Adjust if needed, then export

7. 必要时调整，然后导出

undefined

undefined

"Quick diagram from description"

“根据描述快速生成图表”

python

undefined

python

undefined

For simple diagrams, Mermaid is fastest:

对于简单图表，Mermaid是最快的方式：

mcp__excalidraw__create_from_mermaid( mermaidDiagram="graph TD; A[Frontend] -->|REST| B[API]; B -->|SQL| C[Database]" )

---

mcp__excalidraw__create_from_mermaid( mermaidDiagram="graph TD; A[前端] -->|REST| B[API]; B -->|SQL| C[数据库]" )

---

Export Options

导出选项

Method	Output	Use Case
`export_to_image(format="png")`	PNG file	Embed in docs, Slack, PRs
`export_to_image(format="svg")`	SVG file	Scalable, embed in web pages
`export_scene(filePath="...")`	.excalidraw JSON	Editable in excalidraw.com or VS Code
`export_to_excalidraw_url()`	Shareable URL	Share with anyone, no file needed

方法	输出格式	使用场景
`export_to_image(format="png")`	PNG文件	嵌入文档、Slack、PR
`export_to_image(format="svg")`	SVG文件	可缩放，嵌入网页
`export_scene(filePath="...")`	.excalidraw JSON文件	在excalidraw.com或VS Code中编辑
`export_to_excalidraw_url()`	可分享链接	无需文件，直接分享给任何人