排查动态上下文问题

使用五步检查清单、症状表、角色无响应决策树以及完整的控制台日志参考来诊断动态上下文问题。

大多数 Dynamic Context 问题属于三类之一：时机不正确（在 Apply() 在对话开始前调用），组件配置错误（缺少 ConvaiCharacter 引用或必填字段为空），或者对 Reset() 会清除什么。请按下面的首轮排查清单逐项检查——大多数问题会在第 2 或第 3 步解决。

第一线排查

1

检查 Unity Console 中的警告

ConvaiDynamicContextCommand 每次都会记录带有完整验证消息的警告 Execute() 被跳过。打开 Console（Window → General → Console）并查找带有以下标记的消息 [ConvaiDynamicContextCommand].

如果看到警告，请在下面的 控制台日志参考 表中找到对应的确切消息并按列出的修复方法处理。

2

使用示例 UI 来隔离问题

在调试自己的集成之前，请先使用 SDK 内置的测试 UI 验证 Dynamic Context 系统本身是否正常工作。

预制体路径： Packages/com.convai.convai-sdk-for-unity/Prefabs/SampleDynamicContextUI.prefab

将其拖入场景，分配你的 ConvaiCharacter在 Inspector 中的组件。如果 设置状态 按钮发送一个已知值。如果角色通过示例 UI 正确回应，则问题出在你的集成代码中——而不是 Dynamic Context 系统本身。

3

验证角色引用是否已解析

选择 ConvaiDynamicContextCommand Inspector 中的组件。如果该 目标 部分显示黄色警告，则该组件找不到一个 ConvaiCharacter.

• 已启用 Auto Resolve Character： 请确认 ConvaiDynamicContextCommand 是位于 ConvaiCharacter 位于 同一个 GameObject.
• 已禁用 Auto Resolve Character： 请确认 角色 字段已分配引用。

4

检查该角色是否处于对话中

通过 Apply() 发送的上下文更新如果角色不在活动对话中就会被丢弃。Convai logger 会输出一条警告——启用 Convai 调试日志即可在 Unity Console 中看到它。

如果你正在调用 Apply() 在 Awake(), Start()，或者在会话连接之前调用，请改用 SetState 或 AddEvent 代替。这些方法会自动排队，并在对话开始时刷新。

5

检查反应模式

如果上下文更新已到达角色但它没有立即回应，请检查 反应模式 设置。

• 仅同步 ——上下文会被静默存储。角色会在下一次自然轮次中将其纳入。不会生成立即回复。这是预期行为。
• Auto ——Convai 决定是否回应。若要保证立即回应，请使用 立即响应.
• 立即响应 ——在更新后始终触发一次立即的 LLM 回合。

常见问题

症状	可能原因	修复
角色完全没有引用上下文更新	Apply() 在对话开始前调用	切换为 SetState 或 AddEvent ——它们会自动排队
角色在更新后没有立即回应	反应模式为 仅同步	将 反应模式 到 Auto 或 立即响应
On Execution Skipped 改为触发 执行后	验证失败——请查看 Console 警告	请查看 控制台日志参考 中的确切消息及修复方法
Inspector 中组件显示黄色警告	没有 ConvaiCharacter 已解析	启用 自动解析 并将两个组件放在同一个 GameObject 上，或者分配 角色 显式地
TryGetStateValue 返回 false 在 Apply()	Apply() 会绕过本地跟踪器	使用 SetState 如果该值需要可通过 TryGetStateValue
两条 上下文更新 针对一次 SetState 调用发送了消息	现有状态已更新——这是预期行为	不是 bug。请参阅 一次更新发送两条消息
角色在 Reset()	初始上下文或系统提示不会被 Reset()	请参见 Reset 未清除所有内容
角色仅在第一次回复中引用初始场景事实	InitialDynamicInfoKeepInContext 为 false （默认）	启用 Initial Dynamic Info Keep In Context on ConvaiCharacter
无法向同一个 GameObject 添加第二个 Command 组件	[DisallowMultipleComponent] 限制	将其他命令放到子 GameObject 上
SetStates 列表会产生验证警告	列表中存在重复的状态名称或空条目	删除重复项；确保每个条目都有非空名称

角色不引用上下文更新

当角色似乎完全不知道你发送的某个状态或事件时，请按以下顺序排查。

验证所使用的方法。 Apply() 发送的上下文更新如果角色不在活动对话中就会被丢弃。Convai logger 会发出警告（启用调试日志时可在 Console 中看到），但不会构建队列。请改用 SetState 或 AddEvent 代替——这些方法会自动排队，并在会话开启时刷新。

验证 Execute() 没有被跳过。 将 ConvaiDynamicContextCommand On Execution Skipped 事件绑定到一个临时的 Debug.Log 调用，以便在开发期间调试。如果它被触发，Console 会显示导致跳过的确切验证消息。

验证反应模式。 如果反应模式是 仅同步，角色已接收到更新，但不会立即生成回复——它会在下一次自然轮次中引用新状态。切换到 Auto 或 立即响应 如果需要立即确认。

