> 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/session-lifecycle.md).

# 会话生命周期

说明角色连接如何在不同状态之间移动、如何在重新连接后保持会话，以及如何暂停、恢复或进入后台。

每个 `ConvaiCharacter` 在场景中都与 Convai 保持独立会话。该会话会跟踪角色是否已连接、当前处于什么状态，以及在启用持久化时，上次连接时参与的是哪段对话。了解会话的创建、持久化和恢复方式，有助于你在训练模拟、交互体验和游戏中构建可靠且可恢复的角色交互。

***

### 会话状态机

每个角色会话都会经历以下状态。

```mermaid
stateDiagram-v2
    [*] --> Disconnected

    Disconnected --> Connecting : connect initiated
    Connecting --> Connected : connection established
    Connecting --> Error : configuration or auth failure

    Connected --> Disconnecting : disconnect initiated
    Disconnecting --> Disconnected : clean shutdown

    Connected --> Reconnecting : connection lost
    Reconnecting --> Connected : reconnect succeeded
    Reconnecting --> Error : max attempts exceeded
```

| 状态              | 值 | 含义                                   |
| --------------- | - | ------------------------------------ |
| `Disconnected`  | 0 | 没有活动会话。初始状态，以及正常断开连接后的最终状态。          |
| `Connecting`    | 1 | 正在尝试连接。从 Disconnected 转换为 Connected。 |
| `Connected`     | 2 | 会话处于活动状态。音频流和对话均已启用。                 |
| `Reconnecting`  | 3 | 连接已丢失。SDK 正在尝试自动重新建立连接。              |
| `Disconnecting` | 4 | 正在正常关闭。从 Connected 转换为 Disconnected。 |
| `Error`         | 5 | 发生不可恢复的错误。需要手动干预才能重新连接。              |

你会通过 `SessionStateChangedRelayData` 事件接收状态转换，这些事件由 `ConvaiSessionEventRelay`发布。有关订阅方法，请参阅 [事件系统](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/event-system.md) 。

***

### 每个角色各自的会话

每个 `ConvaiCharacter` 都有自己的独立会话。不同角色之间不会共享会话。在包含多个角色的场景中，每个角色都会独立连接和断开连接——会话 ID 根据 Inspector 中设置的角色 ID 字符串确定（而非场景或对象名称），重连策略按角色分别应用，一个角色发生会话错误也不会影响其他角色。

这里描述的是每个 `ConvaiCharacter` 在本地跟踪的连接。当场景注册了两个或更多角色时，SDK 会在连接时围绕这些角色构建一个共享的多角色房间，并在各角色会话之上增加独立的成员列表和就绪状态模型。有关这一层的说明，请参阅 [多角色会话的工作方式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/how-multi-character-sessions-work.md) 。

`ConvaiSessionData` 是持久化会话存储，用于将每个角色映射到其当前会话标识符。它会在启动时自动从磁盘加载，并在每次更改时写入 `{Application.persistentDataPath}/Convai/sessions.json` ——会话 ID 会在应用重启后保留，无需进行额外设置。

| 方法                                       | 说明                                   |
| ---------------------------------------- | ------------------------------------ |
| `GetSessionId(characterId)`              | 返回该角色当前的会话 ID；如果没有，则返回 `null` 如果不存在。 |
| `StoreSessionId(characterId, sessionId)` | 为角色存储会话 ID，并立即将其保存到磁盘。               |
| `ClearSessionId(characterId)`            | 移除某个角色的会话 ID 并保存。                    |
| `ClearAllSessionIds()`                   | 移除所有已存储的会话 ID 并保存。                   |
| `GetAllSessionIds()`                     | 返回当前所有 character→sessionId 映射的只读快照。  |

{% hint style="info" %}
`ConvaiSessionData` 是一个单例。数据存储在 `{Application.persistentDataPath}/Convai/sessions.json` 并会在应用重启后保留。如果需要清除所有数据，请显式调用 `ClearAllSessionIds()` 。
{% endhint %}

***

### 会话持久化

会话 ID 持久化后，SDK 可在下次连接时继续之前的对话——角色会记得此前交互中的上下文。

