> 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/core-concepts/dialogue-state.md).

# 对话状态

了解具身化模块读取的八值对话状态，以判断角色是空闲、聆听还是说话中。

每个具身模块——注视、身体动画、肢体语言和情绪——都会读取同一个包含八个值的 `DialogueState` ，以了解角色在对话中处于哪个阶段。对话流程是唯一负责决定此值的模块；其他模块都只读取它。了解每种状态的含义，就能看懂其他具身模块的行为。

***

### 八种对话状态

`DialogueState` (`SDK/Domain/Embodiment/Semantics/DialogueState.cs`）是具身模块栈共用的标准对话阶段模型。

| 状态            | 值   | 在对话中的含义                                                                   |
| ------------- | --- | ------------------------------------------------------------------------- |
| `Idle`        | `0` | 角色当前未参与对话轮次。此时以闲置微动作——重心转移、环境注视——为主。                                      |
| `Listening`   | `1` | 玩家正在说话，角色正在专注倾听。角色会持续注视玩家，肢体语言倾向于身体前倾，情绪则保持接近中性。                          |
| `Attending`   | `2` | 角色正转向某个关注目标——例如，玩家即将开始一个对话轮次时——此时玩家尚未开口；或者角色在对话间隙保持积极参与的姿态，随后再逐渐回到环境闲置状态。 |
| `Thinking`    | `3` | 玩家已经说完，角色尚未回应。这一状态模拟自然的认知停顿：角色可能移开视线，微眼跳增多，眉毛上扬。                          |
| `Speaking`    | `4` | 角色当前正在说话。嘴部由 LipSync 控制，情绪和手势的强度则随语音能量变化。                                 |
| `Reacting`    | `5` | 重大事件发生后的短暂反应阶段，例如玩家输入出乎意料，或情绪强烈涌现。它允许模块播放一次性反应，同时不影响主要状态。                 |
| `Interrupted` | `6` | 角色在对话轮次中途被打断。此状态表现为短暂定格，随后迅速恢复平稳，再过渡回 `Attending`.                        |
| `Settling`    | `7` | 对话轮次结束后的冷却阶段：角色说完后，目光变得柔和，情绪逐渐消退至静息基调，然后交接至 `Attending`.                  |

这一模型有意设计得比粗略的“闲置／倾听／说话”划分更细致。每种状态都代表自然对话中的一个独立阶段，因此注视、肢体语言、情绪和身体动画可以各自生成可信的行为，而无须为彼此硬编码覆盖规则。

***

### 状态的负责方与读取方

`ConvaiConversationFlowController` (`SDK/Modules/ConversationFlow/Components/ConvaiConversationFlowController.cs`）是角色对话状态唯一由开发者定义的真实来源。其他具身模块都只读取该状态；它们不会重新定义或自行推断一套状态。

该控制器在其公共接口上公开两个成员：

| 成员        | 类型                                   | 说明                                                                                                                                                      |
| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Current` | `DialogueStateReading`               | 角色当前的状态读数：包含一个 `Primary` 状态、一个正在过渡到的 `BlendTo` 状态、一个 `BlendWeight` 、以秒为单位的 `[0, 1]`, `TimeInState` ，以及用于调整手势和微动作强度的归一化 `EnergyLevel` 、以秒为单位的 `[0, 1]` 。 |
| `Changed` | `event Action<DialogueStateReading>` | 状态读数发生变化时触发。                                                                                                                                            |

状态读数始终描述两个状态之间的混合，而不是瞬间切换，因此模块可以交叉淡化输出，而非突然跳变。当没有正在进行的过渡时， `Primary` 和 `BlendTo` 相等，且 `BlendWeight` 为 `0`.

***

### 控制器自动添加时

一个 `ConvaiConversationFlowController` 不一定总要手动添加。 `ConvaiBodyAnimationController` 会请求添加一个，因此，带有身体动画但未配置控制器的角色会自动获得一个，Convai 也会记录一条日志，说明角色名称和添加原因。自动添加的控制器与手动添加的控制器行为完全一致；如果内置的时序不适合你的角色，可以在之后进行配置。

其他模块不会请求添加控制器。凝视、身体语言和情绪模块会在对话状态可用时读取该状态，否则回退到 `Idle` 。因此，只有这些模块且没有身体动画的角色永远不会离开 `Idle`，行为也会显得呆板，无法对对话作出反应。如果你遇到这种情况，请自行添加 `ConvaiConversationFlowController` 。

{% hint style="info" %}
负责提供此状态的契约 `IConversationFlowSource`是包的 `internal` 实现。请读取 `ConvaiConversationFlowController.Current` 并订阅 `Changed` ——不要自行实现该接口。
{% endhint %}

***

### 后续步骤

{% content-ref url="/pages/491cfe5f38fba67eb46308256f5d4fa1ba67cda0" %}
[角色具身化](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/character-embodiment.md)
{% endcontent-ref %}

{% content-ref url="/pages/8eaf58d7e1fc1a2176b0c4b26425f595bc8e8851" %}
[资产所有权与写时复制](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.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/core-concepts/dialogue-state.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.
