> 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 最常见的故障：完全没有动作、动作与其他模块冲突、脚本手势被拒绝、动作显得过于细微或过于夸张，以及动作随相机距离变化而异常缩放。

### 症状对照表

| 症状                              | 可能原因                                                 | 解决方法                                                          | 验证                                                                    |
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
| 完全没有动作                          | 骨架绑定失败，或未解析到 `Spine` 骨骼                              | 确认角色具有已映射脊柱骨骼链的 Humanoid `Animator` 组件                        | 控制台没有显示 `Rig binding has no Spine bone` 错误，且角色在静止时会呼吸和摇摆              |
| 动作与脚本动画冲突                       | 另一个模块正在控制姿态，例如 Body Animation 正在播放行走或全身动作，或者手势抑制正在生效 | 查看检视器中的 **共享此身体** 卡片，了解哪个模块正在减弱动作                             | **运行时状态** 显示 `GesticulationSuppression` 恢复为 `None` ，表示另一个模块已结束        |
| 发出的 `Nod`/`Shake`/`Tilt` 请求没有效果 | `HeadGestureHandle.Refusal` 为 `Busy` 或 `Unavailable` | `Busy`：稍等片刻后重试。 `Unavailable`：按照下文修复骨架或配置文件设置                 | `handle.IsActive` 在下一次请求时为 `true` ，或 `handle.Refusal` 在下一次请求时为 `None` |
| 动作显得过于细微                        | `表现力预设` 为 `Subtle`，或振幅字段设置得过低                        | 将 `表现力预设` 调高至 `自然` 或更高，或者提高相关配置文件中的振幅字段                       | 在正常的 2 米摄像机距离下，可以看清角色的姿势起伏和摇摆                                         |
| 动作看起来过于戏剧化                      | `表现力预设` 为 `戏剧化`，或者振幅字段设置得过高                          | 降低 `表现力预设` 为 `自然`，或者降低相关配置文件中的振幅字段                            | 在正常的交谈距离下，手势不再显得夸张                                                    |
| 动作随摄像机距离变化异常                    | `启用摄像机距离 LOD` 已开启，且主摄像机远离或靠近了角色                      | 确认此行为符合预期（它不会影响呼吸、姿势或手势，只影响摇摆和待机时的手部动作），或者关闭 `启用摄像机距离 LOD` 开关 | 关闭该开关后，摇摆和手部微动作的振幅不会随摄像机距离变化                                          |

### 完全没有动作

控制器无法解析 `Spine` 骨骼时将处于不活动状态。两种不同的故障都会导致这种情况，且每种故障都只会通过 `ConvaiLogger` 在 `LogCategory.BodyLanguage` 下记录一次，不会逐帧记录：

* 完全没有绑定骨架：

  ```
  [ConvaiBodyLanguageController] No rig binding could be resolved. Body language needs a Humanoid character with a StandardRigBinding (added automatically for Humanoid Animators). The module stays inert.
  ```

  (`ConvaiBodyLanguageController.cs:1863-1865`)
* 存在骨架绑定，但其中没有 `Spine` 骨骼：

  ```
  [ConvaiBodyLanguageController] Rig binding has no Spine bone. Check that the Animator avatar is Humanoid and the spine chain is mapped; the module stays inert until a Spine bone exists.
  ```

  (`ConvaiBodyLanguageController.cs:1874-1876`)

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

* 角色上没有 `Animator` ："此角色没有 Animator — Body Language 会在已动画驱动的骨架上叠加动作，因此没有可供其驱动的对象"（`BodyLanguageSetupService.cs:451-454`).
* Humanoid Avatar 未映射 Spine 骨骼："这是 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 播放行走或全身动作时，它会在动作持续期间接管身体—— `GestureSuppression` 报告 `UpperBody` 或 `FullBody` 在该动作运行期间，Body Language 自身的姿势和手势也会相应让出控制权。这是有意的交接，并非故障。

| `GestureSuppression` | 即可完全隐藏叠加层。                                                                  |
| -------------------- | --------------------------------------------------------------------------- |
| `None`               | 不抑制 — 姿势、呼吸和手势提示均可执行。                                                       |
| `UpperBody`          | 语义手势动画片段会被拒绝，但姿势（由配置文件中的 `Upper Body Suppression Posture Weight`控制）和呼吸仍会继续。 |
| `FullBody`           | 手势提示会被拒绝，程序化姿势和呼吸则会渐隐至零。                                                    |

