reanimate (动画重构) 是做什么的?
照着用户指定的参考,重建动画,使其运动方式与参考一致,通过逐帧对比来证明,并且持续迭代直到对比通过。交付物是位于用户项目中的代码,以及证据(数值和并排对比图),绝不是“看起来差不多就行”。
“完成”的定义
从用户的表述中选取保真度级别,并在第一条消息中说明;它将决定你要验证什么。
| 级别 | 何时使用 | 必须匹配 | 可以不同 |
|---|---|---|---|
| 运动保真(默认) | “克隆这个动画”、“让我们的感觉像他们的”、“同样的主角但我们的文案” | 触发方式、序列和顺序、交错、每一步的时序(±80 毫秒)、缓动族、相对于元素大小的运动方向和距离、布局比例 | 文案、颜色、字体、图片、品牌细节 |
| 像素保真 | “完全匹配”、“像素级精确”、“细节应一致”、“1:1” | 以上所有外加字体、尺寸、颜色、间距、圆角、阴影、资源;平均帧不匹配度 ≤ 2% | 用户未要求更改的任何内容 |
| 混合 | “克隆 X 并添加 Y”、“像他们的但使用我们的定价层级” | 被克隆部分按上述级别之一 | 新增部分,你需要描述并展示,但仅验证其不破坏被克隆的运动 |
用户可以缩小目标范围至一个区块、一个组件、一个页面,或视频的一个时间段(“前 3 秒”、“0:12 至 0:15”)。精确克隆该部分;不要引入页面其余部分。
工作流
以下所有内容位于用户项目内的 .reanimate/<名称>/ 目录下(除非用户希望提交证据到仓库,否则请将其加入 .gitignore)。保留每一轮的人工制品;它们就是证据。
0. 范围界定
在开始任何捕获之前,在 .reanimate/<名称>/spec.md 顶部写下三行:
- 目标:要克隆的内容,尽可能精确地按照用户的描述(URL + 选择器 / 时间段 /“gif 中的开关”)。
- 目标位置:代码放置的位置以及使用的技术栈(读取
package.json、现有组件和正在使用的动画库;匹配它们,而不是引入新的动画库)。 - 保真度:运动保真、像素保真或混合,对于混合模式还需列出新增内容的清单。
尽可能从请求和代码仓库中推断信息。仅当对同一描述有两种不同的解读且会导致不同的工作量时才进行询问(例如,一个页面有两个候选区块时,用户说“那个主角”)。当参考内容被登录墙或无法在此下载的 YouTube/Loom 链接所保护时,请用户提供屏幕录制,并在此期间继续处理其他所有事情。
1. 环境搭建
以下 <skill> 指代本 SKILL.md 所在的目录。脚本需要 Bun;首次运行会下载 Playwright 的 Chromium 和一个静态 ffmpeg(约 250 MB)。
bash <skill>/scripts/setup.sh # 安装 playwright, ffmpeg, pixelmatch;打印 "ready"
所有脚本通过 bun <skill>/scripts/<名称>.ts --help 运行。它们是确定性的,并且遵循一个规则:使用相同的视口、选择器裁剪、触发方式、持续时间和 fps 来捕获参考和克隆,否则比较的结果将反映的是你的环境差异而非你的工作成果。
2. 捕获参考
根据你的源类型,阅读 references/capture.md 中的操作方法。简而言之:
- 网站:
capture.ts --url … --out ref --selector <section> --trigger load|scroll|hover|click|none --duration … --track "<moving elements>"。你将得到video.webm、frames/、inspect.json(声明的动画、关键帧、计算样式、字体、检测到的库)以及track.json(每个动画帧中每个被追踪元素的位置、大小、透明度、变换)。对于 CSS/WAAPI 动画,inspect.json通常包含精确的持续时间、延迟和缓动函数:使用它们,这比估算要好。 - 视频或 gif:
frames.ts --in file --out ref/frames --fps 10..30 --start … --end … --crop …。首先使用--probe探测,然后查看几帧以找到你要克隆的组件的裁剪区域。 - Canvas、WebGL、WebGPU、3D(
inspect.json › canvases显示了一个,或者页面使用了 three.js、Pixi、Babylon、Spline……):在捕获命令中添加--clock virtual --gl --assets,然后阅读gl/summary.md(gl.ts summary <out>)。你将获得着色器源码、每个常量 uniform、场景图、渲染流程、纹理和模型,以及gl-track.json中作为通道的每个动画化的 uniform 或对象属性。虚拟时钟使每一帧都精确,每次捕获都相同,包括随机粒子。阅读references/webgl.md。 - Lottie / Rive / 原型导出:文件本身就是规范;直接阅读它,不要从像素中重新推导。
然后构建带标签的对比图并查看它们:sheet.ts filmstrip --frames ref/frames --out ref/sheets。使用图像查看器阅读每一张对比图。这是用户要求的逐帧检查;不要跳过它或只抽样第一张对比图。
3. 编写运动规范
使用 references/analysis.md 中的模板填充 spec.md。每个元素的每个属性一行:触发方式、开始时间、持续时间、延迟或交错、从 → 到、缓动函数、备注。按优先级顺序从以下来源获取数值:inspect.json 中的动画和关键帧 → 对 track.json 进行 easing.ts 分析,或对 Canvas 使用 gl-track.json --channel → 读取帧(变化的第一个帧、变化的最后一个帧、是否过冲)。同时记录运动依赖的静态信息:元素尺寸和位置、z 轴顺序、溢出裁剪、变换原点,对于像素保真工作还包括字体、颜色、间距和资源。
规范是参考和克隆之间的契约。每一行都将成为第 5 步中的一个检查项。如果某一行带有“?”,说明你还没有完成对帧的读取。
4. 实现
按照 references/implementation.md(缓动表、交错计算、滚动和悬停触发器、减少运动偏好)在用户的技术栈中实现。保持 DOM 结构与参考的角色结构相近,以便被追踪的选择器能有对应项。对于混合工作,将新增内容放在清晰的独立组件或代码块中,并在 spec.md 的“新增内容”部分注明。
为克隆提供一个以与参考相同方式捕获的方法:一个路由或一个静态页面,在参考视口下以相同触发器渲染该组件。开发服务器也可以(capture.ts --url http://localhost:5173/…);独立的 HTML 页面也能工作。
5. 验证、修复、重复
使用与参考完全相同的命令捕获克隆,仅更改 --url 和 --out clone-N,然后:
bun <skill>/scripts/compare.ts --ref ref/frames --clone clone-N/frames --out compare-N
bun <skill>/scripts/sheet.ts compare --ref ref/frames --clone clone-N/frames --diff compare-N/diff --out compare-N/sheets --every 2
bun <skill>/scripts/easing.ts --track clone-N/track.json --selector "<el>" --prop <translateY|opacity|…> --compare-track ref/track.json
对于 Canvas 工作,还需运行 gl.ts compare --ref ref --clone clone-N,它会检查 Canvas 设置、绘制结构和每个动画通道。
阅读 references/verify.md 了解如何解读报告、每个保真度级别的通过标准,以及每种失败通常需要的修复方法。你自己要查看每一轮的对比图;数值告诉你有什么不对劲,对比图告诉你不哪里不对劲。
循环直到每个规范行都通过。每一轮:根据证据指向的最小改动点进行修改,重新捕获,重新比较。预计需要 2 到 5 轮。如果 5 轮后某一行仍然失败,则停止并报告其数值和原因(缺少字体、用户可能无法复制的着色器或模型、你近似处理的物理弹簧),不要悄悄降低阈值或删除该行。
6. 报告
最终消息必须能够独立阅读:
- 保真度级别,克隆了什么,新增了什么。
- 代码位置(文件)以及如何触发运动。
- 最后一轮比较结果的简短表格:时序误差、平均不匹配度、每个关键元素的缓动匹配情况、通过/失败。
- 最终比较图的路径,如果环境支持,则嵌入为图片。
- 残留偏差,每个偏差附带数值和原因。
导致浪费轮次的陷阱
- 参考和克隆之间的视口或裁剪不同:在修改代码之前先修复捕获设置。
- 仅凭第一帧和最后一帧来判断:缓动存在于中间帧;请阅读对比图。
- 字体:不同的后备字体会改变每一帧的像素。对于像素保真工作,在判断不匹配度之前先加载相同的字体(来自
inspect.json的 fonts);对于运动保真工作,忽略文本像素并读取时序列。 - 参考在页面加载完成后录制 vs 克隆在冷启动时捕获:使用
--wait-before,或使用--trigger none并结合一个能重新启动动画的--pre-js,以便两者都从静止状态开始。 - 滚动驱动的运动:它是滚动位置的函数,而不是时间的函数。使用相同的
--scroll-steps和--scroll-ms来捕获两者,并按滚动位置(track 的scrollY)进行比较,而不是按秒。 - JS 库(GSAP、Framer Motion 的弹簧):
--playback-rate无法减慢它们。使用track.json和easing.ts(它会报告过冲和“类似弹簧”),并通过过冲和稳定时间来调整弹簧参数。 - 他人屏幕录制的视频包含光标、浏览器界面和压缩噪声:将它们裁剪掉,并稍微调高
--pixel-threshold(0.15),而不是去追逐噪声。 - Canvas 和 WebGL 在真实时钟上捕获:软件 GL 中会掉帧,并且每次加载的随机内容不同,因此比较的结果反映的是机器性能。使用
--clock virtual和相同的--seed捕获两侧。 - 从截图中重建着色器:追踪报告已经包含了它的源码和每个常量。在编写 GLSL 之前,请阅读
gl/shaders/和固定的 uniforms。