> 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).

# 动态上下文故障排查

当动态上下文更新似乎不起作用时，请使用此页面。先从下面四项检查开始，然后如果问题仍然存在，再查看各症状部分。

### 第一步检查

在深入查看详细症状之前，先执行这四项检查：

| 检查                     | 如何验证                                                                              | 它告诉你什么               |
| ---------------------- | --------------------------------------------------------------------------------- | -------------------- |
| 会话已连接                  | **获取聊天机器人连接状态** 返回 `已连接`                                                          | 网络刷新是否能到达 Convai     |
| 本地跟踪器已接受该值             | **获取上下文状态值** 返回预期的 `输出值` 之后立即 **设置上下文状态**                                         | 蓝图连线和 `名称` 引脚是否正确    |
| 在对话轮次之前刷新已完成           | 等待一个防抖周期（`ContextDebounceWindow`，默认 `0.5` 秒），或者将 `bFlushImmediately = true` 设为连接后 | 时间安排是否导致角色在更新到达前作出响应 |
| `ShouldRespond` 符合你的意图 | `从不` → `run_llm: "false"`; `Auto` → `run_llm: "auto"`; `始终` → `run_llm: "true"`   | 更新是否使用了你期望的连线值发送     |

{% stepper %}
{% step %}

#### 确认会话已连接

调用 **获取聊天机器人连接状态** 在 `Convai 聊天机器人` 组件。返回值应为 `已连接` ，然后再期望网络刷新到达 Convai。

默认的防抖更新在连接前就已暂存，会安全地排队在 `PendingContextBatch`中。会话连接后，它们会在防抖期限已过的第一个 tick 上刷新。这是预期行为，不是错误。
{% endstep %}

{% step %}

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

调用 **获取上下文状态值** 之后立即 **设置上下文状态** 并打印 `输出值` 引脚。如果 `输出值` 返回了预期值，则本地跟踪器已接受更新。

如果本地值正确，但运行时对话测试没有反映出来，请确认网络刷新已在测试轮次之前完成。
{% endstep %}

{% step %}

#### 让防抖窗口过去

除非 `bFlushImmediately` 为 `true`，插件会等待 `ContextDebounceWindow` 秒（默认 `0.5`）后，在刷新前等到最后一次暂存更新之后的
{% endstep %}

{% step %}

#### 检查 ShouldRespond 设置

如果更新已到达 Convai，但连线 `run_llm` 的值不是你想要的，请验证 `ShouldRespond` 在暂存更新的节点上。
{% endstep %}
{% endstepper %}

### 上下文更新看起来被忽略了

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

**症状：** 你调用了 `设置上下文状态` ，但在一次端到端运行时测试之前，测试没有反映该状态值。

**原因 1 — 更新到达时机晚于对话轮次。** 防抖计时器会在最后一次暂存更新后触发。如果玩家在计时器到期前说话，Convai 会在没有该更新的情况下处理这轮对话。

**修复：** 将更新更早发送到游戏流程中，或者在时序关键时将 `bFlushImmediately = true` bFlushImmediately

**验证：** **获取上下文状态值** 在本地返回预期值。如果确实如此，而角色仍然没有提及该状态，请在对话轮次前增加提前量，或者使用 `bFlushImmediately = true`.

***

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

**修复：** 如果此更新应使用不同的连线值，请使用 `ShouldRespond = Auto` 或 `ShouldRespond = Always` 用于该调用。保留 `从不` 用于只应更新上下文的背景事实。

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

***

**原因 3 — 在你期望网络刷新时，会话尚未连接。** 暂存的更新会在离线状态下累积，但直到连接加防抖之后才会到达 Convai。

**修复：** 检查 **获取聊天机器人连接状态** 在测试对话行为之前。

**验证：** **获取聊天机器人连接状态** 返回 `已连接` 在依赖它的测试轮次之前。

***

#### 移除上下文状态没有明显效果

**症状：** 你调用了 `移除上下文状态` 但角色仍然引用已移除的值。

**原因：** 移除已被暂存，但在对话轮次发生时尚未刷新，或者同一个事实存在于动态上下文跟踪器之外。

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

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

***

### 防抖时序带来的意外

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

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

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

**修复：** 无需修复。如果你需要分开发送，请将调用间隔放在防抖窗口之外。不建议在实时游戏中针对每次状态变化都发送单独的即时刷新。

**验证：** 等待一个防抖周期，并用 **获取上下文状态值**.