Apply() 没有效果

Apply() 有两个行为与其他任何 IConvaiDynamicContext 方法不同：

• 没有对话前队列。 如果角色在 Apply() 被调用时不处于活动对话中，则该更新会立即被丢弃。Convai logger 会发出警告——启用 Convai 调试日志即可在 Unity Console 中看到。不会构建队列。请使用 SetState, AddEvent，或者若调用可能发生在会话开始前，则使用其他受跟踪的方法。
• 不会更新跟踪器。 Apply() 会直接发送到传输层，不会触及本地状态跟踪器。随后对 TryGetStateValue 对通过 Apply() 返回 false发送的键的调用 TryGetStateValue。如果该值需要可通过 SetState 代替。

Apply() 是供构造自身上下文文本的外部系统使用的高级逃生通道。对于所有标准上下文管理，请优先使用受跟踪的方法—— SetState, SetStates, AddEvent, RemoveState，以及 Reset ——它们会自动排队并保持本地跟踪器一致。

Reset 未清除所有内容

Reset() 仅作用于 运行时 Dynamic Context 层。有三类角色知识来源不在其范围内：

Initial Dynamic Info Text。 ……的内容 Initial Dynamic Info Text on ConvaiCharacter 会在连接时作为会话请求的一部分发送一次。 Reset() 不会重新发送，也无法清除它。结束并重新启动会话是更改连接时发送内容的唯一方法。

系统提示。 在 Convai 仪表板中写入角色系统提示的事实不属于 Dynamic Context 层。运行时没有任何 SDK 调用会影响它们。

会话内 LLM 记忆。 角色的语言模型会在同一会话中的多个轮次间保留对话上下文。 Reset() 会清除 Dynamic Context 跟踪器并向 Convai 发送 Reset 消息，但不会清除模型的会话内对话记忆。

一次更新发送两条消息

当你调用 SetState 当对一个已存在且值不同的状态执行 上下文更新 时，会有两个 RTVI 消息按顺序发送：

1. A Replace 携带完整规范上下文并将更新后的值就地替换的消息。
2. 一条 Append 携带人类可读差异的消息： “{name} 从 {oldValue} 变为 {newValue}”.

这是有意设计且不可配置的。Replace 让角色获得权威的完整信息；Append 则让它能在对话中自然提及这一变化。如果你在调试时监控网络流量，对于每次现有状态修改都应看到这一模式。

请参见 更新现有状态 有关完整序列的 Sync 行为和时机。

无法向同一个 GameObject 添加多个 command 组件

ConvaiDynamicContextCommand 被标记为 [DisallowMultipleComponent]。Unity 会阻止向同一个 GameObject 添加第二个实例。

将每个额外的命令放在 子 GameObject 的 NPC 的子对象上。在每个命令的 目标 部分中，禁用 自动解析角色 并为 NPC 的 ConvaiCharacter 显式设置——自动解析只会搜索同一个 GameObject，不会搜索父对象或子对象。

角色无响应

以下决策树涵盖了看起来没有效果的上下文更新的完整排查范围。

控制台日志参考

在 Dynamic Context 操作期间，以下消息会出现在 Unity Console 中。所有 ConvaiDynamicContextCommand 警告都以 [ConvaiDynamicContextCommand].

消息	来源	含义	修复
在这个 GameObject 上未找到 ConvaiCharacter。请分配一个，或禁用 Auto Resolve Character。	Execute() 验证	自动解析 已启用但没有 ConvaiCharacter 位于同一个 GameObject 上。	将命令移到 NPC 的 GameObject 上，或者禁用 自动解析 并分配 角色 显式地。
分配一个 ConvaiCharacter，或启用 Auto Resolve Character。	Execute() 验证	自动解析 已关闭且 角色 未分配。	分配 ConvaiCharacter 引用，或启用 自动解析.
Set State 需要一个非空的状态名称。	Execute() 验证	状态名称 字段为空或仅包含空白。	请输入非空的状态名称。
Set States 至少需要一个状态条目。	Execute() 验证	状态条目 列表为空。	至少添加一个 Name / Value 条目。
每个状态条目都需要非空名称。	Execute() 验证	一个或多个 状态条目 名称为空。	填写所有条目的名称。
状态条目包含重复名称“{name}”。	Execute() 验证	在 状态条目 中的两个条目共享相同的状态名称。实际名称会替换 {name} 在 Console 中的显示。	删除重复项或重命名它。
Add Event 需要非空的事件文本。	Execute() 验证	事件文本 字段为空或仅包含空白。	请输入事件文本。
Remove State 需要非空的状态名称。	Execute() 验证	状态名称 字段为空或仅包含空白。	请输入要移除的状态名称。
Raw Update 需要文本，除非模式为 Reset。	Execute() 验证	原始文本 为空且 原始模式 不是 Reset.	请输入文本，或设置 原始模式 到 Reset.

下一步

同步行为与时序动态上下文脚本 API