#### 会保留的内容与重置的内容

| 重新连接时       | 行为                                     |
| ----------- | -------------------------------------- |
| 会话 ID       | 通过以下方式持久化 `ConvaiSessionData` — 支持恢复会话 |
| 对话历史        | 由 Convai 管理；会话 ID 有效时将恢复               |
| 进行中的音频      | 重置 — 流传输中的音频会被丢弃                       |
| 活动轮次状态      | 重置 — 轮次将从头开始                           |
| 模块状态（例如，情绪） | 重置 — 重新连接时模块会重新初始化                     |

#### 默认持久化堆栈

SDK 通过以下接口提供可插拔的持久化层： `ISessionPersistence` 适用于需要自定义后端存储（加密存储、云端存档或数据库）的项目。默认堆栈如下：

```
ISessionPersistence
  └─ KeyValueStoreSessionPersistence        ← 使用前缀 "convai.session." 将 characterId 映射到 sessionId
       └─ PlayerPrefsKeyValueStore           ← 默认的 IKeyValueStore 实现；封装 Unity PlayerPrefs
            └─ UnityEngine.PlayerPrefs       ← 持久化到磁盘
```

会话 ID 存储在按以下格式生成的键中： `convai.session.<characterId>`.

#### 替换持久化存储

实现 `IKeyValueStore` 即可使用任意后端存储——数据库、加密存储或云端存档系统。 `PlayerPrefsKeyValueStore` 会在内部将所有读写操作调度到 Unity 主线程；如果你的后端存储有线程限制，请采用相同的线程安全模式。

```csharp
public sealed class SecureKeyValueStore : IKeyValueStore
{
    public string GetString(string key, string defaultValue = null)
    {
        return SecureStorage.GetValue(key) ?? defaultValue;
    }

    public void SetString(string key, string value)
    {
        SecureStorage.SetValue(key, value);
    }

    public bool HasKey(string key) => SecureStorage.HasKey(key);

    public void DeleteKey(string key) => SecureStorage.DeleteKey(key);

    public void Save() => SecureStorage.Flush();
}
```

通过以下方式注册： `ConvaiRuntimeBuilder`:

```csharp
var runtime = new ConvaiRuntimeBuilder()
    .UsePersistence(new MyPersistenceProvider(new SecureKeyValueStore()))
    .Build();
```

***

### 重新连接策略

`ReconnectPolicy` 用于控制连接意外断开时 SDK 的行为。

| 字段                         | 类型             | 默认值                | 说明                                              |
| -------------------------- | -------------- | ------------------ | ----------------------------------------------- |
| `RoomRejoinTtlSeconds`     | `double`       | `60`               | 连接断开后，SDK 可以重新加入现有房间的时间窗口（秒）。超过此窗口后，SDK 将创建新房间。 |
| `ResumePolicy`             | `ResumePolicy` | `ResumeIfPossible` | 用于控制 SDK 是否尝试通过 `character_session_id`.         |
| `MaxReconnectAttempts`     | `int`          | `3`                | 会话进入 `Error` 状态前自动重连的最大尝试次数。                    |
| `SpawnAgentOnRejoin`       | `bool`         | `true`             | 重新加入现有房间时是否重新生成 AI 代理。                          |
| `StartWaitTimeoutMs`       | `int`          | `5000`             | 连接的超时时间（毫秒）， `Start()` 超过此时长后，该阶段的尝试将被视为失败。     |
| `AutoMicStartDelaySeconds` | `float`        | `0.5`              | 连接后等待多少秒再启动麦克风。此设置可防止会话完全就绪前采集音频。               |

#### `ResumePolicy` 选项

| 值                  | 行为                              |
| ------------------ | ------------------------------- |
| `AlwaysFresh`      | 始终开始新的对话。角色不会记得之前会话的内容。         |
| `ResumeIfPossible` | 尝试恢复之前的对话。如果会话已过期或恢复失败，则回退到新会话。 |
| `AlwaysResume`     | 始终恢复对话。如果恢复失败，连接也会失败，不会回退到新会话。  |

#### 预设策略

