> 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/features/emotion/troubleshooting-and-diagnostics.md).

# 排查情绪问题

大多数情绪问题都属于三类之一：完全没有可视输出、分数在更新但脸部不动，或者事件和脚本回调没有触发。先查看 `Current.DominantScore` 在 Play Mode 下——这个信号即可判断问题出在信号路径还是输出绑定。

### 检查实时状态

`ConvaiEmotionController` 在 Play Mode 期间可在 Inspector 中直接查看完整管道状态，无需任何额外工具。

| 关注什么               | 在哪里找到它                                           | 它告诉你什么                                     |
| ------------------ | ------------------------------------------------ | ------------------------------------------ |
| **Current → 主导标签** | `ConvaiEmotionController` Play Mode 下的 Inspector | 当前哪个规范情绪占主导。 `“neutral”` 表示没有活动信号。         |
| **Current → 主导分数** | `ConvaiEmotionController` Play Mode 下的 Inspector | 主导情绪的平滑强度 \[0–1]。大于 0 的值可确认管道正在接收并处理服务器信号。 |
| **锁定情绪** 复选框       | `ConvaiEmotionController` Inspector（任意模式）        | 勾选后，服务器信号将被忽略。角色会保持锁定的表情。                  |

若要在不进入 Play Mode 的情况下预览 blendshape 槽位映射，请启用 **锁定情绪**中，设置 **锁定情绪标签** 为规范标签，并设置 **锁定强度** 到 `1.0`。因为 `ConvaiEmotionController` 继承 `[ExecuteAlways]` 自其基类，blendshape 会立即在 Scene 视图中更新——无需 Play Mode。

{% hint style="danger" %}
**锁定情绪** 是一个序列化字段。其值会随场景或 prefab 一起保存。在为正式版本构建前务必将其关闭——一个序列化的 `true` 会在发布版本中静默禁用所有实时情绪响应。
{% endhint %}

### 第一线排查

当情绪表现不符合预期时，请按顺序执行此检查清单。大多数问题会在第 1 步或第 2 步解决。

{% stepper %}
{% step %}

#### 检查 Profile 字段

选择你 NPC 的根 GameObject。在 `ConvaiEmotionController` 组件上，确认 **Profile** 字段不是空的。

* **空** → 拖入一个 `ConvaiEmotionProfile` 资源。为了快速测试，请使用随附的 `ConvaiSamplesShared_EmotionProfile` 来自 `Packages / Convai SDK for Unity / SamplesShared / Resources / Embodiment / Modules / Emotion`。没有 Profile，管道就不会运行。
* **已分配** → 继续下一步。
  {% endstep %}

{% step %}

#### 在 Play Mode 中查看 DominantScore

按 **播放**，与角色对话，并观察 **Current → 主导分数** 在 `ConvaiEmotionController` 检视面板。

* **分数是否升至 0 以上** → 管道正在接收服务器信号。问题出在输出绑定。跳到第 4 步。
* **分数保持为 0** → 控制器没有接收到情绪信号。继续第 3 步。
  {% endstep %}

{% step %}

#### 检查 Lock Emotion 和组件位置

有两个常见原因会阻止信号到达累加器：

1. **Lock Emotion 已勾选** → 将其禁用。控制器在锁定时会丢弃所有服务器事件。
2. **组件位于错误的 GameObject 上** → `ConvaiEmotionController` 必须位于 **同一个根 GameObject** 与 Embodiment 组件相同的位置。若放在子对象或其他 NPC 上，它将无法从正确的角色会话接收情绪事件。

如果都不是，验证角色是否已处于活动连接状态——在情绪信号到达之前，它应先能在 Console 中对语音做出响应。
{% endstep %}

{% step %}

#### 检查输出槽填充情况

打开 `ConvaiEmotionProfile` 资源。如果这两个 **Blendshape Binding** 是位于 **Animator Binding** 列表都为空，管道会在内部运行，但不会写入任何地方—— `DominantScore` 会更新，但不会发生面部移动。

