reanimate

reanimate

重建用户指定的内容，让它以与参考动画相同的方式动起来；通过逐帧对比证明效果，并持续迭代，直到对比通过。交付内容是用户项目中的代码和证据（数值及并排对比图），绝不是“看起来差不多”。

什么才算“完成”

根据用户的描述选择保真度级别，并在第一条消息中说明；这将决定需要验证的内容。

级别	适用情形	必须匹配	可以不同
motion-faithful（默认）	“克隆这个动画”、“让我们的动画感觉像他们的”、“像 X 的同款首屏，但文案用我们的”	触发方式、序列和顺序、交错效果、每一步的时长（±80 ms）、缓动类型、相对于元素尺寸的移动方向和距离、布局比例	文案、颜色、字体、图片、品牌细节
pixel-faithful	“完全一致”、“像素级精准”、“细节要匹配”、“1:1”	以上所有内容，以及字体、尺寸、颜色、间距、圆角、阴影、素材；帧间平均差异 ≤ 2 %	用户未要求更改的任何内容
mixed	“克隆 X 并添加 Y”、“像他们那样，但加入我们的定价层级”	选择上述某个级别来匹配克隆部分	新增内容；需描述并展示，但只验证其不会破坏克隆动画

用户可以将目标限定为某个区块、某个小组件、某个页面，或视频中的一段时间范围（“前 3 秒”、“0:12 到 0:15”）。只克隆指定内容；不要把页面其余部分也纳入范围。

工作流

以下所有内容都放在用户项目中的 .reanimate/<name>/ 内（除非用户希望将证据提交到版本库，否则将其加入 .gitignore）。保留每一轮的产物；它们就是证明。

0. 范围

在进行任何捕获之前，先在 .reanimate/<name>/spec.md 顶部写下三行：

• 目标：要克隆的内容，尽可能准确地按照用户的描述填写（URL + 选择器 / 时间范围 / “gif 中的切换开关”）。
• 目标位置：代码的存放位置和所用技术栈（读取 package.json、现有组件及已使用的动画库；沿用现有方案，不要另引入新方案）。
• 保真度：motion-faithful、pixel-faithful 或 mixed；如果是 mixed，还要列出新增内容。

根据请求和代码库推断能确定的内容。只有当不同理解会导致不同工作时才提问（例如页面上有两个可能的区块，而用户只说“首屏”）。如果参考内容是需要登录的页面，或是无法在此处下载的 YouTube/Loom 链接，请用户提供屏幕录制，同时继续处理其他事项。

1. 设置

下方的 <skill> 是此 SKILL.md 所在的目录。脚本需要 Bun；首次运行时会下载 Playwright 的 Chromium 和一个静态 ffmpeg（约 250 MB）。

bash <skill>/scripts/setup.sh      # installs playwright, ffmpeg, pixelmatch once; prints "ready"

所有脚本都通过 bun <skill>/scripts/<name>.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，或画布的 gl-track.json --channel → 查看帧（首次发生变化的帧、最后发生变化的帧，以及是否有过冲）。同时记录动效所依赖的静态信息：元素尺寸和位置、z 轴顺序、溢出裁剪、变换原点；若要做到像素级还原，也要记录字体、颜色、间距和资源。

规范是参考内容与克隆版本之间的约定。第 5 步中的每项检查都对应其中一行。如果某一行中有“？”，说明你还没有完成对帧的检查。

4. 构建

按照 references/implementation.md 在用户指定的技术栈中实现（缓动表、交错间隔计算、滚动和悬停触发、减少动态效果）。让 DOM 结构尽可能贴近参考内容的角色结构，以便为跟踪选择器找到对应元素。对于混合工作，将新增内容放在清晰分离的组件或代码块中，并在 spec.md 的“Additions”部分说明。

让克隆版本能够以与参考内容相同的方式捕获：提供一个路由或静态页面，在与参考内容相同的视口中渲染组件，并使用相同的触发方式。开发服务器即可（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 中的字体）；若要达到动作级保真，则忽略文本像素，查看时序列。
• 参考是在页面已加载时录制的，而克隆是在冷启动时捕获的：使用 --wait-before，或使用 --trigger none 搭配会重启动画的 --pre-js，确保两者都从静止状态开始。
• 滚动驱动的动作：它取决于滚动位置，而非时间。两边都使用相同的 --scroll-steps 和 --scroll-ms 进行捕获，并按滚动位置（轨迹中的 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。