动态上下文 Blueprint 参考

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

大多数动态上下文函数都暴露在 UConvaiChatbotComponent （Blueprint 显示名称 Convai 聊天机器人) 位于 Convai|DynamicContext 类别下。 更新上下文 是一个高级直接 上下文更新 节点，位于 Convai 类别；它绕过已跟踪的状态/事件辅助 API。属性显示在 Convai > DynamicContext （防抖设置）和 Convai (DynamicEnvironmentInfo）在“详情”面板中。

源文件： Source/Convai/Public/ConvaiChatbotComponent.h, Source/Convai/Private/ConvaiChatbotComponent.cpp, Source/Convai/Public/DynamicContext/，以及 Source/Convai/Private/ConvaiSubsystem.cpp.

函数

设置上下文状态

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

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

蓝图类别： Convai|DynamicContext

参数	类型	默认值	说明
名称	FString	—	用于标识此状态属性的键。区分大小写。
值	FString	—	该状态属性的当前值。
ShouldRespond	EC_RunLLMOption	从不	会贡献到批量聚合 run_llm.
bFlushImmediately	bool	false	高级。 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。

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

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

---

设置上下文状态

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

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

蓝图类别： Convai|DynamicContext

参数	类型	默认值	说明
状态	TMap<FString, FString>	—	要设置或更新的键值状态属性映射。
ShouldRespond	EC_RunLLMOption	从不	会贡献到批量聚合 run_llm 适用于所有提供的键。
bFlushImmediately	bool	false	高级。 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。

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

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

---

Add Context Event

将一条按时间顺序的事件字符串追加到动态上下文中。

适用于： 某事只发生一次——警报、里程碑、叙事节点。

蓝图类别： Convai|DynamicContext

参数	类型	默认值	说明
文本	FString	—	要追加的事件描述。
ShouldRespond	EC_RunLLMOption	Auto	会贡献到批量聚合 run_llm.
bFlushImmediately	bool	false	高级。 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。

行为： 相同 文本 在同一防抖窗口内多次暂存的相同值会去重。刷新时，事件会提交到跟踪器并包含在规范中。普通上下文事件不会重复到单独的增量行中。

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

---

移除上下文状态

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

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

蓝图类别： Convai|DynamicContext

参数	类型	默认值	说明
名称	FString	—	要移除的键。区分大小写。
bFlushImmediately	bool	false	高级。 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。

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

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

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

---

重置动态上下文

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

适用于： 仿真重新启动，或者你需要丢弃之前的所有运行时上下文。

蓝图类别： Convai|DynamicContext

参数	类型	默认值	说明
—	—	—	无参数。

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

---

获取上下文状态值

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

适用于： 蓝图条件在发送冗余更新前需要当前本地值。

蓝图类别： Convai|DynamicContext

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

---

更新上下文

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

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

蓝图类别： Convai

参数	类型	默认值	说明
文本	FString	—	要应用的上下文文本。以下情况可选： 模式 为 Reset.
模式	EC_ContextUpdateMode	Append	上下文应用方式： Append, Replace，或 Reset.
ShouldRespond	EC_RunLLMOption	Auto	映射到 run_llm 在线路上传输。

使用 更新上下文 仅当已跟踪节点家族不满足你的格式要求时。它不会更新 FConvaiDynamicContextTracker，因此 获取上下文状态值 当传入空字符串时 模式 为 Reset；SDK 会省略 text 仅在空 Reset 有效负载时。

默认 ShouldRespond 引用

函数	默认值 ShouldRespond
设置上下文状态	从不
设置上下文状态	从不
Add Context Event	Auto
移除上下文状态	（无 ShouldRespond 参数）
重置动态上下文	（Reset 始终使用 从不 在传输中）
更新上下文	Auto

属性

ContextDebounceWindow

详情面板标签	上下文防抖窗口（秒）
类型	float
默认值	0.5
限制	≥ 0.1
类别	`Convai

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

---

ContextMaxDebounceWindow

详情面板标签	最大防抖窗口（秒）
类型	float
默认值	3.0
限制	≥ 0.1
类别	`Convai

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

---

DynamicEnvironmentInfo

详情面板标签	动态环境信息
类型	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	Append	追加	文本会追加到现有上下文。
EC_ContextUpdateMode::Replace	Replace	替换	完整上下文会被提供的文本替换。
EC_ContextUpdateMode::Reset	Reset	重置	上下文会被清空。传入空 文本 用于标准 Reset 有效负载。

传输消息

上下文更新

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

JSON 字段	说明
模式	追加, 替换，或 重置
run_llm	字符串值 "auto", "true"，或 "false"
text	组装后的上下文字符串；在空 Reset 时省略
current_attention_object	当注意对象被折叠进刷新时，可选的注意对象名称

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

update-dynamic-info

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

JSON 字段	说明
dynamic_info.text	自由格式环境文本

连接辅助

函数	类别	说明
获取聊天机器人连接状态	`Convai	连接`

下一步

同步行为与时机动态上下文故障排查