OpenMontage HyperFrames 动画规则索引（rules-index）实战指南：36 条原子动作配方的体系化速查与组合方法

HyperFrames 是 OpenMontage 项目内一套面向「确定性、可逐帧 seek 渲染」的动画创作知识体系，而本文介绍的 .agents/skills/hyperframes-animation/rules-index.md 正是这套体系里原子动作配方（atomic motion rules）的总索引。它以 8 大分类、36 条短小精悍的 rules/<name>.md 为骨干，将文字、数据、运镜、布局、SVG、环境光、转场等常见动效诉求，收敛为「每场景选取 2-4 条规则 + 单条暂停时间线」的标准组装流程。读完本文，你将掌握该索引的分类逻辑、每条规则的功能与适用场景、规则文件的内部结构，以及如何用 1 条 paused GSAP 时间线把多条规则拼成一段可反复 seek、帧级确定的产品宣传片段落。

一、先理解：rules 在 HyperFrames 技能体系中的位置

OpenMontage 把动画知识组织在仓库根目录的 .agents/skills/hyperframes-animation 技能目录下。按 SKILL.md 的说明，这一层技能包含五类知识：

• rules：原子动作配方，每个文件只解决一种动效（例如「弹入入场」），是组合的最小单元；
• blueprints：多阶段场景模板（例如品牌揭示、logo 组装、对比分屏），由多条 rule 编排成整段镜头，索引见 blueprints-index.md；
• transitions：场景与场景之间的转场目录（CSS 驱动），入口见 transitions/overview.md；
• techniques.md：更宽泛的动效技法（SVG 描边、Canvas 2D、CSS 3D、动力学字型等）；
• adapters：七种运行时适配（GSAP 为默认，另有 Lottie、Three.js、Anime.js、CSS keyframes、WAAPI、TypeGPU）。

rules-index.md 是这个体系里默认工作流的起点：按触发器或标签（tag）挑选 2-4 条规则，用单条暂停的 GSAP 时间线把它们粘合起来——SKILL.md 明确写道，这比从 blueprint 起步更快、产出的代码更少。索引文件的开篇原话即点明了这条核心约定：

Atomic motion recipes. Each lives at rules/<name>.md. Compose 2-4 per scene with a single paused timeline.

这也是 HyperFrames 与普通 CSS/GSAP 教程最大的不同：一切动画必须能在一个暂停的、可 seek 的时间线上正确渲染，且不依赖运行时随机性（见第六节约束体系）。

二、索引的全景：8 大分类 × 36 条配方

我对照索引与 rules 目录统计过：目录下共 36 个 .md 规则文件，索引按功能将它们组织为 8 个分类。下面按分类逐一展开，每条规则给出「一句话功能描述 + 核心机制 + 标签」，供按需速查。

2.1 Text & Typography（文字与排版）

这一分类收录 9 条（counting-dynamic-scale 会在 Data & Stats 再次出现），覆盖了从「黑客解密」到「动感节拍」的绝大多数文字动效诉求：

规则	核心机制	标签
hacker-flip-3d	逐字符 3D 旋转 + 确定性字形替换（解密效果），GSAP back.out 缓动 + 逐字形 onUpdate 驱动「哈希闪烁」	text, 3d, reveal, decode
vertical-spring-ticker	老虎机式垂直滚动，在带遮罩的列内用「步进式」GSAP tween 完成	text, ticker, scroll, vertical
counting-dynamic-scale	计数器随数值增大而放大字号，制造递增的强调感；单个数字代理（numeric proxy）上的单条 GSAP tween	counter, scale, font-size, number, dynamic
discrete-text-sequence	在时间阈值处整体替换文本状态，实现非线性的打字效果（含错别字、停顿、批量追加、退格），GSAP onUpdate 驱动的反向搜索	text, typing, discrete, threshold, non-linear
asr-keyword-glow	依据 ASR 词级时间戳对关键词做「辉光 + 缩放 + 变色」高亮；每词两条 GSAP tween 驱动 CSS 变量 --glow 走过 attack-decay-rest 包络	asr, audio-sync, highlight, glow, keyword, text
3d-text-depth-layers	多层错位文字（N 个 div，各偏移 (i*dx, i*dy) 且 alpha 递减）制造大字号标题的立体挤压错觉	text, 3d, depth, layers, shadow, typography, stacked
context-sensitive-cursor	打字光标在段落边界处切换 background-color，并用方波公式 (tl.time() % cycle) < cycle/2 实现闪烁	cursor, color, context, typewriter, styling, segment
dynamic-content-sequencing	由脚本 {textMain, textAccent, charSpeed, hold} 预计算扁平数组 [{startTime, endTime, ...}]；每个短语窗口 = chars × charSpeed + hold，时长由内容驱动、无需手工调偏移	timeline, sequencing, dynamic, duration, script-driven
kinetic-beat-slam	打击乐式动能字型：短句在共享节拍数组上逐个砸入，每个短语使用不同的入场（scale-slam / side-snap / rise-rotate），可加节拍器刻度等节奏装饰，最后以锁定式 finale 收束	text, kinetic, typography, beat, rhythm, slam, percussive, punchy

