motion

动效

路径：${CLAUDE_SKILL_DIR} 表示包含此 SKILL.md 的文件夹，${CLAUDE_PLUGIN_ROOT} 表示其上两级的插件文件夹。

所有问题都放在问题框中：使用 AskUserQuestion 工具（提供 2-4 个选项，并将推荐选项放在首位）。

每个节拍对应一个片段，专为对应台词制作，绝不是填充内容的模板。模板卡片是备用方案。 M="${CLAUDE_SKILL_DIR}/scripts/motion.py"；路径相对于资源库，就像 style-edit 的路径一样。在 Mac 和 Linux 上用 python3 运行脚本，在 Windows 上用 py 运行。

visuals.json (style-edit step 3) -> motion.py pick -> motion/<id>/{index.html, brief.md, beat.json}
  -> one clip-builder agent per clip -> motion.py check (gates + render) -> motion.py place
  -> visuals.json video_card beats -> plan.py -> stills -> render (the clip plays on its word)

0. 准备好了吗？

python3 "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/setup.py" doctor 会显示 motion clips 正常。Setup 默认会安装它们；在动效步骤之前安装的版本没有这些内容，因此 pick 会自行安装（只需几秒，且只安装一次）。如果安装失败，pick 会打印一次 Animations fell back: ...，并且不会创建片段文件夹：将这行内容告知用户一次。视觉模板仍然可用，而模板只有文字的节拍不会生成卡片（plan.py）。

1. 选择节拍

python3 "$M" pick edits/<name>

读取 visuals.json（由 style-edit 步骤 3 或 visual-prep Agent 写入）和 style.json 中的 motion 区块： {"engine": "clips" | "templates", "amount": 0-1, "kinds": {"counter", "list", "flow", "before_after", "ui_demo", "curve", "logo": true|false}, "look": "default"}。所有分配到动态模板（likes、notes、flow、side_by_side、progress、terminal、chat、toasts、curve、logo_cluster）且至少有 1 s 空余时间的节拍，都会变成片段，最多占其中的 amount 比例。其他类型的节拍（卡片、录屏、贴纸）也会变成片段，前提是其句子属于自然列表（四项或更多：notes）、数字（likes）、步骤（先……再……：flow）或前后对比（side_by_side），每句话最多生成一个片段，且其中尚无动画，并且相应类型已启用。片段未通过检查时，会回退到原始节拍。每个片段都会生成 edits/<name>/motion/<id>/：其中包含填入尺寸、时长、外观和对应台词时间的模板、beat.json（剪辑时间轴）和 brief.md。外观说明见 references/looks.md（default，或使用样式的调色板和字体）。如果用户在聊天中提出请求（“给我说到 X 的部分加上动画”）：先在 visuals.json 中添加或修改该节拍（参见 style-edit 的 references/shapes.md），然后再运行 pick。

2. 构建：每个片段启动一个 clip-builder Agent，全部放在同一条消息中

对于 pick 打印出的每个 motion/<id>/brief.md，启动 clip-builder Agent （${CLAUDE_PLUGIN_ROOT}/agents/clip-builder.md，opus，后台运行），并提供该 brief 的完整路径；所有片段都要放在同一条消息中。每个 Agent 只读取自己的 brief 和 references/clip-brief-card.md，构建 index.html，并最多运行 3 次 motion.py check。绝不要在主会话中构建片段。

整个编辑过程中，剪辑技能会在 visual-prep 返回后立即启动这些 Agent，同时用户仍在审核剪辑，因此剪辑获批时片段也已准备就绪。

3. 检查片段（各 Agent 运行的检查）

python3 "${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py" "$M" check edits/<name>/motion/<id>

按顺序运行：check_clip.py（检查源文件中的常见问题，免费）、hyperframes lint、hyperframes check --at-transitions、渲染、check_motion.py（检查是否卡顿、突变以及第 0 帧闪烁）、check_composition.py（仅供参考）、measure_ink.py，然后生成 renders/sheet.png（1 fps）和 renders/strip.png（前 1.2 s，10 fps）。写入 gates.json。阈值见 references/clip-brief-card.md。各类常见问题的原因见 references/build-loop.md。完整规则见 references/visual-system.md；在一个片段中组合多个想法，参见 references/scenes.md。

4. 查看，然后放置

Agent 返回后，亲自对照对应文案查看每个 renders/sheet.png（最好找一个没听过这个节拍的新读者：画面能表达这句文案吗？）。如果某个片段表达不对：把意见发给它的 Agent，再修改一轮。然后：

python3 "$M" place edits/<name>

