> 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`， `对话状态读数` 它返回的结构体，以及其上的每个字段 `ConvaiConversationFlowProfile`。关于每个 `对话状态` 值的含义，请参见 [对话状态](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/dialogue-state.md)。跨模块契约 `IConversationFlowSource` 是内部的，不属于该表面——请改为查看控制器自身的成员。

***

### `ConvaiConversationFlowController`

`ConvaiConversationFlowController` (`密封类：ConvaiCharacterModule<ConvaiConversationFlowProfile>`, `[AddComponentMenu("Convai/Embodiment/Conversation Flow")]`, `[DisallowMultipleComponent]`）是角色唯一由作者指定的来源 `对话状态`。当另一个模块需要时，Convai 会自动添加它——请参见 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md#convai-adds-it-automatically-when-needed).

#### 属性

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

#### 事件

| 事件        | 签名                                | 在以下情况触发：                      |
| --------- | --------------------------------- | ----------------------------- |
| `Changed` | `事件 Action<DialogueStateReading>` | 该读取值的 `主` 状态变化。仅在混合进度变化时不会触发。 |

***

### `对话状态读数`

`对话状态读数` (`只读结构体`, `SDK/Domain/Embodiment/Readings/DialogueStateReading.cs`）是由 `当前` 并传递给 `Changed`。读取值总是描述两个状态之间的混合，而不是硬切换，因此消费者可以对其输出进行交叉淡入淡出，而不是突变。

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

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

***

### `ConvaiConversationFlowProfile`

`ConvaiConversationFlowProfile` (`密封类：ScriptableObject`, `[CreateAssetMenu(menuName = "Convai/Embodiment/Conversation Flow Profile")]`, `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" %}
如果 **思考最短停留** 设置高于 **思考最长停留** 在检查器中，该资源会提高 **思考最长停留** 以匹配 **思考最短停留** 自动地，因此检查器中显示的两个值始终与角色在运行时的行为一致。
{% endhint %}

#### 能量

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

#### 固定行为

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

* 角色一旦有本地证据表明你已经开始说话，就会立刻做出反应，早于 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 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/embodiment/conversation-flow/reference.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.