> 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/unity-plugin-beta-overview/features/dynamic-context/command-component-reference.md).

# 命令组件参考

## Convai 动态上下文命令：检视器完整参考

`ConvaiDynamicContextCommand` 是动态上下文的无代码入口。它是一个 `MonoBehaviour` 它封装了一次上下文操作——选择命令类型、填写参数并调用 `Execute()` 可从任何 `UnityEvent` 来源触发。该组件专为需要通过按钮、过场动画、触发体或动画事件来驱动角色感知，而无需修改 C# 脚本的设计师和技术美术人员而设计。

本页记录了该组件公开的每个部分、字段、命令类型、验证警告和事件。

{% hint style="info" %}
`ConvaiDynamicContextCommand` 被标记为 `[DisallowMultipleComponent]`，因此每个 GameObject 只能存在一个实例。如果你需要在同一个 NPC 上使用多个独立的上下文命令，请将其他命令放在子 GameObject 上。
{% endhint %}

## 添加该组件

在 Unity 检视器中，点击 **添加组件** 并导航到：

**Convai → 动态上下文 → Convai Dynamic Context Command**

该组件在检视器中分为三个部分： **目标**, **命令**，以及 **事件**.

<figure><img src="/files/4b3c1fb011093a8fa64d46440c3abe1febd5810f" alt=""><figcaption></figcaption></figure>

## 目标部分

目标部分控制由哪个 `ConvaiCharacter` 对象执行该命令。

<table><thead><tr><th width="213">字段</th><th width="158.5">类型</th><th width="118.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>角色</strong></td><td><code>ConvaiCharacter</code></td><td>无</td><td>可选的显式角色引用。当命令所在的 GameObject 不是 NPC 本身时请指定此项——例如场景中单独的触发体或 UI 元素。</td></tr><tr><td><strong>自动解析角色</strong></td><td><code>bool</code></td><td><code>true</code></td><td>启用后，组件会通过 <code>ConvaiCharacter</code> 在同一 GameObject 上查找一个 <code>GetComponent&#x3C;ConvaiCharacter>()</code>。禁用此项并显式指定 <strong>角色</strong> ，当命令位于不同的 GameObject 上时。</td></tr></tbody></table>

**角色解析顺序：** 如果 **角色** 已分配，则始终使用它，无论 **自动解析角色** 设置如何。如果 **角色** 未分配，并且 **自动解析角色** 已启用，组件会搜索同一 GameObject。

## 命令部分

该 **命令类型** 下拉菜单选择要执行的操作 `Execute()` 。下拉菜单下方显示的字段会根据所选类型而变化。

### SetState

更新角色上的单个已跟踪状态。如果该状态不存在，则会创建它。如果它已存在且值相同，则不会发送更新——该操作是幂等的。

<table><thead><tr><th width="215.49993896484375">字段</th><th width="165">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>状态名称</strong></td><td><code>""</code></td><td>要设置的状态名称。不能为空且不能仅包含空白字符。</td></tr><tr><td><strong>状态值</strong></td><td><code>""</code></td><td>要赋予的值。空字符串是有效值。</td></tr><tr><td><strong>Reaction</strong></td><td><code>Auto</code></td><td>控制角色是否立即生成新的响应。参见下方的反应模式。</td></tr></tbody></table>

### SetStates

在一次原子操作中更新多个已跟踪状态。当多个值同时变化时使用此项——它可以避免重复的规范重建，并向角色发送更干净的批量更新。

<table><thead><tr><th width="166.5">字段</th><th width="138.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>State Entries</strong></td><td>空列表</td><td>一个可重新排序的名称/值对列表。每个条目都有一个 <strong>名称</strong> 是位于 <strong>值</strong> 字段。拖动条目可重新排序；顺序会影响任何新状态在规范上下文中的插入顺序。</td></tr><tr><td><strong>Reaction</strong></td><td><code>Auto</code></td><td>应用于整个批次。</td></tr></tbody></table>

