oso95/scroll-world · 上手攻略

仓库：oso95/scroll-world
链接：https://github.com/oso95/scroll-world
分类：AI生成 · 3D落地页 · Agent Skill
作者：Tom
更新：2026-07-18
来源：README.md、SKILL.md（GitHub 原始文件）

是什么

scroll-world 是一个 AI Agent Skill（技能），运行在 Claude Code、Codex 或任何兼容 SKILL.md 的 AI 编程助手内。它能为一任意品牌或行业构建「滚动穿越3D世界」的沉浸式落地页——访客滚动页面时，摄影机从场景外部俯冲进入内部，再无缝飞入下一场景，全称无剪辑，像 Apple's scroll-through 产品页一样的视觉体验。

视觉内容完全由 AI 生成（Higgsfield 的 GPT Image 2 + Seedance/Kling 视频模型），最后用一个纯 Vanilla JS 的 scroll scrub engine（滚动寻址引擎）驱动，视频帧位置由滚动位置决定，摄影机真实运动，滚动只驱动时间轴。

一句话理解： 你提供行业/品牌信息，AI 批量生成连贯的等距卡通场景 + 镜头飞行动画，输出一个接入任意前端框架的滚动落地页。

解决什么问题

传统方式做这种滚动穿越落地页，需要：

3D 建模师 / 动画师数周工作
高额预算（万元起步）
复杂的前端对接

scroll-world 把这个流程变成了：告诉 AI 你的品牌 → AI 自动生成所有场景图和镜头动画 → 得到可嵌入任意页面的 HTML/JS 组件。从指令到可交付物，全流程 AI 完成，无需设计师操刀。

快速安装

方式一：Claude Code 插件（推荐）

/plugin marketplace add oso95/scroll-world
/plugin install scroll-world@scroll-world

安装后在对话中直接说"做一个滚动穿越落地页"或输入 /scroll-world 即可触发。

方式二：Codex / 其他 Vercel Skills CLI 兼容 Agent

npx skills add oso95/scroll-world            # 交互式选择目标 agent
npx skills add oso95/scroll-world -a codex   # 直接指定 Codex

方式三：手动复制（通用）

git clone https://github.com/oso95/scroll-world
# 放入 Claude Code 的 skills 目录
cp -R scroll-world/skills/scroll-world ~/.claude/skills/
# 或放入 Codex 的 skills 目录
cp -R scroll-world/skills/scroll-world ~/.codex/skills/

前置依赖（使用前必须满足）

# Higgsfield CLI（核心，负责生成图像和视频）
npm install -g @higgsfield/higgsfield-cli
higgsfield auth login          # 交互式 OAuth 登录，需要浏览器
higgsfield workspace list     # 确认认证成功
higgsfield workspace set <id> # 如有多个 workspace，指定目标

# ffmpeg（视频帧提取和编码）
# macOS
brew install ffmpeg
# Linux
sudo apt install ffmpeg

# Python 3 + Pillow（可选，用于移动端竖版场景的背景扣图）
pip install Pillow

# Codex CLI（可选，如存在则可用 ChatGPT 订阅的 gpt-image-2 生成静态图，省 Higgsfield 额度）
# 见 https://github.com/openai/codex

核心用法

触发方式

安装后在 Agent 对话中直接描述需求：

帮我做一个奶茶品牌的滚动穿越落地页

Agent 会自动进入访谈流程，依次询问：主题行业、品牌的调色板/名称/语气、美术风格、场景顺序、是否需要移动端版本、预算档位。

完整手动执行流程（pipeline.md 摘要）

# 1. 生成 N 张场景静帧图（Higgsfield GPT Image 2）
higgsfield generate image \
  --prompt "<style preamble> <scene description>" \
  --model gpt-image-2 \
  --output ./stills/scene-01.webp

# 2. 从静帧提取帧序列（ffmpeg）
ffmpeg -i ./stills/scene-01.webp ./frames/scene-01/%04d.png

# 3. 生成每场景的"飞入"镜头视频（Higgsfield image-to-video）
higgsfield generate video \
  --start-image ./stills/scene-01.webp \
  --model seedance \
  --duration 5 \
  --output ./clips/dive-01.mp4

# 4. 生成场景间的"连接"镜头（关键！必须用相邻场景的边界帧作为起止帧）
higgsfield generate video \
  --start-image ./stills/scene-01.webp \
  --end-image   ./stills/scene-02.webp \
  --model seedance \
  --duration 3 \
  --output ./clips/connector-01-02.mp4

# 5. 编码为网页友好的 MP4（720p，blob 寻址）
ffmpeg -i ./clips/connector-01-02.mp4 \
  -vf "scale=1280:720" -c:v libx264 -crf 23 \
  ./output/connector-01-02-720p.mp4