索引特别注明 kinetic-beat-slam 是「punchy / rhythmic」风格标语的首选配方。其机理值得展开：先用一个 BEATS = [t0, t1, t2, …] 数组作为节奏主干，让所有短语入场、强调和节拍器都从这一个数组读时间，避免手调偏移彼此漂移；再为每个短语选择不同的入场缓动——源码建议至少使用 3 种不同缓动作为「语气」，常用映射为 power4.out（硬砸、快速稳定，命中首选）、expo.out（最硬脆的侧滑甩入）、back.out(2)（过冲弹入，只用于强调词而非正文）、circ.out（带惯性的重上升）。命中时长控制在 0.35–0.6s，退场不超过 0.25s，保证节拍仍具打击感（见 kinetic-beat-slam.md）。

2.2 Data & Stats（数据与统计）

• counting-dynamic-scale：与文字类条目同一规则，此处强调数据场景属性——onUpdate 中需做到 seek 安全，用 Math.round + tabular-nums 保持数字宽度稳定，并支持多统计值同帧齐奏。
• stat-bars-and-fills：把「数字 + 图形」配成一套的数据可视化原语——增长条形（CSS scaleY 错峰）、进度填充（条形 scaleX 或实测 SVG 圆环）、分数星级擦除（clip-path）。全程只用 transform，seek 安全；且在单点聚焦（single-focus）与分屏（split-frame）之间择一而终，避免视角漂移。

2.3 Camera & Viewport（相机与视口）

这一分类在宣传片里负责「镜头感」，共 5 条：

• coordinate-target-zoom：向非居中元素缩放。外层包装负责 scale、内层负责反向平移。
• camera-cursor-tracking：两阶段虚拟相机。先静态取景，再锁定移动焦点（如打字光标）跟拍；依赖浏览器原生 getBoundingClientRect() / ctx.measureText()，且须在 document.fonts.ready 之后调用以保证字型度量正确。
• multi-phase-camera：多阶段相机系统（拉远 / 对焦 / 推近）+ 持续微漂移（micro-drift），营造电影感。
• viewport-change：真正的「虚拟相机」——通过变换承载全部场景内容的单个 .world 包装层来模拟 zoom / pan / focus-lock。核心数学是单元素复合变换 translate(x,y) scale(S)，反向平移公式为 T = -offset × S——这与 coordinate-target-zoom 的双层结构（那里是 T = -offset，与 S 无关）不同，两条规则刻意对比以免混淆。
• depth-of-field-blur：选择性焦点转移（rack-focus）。用 GSAP tween 驱动 filter: blur()（外加轻微降透明度）加在失焦层上（通过 --dof 变量），而焦点元素保持锐利。提供单次推移、双平面转移、以及「推近时模糊整簇」三种形态。有限时长、确定性、seek 安全。

以 viewport-change.md 为例，其关键代码展示了「单一事实源（cam 对象）+ 统一写变换串」的范式：

window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
const world = document.getElementById("world");

// Camera state — single source of truth.
const cam = { scale: 1, x: 0, y: 0 };

function applyCamera() {
  world.style.transform = `translate(${cam.x}px, ${cam.y}px) scale(${cam.scale})`;
}
applyCamera();

