> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.md).

# 肢体语言故障排查

诊断为什么 Convai 角色的肢体语言控制器没有动作、与其他模块冲突，或者表现得过于含蓄或过于戏剧化。

诊断最常见的 Body Language 失败模式：完全没有动作、与另一个模块相冲突的动作、被拒绝的脚本手势、显得过于微弱或过于戏剧化的动作，以及随镜头距离变化而异常缩放的动作。

### 症状表

| 症状                         | 可能原因                                                | 修复方法                                                                     | 验证                                                           |
| -------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| 完全没有动作                     | 骨骼绑定失败，或者没有 `脊柱` 骨骼已解析                              | 确认角色具有 Humanoid `Animator` 并且脊柱链已映射                                      | 控制台没有显示 `骨骼绑定没有 Spine 骨骼` 错误，而且角色在静止时会呼吸并摆动                  |
| 动作与脚本动画冲突                  | 另一个模块正在占用该姿势——Body Animation 正在播放走路或全身动作，或者手势抑制正在生效 | 检查 Inspector 的 **共享此身体** 卡片，查看是哪个模块在减弱动作                                 | **运行时状态** 显示 `GesticulationSuppression` 恢复到 `无` 在另一个模块结束后    |
| 某个 `点头`/`摇头`/`倾斜` 请求没有任何效果 | `HeadGestureHandle.Refusal` 为 `Busy` 或 `不可用`        | `Busy`：稍等片刻后重试。 `不可用`：修复下面的骨骼或配置文件设置                                     | `handle.IsActive` 为 `true` 在下一次请求时，或者 `handle.Refusal` 为 `无` |
| 动作显得过于微弱                   | `表现力预设` 为 `含蓄`，或者幅度字段设置得过低                          | 提高 `表现力预设` 到 `自然` 或更高，或者提高相关配置文件的幅度字段                                    | 在正常 2 米的镜头距离下，角色的姿势脉冲和摆动会变得可见                                |
| 动作显得过于戏剧化                  | `表现力预设` 为 `戏剧化`，或者幅度字段设置得过高                         | 降低 `表现力预设` 到 `自然`，或者降低相关配置文件的幅度字段                                        | 在正常的对话距离下，手势不再显得夸张                                           |
| 动作随镜头距离变化而异常缩放             | `启用 Camera Distance Lod` 已开启，且主摄像机已远离或靠近角色          | 确认此行为是有意为之（它不会影响呼吸、姿势或手势——只影响摆动和静止手部动作），或者关闭 `启用 Camera Distance Lod` 关闭 | 一旦关闭该开关，摆动和手部微动的幅度将保持不变，不受镜头距离影响                             |

### 完全没有动作

当控制器无法解析某个 `脊柱` 骨骼时，它就会保持静默。此现象由两种不同的故障导致，每种都会通过 `ConvaiLogger` 在 `LogCategory.BodyLanguage` 仅记录一次——绝不是每帧：

* 完全没有骨骼绑定：

  ```
  [ConvaiBodyLanguageController] 无法解析任何骨骼绑定。Body language 需要一个带有 StandardRigBinding 的 Humanoid 角色（该绑定会为 Humanoid Animator 自动添加）。模块将保持静默。
  ```

  (`ConvaiBodyLanguageController.cs:1863-1865`)
* 存在骨骼绑定，但没有 `脊柱` 骨骼：

  ```
  [ConvaiBodyLanguageController] 骨骼绑定没有 Spine 骨骼。请检查 Animator avatar 是否为 Humanoid，并且脊柱链是否已映射；在存在 Spine 骨骼之前，模块将保持静默。
  ```

  (`ConvaiBodyLanguageController.cs:1874-1876`)

在按下 Play 之前， `ConvaiBodyLanguageController` 检查器的 **此角色** 部分会执行相同的检查，并在 Inspector 文本中说明相同原因，无需进入 Play 会话：

* 没有 `Animator` 在角色上：“这个角色没有 Animator——Body Language 是将动作叠加到已动画化的骨架上的，所以它没有可移动的对象”（`BodyLanguageSetupService.cs:451-454`).
* 没有映射脊柱的 Humanoid avatar：“Humanoid avatar，但没有映射 Spine 骨骼——请检查 Avatar 的脊柱链”（`BodyLanguageSetupService.cs:459`).
* 非 Humanoid avatar：“该 avatar 不是 Humanoid，因此无法解析 Spine 骨骼”（`BodyLanguageSetupService.cs:460`).

先修复 Animator 的 Humanoid avatar 映射，然后重新进入 Play 模式。骨架上的其他一切——胸部、肩膀、髋部、腿和手臂——都是可选的：缺少某个可选骨骼只会禁用依赖它的行为（例如，缺少肩膀会禁用肩部紧张，但姿势和呼吸仍然会运行）。 **此角色** 卡片会报告每个可选缺口，而不会把它视为故障。

