用途
motion-clone 用于把用户指定的参考动效在现有项目中重建出来，并证明重建结果与参考一致。可复刻的目标可以是某个区块、组件、页面，也可以是视频中的一段（如“前 3 秒”“0:12 到 0:15”）。参考来源包括在线网站 URL、屏幕录制、mp4/mov/webm、gif、Lottie 文件以及原型导出。
保真等级
开始前会依据用户表述确定保真等级，并据此决定验证内容：
- motion-faithful（默认）：要求触发方式、顺序、错峰、每一步时间（±80 ms）、缓动族、相对元素尺寸的移动方向与距离、布局比例一致；文案、颜色、字体、图片、品牌细节可不同。
- pixel-faithful：在以上基础上还要求字体、尺寸、颜色、间距、圆角、阴影、素材一致，平均帧差异不超过 2%。
- mixed：克隆部分按上述某一等级验证，新增部分只描述和展示，并验证其不破坏被克隆的动效。
工作流程
所有产物放在项目内的 .motion-clone/<name>/ 目录（默认建议加入 .gitignore，除非用户希望提交证据），每轮产物都会保留作为证明。
-
范围：在采集前写下 spec.md，包含目标（URL + 选择器 / 时间范围等）、目标代码位置与技术栈（读取 package.json 与现有组件，尽量沿用已有动画库）、保真等级及 mixed 的附加项。能从请求和仓库推断的就推断，只有两种理解会导致不同工作时才询问。遇到登录墙页面或无法下载的 YouTube/Loom 链接，会请用户提供屏幕录制，同时继续其他部分。
-
环境准备：运行
bash <skill>/scripts/setup.sh一次性安装 playwright、ffmpeg、pixelmatch，首次运行会下载 Playwright 的 Chromium 与静态 ffmpeg（约 250 MB），完成后打印 “ready”。脚本需 Bun 运行，全部以bun <skill>/scripts/<name>.ts --help调用。脚本是确定性的，并要求参考与克隆使用相同的视口、选择器裁剪、触发方式、时长与帧率，否则对比测的是环境而非复刻质量。 -
采集参考：网站使用
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抽帧，先用--probe查看再确定裁剪。Lottie/Rive/原型导出则直接读取文件作为规格，不从像素反推。之后用sheet.ts filmstrip生成带标签的帧条并逐张查看。 -
编写动效规格：按 references/analysis.md 模板填写 spec.md，每个元素的每个属性一行：触发、开始时间、时长、延迟或错峰、从 → 到、缓动、备注。数值优先取自 inspect.json 的动画与关键帧，其次用
easing.ts分析 track.json，最后才读帧推断。同时记录动效依赖的静态事实（尺寸位置、z 序、溢出裁剪、变换原点；pixel-faithful 还需字体颜色间距素材）。规格是参考与克隆之间的契约，每行都会成为验证项。 -
实现：在用户技术栈中按 references/implementation.md 实现（缓动表、错峰计算、滚动与悬停触发、减少动态效果）。DOM 结构尽量贴近参考的角色结构，以便被跟踪选择器有对应物。mixed 的新增部分放在独立组件或区块中，并在 spec.md 的 “Additions” 下说明。需为克隆提供与参考相同的采集入口（路由或静态页），可用开发服务器或独立 HTML 文件。
-
验证与迭代：用与参考完全相同的命令采集克隆（只改 --url 与 --out clone-N），再运行
compare.ts生成对比、sheet.ts compare生成对比帧条、easing.ts --compare-track比较缓动。按 references/verify.md 解读报告、判定各保真等级的通过标准并据此修复。每轮只改证据指向的最小改动，重新采集再对比，通常需要 2 到 5 轮。若 5 轮后仍有行不通，停止并附上数字与原因报告，不擅自降低阈值或删除行。 -
报告：最终消息需独立完整：保真等级、克隆了什么、新增了什么；代码位置与如何触发；最后一轮对比的简表（时间误差、平均差异、关键元素缓动匹配、通过与否）；最终对比帧条路径；残留偏差及数字与原因。
常见陷阱
参考与克隆的视口或裁剪不一致会浪费轮次，应先修采集再改代码；只看首帧和末帧会错过中间帧里的缓动；字体回退会改变每一帧像素，pixel-faithful 需先加载相同字体；在已加载页面上录制的参考与冷启动的克隆应通过 --wait-before 或 --pre-js 统一起点；滚动驱动动效应按滚动位置而非时间对比；GSAP、Framer Motion 弹簧等 JS 库不受 --playback-rate 影响，需用 track.json 与 easing.ts 依据过冲与稳定时间调参；他人录屏中的光标、浏览器边框与压缩噪声应裁掉并适当提高 --pixel-threshold（如 0.15），而不是追着噪声调。
限制
资料未提供浏览器版本支持范围、对其他动画库的完整兼容清单，以及除 Bun 之外的运行方式，暂未提供。