admin
237a09a5b0
一、问题（本轮实测）
`draw-ui` 与 `oil-motion` 目录里**各自带一个内嵌 `.git`** ⇒ 上一次提交把它们记成了 **gitlink（子模块指针）**
⇒ 仓库里只存了一个不属于任何远端的 commit id，**别人克隆下来这两份是空的** ✗（`git status` 显示 ` m draw-ui` / ` m oil-motion` ＝ 子模块内容有改动）。
二、处置（可回退）
· 把两处的 `.git` **挪走**（⛔ 不是删除）⇒ `归档/内嵌git-20261008/{draw-ui,oil-motion}.git`；
· `git rm --cached` 掉那两个 gitlink，再 `git add` 两个目录 ⇒ **按正常文件入库**（内容才真的进仓库）。
三、副作用（如实记）
挪走 `.git` 后，这两个技能**不能再原地 `git pull` 取上游更新**（要更新得重新拉一份覆盖）；
如需恢复其本地仓库，把 `归档/内嵌git-20261008/` 里的 `.git` 挪回原处即可。
188 lines
11 KiB
Markdown
188 lines
11 KiB
Markdown
<p align="center">
|
||
<img src="./assets/readme/hero.svg" width="100%" alt="Oil Motion 把 AI 生成的连续动作接入网页交互">
|
||
</p>
|
||
|
||
**中文** · [English](./README.en.md)
|
||
|
||
Oil Motion 是一个 Agent 通用的交互动画 Skill。它负责设计动作、生成连续画面、整理动画资源，并把最终效果接入页面滚动、鼠标、拖动、触摸或设备方向。
|
||
|
||
使用时只需要说明希望表达什么、提供哪些素材，以及动画应该跟随什么操作。具体的生成、检查、压缩和前端实现由 Agent 完成。
|
||
|
||
## 演示
|
||
|
||
https://github.com/user-attachments/assets/08e26ad6-ca23-4f31-ac53-44c7692ba99d
|
||
|
||
## 安装
|
||
|
||
把仓库地址交给 Agent：
|
||
|
||
```text
|
||
帮我安装 https://github.com/oil-oil/oil-motion 这个 Skill。
|
||
```
|
||
|
||
也可以用命令安装，完成后让 Agent 重新加载 Skill：
|
||
|
||
```bash
|
||
npx skills add oil-oil/oil-motion
|
||
```
|
||
|
||
## 适用边界
|
||
|
||
适合主体本身需要变化的交互动画：角色转头、产品拆解、材质变化、镜头穿越，或者把已有的绿幕视频、雪碧图整理成可以随操作控制的网页资源。
|
||
|
||
只靠 CSS、JS、SVG、Lottie 或实时 3D 就能完成的界面过渡、按钮反馈和布局动效，直接交给普通前端实现即可，不需要这套素材流程。独立成片剪辑和单张配图也不在范围内。
|
||
|
||
## 适合实现的动画
|
||
|
||
- **页面向下滚动时**：产品逐步展开成爆炸图、镜头进入内部结构，或者在几种状态之间切换。
|
||
- **滚动穿过多个场景时**：用多段首尾相接的视频做成一镜到底，比如从城市全景一路推进到芯片内部，或者借前景遮挡、形状相同的物体过渡到下一个场景。
|
||
- **鼠标移动时**：角色的脸始终朝着屏幕，视线跟着光标转；或者硬件产品跟着拖动做 360° 展台旋转。
|
||
- **拖动进度时**：动画跟随手势前进、后退，或者停在指定位置。
|
||
- **在手机上**：用触摸或设备倾斜控制主体的朝向和层次。
|
||
- **点击、悬停或状态变化时**：播放对应的动作转场，反向操作时从当前画面撤回。
|
||
- **没有操作时**：保持自然的微动或循环，用户一开始操作就切换为跟随输入。
|
||
|
||
这些动画可以用于产品介绍、角色互动、操作演示、数据变化和章节转场。Oil Motion 同时处理动作连贯性、画面清晰度、加载体积和移动端表现。
|
||
|
||
## 工作原理
|
||
|
||
AI 生成的视频需要先被整理成稳定时间轴，再根据交互目标选择控制方式：输入值可以持续对应动画进度，也可以只触发一段正常播放的转场，或让动画按时间自主播放。滚动、鼠标和状态切换只是输入来源，不直接决定播放方式。
|
||
|
||
完整过程如下：
|
||
|
||
```text
|
||
参考素材、表达目的和控制方式
|
||
↓
|
||
先确认开始、中间和结束时应该是什么样子
|
||
↓
|
||
使用 AI 视频生成这些画面之间的连续动作
|
||
↓
|
||
逐帧检查，删除停顿、重复和异常画面
|
||
↓
|
||
按照页面中的实际显示大小整理并压缩资源
|
||
↓
|
||
把滚动、鼠标、拖动、触摸或设备方向对应到动画进度
|
||
```
|
||
|
||
这套流程分成三个部分。
|
||
|
||
### 先确认关键画面
|
||
|
||
关键画面是动作过程中必须保持准确的几个状态，例如产品完整、零件展开和最终拆解。Agent 会先生成并检查这些画面，确认主体身份、结构、Logo、构图和风格没有变化。
|
||
|
||
如果直接生成整段视频，模型可能在过程中改变产品结构、角色比例或动作终点。先确认关键画面，可以让连续动作有明确的起点、过程和终点。
|
||
|
||
### 再生成连续动作
|
||
|
||
关键画面确认后，AI 视频负责生成它们之间的变化。肢体转动、产品变形、材质变化和前后遮挡都在这个阶段完成，因为这些变化只靠前端移动或缩放图片通常不自然。
|
||
|
||
位移、缩放、裁切、播放速度、跟随阻尼和最大转动速度由程序控制。这些变化不需要交给视频模型重新生成，程序处理会更稳定，也方便后续调整。
|
||
|
||
### 最后转换成可控制的网页资源
|
||
|
||
生成的视频需要经过整理才能用于交互。Agent 会检查每个画面，裁掉开头和结尾的停顿，删除近似重复画面，找出闪烁或结构变化，并根据页面中的实际显示大小进行压缩。
|
||
|
||
处理完成后，浏览器不会在用户操作时重新生成视频，而是在已经准备好的连续画面中定位或播放。这样可以让动画及时响应输入，也能避免每次交互出现不同结果。
|
||
|
||
## 资源形式
|
||
|
||
Agent 会先锁定 Concept Contract：主体、风格、动作、背景归属、交互输入、时间控制和连续性要求逐项确认，不擅自扩写。背景归属决定是否把场景烧入视频；参数空间、访问方式和设备预算决定资源形式；时间控制单独决定逐帧 scrub、分段播放或自主播放。
|
||
|
||
| 使用情况 | 常用形式 | 原因 |
|
||
| --- | --- | --- |
|
||
| 场景叙事、镜头运动、环境光与地面接触重要 | 烘焙场景全关键帧 MP4 | 背景与主体同视频生成，连续性最好，没有抠色风险 |
|
||
| 透明复用：小型、环形、二维或频繁跳转 | Alpha WebP 图集 | 构建时完成抠色，随机访问响应稳定 |
|
||
| 透明复用：大尺寸、长时间轴、一维滚动 | 绿幕全关键帧 MP4 | WebGL 实时抠色，压缩率高，避免大型图集占用大量内存 |
|
||
|
||
Agent 会先运行预算脚本并直接采用最合适的一种主方案，不会把形式选择交给使用者，也不会重复实现两套。量产之前还会先完成首屏 Pilot：一对关键帧、一段短视频、挂载到真实页面验收通过后生成带工件哈希的批准文件；后续片段缺少批准文件或首尾帧 SHA-256 不一致时，生成脚本会在联网前阻断。
|
||
|
||
压缩会依据页面中的实际显示尺寸进行。展示区域较大时保留更高分辨率；展示区域较小时减少不必要的数据。文件大小和清晰度发生冲突时，优先保证页面中的实际观感。
|
||
|
||
## 快速开始
|
||
|
||
已经有素材和动作方向时，可以直接说明：
|
||
|
||
```text
|
||
使用 oil-motion，把这两张产品图制作成随页面滚动逐步展开的动画。
|
||
桌面端的展示区域较大，需要保持清晰；移动端使用较轻的资源。
|
||
```
|
||
|
||
只有产品素材，还没有动作方案时，可以让 Agent 先完成设计：
|
||
|
||
```text
|
||
使用 oil-motion，为这个产品首页设计一个随滚动变化的连续动画。
|
||
先提供三个方向，分别说明它们表达什么、如何跟随滚动，以及实现成本。
|
||
确认方向以后再生成关键画面和视频。
|
||
```
|
||
|
||
角色或宠物需要跟随鼠标时，可以说明运动范围和期望感受：
|
||
|
||
```text
|
||
使用 oil-motion，让这个角色跟随鼠标调整朝向。
|
||
动作需要及时响应，同时限制转动速度，快速反向时不能闪烁或抽动。
|
||
```
|
||
|
||
## Agent 会判断什么
|
||
|
||
在开始制作前，Agent 会确认以下内容：
|
||
|
||
- 动画要表达的内容，以及它在页面中的作用。
|
||
- 主体的身份、结构、比例和不能改变的部分。
|
||
- 动画由滚动、鼠标、拖动、触摸还是其他状态控制。
|
||
- 动作是一条前后变化的路径，还是需要同时响应水平和垂直方向。
|
||
- 页面中的实际显示大小，以及桌面端和移动端是否需要不同资源。
|
||
- 动画尚未加载、加载失败或用户关闭动态效果时显示什么。
|
||
|
||
如果鼠标的水平位置和垂直位置都会改变主体姿态，就需要准备二维方向的画面。只使用一段左右往返的视频，无法准确表达上下和远近变化。
|
||
|
||
## 交付内容
|
||
|
||
根据项目需要，Agent 会交付其中一部分或全部内容：
|
||
|
||
- 已确认的关键画面和生成提示词。
|
||
- 可以继续处理的原始视频。
|
||
- 删除停顿、重复和异常画面后的动画资源。
|
||
- 适合桌面端与移动端加载的图集或视频。
|
||
- 可以直接接入项目的交互代码。
|
||
- 展示完整画面、当前帧和交互输入的原理预览页。
|
||
- 动画资源、交互范围和加载方式的配置文件。
|
||
|
||
这些文件会保留生成、处理和验收所需的信息，方便后续修改动作、替换画面或调整交互参数。
|
||
|
||
## 质量检查
|
||
|
||
交付前需要检查：
|
||
|
||
- 主体身份、产品结构、比例、位置和光线在连续画面中保持一致。
|
||
- 没有多余肢体、部件复制、硬切、闪帧和异常停顿。
|
||
- 透明素材的边缘干净，内部白色区域和细线没有被误删。
|
||
- 快速滚动、快速反向和频繁移动鼠标时，动画不粘滞、不抽动、不越界。
|
||
- 页面滚动、缩放或设备旋转后，输入位置与动画方向仍然对应。
|
||
- 初次加载时有清晰的首帧，资源加载失败时可以回退到静态画面。
|
||
- 最终资源放进真实页面以后仍然清晰，移动端不会因为资源过大而明显卡顿。
|
||
- 用户选择减少动态效果时，页面可以显示静态替代内容。
|
||
|
||
程序可以处理轻微漂移、颜色差异、重复画面和编码问题，但无法修复错误的动作设计。发现主体结构、肢体关系或动作方向错误时，需要重新调整关键画面或生成视频。
|
||
|
||
## 第一次生成动画
|
||
|
||
本地处理已有视频和序列帧只需要 Python 3.10+ 与 FFmpeg。需要 AI 生成关键帧或视频时，默认通过 ZenMux 调用图片和视频模型，图片与视频共用一个 API Key。
|
||
|
||
第一次生成前，Agent 会打开一个本机配置页，由你亲自填写 Key。Key 存进系统凭据库（macOS 钥匙串、Windows 凭据管理器或 Linux Secret Service），之后自动复用，不需要发到聊天里。配置页需要 Node.js 22.18+；系统凭据服务不可用时会直接停止，不会改存成明文。目前在 macOS 上完成了实机验证。
|
||
|
||
生成时，提示词、参考图和首尾关键帧会发送给 ZenMux 及其背后的模型服务。每次生成都会计费，所以 Agent 会先做一段 Pilot，确认效果后再批量生成。
|
||
|
||
## 技术资料
|
||
|
||
日常使用不需要手动运行脚本。如果需要修改生成参数、资源处理方式或网页运行逻辑，可以继续查看 [`SKILL.md`](./SKILL.md) 和 [`references/`](./references/)；凭据的安装、状态检查和安全边界见[配置说明](references/api-key-setup.md)。
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/oil-oil/oil-ui"><img src="https://raw.githubusercontent.com/oil-oil/oil-ui/main/assets/readme/hero.webp" width="600" alt="oil-ui：把 AI 的 UI 设计能力推到极限"></a>
|
||
<br>
|
||
<strong><a href="https://github.com/oil-oil/oil-ui">想让 AI 做出更好的 UI 设计？试试 oil-ui →</a></strong><br>先探索几种风格，再并排挑选，按实际画面打磨。
|
||
</p>
|
||
|
||
## License
|
||
|
||
[MIT](./LICENSE)
|