### 动作与脚本动画冲突

Body Language 与 Body Animation 和 Gaze 共享脊柱、肩膀和头部。当 Body Animation 播放走路或全身动作时，它会在该持续时间内夺回身体控制权—— `GesticulationSuppression` 报告 `UpperBody` 或 `FullBody` 只要该动作持续运行，Body Language 自身的姿势和手势也会相应让位。这是有意的接管，不是故障。

| `GesticulationSuppression` | 效果                                                                      |
| -------------------------- | ----------------------------------------------------------------------- |
| `无`                        | 没有被抑制——姿势、呼吸和手势提示都可用。                                                   |
| `UpperBody`                | 语义手势片段会被拒绝，但姿势（在配置文件的 `Upper Body Suppression Posture Weight`）和呼吸仍保持有效。 |
| `FullBody`                 | 手势提示会被拒绝，程序化姿势/呼吸会衰减到零。                                                 |

该 `ConvaiBodyLanguageController` 检查器的 **共享此身体** 卡片会在 Play 前列出共享角色身体的每个模块以及各自修改的内容。播放时， **运行时状态** 会补充当前这一刻正在发生的事情： **共享身体的模块** 说明当前是否有任何东西正在削弱动作，且 **头部由以下内容移动** 说明是 Gaze 还是 Body Language 自身在移动头部。

### 某个 `点头`/`摇头`/`倾斜` 请求没有任何效果

`点头` 从不返回 `null` 并且绝不会抛出异常——请检查 `HeadGestureHandle.IsActive` 和 `HeadGestureHandle.Refusal` 而不要假设手势已经播放：

* `Refusal == HeadGestureRefusal.Busy`：角色已经在执行一个头部手势，后面还排着一个。该状态是暂时的——请在稍后再次重试同一请求。
* `Refusal == HeadGestureRefusal.Unavailable`：角色当前根本无法执行头部手势——没有可用的骨架、没有 Body Language 配置文件，或者组件已禁用或未运行。请修复底层骨架或配置文件问题，而不是重试。

参见 [触发手势和反应](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md) 查看完整处理模式，包括随附的 `ConvaiHeadResponseActionExecutor`，它已经会重试一个 `Busy` 拒绝状态，最长 1.5 秒。

{% hint style="info" %}
某个 `PulseGesture` 由以下内容构建的请求 `GestureCueKind` 值，没有随附动画—— `强调`, `节拍`, `手掌朝向玩家`, `手放胸前`, `指示物体`，或 `列举` ——总是会回退到头部节拍和姿势脉冲。这是预期行为，不是 bug：参见 [身体语言脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/scripting-reference.md#gesturecuekind) 了解哪些值带有随附内容。
{% endhint %}

### 动作显得过于微弱或过于戏剧化

按顺序检查：

1. `表现力预设` 在已分配的 `ConvaiBodyLanguageProfile` — `含蓄` 会完全移除可选行为（耸肩、手部微小生动感）并降低幅度； `戏剧化` 会将其最大化。
2. 运行时 `ConvaiBodyLanguageController.Expressiveness` 覆盖值——它会在下一次配置文件热切换之前压过配置文件，因此脚本可能已将其设置为与配置文件创作值不同的值。
3. 配置文件中的各个幅度字段—— `最大张开角度`, `最大倾斜角度`, `姿势脉冲幅度`以及列在 [身体语言配置文件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/profile-reference.md).

该 `ConvaiBodyLanguageController` 检查器的 **姿势（目标 → 当前）** 部分会显示实时的目标姿势值和当前姿势值。如果目标始终停留在接近零的位置，说明状态策略和情绪没有到达导演器——请检查配置文件的 **状态策略** 部分。如果目标在变化但当前值没有跟随，请检查 **主权重**: `0` 表示模块尚未完成渐入，或者骨骼未绑定。

### 动作随镜头距离变化而异常缩放

`启用 Camera Distance Lod` 会根据主摄像机与角色的距离来缩放摆动幅度和静止手部动作权重——近景更细微，远景更明显，在正常对话距离下保持中性。它绝不会影响呼吸、姿势或手势。如果角色的摆动因镜头构图而看起来不同，那么这个开关就是按预期工作的；如果场景要求无论镜头距离如何都保持恒定幅度，请在配置文件中将其关闭。

### 下一步

{% content-ref url="/pages/b0a834d0e9425d60d0788646a7b3343330f88cf0" %}
[触发手势与反应](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md)
{% endcontent-ref %}

{% content-ref url="/pages/652efa54160d6791ad8f9dfe70dc962fa595d73a" %}
[调节表现力](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/tune-expressiveness.md)
{% endcontent-ref %}

{% content-ref url="/pages/aa2dfbd502cd5beea5e136b8b51781cf4aa0c88c" %}
[肢体语言配置文件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/profile-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.