excalidraw-diagrams

创建 Excalidraw 图表

创建 Excalidraw 图表时，请确保：

• 生成的布局间距合适
• 颜色、字体和形状的使用保持一致且符合逻辑
• 文本正确添加在形状内部，而不是作为单独的文本元素（除非有此需求）
• 箭头和线条正确锚定／连接到形状（而非悬空），以便移动对象时连接仍保持完整
• 将 Excalidraw 图表内容保存到文件，并提供文件路径
• 每次会话中，首次调用 create_view 前先调用 read_me——其中包含调色板、画布尺寸、布局规则和元素格式参考。
• 如果用户要求创建 Excalidraw 图表，但你没有启用 Excalidraw MCP，应请他们为你添加；他们可以使用 HTTP MCP URL 进行配置：https://excalidraw-mcp-app.vercel.app/mcp，也可以在此处查看 MCP 文档：https://github.com/excalidraw/excalidraw-mcp

选择工作流

根据用户需求选择一种。不要默认同时使用两种。

仅内嵌预览（create_view）

适用于图表仅用于对话的情况——用户只想在聊天中查看，不需要文件。

• 在形状上使用带有 label 的 create_view（此处效果良好）
• 使用 cameraUpdate 进行动画展示并引导注意力
• 无需输出文件

仅输出文件（Python 脚本）

适用于用户需要 .excalidraw 文件以打开、分享、编辑或留存的情况。完全跳过 create_view。

• 使用 scripts/generate_excalidraw.py 生成文件（见下文）
• 向用户提供文件路径
• 可将文件拖入 excalidraw.com、Excalidraw 桌面应用，或安装 Excalidraw 扩展的 VS Code 中打开

同时提供（内嵌预览 + 文件）

适用于用户既想在聊天中查看图表，又想保留文件的情况。注意：两者使用不同的元素格式，需分别独立构建。二者之间没有数据桥接——你只需在概念上定义一次图表结构，然后分别渲染两次。

• 内嵌预览使用带有 label 的 create_view
• .excalidraw 文件使用带有 labeled_rect 的 Python 脚本

关键：导出后文本无法保留

形状上的 label 属性仅是 create_view 的便捷功能。它在以下场景中不起作用：

• export_to_excalidraw 上传（形状会渲染，但文本不可见）
• 根据 create_view 检查点数据编写的 .excalidraw 文件

请勿使用 export_to_excalidraw 创建可分享的图表。该功能似乎存在 Bug，可能会悄无声息地丢弃所有文本。

原生 Excalidraw 使用两个关联元素表示形状内部的文本：

1. 形状："boundElements": [{"id": "text-id", "type": "text"}]
2. 文本："containerId": "shape-id"、"textAlign": "center"、"verticalAlign": "middle"

文本元素需要 label 简写格式中未包含的字段：fontFamily（1）、width、height、originalText、lineHeight（1.25）、autoResize（true）。

.excalidraw 文件中的所有元素还需要：angle、seed、version、versionNonce、isDeleted、groupIds、frameId、updated、link、locked。

手动编写此 JSON 容易出错。请改用 Python 脚本。

Python 脚本：scripts/generate_excalidraw.py

生成包含所有必需字段的原生 .excalidraw 文件。可在 bash heredoc 中内联使用，也可作为库导入。

主要函数：

函数	返回值	用途
labeled_rect(id, x, y, w, h, bg, stroke, label, ...)	[rect, text]	带居中绑定文本的形状（处理所有绑定和字段生成）
rect(id, x, y, w, h, bg, stroke, ...)	element	不带文本的矩形
txt(id, x, y, w, h, text, size, ...)	element	独立文本或绑定文本
bound_arrow(id, elements, start_id, start_point, end_id, end_point, ...)	element	锚定到两个形状的箭头（会修改形状的 boundElements）
arrow(id, x, y, w, h, points, ...)	element	未绑定／浮动箭头（连接形状时改用 bound_arrow）
ellipse(...) / diamond(...)	element	其他形状类型
write_scene(elements, path)	写入文件	封装为场景结构并保存

示例：

python3 << 'PYEOF'
import sys, random
sys.path.insert(0, "/Users/samm/.claude/skills/excalidraw-diagrams/scripts")
from generate_excalidraw import *

random.seed(42)
elements = []
elements.append(txt("t1", 200, 10, 300, 30, "My Diagram", 24))
elements.extend(labeled_rect("a", 50, 60, 200, 70, "#a5d8ff", "#4a9eed", "Step One"))
elements.extend(labeled_rect("b", 350, 60, 200, 70, "#b2f2bb", "#22c55e", "Step Two"))
elements.append(bound_arrow("a1", elements, "a", [1, 0.5], "b", [0, 0.5]))
write_scene(elements, "/path/to/output.excalidraw")
PYEOF

对于不使用 labeled_rect 便捷函数的形状，可将 rect(..., bound_text="tid") 与 txt(..., container="rid", align="center", valign="middle") 配对使用。

箭头锚定

默认情况下，箭头是自由浮动的——移动形状时，箭头会留在原处。请使用 bound_arrow 而不是 arrow，将箭头锚定到形状。它会自动处理双向绑定（箭头引用形状，形状则在 boundElements 中列出箭头）。

形状连接点的 fixedPoint 值：顶部=[0.5, 0]，右侧=[1, 0.5]，底部=[0.5, 1]，左侧=[0, 0.5]。任何 [fx, fy] 值都有效，其中 0,0 表示形状的左上角，1,1 表示右下角。

重要提示：

• 调用 bound_arrow 前，形状必须已存在于 elements 中，因为该函数会查找形状并修改其 boundElements。
• 连接的形状之间至少间隔 60px。 Excalidraw 会在渲染时重新计算绑定箭头的几何形状。形状距离过近（间隙小于约 60px）时，箭头会重叠并穿过方框，而不是连接到边缘。如果未达到此间距，脚本会发出警告。请规划好布局，留出足够间距。
• 避免使用与可连接形状重叠的大型背景矩形。 当绑定箭头的端点落在与目标形状重叠的背景矩形内部时，Excalidraw 的绑定解析可能出错。如果需要分区背景，请在所有绑定箭头之后添加背景，或改用独立文本标签和颜色编码的方框。

对于内联的 create_view 工作流，请直接在箭头元素上使用 startBinding／endBinding 和 fixedPoint。

隐私

请注意，如果图表包含可能敏感的信息（例如详细的网络图、可识别个人身份的信息等），且用户要求你将图表上传到 excalidraw.com，你应先告知他们上传后图表将公开可访问，并询问他们是否要继续。