⚠️ 核心规则：接片接缝必须帧级一致（frame-identical seam）。 连接两个场景的 connector clip，其起始帧必须与前一场景最后一帧完全相同，终点帧必须与后一场景第一帧完全相同。这是整个技术链最关键也最常出错的地方。

滚动引擎接入（scrub-engine.js）

<!-- 最简独立 HTML 接入示例 -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { margin: 0; background: #000; }
    #scroll-container { height: 3000px; position: relative; }
    video { position: fixed; top: 0; left: 0; width: 100%; }
  </style>
</head>
<body>
  <div id="scroll-container"></div>
  <script src="scrub-engine.js"></script>
  <script>
    // 初始化滚动引擎，传入配置
    const engine = new ScrollScrubEngine({
      container: document.getElementById('scroll-container'),
      clips: [
        { src: 'clips/dive-01-720p.mp4',    scrollStart: 0,    scrollEnd: 500 },
        { src: 'clips/connector-01-02.mp4', scrollStart: 500,  scrollEnd: 1000 },
        { src: 'clips/dive-02-720p.mp4',    scrollStart: 1000, scrollEnd: 1500 },
        // ...
      ],
      stills: ['stills/scene-01.webp', 'stills/scene-02.webp', ...],
      stillThresholds: [0, 500, 1000, ...], // 滚动到达此值时切换到对应静帧
    });
    engine.init();
  </script>
</body>
</html>

典型适用场景

场景	说明
品牌官网 Hero 区	替代静态 Banner，一屏讲完品牌故事
产品发布页	滚动过程中展示产品从外观到内部结构的飞行镜头
电商大促页	多商品串联的故事线式展示，提升沉浸感和停留时长
个人作品集 / 简历页	用自定义职业路径做成的"世界穿越"效果
旅游 / 地产样板间展示	虚拟参观体验，无需实地拍摄
多页广告创意	替代传统 Banner，视觉冲击力更强

坑与注意

Higgsfield 额度消耗大：N 个场景 ≈ N 张图片 + (2N-1) 段视频。生成耗时 3-8 分钟/次，全程后台运行，不要阻塞等待。正式跑之前先用 higgsfield workspace list 确认余额。
接片接缝（seam）是成败关键：README 和 SKILL.md 都单独强调这点。连接两个场景的视频，如果起止帧与相邻场景不匹配，页面会看到明显的「跳帧」。生成前务必读 Step 5 / The seamless chain。
macOS Bash 3.2 兼容：苹果系统默认 Bash 3.2，不支持 declare -A 关联数组，不要在脚本里使用。
视频模型参数差异：Kling 模型不支持 --resolution 参数，且并非所有模型都支持 start/end-image 条件生成。使用前用 higgsfield model get <job_type> 确认目标模型 schema。
本地文件路径传给 Higgsfield：Higgsfield 不接受 job UUID 引用，必须传本地文件路径（--image ./path/to/file.webp）。
移动端版需要明确询问：SKILL.md 要求每次都必须询问用户是否需要移动端版，不要默认生成。移动端原生 9:16 竖版镜头，不是横版裁剪。
生成内容不在本仓库：README 明确说明，生成的 .mp4/.webp 资产是按项目单独生成的，不随本仓库发布。

与同类对比

工具/方案	定位	优势	局限
Apple 原创制作	专业影视团队	最高品质，无技术约束	成本极高，不可复制
Three.js / R3F 手动开发	前端工程师	完全可控，灵活定制	需要 3D 专业知识，开发周期长
Lottie / GSAP 动画	动效师 + 前端	轻量，设计师友好	依赖预制动画素材，无法实时 AI 生成
Midjourney + 手动剪辑	设计师	图质量高	无自动接片，全手动，效率低
scroll-world	AI Agent Skill	全流程 AI 生成，接片自动化，框架无关	需要 Higgsfield 额度付费，依赖 AI 视频模型成熟度

最核心差异：scroll-world 把 AI 视频生成 + 接片规则 + 滚动引擎封装为可复用的 Agent Skill，无需分别找工具、跑管线、写前端，一个人+一个AI Agent即可端到端交付。

一句话推荐结论

如果你需要为品牌或产品做一个「Apple 风格」的滚动穿越 3D 落地页，又没有专业影视团队，scroll-world 是目前最低门槛的 AI 一键交付方案——前提是你能接受 Higgsfield 的按量付费成本。

本文档基于 oso95/scroll-world 公开信息编写，生成于 2026-07-18。视频生成依赖 Higgsfield 平台，其定价和模型可用性请以官方最新公告为准。