ConvaiBodyLanguageController `检查器中的` 「共用此身体」 **卡片会在进入 Play 模式前，列出所有共用角色身体的模块，以及每个模块会改变什么。运行时，** 「运行时状态」 **会补充此刻正在发生的情况：** 「身体共用对象」 **会说明当前是否有任何因素在减弱动作，而** 「头部移动者」 **会说明是 Gaze 还是 Body Language 本身在移动头部。** Nod

### 发出的 `Nod`/`Shake`/`Tilt` 请求没有效果

`绝不会返回` null `，也绝不会抛出异常 — 检查` HeadGestureHandle.IsActive `和` HeadGestureHandle.Refusal `，不要想当然地认为手势已经播放：` Refusal == HeadGestureRefusal.Busy

* `：角色当前正在执行头部手势，另有一个手势在队列中等待。这是暂时状态 — 稍后重试相同请求。`Refusal == HeadGestureRefusal.Unavailable
* `：角色目前完全无法执行头部手势 — 没有可用的骨骼绑定、没有 Body Language 配置文件，或者组件已禁用或未处于运行状态。请修复骨骼绑定或配置文件的根本问题，而不是重试。`有关完整的处理模式，请参阅

「触发手势和反应」，其中包括随附的 [ConvaiHeadResponseActionExecutor](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md) ，它已实现重试 `Busy`拒绝状态，最长可持续 `1.5 秒。` 由

{% hint style="info" %}
PulseGesture `构建的请求`   `GestureCueKind` 没有随包提供动画的值 — `Emphatic`, `Beat`, `PalmToPlayer`, `HandToChest`, `IndicateObject`，或 `Enumerate` — 始终会回退为头部节拍和姿态脉冲。这是预期行为，并非错误：请参阅 [肢体语言脚本编写参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/scripting-reference.md#gesturecuekind) 了解哪些值已提供随包内容。
{% endhint %}

### 动作看起来过于含蓄或过于戏剧化

按以下顺序检查：

1. `Expressiveness Preset` （位于已分配的 `ConvaiBodyLanguageProfile` 上）— `Subtle` 会完全移除可选行为（耸肩、手部细微动作），并降低动作幅度； `Theatrical` 则会将其增强到最大。
2. 运行时的 `ConvaiBodyLanguageController.Expressiveness` 覆盖值 — 在下一次配置文件热替换前，它的优先级高于配置文件，因此脚本可能已将其设置为不同于配置文件中预设的值。
3. 配置文件中的各项幅度字段 — `Max Openness Degrees`, `Max Lean Degrees`, `Posture Pulse Amplitude`以及 [肢体语言配置文件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/profile-reference.md).

中列出的其他字段。 `ConvaiBodyLanguageController` 检查器中的 **姿态（目标值 → 当前值）** 部分会显示实时的目标姿态值和当前姿态值。如果目标值始终接近零，则说明状态策略和情绪没有传递到各个控制器 — 请检查配置文件中的 **状态策略** 部分。如果目标值有变化，但当前值没有跟随变化，请检查 **主权重**: `0` ；这表示模块尚未完成渐入，或绑定骨架失败。

### 动作随摄像机距离变化异常

`Enable Camera Distance Lod` 会根据主摄像机与角色之间的距离，缩放身体摇摆幅度和待机手部动作权重 — 近距离时动作更含蓄，远距离时幅度更大，在正常对话距离时保持中性。它不会影响呼吸、姿态或手势。如果角色的摇摆幅度随镜头取景远近而变化，则此开关正在按预期工作；如果场景要求无论摄像机距离如何都保持固定幅度，请在配置文件中将其关闭。

### 后续步骤

{% content-ref url="/pages/b0a834d0e9425d60d0788646a7b3343330f88cf0" %}
[触发手势与反应](https://docs.convai.com/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" %}
[调节表现力](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/tune-expressiveness.md)
{% endcontent-ref %}

{% content-ref url="/pages/aa2dfbd502cd5beea5e136b8b51781cf4aa0c88c" %}
[肢体语言配置文件参考](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
