> 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/emotion-taxonomy.md).

# 情绪分类法

分类法将 Convai 后端的原始情绪字符串转换为系统其余部分使用的规范标签。当服务器发送 `"快乐"`时，该分类法会将该别名解析为 `"joy"` ，这样累加器和输出绑定——它们以规范标签为键——就能准确知道要更新哪个分数。SDK 自带一个受 Plutchik 启发的九种情绪默认配置；当你需要不同的词汇或额外的服务器别名时，可以编写自定义 `EmotionTaxonomyAsset` 分类法。

### 内置 Plutchik 分类法

当 `分类法` 字段在 `ConvaiEmotionProfile` 上留空时，系统会在运行时合成以下集合。该默认配置涵盖 Convai 后端当前输出的所有情绪，无需创建任何资源。

| 规范标签           | 服务器别名                      | 默认口型影响 |
| -------------- | -------------------------- | ------ |
| `中性`           | `平静`, `空闲`                 | 0.0    |
| `喜悦`           | `快乐`, `幸福`, `狂喜`, `宁静`     | 0.6    |
| `信任`           | `接受`, `钦佩`                 | 0.3    |
| `恐惧`           | `害怕`, `忧虑`, `恐怖`, `害怕的`    | 0.4    |
| `惊讶`           | `惊愕`, `分心`, `惊讶的`          | 0.5    |
| `悲伤`           | `悲伤的`, `沉思`, `悲痛`          | 0.3    |
| `厌恶`           | `感到厌恶`, `憎恶`, `无聊`, `感到无聊` | 0.4    |
| `愤怒`           | `愤怒的`, `恼怒`, `狂怒`          | 0.55   |
| `anticipation` | `兴趣`, `警惕`                 | 0.45   |

**默认口型影响** 是每种情绪的提示值（0–1），用于告诉面部 blendshape 合成器：当角色未在说话时，情绪驱动的嘴部形状应贡献多少。在主动说话期间，LipSync 会根据音素数据覆盖嘴部 blendshape；在非说话状态下，这个值控制情绪姿态对嘴部区域的影响强度。

### 别名解析的工作方式

后端每次输出一种情绪时，控制器都会调用 `IEmotionTaxonomy.TryResolve(serverLabel, out EmotionDescriptor descriptor)`。解析器会先检查规范标签，然后再遍历所有条目的完整别名列表。

* 如果标签解析成功，流水线的各个环节都会使用对应的规范标签和描述符。
* 如果该标签 **不是** 无法解析，控制器会静默回退到中性描述符。 **不会输出控制台警告。** 流水线会继续正常运行，每一帧都写入中性分数。

**例如：** 后端发送 `"快乐"` → `TryResolve` 在 `"快乐"` 的别名列表中找到 `喜悦` 条目 → 累加器会将 `"joy"`.

{% hint style="warning" %}
当服务器发送的标签不在分类法中时，失败是静默的——不会出现控制台警告，也不会记录错误。角色会简单地回到中性状态，仿佛没有收到任何情绪信号。如果某个特定情绪从未出现在你的角色上，很可能是服务器标签未被当前分类法覆盖。请参见 [情绪故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/troubleshooting-and-diagnostics.md#unknown-server-labels-silent-neutral-fallback) 了解如何检测并修复这一问题。
{% endhint %}

### 创建自定义分类法资源

在 Project 窗口中，右键单击你的 `Assets/` 文件夹，并选择：

**Create → Convai → Embodiment → Emotion Taxonomy**

一个名为 `EmotionTaxonomy` 的新资源会出现。选中它即可在 Inspector 中编辑条目列表。

#### EmotionTaxonomyEntry 字段

| 字段                      | 类型             | 说明                                                                                  |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------- |
| `label`                 | `string`       | 在整个流水线中使用的规范小写标签（例如 `"joy"`）。在分类法中必须唯一。                                             |
| `aliases`               | `List<string>` | 所有应解析到此条目的服务器端字符串（例如 `"快乐"`, `"happiness"`).                                        |
| `complements`           | `List<string>` | 在激活时会抑制中性轮替的情绪的规范标签。如果某个互补情绪当前分数高于零，中性轮替器会跳过该条目的淡出循环。在内置分类法中， `喜悦` 是位于 `信任` 彼此互为互补。 |
| `defaultMouthInfluence` | `float` （0–1）  | 供 LipSync 混合使用的嘴部影响提示。参考上面的内置表格中的值。                                                 |
| `isNeutral`             | `bool`         | 将此条目标记为分类法的中性基线——即累加器的衰减目标，以及中性轮替期间的目标状态。                                           |

{% hint style="warning" %}
**必须且仅有一个条目标记为 `isNeutral = true`.** 。累加器将中性条目用作其衰减锚点。如果没有条目标记为中性，或者有多个条目标记为中性，系统会记录警告并合成一个回退项——但表达在运行时不会正确稳定下来。控制台警告消息如下：

* `[EmotionTaxonomyAsset] 未标记任何中性条目；已合成 'neutral' 回退项。` — 未找到中性条目
* `[EmotionTaxonomyAsset] 有 N 个条目标记为 IsNeutral；将仅使用第一个。` — 找到多个中性条目
  {% endhint %}

#### 将自定义分类法分配给配置文件

1. 打开你的 `ConvaiEmotionProfile` 资源。
2. 拖入自定义 `EmotionTaxonomyAsset` 到 **分类法** 字段中。
3. 控制器会在下次应用配置文件时拾取新的分类法——在 Play Mode 中会立即生效，而在 Edit Mode 中也会立即生效，因为 `ConvaiEmotionController` 继承自 `[ExecuteAlways]` 其基类。

### 何时创建自定义分类法

内置的 Plutchik 集合涵盖了 Convai 后端当前发送的所有情绪。当以下情况出现时，创建自定义分类法才值得：

* 你的 Convai 配置使用了与内置别名不同的自定义情绪标签。
* 你想使用不同的概念模型——例如 Ekman 的六种基本情绪——并将多个服务器别名映射到更少的规范桶中。
* 你想调整 `defaultMouthInfluence` 特定情绪的值，以更好地适配角色的骨骼绑定。
* 你需要定义 `complements` 关系，以防止中性轮替在你的应用流程中打断特定情绪组合。

### 下一步

{% content-ref url="/pages/39d161d99d04e6ca98725c740d134ccb5eac9e73" %}
[情绪脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/65ec9decd2473b72bc06bf3c946f3008c8528dda" %}
[排查情绪问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/emotion/troubleshooting-and-diagnostics.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/emotion-taxonomy.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.