> 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-unity-sdk/features/dynamic-context/troubleshoot-dynamic-context.md).

# 排查动态上下文问题

修复 Convai Unity SDK 中常见的动态上下文问题，包括更新丢失、响应延迟，以及重置行为未清除所有内容。

中继器和跟踪器流程中的大多数 Dynamic Context 问题都属于以下三类之一：角色进入对话前就发起了调用、反应模式产生了意外响应，或 `ConvaiDynamicContextRelay` 无法解析 `ConvaiCharacter`。请按下方的一线排查清单逐项检查——大多数问题在前两三步内就能解决。

### 初步排查

{% stepper %}
{% step %}

#### 检查 Unity 控制台中的警告

Dynamic Context 警告由 `ConvaiCharacter` 记录（前缀为角色名称），也由 `ConvaiDynamicContextRelay`记录。打开控制台（**Window → General → Console**），查找提及 `Dynamic context` 或 `Assign a ConvaiCharacter`.

如果看到警告，请在下方的 [控制台日志参考](#console-log-reference) 表格中查找完全相同的消息，并按列出的说明修复。
{% endstep %}

{% step %}

#### 使用 Sample Debug Hub 隔离问题

在调试自己的集成之前，请先确认 Dynamic Context 本身能正常工作。从 Package Manager 导入 **LipSync Sample** 并打开其中的场景——该示例包含一个 **Sample Debug Hub** ，其中有一个 **Context** 抽屉，可向场景中的 `ConvaiCharacter` 发送状态、事件和关注对象更新，无需连接自己的 UI。

如果角色通过 Debug Hub 能正确响应，问题就在你自己的中继器或脚本设置中，而不在 Dynamic Context 本身。
{% endstep %}

{% step %}

#### 确认角色引用已解析

在 Inspector 中选择 `ConvaiDynamicContextRelay` 组件。

* **已启用 Auto Resolve Character：** 确认 `ConvaiDynamicContextRelay` 和 `ConvaiCharacter` 位于 **同一个 GameObject 上**.
* **已禁用 Auto Resolve Character：** 确认 **Character** 字段已分配引用。

如果两种方式都无法解析角色，每次调用都会触发 **On Skipped** 并记录日志 `Assign a ConvaiCharacter or enable Auto Resolve Character.`
{% endstep %}

{% step %}

#### 检查角色是否已进入对话

受跟踪的调用 — `SetState`, `SetStates`, `AddEvent`, `RemoveState`, `Reset`, `SetCurrentAttentionObject`，以及 `ClearCurrentAttentionObject` — 会立即在本地暂存，即使对话尚未开始。角色就绪后，暂存的批次会自动发送到 Convai，因此在 `Awake()` 或 `Start()` 中调用时无需额外处理。

`Apply()` 是个例外：它不会暂存。如果角色尚未进入对话时进行调用，该调用会被丢弃，Convai 会记录 `Cannot apply raw dynamic context update: not in conversation`.
{% endstep %}

{% step %}

#### 检查批次窗口和反应模式

暂存受跟踪的更改后，SDK 会等待 `ConvaiCharacter.DynamicContextBatchDelaySeconds` — 默认值为 0.5 秒 — 然后再发送，因此短时间内的多次更改会合并为一次更新。调用 `Flush()` （在 `IConvaiDynamicContext`上），或在中继上启用 **立即刷新** ，即可无需等待直接发送暂存的更改。

如果角色在你预期 `Silent` 会抑制回复时仍作出了回应，很可能是同一批次窗口内暂存的另一项更改请求了更强烈的反应 — `MustRespond` 优先级高于 `Auto`，而 `Silent`的优先级又高于 Silent，对整个批次都适用。
{% endstep %}
{% endstepper %}

### 常见问题

| 症状                                                    | 可能原因                                                                          | 解决方法                                                                      | 验证                                                |
| ----------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| 角色从未引用通过 `SetState`                                   | 发送的状态 `新值与状态的当前值相同 —` 值未发生变化时，SetState                                        | 不会执行任何操作 `先确认值确实发生了变化；使用` 读取当前值                                           | `TryGetStateValue` 使用真正不同的值调用后，会返回新值              |
| 在 `Awake()` 或 `Start()` 似乎没有效果                        | 预期行为 — 已跟踪的调用会暂存在本地，并在角色就绪后自动发送                                               | 已跟踪的方法无需执行任何操作；避免在对话开始前调用 `Apply()` ，因为它不会暂存更新                            | 对话开始后不久，角色的回复中会出现该状态或事件                           |
| `ConvaiDynamicContextRelay` 触发 **在跳过时** 而不是 **在排队时**  | 否 `ConvaiCharacter` 已解析 — **自动解析角色** 已禁用，且未 **角色** 赋值，或者中继器位于错误的 GameObject 上 | 启用 **自动解析角色** 并将中继器放在 NPC 的 GameObject 上，或明确指定 **角色** 。                   | **在排队时** 触发，且控制台未显示 `Assign a ConvaiCharacter` 警告 |
| **在排队时** 触发，但角色始终未引用该更新                               | 空状态名称或 `null` 值在分发后未通过验证 — **在排队时** 表示已分发，不代表该值已被接受                           | 检查控制台中的验证警告；请参阅 [控制台日志参考](#console-log-reference)                         | 该更新会出现在角色的上下文中，且没有记录验证警告                          |
| 更新后角色未立即回应                                            | 该调用所请求的反应模式为 `Silent`                                                         | 使用 `Auto` 或 `MustRespond` — 在中继器的 **反应模式** 字段中设置，或作为脚本调用的 `reaction` 参数传入 | 角色会在下一个回合引用该更新（`自动`/`静默`) 或立即响应（`必须响应`)           |
| `添加事件` 通过中继发送时，不会使用其脚本默认值 `自动`                        | 中继始终会为每次调用显式传递自己的 **反应模式** 字段，从而覆盖该方法的脚本默认值                                   | 将中继的 **反应模式** 字段设为 `自动` 或 `必须响应` （如果事件应该触发回复）                             | 角色的反应与中继配置的 **反应模式**相符，而不是 `添加事件`的脚本默认值           |
| 即使调用使用了 `静默`                                          | 同一批处理窗口中暂存的另一次调用请求了 `自动` 或 `必须响应` ——批处理中最强的反应模式会应用于整个批次                       | 需要独立反应的调用之间应间隔超过批处理窗口，或者在它们之间调用 `Flush()` 批次按预期的反应模式发送                    | 批次按预期的反应模式发送                                      |
| `Apply()` 似乎没有效果                                      | `Apply()` 会绕过本地跟踪器且不会暂存；在没有活动对话时调用会被丢弃，并显示警告                                  | 请使用 `SetState`, `AddEvent`或其他受跟踪的方法——它们会自动暂存                              | 更新会显示在角色的下一条回复中                                   |
| `TryGetStateValue` 在 `Apply()` 之后返回 `false`           | `Apply()` 永远不会更新本地跟踪器                                                         | 请使用 `SetState` 如果必须能够通过 `TryGetStateValue`                                | `TryGetStateValue` 返回 `true` 切换到……后 `SetState`    |
| 重置后，Character 仍引用初始场景事实 `Reset()`                     | 默认 `Reset()` 仅清除运行时追踪器 — 初始动态信息文本、系统提示词事实和会话内 LLM 记忆均不受影响                     | 调用 `Reset(removeStatic: true)` 以同时请求 Convai 移除该会话的静态初始上下文                 | 角色不再引用仅存在于静态初始上下文中的事实                             |
| 无法向同一个 GameObject 添加第二个 `ConvaiDynamicContextRelay` 。 | `[DisallowMultipleComponent]` 限制                                              | 在子 GameObject 上放置其他中继器，禁用 **自动解析角色**，并明确指定 **角色** 明确地                     | 每个中继器都独立作用于分配给它的角色                                |