至少添加一个 `EmotionSlotBinding` 且具有有效的 `emotionLabel` 以及一个你角色上存在的 blendshape 名称或 Animator 参数。参见 [情绪输出绑定](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/output-bindings.md).
{% endstep %}

{% step %}

#### 验证 blendshape 名称和槽位标签

如果 `DominantScore` 会更新，但脸部仍然不动：

1. 选择你角色的 mesh GameObject → Inspector → **Skinned Mesh Renderer** → 展开 **BlendShapes**.
2. 将准确的 blendshape 名称复制到槽位的 **Blendshape Names** 字段中。名称是 **区分大小写**.
3. 确认槽位的 **Emotion Label** 字段使用 **规范** 分类标签（例如 `"joy"`，不是服务器别名 `"快乐"`）。绑定会与规范标签匹配——别名永远不会解析成功。
   {% endstep %}
   {% endstepper %}

{% hint style="success" %}
完成检查清单后，如果 **Current → 主导分数** 在对话过程中升至 0 以上且 blendshape 发生变化，那么管道就是正常的。
{% endhint %}

### 常见问题速查

| 症状                                                         | 可能原因                                            | 修复                                                                   |
| ---------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| **脸部不动；DominantScore 保持为 0**                               | 未分配 Profile                                     | 分配一个 `ConvaiEmotionProfile` 到 **Profile** 字段                         |
| **脸部不动；DominantScore 保持为 0**                               | Lock Emotion 已启用                                | 禁用 **锁定情绪** on `ConvaiEmotionController`                             |
| **脸部不动；DominantScore 保持为 0**                               | 组件位于错误的 GameObject                              | 移动 `ConvaiEmotionController` 到 NPC 的根 GameObject，与 Embodiment 组件放在一起 |
| **DominantScore 更新，但脸部未变化**                                | 输出槽为空                                           | 向 Profile 中至少添加一个具有有效情绪标签和 blendshape 名称的槽                           |
| **DominantScore 更新，但脸部未变化**                                | blendshape 名称不匹配                                | 将准确名称复制自 **Skinned Mesh Renderer → BlendShapes**；名称区分大小写             |
| **DominantScore 更新，但脸部未变化**                                | 槽位 `emotionLabel` 使用服务器别名                       | 使用规范标签（`"joy"`，而不是 `"快乐"`）在槽位的 **Emotion Label** 字段                  |
| **DominantScore 更新，但脸部未变化**                                | `weightMultiplier` 或 `fullBlendshapeWeight` 为 0 | 在槽位中将两者都设置为非零值                                                       |
| **特定情绪始终不出现；角色保持中性**                                       | 服务器标签不在分类体系中；静默回退到中性                            | 在自定义分类体系中，将服务器标签作为别名添加到最接近的规范条目                                      |
| **说话时 LipSync 停止工作**                                       | 标记了非口部 blendshape `isMouthShape = true`         | 设置 `isMouthShape = false` 用于眉毛、眼睛、脸颊和上半脸形状                           |
| **角色在整个会话中保持一种表情**                                         | `lockEmotion` 序列化为 `true` 在场景或 prefab 中         | 禁用 **锁定情绪**；保存场景（**Ctrl+S** / **Cmd+S**)                             |
| **生产构建中没有情绪响应**                                            | `lockEmotion` 在构建前保持启用                          | 禁用 **锁定情绪** 在构建前；在 Inspector 中按每个 prefab 实例进行验证                      |
| **重新打开项目后，Profile 更改恢复原状**                                 | 正在编辑捆绑的只读包资源                                    | 复制该资源（**Ctrl+D** / **Cmd+D**），将副本移动到 `Assets/`，将副本分配给                |
| **`OnEmotionChanged` on `ConvaiCharacterEventRelay` 从不触发** | 角色引用未解析                                         | 启用 **自动解析角色**，或分配 `ConvaiCharacter` 在 **角色** 字段                      |
| **`[EmotionTaxonomyAsset]` Console 中的警告**                  | 自定义分类体系没有中性条目，或有多个中性条目                          | 设置 `IsNeutral = true` 到恰好一个分类条目上                                     |