| 预设                                | 说明                                                |
| --------------------------------- | ------------------------------------------------- |
| `ReconnectPolicy.Default`         | TTL 为 60 秒， `ResumeIfPossible`，尝试 3 次，麦克风延迟 0.5 秒 |
| `ReconnectPolicy.AlwaysCreateNew` | 不尝试重新加入。始终创建新房间和新会话。                              |

```csharp
var policy = new ReconnectPolicy(
    roomRejoinTtlSeconds: 120,
    resumePolicy: ResumePolicy.AlwaysFresh,
    maxReconnectAttempts: 5,
    autoMicStartDelaySeconds: 1.0f
);
```

{% hint style="warning" %}
`AlwaysResume` 会将会话置于 `Error` 状态（例如，会话已过期时），表示 Convai 无法恢复会话。除非您的训练模拟要求严格保持连续性，且您已明确处理错误状态，否则请使用 `ResumeIfPossible` 。
{% endhint %}

***

### 显式会话控制

`ConvaiManager` 提供了三种异步方法，可在自动重新连接之外控制会话： `PauseAsync()`, `ResumeAsync()`和 `ReconnectAsync()`。当应用需要暂停呈现但不想断开连接，或按需强制建立新连接时，可使用这些方法。例如，训练模拟可能需要在主持人休息期间暂停，或者菜单界面可能会中断游戏。

| 方法                 | 功能说明                                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `PauseAsync()`     | 暂停 Convai 角色音频、已发送的转录内容呈现和运行时模块，同时保持房间连接。                                                                                                    |
| `ResumeAsync()`    | 仅移除由 `PauseAsync()`设置的手动暂停原因。应用同时处于后台时触发的暂停（见下文）仍会保持生效，直到 Unity 报告应用已回到前台。                                                                   |
| `ReconnectAsync()` | 使用上文所述的 `ReconnectPolicy` 和会话恢复行为，显式执行一次断开/连接操作。当 `SessionState` 已处于 `Connecting` 或 `Disconnecting` 状态时调用此方法会抛出 `InvalidOperationException`. |

```csharp
await manager.PauseAsync();
// ... 主持人休息 ...
await manager.ResumeAsync();
```

***

### 应用后台策略

`RuntimeBackgroundPolicy` 用于控制 Unity 应用进入后台时哪些内容继续运行，例如玩家切换到其他窗口，或移动应用转入后台时。可在 **Edit > Project Settings > Convai SDK > Runtime Defaults > Background Policy**中设置项目默认值，也可以在运行时更改当前管理器的设置：

```csharp
await manager.SetBackgroundPolicyAsync(RuntimeBackgroundPolicy.MuteButCatchUp);
```

| 值                 | 角色音频                                  | 规范转录历史记录 | 已发送的转录内容呈现      | 口型同步                                               |
| ----------------- | ------------------------------------- | -------- | --------------- | -------------------------------------------------- |
| `ContinueAudibly` | 继续运行；请求在后台执行                          | 继续运行     | 继续运行            | 按实时音频时钟继续运行                                        |
| `PauseTimeline`   | Convai `AudioSource` 会暂停；不相关的游戏音频不受影响 | 继续接收房间事件 | 暂停时隐藏，恢复后重放当前状态 | 演示更新会暂停；数据接收会保持在有限范围内，恢复时会重新锚定到可用音频，因此可以跳过已过期的缓冲数据 |
| `MuteButCatchUp`  | 本地静音，同时继续推进播放                         | 继续运行     | 继续运行            | 继续运行；切回前台后从实时位置恢复，而不是重放错过的演示内容                     |

`ContinueAudibly` 和 `MuteButCatchUp` 会在运行期间设置 `Application.runInBackground` ，但操作系统或浏览器仍可能暂停或静音进程。在 WebGL 中，音频由浏览器路由，而非由 Unity 的 `AudioSource`管理，因此 `PauseTimeline` 在该平台上会回退到 `MuteButCatchUp` ；状态变更事件会同时报告请求值和生效值。 `PauseTimeline` 只会暂停本地演示；不会阻止 Convai 生成响应，也不会阻止 SDK 接收转录内容。

