OpenMontage 确定性文本动画实战：`animate-text` 技能适配器与 24 种命名文本效果全解

本篇技术指南围绕 OpenMontage 中 HyperFrames 动画体系的核心适配器 .agents/skills/hyperframes-animation/adapters/animate-text.md 展开：它回答了"当故事板需要 typewriter（精确到 240ms / 46ms stagger / steps(1, end) easing）这类可复现的命名文本动画时，规格从哪里来、如何加载、如何引用、以及离线时如何回退"。读完本文，你将掌握 24 个命名文本效果的完整词汇表、在 STORYBOARD.md 中按 ID 引用效果的标准写法、与 HyperFrames 确定性渲染契约的配合方式，以及不依赖上游技能、直接用 GSAP 内联实现文本动画的实战方案。

为什么文本动画需要一份"外部技能"而不是内置目录

HyperFrames 的动画体系遵循一条铁律：同一时间值必须渲染出同一帧像素（参见 .agents/skills/hyperframes-core/references/determinism-rules.md 的动画运行时契约）。文本动画如果靠"即兴发挥"，每个 sub-agent 写出的 typewriter 都可能时长、节奏、缓动各不相同，同一部视频的多个 beat 之间会明显"跳戏"。因此，对于确定性文本动画规格——例如 typewriter 以精确的 240ms / 46ms stagger / steps(1, end) easing 运行——HyperFrames 明确委托给由 Pixel Point 维护的独立 animate-text 技能（项目根目录下的路由表 .agents/skills/hyperframes-animation/SKILL.md 第 46 行即指向本适配器：Named text-animation effects (24 IDs via external animate-text skill) → adapters/animate-text.md）。

它提供一份包含 24 个命名文本效果的目录，每个效果都附带：

• 可移植的运动契约（portable contracts）：与具体动画库无关的规格描述；
• 逐库实现配方（per-library implementation recipes）：GSAP、Anime.js、WAAPI 三个运行时的落地代码。

之所以不把这份目录内置到 OpenMontage 仓库，原文给出了清晰的工程与法律理由：Pixel Point 的 animate-text 是规格的"来源真相"（source of truth），将其文件 vendoring 进本仓库会违反上游的许可约束（截至写作时上游未声明明确 license）。单独以技能形式加载，既保持法律层面的干净，又让你获得完全相同的目录能力——这也是 OpenMontage 大量采用外部技能插件的通用模式（参考 .agents/skills/hyperframes-animation/SKILL.md 中 Lottie、Three.js、Anime.js、WAAPI、TypeGPU 等七个运行时适配器的并存设计）。

如何加载：两条路径，一条命令

在需要确定性的文本动画时，把上游技能与 hyperframes-animation 一起加载即可。文档给出了两种加载方式。

方式一：项目根目录安装（CLI）

# 在项目根目录，将上游技能安装到 .agents/skills/ 下
npx skills add pixel-point/animate-text

方式二：技能感知的 Agent 运行时按名调用

/animate-text

安装完成后，规格文件位于以下结构：

.agents/skills/animate-text/assets/effects/<id>.json   # 各库实现配方（per-library implementation recipe）
.agents/skills/animate-text/assets/specs/<id>.json     # 可移植运动契约（portable motion contract）

负责实现 beat 的 sub-agent 读取这些文件后，拿到的是精确的 GSAP 时间线、缓动字符串、DOM 拆分规则和 stagger 算法——不需要任何创造性发明。这正是"确定性"的来源：同一个效果 ID，无论由哪个 sub-agent、在哪次构建中实现，产出的运动参数都一致。

24 个命名效果词汇表：四大家族一次看清

为了方便在尚未加载上游技能时编写故事板，适配器文档完整列出了 24 个效果的 ID。注意：这里仅提供词汇（vocabulary），不是实现来源——具体规格以 .agents/skills/animate-text/assets/specs/<id>.json 为准。效果按拆分的文本粒度分为四类：

逐字符（Per-character，7 个）

ID	直观含义
soft-blur-in	模糊中柔和淡入
per-character-rise	逐字符上升
typewriter	打字机逐字揭示
bottom-up-letters	字母自下而上
top-down-letters	字母自上而下
stagger-from-center	从中心向两侧错开
stagger-from-edges	从两侧向中心错开

逐词（Per-word，8 个）

ID	直观含义
per-word-crossfade	逐词交叉淡化
spring-scale-in	弹簧缩放进入
shared-axis-y	共享 Y 轴滑动
blur-out-up	模糊后向上移出
kinetic-center-build	动能居中构建
short-slide-right	短距右滑
short-slide-down	短距下滑
depth-parallax-words	深度视差词

逐行（Per-line，2 个）

