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

# 动态上下文故障排查

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

### 第一线排查

{% stepper %}
{% step %}

#### 检查 Unity Console 中的警告

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

如果看到警告，请在下面的 [控制台日志参考](#console-log-reference) 表中找到对应的确切消息并按列出的修复方法处理。
{% endstep %}

{% step %}

#### 使用示例 UI 来隔离问题

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

**预制体路径：** Packages/<code class="expression">space.vars.sdk\_package\_id</code>/Prefabs/SampleDynamicContextUI.prefab

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

{% step %}

#### 验证角色引用是否已解析

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

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

{% step %}

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

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

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

{% step %}

#### 检查反应模式

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

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

### 常见问题

| 症状                                        | 可能原因                                             | 修复                                                               |
| ----------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| 角色完全没有引用上下文更新                             | `Apply()` 在对话开始前调用                               | 切换为 `SetState` 或 `AddEvent` ——它们会自动排队                            |
| 角色在更新后没有立即回应                              | 反应模式为 `仅同步`                                      | 将 **反应模式** 到 `Auto` 或 `立即响应`                                     |
| **On Execution Skipped** 改为触发 **执行后**     | 验证失败——请查看 Console 警告                             | 请查看 [控制台日志参考](#console-log-reference) 中的确切消息及修复方法                |
| Inspector 中组件显示黄色警告                       | 没有 `ConvaiCharacter` 已解析                         | 启用 **自动解析** 并将两个组件放在同一个 GameObject 上，或者分配 **角色** 显式地             |
| `TryGetStateValue` 返回 `false` 在 `Apply()` | `Apply()` 会绕过本地跟踪器                               | 使用 `SetState` 如果该值需要可通过 `TryGetStateValue`                       |
| 两条 `上下文更新` 针对一次 `SetState` 调用发送了消息        | 现有状态已更新——这是预期行为                                  | 不是 bug。请参阅 [一次更新发送两条消息](#two-messages-for-one-update)            |
| 角色在 `Reset()`                             | 初始上下文或系统提示不会被 `Reset()`                          | 请参见 [Reset 未清除所有内容](#reset-did-not-clear-everything)             |
| 角色仅在第一次回复中引用初始场景事实                        | `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` 代替。

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

### 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 则让它能在对话中自然提及这一变化。如果你在调试时监控网络流量，对于每次现有状态修改都应看到这一模式。

请参见 [更新现有状态](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.md#updating-an-existing-state) 有关完整序列的 Sync 行为和时机。

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

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

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

### 角色无响应

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

```mermaid
flowchart TD
    A[角色未响应上下文更新] --> B{入口点是哪一个？}
    B -- ConvaiDynamicContextCommand --> C{OnExecuted 是否触发？}
    C -- 否 --> D[检查 Console 中的\n验证警告\n参见 Console 日志参考]
    C -- 是 --> E{反应模式？}
    B -- IConvaiDynamicContext 脚本 --> F{使用了哪种方法？}
    F -- Apply --> G{是否处于活动对话中？}
    G -- 否 --> H[Apply 被丢弃\n使用 SetState 或 AddEvent]
    G -- 是 --> E
    F -- SetState / AddEvent / 等 --> E
    E -- SyncOnly --> I[预期行为——不会立即回应\n切换到 Auto 或 ReactImmediately]
    E -- Auto 或 ReactImmediately --> J{更新是否到达后端？}
    J -- 是 --> K[检查角色系统提示\n和仪表板配置]
    J -- 不确定 --> L[使用示例 UI 预制体\n在隔离环境中验证传递]
```

### 控制台日志参考

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

### 下一步

{% content-ref url="/pages/bb1aef3496a2be08987c770aa7b8072e7d8c5cd6" %}
[同步行为和时序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.md)
{% endcontent-ref %}

{% content-ref url="/pages/5c3f9bcc544ac6f441fe54139ac1c670eeb5c958" %}
[动态上下文脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.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-unity-sdk/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.