通过审核的片段会成为 video_card 节拍，并使用渲染文件（images/motion-<id>.mp4）；clip_motion.py 会设置 start_s，确保动画在卡片离开前 0.25 s 结束。多轮修改后仍未通过的片段会保留模板节拍（存放在 fallback 中，由 place 恢复）。然后从步骤 4 继续进行样式编辑（规划、静帧、渲染）。每次重新构建后都要重新运行 place。

5. 检查动画

静帧看不出闪烁。渲染完成后，为至少四个片段的入场制作条带，并绘制安全区域：

python3 "$M" strips edits/<name>/render.mp4 --at <t1>,<t2>,<t3>,<t4> --out edits/<name>/stills/motion-strips.png --safe

每一行显示其时间点前 0.4 s 到后 1.1 s 的画面，帧率为 10 fps。留意某个元素是否只在一帧中出现后就消失、卡片之间是否有空白帧、元素在显示期间是否始终静止、是否有元素遮挡人脸或超出边框。

关于片段的备注

当片段显示时，在某个时间点添加一条审阅页面备注（“把计数器放大”“改成蓝色”）：

python3 "$M" note edits/<name> "make the counter bigger" --at <note time>

它会将备注写入该片段的 notes.md，并打印片段。将它的 brief.md 交给一个 clip-builder（最多再检查 2 次），然后运行 place、规划和 edit.py patch（样式编辑）：只重建该片段，并且只重新渲染它的时段（每个已放置的渲染文件都有自己的文件名，因此补丁能识别变更）。

动画库

用户批准渲染后：运行 python3 "$M" save edits/<name>。每个已放置的片段都会存入 $AI_EDITOR_HOME/motion-library/<id>/（构图、简报、缩略图及其来源样式）。pick 会将同类中最新的片段（或标记为“再次使用”的片段）作为 start.html 提供，作为 Agent 重新调整时长并修改的起点，而不是副本（未修改的内容会导致 check 失败）。归档的片段绝不会被使用。窗口中的样式页面会列出这些片段（Archive、Delete、Use again）；在聊天中运行：python3 "$M" library [archive|unarchive|use <id>]。

设置

style.json motion（样式页面的 Motion 部分会通过用户的修改写入该设置）：amount（0 表示无，0.5 表示少量，1 表示大量；未设置时，使用测量所得样式的动画占比）、kinds（每种效果均可开启或关闭）、look （default、editorial、editorial-dark、mono、poster-red、poster-green、poster-blue）。engine: "templates" 会保留模板卡片。

50/50 样式

分屏布局样式（style.json layout.mode: "split"，示例 50/50）：每个片段都针对面板上的艺术区域构建，使用面板底色，并从边缘到边缘播放；panel 检查项（角落处的底色，墨色覆盖率超过 55%）和四项验证（verify.mjs）会阻止不合格内容。变体、规则和抠图说明见：references/fifty-fifty.md。

Motion design 样式

看板布局样式（style.json layout.mode: "board"，示例 Motion design，16:9）：片段作为说话者旁边的叠加层，采用 board 风格，尺寸为 1200x964（近黑色底色、银白色墨色）。Logo 不属于片段：它们会作为图块放置在画布上。规则见：references/board.md。

技能样式

用户自己的样式技能只需一句话即可生成专属动画：“Animations: use the motion skill”。

如果脚本停止运行

提示	操作
the motion tools are not installed / Animations fell back	运行 setup.py motion，然后重试同一命令；如果再次失败，说明一次该情况，然后继续，不使用片段
某个片段经过检查后仍为 FAIL（构建时检查 3 次，每条备注还可再检查 2 次）	保留该片段：place 会恢复其模板
no frames read（条带）	渲染路径不正确，或渲染失败：查看样式编辑步骤 7

文件

• scripts/motion.py（pick、check、place、status、strips）、check_clip.py、check_motion.py、 check_composition.py、measure_ink.py、clip_motion.py：每个文件都带有 demo 自检。
• template/：每个片段的起始 HyperFrames 合成。
• scripts/verify.mjs：在 Chrome 中逐帧检查四项验证（clipped、rails、neighbour、reading）。
• references/：clip-brief-card.md（每个 Agent 都会阅读的核心文档）、visual-system.md、build-loop.md、 scenes.md、looks.md、fifty-fifty.md、board.md。
• HyperFrames 采用 Apache-2.0 许可证（github.com/heygen-com/hyperframes），GSAP 使用其标准免费许可证 （gsap.com/standard-license）；二者均由 setup 从 npm 安装，不包含在此处。