动态上下文的工作原理

了解动态上下文如何跟踪运行时状态、批处理事件、选择响应行为并为 Convai 组装载荷。

动态上下文是 Convai 角色如何了解会话开始时不可用——或尚未发生——的运行时信息。你从 Blueprint 推送更新；插件会将它们本地存储、对快速变化进行批处理，并将组装好的负载发送给 Convai。

在 Unreal Engine 中的动态上下文，逐步讲解

把动态上下文看作两个通道：

通道	表示内容	Blueprint 节点	示例
状态	可被替换的当前事实	设置上下文状态 / 设置上下文状态	生命值 为 80
事件	会话中的一次性时刻	添加上下文事件	4 区触发警报

状态属性与事件

一个 状态属性 是一个命名的键值对，表示一个当前可替换的事实—— 生命值 为 80, 区域 为 市场区, 任务激活 为 true. 设置上下文状态 和 设置上下文状态 立即写入本地跟踪器。刷新时插件会发送一个 替换-模式 上下文更新 其文本为规范上下文，并可在下一行后附加差异行。

一个 事件 是一个自由格式的按时间顺序字符串—— 玩家捡起了红色钥匙, 4 区触发警报. 添加上下文事件 将文本暂存到待处理批次中。刷新时，该事件会提交到跟踪器的时间顺序事件列表，并包含在规范上下文中。普通上下文事件不会重复到单独的差异行中。

通道	可替换的	典型用途
状态属性	是——仅保留最新值	当前生命值、区域、装备配置
事件	否——仅追加	警报、里程碑、一次性叙事节点

角色接收到的内容

刷新时，插件会将所有活动状态和事件组装成一个以换行分隔的上下文字符串：

{StateName} 为 {Value}
{AnotherState} 为 {Value}
事件文本第一行
事件文本第二行

状态会先出现，按插入顺序排列。更新某个值不会改变其位置。事件随后按时间顺序排列。

// Blueprint 伪代码——当状态更新时，插入顺序会保持不变
设置上下文状态  名称="Zone"   值="Market District"   ShouldRespond=Never
设置上下文状态  名称="Health" 值="80"                ShouldRespond=Never
添加上下文事件  文本="玩家捡起了红色钥匙"     ShouldRespond=Auto
设置上下文状态  名称="Zone"   值="Docks"             ShouldRespond=Never

所有四次调用后的规范上下文：

Zone 为 Docks
Health 为 80
玩家捡起了红色钥匙

你提供名称、值和事件文本。插件会在刷新时组装并传递规范字符串。

防抖批处理

对 设置上下文状态, 设置上下文状态，以及 添加上下文事件 会安排一次防抖刷新，而不是立即发送。 移除上下文状态 仅当本地跟踪器中存在该键时，才会安排防抖刷新。

短时间窗口内的快速更新会合并为一次发送。两个属性控制 UConvaiChatbotComponent 时机：

属性	详情面板标签	默认值	含义
ContextDebounceWindow	上下文防抖窗口（秒）	0.5	在最近一次暂存更新后，等待这么多秒再刷新。窗口内的每次新更新都会重置计时器。
ContextMaxDebounceWindow	最大防抖窗口（秒）	3.0	从突发中的第一次更新开始，到总延迟的硬性上限。可防止持续不断的更新流无限期推迟刷新。

防抖计时器在突发中的第一次更新到达时启动。后续更新会将计时器重置为 ContextDebounceWindow 距最近一次调用的 ContextMaxDebounceWindow 距突发开始的 上下文更新 消息。

这两个属性都标记为 高级显示 在以下位置 Convai > DynamicContext 在 Details 面板中。

角色可能回应时

每个暂存的状态或事件都带有自己的 ShouldRespond 值。批次会将它们合并为一个聚合等级： 总是 > Auto > 从不。刷新会发送一个单一 上下文更新 ，并将该聚合值作为 run_llm.

聚合等级决定是否输出状态差异行：

