1实现原理 · 为什么它能做到
产出镜头：圆角倒角的立方体作为「卡片」从右侧整体飞入，巡航时每个立方体有错峰旋转，减速到 hero 停留，再向左退出——一条行进波式的 3D 轮播。
registry/blocks/cuboid-carousel/SKILL.md
Rounded, bevelled cuboids carrying card content fly in from the right as one rigid group, cruise with a per-cuboid rotation stagger, decelerate to a hero hold, then exit left.
注：这里在做什么：把「卡片轮播」放到 3D 里做，但保持整体刚性编舞（不是各自乱飞），所以读起来仍像一次排版动作。
布局安全由几何推导：间距来自立方体尺寸与「最大可达 X 半展」，因此立方体永不重叠——这是结构性保证，而不是靠手调数值。
registry/blocks/cuboid-carousel/SKILL.md
Spacing is derived from the cuboid dimensions and the largest reachable X half-extent, so cuboids can never overlap.
注：这里在做什么：回答「用户把宽高调很大会不会撞在一起」——不会，间距随尺寸重算。
参数面是本批最宽的一块：40 个变量沿用原 DialKit schema，覆盖几何、材质、灯光、阴影、背景、相机，以及每一段的时长与缓动。
registry/blocks/cuboid-carousel/SKILL.md
Forty variables carry the original DialKit schema: geometry, materials, lights, shadows, backdrop, camera and every segment duration and easing.
注：这里在做什么：把「美术调参面板」整体搬进块里——非 3D 使用者也能靠滑杆改观感，不必碰灯光公式。
依赖基本本地化：importmap 指向随包的 three.module.min.js、addons/ 与 593 KB 的运动数据模块 cuboid-motion.js；产物期外链只剩 Google Fonts 的 Inter。
registry/blocks/cuboid-carousel/cuboid-carousel.html
"three": "./assets/three.module.min.js", … "cuboid-carousel/motion": "./assets/cuboid-motion.js" … href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap"
注：这里在做什么：three 与运动数据随块分发（合计 ~1.1 MB JS），渲染不依赖外网取库；字体是唯一产物期外链。
卡片内容由 canvas 2D 现画成面贴图，来源可以是内置列表或 cardsJson 变量——因此换内容不一定要准备图片资产。
registry/blocks/cuboid-carousel/cuboid-carousel.html
function faceTexture(item) { … const c = document.createElement("canvas");
注：这里在做什么：卡片文字由浏览器字体渲染，所以内容更新只需改变量。
时间线带命名段与暂停语义：gsap.timeline({ paused: true }) 加 arrival / alternate-camera 标签，seek 由 hf-seek 事件驱动重同步与重绘。
registry/blocks/cuboid-carousel/cuboid-carousel.html
/* ---- timeline: paused, seek-safe, no rAF ---- */ … const tl = gsap.timeline({ paused: true }); … tl.addLabel("arrival", 0);
注：这里在做什么：命名标签让「相机切换段」可被外部引用（Studio 时间轴/编排），同时保持 seek-safe。
首帧质量与稳定性做了两道预热：ready 之前先 renderAt(0) 并「跨时间线画一遍并 flush GPU」，另外用一个一次性 setInterval 轮询 __timelines 注册完成。
registry/blocks/cuboid-carousel/cuboid-carousel.html
Draw across the timeline and flush the GPU before ready, so shader links … var tick = setInterval(function () { … if (!ids.length) return; … clearInterval(tick);
注：这里在做什么：避免 shader 在播放中途首次链接导致卡顿——这是「逐帧渲染」流水线特有的预热需求。
2核心能力
013D 立方体卡片轮播镜头（1920×1080、6.6667s；飞入→巡航→hero 停留→左出）
0240 个变量的完整调参面（几何 / 材质 / 灯 / 阴影 / 背景 / 相机 / 每段时长与缓动，沿用 DialKit 值域）
03卡片内容可换成 JSON（cardsJson），也可以走内置列表
04阴影可调：贴图尺寸 512–4096、软度 0–50（在 2048 贴图下的半径）
05相机两段式：初始机位（fov、settle frame、手持强度）过渡到 cameraTarget 机位
06离线可渲染：three 核心 + addons（RoomEnvironment、BufferGeometryUtils）+ 运动数据模块全部随块分发
07脱离 Studio 也能出片：直接渲染并覆盖卡片内容与 hero 序号
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | HyperFrames 官方 CLI（add / render） |
| package | three.js 与 addons（随块本地副本；PMREM/RoomEnvironment 造环境光） |
| package | GSAP 3.14.2（随块本地副本）+ 本地运动数据模块 |
| network | Google Fonts：Inter（产物期浏览器拉取，本块唯一外链） |
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- 依赖体积大 — 随块分发约 1.1 MB+ 的 three 与运动数据（three.module/three.core/cuboid-motion），项目体积与首帧编译成本随之上升。
- 单实例内存较重 — SKILL.md 自述约 350 MB/实例、run one at a time；多块并列需评估。
- 字体为唯一外链 — Inter 由浏览器在渲染期拉取；离线/受限网络需本地化，否则回退系统无衬线字体，排版观感会变。
- 参数多、组合空间大 — 40 个变量（含相机目标机位与每段缓动）组合后观感差异很大，投产前需要在真实时长上过一遍接触表。
风险提醒：蓝色，知晓即可。判级对象＝本 block 目录（SKILL.md + composition HTML + 随包 three/gsap/运动数据模块 + addons + 许可文本）：无凭证/env 读取、无 shell 脚本、无本地写盘代码、无数据外发。唯一网络面是产物期浏览器取 Google Fonts 的 Inter（范式附录A第2条：产物期引用不判级，仅列出端点）。安装/渲染走官方 CLI 生态。据此取 blue。
5第二遍独立确认
- [ok] 变量数与声明一致性（frontmatter 自称 40 variables） — 脚本实测：SKILL.md 变量表 40 行、html data-composition-variables 解析出 40 项、frontmatter 写 40 —— 一致。
- [ok] 「no rAF」注释 vs 代码里的 setInterval — 该 setInterval 是一次性的就绪轮询（等 __timelines 出现后立即 clearInterval），不是渲染循环；时间线注释也确写 seek-safe, no rAF。两者不冲突。
- [ok] 外链清点 — html 全文 http(s):// grep 仅命中三处 Google Fonts（preconnect ×2 + css2?family=Inter）；three/gsap/运动数据均为 ./assets/ 本地路径。
- [ok] registry-item 文件清单 vs 盘上文件 — 声明 10 个文件全部存在于盘上（含两个 addons 与两份许可文本），无远端 url 兜底。
- [ok] 几何安全声称 — SKILL.md 明写间距由尺寸与最大 X 半展推导；html 中 cuboidWidth/Height/Depth/cornerRadius/bevel/smoothness 均按 DialKit 区间读取（变量段注释写 every one clamped to the DialKit range）。
- [ok] 时长一致性 — registry-item duration 6.67、html data-duration 6.666666666666667、SKILL.md 标题行 6.666666666666667s —— 前两者为同一精度的两种写法。
6结论
适合：需要「一组卡片/条目按 3D 轨迹入场并逐张成为主角」的短片段（6.7s），且希望不写代码就能调整几何质感、灯光与相机节奏的产品/功能发布片。
不适合：需要每张卡片独立编舞或大量卡片（>12）的场合（count 上限 12、heroCard 1–12）；对项目体积敏感、不想带 1 MB+ 3D 运行时的流水线。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-28
方式 A · 人下载镜像包下载 cuboid-carousel.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentfc159be9ba802332…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库heygen-com / heygen-com/hyperframes
原始 GitHubheygen-com/hyperframes ↗
Stars44283
最近推送2026-09-06
本 skill commit
d2f0bc7f34许可Apache-2.0（仓库根 LICENSE = Apache License Version 2.0；块内随带第三方许可文本：three.js MIT、GSAP 标准许可、Geist/Archivo/Cormorant Garamond OFL 等）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。