### `Apply()` 丢弃了我的更新

`Apply()` 是唯一不会暂存的 Dynamic Context 入口点。与 `SetState`, `AddEvent`以及其他受跟踪的方法不同，如果角色当前未处于活动对话中，调用会立即被丢弃——Convai 会记录 `Cannot apply raw dynamic context update: not in conversation` 并且不会将更新排入队列，以便在对话开始后发送。

{% hint style="warning" %}
仅在 `Apply()` 适用于高级场景：在外部构建上下文文本，或将上下文更新与 action-config 补丁结合。对于可能在对话开始前运行的任何操作，请使用 `SetState`, `AddEvent`，或其他受跟踪的方法——它们会自动暂存。
{% endhint %}

`Apply()` 也会完全绕过本地跟踪器：通过 `Apply()` 发送的值不会更新 `TryGetStateValue` 可读取的状态。完整的验证警告列表，请参阅脚本 API 参考中的 [`Apply`](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md#apply) 。

### `Reset()` 保留不变

调用 `Reset()` 不带参数时，只会清除运行时 Dynamic Context 跟踪器中的内容——所有已跟踪的状态和事件。它不会影响另外三个角色知识来源：

* **初始 Dynamic Info 文本**，在连接时通过 `ConvaiCharacter`.
* **系统提示词事实** （在 Convai 控制面板中配置）。
* **会话内 LLM 记忆** （模型会在多轮对话中保留）。

调用 `Reset(removeStatic: true)` 还会请求 Convai 移除当前会话中角色的静态初始动态上下文。系统提示词事实和会话内记忆仍不受影响——没有任何运行时调用可以清除它们。有关如何配置静态初始上下文，请参阅 [连接时的静态上下文](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/static-context-at-connection-time.md) 。

### 角色没有响应

以下决策树涵盖了上下文更新看似无效时的完整故障排查流程。

```mermaid
flowchart TD
    A[角色未响应上下文更新] --> B{使用了哪个入口点？}
    B -- ConvaiDynamicContextRelay --> C{是否触发了 On Queued？}
    C -- 否，触发了 On Skipped --> D[检查 Console 中是否有\nAssign a ConvaiCharacter 警告]
    C -- 是 --> E{使用了哪个方法？}
    B -- IConvaiDynamicContext 脚本 --> E
    E -- Apply --> F{是否正在进行对话？}
    F -- 否 --> G[操作已丢弃，并显示警告\n请改用 SetState 或 AddEvent]
    F -- 是 --> H{此批次的反应模式是什么？}
    E -- SetState / AddEvent / 等 --> H
    H -- Silent --> I[符合预期：不会立即响应\n检查同一批次中是否有更强烈的反应]
    H -- Auto 或 MustRespond --> J{更新是否已送达 Convai？}
    J -- 是 --> K[检查角色系统提示词\n和控制面板配置]
    J -- 不确定 --> L[使用 Sample Debug Hub\n单独验证是否送达]
```

### 控制台日志参考

执行 Dynamic Context 操作时，以下消息会显示在 Unity Console 中。

| 消息                                                             | 来源                                                                        | 含义                                                                                                      | 解决方法                                                                                          | 验证                                             |
| -------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `Assign a ConvaiCharacter or enable Auto Resolve Character.`   | `ConvaiDynamicContextRelay`                                               | 未 `ConvaiCharacter` 已为此次调用解析。                                                                           | 启用 **Auto Resolve Character** 并将中继组件放到角色的 GameObject 上，或明确指定 **角色** 。                         | 警告不再出现，且会触发 `On Queued` 而非 `On Skipped`.       |
| `Dynamic context state name cannot be empty`                   | `ConvaiCharacter.DynamicContext` — `SetState`, `SetStates`, `RemoveState` | 状态名称为空或仅包含空白字符。                                                                                         | 请传入非空且不全为空白字符的状态名称。                                                                           | 调用不再记录警告，并且该状态会显示在角色的上下文中。                     |
| `Dynamic context state '{name}' cannot use a null value`       | `ConvaiCharacter.DynamicContext` — `SetState`, `SetStates`                | 传入给 `{name}` 的值为 `null`。允许使用空字符串； `null` 但不允许使用                                                         | 请传入空字符串，而不是 `null`，或者提供一个实际值。                                                                 | 调用不再记录警告，并且 `{name}` 会更新为预期值。                  |
| `Cannot set empty dynamic context states`                      | `ConvaiCharacter.DynamicContext` — `SetStates`                            | 传入给 `SetStates` 的字典为 `null` 或不包含任何条目。                                                                   | 请传入至少包含一组名称/值对的字典。                                                                            | 调用不再记录警告，并且所有传入的状态都会显示在角色的上下文中。                |
| `Dynamic context event text cannot be empty`                   | `ConvaiCharacter.DynamicContext` — `AddEvent`                             | 事件文本为空或仅包含空白字符。                                                                                         | 请传入非空事件文本。                                                                                    | 调用不再记录警告，并且事件行会显示在角色的上下文中。                     |
| `Dynamic context attention object cannot be null`              | `ConvaiCharacter.DynamicContext` — `SetCurrentAttentionObject`            | 注意对象参数为 `null`.                                                                                         | 请传入一个 `string` 对象名称或 `ConvaiActionObjectDefinition` 引用，或者改为调用 `ClearCurrentAttentionObject` 。 | 此调用不再记录警告，角色也会引用预期对象。                          |
| `Cannot apply raw dynamic context update: not in conversation` | `ConvaiCharacter.DynamicContext` — `Apply`                                | 调用 `Apply` 时，角色未处于活动对话中。                                                                                | 对于可能在对话开始前发生的更新，请使用 `SetState`, `AddEvent`或其他受跟踪的方法。                                          | 受跟踪的方法调用会成功，并且对话准备就绪后，更新会发送到角色。                |
| `Connection not ready for {purpose}`                           | `ConvaiCharacter.DynamicContext` — 内部发送路径                                 | 传输层已存在，但在分批发送暂存数据、调用 `Reset`或 `Apply` 尝试发送时，连接尚未就绪。 `{purpose}` 用于说明正在发送的内容，例如 `dynamic context batch`. | 请确认角色已完全连接（`IsInConversation`），再依赖即时送达；连接稳定后重试。                                               | 此消息将不再出现，且分批数据、重置或 `Apply` 调用会在下次尝试时送达 Convai。 |

### 场景元数据未发送（已在 SDK 4.3.0 中修复）

{% hint style="info" %}
SDK 4.3.0 修复了待发送的场景元数据可能无法送达 Convai 的错误——CHANGELOG 中将此项记为“修复了待发送的场景元数据未被刷新发送的问题”。如果项目使用的是 SDK 4.3.0 或更高版本，则这不再是现存问题。如果场景元数据仍似乎未能送达角色，请先确认 SDK 软件包版本，再将其视为新问题。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/743bcc7de155496cbbf02a52a5577aee99f28aab" %}
[中继组件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/relay-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/5c3f9bcc544ac6f441fe54139ac1c670eeb5c958" %}
[动态上下文脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/bb1aef3496a2be08987c770aa7b8072e7d8c5cd6" %}
[同步行为与时序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.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-unity-sdk/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.