{% hint style="warning" %}
列表必须至少包含一个名称非空且不只包含空白字符的条目。列表中的重复名称将阻止 `Execute()` ，并在检视器中显示验证警告。
{% endhint %}

### AddEvent

向角色的上下文追加一个按时间顺序排列的事件。事件不会被替换或去重——它们会在所有已跟踪状态之后按顺序累积。

<table><thead><tr><th width="182">字段</th><th width="190.00006103515625">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>Event Text</strong></td><td><code>""</code></td><td>要追加的事件文本。不能为空且不能仅包含空白字符。</td></tr><tr><td><strong>Reaction</strong></td><td><code>Auto</code></td><td>在 <code>Auto</code>，由服务器决定该事件是否需要角色立即响应。请使用 <code>ReactImmediately</code> 当事件重要到需要角色立即确认时。</td></tr></tbody></table>

### RemoveState

按名称移除一个已跟踪状态。移除后，规范上下文会被重建，并作为替换操作发送给角色。

<table><thead><tr><th width="166.49993896484375">字段</th><th width="136">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>状态名称</strong></td><td><code>""</code></td><td>要移除的状态名称。必须与现有状态名称完全匹配（区分大小写）。</td></tr></tbody></table>

{% hint style="info" %}
**移除状态** 在检视器中不提供反应字段。移除始终会在内部触发一次规范的替换同步，检视器中的说明为： *“移除状态会重建已跟踪的规范上下文，并且不使用反应模式。”*
{% endhint %}

### Reset

清除角色动态上下文中的所有已跟踪状态和事件。这是当前会话运行时上下文层的硬重置。

此命令类型没有可配置字段。清除本地跟踪器后，会向角色发送一条重置消息。

{% hint style="info" %}
**Reset** 会忽略反应模式。检视器中的说明为： *“重置会清除所有已跟踪的角色上下文，并忽略反应模式。”* 重置不会重新发送在 `ConvaiCharacter` 上配置的初始动态信息文本——只会擦除运行时跟踪的状态和事件。
{% endhint %}

### 原始更新

直接向传输层发送一个带类型的更新，完全绕过本地跟踪状态。仅在需要精确控制发送到后端的模式和文本的高级场景中使用。

<table><thead><tr><th width="133.5">字段</th><th width="142">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>Raw Mode</strong></td><td><code>Append</code></td><td>文本在后端的应用方式。 <code>Append</code> 追加到现有上下文； <code>Replace</code> 完全覆盖它； <code>Reset</code> 清除它（当模式为 <code>Reset</code>).</td></tr><tr><td><strong>Raw Text</strong></td><td><code>""</code></td><td>要发送的上下文文本。除非 <strong>Raw Mode</strong> 为 <code>Reset</code>.</td></tr><tr><td><strong>Reaction</strong></td><td><code>Auto</code></td><td>控制 LLM 重新提示行为。</td></tr></tbody></table>

{% hint style="warning" %}
**原始更新会绕过本地跟踪状态。** 通过原始更新发送的更新不会反映在 `TryGetStateValue()` 结果中，且规范重建不会包含它们。检视器中的说明为： *“原始更新会绕过本地跟踪状态。仅在高级传输场景中使用它。”* 优先使用 `SetState`, `SetStates`, `AddEvent`，以及 `RemoveState` 用于所有标准上下文管理。
{% endhint %}

## 反应模式

该 **Reaction** 字段显示在 `SetState`, `SetStates`, `AddEvent`，以及 `原始更新`。它控制在应用上下文更新后，角色是否立即生成新的对话响应。