// 注意：CSS 先应用 scale 再应用 translate，
// 世界点 (ox, oy) 落在屏幕 (S×ox + x, S×oy + y)，故补偿量 T = -offset × S。
const counterY = -TARGET_OFFSET_Y * TARGET_SCALE;
tl.to(cam, {
  scale: TARGET_SCALE,
  y: counterY,
  duration: ZOOM_DUR,
  ease: "power3.inOut",
  onUpdate: applyCamera,
}, ZOOM_START);

源码还给出了缩放观感分档表：1.02–1.05 为几乎不可察觉的「专业感」；1.05–1.15 为「Ta-da」式强调；1.15–1.30 聚焦某个区域；1.5–2.5 属戏剧性让元素充满画面；3.0+ 元素覆盖全屏。并配套感知阈值：<5% 不可感知、10–15% 舒适强调、>30% 电影化。另外列出硬件约束——若缩放对象是位图素材，需满足 sourceResolution ≥ rendered × TARGET_SCALE，而文字在任意缩放下依然清晰。

2.4 Layout & Network（布局与网络）

• avatar-cloud-network：头像沿椭圆环排布，以 SVG 连线汇聚到中心点并错峰入场；云中心的坐标必须与中心元素精确一致。典型用途是「社会证明 / 客户墙」。
• 3d-page-scroll：把完整网页渲染成倾斜的 3D 卡片，内部内容滚动以逐段揭示特定区块；可与 asr-keyword-glow 搭配做页面内关键词高亮。
• center-outward-expansion：元素先聚拢在屏幕中心，再向外展开到最终位置。每个元素的目标位置由 CSS 给定一次，GSAP 以共享驱动（shared driver）同步把 x/y 偏移归零。
• split-tilt-cards：并排双卡，各自以相反的 rotationY 倾斜（±baseTilt）并从自己一侧滑入；随后持续悬浮，相位相差 Math.PI，形成对称呼吸。
• orbit-3d-entry：元素从 3D 空间翻入（rotateX + rotateY + translateZ）后进入持续椭圆轨道。关键警示：入场必须在轨道起点原地翻转（阶段 1 前用 gsap.set 预置），而不是在场景中心翻转。
• ai-tracking-box：AI 检测叠加层——黄色 #facc15 L 形四角 + 置信度标签（在 95–99% 间波动），跟随正弦弧线路径上的目标；框位置逐帧从目标位置重算，绝不单独 tween。
• depth-scatter-assemble：N 个元素散开 / 重组到旋转的 3D 深度云中——每个元素从确定性的、由索引推导的 3D 偏移出发（translateZ + rotateX/Y + scatter），归位成干净的平面布局；提供 tumble-swap 与 radial-explode 变体。全程 preserve-3d + perspective、仅用 transform，seek 安全。

2.5 SVG & Icons（SVG 与图标）

• svg-icon-enrichment：让图标内部 SVG 元素动起来（指针旋转、叶片摆动、光点脉冲、虚线流动）。关键警示：旋转必须用 setAttribute('transform', 'rotate(deg cx cy)') 显式给出中心——因为 CSS 的 transform-origin + transform-box: fill-box 会以包围盒局部坐标解释原点，对细线元素会偏离中心。
• svg-path-draw：SVG 描边逐笔自绘——用 stroke-dasharray/stroke-dashoffset。在合成设置期用 getTotalLength() 量取长度，把初始 dashoffset 设为全长，再 GSAP tween 到 0；做圆环进度时把描边旋转 -90deg，使绘制从 12 点钟方向开始。

2.6 Idle & Ambient（待机与环境）

• sine-wave-loop：持续呼吸/待机环境动作。两种形态：GSAP sine.inOut + 有限次 yoyo（独立场景优先），或在 onUpdate 中读取 tl.time()（需要叠加到另一实时值上时优先）——两条路线都避开无限循环，保证 seek 安全。
• ambient-glow-bloom：无触发器参与的柔和径向辉光，在 hero 元素背后绽放并有限呼吸保持，或做单次掠过高光面（sheen）。无点击、无词同步；峰值透明度 ≤ 约 0.45；有限时长、确定性。

2.7 Transition & Motion（转场与运动）

