excalidraw-skill

Excalidraw 技能

步骤 0：检测连接模式

开始任何操作之前，先确定可用的模式。按以下顺序运行这些检查：

检查 1：MCP 服务（体验最佳）

mcp-cli tools | grep excalidraw

如果看到 excalidraw/batch_create_elements 等工具 → 使用 MCP 模式。直接调用 MCP 工具。

检查 2：REST API（备用方案 — 无需 MCP 服务即可使用）

curl -s http://localhost:3000/health

如果得到 {"status":"ok"} → 使用 REST API 模式。使用速查表中的 HTTP 端点（curl / fetch）。

检查 3：都无法使用 → 指引用户安装

如果两者都无法使用，请告知用户：

Excalidraw 画布服务未运行。设置方法：

1. 克隆：git clone https://github.com/yctimlin/mcp_excalidraw && cd mcp_excalidraw
2. 构建：npm ci && npm run build
3. 启动画布：HOST=0.0.0.0 PORT=3000 npm run canvas
4. 在浏览器中打开 http://localhost:3000
5. （推荐）安装 MCP 服务以获得最佳体验：

   claude mcp add excalidraw -s user -e EXPRESS_SERVER_URL=http://localhost:3000 -- node /path/to/mcp_excalidraw/dist/index.js
   

MCP 与 REST API 速查

操作	MCP 工具	REST API 对应方式
创建元素	batch_create_elements	使用 {"elements": [...]} 执行 POST /api/elements/batch
获取所有元素	query_elements	GET /api/elements
获取单个元素	get_element	GET /api/elements/:id
更新元素	update_element	PUT /api/elements/:id
删除元素	delete_element	DELETE /api/elements/:id
清空画布	clear_canvas	DELETE /api/elements/clear
描述场景	describe_scene	GET /api/elements（手动解析）
导出场景	export_scene	GET /api/elements（保存到文件）
导入场景	import_scene	使用 {"elements": [...]} 执行 POST /api/elements/sync
快照	snapshot_scene	使用 {"name": "..."} 执行 POST /api/snapshots
恢复快照	restore_snapshot	执行 GET /api/snapshots/:name，然后执行 POST /api/elements/sync
截图	get_canvas_screenshot	仅可通过 MCP 使用（需要浏览器）
设计指南	read_diagram_guide	不可用 — 指南请参阅速查表
视口	set_viewport	POST /api/viewport（需要浏览器）
导出图像	export_to_image	POST /api/export/image（需要浏览器）
导出 URL	export_to_excalidraw_url	仅可通过 MCP 使用

REST API 注意事项（重要 — 使用 REST API 前请阅读）

1. 标签：使用 "label": {"text": "My Label"}（而不是 "text": "My Label"）。MCP 工具会自动转换，REST API 不会。
2. 箭头绑定：使用 "start": {"id": "svc-a"}, "end": {"id": "svc-b"}（而不是 "startElementId"/"endElementId"）。MCP 工具接受 startElementId 并进行转换；REST API 则要求直接使用 start/end 对象格式。
3. fontFamily：必须是字符串（例如 "1"），或者完全省略。请勿传入 1 这样的数字。
4. 更新标签：通过 PUT /api/elements/:id 更新形状时，请在更新内容中包含完整的 label，以保留标签。从更新内容中省略 label 不会删除它，但重新发送可确保正确渲染。
5. REST 模式下的截图：POST /api/export/image 会返回 {"data": "<base64>"}。保存到文件后再读取，以进行视觉验证。需要打开浏览器。

质量关卡（必须执行 — 创建任何图表前请阅读）

每次迭代（每批新增的元素）之后，都必须先进行质量检查，再继续操作。只有所有检查都通过后，才能说“看起来很棒”。

质量检查清单 — 添加更多元素前，请逐项核验：

1. 文本截断：所有文本是否都完整可见？标签必须能完整显示在形状内。如果文本被截断或换行不佳 → 增加 width 和/或 height。
2. 重叠：是否有任何元素彼此重叠？检查矩形、椭圆或文本元素是否占用相同空间。背景区域必须留有内边距，完整容纳其子元素。
3. 箭头交叉：箭头是否穿过无关元素或与文本标签重叠？如果是 → 使用带路径点的弯曲/折线箭头绕开障碍物（参见“箭头布线”部分）。绝不接受箭头交叉。
4. 箭头与文本重叠：箭头标签（“charge”“event”等）是否与形状重叠？箭头标签位于中点 — 如果重叠，则移除标签、缩短标签或调整箭头路径。
5. 间距：元素之间是否至少留有 40px 的间隔？拥挤的布局难以阅读。
6. 可读性：在正常缩放比例下，所有标签是否清晰可读？正文的字号 >= 16，标题的字号 >= 20。

