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

# 故障排查与诊断

## 诊断并解决情绪问题

大多数情绪问题可归为三类之一：完全没有可视输出、分数在更新但面部不动，或者事件和脚本回调未触发。本页先介绍内置 Inspector 检查界面，然后依次讲解结构化的第一线排查清单、快速参考表、按问题细分的详细说明、控制台日志参考，以及针对最常见故障路径的决策树。

## 检查实时状态

`ConvaiEmotionController` 在 Play Mode 下无需任何额外工具即可在 Inspector 中显示完整的流水线状态。

| 需要关注什么        | 在哪里找到它                                           | 它告诉你什么                                      |
| ------------- | ------------------------------------------------ | ------------------------------------------- |
| **当前 → 主导标签** | `ConvaiEmotionController` Play Mode 中的 Inspector | 当前哪种规范情绪处于主导地位。 `"neutral"` 表示没有有效信号。       |
| **当前 → 主导分数** | `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**

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

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

{% step %}
**检查 Lock Emotion 和组件位置**

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

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

如果两者都不适用，请确认角色已实际连接——在情绪信号到来之前，它应当先能在 Console 中对语音做出响应。
{% endstep %}

{% step %}
**检查输出槽是否已填充**

打开 `ConvaiEmotionProfile` 资源。如果两者都 **Blendshape 绑定** 是位于 **Animator 绑定** 列表都为空，流水线会在内部运行，但没有写入目标—— `DominantScore` 会更新，但不会发生面部动作。

至少添加一个 `EmotionSlotBinding` 且具有有效的 `emotionLabel` 以及一个存在于角色上的 blendshape 名称或 Animator 参数。参见输出绑定。
{% endstep %}

{% step %}
**验证 blendshape 名称和槽标签**

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

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

## 常见问题

| 症状                                                         | 可能原因                                            | 修复                                                                     |
| ---------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
| **脸完全不动；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 | 将两者都设置为槽中的非零值                                                          |
| **特定情绪从未出现；角色始终保持中立**                                      | 服务器标签不在 taxonomy 中；静默回退为中立                      | 在自定义 taxonomy 中，将服务器标签作为别名添加到最接近的规范条目                                  |
| **说话时 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 中**                 | 自定义 taxonomy 没有中立条目，或者有多个中立条目                   | 设置 `IsNeutral = true` 在且仅在一个 taxonomy 条目上                              |

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

**症状：** 服务器发送的某种情绪从未出现在角色上。面部会回到中立，就像没有收到信号一样。

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

**如何检测：**

1. 在 Play Mode 中展开 **当前 → 所有分数** 在 `ConvaiEmotionController` Inspector。如果你期望看到的情绪分数正好是 0.0，而对话内容明显应触发它，那么服务器标签很可能没有解析成功。
2. 启用 `lockEmotion` 在 Inspector 中，将 **锁定的情绪标签** 设置为你期望的规范标签（例如 `“anticipation”`），并确认 blendshape 槽被激活。如果是这样，说明输出绑定是正确的——只是该标签下的信号根本没有从服务器传来。

**修复：** 打开你的自定义 taxonomy 资源（如果使用内置默认值则创建一个），并将服务器标签作为别名添加到语义最接近的匹配项。例如，如果服务器发送 `“excited”` 并且它应映射到视觉槽 `“anticipation”`，则添加 `“excited”` 添加到 **Aliases** 列表中的 `anticipation` 条目。有关如何创建并分配自定义 taxonomy，请参见 Emotion Taxonomy。

## Blendshape 名称不匹配

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

**原因：** 其中的 blendshape 名称 `EmotionSlotBinding` 与上的名称不完全一致 `SkinnedMeshRenderer`.

**修复：**

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

{% hint style="info" %}
如果角色有多个 `SkinnedMeshRenderer` 组件（身体、头部和牙齿分别作为独立网格），blendshape 绑定会指向在 Embodiment compositor 中注册的网格。在复制名称之前，请确认 Embodiment 组件的 rig 绑定引用的是哪一个网格。
{% endhint %}

## 当情绪激活时 LipSync 失效

**症状：** 当角色说话时，由 LipSync 驱动的口型停止工作，或者情绪形状意外压制了音素形状。

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

**修复：** 打开 `ConvaiEmotionProfile` 资源。在每个 **Blendshape 绑定** 槽中，将 `isMouthShape = true` **仅** 用于变形嘴唇、下颌或下巴的形状。抬眉、眯眼、鼓脸和上脸部形状应当设置为 `isMouthShape = false`.

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

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

**原因：** `lockEmotion` 被序列化为 `true` 在场景或 prefab 中——这是 Inspector 预览留下的常见编辑遗留物。

**修复：**

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

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

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

## Profile 更改没有保存

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

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

**修复：**

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

## ConvaiCharacterEventRelay OnEmotionChanged 不触发

**症状：** 你将一个 Unity Event 连接到 **On Emotion Changed** on `ConvaiCharacterEventRelay`，但在 Play Mode 中它始终不触发。

**清单：**

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

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

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

**清单：**

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

## 控制台日志参考

以下消息会从 Emotion 系统显示在 Unity Console 中。使用此表了解每条消息的含义以及下一步该做什么。

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

{% hint style="info" %}
这里没有 **控制台警告** 当服务器发送无法识别的情绪标签时。 `TryResolve` 会静默回退到中立描述符。如果预期的情绪从未出现在角色上，请参见上面的“未知服务器标签——静默中立回退”。
{% endhint %}

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

```mermaid
flowchart TD
    A[面部未响应情绪] --> B{已分配 profile？}
    B -- 否 --> C[将 ConvaiEmotionProfile<br/>分配到 Profile 字段]
    B -- 是 --> D{对话期间 DominantScore<br/>是否上升？}
    D -- 否 --> E{Lock Emotion 已启用？}
    E -- 是 --> F[在 ConvaiEmotionController 上<br/>禁用 Lock Emotion]
    E -- 否 --> G{控制器是否位于根<br/>GameObject 上？}
    G -- 否 --> H[将控制器移动到 NPC 根<br/>GameObject，与 Embodiment 放在一起]
    G -- 是 --> I[确认角色会话已<br/>激活——先测试语音]
    D -- 是 --> J{输出槽<br/>已填充？}
    J -- 否 --> K[添加带有效标签的 BlendshapeEmotionBinding<br/>槽]
    J -- 是 --> L{Blendshape 名称<br/>是否完全匹配？}
    L -- 否 --> M[从 SkinnedMeshRenderer BlendShapes<br/>复制准确名称]
    L -- 是 --> N{emotionLabel 是否为<br/>规范标签，而非别名？}
    N -- 否 --> O[使用规范标签：<br/>“joy” 而不是 “happy”]
    N -- 是 --> P{weightMultiplier 和<br/>fullBlendshapeWeight > 0？}
    P -- 否 --> Q[在槽中设置非零权重<br/>值]
    P -- 是 --> R[检查 isMouthShape 标志<br/>以及 LipSync compositor 层]
```

## 结论

大多数 Emotion 问题可归结为四个根本原因之一：缺少 profile、输出槽为空或配置错误、意外序列化的 `lockEmotion`，或者 blendshape 名称不匹配。先观察 `Current.DominantScore` 在 Play Mode 中——如果它在更新，说明流水线是健康的，问题出在输出绑定；如果它一直为零，就倒查 profile、锁定状态和组件位置。使用“常见问题”表进行快速查找，使用“控制台日志参考”来解读警告消息；当原因不够明确时使用决策树。


---

# 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/unity-plugin-beta-overview/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.