• reactive-displacement：物理碰撞式转场——入场元素的 GSAP tween 驱动退场元素位移。同一时间线位置并发三条 tween，被撞元素的时长取闯入者的 40–50%。
• press-release-spring：有触感的按钮按压：先线性压缩、再弹簧恢复，用同一属性上两条相邻 GSAP tween 完成；变体包括颜色过渡、经 CSS 变量实现的阴影深度、释放爆点、背景辉光。
• physics-press-reaction：物理点击模拟——两条顺序 scale tween（先到 0.9、再回 1.0）近似带过冲的弹簧。可将单一 targets 数组 ["#cta", "#cursor"] 传入同一条 tween，让按钮与光标一起压缩以营造接触手感。
• cursor-click-ripple：动画光标移动到目标 → 点击时光标与目标一起下沉 → 发出带 attack-decay 透明度包络的扩散波纹。元素自 t=0 就以 opacity: 0 存在于 DOM（不做条件渲染）。
• scale-swap-transition：两个 DOM 元素在同一屏幕中心完成协调变形。退出簇收缩淡出，入场元素以 back.out(2) 过冲弹出。
• card-morph-anchor：容器在两次镜头间变形表观尺寸 + 圆角 + 表面质感，再淡出揭示底下真实目标。HyperFrames 用统一 scale 替代被禁止的 width/height tween，并对 borderRadius/background/boxShadow 这类纯绘制属性做 tween。
• spring-pop-entrance：标准入场 pop——元素（或错峰组）以 scale: 0 → 1 弹入，配 back.out 过冲，用 fromTo 保证 seek 到 t=0 时状态正确。支持单 hero、错峰组（总窗口 ≤ 约 0.5s），过冲强度按品牌个性调校。索引特意注明它区别于 press-release-spring（那是点击/按压反馈）。
• motion-blur-streak：为快速入场或镜头穿行伪造定向速度模糊——模糊在速度峰值最大、落地归零。两条路径：SVG feGaussianBlur 沿运动轴做 stdDeviation（代理对象 tween），或确定性回声/残影拖尾收敛进主体。仅限入场 / 中段镜头使用。

2.8 Effect Recipes（从 hyperframes-creative 迁移来的特效配方）

这一节是索引标注「moved from hyperframes-creative」的迁移目录：

• gsap-effects：可直接落地的 GSAP 时间线模式——打字机、音频可视化等可复用编排块。
• css-marker-patterns：纯 CSS + GSAP 实现的荧光笔标注画法——highlight（黄色扫过）、circle（手绘椭圆）、burst（放射线）、scribble（杂乱涂鸦）、sketchout（粗糙矩形轮廓）。

三、与相邻文档的关系（See Also 路由）

索引结尾给出一组路由，用于把「单条动作」扩展成「整段镜头」与「转场」：

• blueprints-index.md——场景形态模板（skill 的 blueprints 层），把多条 rules 编排成完整镜头；索引原文称其为本技能把 rules「compose into full shots」的模板。该文件把 15 个 blueprint（如 kinetic-type-beats、typewriter-reveal、cta-morph-press 等）映射到故事板帧类型（Hook / Problem / Product_Intro / Key_Feature / Benefits / Social_Proof / CTA / Brand_Outro），并给出「角色 → blueprint 菜单」，每行即一个应选择该形状的触发条件。
• techniques.md——更广泛的动效技法（SVG 路径绘制、Canvas 2D、CSS 3D、动能字型、可变字体、合成），少数 rules 会引用它。
• transitions/——场景转场目录（共享技能；故事拥有 transition_in，由 harness 注入），目录含 CSS 驱动的转场分类（blur、cover、dissolve、push、scale、grid、light、mechanical、radial 等，见 catalog.md）。

四、读透一条 rule 的内部结构

索引中的每条引用都直接指到 rules/<name>.md。要真正落地一条规则，你需要理解规则文件本身的结构——它远不止一段代码，而是一份带参数的完整配方。以 spring-pop-entrance.md 为例，其结构具备代表性：

