> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md).

# 排查动态上下文问题

修复动态上下文更新到达过晚、触发意外响应，或在刷新或重新连接后看似被忽略的问题。

当动态上下文更新似乎未生效时，请参阅此页面。先执行以下四项检查，如果问题仍然存在，再根据症状查看相应章节。

### 初步检查

在深入排查具体症状之前，请先执行以下四项检查：

| 检查项                    | 验证方法                                                                                   | 说明                    |
| ---------------------- | -------------------------------------------------------------------------------------- | --------------------- |
| 会话已连接                  | **Get Chatbot Connection State** 返回 `Connected`                                        | 网络刷新能否到达 Convai       |
| 本地跟踪器已接受该值             | **Get Context State Value** 返回预期的 `OutValue` ，且在执行以下操作后立即返回： **Set Context State**     | 蓝图连线和 `Name` 引脚是否正确   |
| 刷新在对话轮次开始前已完成          | 等待一个防抖周期（`ContextDebounceWindow`，默认为 `0.5` 秒），或设置 `bFlushImmediately = true` ，并在连接后应用  | 时序问题是否导致角色在更新到达之前作出响应 |
| `ShouldRespond` 符合你的意图 | `Never` → `run_llm: "false"`; `Auto` → `run_llm: "auto"`; `Always` → `run_llm: "true"` | 更新发送时使用的传输值是否符合预期     |

{% stepper %}
{% step %}

#### 确认会话已连接

在 **Get Chatbot Connection State** 上调用 `Convai Chatbot` 组件。返回值应为 `Connected` ，之后网络刷新才能到达 Convai。

连接前暂存的默认防抖更新会安全地排入 `PendingContextBatch`。会话连接后，这些更新会在防抖期限到期后的第一个 tick 刷新。这是预期行为，并非错误。
{% endstep %}

{% step %}

#### 验证本地跟踪器已接受该值

调用 **获取上下文状态值** 紧接着 **设置上下文状态** 并打印 `OutValue` 引脚。如果 `OutValue` 返回预期值，则本地跟踪器已接受此更新。

如果本地值正确，但运行时对话测试未反映该值，请确认测试轮次开始前网络刷新已完成。
{% endstep %}

{% step %}

#### 等待防抖时间窗口结束

除非 `bFlushImmediately` 为 `true`，否则插件会在最后一次暂存更新后等待 `ContextDebounceWindow` 秒（默认值为 `0.5`），然后再执行刷新。开始依赖新上下文的对话轮次之前，请至少等待一个完整的防抖周期。
{% endstep %}

{% step %}

#### 检查 ShouldRespond 设置

如果更新已到达 Convai，但线上的 `run_llm` 值与预期不符，请检查暂存该更新的节点上的 `ShouldRespond` 设置。
{% endstep %}
{% endstepper %}

### 上下文更新似乎未生效

#### 运行时对话测试未反映状态

**症状：** 你在端到端运行时测试前调用了 `Set Context State` ，但测试未反映该状态值。

**原因 1 — 更新在对话轮次之后才到达。** 防抖计时器会在最后一次暂存更新后触发。如果玩家在计时器结束前说话，Convai 处理该轮对话时就不会包含此更新。

**解决方法：** 在游戏流程中更早发送更新，或者在时机至关重要时设置 `bFlushImmediately = true` 。

**验证：** **Get Context State Value** 在本地返回预期值。如果返回了预期值，但角色仍未提及该状态，请提前更多时间发送更新，或使用 `bFlushImmediately = true`.

***

**原因 2 — `ShouldRespond` 为 `Never`，因此该更新使用了 `run_llm: "false"`.**

**解决方法：** 如果此更新应使用不同的线上值，请使用 `ShouldRespond = Auto` 或 `ShouldRespond = Always` 用于该调用。保持 `Never` 用于只需更新上下文的背景信息。

**验证：** 确认节点引脚使用预期的 `ShouldRespond` 值，然后再暂存更新。

***

