用途
web3d-animation 用于实时 3D 网页场景中的动画制作与播放，主要面向 three.js 和 React Three Fiber 项目。它关注动画资产与运行时之间的“接缝”：制作动画片段的人与播放动画片段的人往往不是同一人，导致片段名为 Armature|mixamo.com|Layer0，而代码请求 run，角色滑步，死亡姿势弹回 T-pose。该技能定义这条接缝两侧的契约——资产侧与运行时侧，以及它们共享的规范（references/clip-canon.md）。
主要能力
- 第一步：检查并报告。读取 package.json 中的 three 版本（API 事实基于 three@0.186.1 验证）；列出每个运动对象及其当前驱动方式（片段、代码、着色器、物理或尚未驱动）；对每个 .glb/.gltf 运行 npx @gltf-transform/cli inspect <file>，检查动画（名称、时长、通道）、蒙皮（关节数）、变形目标以及文件是否压缩；比较片段名称与规范；确定资产来源（Asset Foundry 工具或 asset-foundry 技能，否则由 web3d-assets 决定）。输出一张表：对象 · 当前技术 · 所需技术 · 差距，以及恰好一个下一步动作。
- 第二步：在接触资产前选择技术。根据运动类型选择：刚体对象用帧循环中的变换或关键帧片段；环境表面运动（植被、布料摆动、水、脉冲）用 TSL 材质上的时间与 positionLocal.add(offset)；面部、混合形状、校正形状用 morph targets；有作者动画的角色用 SkinnedMesh + AnimationMixer；大量相同姿势的副本用蒙皮实例化，一个 mixer 更新驱动全部；大量独立时序的副本用逐实例 mixer.setTime + 一次 compute 蒙皮；数千个无交互固定运动用 TSL 中的顶点动画纹理（VAT）；对力反应（坠落、击中、布娃娃）用固定步长物理；粒子、群集、模拟用 compute（web3d-runtime）。BatchedMesh 不能蒙皮，只能批处理道具，不能批处理角色。
- 第三步：资产侧。每个角色检查：绑定（T-pose 或 A-pose、米、+Y 向上、面向 +Z；自动绑定服务绑定人形；非人形最多获得运动，应改用程序化/morph/VAT）；规范（每个片段从 references/clip-canon.md 获得规范名称、循环模式和位移规则，提供者名称在导入时映射一次）；来源（通过 Asset Foundry 订购，否则参考 references/asset-animation.md 中的提供者表和许可规则；运动数据许可与网格许可不同，两者都要记录）；重定向（为另一骨架制作的片段，参考 references/asset-animation.md → Retargeting，或运行时用 SkeletonUtils.retargetClip）；导出（GLB、30 fps、原地、每顶点 ≤4 影响，three.js 只读取一组 JOINTS_0/WEIGHTS_0 并静默丢弃其余，骨骼名称稳定）；预算（关节、影响、片段数量和文件大小对照目标配置；r186 解除 uniform-buffer 骨骼上限，预算变为性能而非硬限制）；门禁（npx @gltf-transform/cli validate 通过；每个片段在查看器中播放；循环无接缝；脚在片段预期速度下保持踩地；没有片段以绑定姿势结束。未运行的门禁标记为 NOT_RUN）。
- 第四步：运行时侧。一个时钟：new Timer()（r186 核心；Clock 已弃用），timer.connect(document) 使隐藏标签页不返回巨大 delta，timer.update() 每帧一次，mixer 使用钳制 dt（例如 Math.min(dt, 0.1)）；物理使用同一时钟驱动的固定步长累加器。帧顺序：mixer.update(dt) → compute 通道 → 渲染。每个角色根一个 mixer；副本来自 SkeletonUtils.clone（普通 .clone() 会使骨架绑定到原始骨骼）；重定向片段在 SkinnedMesh 自身为根的 mixer 上播放。过渡：运动变化用 crossFadeTo(next, duration, warp)；syncWith 在 walk↔run 切换时保持周期相位；一次性动作用 LoopOnce，监听 mixer 上的 'finished' 而非 action；death 设置 clampWhenFinished = true。层：呼吸、瞄准和上半身手势是叠加片段（AnimationUtils.makeClipAdditive）叠加在基础运动上，加权，而非第二个状态。根运动与滑步：原地片段 + 代码驱动移动；根据实际速度与片段作者速度驱动 timeScale，否则脚会滑；_rm 片段的髋部平移由代码提取——three.js 没有根运动。屏幕外少做：视锥外或远处的角色跳过或稀释 mixer.update；标签页隐藏情况已由 Timer 处理。减少运动：在 prefers-reduced-motion 下，停止装饰性运动（环境循环、相机漂移、空闲花哨动作），保留有意义的运动（击中、状态变化）。销毁：stopAllAction、uncacheRoot，然后 dispose 几何体和材质。
使用方式
该技能以检查开始，不询问可以读取的内容。它提供参考文档：references/clip-canon.md（命名、循环或加载任何片段时；映射提供者名称——与 web3d-assets 的共享契约）、references/runtime-patterns.md（编写循环、mixer、过渡、层、重定向、人群、morph 实例化、VAT、R3F）、references/asset-animation.md（获取绑定或片段：提供者、绑定检查、运动许可、重定向管线、导出和 QA）。运行时（渲染器、TSL、compute、性能）属于 web3d-runtime；文件管线和预算属于 web3d-assets。该技能只负责运动。
适用场景
适用于需要在实时 3D 网页场景中让物体或角色运动的项目，尤其是使用 three.js 或 React Three Fiber 的场景。包括角色绑定与片段、混合与状态过渡、环境表面运动、面部表情、大量副本、物理反应、粒子与模拟等。
限制
- 所有 API 事实基于 three@0.186.1 验证；旧版本需先检查 references/runtime-patterns.md → Version notes。
- 如果主机没有工具，只能编写命令和代码，不能编造结果；未测量的检查标记为 NOT_RUN。
- 如果主机没有浏览器或无头 GPU，只能实现和验证结构，视觉门禁标记为 NOT_RUN。
- 如果 @gltf-transform/cli 不可用，可读取 glTF JSON（.gltf 直接读；.glb 读 chunk 0）检查动画、蒙皮和目标，并说明无法进行的检查。
- 如果 Asset Foundry 不存在，通过 web3d-assets 手动获取。
- 需要操作者决策时（超预算的付费订单、范围未知的许可），停在该线并说明，不绕过。
- 该技能不负责运行时渲染、TSL、compute、性能（属于 web3d-runtime），也不负责文件管线和预算（属于 web3d-assets）。