1. frontmatter：name、description、metadata.tags，为 Agent 检索与路由提供元数据；
2. How It Works：机制说明与「何时用 / 何时不用」（区分入场与按压反馈）；
3. HTML / CSS / GSAP Timeline：三块可复制的实现骨架，且注册到全局 window.__timelines[data-composition-id]；
4. Variations：变体（如 calm settle / firm settle / bouncy pop / origin-anchored pop / pop-into-held-slot）；
5. How to Choose Values：每个参数的取值区间、效果与约束。例如 POP_DUR（0.4–0.7s）、STAGGER（0.04–0.08s，且强制 ITEM_COUNT × STAGGER ≤ ~0.5s，超出则退化为慢速列举）、OVERSHOOT（仅限俏皮变体且 ≤ ~2）、Y_RISE（0–32px）、ENTRY_AT（0–0.4s）；
6. Key Principles：设计原理（smooth beats bouncy、fromTo always、easing 承载运动而非手写关键帧、用 grow 承载、错峰窗口封顶、按索引确定性、t≤0.5s 内主体可见、勿在入场内烘焙无限待机）；
7. Critical Constraints：硬性约束清单（见第六节）；
8. Combinations：与哪些相邻规则配合（sine-wave-loop 的细微抖动、center-outward-expansion、press-release-spring），组成「链路化」编排；
9. Pairs with HF skills：注明配套的 hyperframes-core（合成接线）、hyperframes-cli（hyperframes lint）。

这段 GSAP 时间线是「单条规则」的标准骨架，注意它把起点状态写进 from，从而让 seek 到 t=0 时画面即正确：

// 单 hero 入场：默认平滑长尾沉降、无过冲
tl.fromTo(
  "#hero",
  { scale: 0, opacity: 0 },
  { scale: 1, opacity: 1, duration: POP_DUR, ease: "power3.out" },
  ENTRY_AT,
);

// 错峰组入场：确定性、索引派生错峰（无 Math.random），
// 全组总窗口封顶：ITEM_COUNT * STAGGER <= ~0.5s
const items = gsap.utils.toArray(".pop-item");
items.forEach((el, i) => {
  tl.fromTo(
    el,
    { scale: 0, opacity: 0, y: Y_RISE },
    { scale: 1, opacity: 1, y: 0, duration: POP_DUR, ease: "power3.out" },
    GROUP_ENTRY_AT + i * STAGGER,
  );
});
window.__timelines["pop-scene"] = tl;

更细的谱系：ASR 时间戳驱动的关键词高亮

当文字需要跟随语音「被读到」而亮起时，索引指向 asr-keyword-glow。它把每个词的时间戳 { start, end } 换算成攻击-保持-衰减-余晖（attack-sustain-release）包络：start 前为 0；start→peak 线性攻击升到 1；peak→end 保持 1；end→end+release 衰减到 restLevel（典型 0.25）；之后停在微妙余辉。包络值同时驱动 textShadow 模糊半径与 scale，形成「正在被念到」的强调；即使用户没有真实语音数据，也可按同样的硬编码时间轴模拟旁白重音（源码在 asr-keyword-glow.md 的 How It Works 一节有完整描述）。

五、组装方法论：2-4 条规则 = 一个场景

索引开篇给出全体系最核心的组合纪律——Compose 2-4 per scene with a single paused timeline。这在实践中意味着：

1. 按触发器/标签选题：rules-index.md 本身的设计目的就是「pick by trigger / tag」——先用自然语言描述画面需求，在分类中定位到规则并阅读其 tags。
2. 单条时间线编排：所有规则共享同一条 gsap.timeline({ paused: true })，通过第三参（position parameter）错开各自起点，最终注册进 window.__timelines，以 data-composition-id 为键，供 HyperFrames 渲染器统一 seek。
3. 选择场景级模板的时机：若画面属于既有 blueprint（品牌揭示、社会证明、CTA 等），SKILL.md 建议改走 blueprints-index.md，其 15 个模板自带「时间编码 + [slots] + 签名动作」，能让你复用已验证的多阶段编排；而单条规则更适合「快速、代码量更少」的即兴组合。
4. 收尾审计：成片后可用仓库里的 animation-map.mjs 分析组合，用法见 SKILL.md：

node .agents/skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

该脚本会读取注册在 window.__timelines 上的每条 GSAP 时间线、枚举 tween、采样包围盒并输出 animation-map.json，用于排查「死区、错峰一致性、生命周期告警」等编排问题。

六、贯穿全部规则的约束体系：确定性渲染是第一公民

