1实现原理 · 为什么它能做到
把 gsap.utils 定位成「纯函数工具箱、无需注册」，并解释它在动画流程里的插入点（function-based values、ScrollTrigger/Observer 回调）。
skills/gsap-utils/SKILL.md
**gsap.utils** provides pure helpers; no need to register.
注：为什么能实现宣称功能：utils 是纯计算 API，不产生副作用也不联网；skill 的价值在于给出每个函数的输入→输出语义，让模型在「滚动位置映射成数值」「随机化」「吸附网格」等场景不再手写算术。
统一「省略值 → 返回可复用函数」的调用范式，并单独点出唯一例外 random() 传 true。
skills/gsap-utils/SKILL.md
If you omit that argument, the util returns a **function** that accepts the value later.
注：这是 utils 设计上的一致性：clamp/mapRange/normalize/interpolate/snap/wrap/wrapYoyo 都支持函数式；random 因为签名不同（多一个 snapIncrement）改用末参 true 返回函数。写清例外，避免模型套错范式。
每个函数给「具体的输入 → 输出注释」当行为规格（实质是可核对的微型测试），模型能靠示例对齐语义。
skills/gsap-utils/SKILL.md
gsap.utils.clamp(0, 100, 150); // 100
注：例如 normalize(0,100,50) // 0.5、snap(10,23) // 20、interpolate("#ff0000","#0000ff",0.5) // mid color；这类确定性注释让模型可自校验取值方向，比读散文定义更可靠。
distribute() 被拆成表格化的配置（base/amount/each/from/grid/axis/ease），它是 GSAP 内部 stagger 的分布内核。
skills/gsap-utils/SKILL.md
**Returns a function** that assigns a value to each target based on its position in the array (or in a grid).
注：用法两种：直接作为 tween 属性值（GSAP 按 (index, target, targets) 逐目标调用），或手工调用取某索引的值；配合 grid+axis 可做二维波纹。
selector(scope) 作为组件内「选择器沙箱」的官方原语，与 gsap-react / gsap-frameworks 的 scoping 纪律同源。
skills/gsap-utils/SKILL.md
Returns a scoped selector function that finds elements only within the given element (or ref).
注：接受 DOM 元素或 ref（内部处理 .current），因此 React/Vue 里可直接把 containerRef 交给它，避免全局选择器误伤页面其它节点。
单位与颜色解析单独成节：getUnit/unitize/splitColor 处理「数值之外」的输入，并明确 mapRange/normalize 不做单位换算。
skills/gsap-utils/SKILL.md
❌ Assume **mapRange** / **normalize** handle units; they work on numbers.
注：splitColor 支持 rgb/rgba/hsl/hsla/hex/具名色，第二参 true 返回 HSL——用于按通道做颜色插值或生成渐变。
2核心能力
01范围映射与归一：clamp / mapRange / normalize / interpolate（数值、颜色、对象）
02随机与吸附：random（含 snapIncrement 与数组取样）/ snap（数值或数组）/ shuffle
03tween 内的字符串形式随机：x: "random(-100, 100, 5)"，GSAP 逐目标求值
04distribute()：按索引/网格/缓动分布数值（高级 stagger 的内核，可手工调用）
05单位与颜色：getUnit / unitize / splitColor（含 HSL 输出）
06集合与作用域：selector(scope) / toArray(value, scope) 把混合输入变成真数组
07函数组合与循环取模：pipe(...fns)（管道）、wrap / wrapYoyo（循环/往复）
3外部依赖
| 类型 | 依赖 |
|---|---|
| package | gsap（utils 为内核自带命名空间，无需注册） |
| network | distribute() 官方文档 |
| network | random() 官方文档 |
| network | splitColor() 官方文档 与 HelperFunctions 列表页 |
4风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- 纯工具层，不会替你决定用哪个函数 — 它给函数语义不给场景决策；选错（如用 normalize 却又传带单位字符串）仍需开发者理解，文中仅以 ❌ 提示一句。
- 函数式返回值易被误用 — 省略值会得到闭包；若把它当数值直接参与运算，动画会静默不生效，难以排查。
- 颜色/单位输出的形态差异 — splitColor 默认返回 RGB 数组、传 true 返回 HSL，误用会导致颜色插值方向错误，需按示例核对。
- 版本边界 — distribute 等 API 属 GSAP 3 系列；结论仅对 pin aed9cfd（2026-04-21）有效，跨大版本需重新核对。
风险提醒：绿色，放心使用。纯指令型 skill：目录内仅 SKILL.md（12,093 B），无脚本、无网络外发、无凭证读取、无文件写入；外链为 4 条 gsap.com 官方文档。它通篇是数学/集合/单位转换的函数说明，是这个仓库里最不可能产生越权行为的一份。注意点仅为：函数式返回的闭包若被误用（如把返回值当数值比较）会导致动画静默不动——能力使用边界，非安全面。
5第二遍独立确认
- [ok] 目录资产面：仅 SKILL.md — skills/gsap-utils/ 下唯一文件 SKILL.md（12,093 B）；无 scripts/、references/、数据文件。
- [ok] external_deps 逐条核实 — gsap 包依赖证据取自 README 安装段；三条 gsap.com 链接（distribute、random()、HelperFunctions）+ splitColor 链接在内文中逐字命中。
- [ok] 函数签名与示例输出是否与官方语义一致 — 抽查 clamp(0,100,150)=100、mapRange(0,100,0,500,50)=250、normalize(0,100,50)=0.5、snap(10,23)=20、wrap(0,360,370)=10、wrapYoyo(0,100,150)=50，均与 GSAP 官方 API 语义吻合，无编造。
- [ok] 「random 是唯一例外」的说法是否可复核 — 原文明确「This is the only util that uses `true` for the function form instead of omitting the value.」并给出 random(-200,500,10,true) 示例，叙述自洽。
- [ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；无混淆代码（该文件只有短代码块）。
- [ok] 与 gsap-react / gsap-frameworks 的 scoping 叙述是否一致 — 本文件「Use **gsap.utils.selector(scope)** in components so selectors are scoped to a container or ref.」与 gsap-react 的「always pass scope」、gsap-frameworks 的「Do not use global selectors」同向。
- [ok] 元数据与 pin — frontmatter license: MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326、pushed_at 2026-07-29T17:36:08Z。
- [ok] 无夸大检查 — description 只声明「Official GSAP skill for gsap.utils …」，文件内容即函数清单与示例，无越界承诺（不宣称性能优化或自动重构）。
6结论
适合：适合任何需要「滚动进度→数值映射」「随机/吸附」「网格分布错峰」「作用域选择器」「颜色通道插值」的 GSAP 项目；在写 ScrollTrigger 回调或 complex stagger 时是最实用的配套 skill。
不适合：不适合把它当动画教学（它不教 tween/timeline，需要 gsap-core/gsap-timeline 打底）；不适合不用 GSAP 的项目（这些函数都在 gsap.utils 命名空间下）；不适合期望它提供运行时类型校验或性能诊断的场景。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 gsap-utils.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent55bd8167106fd1d2…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库greensock / greensock/gsap-skills
原始 GitHubgreensock/gsap-skills ↗
Stars15326
最近推送2026-07-29
本 skill commit
aed9cfd327许可MIT（仓库根 LICENSE，Copyright (c) 2026 GreenSock；GitHub API spdx_id=MIT；每个 SKILL.md frontmatter 亦写 license: MIT）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。