English: README.en.md · 中文: README.md

Oil Motion 是一个 Agent 通用的交互动画 Skill。它负责设计动作、生成连续画面、整理动画资源，并把最终效果接入页面滚动、鼠标、拖动、触摸或设备方向。

使用时只需要说明希望表达什么、提供哪些素材，以及动画应该跟随什么操作。具体的生成、检查、压缩和前端实现由 Agent 完成。

https://github.com/user-attachments/assets/08e26ad6-ca23-4f31-ac53-44c7692ba99d

安装

告诉 Agent：帮我安装「https://github.com/oil-oil/oil-motion」这个 Skill。

适合实现的动画

• 页面向下滚动时，产品逐步展开、拆解或切换状态。
• 鼠标移动时，角色、宠物或产品自然地调整朝向。
• 拖动进度时，动画跟随手势前进、后退或停在指定位置。
• 在手机上使用触摸或设备方向控制画面。
• 点击、悬停或组件状态变化时，播放对应的动作。
• 没有操作时自然播放，用户开始操作后切换为跟随模式。

这些动画可以用于产品介绍、角色互动、操作演示、数据变化和章节转场。Oil Motion 同时处理动作连贯性、画面清晰度、加载体积和移动端表现。

工作原理

AI 生成的视频本身只能从头播放到结尾。为了让它跟随滚动或鼠标变化，Oil Motion 会先生成一段连续动作，再把用户的操作位置对应到动画进度。

例如，一段产品拆解动画共有 100 个画面。页面滚动到 30% 时显示第 30 个画面，滚动到 70% 时显示第 70 个画面。用户反向滚动，动画也会沿着同一组画面自然返回。鼠标、拖动和设备方向使用的是同一种映射方式，只是输入来源不同。

完整过程如下：

参考素材、表达目的和控制方式
  ↓
先确认开始、中间和结束时应该是什么样子
  ↓
使用 AI 视频生成这些画面之间的连续动作
  ↓
逐帧检查，删除停顿、重复和异常画面
  ↓
按照页面中的实际显示大小整理并压缩资源
  ↓
把滚动、鼠标、拖动、触摸或设备方向对应到动画进度

这套流程分成三个部分。

先确认关键画面

关键画面是动作过程中必须保持准确的几个状态，例如产品完整、零件展开和最终拆解。Agent 会先生成并检查这些画面，确认主体身份、结构、Logo、构图和风格没有变化。

如果直接生成整段视频，模型可能在过程中改变产品结构、角色比例或动作终点。先确认关键画面，可以让连续动作有明确的起点、过程和终点。

再生成连续动作

关键画面确认后，AI 视频负责生成它们之间的变化。肢体转动、产品变形、材质变化和前后遮挡都在这个阶段完成，因为这些变化只靠前端移动或缩放图片通常不自然。

位移、缩放、裁切、播放速度、跟随阻尼和最大转动速度由程序控制。这些变化不需要交给视频模型重新生成，程序处理会更稳定，也方便后续调整。

最后转换成可控制的网页资源

生成的视频需要经过整理才能用于交互。Agent 会检查每个画面，裁掉开头和结尾的停顿，删除近似重复画面，找出闪烁或结构变化，并根据页面中的实际显示大小进行压缩。

处理完成后，浏览器不会在用户操作时重新生成视频，而是在已经准备好的连续画面中定位。这样可以让动画及时响应输入，也能避免每次交互出现不同结果。

资源形式

所有动画都从绿幕母版开始，页面背景独立。Agent 会根据画面大小、动画长度、访问方式和设备预算自动选择资源形式，不要求使用者理解或决定技术方案。

使用情况	常用形式	原因
小型、环形、二维或频繁跳转	Alpha WebP 图集	构建时完成抠色，随机访问响应稳定
大尺寸、长时间轴、一维滚动	绿幕全关键帧 MP4	WebGL 实时抠色，压缩率高，避免大型图集占用大量内存

Agent 会先运行预算脚本并直接采用最合适的一种主方案，不会把图集与视频选择交给使用者，也不会重复实现两套。无论选择哪种，最终背景都由页面提供，换背景不用重新生成主体。

压缩会依据页面中的实际显示尺寸进行。展示区域较大时保留更高分辨率；展示区域较小时减少不必要的数据。文件大小和清晰度发生冲突时，优先保证页面中的实际观感。

快速开始

已经有素材和动作方向时，可以直接说明：

使用 $oil-motion，把这两张产品图制作成随页面滚动逐步展开的动画。
桌面端的展示区域较大，需要保持清晰；移动端使用较轻的资源。

只有产品素材，还没有动作方案时，可以让 Agent 先完成设计：

使用 $oil-motion，为这个产品首页设计一个随滚动变化的连续动画。
先提供三个方向，分别说明它们表达什么、如何跟随滚动，以及实现成本。
确认方向以后再生成关键画面和视频。

角色或宠物需要跟随鼠标时，可以说明运动范围和期望感受：

使用 $oil-motion，让这个角色跟随鼠标调整朝向。
动作需要及时响应，同时限制转动速度，快速反向时不能闪烁或抽动。

Agent 会判断什么

在开始制作前，Agent 会确认以下内容：

• 动画要表达的内容，以及它在页面中的作用。
• 主体的身份、结构、比例和不能改变的部分。
• 动画由滚动、鼠标、拖动、触摸还是其他状态控制。
• 动作是一条前后变化的路径，还是需要同时响应水平和垂直方向。
• 页面中的实际显示大小，以及桌面端和移动端是否需要不同资源。
• 动画尚未加载、加载失败或用户关闭动态效果时显示什么。

如果鼠标的水平位置和垂直位置都会改变主体姿态，就需要准备二维方向的画面。只使用一段左右往返的视频，无法准确表达上下和远近变化。

交付内容

根据项目需要，Agent 会交付其中一部分或全部内容：

• 已确认的关键画面和生成提示词。
• 可以继续处理的原始视频。
• 删除停顿、重复和异常画面后的动画资源。
• 适合桌面端与移动端加载的图集或视频。
• 可以直接接入项目的交互代码。
• 展示完整画面、当前帧和交互输入的原理预览页。
• 动画资源、交互范围和加载方式的配置文件。

这些文件会保留生成、处理和验收所需的信息，方便后续修改动作、替换画面或调整交互参数。

质量检查

交付前需要检查：

• 主体身份、产品结构、比例、位置和光线在连续画面中保持一致。
• 没有多余肢体、部件复制、硬切、闪帧和异常停顿。
• 透明素材的边缘干净，内部白色区域和细线没有被误删。
• 快速滚动、快速反向和频繁移动鼠标时，动画不粘滞、不抽动、不越界。
• 页面滚动、缩放或设备旋转后，输入位置与动画方向仍然对应。
• 初次加载时有清晰的首帧，资源加载失败时可以回退到静态画面。
• 最终资源放进真实页面以后仍然清晰，移动端不会因为资源过大而明显卡顿。
• 用户选择减少动态效果时，页面可以显示静态替代内容。

程序可以处理轻微漂移、颜色差异、重复画面和编码问题，但无法修复错误的动作设计。发现主体结构、肢体关系或动作方向错误时，需要重新调整关键画面或生成视频。

第一次生成动画

第一次需要生成动画时，Agent 会引导配置所需的 API Key。密钥只保存在本机，之后会自动读取，不需要重复输入。

技术资料

日常使用不需要手动运行脚本。如果需要修改生成参数、资源处理方式或网页运行逻辑，可以继续查看 SKILL.md 和 references/。

License

MIT