**原因 3 — 你预期网络刷新时，会话尚未连接。** 暂存的更新会在离线时累积，但只有连接后经过防抖等待，才会发送到 Convai。

**解决方法：** 在测试对话行为前，检查 **获取聊天机器人连接状态** 。

**验证：** **获取聊天机器人连接状态** 在依赖该状态的测试轮次开始前， `Connected` 。

***

#### 移除上下文状态没有可见效果

**症状：** 你调用了 `Remove Context State` ，但角色仍然引用已移除的值。

**原因：** 移除操作已暂存，但对话轮次发生时尚未刷新；或者同一条信息也存在于动态上下文跟踪器之外。

**解决方法：** 在聊天机器人已连接后，将 `bFlushImmediately = true` 设为 **移除上下文状态** 调用的参数。如果确认刷新后该值已从跟踪器中消失，请检查此动态上下文页面之外、项目特有的其他上下文来源。

**验证：** **获取上下文状态值** 对已移除的键返回 `false` 。

***

### 防抖时序与预期不符

#### 多次快速更新合并为一次刷新

**症状：** 你在单个 tick 中调用了 `Set Context State` 十次，但只观察到一次动态上下文发送。

**原因：** 这是预期的防抖行为。在 `ContextDebounceWindow` 时间窗口内的快速更新会合并为一次刷新。

**解决方法：** 无需解决。如果需要分别发送，请将调用间隔拉长至超出防抖窗口。不建议在实时游戏中每次状态变化都立即单独刷新。

**验证：** 等待一个防抖周期，并使用以下方法确认最终的本地值 **获取上下文状态值**.

***

#### 快速对话轮次后，更新到达得太晚

**症状：** 游戏事件推送状态更新后，刷新尚未完成，测试轮次便立即开始。

**原因：** 防抖窗口导致刷新延迟，晚于对话轮次。

**修复：** 在上下文更新调用中将 `bFlushImmediately = true` 设为 true，或者更早推送更新（例如，在进入区域时，而不是在对话开始时）。对于重要事件， **添加上下文事件** 使用 `ShouldRespond = Always` 发送 `run_llm: "true"`.

**验证：** 确认 **获取聊天机器人连接状态** 为 `Connected` 并在依赖它的对话轮次开始前，等待刷新完成。

***

#### “ContextMaxDebounceWindow”在“详情”面板中不可见

**症状：** 您想调整防抖上限，但找不到 `ContextMaxDebounceWindow`.

**原因：** 底层字段 `ContextDebounceWindow` 和 `ContextMaxDebounceWindow` 是 **高级显示** 下的属性 **Convai > DynamicContext**.

**修复方法：** 展开 **高级** 部分，然后在“细节”面板中查找 **上下文防抖窗口（秒）** 和 **最大防抖窗口（秒）**.

**验证：** 展开后两个标签均可见 **高级**.

***

### 误用 ShouldRespond

#### 健康状态更新发送 `run_llm` 意外地

**症状：** 每次调用 `设置上下文状态` （针对  `PlayerHealth` ）暂存时使用了  `ShouldRespond = Auto`  或  `Always`.

**原因：** `ShouldRespond`  设置为  `Auto`  或  `Always` ，位于 **设置上下文状态** 节点上。

**解决方法：** 对后台状态使用  `ShouldRespond = Never` 。将  `Auto`  或  `Always`  保留给传输时  `run_llm`  值应为  `"auto"`  或  `"true"`.

**验证：** 针对  **设置上下文状态**  节点中的  `PlayerHealth` ，其  `ShouldRespond`  设置为  `Never`.

***

#### 事件更新未发送预期的  `run_llm`

**现象：** 你针对一个重要的上下文事件调用了  `添加上下文事件` ，但更新未使用你预期的  `run_llm`  值。

**原因：** `ShouldRespond`  未设置为你预期的枚举值，或者同一防抖窗口中暂存的另一项改变了聚合优先级。

**解决方法：** 设置 `ShouldRespond = Always` 何时应发送更新 `run_llm: "true"`。使用 **Is Talking** 仅在编排自己的 Blueprint 逻辑时，作为本地状态检查使用。

