排查具身化问题

诊断 Convai 具身化系统中的骨骼检测、预设槽位、模块 Tick 和面部合成问题，并提供修复与验证步骤。

当角色的 Rig 无法被正确检测、某个具身预设没有按预期生效、某个模块似乎从不更新，或者两个模块看起来在争夺同一个面部表情时，请使用此页面。先从 具身编辑器窗口 ——它的 设置 选项卡和 预设 选项卡表面会直接处理大多数这些问题，并在可用时提供一键修复。

故障排查表

症状	可能原因	修复方法	验证
具身编辑器中的 Rig 部分显示为 未设置	未选择角色，或者所选 游戏对象 没有 ConvaiCharacter 组件	在 Hierarchy 中选择该角色，或者将 ConvaiCharacter 添加到其 游戏对象	“ 设置 选项卡的 Rig 部分标题会变为 就绪 或 需要注意
Rig 部分显示为 需要注意："没有 Animator（可选）" 或 "Rig 不是 Humanoid"	该角色没有 Animator，或者其 Rig 未设置为 Humanoid	如果角色不需要骨骼身体运动，则跳过此项；否则请将模型的 Rig 类型在 Humanoid 其导入设置中	该发现项会被一个 正常 发现项替代，或者替换为针对以下骨骼解析的发现项： 头部/左眼/右眼
Rig 部分显示为 需要注意："Face rig 未被识别"	StandardRigBinding.DetectedConvention 解析为 未知 ——面部网格不符合已知的 blendshape 命名约定	设置 约定覆盖 在 StandardRigBinding 组件手动设置，或者指定一个 CustomRigConventionMap	该发现项会被一个 正常 发现项会命名该约定
Rig 部分显示为 需要注意: ……但勉强	DetectionConfidence 低于 50%	检查表情和口型同步是否正确；如果不正确，请手动设置该约定，而不要相信自动检测	DetectionConfidence 由 StandardRigBinding 升至高于 50%，或者该约定是手动设置的
"Head"、"Left eye" 或 "Right eye" 骨骼发现项显示警告	该 Rig 的 Humanoid Avatar 中没有为该语义映射骨骼，或者该 Rig 不是 Humanoid	将模型的 Rig 类型设置为 Humanoid 在其导入设置中，或者在上显式指定骨骼覆盖 StandardRigBinding	StandardRigBinding.TryGetBone 对该骨骼返回 是，相应警告就会停止在 Console 中出现
每次你碰到角色时，Console 都会重复一条 Rig 骨骼或 blendshape 警告	第一次未命中属于正常情况——这是 Rig 缺失，不是 bug	补上缺失项（见上面两行），或者如果需要它的功能未在使用中，则忽略它	该警告在组件生命周期内只会记录一次，而不是每帧一次，因此在没有状态变化的情况下不应再次出现
一个 ConvaiEmbodimentPreset 显示 未设置 在具身编辑器的 预设 选项卡	该预设包含重复的模块 ID、一个未选择模块的槽位，或者一个指向错误配置文件类型的槽位	打开预设并使用该发现项的修复按钮，例如 移除重复项 或 清除设置	该预设在 预设 选项卡中的状态会变为 就绪 或 需要注意
某个模块的设置与所分配预设所要求的不一致	保留缺失槽位 已启用，并且预设中没有该模块的槽位，因此该模块保留了其在 Inspector 中分配的自身配置文件	在预设中为该模块添加一个槽位，或者禁用 保留缺失槽位 如果你希望所有未列出的模块都改为回退到其默认配置文件	该角色的 Console 预设诊断消息不再将该模块列在“Active receivers without a preset slot”下
某个模块似乎从不更新——它在运行时状态从不变化	该组件不在相同的 游戏对象 层级中，和 ConvaiCharacter，因此它已自行禁用	将该组件移动到角色的 游戏对象 或其某个子对象上	Console 中提到该组件并指出“is not on a Convai character”的错误不再出现，并且组件在进入 Play 模式后仍保持启用
某个模块先是能正常更新一段时间，然后悄无声息地停止	该模块的 tick 抛出了异常，这会被报告一次，然后该模块会被跳过	检查 Console 中的“threw during its embodiment tick”消息，并修复该模块中的底层异常	一旦引发异常的代码被修正并重新进入场景，该模块就会恢复更新
两个模块看起来在争夺同一个面部表情	两个模块正在同一面部区域驱动 blendshape，且权重相互冲突	检查角色上的按区域权重 ConvaiFacialCompositionProfile ，而不是禁用任一模块——面部输出是按区域将 Emotion、LipSync 和 Custom 图层进行加权混合，而不是独占锁	该区域的 blendshape 会稳定成一个一致的表情，而不是明显地来回震荡

未检测到 Rig 或置信度过低

具身编辑器的 设置 选项卡会报告角色的 StandardRigBinding 在 Rig 部分下。如果角色还没有 StandardRigBinding 组件，该选项卡会显示“Rig will be worked out automatically”——Convai 会在角色启动的那一刻解析它，所以这本身不是问题。

一旦 StandardRigBinding 存在（无论是手动添加还是通过 Set Up This Character 按钮添加），其 DetectedConvention 和 DetectionConfidence 来自检查角色的面部网格。检测置信度低于 50% 会被视为值得检查的猜测：

Face rig 被检测为 <convention>，但只是勉强达到

如果完全没有已知约定匹配， DetectedConvention 保持 未知 并且选项卡会报告：