### 未知服务器标签——静默回退到中性

**症状：** 服务器发送的某种情绪从未出现在角色身上。脸部会像没有信号到达一样回到中性。

**原因：** 当服务器发送的标签与当前分类体系中的任何规范标签或别名都不匹配时， `TryResolve` 返回 `false` 控制器会静默使用中性描述符。与 blendshape 槽中的名称不匹配不同，这种失败 **不会产生控制台警告** ——管道会正常继续，每一帧都写入中性分数。

**如何检测：**

1. 在 Play Mode 下，展开 **Current → 全部分数** 在 `ConvaiEmotionController` Inspector。如果你期望看到的某种情绪得分恰好为 0.0，而对话明显需要它，那么服务器标签很可能没有解析成功。
2. 启用 `lockEmotion` 在 Inspector 中，将 **锁定情绪标签** 设置为你期望的规范标签（例如 `“期待”`），并确认 blendshape 槽已激活。如果激活了，则输出绑定是正确的——只是该标签下的信号始终没有从服务器到达。

**修复：** 打开你的自定义分类体系资源（如果使用内置默认值，则创建一个），并将服务器标签作为别名添加到语义最接近的条目。例如，如果服务器发送 `“excited”` 而它应该映射到以下视觉槽位： `“期待”`，则添加 `“excited”` 到 **别名** 列表中的 `anticipation` 条目。参见 [情绪分类体系](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/emotion-taxonomy.md) 以了解如何创建和分配自定义分类体系。

**验证：** 在 Play Mode 下，观察 **Current → 主导标签** 是位于 **Current → 全部分数** ——当服务器发送先前无法解析的标签时，预期情绪现在应高于 0 分。

### blendshape 名称不匹配

**症状：** `Current.DominantScore` 在 Play Mode 下更新正确，但角色的脸部视觉上没有变化。

**原因：** 中的 blendshape 名称 `EmotionSlotBinding` 与上的名称不完全匹配 `SkinnedMeshRenderer`.

**修复：**

1. 在 Hierarchy 中选择你角色的 mesh GameObject。
2. 在 Inspector 中滚动到 **Skinned Mesh Renderer** 组件。
3. 展开 **BlendShapes** 部分开始。
4. 将那里的准确名称复制到槽位的 **Blendshape Names** 字段中。名称区分大小写，必须完全匹配——包括下划线、空格和大小写。

**验证：** 在 Play Mode 下，观察 Inspector 中的该对象的 blendshape 值 `SkinnedMeshRenderer`。当 `DominantScore` 上升时，它应发生变化。

{% hint style="info" %}
如果角色有多个 `SkinnedMeshRenderer` 组件（身体、头部和牙齿作为独立 mesh），blendshape 绑定会指向与 Embodiment 合成器注册的 mesh。复制名称前，请确认你的 Embodiment 组件的 rig 绑定引用的是哪个 mesh。
{% endhint %}

### 情绪激活时 LipSync 失效

**症状：** 当角色说话时，由 LipSync 驱动的口型不再工作，或者情绪形状会意外抑制音素形状。

**原因：** 一个或多个 blendshape 槽具有 `isMouthShape = true` 用于会变形眉毛、眼睛或脸颊而不是嘴唇或下颌的形状。这些形状会通过口部合成层路由——也就是 LipSync 在说话时写入的同一层——从而导致它们干扰音素输出。

**修复：** 打开 `ConvaiEmotionProfile` 资源。在每个 **Blendshape Binding** 槽位中，将 `isMouthShape = true` **仅** 用于会变形嘴唇、下颌或下巴的形状。眉毛上扬、眯眼、鼓脸以及上半脸形状应使用 `isMouthShape = false`.

