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外部依赖

Kind	Dependency / Endpoint
package	gsap（utils 为内核自带命名空间，无需注册）
network	distribute() 官方文档
network	random() 官方文档
network	splitColor() 官方文档与 HelperFunctions 列表页

4管控建议与判定依据

建议配套管控措施

面向 Agent

可自动加载

面向管理者

登记来源与版本

判定依据（文件路径与关键语句摘要）

SKILL.md: 纯提示词指令与规则文本，无脚本执行与外部影响

审计说明： 。纯指令型 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结论

把散落的工具函数整理成可查清单：范围映射、随机吸附、分布、单位颜色、集合作用域，五大类一次覆盖。

注释即断言：每条 API 都带确定性输入→输出，模型可据此自校验，比散文定义更不易误解。

统一的函数式范式 + 显式例外，减少「配错调用形式」的错。

distribute() 覆盖到高级 stagger 内核，能做出按网格/缓动分布的值，而不必自己写 index 数学。

组件作用域安全有官方原语：selector(scope) / toArray(value, scope)，与 React/Vue 纪律闭环。

适合： 适合任何需要「滚动进度→数值映射」「随机/吸附」「网格分布错峰」「作用域选择器」「颜色通道插值」的 GSAP 项目；在写 ScrollTrigger 回调或 complex stagger 时是最实用的配套 skill。

不适合： 不适合把它当动画教学（它不教 tween/timeline，需要 gsap-core/gsap-timeline 打底）；不适合不用 GSAP 的项目（这些函数都在 gsap.utils 命名空间下）；不适合期望它提供运行时类型校验或性能诊断的场景。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload gsap-utils.tar.gz

sha256: 55bd8167106fd1d2…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit aed9cfd327.