连接时静态上下文

了解哪些已验证连接数据在会话开始时是固定的，以及实时上下文更新如何使用单独的运行时消息。

有些上下文会在会话开始时发送一次。其他上下文可以在游戏过程中通过单独的更新路径发生变化。本页说明连接时固定的内容，以及可以实时更新的内容。

连接时发送的内容

当 开始会话 运行时， UConvaiChatbotComponent 使用组件中的连接参数和当前环境数据打开一个实时会话。经源码验证的实时连接路径包含以下数据：

Data	来源开启 UConvaiChatbotComponent	说明
角色 ID	CharacterID	决定 Convai 加载哪个角色配置。
动作配置	EnvironmentData 当 bEnableActions 为 true 并且至少配置了一个动作	序列化为一个 JSON action_config 块。动作集、对象列表和角色列表在重新连接前保持固定。
终端用户身份	EndUserID 是位于 EndUserMetadata	用于长期记忆。在会话中途更改它们不会影响当前会话。

这些值用于建立会话。在游戏过程中推送动态上下文时，它们不会改变。

哪些内容可实时更新

会话连接后，有六种机制可以向 Convai 传递更新后的上下文：

机制	RTVI 消息	承载内容
动态上下文管道	上下文更新	跟踪的状态和事件，来自 设置上下文状态, 设置上下文状态, Add Context Event, 移除上下文状态，以及 重置动态上下文
直接上下文更新	上下文更新	通过 更新上下文，绕过已跟踪的状态/事件辅助 API
场景元数据管道	update-scene-metadata	来自……的新建或移除的环境条目 AddObject, RemoveObject, AddCharacter, RemoveCharacter以及相关的环境变更
动态环境信息	update-dynamic-info	来自……的自由格式文本 DynamicEnvironmentInfo
叙事模板键	update-template-keys	当前 NarrativeTemplateKeys 连接后以及通过……更新时的值 UpdateNarrativeTemplateKeys
注意力折叠	上下文更新 （同一条消息）	可选 current_attention_object 当注意力在上下文刷新时被暂存

请参见 动态上下文如何工作 用于跟踪管道，且 场景元数据如何工作 用于环境更新。

DynamicEnvironmentInfo

DynamicEnvironmentInfo 是一个 FString 属性，位于 Convai 详细信息面板的……类别中。它承载的是自由格式文本， 不是 由 FConvaiDynamicContextTracker.

插件通过 update-dynamic-info 在两种情况下：

1. 在参会者连接时 — OnAttendeeConnected 调用 UpdateDynamicInfo 使用当前属性值。
2. 连接状态下属性更改时 —— 赋予新值会触发 UpdateDynamicEnvironmentInfo，其会调用 UpdateDynamicInfo 当会话代理存在时。

线上载荷结构如下：

{
  "dynamic_info": {
    "text": "你的自由格式文本"
  }
}

DynamicEnvironmentInfo 不会经过防抖批处理。它不使用规范的状态/事件组装。对于在游戏过程中频繁变化的值，请使用 设置上下文状态 代替。

使用场景	推荐路径
会话级简报，设置一次或很少更改	DynamicEnvironmentInfo
游戏过程中变化的运行时事实	设置上下文状态 或 Add Context Event

连接数据与实时更新之间的关系

连接数据用于建立实时会话，并在启用动作时建立初始动作配置。实时更新承载的是会话开始后发生变化的信息。

类似这样的动态状态更新 Health 为 50 会向 Convai 通报当前的运行时事实。它不会编辑 action_config 在连接时发送的内容。只推送游戏过程中发生变化的内容，不要通过动态上下文管道重新发送相同的连接数据。

重新连接与动态层

在默认的连接代理设置下，调用 停止会话 然后调用 开始会话 会创建一个新的实时连接。如果启用了连接代理复用，并且正值的 ConnectionProxyTTL，同一角色重启可以复用一个孤立连接。新的连接会使用当前的 CharacterID、终端用户身份字段以及当时的动作配置。 FConvaiDynamicContextTracker 是一个客户端内存中的结构；当会话重启时，它不会自动重置。

调用 重置动态上下文 如果你想要一个干净的动态上下文跟踪器，请在重新连接前重置它。

动作配置在 /connect 时固定。运行时对 AddAction 或 RemoveAction 会为 下一 个会话，而不是当前会话。要更改实时动作契约，请调用 停止会话 然后 开始会话 ，在修改动作列表之后。

会话前动态上下文排队

对……的默认防抖调用 设置上下文状态, 设置上下文状态, Add Context Event，以及 移除上下文状态 在会话连接前发出的调用可免受 BeginPlay。 PendingContextBatch。当会话建立连接后，插件会在防抖期限已过的第一个 tick 中刷新该批次。

重置动态上下文 在连接前不会立即丢弃已暂存的更新——它会标记一个待处理的 Reset ，该项会在 在 任何已暂存的内容都会在连接后的首次刷新时排空。若要从空的动态上下文开始，请先让重置刷新完成，再暂存新的更新。

SessionID 和实时会话

SessionID 存在于 UConvaiChatbotComponent，但经过验证的实时 /connect 路径在当前源码中不会将其作为 FConvaiConnectionParams。不要依赖此节点返回的 SessionID 来控制动态上下文重置行为。请使用 重置动态上下文 用于跟踪的动态上下文层。

下一步

动态上下文如何工作动态上下文快速开始