自动关联目录：动画资产契约：能加载，不等于能在当前骨架播放

核心判断：UAnimSequence 成功反序列化只证明运输完成。只有源语义、目标骨架、姿势数据、依赖闭包和当前宿主代际同时通过校验，动画才有资格绑定；否则必须保留占位姿势，并返回稳定、可定位的拒绝原因。

一、业务冲突：角色和动画可以独立生产，却必须组合成同一个姿势

创作者希望把外部动作导入、在编辑态修改关键帧，再把它用于另一个流程产出的角色；运行时还要支持资源晚到、角色换装、首次进入预取和不同目标构建。这让 Mesh、Skeleton 和 Animation 不再天然来自同一个 UE 内容包。业务看到的是一个 AnimationId，客户端实际要回答的却是五个不同问题：文件能否读取、语义能否解释、骨架是否兼容、目标制品能否求值、异步结果是否仍属于当前角色。

工程中出现过几条很有代表性的失败链：

• 外部动画的完整骨骼路径与目标一致，早期报告便把它称为“完全匹配”；但交换格式没有携带目标绑定姿势，实际上只能证明层级相同，无法证明同名骨骼的参考变换相同。若继续绑定，动作可能不崩溃，却会以扭曲、漂移或错误根运动的形式失败。
• 二进制 FBX 依赖 UE Editor 的导入器，而轻量提取文档只包含层级和采样结果。二者如果共用一个“FBX 已验证”的状态，编辑器里能导入不代表 Client、小游戏目标或自动化环境具有相同能力。
• FBX 坐标系和单位转换曾不能只对每个节点的 Local Transform 独立处理。UE 的场景轴变换会影响根节点及其后代，嵌套骨骼必须先在规范空间重建 Global Transform，再反求 Local；否则子骨骼平移仍可能保留源单位。
• 一次动画 Bundle 的表、哈希和 CRC 都合法，根对象也确实是 UAnimSequence，但构建阶段剥掉了外部骨骼/曲线压缩设置。打包 Client 在异步加载线程反序列化压缩数据时访问空依赖并崩溃。它证明“文件完整”与“UE 对象图完整”是两种完整性。
• Editor 中的 Sequence 可能没有 Raw Track，却带有可用的压缩姿势数据。若自定义求值器只按 Raw 数量判断，PIE 会跳过贡献或回到 T Pose，而打包 Client 反而能走压缩路径正常播放。
• 关键资源预取完成，也只表示内容可获得；它不表示 Animator 已创建、Sequence 已绑定，更不表示动画线程已经成功采样出第一帧有效基础姿势。

因此问题不能简化成“支持 FBX”或“异步加载动画”。真正的业务目标是：独立生产的内容只能在兼容性可证明、目标能力可用、依赖完整时组合；失败要停在绑定之前，而不是把错误姿势交给玩家。

二、实际实现：把格式、骨架、制品和绑定拆成连续门禁

后续实现逐步形成了三类内容形态，而不是让一种格式承担所有职责：

1. 可编辑语义文档保存关键帧、曲线、标记、Skeleton Signature、Root Policy 和版本，是无损编辑与交换的权威。
2. DCC 桥接格式负责进出外部工具。二进制 FBX 只在 Editor 模块处理；层级提取文档可以跨目标读取，但必须诚实声明它不含可验证的 Rest Pose，不能冒充二进制 FBX。
3. UE 运行时制品是按目标 Cook、压缩并可被姿势求值器直接采样的 UAnimSequence。它不是编辑真相，而是某个源版本、编译器版本、平台和依赖环境下的派生产物。

导入先要求目标骨架签名。优先比较完整骨骼路径，旧数据只有叶子名称时，仅在名称唯一且层级可消歧的情况下兼容，并产生警告。兼容结果被拆成 HierarchyOnly、RestPoseVerified 和 Incompatible：没有目标 Rest Pose 时绝不再声称精确兼容；调用方要求校验而提取格式又拿不出源 Rest Pose 时，直接以 RestPoseUnavailable 失败。当前只能忠实表达“忽略根节点世界平移”这一类 Root Policy，其它策略不猜测，返回 UnsupportedRootPolicy。轴和单位统一到 UE 使用的规范空间后，才生成本地轨道。整个导入是事务：读取、归一化、兼容校验和轨道构建全部成功后才替换 Working Copy，失败不推进 Revision。

