动态上下文 Blueprint 参考

参考从 Unreal 角色在实时会话中向 Convai 发送运行时状态、事件、重置、时序和传递更新的 Blueprint 控件。

大多数动态上下文函数都暴露在 UConvaiChatbotComponent （蓝图显示名称 Convai 聊天机器人) 位于 Convai|DynamicContext 类别。 更新上下文 是一个高级的直接 context-update 中的节点 Convai 类别；它绕过已跟踪的状态/事件辅助 API。属性显示在 Convai > DynamicContext (去抖和交付时序设置) 和 Convai (DynamicEnvironmentInfo) 在 Details 面板中。

权威来源： Source/Convai/Public/ConvaiChatbotComponent.h, Source/Convai/Private/ConvaiChatbotComponent.cpp, Source/Convai/Public/DynamicContext/ConvaiPendingContextBatch.h, Source/Convai/Public/DynamicContext/，以及 Source/Convai/Private/ConvaiSubsystem.cpp.

函数

设置上下文状态

在动态上下文中设置单个状态属性。如果存在同名属性 名称 ，则替换其值。

适用场景： 游戏过程中某个当前事实发生变化——生命值、区域、装备状态。

Blueprint 类别： Convai|DynamicContext

参数	类型	默认值	描述
名称	FString	—	标识此状态属性的键。区分大小写。
值	FString	—	状态属性的当前值。
ShouldRespond	EC_RunLLMOption	从不	会纳入批量聚合 run_llm.
传递方式	EConvaiContextDelivery	正常发送	高级。 等待对话空闲 会将更新保留到对话暂停，因此不会让角色打断自己。仅在该批次的聚合 ShouldRespond 为 Auto/总是.
bFlushImmediately	bool	false	高级。 绕过去抖，并在当前帧运行刷新路径。使用 传递方式 设置为 等待对话空闲，更新仍会等待安静时刻，但会跳过完整的 交付前静默时间（秒） 窗口。连接后用于必须交付的数据。

刷新行为： 一个替换 context-update。当聚合为 从不；否则新键会在首次刷新时延迟到增量行。更新后的键始终出现在规范中；当聚合不是 从不.

会话前： 使用默认去抖时，会安全地暂存，并在会话连接且去抖截止时间到期后刷新。不要在 bFlushImmediately = true 连接前用于必须交付的数据。

---

设置上下文状态

一次设置多个状态属性。所有键共享一次规范重建和一次刷新。

适用场景： 多个相关事实同时变化——场景切换后的区域、装备和一天中的时间。

Blueprint 类别： Convai|DynamicContext

参数	类型	默认值	描述
状态	TMap<FString, FString>	—	要设置或更新的键值状态属性映射。
ShouldRespond	EC_RunLLMOption	从不	会纳入批量聚合 run_llm 适用于所有提供的键。
传递方式	EConvaiContextDelivery	正常发送	高级。 等待对话空闲 会将更新保留到对话暂停，因此不会让角色打断自己。仅在该批次的聚合 ShouldRespond 为 Auto/总是.
bFlushImmediately	bool	false	高级。 绕过去抖，并在当前帧运行刷新路径。使用 传递方式 设置为 等待对话空闲，更新仍会等待安静时刻，但会跳过完整的 交付前静默时间（秒） 窗口。连接后用于必须交付的数据。

行为： 空映射会被忽略。聚合 ShouldRespond 会与同一去抖窗口中的任何其他暂存项合并（总是 > Auto > 从不).

会话前： 使用默认去抖时，会安全地暂存，并在会话连接且去抖截止时间到期后刷新。不要在 bFlushImmediately = true 连接前用于必须交付的数据。

---

添加上下文事件

向动态上下文追加一条按时间顺序排列的事件字符串。

适用场景： 某件事只发生了一次——警报、里程碑、叙事节拍。

Blueprint 类别： Convai|DynamicContext

参数	类型	默认值	描述
文本	FString	—	要追加的事件描述。
ShouldRespond	EC_RunLLMOption	Auto	会纳入批量聚合 run_llm.
传递方式	EConvaiContextDelivery	正常发送	高级。 等待对话空闲 会将事件保留到对话暂停，因此不会让角色打断自己。被保留的事件在最终发送时会落到事件历史末尾。仅在 ShouldRespond 为 Auto/总是.
bEphemeral	bool	false	高级。 当 true，角色只会在下一次更新时看到该事件一次，并且它永远不会提交到持久化上下文——后续更新中也不会再次出现。当 false （默认），事件会保留在运行上下文中。
bFlushImmediately	bool	false	高级。 绕过去抖，并在当前帧运行刷新路径。使用 传递方式 设置为 等待对话空闲，该事件仍会等待安静时刻，但会跳过完整的 交付前静默时间（秒） 窗口。连接后用于必须交付的数据。