**验证：** 在 Play Mode 下，与角色说话——口部形状应在说话时正确动画，同时由情绪驱动的眉毛和眼睛形状继续同步更新。

### 表情冻结——角色忽略对话

**症状：** NPC 在整个会话中保持单一表情，从不对 AI 情绪信号做出反应。

**原因：** `lockEmotion` 被序列化为 `true` 在场景或预制体中——这是 Inspector 预览遗留的常见创作产物。

**修复：**

1. 选择 NPC 的根 GameObject。
2. 在 `ConvaiEmotionController`，禁用 **锁定情绪**.
3. 保存场景（**Ctrl+S** / **Cmd+S**).

如果你有多个 NPC prefab，请逐个检查——除非显式覆盖，否则该字段会按每个 prefab 实例保留。

**验证：** 在 Play Mode 下， **Current → 主导标签** 应随着对话的发展而变化。

{% hint style="danger" %}
始终验证 **锁定情绪** 为 `false` 在为正式版本构建之前。一个序列化的 `true` 值会在发布版本中静默禁用所有实时情绪响应，并且不会产生运行时错误。
{% endhint %}

### Profile 更改未保存

**症状：** 你在 Emotion Profile 资源上编辑设置，但在重新打开项目或返回 Inspector 时更改会回退。

**原因：** 你正在编辑包内捆绑的只读资源。Unity package 内的资源无法修改。

**修复：**

1. 选择 `ConvaiSamplesShared_EmotionProfile` 在 Project 窗口中。
2. 复制它（**Ctrl+D** / **Cmd+D**).
3. 将副本移动到你自己的 `Assets/` 文件夹。
4. 在 `ConvaiEmotionController`，分配副本而不是原始文件。

**验证：** 在副本上编辑一个值并重新打开 Inspector——更改应会保留。

### ConvaiCharacterEventRelay 的 OnEmotionChanged 不触发

**症状：** 你将一个 Unity Event 绑定到 **情绪变化时** on `ConvaiCharacterEventRelay`，但在 Play Mode 下从不触发。

**检查清单：**

1. **角色引用：** 任一 **自动解析角色** 已启用，并且一个 `ConvaiCharacter` 位于同一个 GameObject 上，或者你已手动分配了一个 `ConvaiCharacter` 在 **角色** 字段。如果两者都不满足，中继器会记录配置警告并保持非活动状态。
2. **组件已启用：** 确认 `ConvaiCharacterEventRelay` 组件已启用（Inspector 标题栏中的复选框已勾选）。
3. **订阅时机：** 中继器仅在 Convai 会话建立后才会触发。在 `OnEnable` 中订阅，并在 `OnDisable` 中取消订阅，以从组件激活的那一刻起捕获所有事件。
4. **会话已激活：** 在测试情绪回调之前，确认角色能正常响应语音。

**验证：** 在 Play Mode 下与角色说话——每当新的情绪信号到达时，UI 或回调目标都应更新。

### 情绪分数可见，但未写入输出绑定

**症状：** `ConvaiEmotionController.Current.DominantScore` 在 Play Mode 下更新正确，但 blendshape 和 Animator 参数都没有变化。

**检查清单：**

1. 确认 **Blendshape Binding** 或 **Animator Binding** Profile 中的列表不为空。
2. 确认 `emotionLabel` 每个槽位中的……都匹配一个 **规范** 分类标签——使用 `"joy"`，不是服务器别名 `"快乐"`.
3. 对于 Animator 绑定，确认该参数名称存在作为一个 **Float** 在 Animator Controller 中，并且 Animator 组件与……位于同一个 GameObject 上 `ConvaiEmotionController`.
4. 请确认 `weightMultiplier` 大于 0，并且 `fullBlendshapeWeight` 每个槽位都大于 0。

**验证：** 在 Inspector 中将情绪锁定为一个规范标签，并确认 blendshape 或 Animator 参数有响应——这能将问题范围缩小到绑定配置，而不是信号路径。

### Console 日志参考

以下消息会从情绪系统出现在 Unity Console 中。

