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

# Emotion 分类体系

说明内置情绪集合、服务器标签如何映射到它，以及如何为角色编写自定义情绪分类体系。

该分类法将 Convai 的原始情绪字符串转换为 Emotion 模块其余部分使用的规范标签。当 Convai 发送 `"快乐"`时，分类法会将该别名解析为 `“joy”` ，这样以规范标签为键的累加器和表情管线就能准确知道要更新哪个分数。SDK 自带一个受 Plutchik 启发的九情绪默认设置；在以下情况创建一个自定义 `EmotionTaxonomyAsset` ，当你需要不同的词汇表或额外的服务器别名时。

### 内置分类法

当 `分类体系` 上的字段 `ConvaiEmotionProfile` 留空时，系统会在运行时生成以下集合。此默认设置涵盖 Convai 当前产生的所有情绪，无需创建任何资源。

| 规范标签      | 服务器别名                                     | 默认嘴部影响 |
| --------- | ----------------------------------------- | ------ |
| `neutral` | `平静`, `静止`                                | 0.0    |
| `喜悦`      | `快乐`, `快乐`, `狂喜`, `宁静`, `兴奋`, `热情`        | 0.6    |
| `信任`      | `接纳`, `钦佩`, `自信`, `安心`                    | 0.3    |
| `恐惧`      | `害怕`, `忧惧`, `惊恐`, `恐惧的`, `担心`, `焦虑`, `紧张` | 0.4    |
| `惊讶`      | `惊奇`, `分心`, `惊讶的`                         | 0.5    |
| `悲伤`      | `难过`, `沉思`, `悲痛`                          | 0.3    |
| `厌恶`      | `厌恶的`, `憎恶`, `无聊`, `无聊的`                  | 0.4    |
| `愤怒`      | `生气`, `恼怒`, `暴怒`                          | 0.55   |
| `期待`      | `兴趣`, `警觉`, `好奇`, `好奇心`, `渴望`, `充满希望`     | 0.45   |

**默认嘴部影响** 是一个按情绪设置的提示值（0–1），告诉面部合成器：当角色不说话时，由情绪驱动的嘴部形状应贡献多少。主动说话时，嘴部 blendshapes 由 LipSync 接管；在非说话状态下，此值控制情绪姿态对嘴部区域的影响强度。

内置集合中每个非中性条目还带有一个 **互补项** ——一种相关情绪，当 [情绪混合](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-profile.md#emotion-blending) 开启时显示。 `喜悦` 和 `信任` 彼此互为互补项； `恐惧` 和 `惊讶` 彼此互为； `悲伤` 互补项 `厌恶`; `厌恶` 互补项 `愤怒`; `愤怒` 互补项 `厌恶`; `期待` 互补项 `喜悦`.

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

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

* 如果标签解析成功，相应的规范标签和描述符会在整个管线中使用。
* 如果标签 **不** 无法解析，控制器会回退到中性描述符。 **不会生成控制台警告。** 管线会继续正常运行，并在每一帧写入中性分数。

**示例：** Convai 发送 `"快乐"` → `TryResolve` 在 `"快乐"` 的别名列表中找到 `喜悦` 条目 → 累加器会将目标分数设为 `“joy”`.

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

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

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

**创建 → Convai → 具身化 → 情绪分类法**

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

#### EmotionTaxonomyEntry 字段

| 字段                        | 类型             | 说明                                                                                                                                                                                      |
| ------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`                   | `字符串`          | 整个管线中使用的规范小写标签（例如 `“joy”`）。在该分类法内必须唯一。                                                                                                                                                  |
| `别名`                      | `List<string>` | 所有应解析到此条目的服务器端字符串（例如 `"快乐"`, `"快乐"`).                                                                                                                                                   |
| `互补项`                     | `List<string>` | 与该情绪自然搭配的情绪规范标签，当 [情绪混合](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-profile.md#emotion-blending) 开启时会以较低强度同时出现——例如 `喜悦` 带有一丝 `信任`。仅当角色配置文件启用混合时才会查询。 |
| `defaultMouthInfluence`   | `float` (0–1)  | 用于 LipSync 混合的嘴部影响提示值。参考值请见上方的内置表。                                                                                                                                                      |
| `isNeutral`               | `布尔值`          | 将此条目标记为该分类法的中性基线——面部在情绪之间回归的状态，也是累加器的衰减锚点。                                                                                                                                              |
| `useCustomDimensions`     | `布尔值`          | 启用后，此条目的 `效价`/`唤醒度`/`能动性`/`接近性` 字段将覆盖该标签的内置维度默认值。禁用时，这些值将从 `EmotionDimensionDefaults` 中已知标签的默认值解析。                                                                                      |
| `效价`, `唤醒度`, `能动性`, `接近性` | `float` （-1–1） | “ `EmotionDimensions` 此情绪所携带的维度：有多愉快、多激动、多有控制感，以及它是否会让角色朝向或远离引发它的事物。Gaze、Body Language 和 locomotion 会将其与类别标签一起作为共享调制信号使用。仅在 `useCustomDimensions` 是 `是`.                                |

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

* `[EmotionTaxonomyAsset] 此情绪词汇表未将任何情绪标记为中性，因此正在使用一个替代项。请仅在一个情绪上勾选“Is Neutral”——它就是面部在情绪之间回归的状态。` ——未找到中性条目
* `[EmotionTaxonomyAsset] 此词汇表中有 N 个情绪勾选了“Is Neutral”，仅使用第一个。请取消勾选其他项，以明确面部应回归到哪一个。` ——找到多个中性条目
  {% endhint %}

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

{% stepper %}
{% step %}

#### 打开配置文件资源

打开你的 `ConvaiEmotionProfile` 资源。
{% endstep %}

{% step %}

#### 分配分类法

将自定义 `EmotionTaxonomyAsset` 将第二个角色自己的 Character ID 从 **Taxonomy** 字段中。
{% endstep %}

{% step %}

#### 确认控制器已拾取它

控制器会在下次应用配置文件时拾取新的分类法——在 Play Mode 中会立即生效，在 Edit Mode 中也会立即生效，因为 `ConvaiEmotionController` 继承自 `[ExecuteAlways]` 其基类中的该特性。
{% endstep %}
{% endstepper %}

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

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

* 你的 Convai 配置使用了与内置别名不同的自定义情绪标签。
* 你想使用不同的概念模型——例如 Ekman 的六种基本情绪——并将多个服务器别名映射到更少的规范桶中。
* 你想调整 `defaultMouthInfluence` 特定情绪的值，以更好地适配你的角色绑定。
* 你需要定义 `互补项` 情绪混合的关系，或者编写 `效价`/`唤醒度`/`能动性`/`接近性` 与内置默认值不同的维度。

### 下一步

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

{% content-ref url="/pages/65ec9decd2473b72bc06bf3c946f3008c8528dda" %}
[排查情绪问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-taxonomy.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.