规则索引之所以把动效「配方化」，底层是为了满足 HyperFrames 的确定性渲染契约。SKILL.md 明确声明这些约束「不在本文件重复、而由 hyperframes-core 承载」，并把动画层新增的纪律列出来：

来自 hyperframes-core 的 Non-Negotiable Rules（前置依赖）：

• 单条暂停时间线（single paused timeline）；
• data-duration 决定时长；
• 禁用 Math.random / Date.now / performance.now；
• 禁用 repeat: -1 无限循环；
• 禁止在后续场景 clip 上做 gsap.set；
• 禁止对 display / visibility 做动画；
• 禁止在 async / setTimeout / Promise 内构建时间线。

hyperframes-animation 动画层的补充纪律（SKILL.md「Critical Constraints」一节）：

• 预计算布局常量：绝不在地 tween 时间点用 getBoundingClientRect() 推导位置——渲染器会并行采样帧，tween 期测量会导致失同步；坐标只在合成 setup 期算一次后复用（注意 viewport-change 的 focus-lock 变体按帧读取是「跟随实时焦点」的例外，其世界偏移与相机换算同样在 onUpdate 内统一计算）。
• 空间运动只用 GSAP 变换别名：x、y、scale、rotation；非空间属性允许 opacity / color / backgroundColor / borderRadius，但绝不用 width / height / top / left 做布局变化。
• 入场一律 fromTo：把 { scale: 0, opacity: 0 } 这类起点写进 from 对象，让 seek 到 t=0 就落在此状态；依赖「CSS 先隐藏 + .to()」的入场会在 HF seek 下闪烁。
• 暂停时间线是硬性要求：gsap.timeline({ paused: true })，注册键 = data-composition-id。
• 禁止在动效元素上写 CSS transition（会与 GSAP 竞争、脱离 HF seek 插值导致闪烁）；对高频变换元素给 will-change: transform。

七、多运行时扩展（索引之外的一层能力）

索引所在技能还配有一套 adapters 目录，覆盖七种运行时。对使用 rules 的人而言，这层能力意味着：同一条「规则思路」可以在 Lottie（带预烘焙时间线的 After Effects 导出）、Three.js（3D 场景 + AnimationMixer + hf-seek）、Anime.js、CSS keyframes、WAAPI、TypeGPU/WebGPU 等运行时里实现。SKILL.md 的运行时选择建议是：95% 的动效用 GSAP（默认）；素材自带时间线用 Lottie；3D / 相机 / shader 用 Three.js；轻量 tween 用 Anime.js；重复装饰性动效用 CSS；无 GSAP 依赖的浏览器原生场景用 WAAPI；粒子 / 液态玻璃 / 自定义 shader 等 GPU 渲染场景用 TypeGPU。多个运行时可在同一合成中共存——各自把实例注册到运行时专属全局对象上，HyperFrames 便可一次 seek 全部。入门 API 参考可查 adapters/gsap.md 等适配器文档。

八、核心要点速记

1. 索引定位：rules-index.md 是 36 条原子动作配方的总菜单，按「触发器/标签」路由到 rules 目录 下的独立配方文件。
2. 组合铁律：每场景取 2-4 条规则，编入一条暂停的 GSAP 时间线，用 data-composition-id 注册到 window.__timelines。
3. 分类地图：文字排版（9 条）→ 数据统计（2 条）→ 相机视口（5 条）→ 布局网络（7 条）→ SVG 图标（2 条）→ 待机环境（2 条）→ 转场运动（8 条）→ 迁移特效（2 条），覆盖从逐字解密、节拍字型、虚拟相机到碰撞转场的整套运动语言。
4. 配方文件结构：每个 rule 是「机制 + HTML/CSS/GSAP 骨架 + 变体 + 参数表 + 关键原则 + 硬约束 + 组合建议」的完整文档，能独立落地。
5. 确定性优先：禁用随机源与无限循环、入场用 fromTo、空间运动只用变换别名、布局常量预计算——这些纪律是全部 rules 能安全运行在 HyperFrames seek 渲染引擎之上的前提。
6. 向上组合：需要整段镜头时，从 blueprints-index.md 选蓝图并映射到故事板帧角色；场景切换再接入 transitions 转场目录。