***

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

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

**原因：** 防抖窗口使刷新延迟到了对话轮次之后。

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

**验证：** 请确认 **获取聊天机器人连接状态** 为 `已连接` 并允许刷新在依赖的对话轮次之前完成。

***

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

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

**原因：** 底层字段 `ContextDebounceWindow` 是位于 `ContextMaxDebounceWindow` 是 **高级显示** 属性，位于 **Convai > DynamicContext**.

**修复：** 展开 **高级** 详情面板中的该部分，并查找 **上下文防抖窗口（秒）** 是位于 **最大防抖窗口（秒）**.

**验证：** 展开后，这两个标签都会可见 **高级**.

***

### ShouldRespond 误用

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

**症状：** 每次调用 `设置上下文状态` 用于 `PlayerHealth` 都以 `ShouldRespond = Auto` 或 `始终`.

**原因：** `ShouldRespond` 被设置为 `Auto` 或 `始终` 在 **设置上下文状态** 节点进行暂存。

**修复：** 使用 `ShouldRespond = Never` 用于背景状态。保留 `Auto` 或 `始终` 用于那些连线 `run_llm` 值应该为 `"auto"` 或 `"true"`.

**验证：** 该 **设置上下文状态** 节点，用于 `PlayerHealth` 具有 `ShouldRespond` 设置为 `从不`.

***

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

**症状：** 你调用了 `Add Context Event` 用于一个重要的上下文事件，但该更新没有使用 `run_llm` 你期望的值。

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

**修复：** 设置 `ShouldRespond = Always` 在更新应发送 `run_llm: "true"`时。使用 **是否在说话** 仅作为本地状态检查，当你编排自己的蓝图逻辑时。

**验证：** 暂时切换为 `ShouldRespond = Always` 单独测试，并确认更新是以 `run_llm` 设置为 `"true"`.

***

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

#### 重置动态上下文后，本地状态仍然出现

**症状：** 你调用了 `重置动态上下文`的 Actor，但 **获取上下文状态值** 仍返回 `true` 对于你期望清除的键。

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

**修复：** 在从空动态上下文开始时，先让重置刷新完成，再暂存新的状态值。

**验证：** **获取上下文状态值** 对已清除键的 `false` 在重置刷新后返回

***

#### 重置没有清除全部内容

**症状：** `重置动态上下文` 已完成，但相关运行时数据仍然出现在项目中。

**原因：** `重置动态上下文` 仅作用于 **运行时动态上下文跟踪器仅**。它会在发送 `Reset` `上下文更新`后清除已跟踪的状态和事件，但其他更新路径是分开的。

**修复：** 将 `DynamicEnvironmentInfo` 如果这些文本也需要更改，请显式更新。将动作和场景元数据通过各自的环境元数据路径进行更新。

**验证：** **获取上下文状态值** 返回 `false` 对已清除键返回，如果仍有任何数据，则通过相应的非跟踪器更新路径处理。

{% hint style="warning" %}
`重置动态上下文` 会清除本地状态跟踪器并发送一个 Reset `上下文更新`。它不会清除 `DynamicEnvironmentInfo` 或环境元数据。
{% endhint %}

***

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

**症状：** 你调用了 `重置动态上下文` 在 `BeginPlay`，然后暂存了新状态，但角色始终看不到新数据。

**原因：** `重置动态上下文` 会在第一次连接后的刷新时标记一个待处理的 `Reset` ，该项会在 **在** 暂存内容。无论是在 Reset 调用之前还是之后暂存的，只要处于同一个离线窗口中，这都适用于暂存更新。

**修复：** 连接后先让重置刷新完成，然后再暂存新的 **设置上下文状态** 或 **Add Context Event** 调用。

**验证：** 在第一次连接后的刷新之后， **获取上下文状态值** 返回 `false` 对那些本应已被清除的键。

***

### 上下文更新诊断流程

在完成第一步检查后使用此流程。沿着从本地跟踪器状态到连接状态、刷新时机以及预期的 `run_llm` 值来查看各分支。

```mermaid
flowchart TD
    A[角色未使用上下文更新] --> B{获取上下文状态值是否匹配？}
    B -- 否 --> C[检查蓝图节点连线和 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 -- Always --> L
```

### 下一步

{% content-ref url="/pages/752c51862623321d86861772e63c55db752c58da" %}
[同步行为和时序](/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 参考](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.