| 日志消息                                                                                           | 组件                        | 含义                                                                                                                     |
| ---------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `[ConvaiEmotionController] 忽略了一个没有 character id 的情绪事件。按角色范围的情绪事件必须包含 character id，以避免跨角色表情串扰。` | `ConvaiEmotionController` | 收到一个没有 character ID 的情绪事件。这在多 NPC 场景中很常见，因为事件会全局广播。确保每个 NPC 都有唯一的 **角色 ID** 设置在其 `ConvaiCharacter` 组件上。每个控制器生命周期只记录一次。 |
| `[EmotionTaxonomyAsset] 没有条目标记为中性；已合成“neutral”回退。将恰好一个条目标记为中性基线以抑制此警告。`                        | `EmotionTaxonomyAsset`    | 自定义分类体系资源中没有带有 **IsNeutral** = true 的条目。系统会合成一个回退中性值，以便管道运行。将 `IsNeutral = true` 设置在恰好一个条目上以抑制此警告。                     |
| `[EmotionTaxonomyAsset] 没有条目设置 IsNeutral。运行时将使用合成的“neutral”；请将一个条目标记为中性基线。`                    | `EmotionTaxonomyAsset`    | 同上——在 Inspector 中触发（`OnValidate`）当你在 Edit Mode 下保存分类体系资源时触发。通过将一个条目标记为中性基线来修复。                                         |
| `[EmotionTaxonomyAsset] 有 N 个条目标记为 IsNeutral；只会使用第一个。请恰好标记一个中性基线。`                             | `EmotionTaxonomyAsset`    | 多个分类体系条目具有 **IsNeutral** = true。只会使用第一个。移除 `IsNeutral` 除一个条目之外所有条目的标志。                                                 |

{% hint style="info" %}
存在 **没有控制台警告** 当服务器发送无法识别的情绪标签时。 `TryResolve` 会静默回退到中性描述符。如果某个预期情绪始终未出现在角色身上，请参见 [未知服务器标签——静默回退到中性](#unknown-server-labels-silent-neutral-fallback) 上方。
{% endhint %}

### 表情无响应——决策树

```mermaid
flowchart TD
    A[脸部未对情绪响应] --> B{已分配 Profile？}
    B -- No --> C[将 ConvaiEmotionProfile\n分配到 Profile 字段]
    B -- Yes --> D{对话过程中 DominantScore 上升？}
    D -- No --> E{Lock Emotion 已启用？}
    E -- Yes --> F[在 ConvaiEmotionController 上\n禁用 Lock Emotion]
    E -- No --> G{控制器在根\nGameObject 上？}
    G -- No --> H[将控制器移动到 NPC 根\nGameObject，与 Embodiment 一起放置]
    G -- Yes --> I[验证角色会话是否\n处于活动状态 - 先测试语音]
    D -- Yes --> J{输出槽\n已填充？}
    J -- No --> K[添加带有效标签的 BlendshapeEmotionBinding\n槽]
    J -- Yes --> L{Blendshape 名称\n完全匹配？}
    L -- No --> M[从\nSkinnedMeshRenderer BlendShapes 复制准确名称]
    L -- Yes --> N{emotionLabel 是\n规范标签，而不是别名？}
    N -- No --> O[使用规范标签：\n“喜悦”而不是“快乐”]
    N -- Yes --> P{weightMultiplier 和\nfullBlendshapeWeight > 0？}
    P -- No --> Q[在槽位中设置非零权重\n值]
    P -- Yes --> R[检查 isMouthShape 标志\n以及 LipSync 合成器层]
```

{% content-ref url="/pages/931fe5969b6c7b83aac82771a8aedc0f94f896d1" %}
[情绪输出绑定](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/output-bindings.md)
{% endcontent-ref %}

{% content-ref url="/pages/830c8a41ce176512408273566b88a4c868c56a59" %}
[情绪分类法](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/emotion-taxonomy.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/troubleshooting-and-diagnostics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.