> 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/character-actions/actions-scripting-reference.md).

# 角色动作脚本参考

Convai 角色动作系统的 API 参考——执行器基类、调度器、配置类型、调用对象和枚举。

Convai 角色动作系统中公共类型的完整 API 参考。这些类型位于 `Convai.Runtime.Actions`, `Convai.Runtime.Components`, `Convai.Shared.Actions`或 `Convai.Shared.Types` 命名空间中，另有说明的除外。

### `IConvaiActionExecutor`

`Convai.Runtime.Actions` — 接口

所有动作行为的扩展点。可在任意 `MonoBehaviour`上实现，也可以改为派生自 `ConvaiActionExecutorBase` ——请参阅 [编写自定义动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md).

```csharp
public interface IConvaiActionExecutor
{
    Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

当组件无法处理该调用时（例如，缺少装置或对端），返回 `ConvaiActionExecutionResult.Unhandled` ，这样调度器就能明确报告此情况。请遵循 `cancellationToken` ，以支持批次替换和超时。

### 执行器基类

`Convai.Runtime.Actions` — 抽象 `MonoBehaviour` 类

所有随附的执行器都派生自以下某个类，而不是直接实现 `IConvaiActionExecutor` 。派生类会自动为组件提供 Convai 检视器——包含分区字段、工具提示和动作绑定状态块——无需编写编辑器代码。

| 类                                      | 派生自                                      | 提供                                                                 |
| -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| `ConvaiActionExecutorBase`             | `MonoBehaviour`, `IConvaiActionExecutor` | `CharacterTransform`, `ResolvePlayer()`, `DeclaredButNotSent(...)` |
| `ConvaiTargetedActionExecutor`         | `ConvaiActionExecutorBase`               | 目标验证、对端解析/缓存、缺少对端的诊断信息、参数覆盖辅助方法                                    |
| `ConvaiCharacterActionExecutor<TPeer>` | `ConvaiTargetedActionExecutor`           | 解析一个特定的角色侧组件（`TPeer`），并将其传递给 `ExecuteCoreAsync`                    |
| `ConvaiActionExecutor<TParameters>`    | `ConvaiActionExecutorBase`               | 将调用参数绑定到强类型 `TParameters` 按名称获取对象，然后再执行                            |

#### `ConvaiActionExecutorBase`

```csharp
public abstract class ConvaiActionExecutorBase : MonoBehaviour, IConvaiActionExecutor
{
    public abstract Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

| 成员                                              | 类型                            | 说明                                                                        |
| ----------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| `CharacterTransform`                            | `Transform` （受保护）             | Convai Character 的变换组件；首次使用时通过向上搜索解析并缓存。如果上方没有找到角色，则回退为此组件自身的变换组件（不缓存）    |
| `ResolvePlayer()`                               | `protected virtual Transform` | 玩家实际所在的位置；参见下方的 `ConvaiPlayerBody` 。可针对分屏、多个角色骨架或过场动画摄像机进行重写              |
| `DeclaredButNotSent(invocation, parameterName)` | `protected static bool`       | 该操作是否声明了 `parameterName` ，但 Convai Character 未为其发送任何值——用于区分“未提及此项”和恰好为空的值 |

#### `ConvaiTargetedActionExecutor`

```csharp
public abstract class ConvaiTargetedActionExecutor : ConvaiActionExecutorBase
{
    protected virtual bool RequiresTarget => true;

    protected abstract Task<ConvaiActionExecutionResult> ExecuteCoreAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

`ExecuteAsync` 已封闭：当 `RequiresTarget` 为 `true` （默认值），且调用没有已解析的目标 `GameObject`时，它会返回 `MissingTargetResult(invocation)` —— `Unhandled` 为默认值——而不会调用 `ExecuteCoreAsync`。对于不需要目标的操作（例如脚本化的头部动作），请设置 `RequiresTarget => false` 。

| 成员                                              | 类型                                              | 说明                                                                                                                        |
| ----------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `MissingTargetResult(invocation)`               | `protected virtual ConvaiActionExecutionResult` | 必需目标缺失时返回的结果。可重写此方法，返回 `Failed(..., ConvaiActionFailureReason.TargetMissing)` ，而不是默认的 `Unhandled`                         |
| `ResolveTargetGameObject(invocation)`           | `protected static GameObject`                   | 已解析的目标 `GameObject`，或 `null`                                                                                              |
| `ResolveTargetInteractionPoint(invocation)`     | `protected static Transform`                    | 已解析目标的 `InteractionPoint`，若未找到则回退到其 `GameObjectReference`的变换                                                              |
| `TryResolvePeer<T>(ref T authored, out T peer)` | `protected bool`                                | 解析必需的关联组件：显式设置的 `authored` 字段始终优先；否则依次查找 `GetComponentInParent<T>()` ，然后查找 `GetComponentInChildren<T>()` ，并在该组件的生命周期内记住结果 |
| `UnhandledMissingPeer<T>()`                     | `protected ConvaiActionExecutionResult`         | 为缺失的关联组件构建一个 `Unhandled` 结果，关联组件的类型为 `T`，并且每个组件实例只记录一次日志                                                                  |
| `GetOverride(invocation, name, defaultValue)`   | `protected static float`/`bool`/`string`        | 读取调用参数覆盖值；如果不存在，或 `invocation` 为 `null`                                                                                   |

#### `ConvaiCharacterActionExecutor<TPeer>`

```csharp
public abstract class ConvaiCharacterActionExecutor<TPeer> : ConvaiTargetedActionExecutor
    where TPeer : Component
{
    protected abstract Task<ConvaiActionExecutionResult> ExecuteCoreAsync(
        TPeer characterComponent,
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

解析 `TPeer` 一次，通过 `TryResolvePeer` 并将其直接传递给 `ExecuteCoreAsync`；如果组件缺失，则在你的方法运行前通过 `Unhandled` 和 `UnhandledMissingPeer<TPeer>()` 返回结果。这是需要且仅需一个角色侧控制器的执行器共用的基类，例如 `ConvaiScanEnvironmentActionExecutor` （需要一个 `ConvaiGazeController`）和 `ConvaiLeadPlayerActionExecutor` （需要一个 `ConvaiNavMeshLocomotion`).

#### `ConvaiActionExecutor<TParameters>`

```csharp
public abstract class ConvaiActionExecutor<TParameters> : ConvaiActionExecutorBase
    where TParameters : new()
{
    protected abstract Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        TParameters parameters,
        CancellationToken cancellationToken);

    protected virtual TParameters BindParameters(ConvaiActionInvocation invocation);
}
```

按参数名称绑定 `TParameters` 的公共字段和属性（支持的成员类型： `string`, `float`, `double`, `int`, `bool`, `ConvaiResolvedActionTarget`, `ConvaiActionParameterValue`）。当 DTO 成员名称与编写的参数名称不同时，使用 `[ConvaiActionParameter("name")]` 。

### `ConvaiPlayerBody`

`Convai.Runtime.Actions` — `public static class`

对于非执行器的场景代码，此对象表示玩家实际所在的位置。 `ConvaiActionExecutorBase.ResolvePlayer()` （protected virtual， `ConvaiActionExecutorBase.cs:113`）是执行器侧对此功能的简写。

| 方法                        | 签名                                                                             | 说明                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Resolve`                 | `static Transform Resolve()`                                                   | 用于测量玩家位置的 Transform：优先使用场景中的 `ConvaiPlayer`，并解析为其骨架实际移动的 Transform（即内部的 `CharacterController` 或 `Rigidbody` ，而不是预制体根对象）；如果不存在，则回退到 `Camera.main`; `null` 如果两者都不存在 |
| `TryResolveFloorPosition` | `static bool TryResolveFloorPosition(float floorHeight, out Vector3 position)` | 玩家站立的位置，并将其投影到 `floorHeight`平面上。返回 `false` 如果没有可供测量的玩家                                                                                                            |

### `ConvaiActionExecutionResult`

`Convai.Runtime.Actions` — 只读结构体

返回类型，用于 `IConvaiActionExecutor.ExecuteAsync`.

#### 属性

| 属性              | 类型                            | 说明                                                                   |
| --------------- | ----------------------------- | -------------------------------------------------------------------- |
| `Status`        | `ConvaiActionExecutionStatus` | 此执行步骤的结果                                                             |
| `Message`       | `string`                      | 可选的诊断详情。会显示在 Console、Actions Editor 和你自己的游戏代码中，不会传给 Convai Character |
| `Answer`        | `string`                      | 此操作发现的内容，写成角色可以大声说出的一句普通话。对于执行可见行为而非回答问题的操作，此字段为空                    |
| `HasAnswer`     | `bool`                        | 此结果是否包含非空的 `Answer`                                                  |
| `Exception`     | `Exception`                   | 执行器抛出异常时捕获的异常                                                        |
| `FailureReason` | `ConvaiActionFailureReason`   | 机器可读的失败原因； `非失败情况下为` None                                            |

#### 工厂方法

| 方法                                                                   | 签名                                                                                                                        | 适用情况                                                                          |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `Succeeded`                                                          | `static ConvaiActionExecutionResult Succeeded(string message = null)`                                                     | 行为已成功完成，没有需要告知玩家的内容                                                           |
| `Answered`                                                           | `static ConvaiActionExecutionResult Answered(string answer, string message = null)`                                       | 行为发现了玩家询问的信息，例如读取仪表、清点一组物品或测量距离。 `message` 默认为 `answer`                       |
| `Failed`                                                             | `static ConvaiActionExecutionResult Failed(string message = null, Exception exception = null)`                            | 发生了未分类错误。若 `message` 非空，则映射为 `ConvaiActionFailureReason.Custom` ；否则映射为 `None` |
| `Failed`                                                             | `static ConvaiActionExecutionResult Failed(string message, ConvaiActionFailureReason reason, Exception exception = null)` | 发生了原因明确且结构化的错误。新代码中优先使用此重载，而非未分类错误的重载                                         |
| `Canceled`                                                           | `static ConvaiActionExecutionResult Canceled()`                                                                           | CancellationToken `因超时以外的原因发出信号。` FailureReason `为` Interrupted `TimedOut`    |
| `static ConvaiActionExecutionResult TimedOut(string message = null)` | `请勿手动调用。`                                                                                                                 | **当** TimeoutSeconds `到期时，分发器会自动返回此结果。` FailureReason `为` TimedOut `超时`       |
| `未处理`                                                                | `static ConvaiActionExecutionResult Unhandled(string message = null)`                                                     | 此执行器会有意拒绝此次调用。 `FailureReason` 是 `None`                                       |

`Answered(...)` 是查询操作区别于所有其他类型操作的关键：它是唯一会填充 `Answer`的工厂方法，并且 `Answer` 是 Convai Character 唯一会获知的结果部分。结果是被说出、默默记住，还是交由角色自行判断，由操作的 `ConvaiActionAnswerDelivery` 设置另行决定，而非由执行器决定。完整模式请参见 [回答问题而非执行操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md#answer-a-question-instead-of-acting) 。

### `ConvaiActionFailureReason`

`Convai.Runtime.Actions`

机器可读的步骤失败原因，与自由文本 `Message`.

| 值                     | 说明                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `None`                | 没有失败，或原因未分类（ `Succeeded`/`Unhandled`)                                                          |
| `TargetMissing`       | 调用需要一个已解析的目标，但未找到目标                                                                            |
| `TargetUnreachable`   | 已解析目标，但无法到达                                                                                    |
| `PathBlocked`         | 概念上存在通往目标的路径，但路径被阻挡（例如，没有有效的 NavMesh 路径）                                                       |
| `PeerMissing`         | 角色上未找到所需的同级组件（控制器、移动组件或骨架）                                                                     |
| `InvalidState`        | 执行器或其依赖项处于无法处理请求的状态                                                                            |
| `Timeout`             | 步骤超出其定义的超时时间                                                                                   |
| `Interrupted`         | 步骤在完成前被中断（已取消、替换或取代）                                                                           |
| `Custom`              | 其他特定于执行器的失败，仅通过 `Message`                                                                      |
| `TargetNotActionable` | 已解析目标，但目标缺少此操作所需的组件，无法对其执行操作（参见 `RequiredTargetComponent` 上的 `ConvaiActionArchetypeAttribute`) |
| `Busy`                | 角色当前无法处理此请求，因为它正在执行一项会占用同一部位的操作；稍后再次发出相同请求通常即可成功                                               |

### `ConvaiActionDefinition`

`Convai.Runtime.Actions` — 可序列化的密封类

创作定义，用于将后端操作名称绑定到本地执行器、其类型化参数及其分发行为。只有渲染后的线路模板（来自 `ToActionConfigString`) 会发送到 Convai。

#### 字段和属性

| 成员                           | 类型                                      | 说明                                                                                                                                     |
| ---------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ActionName`                 | `string`                                | 与后端命令匹配的操作名称（不区分大小写）                                                                                                                   |
| `Description`                | `string`                                | 发送到 Convai、用于提供依据的可选描述                                                                                                                 |
| `Parameters`                 | `List<ConvaiActionParameterDefinition>` | 按顺序排列的类型化参数，用于生成线上模板                                                                                                                   |
| `TargetRequirement`          | `ConvaiActionTargetRequirement`         | 此操作需要哪种类型的目标                                                                                                                           |
| `Executor`                   | `MonoBehaviour`                         | 执行行为的组件。必须实现 `IConvaiActionExecutor`。此处显式指定的引用始终优先于 `ExecutorTypeHint`                                                                 |
| `ExecutorTypeHint`           | `string`                                | 可选的短类型名称或完整类型名称，用于指定一个 `IConvaiActionExecutor` ，当 `Executor` 为 `null` 时，可在角色层级结构中自动绑定——此设置用于在 `ConvaiActionSet` 资源中编写的定义，因为该资源无法持有场景引用 |
| `TimeoutSeconds`             | `float`                                 | 最长执行时间（秒）。 `0` 或更小的值会禁用超时                                                                                                              |
| `FailurePolicyOverride`      | `ConvaiActionFailurePolicyOverride`     | 针对单个操作覆盖分发器的批处理失败策略                                                                                                                    |
| `AnswerDelivery`             | `ConvaiActionAnswerDelivery`            | 角色如何处理 `Answered(...)` 结果。仅用于编写配置，不会发送到 Convai                                                                                         |
| `WaitForBotSpeech`           | `bool`                                  | 新批次的第一步是否等待角色说话                                                                                                                        |
| `DelayAfterBotSpeechSeconds` | `float`                                 | 语音等待门解除后的可选延迟                                                                                                                          |
| `Category`                   | `string` （属性）                           | 可选的编写配置标签，用于在 Actions Editor 中对操作进行分类。仅用于组织，不会发送到 Convai                                                                               |
| `Enabled`                    | `bool` （属性）                             | 编写配置中设定的可用状态。已禁用的操作不会包含在发送到 Convai 的 `action_config` 中。默认值为 `true`                                                                     |

#### 方法

| 方法                     | 签名                              | 说明                          |
| ---------------------- | ------------------------------- | --------------------------- |
| `ToActionConfigString` | `string ToActionConfigString()` | 呈现发送给 Convai 的此定义对应的线缆模板字符串 |

### `ConvaiActionAnswerDelivery`

`Convai.Runtime.Actions`

Convai 角色如何处理 `Answer` 返回的操作。可在 Actions Editor 中为每个操作单独设置 **完成时**.

| 值                     | 整数  | 说明                                     |
| --------------------- | --- | -------------------------------------- |
| `UseCharacterSetting` | `0` | 遵循角色的 `ConvaiActionFeedbackRelay`。默认值为 |
| `RememberOnly`        | `1` | 角色会保留答案，但不会大声说出来。答案仍会进入角色的记忆           |
| `MentionIfRelevant`   | `2` | 角色自行决定是否值得提及该答案                        |
| `TellThePlayer`       | `3` | 角色会说出操作查到的内容。适用于回答直接问题的操作              |

### `ConvaiActionParameterDefinition`

`Convai.Runtime.Actions` — 可序列化的密封类

单个类型化操作参数的创作定义，由以下内容引用： `ConvaiActionDefinition.Parameters`.

| 字段            | 类型                          | 说明                                     |
| ------------- | --------------------------- | -------------------------------------- |
| `Name`        | `string`                    | 用作线缆键和模板锚点的参数名称                        |
| `Description` | `string`                    | 发送到 Convai、用于提供依据的可选描述                 |
| `Type`        | `ConvaiActionParameterType` | 声明的参数类型。 `Auto` 根据值推断。默认值为 `Auto`      |
| `Connector`   | `string`                    | 在线缆模板中渲染于参数前的可选连接词（例如 `"on"` 或 `"in"`) |
| `Choices`     | `List<string>`              | 当 `Type` 为 `Choice`                    |

### `ConvaiActionInvocation`

`Convai.Runtime.Actions` — 密封类

传递给执行器和所有分发器事件的类型化执行上下文。

#### 属性

| 属性               | 类型                           | 说明                                   |
| ---------------- | ---------------------------- | ------------------------------------ |
| `Command`        | `ConvaiActionCommand`        | 此步骤对应的原始后端命令                         |
| `Definition`     | `ConvaiActionDefinition`     | 匹配到的本地操作定义。 `null` （如果未找到定义，则此步骤将失败） |
| `ResolvedTarget` | `ConvaiResolvedActionTarget` | 解析后的目标绑定。 `null` ，如果操作没有目标或解析失败      |
| `Character`      | `ConvaiCharacter`            | 执行此操作的 NPC                           |
| `BatchIndex`     | `int`                        | 所属批次在分发器整个生命周期内的顺序索引                 |
| `StepIndex`      | `int`                        | 此步骤在当前批次中从 0 开始的索引                   |

#### 方法

| 方法                | 签名                                                                        | 说明                                      |
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------- |
| `TryGetParameter` | `bool TryGetParameter(string name, out ConvaiActionParameterValue value)` | 尝试按名称读取一个有类型的参数（不区分大小写）                 |
| `GetString`       | `string GetString(string name, string fallback = "")`                     | 读取字符串参数，返回 `fallback` （当参数不存在时）         |
| `GetNumber`       | `float GetNumber(string name, float fallback = 0f)`                       | 读取数值参数，返回 `fallback` （当参数不存在时）          |
| `GetBool`         | `bool GetBool(string name, bool fallback = false)`                        | 读取布尔参数，返回 `fallback` （当参数不存在时）          |
| `GetReference`    | `ConvaiResolvedActionTarget GetReference(string name)`                    | 根据角色的操作配置解析引用参数；当参数未显式指定类型时，回退到定义中的目标要求 |

### `ConvaiResolvedActionTarget`

`Convai.Runtime.Actions` — 可序列化的密封类

单个操作步骤的已解析目标，由以下内容中描述的分层解析流程生成： [操作目标解析的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/attention-and-reference-grounding.md).

| 属性                    | 类型                                | 说明                                                                                                                           |
| --------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Kind`                | `ConvaiActionTargetKind`          | 已解析目标的类型是 Object、Character 还是 None                                                                                           |
| `Name`                | `string`                          | 解析后的名称（来自后端命令）                                                                                                               |
| `ObjectBinding`       | `ConvaiActionObjectDefinition`    | 匹配的对象定义。 `null` ，如果 `Kind != Object`                                                                                         |
| `CharacterBinding`    | `ConvaiActionCharacterDefinition` | 匹配的角色定义。 `null` ，如果 `Kind != Character`                                                                                      |
| `GameObjectReference` | `GameObject`                      | 场景中的 `GameObject` （来自匹配的绑定）                                                                                                  |
| `InteractionPoint`    | `Transform`                       | 如果已设置，则使用绑定中显式指定的交互点；否则使用 `GameObjectReference`的变换；如果不存在，则使用 `null`。所有随附的定向执行器都会移动到此处或以此为目标，而不是使用原始 `GameObjectReference` 变换 |

### `ConvaiActionCommand`

`Convai.Shared.Types` — 可序列化的密封类

用于执行单个步骤的结构化操作命令，由后端返回。

#### 属性

| 属性                           | 类型                                               | 说明                                             |
| ---------------------------- | ------------------------------------------------ | ---------------------------------------------- |
| `Name`                       | `string`                                         | 必填。由后端选择的操作名称（例如， `"Move To"`)                 |
| `Target`                     | `string`                                         | 可选。后端解析为目标的对象或角色名称。 `null` （如果没有目标）            |
| `ActionString`               | `string`                                         | 由后端的 `Name` 和 `Target`                         |
| `Parameters`                 | `Dictionary<string, ConvaiActionParameterValue>` | 根据后端响应和当前 Unity 模板解析出的类型化参数。键不区分大小写            |
| `WaitForBotSpeech`           | `bool`                                           | 在新批次中，第一个操作运行前是否应等待角色说话                        |
| `DelayAfterBotSpeechSeconds` | `float`                                          | 语音等待条件解除后应用的可选延迟                               |
| `Enriched`                   | `bool`                                           | `true` 表示该命令已根据当前操作模板完成增强。分发器会在分发前恰好一次增强未标记的命令 |
| `HasTarget`                  | `bool`                                           | `true` 当 `Target` 不为空时                         |

#### 构造函数

```csharp
new ConvaiActionCommand("Move To", "Crate")  // name + target
new ConvaiActionCommand("Wave")              // name only
```

构造函数会规范化 `Name` 和 `Target` ，并据此生成 `ActionString` 。 `Parameters`, `WaitForBotSpeech`, `DelayAfterBotSpeechSeconds`，以及 `已丰富` 默认为其空值，并由后端响应或丰富处理填充。

### `ConvaiActionParameterValue`

`Convai.Shared.Types` — 可序列化的密封类

丰富处理后，每个操作参数都有类型。系统会尽力根据原始文本填充所有表示形式； `Type` 表示作者编写的模板所指定的类型。

| 属性                  | 类型                               | 说明                                    |
| ------------------- | -------------------------------- | ------------------------------------- |
| `Type`              | `ConvaiActionParameterType`      | 强制转换后的有效类型。作者编写的 `Auto` 会解析为具体类型      |
| `RawValue`          | `string`                         | 解析此值所依据的、经过修剪的原始文本                    |
| `StringValue`       | `string`                         | 文本形式的值（与 `RawValue` 修剪后相同）            |
| `NumberValue`       | `float`                          | 解析出的浮点数；如果文本不是数字，则为 `0` 该值            |
| `BoolValue`         | `bool`                           | 解析出的布尔值；如果文本不是可识别的布尔值，则为 `false` 该值   |
| `ResolvedReference` | `ConvaiActionParameterReference` | 如果文本指定了作者定义的目标，则为匹配的目标； `null` 否则     |
| `IsConstraintMatch` | `bool`                           | `false` 仅当 `Choice` 参数的文本不属于其作者定义的选项时 |
| `Presence`          | `ConvaiActionParameterPresence`  | 指示 Convai Character 是否为此参数提供了值        |

请通过以下方法读取参数： `ConvaiActionInvocation.TryGetParameter`, `GetString`, `GetNumber`, `GetBool`或 `GetReference` 而不要直接对 `ConvaiActionCommand.Parameters` 进行索引。

### `ConvaiActionParameterPresence`

`Convai.Shared.Types`

指示参数值是否由 Convai Character 提供。声明了三个参数的操作总会返回三个参数，因为未填充的槽位会补齐，以便值与作者定义的顺序保持一致—— `Presence` 可让执行器区分补齐的槽位和已回答的槽位。

| 值          | 整数  | 说明                      |
| ---------- | --- | ----------------------- |
| `Provided` | `0` | 为此槽位提供了一个值。默认值          |
| `Missing`  | `1` | 没有值传入此槽位；此参数仅因操作声明了它而存在 |

对空值采取操作前，请检查这一点： `Missing` 表示没有提供有关该参数的信息，执行器应自行决定如何处理——拒绝、询问或应用自己的默认值——而不应将其视为空指令。 `Missing` 也会通过 `Actions` 日志类别记录一次。

### `ConvaiActionParameterReference`

`Convai.Shared.Types` — 可序列化的密封类

名称和类型用于处理 `Reference` 参数，该参数会在信息补全过程中解析为一个句柄。

| 属性     | 类型                       | 说明                                 |
| ------ | ------------------------ | ---------------------------------- |
| `Name` | `string`                 | 原始值匹配的已定义目标名称（已去除首尾空格，绝不会为 `null`) |
| `Kind` | `ConvaiActionTargetKind` | 名称是否匹配某个已定义对象或角色                   |

`ConvaiActionParameterReference` 是一个查找键，而不是场景绑定——它不包含 `GameObjectReference`。请通过 `GameObject` 解析为一个有效的 `ConvaiActionInvocation.GetReference(name)`，该方法会返回一个 `ConvaiResolvedActionTarget`.

### `ConvaiActionConfig`

`Convai.Shared.Actions` — 可序列化的密封类

连接时的操作能力配置，会序列化到会话连接负载中。

| 属性                       | 类型                                      | 说明                                         |
| ------------------------ | --------------------------------------- | ------------------------------------------ |
| `Actions`                | `List<string>`                          | 此会话允许使用的操作名称。仅发送名称——执行器绑定保留在本地             |
| `Objects`                | `List<ConvaiActionObjectDefinition>`    | 后端可引用为目标的对象。 `GameObjectReference` 绝不会被序列化 |
| `Characters`             | `List<ConvaiActionCharacterDefinition>` | 后端可引用为目标的角色。 `GameObjectReference` 绝不会被序列化 |
| `CurrentAttentionObject` | `string`                                | 初始关注对象名称。必须与 `Objects`                     |

### `ConvaiActionConfigPatch`

`Convai.Shared.Actions` — 可序列化的密封类

用于当前会话操作能力的运行时补丁，通过 `character.DynamicContext.Apply(...)`.

| 属性                       | 类型                                      | 说明             |
| ------------------------ | --------------------------------------- | -------------- |
| `Actions`                | `List<string>`                          | 替换操作列表         |
| `Characters`             | `List<ConvaiActionCharacterDefinition>` | 替换角色目标列表       |
| `Objects`                | `List<ConvaiActionObjectDefinition>`    | 替换对象目标列表       |
| `CurrentAttentionObject` | `string`                                | 替换列表后解析的关注对象更新 |

{% hint style="warning" %}
每个字段都遵循省略与空值的语义：一个 `null` 列表或字符串会保留当前值，空列表或空字符串则会明确清除该值。仅在需要更改字段时才设置它。
{% endhint %}

### `ConvaiActionObjectDefinition`

`Convai.Shared.Actions` — 可序列化的密封类

| 属性                    | 类型             | 已序列化                   | 说明                                                                    |
| --------------------- | -------------- | ---------------------- | --------------------------------------------------------------------- |
| `Name`                | `string`       | 是（`"name"`)            | 在操作命令中使用的标识符。匹配时不区分大小写                                                |
| `Description`         | `string`       | 是（`"description"`)     | 发送给 Convai 以供指代消解使用的自然语言描述                                            |
| `GameObjectReference` | `GameObject`   | **否** (`[JsonIgnore]`) | 本地场景引用。绝不会发送给 Convai                                                  |
| `TextOnly`            | `bool`         | **否** (`[JsonIgnore]`) | 声明此条目有意不包含 `GameObjectReference`。如果没有此项，缺失的引用会被报告为设置错误                |
| `别名`                  | `List<string>` | **否** (`[JsonIgnore]`) | 备用名称；解析流程会先进行精确匹配（步骤 2），然后再回退到标准化/包含匹配                                |
| `InteractionPoint`    | `Transform`    | **否** (`[JsonIgnore]`) | 用于移动到或瞄准的显式点位。若未指定，则回退到 `GameObjectReference`的 transform（变换），当 `null` |
| `Available`           | `bool`         | **否** (`[JsonIgnore]`) | 本地解析开关， `true` 为默认值。解析流程会跳过不可用条目                                      |

### `ConvaiActionCharacterDefinition`

`Convai.Shared.Actions` — 可序列化的密封类

| 属性                    | 类型             | 已序列化                   | 说明                               |
| --------------------- | -------------- | ---------------------- | -------------------------------- |
| `Name`                | `string`       | 是（`"name"`)            | 此角色目标的标识符                        |
| `Bio`                 | `string`       | 是（`"bio"`)             | 发送给 Convai 的简短描述（例如：“现场安全主管”）    |
| `GameObjectReference` | `GameObject`   | **否** (`[JsonIgnore]`) | 本地场景引用。绝不会发送给 Convai             |
| `TextOnly`            | `bool`         | **否** (`[JsonIgnore]`) | 与 `ConvaiActionObjectDefinition` |
| `别名`                  | `List<string>` | **否** (`[JsonIgnore]`) | 与 `ConvaiActionObjectDefinition` |
| `InteractionPoint`    | `Transform`    | **否** (`[JsonIgnore]`) | 与 `ConvaiActionObjectDefinition` |
| `Available`           | `bool`         | **否** (`[JsonIgnore]`) | 与 `ConvaiActionObjectDefinition` |

### `ConvaiActionTarget`

`Convai.Runtime.Actions` — `MonoBehaviour`

菜单路径： `Add Component → Convai → Actions → Convai Action Target`

将任意 `GameObject` 标记为运行时操作定位目标，无需编写代码。启用后，它会显示在所选角色合并后的操作配置中，并像通过代码定义的对象或角色一样参与解析流程；但如果存在名称相同的定义条目，则始终优先使用定义条目。

| 属性                   | 类型                             | 说明                                                    |
| -------------------- | ------------------------------ | ----------------------------------------------------- |
| `TargetName`         | `string`                       | 解析流程用于匹配的目标名称。留空时默认为此 `GameObject`的名称                 |
| `Kind`               | `ConvaiActionTargetKind`       | 此项是否为可执行操作的对象或角色                                      |
| `Description`        | `string`                       | 发送给 Convai 以供定位（对象类型）                                 |
| `Bio`                | `string`                       | 发送给 Convai 以供定位（角色类型）                                 |
| `别名`                 | `List<string>`                 | 备用名称；解析流程会进行精确匹配（步骤 2）                                |
| `InteractionPoint`   | `Transform`                    | 可选的显式移动或瞄准点位                                          |
| `ApplyTo`            | `ConvaiActionTargetApplyScope` | 启用时哪些角色会注册此目标： `AllCharacters` 或 `SpecificCharacters` |
| `SpecificCharacters` | `List<ConvaiCharacter>`        | 当 `ApplyTo` 为 `SpecificCharacters`                    |
| `RegisterOnEnable`   | `bool`                         | 是否在启用时注册目标，并在禁用时取消注册。默认值为 `true`                      |

### 内置执行器类型

每种执行器的完整字段级参考位于 [动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)。以下是该目录中的部分内容：

| 执行器                                    | 菜单路径                                   | 备注                                                                        |
| -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `ConvaiLeadPlayerActionExecutor`       | `Convai/Actions/Lead Player To Target` | Body Animation 包；需要一个 `ConvaiNavMeshLocomotion` 协同组件                      |
| `ConvaiScanEnvironmentActionExecutor`  | `Convai/Actions/Scan Environment`      | Gaze 包；需要一个 `ConvaiGazeController` 协同组件                                   |
| `ConvaiCountTargetGroupActionExecutor` | `Convai/Actions/Count Target Group`    | Observation 包；需要在已解析的目标上有一个 `ConvaiActionTargetGroup` ；返回 `Answered(...)` |
| `ConvaiMeasureDistanceActionExecutor`  | `Convai/Actions/Measure Distance`      | Observation 包；不需要协同组件；返回 `Answered(...)`                                  |

Observation 包的执行器使用 `ConvaiActionExecutionResult.Answered(...)` 而非 `Succeeded(...)`.

### `ConvaiActionDispatcher`

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `Add Component → Convai → Convai Action Runner`

限制： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

#### 属性

| 属性                           | 类型                                 | 说明                                                                |
| ---------------------------- | ---------------------------------- | ----------------------------------------------------------------- |
| `BatchPolicy`                | `ConvaiActionBatchPolicy`          | 当前批处理策略（代码中只读；在 Inspector 中设置）                                    |
| `FailurePolicy`              | `ConvaiActionBatchFailurePolicy`   | 当前失败策略（代码中只读；在 Inspector 中设置）                                     |
| `IsBusy`                     | `bool`                             | 当前是否正在执行批次                                                        |
| `PendingBatchCount`          | `int`                              | 排在当前批次之后的队列中批次数量                                                  |
| `CurrentActionName`          | `string`                           | 当前正在执行的操作的显示名称；若无则为空                                              |
| `CancelOnUserSpeech`         | `bool`                             | 启用后，玩家一开始说话，分发器便会取消正在执行的批次并清空队列。默认关闭                              |
| `EnablePerformanceReactions` | `bool`                             | 是否发送批次/步骤生命周期通知 `IActionPerformanceReactor` 同级组件（注视、肢体语言、情绪）。默认启用 |
| `OnBatchStarted`             | `UnityEvent`                       | 批次开始执行时触发                                                         |
| `OnStepStarted`              | `ConvaiActionInvocationUnityEvent` | 每个操作步骤开始时触发                                                       |
| `OnStepSucceeded`            | `ConvaiActionInvocationUnityEvent` | 执行器返回 `Succeeded` 或 `Answered`                                    |
| `OnStepFailed`               | `ConvaiActionInvocationUnityEvent` | 步骤失败时触发（Failed、Canceled 或 TimedOut）                               |
| `OnStepUnhandled`            | `ConvaiActionInvocationUnityEvent` | 执行器返回 `Unhandled`                                                 |
| `OnStepCompleted`            | `ConvaiActionStepReportUnityEvent` | 每个步骤结束后触发，无论是否成功，并附带完整的 `ConvaiActionStepReport`                  |
| `OnBatchCompleted`           | `UnityEvent`                       | 批次的所有步骤完成且批次未中止时触发                                                |
| `OnBatchAborted`             | `UnityEvent`                       | 当 `StopBatch` 策略在发生失败后提前终止批次时触发                                   |
| `OnCancelledByUserSpeech`    | `event Action<string>`             | 当 `CancelOnUserSpeech` 取消正在执行的操作时触发，并携带其显示名称                      |

#### 方法

| 方法               | 签名                                                                | 说明                               |
| ---------------- | ----------------------------------------------------------------- | -------------------------------- |
| `EnqueueActions` | `void EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions)` | 向分发器提交一个批次。遵循当前启用的 `BatchPolicy` |

参见 [调度器和批处理策略](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/dispatcher-and-batch-policies.md) ，了解批处理/失败策略的行为和调优指南。

### `ConvaiActionConfigSource`

`MonoBehaviour` — `Convai.Runtime.Components`

菜单路径： `Add Component → Convai → Convai Actions`

限制： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

#### 属性

| 属性                       | 类型                                               | 说明                                                                           |
| ------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| `Definitions`            | `IReadOnlyList<ConvaiActionDefinition>`          | 已编写的内联操作定义列表                                                                 |
| `ActionSets`             | `IReadOnlyList<ConvaiActionSet>`                 | 可复用的操作集资源，会合并到 `Definitions`之前；内联定义在名称冲突时始终优先于任何操作集                          |
| `Objects`                | `IReadOnlyList<ConvaiActionObjectDefinition>`    | 已编写的可操作对象列表                                                                  |
| `Characters`             | `IReadOnlyList<ConvaiActionCharacterDefinition>` | 已编写的可操作角色列表                                                                  |
| `InitialAttentionObject` | `string`                                         | 连接时预先设为 NPC 关注对象的对象名称                                                        |
| `ActionExecutionMode`    | `ConvaiActionExecutionMode`                      | 声明是否由 `ConvaiActionDispatcher` 或自定义代码来运行此角色的动作。不会改变运行时的任何行为；仅供 SDK 自身的设置检查使用 |
| `BehaviorHost`           | `GameObject`                                     | 新建的动作行为所添加到的对象：指定的子对象；如果未指定，则添加到角色本身                                         |

#### 方法

| 方法                  | 签名                                       | 说明                               |
| ------------------- | ---------------------------------------- | -------------------------------- |
| `BuildActionConfig` | `ConvaiActionConfig BuildActionConfig()` | 构建并返回连接时负载。返回 `null` （如果不存在有效定义） |

### `ConvaiActionExecutionMode`

`Convai.Runtime.Components`

| 值                        | 整数  | 说明                                                                                                 |
| ------------------------ | --- | -------------------------------------------------------------------------------------------------- |
| `ConvaiActionDispatcher` | `0` | 随附的 `ConvaiActionDispatcher` 此角色上的组件负责运行命令。默认模式；设置检查要求此模式下存在一个 dispatcher 组件                       |
| `CustomCode`             | `1` | 您自己的代码订阅 `ConvaiCharacter.OnActionsReceived` 或 `ConvaiManager.Events.OnCharacterActionReceived` 代替 |

### `ConvaiCharacter` — 与操作相关的成员

`MonoBehaviour` — `Convai.Runtime.Components`

#### 事件

| 事件                  | 类型                                                 | 说明                                      |
| ------------------- | -------------------------------------------------- | --------------------------------------- |
| `OnActionsReceived` | `event Action<IReadOnlyList<ConvaiActionCommand>>` | 当 Convai 为此角色返回一批操作时触发。触发时间早于分发器处理该批操作。 |

#### 属性

| 属性             | 类型                   | 说明                                  |
| -------------- | -------------------- | ----------------------------------- |
| `ActionConfig` | `ConvaiActionConfig` | 返回当前活动会话的操作配置副本。连接前可能为 `null` （连接前） |

#### 方法

| 方法                      | 签名                                                 | 说明                                                             |
| ----------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
| `GetActionConfigSource` | `ConvaiActionConfigSource GetActionConfigSource()` | 返回此 `ConvaiActionConfigSource` 上与此 `GameObject`关联的对象，或者 `null` |

{% hint style="info" %}
当前注意力对象的运行时更新由动态上下文系统处理，而不是由 `ConvaiCharacter` 直接处理。请参阅 [操作目标解析的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/attention-and-reference-grounding.md#runtime-attention-api).
{% endhint %}

### `RoomSessionConnectOptions` — 操作字段

`Convai.Runtime.Room`

| 字段                          | 类型                             | 说明                                                                          |
| --------------------------- | ------------------------------ | --------------------------------------------------------------------------- |
| `ActionConfigOverride`      | `ConvaiActionConfig`           | 设置后，将替换此会话的 `ConvaiActionConfigSource.BuildActionConfig()` 生成的配置            |
| `ActionDefinitionsOverride` | `List<ConvaiActionDefinition>` | 设置后，将替换此会话的 Inspector 操作定义。若同时设置了 `ActionConfigOverride.Actions` ，则会根据它进行筛选 |

### `ConvaiActionStepReport`

`Convai.Runtime.Actions` — 可序列化的密封类

已完成步骤的报告，由 `ConvaiActionDispatcher.OnStepCompleted`.

| 属性               | 类型                            | 说明                        |
| ---------------- | ----------------------------- | ------------------------- |
| `Invocation`     | `ConvaiActionInvocation`      | 报告所描述的调用                  |
| `Result`         | `ConvaiActionExecutionResult` | 步骤执行器返回的原始结果              |
| `FailureReason`  | `ConvaiActionFailureReason`   | 透传 `Result.FailureReason` |
| `BatchAborted`   | `bool`                        | 此步骤是否中止了批次中剩余的操作          |
| `Message`        | `string`                      | 成功时的详细信息；状态非成功时的失败消息      |
| `FailureMessage` | `string`                      | 包含批次后续影响的失败详情。成功时为空       |

### 枚举

操作系统中其余的枚举类型，集中列于此以供参考。

#### `ConvaiActionBatchPolicy`

`Convai.Runtime.Actions`

| 值                | 整数  | 说明                      |
| ---------------- | --- | ----------------------- |
| `Queue`          | `0` | 新批次将等待当前批次完成。默认值        |
| `ReplaceCurrent` | `1` | 取消当前步骤和所有待处理批次，并立即启动新批次 |
| `DropIncoming`   | `2` | 在当前和排队的所有任务完成前，丢弃新批次    |

#### `ConvaiActionBatchFailurePolicy`

`Convai.Runtime.Actions`

| 值               | 整数  | 说明                                        |
| --------------- | --- | ----------------------------------------- |
| `StopBatch`     | `0` | 某个步骤失败后，将中止剩余批次。 `OnBatchAborted` 会触发。默认值 |
| `ContinueBatch` | `1` | 无论如何，执行都会继续到下一步。 `OnBatchCompleted` 会触发   |

#### `ConvaiActionTargetRequirement`

`Convai.Runtime.Actions`

| 值           | 整数  | 说明            |
| ----------- | --- | ------------- |
| `None`      | `0` | 操作不需要目标       |
| `Object`    | `1` | 操作需要已解析的对象目标  |
| `Character` | `2` | 操作需要已解析的角色目标  |
| `Either`    | `3` | 操作接受对象或角色作为目标 |

#### `ConvaiActionFailurePolicyOverride`

`Convai.Runtime.Actions`

| 值                      | 整数  | 说明                                   |
| ---------------------- | --- | ------------------------------------ |
| `UseDispatcherDefault` | `0` | 遵循 `ConvaiActionDispatcher` 失败策略。默认值 |
| `StopBatch`            | `1` | 结果非成功时，中止剩余批次                        |
| `ContinueBatch`        | `2` | 结果非成功时，继续执行剩余批次                      |

#### `ConvaiActionTargetKind`

`Convai.Shared.Types`

| 值           | 整数  | 说明        |
| ----------- | --- | --------- |
| `None`      | `0` | 未解析到目标    |
| `Object`    | `1` | 目标是已注册的对象 |
| `Character` | `2` | 目标是已注册的角色 |

#### `ConvaiActionParameterType`

`Convai.Shared.Types`

| 值           | 整数  | 说明                                           |
| ----------- | --- | -------------------------------------------- |
| `Auto`      | `0` | 按引用、数字、布尔值或字符串的顺序尽力推断。默认值                    |
| `Reference` | `1` | 按名称解析已编写的对象或角色目标                             |
| `String`    | `2` | 保留原始文本                                       |
| `Number`    | `3` | 按不变区域性解析浮点数                                  |
| `Bool`      | `4` | 解析 `true`/`yes`/`1` 或 `false`/`no`/`0`       |
| `Choice`    | `5` | 要求值为已编写的选项字符串之一。不匹配时，会通过 `IsConstraintMatch` |

#### `ConvaiActionExecutionStatus`

`Convai.Runtime.Actions`

| 值                                                                    | 整数  | 调度器事件触发           |
| -------------------------------------------------------------------- | --- | ----------------- |
| `Succeeded`                                                          | `0` | `OnStepSucceeded` |
| `Failed`                                                             | `1` | `OnStepFailed`    |
| `Canceled`                                                           | `2` | `OnStepFailed`    |
| `static ConvaiActionExecutionResult TimedOut(string message = null)` | `3` | `OnStepFailed`    |
| `未处理`                                                                | `4` | `OnStepUnhandled` |

### `ConvaiActionInvocationUnityEvent`

`Convai.Runtime.Actions` — 可序列化类，继承自 `UnityEvent<ConvaiActionInvocation>`

使 `ConvaiActionInvocation` 可作为 UnityEvent 参数进行序列化的包装类型。像配置任何标准 UnityEvent 一样，在检查器中指定处理程序。该事件唯一的参数是该步骤的 `ConvaiActionInvocation` 。

`ConvaiActionStepReportUnityEvent` 是 `ConvaiActionDispatcher.OnStepCompleted`的等效包装类型；它继承自 `UnityEvent<ConvaiActionStepReport>` 并携带完整的 `ConvaiActionStepReport` 替代。

### `ConvaiActionDebugProbe`

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `Add Component → Convai → Actions → Diagnostics → Convai Action Monitor`

限制： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

请参阅 [排查角色动作问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.md) 了解完整的 Inspector 字段参考和使用指南。

#### 上下文菜单操作

| 命令                  | 效果                                                 |
| ------------------- | -------------------------------------------------- |
| `Inject Test Batch` | 向分发器提交一个 `Move To` 命令，目标为第一个已注册对象。无需进行实时对话即可测试整个管线 |
| `Reset Probe State` | 将所有计数器和文本字段重置为零或空值                                 |

### 后续步骤

{% content-ref url="/pages/f592d9dc3ad261e175159690b86cdd4b50bb4d81" %}
[动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)
{% endcontent-ref %}

{% content-ref url="/pages/0e9ccbf7f8fa10ad65f6395315d82ba64412791c" %}
[角色动作示例](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/1398e3302b345ef93934a0e6c93b4d8e576ab00e" %}
[排查角色动作问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.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/character-actions/actions-scripting-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.