行为： 相同 文本 值在同一去抖窗口内多次暂存时会去重（短暂事件和持久事件分别跟踪，因此与持久事件同文本的短暂事件不会与之去重）。在刷新时，非短暂事件会提交到跟踪器并包含在规范中。短暂事件会在输出的刷新文本中追加一次，之后丢弃——它永远不会写入跟踪器，因此后续更新中不会出现在规范上下文里。常规（非短暂）上下文事件不会复制到单独的增量行中。

会话前： 使用默认去抖时，会安全地暂存，并在会话连接且去抖截止时间到期后刷新。不要在 bFlushImmediately = true 连接前用于必须交付的数据。

---

移除上下文状态

从动态上下文中移除一个状态属性，并重新构建不包含它的规范上下文。

适用场景： 某个条件不再适用——物品已使用，警报已清除。

Blueprint 类别： Convai|DynamicContext

参数	类型	默认值	描述
名称	FString	—	要移除的键。区分大小写。
bFlushImmediately	bool	false	高级。 绕过去抖，并在当前帧运行刷新路径。连接后用于必须交付的数据。

返回： 无。如果 名称 不存在，则该调用无操作。

行为： 设置 bForceReplace 到待处理批次上，以便刷新时发送更新后的规范上下文而不包含已移除的键。不添加增量行。

会话前： 使用默认去抖时，会安全地暂存，并在会话连接且去抖截止时间到期后刷新。不要在 bFlushImmediately = true 连接前用于必须交付的数据。

---

重置动态上下文

清除所有已跟踪的状态属性和事件，并重置远程上下文。

适用场景： 模拟重新启动，或者你需要丢弃之前所有运行时上下文。

Blueprint 类别： Convai|DynamicContext

参数	类型	默认值	描述
—	—	—	无参数。

行为： 标记 bPendingReset。不会预先清除跟踪器或丢弃暂存更新。刷新时：先清空暂存批次，然后触发 Reset context-update 触发（模式：reset, run_llm: "false"，并带有 文本 （空的 Reset 载荷省略），然后清除本地跟踪器。清除 PendingTriggers 在请求重置时。连接时会立即调用刷新路径；离线时会排队直到首次连接后刷新。

---

获取上下文状态值

返回已跟踪状态属性当前的客户端值。读取本地跟踪器——不会查询 Convai。

适用场景： Blueprint 条件在发送冗余更新前需要当前本地值。

Blueprint 类别： Convai|DynamicContext

参数	方向	类型	默认值	描述
名称	在	FString	—	要查找的键。区分大小写。
OutValue	输出	FString	—	如果键存在，则返回当前值。
返回值	返回	bool	—	true 如果找到了该键。

---

更新上下文

高级直接节点。发送原始 context-update 并显式使用 文本, 模式，以及 ShouldRespond。暂存的状态/事件刷新在 FlushDynamicContext() 时使用相同的传输消息类型，而不会通过此节点更新跟踪器。 重置动态上下文 使用相同的 C++ UpdateContext 发送路径发送重置消息。

适用场景： 已跟踪节点族不满足你的格式要求。

Blueprint 类别： Convai

参数	类型	默认值	描述
文本	FString	—	要应用的上下文文本。当 模式 为 重置.
模式	EC_ContextUpdateMode	追加	上下文应用方式： 追加, 替换，或 重置.
ShouldRespond	EC_RunLLMOption	Auto	映射到 run_llm 在传输层。

在每个阶段加载时，对聊天机器人组件使用 更新上下文 仅在已跟踪节点族不满足你的格式要求时使用。它不会更新 FConvaiDynamicContextTracker，因此 获取上下文状态值 无法读取仅通过此节点发送的值。当 模式 为 重置；SDK 会省略 文本 仅用于空的 Reset 载荷。

默认 ShouldRespond 参考值