ID	直观含义
mask-reveal-up	遮罩向上揭示
line-by-line-slide	逐行滑动

整元素（Whole element，7 个）

ID	直观含义
micro-scale-fade	微缩放淡入
shimmer-sweep	闪光扫过
fade-through	贯穿式淡化
shared-axis-z	共享 Z 轴纵深
scale-down-fade	缩小淡出
focus-blur-resolve	失焦—聚焦解析
shared-axis-x	共享 X 轴滑动

选择建议：当你在几个相似效果间犹豫时——例如 typewriter（逐字阶梯式揭示、无插值）vs per-character-rise（逐字符上升）vs bottom-up-letters（字母自下而上）——请一次性加载 /animate-text 通读全部 24 个的目录页，对比其描述、时长、缓动曲线和逐库配方后再决定。

在 STORYBOARD.md 中按 ID 命名效果

每个 beat 中的每个文本元素都可以在故事板里通过效果 ID 显式声明动画。故事板采用 ## Frame N — Title 的帧结构，元数据以 - key: value 形式书写，任何未知键都会被保留在帧的 extra 字段中（参见 .agents/skills/hyperframes-core/references/storyboard-format.md），因此 Text Animations 这类自定义小节可以安全承载效果命名。文档给出的标准写法如下：

**Text Animations:**

- Main headline: `kinetic-center-build`
- Eyebrow label: `soft-blur-in`
- Body copy 3 lines: `mask-reveal-up`

实现该 beat 的 sub-agent 会先加载 /animate-text（若尚未加载），然后从上游技能的 assets/specs/ 与 assets/effects/ 中读取每个被命名效果对应的规格与实现配方。这种"故事板写意图、sub-agent 查规格"的分工，与 HyperFrames 核心的"预计算布局常量、单一暂停时间轴、确定性渲染"契约天然契合——效果 ID 就是契约本身。

何时不需要上游技能：内联实现的三种典型场景

如果某个 beat 的文本动画简单到可以用散文描述（例如"headline 逐词淡入上浮，80ms stagger"），完全可以就地用本仓库已有的 GSAP 知识实现，无需引入上游目录。文档明确指出上游目录最有价值的场景只有三类：

1. 跨多个 beat 复用某个具名效果——让整部视频像同一个设计系统，而不是一次性的零散动画；
2. 在几个相似效果之间做选择——需要一次性看到全部 24 个的对比；
3. 需要布局感知的效果（kinetic-center-build、short-slide-right、short-slide-down）——这类效果仅靠参数不足以描述，上游携带了自定义布局算法。

对于其余情况，仓库自身已提供两条直接可用的内联路径：

• 逐词动能排版（Per-Word Kinetic Typography）：见 .agents/skills/hyperframes-animation/techniques.md 第 4 条。单词逐个出现，同步到 transcript.json 时间戳；滑动距离逐词衰减（80→60→50→25→12px），模拟镜头落定的质感：

// 单词起始时间（相对 beat 起点，秒）与水平滑动衰减（px）
var timings = [0.0, 0.23, 0.28, 0.63, 0.78];
var slides = [80, 60, 50, 25, 12];

document.querySelectorAll(".word").forEach(function (word, i) {
  tl.from(word, { x: slides[i], y: 14, opacity: 0, duration: 0.35, ease: "power2.out" }, timings[i]);
});

• 逐字符打字（Character-by-Character Typing）：见同文件第 7 条。终端风格逐字符揭示，用 ease: "steps(1)" 驱动光标闪烁——离散开关、无插值，与 typewriter 的 steps(1, end) 语义同源：

var CMD = "npx hyperframes init";
var typed = document.getElementById("typed-text");

// 光标闪烁：steps(1) 产生离散开/关
tl.to(".cursor", { opacity: 0, duration: 0.12, yoyo: true, repeat: 20, ease: "steps(1)" }, 0);

// 逐字符更新文本内容
for (var i = 0; i < CMD.length; i++) {
  (function (idx) {
    tl.call(function () { typed.textContent = CMD.substring(0, idx + 1); }, null, (idx / CMD.length) * 0.9);
  })(i);
}

此外，.agents/skills/hyperframes-animation/adapters/gsap-easing-and-stagger.md 提供了内联实现所需的完整缓动词汇表：power1–power4、back(N)、elastic、bounce、expo、sine、circ、steps(N) 均含 .in/.out/.inOut 变体；其中 steps(N)（离散 N 步跳跃、无插值）正是打字效果、光标闪烁的标准选择。stagger 建议使用对象形式（each/from/amount/grid/axis）而非手工延迟，这样在目标数量或顺序变化时依然保持正确。

离线回退：没有上游技能时怎么办