运行时加载又做一次不同层次的校验。逻辑动画引用先解析并锁定版本；多个 Track 请求同一物理资产时合并下载，但每个等待者保留 Host、Track 和捕获的 Generation。依赖集合全部到达后，根对象必须是预期动画类型，Sequence 必须带 Skeleton，或只在“当前 Mesh 已明确提供 Skeleton、Sequence 恰好缺失关联”的恢复路径中补上关联；随后通过 UE Skeleton 与 Mesh 的兼容检查。宿主已销毁、World 已切换、Track 已停止或 Generation 已变化时，晚到结果只记为 Stale，不能绑定到新身体。

这里还处理了 UE Editor 与 packaged runtime 的差异：如果 Cooked Sequence 没有 Raw 数据但压缩数据有效，Editor 下显式切回压缩姿势路径，并同步 Virtual Bone Guid；Raw 和压缩都不可用则以确定错误拒绝。另一条“导入层级生成骨架”的实际装配路径更严格：逐骨比较名称、父索引和参考姿势，再验证压缩轨道数量及 Track-to-Skeleton 映射，全部通过后才把 Mesh、Skeleton 和 Sequence 连接起来。

flowchart LR
    S[关键帧语义文档\nRevision + Skeleton Contract] --> I[导入/归一化门禁\nAxis + Unit + Root Policy]
    F[FBX 或层级提取格式] --> I
    I --> C{兼容等级}
    C -->|RestPoseVerified| B[按目标编译/Cook]
    C -->|HierarchyOnly + 明示风险| B
    C -->|Incompatible| X[拒绝并保留旧 Working Copy]
    B --> A[运行时制品清单\nSequence + 依赖 + Target]
    A --> L[异步加载\n版本锁定 + 请求合并]
    L --> G{类型/骨架/姿势数据/Generation}
    G -->|全部通过| P[原子绑定 Track]
    G -->|任一失败| H[占位或上一有效姿势\n稳定诊断码]

首次进入的优化也被分成两个事实。客户端可以根据角色配置提前收集身体、材质依赖和 Idle/Walk/Run/Jump/Fall 等最小动作集，去重后提高请求优先级；预测配置与 DS 后续给出的权威配置不同，则补提权威集合，共享内容仍由底层合并。这个过程不阻塞场景解码，也不调用 Play。真正的“角色可见就绪”由本地 Body 的动画实例在动画线程成功贡献至少一个有效 Base Pose 后，再回报 GameThread；只创建 Track、下载结束或落到参考姿势都不能冒充首姿势完成。

三、值得保留：对“不知道”给出类型，而不是用成功布尔值掩盖

第一，格式职责被说清了。编辑文档负责语义，FBX 负责 DCC 交换，Cooked Sequence 负责目标求值。二进制 FBX 放在 Editor 模块，Runtime、Client 和 Server 不链接 UnrealEd；轻量提取格式也不再借用 FBX 名义。这种模块边界既减少目标体积，也避免 API 在某些构建中“存在但永远失败”。

第二，兼容性不是一个布尔值。HierarchyOnly 明确表达“只验证到了这里”，RestPoseVerified 才代表参考姿势也通过；缺数据与真正不兼容使用不同诊断。相比自动接受同名骨骼，这种分级让产品可以在预览、发布和运行时采用不同门槛。

第三，失败不污染当前状态。导入只有全链成功才提交 Working Copy；发布失败不覆盖既有版本；运行时只有依赖、类型、骨架和代际都通过才写入 Track。旧内容继续可用，失败结果可以重试，也不会留下“Revision 已更新但轨道只生成一半”的中间态。

第四，异步生命周期进入了资产契约。共享请求解决重复下载，等待者级状态保留每个 Track 的 Pending/Ready/Failed/Cancelled；等待者离开时撤销自身绑定资格，底层请求若仍被其它消费者共享则继续完成并丢弃该动画的晚到结果。版本锁定避免请求期间注册表变化导致同一 Track 前后拿到不同制品，Generation 则阻止旧 Mesh 的回调污染新 Mesh。