如果发现任何问题：

• 停止添加新元素
• 先修复问题（调整大小、重新定位、删除并重新创建）
• 使用新的截图重新核验
• 只有通过所有检查后，才继续下一轮

尺寸规则（防止文本截断）：

• 形状宽度：max(160, labelTextLength * 9) 像素。对于“API Gateway (Kong)”这类多词标签，请计算所有字符。
• 形状高度：单行 60px，2 行 80px，3 行 100px。
• 背景区域：在所包含元素的四周各留出 50px 内边距。
• 元素间距：层级之间垂直间隔 60px，同级元素之间水平间隔 40px。
• 侧边面板：与主图元素至少相距 80px。
• 箭头标签：标签应简短（1-2 个词）。较长的箭头标签会与其他元素重叠。

布局规划（防止重叠）：

创建元素之前，先在纸上规划坐标网格：

• 第 1 层（y=50-130）：客户端应用
• 第 2 层（y=200-280）：网关/边缘
• 第 3 层（y=350-440）：服务（横向分散：每个服务约间隔 180px）
• 第 4 层（y=510-590）：数据存储
• 侧边面板：x < 0（左侧）或 x > 主图右边界 + 80（右侧）

不要将侧边面板（可观测性、外部 API）放在与主图相同的 x 范围内 — 它们一定会重叠。

快速开始

1. 运行上方的步骤 0，检测连接模式。
2. 在浏览器中打开画布 URL（导出图像/截图时必需）。
3. MCP 模式：所有操作都使用 MCP 工具。REST 模式：使用速查表中的 HTTP 端点。
4. 如需完整的工具/端点参考，请阅读 references/cheatsheet.md。

工作流：绘制图表

MCP 模式

1. 首先调用 read_diagram_guide，了解设计最佳实践。
2. 在编写任何 JSON 之前，先规划坐标网格（参见“质量关卡” → “布局规划”）。
3. 可选：使用 clear_canvas 清空画布。
4. 使用 batch_create_elements，在一次调用中创建形状和箭头。
5. 为形状分配自定义 id（例如 "id": "auth-svc"）。将标签设为形状的 text 字段。
6. 根据文本设置形状尺寸 — 使用 width: max(160, textLength * 9)。
7. 使用 startElementId / endElementId 绑定箭头 — 箭头会自动布线。
8. 使用 set_viewport 并设置 scrollToContent: true，自动适配图表。
9. 运行质量检查清单 — 使用 get_canvas_screenshot 并进行严格评估。继续之前先修复问题。

REST API 模式

1. 阅读 references/cheatsheet.md，了解设计指南。
2. 编写任何 JSON 之前，先规划坐标网格（参见质量门禁 → 布局规划）。
3. 可选：curl -X DELETE http://localhost:3000/api/elements/clear
4. 一次调用创建元素（大型负载请使用 @file.json）：

   curl -X POST http://localhost:3000/api/elements/batch \
     -H "Content-Type: application/json" \
     -d '{"elements": [
       {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 160, "height": 60, "label": {"text": "Service A"}},
       {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 160, "height": 60, "label": {"text": "Service B"}},
       {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}}
     ]}'
   

5. 形状标签请使用 "label": {"text": "..."}（而不是 "text": "..."）。
6. 使用 "start": {"id": "..."} / "end": {"id": "..."} 绑定箭头——服务会自动路由边。
7. 根据文本调整形状大小——使用 width: max(160, labelTextLength * 9)。
8. 运行质量检查清单——截图并认真评估。添加更多元素之前先修复问题。

箭头绑定（推荐）

将箭头绑定到形状，以自动路由边。MCP 与 REST API 的格式不同：

MCP 模式——使用 startElementId / endElementId：

{"elements": [
  {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 120, "height": 60, "text": "Service A"},
  {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 120, "height": 60, "text": "Service B"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "svc-b", "text": "calls"}
]}

REST API 模式——使用 start: {id} / end: {id} 和 label: {text}：

{"elements": [
  {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 120, "height": 60, "label": {"text": "Service A"}},
  {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 120, "height": 60, "label": {"text": "Service B"}},
  {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}, "label": {"text": "calls"}}
]}

未绑定的箭头使用手动 x、y、points 坐标。

箭头路由——避免重叠（复杂图表的关键）

直线箭头（2 个点）会在复杂图表中造成交叉和重叠。请改用曲线箭头或折线箭头：

选项 1：曲线箭头——添加中间路径点和 roundness：

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2},
  "strokeColor": "#1971c2"
}

路径点 [50, -40] 会将箭头向上推，使其绕过元素。roundness: {type: 2} 会使其成为平滑曲线。

选项 2：折线箭头——直角路由（L 形或 Z 形）：

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true,
  "strokeColor": "#1971c2"
}

