> 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/conversation-flow/reference.md).

# 对话流程参考

Conversation Flow 控制器公共 API、其返回的对话状态读取值，以及配置文件资源上每个时序字段的完整参考。

公共对话流程接口参考： `ConvaiConversationFlowController`， `DialogueStateReading` 它返回的结构体，以及其中的每个字段 `ConvaiConversationFlowProfile`。关于每个 `DialogueState` 值的含义，请参见 [对话状态](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/dialogue-state.md)。跨模块约定 `IConversationFlowSource` 是内部内容，不属于此接口范围——请改为阅读控制器自身的成员。

***

### `ConvaiConversationFlowController`

`ConvaiConversationFlowController` (`密封类：ConvaiCharacterModule<ConvaiConversationFlowProfile>`, `[AddComponentMenu("Convai/具身/对话流程")]`, `[DisallowMultipleComponent]`) 是该角色唯一手工编写的来源 `DialogueState`。当另一个模块需要时，Convai 会自动添加它——请参见 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md#convai-adds-it-automatically-when-needed).

#### 属性

| 成员        | 类型                     | 说明                                                         |
| --------- | ---------------------- | ---------------------------------------------------------- |
| `Current` | `DialogueStateReading` | 角色当前的对话状态读数。返回 `DialogueStateReading.Idle` 在控制器首次 tick 之前。 |

#### 事件

| 事件    | 签名                                | 在……时触发                       |
| ----- | --------------------------------- | ---------------------------- |
| `已变更` | `事件 Action<DialogueStateReading>` | 该读数的 `主` 状态变化。仅在混合进度变化时不会触发。 |

***

### `DialogueStateReading`

`DialogueStateReading` (`readonly struct`, `SDK/Domain/Embodiment/Readings/DialogueStateReading.cs`) 是由……暴露的不可变快照 `Current` 并传递给 `已变更`。读数始终描述两个状态之间的混合，而不是硬切换，因此消费者可以交叉淡入淡出其输出，而不是突变。

| 字段                | 类型              | 说明                                                                         |
| ----------------- | --------------- | -------------------------------------------------------------------------- |
| `主`               | `DialogueState` | 当前权威状态。                                                                    |
| `BlendTo`         | `DialogueState` | 正在朝其混合的状态。等同于 `主` ，当没有过渡进行中时。                                              |
| `BlendWeight`     | `float`         | 从……开始的线性混合权重 `主` 移动到 `BlendTo`，被限制在 `[0, 1]`. `0` 表示完全处于 `主`; `1` 表示过渡已完成。 |
| `TimeInState`     | `float`         | 角色已处于……中的秒数 `主`，被限制在 `0` 或以上。                                              |
| `EnergyLevel`     | `float`         | 归一化能量，范围为 `[0, 1]` 供手势调度器和微行为强度使用——在……期间更高 `说话中` 和 `反应中`，在……期间更低 `空闲`.     |
| `IsTransitioning` | `布尔值`           | `是` 当 `主` 和 `BlendTo` 不同，并且 `BlendWeight` 大于 `0`.                          |

`DialogueStateReading.Idle` 是一个静态属性，返回角色在……中的稳态读数 `空闲` — `主` 和 `BlendTo` 两者 `空闲`, `BlendWeight` `0`, `TimeInState` `0`, `EnergyLevel` `0`.

***

### `ConvaiConversationFlowProfile`

`ConvaiConversationFlowProfile` (`密封类：ScriptableObject`, `[CreateAssetMenu(menuName = "Convai/具身/对话流程配置")]`, `SDK/Modules/ConversationFlow/Profiles/ConvaiConversationFlowProfile.cs`) 负责定义状态机的时序参数。将其分配给控制器的 **流程配置** 字段；如果未分配，控制器将使用下面的值作为内置默认值运行。

#### 过渡

| 字段     | 范围      | 默认     | 说明                                                |
| ------ | ------- | ------ | ------------------------------------------------- |
| 过渡持续时间 | `0`–`2` | `0.25` | 两个状态之间线性交叉淡入淡出的持续时间（秒）——读取回来的值为 `BlendWeight` 进度。 |

#### 对话节拍

| 字段       | 范围         | 默认     | 说明                                  |
| -------- | ---------- | ------ | ----------------------------------- |
| 思考最短保持时间 | `0`–`3`    | `0.25` | 角色在……中停留的最短时长 `思考中` ，在玩家确认轮次之后。     |
| 思考最长保持时间 | `0.5`–`10` | `2.5`  | 角色在……中停留的最长时长 `思考中` 然后回落到 `关注中`.    |
| 聆听宽限期    | `0`–`2`    | `0.3`  | 玩家停止说话但未确认轮次后，在角色从……继续之前的宽限期 `关注中`. |
| 稳定持续时间   | `0`–`3`    | `0.6`  | 角色在后轮次稳定节拍中停留的持续时间，之后返回到 `空闲`.      |
| 返回空闲延迟   | `0`–`120`  | `60`   | 在角色从……冷却下来之前的不活动秒数 `关注中` 回到 `空闲`.   |
| 中断冻结持续时间 | `0`–`2`    | `0.25` | 角色冻结在……中的持续时间 `被打断` 在被打断后。          |

{% hint style="info" %}
如果 **思考最短保持时间** 设置高于 **思考最长保持时间** 在 Inspector 中时，资源会提高 **思考最长保持时间** 以匹配 **思考最短保持时间** 会自动，因此 Inspector 中显示的两个值始终与角色在运行时的行为一致。
{% endhint %}

#### 能量

| 字段     | 范围        | 默认    | 说明                                                    |
| ------ | --------- | ----- | ----------------------------------------------------- |
| 说话基础能量 | `0.1`–`1` | `0.6` | 在……期间发出的基础能量水平 `说话中`，由……读取 `EnergyLevel` 并用于缩放肢体语言强度。 |

#### 固定行为

配置文件中的三个字段—— `noticeYouLocally`, `stopWhenTheVoiceStops`以及 `voiceEndHold` ——是 `私有的` 并且配置文件的 Inspector 不会显示它们，因此任何读取器都无法通过 Inspector 或脚本修改这三个字段中的任何一个。它们作为固定行为随包提供，对所有角色都相同：

* 一旦角色获得本地证据表明你已经开始说话，它就会立刻作出反应，早于 Convai 自身确认它听到了你。
* 角色自己的声音一停止，这一说话轮次就结束，而不是等待 Convai 的轮次完成确认。
* 在控制器将沉默视为一轮结束之前，它会等待 `0.4` 秒，因为两句话之间的停顿听起来和结束没区别。此保持仅在角色没有 Lip Sync 读数时适用；当存在 Lip Sync 时，它会标记回应的结束，无需保持。

参见 [说话轮次如何结束](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md#how-a-speaking-turn-ends) 对于完整模型，这两种行为都属于其中的一部分。

***

### 下一步

{% content-ref url="/pages/e36846646869669757941fb114c42828a6d974ad" %}
[配置对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow/configure.md)
{% endcontent-ref %}

{% content-ref url="/pages/8922153d9c96476ab1f2a88254d25a41d45588ff" %}
[排查对话流程问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow/troubleshooting.md)
{% endcontent-ref %}

{% content-ref url="/pages/98cb5fe5ecdb3bff07eface0a87fc2b885cc0704" %}
[具身化脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/scripting-reference.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/conversation-flow/reference.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.