函数	默认值 ShouldRespond	默认值 传递方式
设置上下文状态	从不	正常发送
设置上下文状态	从不	正常发送
添加上下文事件	Auto	正常发送
移除上下文状态	（无 ShouldRespond 参数）	（无 传递方式 参数）
重置动态上下文	（Reset 始终使用 从不 在传输层）	（无 传递方式 参数）
更新上下文	Auto	（无 传递方式 参数）

属性

ContextDebounceWindow

Details 面板标签	上下文去抖窗口（秒）
类型	float
默认值	0.5
夹紧	≥ 0.1
类别	`Convai

在最近一次暂存的上下文更新后，等待多少秒再刷新。窗口内每次新的更新都会重置此计时器。

---

ContextMaxDebounceWindow

Details 面板标签	最大去抖窗口（秒）
类型	float
默认值	3.0
夹紧	≥ 0.1
类别	`Convai

去抖突发中的第一次更新最多可延迟的上限。必须 ≥ ContextDebounceWindow；较小的值会在刷新时被夹紧。

---

ConversationIdleSettleSeconds

Details 面板标签	交付前静默时间（秒）
类型	float
默认值	2.0
夹紧	≥ 0.0
类别	`Convai

对话必须连续保持安静多长时间，才会让一个其 传递方式 为 等待对话空闲 被交付。任何对话活动都会重新开始等待——这里刻意不设总等待时长上限，因此等待中的更新绝不会打断正在进行的交流。设置为 0 可在检测到空闲后立即交付。

---

DynamicEnvironmentInfo

Details 面板标签	动态环境信息
类型	FString
默认值	""
类别	Convai

通过以下方式发送的自由格式文本 update-dynamic-info 在参与者连接时，以及在已连接会话中该属性发生变化时发送。不由 FConvaiDynamicContextTracker跟踪。对于运行时变化的事实，请使用 设置上下文状态.

枚举

EC_RunLLMOption

控制 Convai 在收到上下文更新后是否生成语音回复。

枚举项	Blueprint 显示名称	传输字符串（run_llm)	行为
EC_RunLLMOption::Auto	Auto	"auto"	发送更新，并请求自动回复处理。
EC_RunLLMOption::Always	总是	"true"	发送更新，并请求回复处理。
EC_RunLLMOption::Never	从不	"false"	发送更新，不请求回复处理。

---

EC_ContextUpdateMode

控制在调用时如何应用上下文字符串 更新上下文 直接。

枚举项	Blueprint 显示名称	传输值（模式)	行为
EC_ContextUpdateMode::Append	追加	追加	文本将追加到现有上下文。
EC_ContextUpdateMode::Replace	替换	替换	完整上下文将被提供的文本替换。
EC_ContextUpdateMode::Reset	重置	重置	上下文被清空。传入空的 文本 用于标准 Reset 载荷。

---

EConvaiContextDelivery

控制 当 状态、事件或事实更新到达角色的方式，与中所述的去抖批处理分开控制 同步行为和时序.

枚举项	Blueprint 显示名称	行为
EConvaiContextDelivery::SendNormally	正常发送	默认。批处理到下一次计划发送中——与此选项存在之前的行为相同。
EConvaiContextDelivery::WaitUntilConversationIsIdle	等待对话空闲	会被延后，直到对话已保持安静 交付前静默时间（秒），因此更新不会让角色打断自己或抢话。这里刻意不设置等待时间上限。

仅当 ShouldRespond 为 Auto/总是 ——一个静默（从不）更新没有可供打断的内容，因此无论 传递方式.

传输消息

context-update

由以下发送： UConvaiSubsystem::UpdateContext 用于已跟踪动态上下文刷新以及直接 更新上下文 调用。

JSON 字段	描述
模式	追加, 替换，或 重置
run_llm	字符串值 "auto", "true"，或 "false"
文本	组装后的上下文字符串；在空的 Reset 时省略
current_attention_object	当注意力信息合并到刷新中时的可选注意对象名称

来自以下的跟踪刷新： FlushDynamicContext 始终使用 模式：replace 用于暂存的批次内容。

update-dynamic-info

由以下发送： UpdateDynamicInfo 用于 DynamicEnvironmentInfo 变化以及参与者连接时。

JSON 字段	描述
dynamic_info.text	自由格式的环境文本

连接助手

函数	类别	描述
获取聊天机器人连接状态	`Convai	Connection`

下一步

同步行为与时序排查动态上下文问题