订阅 `OnRuntimeBackgroundStateChanged` 以观察请求的策略和实际生效的策略；当平台无法实现请求的行为时，两者可能不同。管理器会在 `OnApplicationPause` 以及失去焦点的状态切换时应用所选策略；即使 Unity 同时触发两个回调，也不会重复暂停。

```csharp
[SerializeField] private ConvaiSessionEventRelay _relay;

private void OnEnable() =>
    _relay.OnRuntimeBackgroundStateChanged.AddListener(HandleBackgroundStateChanged);

private void HandleBackgroundStateChanged(RuntimeBackgroundStateRelayData data)
{
    if (data.RequestedPolicy != data.EffectivePolicy)
        Debug.LogWarning($"Background policy fell back from {data.RequestedPolicy} to {data.EffectivePolicy}.");
}
```

***

### 空闲警告和超时

Convai 会发送一条 `user-idle-warning` 消息，其中包含 `remaining_seconds` ，并在此后断开空闲会话。SDK 会通过 `ConvaiManager.Events.OnUserIdleWarningReceived` 提供此事件；对于由 Inspector 驱动的侦听器，则通过 `ConvaiSessionEventRelay.OnUserIdleWarning`.

管理器还会根据该倒计时计算一次性本地截止时间，并通过 `ConvaiManager.Events.OnUserIdleTimeoutElapsed` 和 `ConvaiSessionEventRelay.OnUserIdleTimeout`. `OnUserIdleTimeoutElapsed` 是面向超时 UI 和恢复流程的客户端截止时间信号——它并不代表 Convai 已关闭房间，因为 Convai 目前不会单独发送超时数据包。请使用 `OnSessionStateChanged` 或 `OnDisconnected` 作为权威传输状态。

语音、文本、触发器和动态上下文活动已经会重置 Convai 的空闲计时。对于警告后仅发生在 UI 上的活动，请调用 `ResetIdleTimer()` （或面向 UI 的别名 `ExtendIdleTimeout()`）将截止时间延后；如果没有可接受重置请求的已连接房间，这两个方法都会返回 `false` 。

```csharp
private void HandleIdleWarning(UserIdleWarningRelayData warning)
{
    ShowIdlePrompt(warning.RemainingSeconds);
}

public void ContinueSession()
{
    if (!manager.ExtendIdleTimeout())
        ShowReconnectPrompt();
}
```

***

### 用法示例

#### 示例 1：医疗培训模拟——网络中断后恢复

学员正在进行评估时网络中断。连接恢复后，患者角色会继续之前的对话，不会丢失上下文。

```csharp
var policy = new ReconnectPolicy(
    roomRejoinTtlSeconds: 120,          // 2-minute window to rejoin the existing room
    resumePolicy: ResumePolicy.ResumeIfPossible,
    maxReconnectAttempts: 5,
    autoMicStartDelaySeconds: 1.0f      // extra delay for slow mobile networks
);
```

**预期结果：** SDK 会在 2 分钟的时间窗口内自动重试，最多 5 次。如果 Convai 端的会话仍然有效，对话会从中断处继续。如果会话已过期，角色会开始新的对话，而不是卡住。

***

#### 示例 2：企业入职服务终端——每次对话都从头开始

每位走到服务终端前的新员工都应从头开始，且不保留对之前用户的记忆。 `AlwaysFresh` 和 `AlwaysCreateNew` 可确保每次都从全新状态开始。

```csharp
// Apply policy in the ConvaiRoomManager's reconnect settings
var policy = ReconnectPolicy.AlwaysCreateNew;
// ResumePolicy defaults to AlwaysFresh in AlwaysCreateNew — no prior session carried over
```

为确保在下一次会话开始前清除上一位用户的数据：

```csharp
public class KioskSessionReset : MonoBehaviour
{
    [SerializeField] private string _characterId;

    public void OnUserLogOut()
    {
        ConvaiSessionData.Instance.ClearSessionId(_characterId);
    }
}
```

**预期结果：** 每位新用户都会开始一段完全全新的对话。角色不会记得之前的交互，这适用于共享服务终端的部署场景。

***

#### 示例 3：在培训模拟中处理错误状态