第五，UE 的 Raw/Compressed 双路径被当作真实兼容问题处理。自定义 AnimInstance 不是拿到 Sequence 就直接 GetAnimationPose，而是在采样前确认当前构建实际能使用的数据路径；不满足条件的贡献被跳过并节流告警。它修复的是 Editor 与 Client 的求值分叉，而不是仅让一个自动化用例变绿。

第六，Preload 与 First Pose 分开计量。预取解决“资源何时开始来”，首姿势门禁解决“玩家何时真的看到正确角色”。这两个状态拆开后，下载慢、依赖缺失、骨架拒绝、AnimInstance 未建立和求值失败才能分别归因。

四、结构性缺陷：门禁已经存在，但还不是一份统一、不可变的制品契约

当前校验分布在外部格式导入、Working Session、运行时加载协调器、特殊层级动画装配和自定义 AnimInstance 中。每一处都修复了真实问题，但同一个“兼容”在不同路径上并非同一强度：导入侧比较路径签名和可选 Rest Pose，通用运行时主要依赖 USkeleton::IsCompatibleMesh，特殊装配路径则逐骨比较名称、父索引和参考姿势。新增一种发布路径时，很容易只复用其中较弱的一层。

“Sequence 没有 Skeleton 时，用当前 Mesh 的 Skeleton 补上”也是一项需要收紧的恢复策略。它对已知 Cook/装配链丢失对象关联的问题有效，却把“制品缺元数据”转化成了“相信当前宿主”。如果 Sequence 的轨道实际来自另一套同名层级，这个补写会让后续指针兼容检查失去证据意义。它应受制品来源、轨道签名和编译器版本约束，而不能成为通用容错。

依赖闭包也经历过一次边界误判。对所有资产统一剥离外部硬引用，看起来能得到自包含 Bundle；但动画压缩数据依赖骨骼/曲线压缩设置与 Codec 对象，删除 Import 而不重写对象图会在反序列化阶段崩溃。工程曾尝试把这些对象复制进每个动画包，随后收敛为只对真正可独立化的静态网格做剥离，动画、骨骼网格等保留原始依赖，由已挂载包提供。这是更诚实的修复，但仍说明当前“显式业务依赖”和“UE Package 隐式依赖”属于两套清单：根动画下载完成，不天然证明其引擎依赖已安装。

编辑器预览与运行时也尚未天然同构。Timeline 可以直接采样 Working Copy 并向选中 Mesh 写临时 Bone Override；Persona 可以播放瞬时构造的 Sequence；真正运行时播放的却是发布后 Cook、压缩、跨包加载的制品。前两条路径适合提供低延迟编辑反馈，却会绕过 Cook、压缩设置、依赖挂载和运行时加载门禁。预览正确只能证明源语义在该采样器中正确，不能证明目标制品可播放。

最后，目标差异已经通过条件编译和模块裁剪暴露出来：有的轻量目标不携带 Sequencer，只接受骨架动画后端；二进制导入只属于 Editor；DS 可能需要骨架拓扑、根运动或玩法标记，却不需要渲染 Mesh 和完整视觉姿势。继续把“动画资产”定义成同一个 UObject，会让能力差异散落成宏和空指针判断。

五、目标设计：让编译器产出带证明的 Artifact Manifest

更好的架构不是再加一层 IsCompatible，而是把已经存在于多处的事实冻结成版本化契约。源文档、骨架和每个目标制品都不可变；发布只新增 Revision，不原地修改。建议至少有三份结构：

• SkeletonContract：完整骨骼路径、父索引、Rest Pose Hash、Virtual Bone Revision、Root Policy 和可选的显式 Retarget Profile。
• AnimationArtifactManifest：源 Revision、编译器版本、目标平台/运行域、制品 Hash、姿势编码、压缩设置身份、必需 Package/Asset 集合、Skeleton Contract 和支持的事件能力。
• BindingTicket：角色身份、宿主 Generation、Track 身份、锁定的动画 Revision、期望 Skeleton Contract、占位策略和取消句柄。