适用场景：

• 扇出箭头（一个源连接多个目标）：使用带路径点的曲线箭头，并在垂直方向错开路径点，以避免彼此重叠。
• 跨泳道箭头（连接到侧面板）：使用折线箭头绕过主图表进行路由——先向上，再横向，然后向下。
• 服务间箭头（水平连接）：使用带轻微垂直偏移的曲线箭头，避免穿过相邻元素。

**经验法则：**如果箭头会穿过无关元素，就添加路径点绕开它。绝不接受箭头交叉——务必修复。

工作流：迭代优化（核心差异）

让这项技能与众不同的反馈循环。每次迭代都必须包含质量检查。

MCP 模式（完整反馈循环）

1. 添加元素（batch_create_elements、create_element）。
2. 使用 scrollToContent: true 调用 set_viewport。
3. 调用 get_canvas_screenshot——根据质量检查清单认真评估。
4. 如果发现问题 → 修复问题（update_element、delete_element、调整大小、重新定位）。
5. 再次调用 get_canvas_screenshot——重新验证修复结果。
6. 只有在所有质量检查都通过后，才能进入下一次迭代。

REST API 模式（部分反馈循环）

1. 通过 POST /api/elements/batch 添加元素。
2. 使用 {"scrollToContent": true} 调用 POST /api/viewport。
3. 截图：调用 POST /api/export/image → 保存 PNG → 根据质量检查清单认真评估。
4. 如果发现问题 → 通过 PUT /api/elements/:id 修复，或删除后重新创建。
5. 重新截图并再次验证。
6. 只有在所有质量检查都通过后，才能进入下一次迭代。

如何认真评估截图：

• 检查每个标签——是否有文本被截断，或溢出容器？
• 检查每条箭头——是否有箭头穿过无关元素？
• 检查所有元素对——是否存在重叠或接触？
• 检查间距——是否有内容挤在一起？
• 如实评估。如果发现任何问题，就说“我发现了[问题]，正在修复”，而不是“看起来很棒”。

示例流程（MCP）：

batch_create_elements → get_canvas_screenshot → "text truncated on 2 shapes"
→ update_element (increase widths) → get_canvas_screenshot → "overlap between X and Y"
→ update_element (reposition) → get_canvas_screenshot → "all checks pass"
→ proceed to next iteration

工作流：优化现有图表

1. 调用 describe_scene 了解当前状态。
2. 按 id、类型或标签文本（而不是 x/y 坐标）确定目标。
3. 使用 update_element 移动、调整大小或更改颜色，使用 delete_element 删除。
4. 调用 get_canvas_screenshot，直观验证更改。
5. 如果更新失败：检查元素 id 是否存在（get_element），以及元素是否已锁定（unlock_elements）。

工作流：文件 I/O（代码绘图）

• 导出为 .excalidraw 格式：使用 export_scene，可选参数为 filePath。
• 从 .excalidraw 导入：使用 import_scene，并设置 mode: "replace" 或 "merge"。
• 导出为图像：使用 export_to_image，设置 format: "png" 或 "svg"（需要打开浏览器）。
• CLI 导出：node scripts/export-elements.cjs --out diagram.elements.json
• CLI 导入：node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync

工作流：快照（保存／恢复画布状态）

1. 在进行高风险更改前，使用 snapshot_scene 并指定名称。
2. 进行更改，然后使用 describe_scene / get_canvas_screenshot 进行评估。
3. 如有需要，使用 restore_snapshot 回滚。

工作流：复制

• 使用 duplicate_elements 并指定 elementIds，可选参数为 offsetX / offsetY（默认值为 20,20）。
• 适用于创建重复图案或复制现有布局。

箭头／直线的 points 格式

points 字段支持以下两种格式：

• 元组：[[0, 0], [100, 50]]
• 对象：[{"x": 0, "y": 0}, {"x": 100, "y": 50}]

两种格式都会自动规范化为元组。

工作流：分享图表（excalidraw.com URL）

1. 使用上述任意工作流创建图表。
2. 使用 export_to_excalidraw_url 上传加密后的场景，并获取可分享的 URL。
3. 分享该 URL，任何人都可以在 excalidraw.com 打开并查看和编辑。

工作流：视口控制

• 使用 set_viewport 并设置 scrollToContent: true，自动适应所有元素（缩放至适配）。
• 使用 set_viewport 并设置 scrollToElementId: "my-element"，将视图居中到指定元素。
• 使用 set_viewport 并设置 zoom: 1.5, offsetX: 100, offsetY: 200，手动控制视图。

参考资料

• references/cheatsheet.md：完整的 MCP 工具列表（26 个工具）+ REST API 端点 + 负载结构。

相关技能

• 另请参阅：figure-generation、algorithm-design、slide-generation