gsap-router

GSAP 路由器

根据动画需求路由至 4 个专用技能。

路由协议

1. 分类 — 根据用户请求识别动画类型
2. 匹配 — 应用下方的信号匹配规则
3. 组合 — 生产级动画通常需要组合 2-3 个技能
4. 加载 — 实现前读取匹配技能的 SKILL.md 文件

快速路由

第 1 层：核心（从这里开始）

需求	技能	信号
基础动画、缓动	gsap-fundamentals	tween, animate, ease, from, to, duration, delay
复杂序列	gsap-sequencing	timeline, sequence, orchestrate, labels, callbacks
滚动动画	gsap-scrolltrigger	scroll, pin, scrub, parallax, reveal, sticky
React 集成	gsap-react	React, useGSAP, ref, hook, cleanup, context

信号匹配

主要信号

gsap-fundamentals：

• “animate”、“tween”、“transition”
• “ease”、“easing”、“timing”
• “from”、“to”、“fromTo”
• “duration”、“delay”、“repeat”
• “stagger”、“properties”

gsap-sequencing：

• “timeline”、“sequence”、“orchestrate”
• “labels”、“callbacks”、“nested”
• “position parameter”、“overlap”
• “complex animation”、“choreography”
• “play”、“pause”、“reverse”、“seek”

gsap-scrolltrigger：

• “scroll”、“ScrollTrigger”
• “pin”、“sticky”、“fixed”
• “scrub”、“parallax”
• “reveal on scroll”、“snap”
• “progress indicator”

gsap-react：

• “React”、“component”
• “useGSAP”、“useRef”、“hook”
• “cleanup”、“context”
• “event handler”、“state”

置信度评分

• 高（3 个以上信号） — 直接路由至匹配的技能
• 中（1-2 个信号） — 以 fundamentals 为基础进行路由
• 低（0 个信号） — 从 gsap-fundamentals 开始

常见组合

基础动画（1 个技能）

gsap-fundamentals → Tweens, easing, basic properties

React 组件动画（2 个技能）

gsap-fundamentals → Animation principles, easing
gsap-react → Hook patterns, cleanup, refs

基于滚动的体验（3 个技能）

gsap-scrolltrigger → Scroll triggers, pinning
gsap-sequencing → Timeline for pinned sections
gsap-fundamentals → Individual animations

完整生产级方案（3-4 个技能）

gsap-fundamentals → Core animations
gsap-sequencing → Complex orchestration
gsap-react → Framework integration
gsap-scrolltrigger → Scroll interactions (if needed)

决策表

框架	动画类型	复杂度	路由至
Vanilla JS	简单	低	fundamentals
Vanilla JS	序列动画	中	fundamentals + sequencing
Vanilla JS	基于滚动	中	fundamentals + scrolltrigger
React	简单	低	fundamentals + react
React	复杂	高	全部四个技能
React	滚动	中	react + scrolltrigger

动画类别

运动类型 → 技能映射

动画类型	主要技能	辅助技能
淡入/淡出	gsap-fundamentals	-
滑动/移动	gsap-fundamentals	-
缩放/旋转	gsap-fundamentals	-
交错动画	gsap-fundamentals	-
页面过渡	gsap-sequencing	fundamentals
编排式显现	gsap-sequencing	fundamentals
滚动显现	gsap-scrolltrigger	fundamentals
视差	gsap-scrolltrigger	-
固定区段	gsap-scrolltrigger	sequencing
React 动画	gsap-react	fundamentals
React + 滚动	gsap-react	scrolltrigger

与其他领域集成

与 R3F（r3f-*）集成

r3f-fundamentals → 3D scene setup
gsap-fundamentals → Object property animation
gsap-sequencing → Camera movements, scene transitions

GSAP 通过 onUpdate 为 Three.js 对象属性添加动画。

与后期处理（postfx-*）集成

postfx-composer → Effect setup
gsap-fundamentals → Animate effect parameters
gsap-sequencing → Transition between effect states

GSAP 驱动效果强度、颜色等。

与音频（audio-*）集成

audio-playback → Music timing
gsap-sequencing → Sync animations to audio cues
gsap-fundamentals → Audio-reactive property changes

时间线回调与音频事件同步。

与粒子（particles-*）集成

particles-systems → Particle emitters
gsap-fundamentals → Animate emitter properties
gsap-sequencing → Particle burst sequences

工作流模式

页面加载动画

1. gsap-fundamentals → Understand tweens, easing
2. gsap-sequencing → Build entrance timeline
3. gsap-react → Integrate with React (if applicable)

滚动体验

1. gsap-scrolltrigger → Set up triggers, pins
2. gsap-sequencing → Build scrubbed timelines
3. gsap-fundamentals → Individual animation properties

交互式 UI

1. gsap-fundamentals → Hover, click animations
2. gsap-react → Event handlers, cleanup
3. gsap-sequencing → Complex interaction sequences

时间坍缩动画栈

适用于新年倒计时项目：

gsap-fundamentals → Digit animations, pulse effects, easing
gsap-sequencing → Countdown sequence, final moment orchestration
gsap-react → Component integration, cleanup

关键动画：

• 时间变化时数字翻转
• 脉冲/辉光强度随时间变化
• 最后倒计时的戏剧性序列
• 到零时呈现庆祝效果

快速参考

任务 → 技能

任务	主要	次要
“为此元素添加动画”	fundamentals	-
“创建入场动画”	fundamentals	react
“构建页面过渡”	sequencing	fundamentals
“滚动时添加动画”	scrolltrigger	fundamentals
“React 组件动画”	react	fundamentals
“固定滚动区域”	scrolltrigger	sequencing
“复杂动画序列”	sequencing	fundamentals
“列表交错动画”	fundamentals	react

缓动速查

感觉	缓动
灵敏的 UI	power2.out
平滑入场	power3.out
活泼弹跳	back.out(1.7)
弹簧感	elastic.out
球体下落	bounce.out
线性／机械感	none

回退行为

• 未指定框架 → 假设使用原生 JS，从 gsap-fundamentals 开始
• 提到 React → 将 gsap-react 加入组合
• 提到滚动 → 将 gsap-scrolltrigger 加入组合
• 提到“复杂”或“序列” → 将 gsap-sequencing 加入组合
• 需求不明确 → 从 gsap-fundamentals 开始

性能优先级

性能至关重要时：

1. gsap-fundamentals — 使用变换，避免布局属性
2. gsap-react — 正确清理可防止内存泄漏
3. gsap-scrolltrigger — 明智地使用 scrub，批量更新
4. gsap-sequencing — 复用时间线，不要重新创建