当上游技能不可用时——离线构建、网络受限、或 agent 运行时不支持技能加载——sub-agent 的既定回退策略是：仅凭效果描述实现动画，用 GSAP 知识加上效果 ID 所表达的意图。例如：

• typewriter = 逐字符阶梯式揭示，无插值（对应 steps(1) 语义）；
• soft-blur-in = 模糊淡入；
• mask-reveal-up = 遮罩向上揭示。

这种回退之所以可行，是因为效果 ID 本身就是意图契约——即便拿不到精确的 240ms / 46ms stagger 数字，实现者仍能忠实还原效果的"动词"，而不是偏离到完全不同的运动。它保证了故事板的可移植性：同一份 STORYBOARD.md，在有上游技能时精确实现，在无上游技能时近似实现，但绝不错位。

落地时的确定性约束：与 HyperFrames 契约对齐

无论选择上游规格还是内联实现，文本动画都必须服从 HyperFrames 的确定性渲染约束（.agents/skills/hyperframes-core/references/determinism-rules.md）：

• 单一暂停时间轴：gsap.timeline({ paused: true })，同步创建并注册到 window.__timelines，键与 data-composition-id 一致；
• 禁止墙钟依赖：视觉状态不得依赖 Date.now()、performance.now()、未播种的 Math.random()；循环次数须有限计算（如 repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)），禁用 repeat: -1；
• 禁止在 async/setTimeout/Promise/事件处理器中构建时间轴——渲染器可能在它们完成前采样；
• 动画属性受 allowlist 约束：只动画 opacity、x、y、scale、rotation、color、backgroundColor、borderRadius 等，绝不动画 display/visibility；
• 预计算布局常量：不要在 tween 时用 getBoundingClientRect() 推导位置——渲染器并行采样会导致失同步。动态文本排版可借助 window.__hyperframes.pretext 与 fitTextFontSize 做纯算术布局（约 0.0002 ms/次）。

对于 typewriter 这类需要拆 DOM 的效果，还要注意 .agents/skills/hyperframes-animation/techniques.md 第 7 条中的做法：逐字符更新应通过 tl.call() 挂在可 seek 的时间轴上（而非裸 gsap.to() 或事件驱动），确保捕获引擎非线形 seek 时也能复现。.agents/skills/hyperframes-creative/references/motion-principles.md 则补充了创作侧纪律：总 stagger 序列控制在 500ms 以内、先动的元素最有重量、进入用 .out 缓动、每场至少变化 3 种缓动——这些让文本动画在"确定性正确"之上还"有节奏"。

与内置蓝图的协同：typewriter-reveal 与 kinetic-type-beats

HyperFrames 的蓝图层（.agents/skills/hyperframes-animation/blueprints-index.md）中有两个重度依赖文本动画的模板，可作为命名效果的真实落地参照：

• typewriter-reveal（Hook / Brand_Outro，3.6–7s）：真实光标"像人一样"打字并编辑一行文字，随后折叠成一点并弹出品牌元素，或让品牌标识常驻而副行继续打入最终 CTA。其规则映射显示，字符级打字揭示对应 discrete-text-sequence 规则与 gsap-effects 中的 typewriter 配方，折叠动画对应 scale-swap-transition，品牌弹出对应 spring-pop-entrance——完整的蓝图规格见 .agents/skills/hyperframes-animation/blueprints/typewriter-reveal.md；
• kinetic-type-beats（6 个角色均可用的"工作马"）：扁平、居中、粗体的镜头，运动本身就是"文字在变化"——固定行原位换词、或整屏语句逐拍构建并落在 spring-pop 收尾上。这正是 kinetic-center-build 等布局感知效果大显身手的场景。

当你在这些蓝图中为每个文本元素按 ID 命名效果时，kinetic-center-build（主标题）、soft-blur-in（眉题）、mask-reveal-up（多行正文）组合起来，就构成了一套跨镜头一致的文本运动设计语言。

总结

animate-text 适配器回答了一个核心工程问题：如何在多 Agent 协作的确定性渲染流水线里，让"命名文本效果"既精确可复现、又不背负外部许可负担。它的设计可提炼为四点：目录外置（上游为 source of truth，本仓库只维护词汇与加载方式）、契约与实现分离（specs/ 管"动什么"，effects/ 管"怎么动"）、按 ID 声明（故事板只写意图）、分级回退（有上游用精确规格，无上游按意图内联实现）。配合本文梳理的 24 个效果词汇、npx skills add pixel-point/animate-text 加载命令、STORYBOARD.md 引用语法与 HyperFrames 确定性约束，你即可在自己的 HyperFrames 合成中稳定产出高质量、可复现的文本运动。