> 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/command-component-reference.md).

# 命令组件参考

`ConvaiDynamicContextCommand` 是动态上下文的无代码入口。它是一个 `MonoBehaviour` 它封装一个上下文操作，并通过 Unity Inspector 暴露其全部配置。该组件被标记为 `[DisallowMultipleComponent]` —— Unity 会阻止向同一个 GameObject 添加第二个实例。要从一个 NPC 驱动多个命令，请将每个额外命令放在一个 **子 GameObject** （见 [每个 NPC 的多个命令](#multiple-commands-per-npc)).

通过以下方式添加该组件： **Convai → 动态上下文 → Convai Dynamic Context Command**.

<figure><img src="/files/4b3c1fb011093a8fa64d46440c3abe1febd5810f" alt="Unity Inspector showing the ConvaiDynamicContextCommand component with Target, Command, and Events sections collapsed on an NPC GameObject"><figcaption><p>ConvaiDynamicContextCommand Inspector——Target 部分用于解析哪个角色接收该命令，Command 定义操作类型及其参数，而 Events 则提供 On Executed 和 On Execution Skipped 回调。</p></figcaption></figure>

### Target 部分

控制哪个 `ConvaiCharacter` 对象执行该命令。

| 字段     | 类型                | 默认值    | 说明                                                                     |
| ------ | ----------------- | ------ | ---------------------------------------------------------------------- |
| 角色     | `ConvaiCharacter` | 无      | 显式角色引用。分配后优先于自动解析。用于命令所在 GameObject 与 NPC 不同的情况。                       |
| 自动解析角色 | `bool`            | `true` | 启用后，组件会调用 `GetComponent<ConvaiCharacter>()` 在 **同一个 GameObject** 在执行时。 |

**解析顺序：** 如果 **角色** 已分配，则无论 **自动解析角色** 设置如何。如果 **角色** 为空，且 **自动解析角色** 是否启用，组件都会搜索同一个 GameObject。如果两者都无法解析出角色， `Execute()` 将被跳过，并且 **On Execution Skipped** 会触发。

### Command 部分

#### 命令类型

该 **命令类型** 字段控制执行什么操作 `Execute()` 。一个组件 = 一种命令类型。

**设置状态**

更新一个受跟踪的状态。如果该状态不存在，则会创建它。如果值与当前值相同，则不会发送更新（幂等）。

| 字段   | 说明                           |
| ---- | ---------------------------- |
| 状态名称 | 状态标识符。不能为空，也不能仅包含空白字符。区分大小写。 |
| 状态值  | 要赋予的值。可以为空字符串。               |

**设置状态**

在一次调用中以原子方式更新多个受跟踪的状态。优先于多个顺序 `SetState` 命令，当多个值同时变化时——只生成一次规范重建，而不是多次。

| 字段            | 说明                                             |
| ------------- | ---------------------------------------------- |
| State Entries | Name / Value 对列表。至少必须有一项。所有名称都不能为空，并且在列表内必须唯一。 |

**添加事件**

追加一条按时间顺序排列的事件条目。事件不会被替换或去重——每次调用都会按调用顺序新增一行，位于规范上下文中所有状态之后。

| 字段         | 说明                     |
| ---------- | ---------------------- |
| Event Text | 发送给 Convai 的事件描述。不能为空。 |

**移除状态**

按名称移除一个受跟踪的状态，并向 Convai 发送更新后的规范上下文。如果该状态未被跟踪， `Execute()` 则完成而不发送任何更新。

| 字段   | 说明             |
| ---- | -------------- |
| 状态名称 | 要移除的状态名称。不能为空。 |

**Reset**

清除角色 Dynamic Context 中所有受跟踪的状态和事件，并向 Convai 发送 Reset 消息。不需要其他字段。

{% hint style="warning" %}
**Reset** 仅清除运行时 Dynamic Context 层。Initial Dynamic Info Text（在 `ConvaiCharacter`）中设置）不会重新注入，Convai 仪表板上的 system prompt 事实也不受影响。角色在会话中的 LLM 记忆也不会被清除。参见 [连接时的静态上下文](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/static-context-at-connection-time.md) 以了解 Reset 会清除和不会清除哪些内容的完整说明。
{% endhint %}

**原始更新**

直接将类型化上下文更新发送到传输层，绕过本地跟踪器。适用于在外部构造上下文文本的高级用例。

| 字段       | 说明                                                                           |
| -------- | ---------------------------------------------------------------------------- |
| Raw Text | 要发送的上下文文本。除非 Raw Mode 为 `Reset`.                                             |
| Raw Mode | `Append` —— 向现有上下文追加。 `Replace` —— 替换整个上下文。 `Reset` —— 清除所有上下文；Raw Text 被忽略。 |

{% hint style="danger" %}
**Raw Update 不会排队会话前更新。** 如果 `Execute()` 在会话激活之前被调用，则该更新会被丢弃。此外，通过 Raw Update 发送的值无法通过 `TryGetStateValue` 脚本 API 中的 **设置状态** 或 **添加事件** 代替。
{% endhint %}

### 反应模式

该 **反应模式** 字段控制在上下文更新送达后角色是否立即生成回复。

| 值                  | 行为                                                              |
| ------------------ | --------------------------------------------------------------- |
| `Auto`             | 由 Convai 决定该更新是否需要立即回复。 **默认用于 `ConvaiDynamicContextCommand`.** |
| `ReactImmediately` | 更新后始终触发一次立即的 LLM 回合。用于需要角色确认变更的更新。                              |
| `SyncOnly`         | 静默更新上下文。角色会在下一次自然轮次中纳入新信息。不生成立即回复。                              |

{% hint style="warning" %}
**组件默认值与脚本 API 默认值不同。** `ConvaiDynamicContextCommand` 默认 **反应模式** 到 `Auto` 适用于所有命令类型——包括 Set State 和 Set States。脚本 API 方法 `SetState` 是位于 `SetStates` 默认是 `SyncOnly`。如果你在 Inspector 和脚本控制之间切换，请确认反应模式符合预期。
{% endhint %}

### Events 部分

| 事件                   | 触发时机                                                 |
| -------------------- | ---------------------------------------------------- |
| 执行时                  | 在 `Execute()` 成功完成——命令已运行且上下文更新已发送。                  |
| On Execution Skipped | 当 `Execute()` 被调用但验证失败或角色解析失败。Unity Console 会显示确切原因。 |

连接 **On Execution Skipped** 到一个临时 `Debug.Log` 在开发期间用于捕获配置错误，而无需手动查看 Console。

### 每个 NPC 的多个命令

`[DisallowMultipleComponent]` 会阻止多个 `ConvaiDynamicContextCommand` 位于同一个 GameObject 上。要从一个 NPC 发送多个独立命令：

1. 在 NPC 下创建一个子 GameObject。
2. 添加 `ConvaiDynamicContextCommand` 到子对象。
3. 在 **目标** 部分， **禁用 Auto Resolve Character** —— 自动解析只会搜索同一个 GameObject。
4. 将 NPC 的 `ConvaiCharacter` 到 **角色** 字段显式拖入。
5. 对每个额外命令重复此操作。

每个子命令都是独立的——分别配置其命令类型、字段和反应模式。

### 验证警告

当 `Execute()` 因配置或验证失败而被跳过时，组件会在 Unity Console 中记录一条警告，并以前缀 `[ConvaiDynamicContextCommand]`。该 **On Execution Skipped** 事件也会触发。

| Console 消息                                            | 原因                                                      | 修复                                                     |
| ----------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| `在此 GameObject 上未找到 ConvaiCharacter。请分配一个，或禁用自动解析角色。` | **自动解析角色** 已启用但没有 `ConvaiCharacter` 位于同一个 GameObject 上。 | 将命令移动到 NPC 的 GameObject 上，或禁用 **自动解析** 并分配 **角色** 显式地。 |
| `请分配一个 ConvaiCharacter 或启用自动解析角色。`                    | **自动解析角色** 已禁用，并且 **角色** 未被分配。                          | 分配该 `ConvaiCharacter` 引用，或启用 **自动解析角色**.               |
| `Set State 需要一个非空状态名称。`                               | **状态名称** 为空或仅包含空白字符。                                    | 输入一个非空的状态名称。                                           |
| `Set States 至少需要一个状态条目。`                              | **State Entries** 列表为空。                                 | 至少添加一个 Name / Value 条目。                                |
| `每个状态条目都需要一个非空名称。`                                    | 一个或多个 **State Entries** 具有空白名称。                         | 填写所有条目名称。                                              |
| `状态条目包含重复名称“{name}”。`                                 | 两个或多个条目共享相同的状态名称。实际的重复名称会替换 `{name}` 在 Console 输出中的     | 移除或重命名重复条目。                                            |
| `Add Event 需要非空的事件文本。`                                | **Event Text** 为空或仅包含空白字符。                              | 输入事件描述。                                                |
| `Remove State 需要一个非空状态名称。`                            | **状态名称** 为空或仅包含空白字符。                                    | 输入要移除的状态名称。                                            |
| `除非模式为 Reset，否则 Raw Update 需要文本。`                     | **Raw Text** 为空，且 **Raw Mode** 不是 `Reset`.              | 输入上下文文本，或设置 **Raw Mode** 到 `Reset`.                    |

### 下一步

{% content-ref url="/pages/493c8451db0d99cc31b81e26c17158c645622f0e" %}
[动态上下文使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-usage-examples.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 %}

{% 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 %}


---

# 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/command-component-reference.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.