发布编译器先对语义文档做确定性校验，再为 Editor Preview、Client、轻量 Client 和 DS 分别输出所需制品。Client Manifest 指向可求值 Sequence 及完整依赖；DS 只有在玩法确实读取根运动、骨骼查询或标记时才生成对应的 headless 数据，否则只有动作状态元数据。Retarget 不做运行时猜测：只有来源/目标 Skeleton Contract、骨骼映射、尺度规则和质量门槛均被冻结的 Profile 才能生成派生制品；没有 Profile 就明确不兼容。

BindResult BindAnimation(BindingTicket ticket)
{
    Host* host = ResolveHost(ticket.characterId);
    if (!host || !host->Accepts(ticket.world, ticket.generation))
        return Stale("HostGenerationChanged");

    Manifest manifest = ResolveExactRevision(ticket.animationRevision);
    if (!manifest.Supports(CurrentTarget()) || !VerifyHash(manifest))
        return KeepPlaceholder("WrongTargetOrCorruptArtifact");
    if (!DependenciesMounted(manifest.requiredPackages))
        return Pending(Install(manifest.requiredPackages, ticket.cancel));

    Compatibility c = Compare(manifest.skeleton, host->SkeletonContract());
    if (c == Compatibility::NeedsRetarget) {
        RetargetProfile profile = ResolveProfile(manifest.skeleton, host->SkeletonContract());
        if (!profile.IsVerified())
            return KeepPlaceholder("RetargetProfileMissing");
        manifest = ResolveRetargetedArtifact(manifest, profile, CurrentTarget());
    } else if (c != Compatibility::Exact) {
        return KeepPlaceholder(c.DiagnosticCode());
    }

    Sequence* sequence = LoadTypedSequence(manifest.artifact);
    if (!sequence || !HasUsablePoseData(sequence, CurrentBuild()))
        return KeepPlaceholder("PoseDataUnavailable");
    if (!ResolveHost(ticket.characterId)->Accepts(ticket.world, ticket.generation))
        return Stale("HostChangedDuringLoad");

    return CommitTrackAtomically(ticket.trackId, sequence, ticket.virtualTime);
}

Editor 不必牺牲即时预览，但必须把两种成功分开显示：SourcePreviewReady 只表示 Working Copy 可采样，TargetArtifactVerified 才表示同一冻结 Revision 经正式编译、Cook 和目标加载器后可播放。发布门禁对代表性时间点比较源采样器与目标制品的 Bone Transform Hash、曲线和标记序列，并在真正的 Client 加载环境执行；这样编辑体验仍快，发布结论也不再借用预览结果。

六、决策规则：证明到哪一层，就只承诺到哪一层

动画资产契约可以用六条规则评审：

1. Loaded UObject 只代表反序列化结果，不能直接映射为 Playable。
2. 骨骼层级相同只能叫 HierarchyOnly；参考姿势、Virtual Bone 和 Root Policy 也一致后，才允许称为精确兼容。
3. 缺少显式 Retarget Profile 时拒绝跨骨架播放；运行时按名字猜骨骼不是降级，而是在制造不可复现结果。
4. Preload、DependenciesMounted、Bound、FirstPoseSampled 是四个状态，任何一个都不能替代下一个。
5. Editor 直采样预览和正式目标制品分别验收；二者共享源语义与编译器测试，但不能共享成功标志。
6. 制品按目标能力生成。Editor 导入器、Client 姿势数据、轻量目标后端和 DS 玩法数据没有理由被塞进同一个包。

我的反思是：早期最容易把“动画能播”理解成一个 API 调用，随后才发现 UE 把 Skeleton、参考姿势、Raw/Compressed 数据、压缩设置、Virtual Bone、Package Import 和构建目标都带进了这个判断。后来补上的兼容等级、事务导入、Editor 模块隔离、版本锁定、依赖 Barrier、Generation、压缩路径修复和 First Pose 门禁都解决了真实问题；不足之处是这些证明仍分散在各条路径。下一步不应继续堆特殊判断，而应让编译器把证明写进 Manifest，让运行时只执行契约。动画管线的成熟度，不由支持多少格式衡量，而由它能否在绑定之前准确说明“为什么能播，为什么不能播”。