Face rig 未被识别

在这两种情况下，请设置 约定覆盖 在 StandardRigBinding 组件，或者提供一个 CustomRigConventionMap 用于不匹配任何内置约定的 Rig。参见 角色 Rig 设置 以了解完整的检测模型。

缺少骨骼或 blendshape 时，会在组件生命周期内通过 Console 记录一次警告：

[<character name>] 该 Rig 没有 '<bone>' 骨骼，因此任何需要它的内容都会保持未激活。请在 Character Rig 组件的 Custom Rig Setup 下为其分配，或使用其 humanoid avatar 映射了该骨骼的 Rig。

[<character name>] 该角色上的任何网格都没有 '<blendshape>' blendshape，因此任何驱动它的内容都会保持未激活。请将该 blendshape 添加到面部网格，或在 Custom Convention Map 下映射其实际名称。

这两条消息都来自 StandardRigBinding.TryGetBone 和 TryGetBlendshape。一旦相应的骨骼或 blendshape 得到解析，或者你分配了显式覆盖，它们就会停止重复。

预设槽位不匹配

一个 ConvaiEmbodimentPreset 将模块 ID 映射到配置文件资源。问题有两个来自预设资源本身：

• 重复的模块 ID。 如果某个预设把同一个模块列了两次，则只会使用第一个匹配的槽位。Console 会记录：

  重复的模块配置文件槽位：<ids>。将使用第一个匹配槽位。

  在具身编辑器的 预设 选项卡中打开预设并移除重复项。
• 某个槽位命名了项目未安装的模块、一个未选择模块的槽位，或者一个为该模块分配了错误类型配置文件的槽位。这些都会在 预设 选项卡中各自显示为单独的发现项，并带有一个可移除或清除有问题槽位的修复按钮。

另外， ConvaiEmbodimentPresetBinding 会将预设与角色上实际存在的模块进行比较，并在有任何异常时记录一条合并诊断消息：

[ConvaiEmbodimentPresetBinding] 预设 '<preset name>' 在 '<character name>' 上的诊断：<report>

“ <report> 部分可包含以下任意内容：

• 没有活动接收器的配置文件槽位：<ids>。 ——预设配置了角色没有的模块。
• 具有空配置文件的槽位：<ids>。 ——槽位存在，但未分配配置文件资源。
• 没有预设槽位的活动接收器；将保留 Inspector 配置文件：<ids>。 ——在以下情况下显示： 保留缺失槽位 已启用：没有匹配槽位的模块会保留其自身组件上分配的配置文件。
• 没有预设槽位的活动接收器；将应用空配置文件：<ids>。 ——在以下情况下显示： 保留缺失槽位 已禁用：没有匹配槽位的模块会回退到 null，它会解析为其内置默认配置文件。
• 空白配置文件槽位索引：<indices>。 ——某个槽位条目根本没有模块 ID。

如果某个模块的行为与您从预设中预期的不一致，请先检查 保留缺失槽位 时 ConvaiEmbodimentPresetBinding ——它决定未列出的模块是保留自身设置还是重置为默认值。

某个模块没有在 tick

每个具身模块都会在以下位置向角色的 tick 调度器注册： OnEnable 通过 EmbodimentContext.RegisterTickable。两种不同的故障看起来相似，但原因不同。

该组件根本没有注册。 当该组件不在相同的 游戏对象 层级中，和 ConvaiCharacter。该组件会自行禁用，并且 Console 会记录：

[<ComponentType>] '<GameObject name>' 不在 Convai 角色上，因此它没有可驱动的内容。请将此组件移动到带有 Convai Character 组件的对象（或其子对象）上。

将该组件移动到角色的 游戏对象 或其子对象上，然后重新启用它。

该组件已注册，但其 tick 抛出异常。 调度器会捕获任一单个模块 tick 中的异常，只报告一次，并继续正常 tick 其他所有模块：

[EmbodimentTickScheduler] '<GameObject name>' 上的 <ComponentType> 在其 embodiment tick 期间抛出了异常，并且只会被报告一次。该角色上的其他模块不受影响。

由于这只会在每次会话中每个模块报告一次，因此如果某个模块看起来“停止工作”而 Console 不再输出任何内容，这通常就是这种情况的标志。修复源头处的异常并重新进入 Play 模式——模块就会在修复后恢复。

如果两种消息都没有出现，而模块仍然看起来没有反应，请确认场景处于 Play 模式：tick 调度器只会在运行时创建，因此在 Edit 模式下，除具身编辑器的 实时 选项卡。

模块之间的面部输出冲突

面部 blendshape 并不由单个模块独占。相反，每个 blendshape 区域（嘴、眉、眼、脸颊/鼻子、下巴以及其他所有部分）都会根据角色上的按区域权重，将 Emotion、LipSync 和 Custom 图层混合在一起 ConvaiFacialCompositionProfile，并分别对应静止和说话状态。

可见的冲突——表情闪烁或过冲而不是稳定下来——通常意味着两个图层以相近权重向同一区域贡献了冲突值，而不是某个模块坏了。请检查 ConvaiFacialCompositionProfile 该区域在上的权重，而不是禁用其中一个模块：降低该区域中某一图层的权重，或者通过调整其名称模式将某个 blendshape 移到不同区域，可以在不丢失模块其他输出的情况下解决冲突。参见 面部组合 以了解完整的按区域加权模型。

下一步

具身化编辑器窗口角色骨架设置具身化预设