当所有重连尝试均已用尽时，会话会进入 `Error` 状态。应向培训人员显示此状态，并允许手动重试，而不是让程序无提示地卡住。

```csharp
public class SessionErrorHandler : MonoBehaviour
{
    [SerializeField] private ConvaiSessionEventRelay _relay;
    [SerializeField] private GameObject _errorPanel;
    [SerializeField] private ConvaiManager _manager;

    private void OnEnable()  => _relay.OnSessionStateChanged.AddListener(HandleStateChange);
    private void OnDisable() => _relay.OnSessionStateChanged.RemoveListener(HandleStateChange);

    private void HandleStateChange(SessionStateChangedRelayData data)
    {
        _errorPanel.SetActive(data.IsError);
    }

    // Called by the facilitator's "Retry" button
    public async void RetryConnection()
    {
        _errorPanel.SetActive(false);
        await _manager.ConnectAsync();
    }
}
```

**预期结果：** 会话进入 `Error` 状态时，错误面板会显示。主持人点击“重试”，尝试重新建立连接，而无需重启模拟。

***

### 故障排查

| 症状                                                 | 可能原因                                                                         | 解决方法                                                                               |
| -------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 会话在连接中断后仍停留在 `Error` 状态                            | `AlwaysResume` 无法恢复会话，因为会话已过期                                                | 切换为 `ResumeIfPossible`；调用 `ClearSessionId(characterId)` 以移除过期的会话 ID，然后重新连接         |
| 尽管使用了 `ResumeIfPossible`                           | 角色每次启动时都会开始新的对话，因为之前调用了 `ClearAllSessionIds()` 并清除了会话文件，或者角色 ID 在不同运行之间发生了变化 | 确认 `characterId` 字符串在每次运行中保持一致；检查 `{persistentDataPath}/Convai/sessions.json`      |
| 会话一直卡在 `Connecting` 状态                             | `StartWaitTimeoutMs` 未针对慢速网络进行配置；或者防火墙阻止了传输                                  | 增大 `StartWaitTimeoutMs` 在 `ReconnectPolicy`中的值；确认网络可以访问 Convai 端点                  |
| 重连循环始终未能成功；会话最终进入 `Error`                          | `MaxReconnectAttempts` 已达上限                                                  | 订阅 `ConvaiSessionEventRelay.OnSessionStateChanged` 并向用户显示错误；在用户确认后手动重新连接           |
| 两个角色共享同一个会话 ID                                     | Inspector 中的角色 ID 字符串完全相同                                                    | 为场景中的每个 `ConvaiCharacter` 分配唯一的角色 ID                                               |
| `ResumeAsync()` 未能恢复音频                             | 应用仍处于后台，因此后台策略会使手动暂停原因保持生效                                                   | 等待应用返回前台，或检查 `IsBackgrounded` 最新的 `OnRuntimeBackgroundStateChanged` 负载             |
| `ReconnectAsync()` 会抛出 `InvalidOperationException` | 调用时， `SessionState` 已经处于 `Connecting` 或 `Disconnecting`                      | 调用前检查 `SessionState` ，或等待正在进行的状态转换完成                                               |
| 空闲警告从未触发                                           | 没有订阅监听器，或者活动持续重置 Convai 的空闲跟踪                                                | 订阅 `OnUserIdleWarningReceived` 或 `OnUserIdleWarning`；请注意，语音、文本、触发器和动态上下文活动都会重置空闲跟踪 |

***

### 后续步骤

现在，你已经了解了如何创建角色会话、状态转换如何工作、如何在重启后保留会话 ID，以及如何配置重连行为。接下来阅读“轮流发言模式”，了解如何配置 SDK 检测语音输入；然后阅读“事件系统”，了解如何在场景脚本中订阅会话和角色事件。

{% content-ref url="/pages/251e0bf7030a5f742a1182e15529c0604e3ee150" %}
[轮流发言模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/turn-taking-modes.md)
{% endcontent-ref %}

{% content-ref url="/pages/0bd691fc4d8a06b0dbafd0f28b11f39be6f57f9a" %}
[事件系统](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/event-system.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/session-lifecycle.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.