<table><thead><tr><th width="213.5">值</th><th>说明</th></tr></thead><tbody><tr><td><code>Auto</code></td><td>由服务器决定该更新是否需要立即进行一次 LLM 轮次。大多数情况下推荐使用——它能让角色在更新重要时作出反应，而不必每次都强制回应。</td></tr><tr><td><code>ReactImmediately</code></td><td>在更新后始终立即触发一次 LLM 轮次。角色会生成对新上下文的响应，即使在对话中途也是如此。适用于需要角色立即确认的高影响事件。</td></tr><tr><td><code>SyncOnly</code></td><td>更新上下文但不提示 LLM。角色保持沉默，并在下一次响应中自然地纳入新信息。适用于不需要确认的后台状态更新。</td></tr></tbody></table>

{% hint style="info" %}
该 **Reaction** 字段默认为 `Auto` 在检视器中对所有命令类型均如此。脚本 API（`IConvaiDynamicContext`）在不同方法上的默认值不同： `SetState` 是位于 `SetStates` 默认是 `SyncOnly`; `AddEvent` 默认为 `Auto`。使用命令组件时，如果 `Auto` 不是预期行为，请显式设置反应字段。
{% endhint %}

## 事件部分

事件部分公开两个 `UnityEvent` 回调。

| 事件                       | 触发时机                                                                              |
| ------------------------ | --------------------------------------------------------------------------------- |
| **执行时**                  | 在 `Execute()` 成功完成后——角色引用已解析、配置有效，并且命令已发送给角色。                                     |
| **On Execution Skipped** | 当 `Execute()` 已调用，但无法继续——配置验证失败，或者没有 `ConvaiCharacter` 可解析的对象。Unity 控制台中也会记录一条警告。 |

{% hint style="info" %}
在开发期间，将 **On Execution Skipped** 连接到 UI 提示或 `Debug.Log` 调用，这样静默的验证失败就会在播放模式中可见，而不是被悄悄丢弃。
{% endhint %}

## 验证警告

当组件配置无效时，检视器会显示警告框。相同的检查也会在执行时运行，从而导致 `Execute()` 调用 `OnExecutionSkipped` 而不是命令。

| 条件                                                      | 警告消息                                                  |
| ------------------------------------------------------- | ----------------------------------------------------- |
| 已启用自动解析，但没有 `ConvaiCharacter` 在同一 GameObject 上的         | `在此 GameObject 上未找到 ConvaiCharacter。请分配一个，或禁用自动解析角色。` |
| 已禁用自动解析，但没有显式 **角色** 分配                                 | `请分配一个 ConvaiCharacter 或启用自动解析角色。`                    |
| SetState — **状态名称** 为空或仅包含空白字符                          | `Set State 需要一个非空状态名称。`                               |
| SetStates — **State Entries** 列表为空或为 null               | `Set States 至少需要一个状态条目。`                              |
| SetStates — 某个条目具有空或仅含空白字符的 **名称**                      | `每个状态条目都需要一个非空名称。`                                    |
| SetStates — 列表中存在重复的状态名称                                | `状态条目包含重复名称“{name}”。`                                 |
| AddEvent — **Event Text** 为空或仅包含空白字符                    | `Add Event 需要非空的事件文本。`                                |
| RemoveState — **状态名称** 为空或仅包含空白字符                       | `Remove State 需要一个非空状态名称。`                            |
| RawUpdate — **Raw Mode** 不是 `Reset` 是位于 **Raw Text** 为空 | `除非模式为 Reset，否则 Raw Update 需要文本。`                     |

## 接下来是什么

* [脚本 API 参考 ](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md)——本页每种命令类型对应的 C# 实现，包含精确的方法签名和参数默认值。
* [使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/usage-examples.md) ——在模拟场景中连接这些命令的真实示例。

## 结论

`ConvaiDynamicContextCommand` 使设计师和技术美术人员能够直接从检视器完全控制角色上下文——从单状态更新到完全重置——而无需接触 C#。有关此处记录的每种命令类型对应的脚本版本，请参见 [脚本 API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md).


---

# 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/unity-plugin-beta-overview/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.