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

# 命令组件参考

Dynamic Context Command 组件上的每个字段、命令类型和事件——从 Unity Inspector 驱动角色感知的完整参考。

## Convai Dynamic Context Command：完整检查器参考

`ConvaiDynamicContextCommand` 是 Dynamic Context 的无代码入口。它是一个 `MonoBehaviour` ，用于封装一项上下文操作——选择命令类型、填写参数，并从任意 `Execute()` 调用它的 `UnityEvent` 源。此组件专为设计师和技术美术人员打造，让他们无需修改 C# 脚本，就能通过按钮、过场动画、触发区域或动画事件来控制角色的感知能力。

本页介绍该组件公开的所有分区、字段、命令类型、验证警告和事件。

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

## 添加组件

在 Unity Inspector 中，点击 **添加组件** 并导航至：

**Convai → 动态上下文 → Convai 动态上下文命令**

该组件在 Inspector 中分为三个部分： **目标**, **命令**，和 **事件**.

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-701a9d532717d6236cfdf2ee397243554b41f244%2Fimage.png?alt=media" 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>。禁用此选项，并在命令位于不同的 GameObject 上时， <strong>显式指定 Character</strong> 。</td></tr></tbody></table>

**Character 解析顺序：** 如果 **已指定 Character** ，则始终使用它，无论 **自动解析角色** 设置。如果 **已指定 Character** 未分配且 **自动解析角色** 已启用，该组件会在同一个 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>反应</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>状态条目</strong></td><td>空列表</td><td>可重新排序的名称/值对列表。每个条目都有一个 <strong>名称</strong> 和 <strong>值</strong> 字段。拖动条目即可重新排序；对于任何新状态，顺序会影响其在规范上下文中的插入顺序。</td></tr><tr><td><strong>反应</strong></td><td><code>Auto</code></td><td>应用于整个批次。</td></tr></tbody></table>

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

### AddEvent

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

<table><thead><tr><th width="182">字段</th><th width="190.00006103515625">默认值</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>Auto</code></td><td>使用 <code>Auto</code>时，服务器会判断该事件是否需要角色立即回复。当事件足够重要、需要角色立即确认时，请使用 <code>ReactImmediately</code> 。</td></tr></tbody></table>

### RemoveState

按名称移除受跟踪状态。移除后，系统会重建规范上下文，并以 Replace 操作发送给角色。

<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" %}
**移除状态** 在 Inspector 中不提供 Reaction 字段。移除操作始终会在内部触发规范 Replace 同步，Inspector 备注如下： *“移除状态会重建受跟踪的规范上下文，且不使用反应模式。”*
{% endhint %}

### 重置

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

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

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

### RawUpdate

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

<table><thead><tr><th width="133.5">字段</th><th width="142">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>原始模式</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>原始文本</strong></td><td><code>""</code></td><td>要发送的上下文文本。必填，除非 <strong>原始模式</strong> 为 <code>Reset</code>.</td></tr><tr><td><strong>反应</strong></td><td><code>Auto</code></td><td>控制重新提示 LLM 的行为。</td></tr></tbody></table>

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

## 反应模式

“ **反应** ”字段出现在 `SetState`, `SetStates`, `AddEvent`和 `RawUpdate`中。它控制角色是否在上下文更新应用后立即生成新的对话回复。

<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" %}
“ **反应** ”字段的默认值为 `Auto` ，适用于 Inspector 中的所有命令类型。脚本 API（`IConvaiDynamicContext`）中各方法的默认值则有所不同： `SetState` 和 `SetStates` 的默认值为 `SyncOnly`; `AddEvent` 默认为 `Auto`。使用命令组件时，如果 `Auto` 不是预期行为，请显式设置 Reaction 字段。
{% endhint %}

## 事件部分

事件部分提供两个 `UnityEvent` 回调。

| 事件        | 触发时机                                                                               |
| --------- | ---------------------------------------------------------------------------------- |
| **执行后**   | 在 `Execute()` 成功完成后触发——角色引用已解析、配置有效，并且命令已发送给角色。                                    |
| **执行跳过时** | 当 `Execute()` 被调用但无法继续时触发——配置验证失败，或无法解析任何 `ConvaiCharacter` 。同时也会在 Unity 控制台中记录警告。 |

{% hint style="info" %}
开发期间，将 **执行跳过时** 连接到 UI 提示或 `Debug.Log` 调用，以便在 Play Mode 中显示静默发生的验证失败，而不是让它们被悄然忽略。
{% endhint %}

## 验证警告

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

| 条件                                            | 警告消息                                                                                         |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| 已启用自动解析，但同一 `ConvaiCharacter` GameObject 上没有  | `No ConvaiCharacter found on this GameObject. Assign one or disable Auto Resolve Character.` |
| 已禁用自动解析，且未显式 **指定角色** 。                       | `Assign a ConvaiCharacter or enable Auto Resolve Character.`                                 |
| SetState — **State Name** 为空或仅包含空白字符          | `Set State requires a non-empty state name.`                                                 |
| SetStates — **State Entries** 列表为 null 或为空    | `Set States requires at least one state entry.`                                              |
| SetStates — 某个条目的 **Name**                    | `Each state entry requires a non-empty name.`                                                |
| SetStates — 列表中存在重复的状态名称                      | `State entries contain duplicate name '{name}'.`                                             |
| AddEvent — **事件文本** 为空或仅包含空白字符                | `Add Event requires non-empty event text.`                                                   |
| RemoveState — **状态名称** 为空或仅包含空白字符             | `Remove State requires a non-empty state name.`                                              |
| RawUpdate — **原始模式** 不是 `Reset` 且 **原始文本** 为空 | `Raw Update requires text unless mode is Reset.`                                             |

## 接下来

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

## 总结

`ConvaiDynamicContextCommand` 让设计师和技术美术人员无需编写 C#，即可通过 Inspector 全面控制角色上下文——从单个状态更新到完全重置。有关此处介绍的每种命令类型对应的脚本实现，请参阅 [脚本 API 参考](https://docs.convai.com/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 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/unity-plugin-beta-overview/features/dynamic-context/command-component-reference.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.
