通过 MCP 使用 Excalidraw
只需说“使用 Excalidraw MCP”，就能绘制一个复杂的图表并保存到正确位置。这个技能让这一切变为现实。
唯一会破坏一切的问题
create_view 的元素格式是骨架，而不是磁盘存储模式。形状的 label 仅是骨架中的语法糖。Excalidraw 的画布渲染器没有针对矩形/椭圆/菱形的文本分支——容器文本仅通过 boundElements → containerId 绘制。因此，将 create_view 的 JSON 粘贴到 .excalidraw 文件中会产生空盒子，且没有任何提示。这正是 scripts/excalidraw_build.py 存在的原因：在骨架中编写一次，即可同时获得实时渲染和正确的文件。
第二个事实：手工绘制的图表不会随着尺寸增加而逐渐退化——它们会在不规则性上失败。根据对一个真实生成场景的测量，通过重复布局公式产生的元素错误率为 0.00；而手工创建的一次性元素错误率为 0.71。因此，应使用公式计算位置，并让检查工具验证结果。
新机器上的预检
安装此技能不会安装 MCP 服务器——mcp-deps 只是一个声明，vskill check 会验证它，而不是一个安装程序。如果 mcp__excalidraw__* 工具不可用，请先运行以下命令——它会检测并注册服务器，支持任何操作系统：
python3 scripts/ensure_mcp.py --install
它会报告服务器的位置，或者运行 claude mcp add --transport http --scope user excalidraw https://mcp.excalidraw.com 并重新验证。退出码 0 表示已配置，1 表示缺失，2 表示无法注册（PATH 中没有 Claude CLI——它会打印需要手动运行的命令）。Claude Code 在添加新服务器后需要重启才能识别。
作用域：--scope user（默认）通过 ~/.claude.json 覆盖机器上的所有项目；--scope project 写入 ./.mcp.json，这样团队成员在克隆时也能获得；--scope local 仅限本项目。如果服务器在不同的项目中注册，则视为缺失——Claude Code 不会在此处加载它，脚本会给出相应提示。
即使没有 MCP，除了实时内联渲染之外的所有功能仍然正常工作。 excalidraw_build.py 和 excalidraw_lint.py 是仅使用标准库的 Python 3 脚本——无需安装包，无需网络。构建文件、检查文件、交付文件。excalidraw_render.py 额外需要 pip install playwright && playwright install chromium。
Windows
使用 py -3 和反斜杠；Windows 上的 python3 是一个 Microsoft Store 存根，只会打开商店而不会运行任何程序。
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
其他所有内容都是可移植的：路径通过 pathlib 处理，输出使用显式的 UTF-8 和 \n 换行符写入，这样 Windows 运行不会在场景 JSON 中引入 CRLF，预检脚本能解析 claude.cmd / claude.exe 以及 claude。如果 vskill i 警告符号链接不可用，它会回退到复制——启用开发者模式即可恢复符号链接。
工作流程
- 预检（仅新机器）：如果
mcp__excalidraw__*工具缺失，运行python3 scripts/ensure_mcp.py --install（Windows 上用py -3）。 - 编写骨架。 一个 JSON 数组，与
create_view接收的格式相同。位置来自布局公式（参见references/layout-recipes.md），绝不能靠目测。 - 检查骨架——离线，无依赖，可检测溢出/重叠/几何错误：
python3 scripts/excalidraw_lint.py scene.json --camera--camera会打印一个正确取景的 4:3cameraUpdate，可以粘贴到顶部。 - 实时渲染使用
mcp__excalidraw__create_view，元素按 z 顺序流式传输并带有相机移动（参见references/mcp-workflow.md）。保留返回的checkpointId。 - 保存文件当用户希望保存到磁盘时：
python3 scripts/excalidraw_build.py scene.json -o out.excalidraw python3 scripts/excalidraw_build.py scene.json -o out --obsidian # → out.excalidraw.md python3 scripts/excalidraw_build.py scene.json -o out.excalidraw --dark - 检查结果在宣布任何复杂图表成功之前。此渲染通过 Excalidraw 自己的
exportToSvg完成，因此文本使用真实字体度量进行测量：
然后读取 PNG。修正发现的问题；重新检查；重新渲染。python3 scripts/excalidraw_render.py out.excalidraw -o /tmp/preview.png
步骤 2 和 5 是质量控制门。跳过它们会导致标签出现在盒子外面，箭头指向空白处。
骨架速查表
{"type":"rectangle","id":"api","x":100,"y":80,"width":180,"height":80,
"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid",
"strokeColor":"#4a9eed","label":{"text":"API Gateway","fontSize":18}}
{"type":"arrow","id":"e1","from":"api","to":"db","label":{"text":"SQL"}} // 自动绑定
{"type":"arrow","id":"e2","from":"api","to":"db","route":"ortho"} // L 形
{"type":"arrow","id":"e3","x":300,"y":150,"points":[[0,0],[120,0]]} // 手动
{"type":"text","id":"ttl","center":400,"y":20,"text":"Title","fontSize":24} // 自动居中
{"type":"rectangle","id":"zone","x":40,"y":40,"width":700,"height":420,
"opacity":30,"zoneLabel":"Data layer"} // 标题，非绑定标签
仅构建器支持的扩展：from/to（周界锚点 + 双向绑定）、route:"ortho"、zoneLabel、center（文本上）、fixedWidth（形状上，用于换行而非扩展）。其他所有内容都会原样传递，因此同一数组仍可直接与 create_view 配合使用。
永远不要将绑定的 label 放在背景区域矩形上——它会居中在区域中间且无法抓取。请使用 zoneLabel。
选择输出
| 目标 | 命令 | 说明 |
|---|---|---|
| 立即展示给用户 | create_view | 动画、相机引导；返回 checkpointId |
| 保存到仓库文件 | excalidraw_build.py -o x.excalidraw | 可在 excalidraw.com 或 VS Code 扩展中打开 |
| Obsidian 库 | ... -o x --obsidian | .excalidraw.md，可被插件解析、Git 可对比 |
| 可分享链接 | mcp__excalidraw__export_to_excalidraw | 上传到 excalidraw.com——请先询问 |
MCP 没有本地文件工具。export_to_excalidraw 是公开上传，因此将其视为发布：在调用前需征得用户同意。
迭代
create_view 返回一个 checkpointId。要从中继续——包括用户在全屏模式下所做的编辑——在下一次数组开头添加 {"type":"restoreCheckpoint","id":"<checkpointId>"}，并仅追加新元素。使用 {"type":"delete","ids":"a,b"} 删除元素；切勿重用已删除的 id。保持磁盘上的骨架文件同步，因为该文件用于构建和检查。
参考
references/file-format.md— 磁盘存储模式，已根据上游验证：字体代码、绑定文本、箭头几何、绑定关系、Excalidraw 在打开时会重新计算什么以及不会重新计算什么。手动编辑任何.excalidraw文件前请先阅读。references/mcp-workflow.md— 相机编排、流式传输顺序、检查点、暗色模式以及 MCP 自身的限制。references/layout-recipes.md— 流式布局、分层布局、泳道图、时序图、网格布局、径向布局和矩阵布局的公式，以及如何保持 60 元素图表的可读性。references/obsidian.md—.excalidraw.md包装器、块引用规则以及压缩场景的陷阱。scripts/ensure_mcp.py— 在任何操作系统上检测并注册 Excalidraw MCP 服务器。scripts/split_excalidraw_library.py— 将.excalidrawlib（来自 libraries.excalidraw.com 的 AWS/GCP/K8s 图标包）拆分为每个图标的 JSON 文件和查找表，这样图标数据就不会进入上下文。
值得明确的限制
- 宽度估计是基于每个字符校准的，并非从字体二进制文件中测量；检查工具会在溢出 10% 范围内发出警告。当它对重要内容发出警告时，请进行渲染。
excalidraw_render.py需要playwright以及对 esm.sh 的网络访问。没有这些，检查仍然完全离线可用。- 检查工具无法判断图表是否优秀，只能判断是否正确。构图仍然是你的工作。
变更日志
- 1.2.0 —
scripts/ensure_mcp.py：跨平台预检，可检测 MCP 服务器（包括~/.claude.json中的项目级映射）并在缺失时注册。Windows 支持：记录了py -3、claude.cmd解析、每次写入都使用显式 UTF-8 和\n换行符。 - 1.1.1 — 检查工具不再对箭头容器应用盒子适配规则（R1/R2）；箭头标签沿着路径放置，由 R10 覆盖。
- 1.1.0 — 移入
skills/excalidraw-mcp/的 vskill 单体仓库，与remotion-best-practices和其他仓库内技能保持一致。独立的anton-abyzov/excalidraw-mcp-skill仓库已弃用。 - 1.0.1 — 文档化 MCP 设置：安装技能不会安装服务器；添加了
claude mcp add单行命令以及没有它时仍能正常工作的内容。 - 1.0.0 — 首次发布。替换了仅文件的
excalidraw-diagram-generator技能，该技能的模板在形状上内联生成了text，因此打开时显示为空盒子。