excalidraw-use

Excalidraw：将图片放到画布上

Excalidraw 是一个供人们实时绘图的白板。本技能涵盖一项手动操作起来颇为繁琐的工作：将大量现有图片放到画布上，并妥善排布，让用户之后不必再把它们拖开。

它不会根据文字描述生成图表。如果用户要求“画出架构图”或“制作流程图”，那属于图表生成任务——有多个工具和技能可以完成，包括 gstack 套件中的 diagram 技能（如果用户已安装）。

这是哪种任务？

用户说	前往
“把这些图片放到我的画布上”“把旧截图添加到画布上”	任务 1 — 创建图片选取托盘
“把演示文稿转换成图片”“给每张幻灯片截图”	任务 2 — 将演示文稿转成图片，然后执行任务 1
“这个文件里有什么”“这个画布有多大”“有没有损坏的内容”	任务 3 — 检查
“根据这段描述给我画个流程图”	不属于此技能

任务 1 — 创建图片选取托盘

python3 scripts/build_scene.py \
  --out tray.excalidraw \
  --cols 6 \
  --template-from ~/path/to/their-board.excalidraw \
  --exclude already-placed.png \
  images/*.png

预期输出 — 如果看不到 verified: 行，文件就不可用：

verified: 30 image element(s), hashes match, no overlap
placed 30 image(s), 6 x 5 grid, min gap 600
wrote tray.excalidraw (3.5 MB)

将文件和如何把文件放到画布上的方法一并交给用户。 后半部分最容易出错：在 excalidraw.com 上，Open 和拖放操作都会替换整个当前场景。如果用户当前有一个正在使用的画布，告诉他们“打开这个文件”就等于让他们丢掉画布内容。追加内容的方式是使用剪贴板——完整说明及其原因见 references/paste_workflow.md。撰写交付说明前，请先阅读该文件。

有三个决定值得认真考虑：

• 用户有现有画布时，始终使用 --template-from。 Excalidraw 发布的 JSON 架构文档说明了顶层结构和 files 映射，但没有说明图片元素自身的字段（fileId、status、scale、crop），因此，复制用户画布中的实时元素是确保字段集与其实际运行的构建版本匹配的唯一方法。不使用该选项时会采用一个合理的默认值；它虽已验证可用，但只是观察到的一种字段集，并非规范。references/scene_file_format.md 逐字段进行了拆解，并将官方文档中的说明与从真实文件中读取的信息分开；如果需要手动构建或修复场景，而不是让脚本生成，请阅读该文件。
• 使用 --exclude 排除用户画布上已有的内容。 检查依据是图片内容，而非文件名，因此即使重命名过的副本也会被识别。跳过此步骤会导致用户看到同一张图片出现两次，还得手动删掉一张。
• 间距。 --cell 是每张图片缩放后的最长边；--pitch 是单元格中心之间的距离。间隙为 pitch - cell，默认值（800 / 1400 → 600）特意设得比较宽松。如果用户曾说过“别再让我调整间距”，就调高 --pitch，不要调低。

如果场景超过约 15 MB，请将其拆分——大场景会卡在剪贴板这一步：

python3 scripts/split_scene.py --scene tray.excalidraw --out-dir parts/ --chunks 4

任务 2 — 将幻灯片转换为整洁的图像

适用于 Vite/React 幻灯片，其中的幻灯片在 src/slides/index.ts 中注册， 条目格式为 { id: 'intro', component: S01, fragmentCount: 3 }。

# 1. Build the deck FROM SOURCE and serve that build (not a dev server).
cd <deck>; npx vite build --outDir /tmp/deck-dist --emptyOutDir
cd /tmp/deck-dist && python3 -m http.server 8080 &

# 2. Shoot it.
node scripts/shoot_deck.mjs \
  --index <deck>/src/slides/index.ts \
  --url http://127.0.0.1:8080/index.html \
  --out shots/ \
  --advance pdf     # or: keys

预期输出：

30 slides (7 with fragments), advance=pdf
30/30 captured, 32 inline chrome element(s) hidden -> shots/
all .fragment elements rendered visible (opacity check)

最后那一行才是关键。如果看到的是 WARNING: N slide(s) have fragments that never revealed，说明这些截图缺少内容——不要将它们交给任务 1。请阅读 references/deck_screenshot_pitfalls.md； 通常是因为正在提供服务的构建版本比源代码旧。

无论从哪里运行脚本，都必须能解析到 puppeteer。 通常，能够自行生成 PDF 的幻灯片项目已经安装了它——请从该项目运行脚本，或将其 node_modules 软链接到脚本所在目录旁。npx puppeteer 不会安装可供 ESM 导入解析的模块。

选择 --advance： 在幻灯片的 Deck 组件中搜索 pdf。如果它读取 ?pdf=1 查询参数，就使用 pdf；否则使用 keys。不要同时使用两者——在 ?pdf=1 模式下，片段索引已达到最大值，因此额外的按键会转到下一张幻灯片，导致你在不知情的情况下截取错误内容。

添加 --strict，可在此脚本于流水线中运行时，将未显示的片段作为非零退出状态处理。默认情况下它仍只是警告，因此合理地将某个 .fragment 保持隐藏的幻灯片不会导致整个运行失败。

任务 3 — 检查场景

python3 scripts/inspect_scene.py board.excalidraw --images

报告各类型元素的数量、嵌入内容的大小、每个图像元素是否都能找到对应文件且文件内容仍与其键匹配，以及占用范围。此操作只读。

占用范围是实际最有用的数值：粘贴的内容会落在视口所在位置，因此了解现有内容的位置，才能告诉用户粘贴前应滚动到哪里。

切勿写入用户正在使用的白板文件

请构建一个单独的场景文件，让用户从中粘贴内容。这样做有两个独立的理由，且都已实际发生过：

• 浏览器标签页中打开的白板不会在磁盘文件发生变化时重新加载；而下一次在应用内保存时，会覆盖你写入的内容。
• 磁盘上的文件通常比浏览器中的状态旧——有人几天前导出了文件，此后一直在标签页中继续编辑。合并到该导出文件会悄无声息地丢失他们之后所做的所有更改。

如果确实需要合并文件，请将其写入新路径，由用户选择要打开哪个文件。绝不要覆盖原文件。

故障排查

症状	原因	修复方法
场景已打开，但图片为空白	缺少 files 条目，或其键与内容不匹配	inspect_scene.py 会报告这两种情况；请重新构建
白板上的图像相互接触或重叠	--pitch 不大于 --cell	脚本会拒绝此组合；请增大 --pitch
粘贴无反应 / 耗时过长	场景对于剪贴板来说太大	使用 split_scene.py，然后逐个粘贴各部分
粘贴替换了整个白板	使用了打开 / 拖放，而不是复制粘贴	请参阅 references/paste_workflow.md；使用应用内撤销恢复
截取的幻灯片缺少后续内容	片段从未显示	从源代码重新构建幻灯片，重新提供服务，再次截图
幻灯片截图中出现按键徽标	等待徽标消失的时间不足	脚本在最后一次按键后已等待约 2.9 秒；如果某个幻灯片停留时间更长，请延长等待时间
Cannot find package 'puppeteer'	无法从脚本所在位置解析该模块	从已安装该模块的项目运行
图像绘制成了错误的形状	元素的宽高比与源图像不匹配	build_scene.py 会因此失败，而不会写入文件

下一步

构建好托盘后，自然的后续步骤就是粘贴，而这只能由用户完成。告诉他们文件路径、滚动到空白区域的提醒以及三个按键的顺序——然后停止。不要打开 excalidraw.com 来“验证”文件：在那里加载场景会替换该浏览器当前会话中的内容，而其中可能正是你试图保护的白板。