**验证：** 暂时单独切换为 `ShouldRespond = Always` 并确认更新已发送，且 `run_llm` 设置为 `"true"`.

***

### 重置动态上下文并重新连接

#### 重置动态上下文后，本地状态仍然存在

**症状：** 你调用了 `Reset Dynamic Context`，但 **Get Context State Value** 仍会返回 `true` ，而你原本预期该键会被清除。

**原因：** 重置尚未完成刷新，或者在调用重置后又暂存了新状态。

**解决方法：** 从空的动态上下文开始时，先等待重置刷新完成，再暂存新的状态值。

**验证：** **Get Context State Value** 对于已清除的键，会在重置刷新后返回 `false` 。

***

#### 重置未能清除所有内容

**症状：** `Reset Dynamic Context` 已完成，但项目中仍会显示相关运行时数据。

**原因：** `Reset Dynamic Context` 仅作用于 **运行时动态上下文跟踪器**。它会在发送 `Reset` `context-update`后清除已跟踪的状态和事件，但其他更新途径彼此独立。

**解决方法：** 如果还需要更改相应文本，请明确修改 `DynamicEnvironmentInfo` 。通过各自的环境元数据路径更新动作和场景元数据。

**验证：** **Get Context State Value** 返回 `false` 对于已清除的键，剩余数据则通过相应的非跟踪器更新路径处理。

{% hint style="warning" %}
`Reset Dynamic Context` 会清除本地状态跟踪器并发送一条 Reset `context-update`。它不会清除 `DynamicEnvironmentInfo` 或环境元数据。
{% endhint %}

***

#### 离线 Reset 后暂存的更新消失

**症状：** 你在 `Reset Dynamic Context` 中调用了 `BeginPlay`，随后暂存了新状态，但角色始终看不到新数据。

**原因：** `Reset Dynamic Context` 会标记一个待处理的 `Reset` ，并在连接后首次刷新时触发，且在已暂存内容之后执行。无论这些更新是在离线期间的 Reset 调用之前还是之后暂存的，此规则都适用。 **在** 连接后首次刷新时触发。对于同一离线时段内暂存的更新，无论它们是在 Reset 调用之前还是之后暂存的，这一行为都适用。

**解决方法：** 连接后先让重置刷新完成，然后再调用新的 **Set Context State** 或 **Add Context Event** 。

**验证：** 连接后首次刷新完成后， **Get Context State Value** 对于本应已清除的键，返回 `false` 。

***

### Context 更新诊断流程

完成第一轮检查后，使用此流程。按照分支依次检查本地跟踪器状态、连接状态、刷新时机，以及预期的 `run_llm` 值。

```mermaid
flowchart TD
    A[角色未使用 context update] --> B{Get Context State Value 是否匹配？}
    B -- 否 --> C[检查 Blueprint 节点连线和 Name 引脚]
    B -- 是 --> D{Get Chatbot Connection State 是否为 Connected？}
    D -- 否 --> E[等待连接，或检查 Start Session 设置]
    D -- 是 --> F{回合开始前是否已完成刷新？}
    F -- 否 --> G[使用 bFlushImmediately，或提前推送更新]
    F -- 是 --> H{ShouldRespond 的值是什么？}
    H -- Never --> I[如果 run_llm 应请求处理，则使用 Auto 或 Always]
    H -- Auto --> J{需要 run_llm 为 true 吗？}
    J -- 是 --> K[使用 Always]
    J -- 否 --> L[在此跟踪器之外检查运行时上下文]
    H -- 始终 --> L
```

### 后续步骤

{% content-ref url="/pages/752c51862623321d86861772e63c55db752c58da" %}
[同步行为与时序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/sync-behavior-and-timing.md)
{% endcontent-ref %}

{% content-ref url="/pages/a80705d8480f2f63dc8b84ea2e437c9dac45b7c5" %}
[动态上下文 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-blueprint-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