• 聚合 从不 ——不输出差异行。新的状态键会立即进入规范上下文，因此 Convai 会保留它们。
• 聚合 Auto 或 总是 ——差异行会附加在规范块之后（用一个换行符分隔）。批次中的全新状态键在该次刷新中会被排除在规范上下文之外，只作为差异行出现；它们会在下一次刷新时进入规范上下文。

按键 ShouldRespond 在单独调用中仍会计入聚合等级，但当聚合不是 从不.

立即刷新

每个变更函数都提供一个 Advanced 参数 bFlushImmediately。当 true，插件会调用 FlushDynamicContext() 在当前帧中，绕过防抖计时器。仅在聊天机器人已连接后、需要时间敏感更新时使用。高频使用可能会每次调用都发送一个 上下文更新 ，且在存在暂存工作时处于连接状态。

重置动态上下文 不提供 bFlushImmediately。当角色已连接时，它会立即调用刷新路径；当离线时，它会将重置排队到下次连接后的刷新中。

会话前排队

在……之前发出的默认防抖调用 IsChatbotConnected() 返回 true 累积在 PendingContextBatch. TickDynamicContext() 在断开连接时会提前返回，因此不会发送消息。会话连接后，下一个到达防抖截止时间的 Tick 会调用 FlushDynamicContext() 并将待处理批次作为一个 替换-模式快照。不要在 bFlushImmediately = true 连接前用于必须送达的数据，因为它会绕过断开连接时的 Tick 保护。

你可以从 BeginPlay 填充初始状态

而无需延迟执行或连接保护：
事件 BeginPlay
  // Blueprint 伪代码——可在 Start Session 之前从 BeginPlay 安全调用
  → 设置上下文状态  名称="Facility"  值="Offshore Platform Alpha"  ShouldRespond=Never
  → 设置上下文状态  名称="Scenario"  值="Fire Drill"               ShouldRespond=Never

重置顺序

重置动态上下文 标记 bPendingReset 在待处理批次上。当连接时，它会立即刷新；当断开连接时，它会将重置安排到下次连接后的刷新中。它不会 不 预先清除跟踪器或丢弃已暂存的更新。刷新时：

1. 暂存的状态、事件和可选注意力会作为一个 替换 上下文更新.
2. 如果已排队，待处理的环境元数据会被清空。当……时已存在的排队叙事触发器会被该重置请求清除；在待处理的离线 重置动态上下文 被调用时 重置 之前排队的触发器仍可能在 重置.
3. 一个 重置 上下文更新 最后触发（模式：重置, run_llm: "false"，无 文本 字段用于空的 重置 负载），然后本地跟踪器会被清空。

如果你调用 重置动态上下文 并在同一离线窗口中暂存新更新，则第一次连接后的刷新会先传递暂存内容，然后 重置 会清除远程和本地上下文。当你希望从空的动态层开始时，请先让重置刷新完成，再暂存新数据。

批次内事件去重

在同一防抖窗口内多次暂存的相同事件字符串会去重——该次刷新只保留第一次出现。 同一突发中的不同事件字符串都会按时间顺序保留。

动态环境信息是单独通道

DynamicEnvironmentInfo 是一个 FString 位于 UConvaiChatbotComponent上的属性 更改它会调用 使用 update-dynamic-info dynamic_info.text FConvaiDynamicContextTracker 跟踪，也不会经过防抖批次。参见 连接时的静态上下文.

何时使用哪个函数

目标	在每个阶段加载时，对聊天机器人组件使用
跟踪一个当前条件	设置上下文状态
跟踪多个一起变化的条件	设置上下文状态
记录某事已发生	添加上下文事件
移除不再适用的条件	移除上下文状态
清除所有运行时上下文	重置动态上下文
发送外部构建的上下文文本	更新上下文 ——绕过跟踪器
推送会话级自由格式备注	DynamicEnvironmentInfo ——独立的 更改它会调用 通道

下一步

同步行为与时序动态上下文快速开始动态上下文 Blueprint 参考排查动态上下文问题