> 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          |
| 本地跟踪器已接受该值             | **获取上下文状态值** 返回预期的 `OutValue` 紧接着 **设置上下文状态**                                     | Blueprint 连线和 `名称` 引脚是否正确 |
| 在对话轮次之前刷新已完成           | 等待一个去抖周期（`ContextDebounceWindow`，默认 `0.5` 秒），或者设置 `bFlushImmediately = true` 在连接后 | 时序是否导致角色在更新到达之前就做出了响应     |
| `ShouldRespond` 符合你的意图 | `从不` → `run_llm: "false"`; `自动` → `run_llm: "auto"`; `始终` → `run_llm: "true"`     | 更新发送时所用的连线值是否符合你的预期       |

{% stepper %}
{% step %}

#### 确认会话已连接

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

在连接之前暂存的默认去抖更新会安全地排队于 `PendingContextBatch`。会话连接后，它们会在去抖截止时间已过的第一个 tick 时刷新。这是预期行为，不是错误。
{% endstep %}

{% step %}

#### 验证本地跟踪器是否接受了该值

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

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

{% step %}

#### 允许去抖窗口经过

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

{% step %}

#### 检查 ShouldRespond 设置

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

### 上下文更新似乎被忽略

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

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

**原因 1 — 更新在对话轮次之后才到达。** 去抖计时器会在最后一次暂存更新之后触发。如果玩家在计时器结束前开口，Convai 会在没有该更新的情况下处理这轮对话。

**修复：** 在游戏流程中更早发送更新，或者设置 `bFlushImmediately = true` ，当时序很关键时。

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

***

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

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

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

***

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

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

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

***

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

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

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

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

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

***

### 去抖时序意外

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

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

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

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

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

***

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

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

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

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

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

***

#### ContextMaxDebounceWindow 在 Details 面板中不可见

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

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

**修复：** 展开 **高级** 部分，然后查找 **Context Debounce Window (秒)** 和 **Max Debounce Window (秒)**.

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

***

### ShouldRespond 误用

#### 生命值更新发送 `run_llm` 出乎意料地

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

**原因：** `ShouldRespond` 设置为 `自动` 或 `始终` 在 **设置上下文状态** 节点一起暂存。

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

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

***

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

**症状：** 你调用了 `添加上下文事件` 用于一个重要的上下文事件，但该更新未使用 `run_llm` 你期望的值。

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

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

**验证：** 临时切换为 `ShouldRespond = Always` 单独测试，并确认更新是以以下方式发送的： `run_llm` 设置为 `"true"`.

***

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

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

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

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

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

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

***

#### 重置没有清除所有内容

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

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

**修复：** 更改 `DynamicEnvironmentInfo` 如果该文本也需要更改，请明确更新。通过各自的环境元数据路径更新动作和场景元数据。

**验证：** **获取上下文状态值** 返回 `false` 用于已清除的键，任何剩余数据都会通过相应的非跟踪器更新路径处理。

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

***

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

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

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

**修复：** 在连接后让重置刷新完成，然后再暂存新的 **设置上下文状态** 或 **添加上下文事件** 调用。

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

***

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

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

```mermaid
flowchart TD
    A[角色未使用上下文更新] --> 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 -- 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 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.