> 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/actions/configuring-actions.md).

# 配置动作

## ConvaiActionConfigSource 组件

`ConvaiActionConfigSource` 是检查器面板，在这里你可以定义 AI 角色被允许执行的一切内容——有哪些动作、哪些场景对象或角色可以作为目标，以及每个动作如何映射到一种行为。

通过选择你的 NPC 的 GameObject 并单击 **添加组件 → Convai Action Config Source**.

{% hint style="info" %}
`ConvaiActionConfigSource` 需要一个 `ConvaiCharacter` 同一 GameObject 上的组件。如果放在不同的对象上将无法工作。
{% endhint %}

该组件有四个部分：

| 章节         | 用途                 |
| ---------- | ------------------ |
| **动作定义**   | 将动作名称映射到执行器组件      |
| **可操作对象**  | AI 可以作为目标的场景对象     |
| **可操作角色**  | 场景中 AI 可以作为目标的其他角色 |
| **初始关注对象** | 会话开始时 AI 默认聚焦的对象   |

<figure><img src="/files/ba72139f2b0dc839a3de9312a2318c2a06a17204" alt=""><figcaption></figcaption></figure>

***

## 动作定义

中的每一项 **动作定义** 列表都将一个后端动作名称连接到执行它的 Unity 组件。

### 添加定义

点击 **+** 按钮下的 **动作定义** 来添加一条新条目。填写以下字段：

#### 动作名称

当此动作被触发时，Convai 后端会发送的名称字符串。

```
Move To
拾取
挥手
看向
报告危险
```

{% hint style="info" %}
动作名称在运行时是 **不区分大小写的** —— `Move To`, `前往`，以及 `前往` 都匹配同一定义。不过，请保持名称一致且易读，因为 AI 后端会使用它们进行意图匹配。
{% endhint %}

{% hint style="warning" %}
列表中重复的动作名称会被静默去重——只有 **第一条** 条目会被保留。如果某个动作看起来没有任何作用，请检查是否有重复项。
{% endhint %}

#### 目标要求

指定此动作是否需要一个目标对象或角色，以及需要哪种类型。

| 值    | 行为                                                                        |
| ---- | ------------------------------------------------------------------------- |
| `无`  | 不需要目标。执行器接收 `null` 用于 `ResolvedTarget`。用于“Wave”或“Sit Down”这类不涉及特定对象或人的动作。 |
| `对象` | 需要一个会解析为 **可操作对象**中的条目的目标对象。如果没有解析出对象目标，步骤将失败。                            |
| `角色` | 需要一个会解析为 **可操作角色**。如果没有解析出角色目标，步骤将失败。                                     |
| `任一` | 可以接受对象或角色目标。将解析为最先匹配的那个。                                                  |

#### 执行器

将任何实现了 `IConvaiActionExecutor` 的 MonoBehaviour 组件拖到此字段中。该组件可以位于同一 GameObject 上的任何位置。

有关 SDK 随附的所有可用执行器，请参阅 Action Executors。

#### 超时秒数

此动作允许运行的最长时间（秒）。如果执行器在此限制内没有返回，该步骤会自动取消并标记为 `超时`.

设为 `0` 以禁用超时（执行器会一直运行，直到其自行返回）。

```
0    → 无超时（默认）
5    → 5 秒限制
30   → 30 秒限制
```

{% hint style="info" %}
超时对于涉及移动或动画的动作很有用。如果某个 NPC 在前往目标时卡住，超时可以防止整个对话挂起。
{% endhint %}

<figure><img src="/files/513a7d6af96a36aafd58e8af123a1ee6c2a40132" alt=""><figcaption></figcaption></figure>

***

## 可操作对象

场景中 AI 可以作为目标的对象。Convai 后端使用此列表来了解有哪些对象以及它们是什么，从而决定何时将动作指向它们。

### 添加对象

点击 **+** 按钮下的 **可操作对象** 来添加一条新条目：

| 字段         | 说明                                                                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| **名称**     | 后端用来指代此对象的标识符（例如， `灭火器`, `箱子`, `出口门`）。目标名称在运行时不区分大小写。                                                    |
| **说明**     | 用平实语言描述该对象及其上下文的句子。后端会将其用于 grounding——理解这个对象是什么，以及何时使用它。有关编写有效描述的技巧，请参阅 Attention & Reference Grounding。 |
| **游戏对象引用** | 场景中的实际 GameObject。这就是执行器接收到的内容，作为 `invocation.ResolvedTarget.GameObjectReference`.                       |

#### 编写良好描述

描述有助于 AI 理解这个对象是什么。请用普通英语编写，就像在向一个没见过你的场景的人描述该对象一样。

| 对象   | 示例描述               |
| ---- | ------------------ |
| 灭火器  | `安装在入口附近墙上的红色灭火器。` |
| 紧急出口 | `走廊最远端的紧急出口门。`     |
| 箱子   | `仓库地板上放着的一个木箱。`    |
| 安全头盔 | `挂在设备架上的黄色安全帽。`    |

{% hint style="info" %}
**描述会发送到后端。** 它会直接影响 AI 如何推理要瞄准什么。模糊的描述（“object”）比具体的描述（“入口附近的红色灭火器”）效果更差。
{% endhint %}

### 示例：训练模拟设置

消防安全培训模拟可能会注册以下对象：

| 名称     | 说明              | 游戏对象引用                        |
| ------ | --------------- | ----------------------------- |
| `灭火器`  | 紧急面板附近墙上的红色灭火器。 | `FireExtinguisher` GameObject |
| `紧急出口` | 走廊最远端的紧急出口门。    | `ExitDoor` GameObject         |
| `消防面板` | 安装在墙上的火灾警报控制面板。 | `AlarmPanel` GameObject       |

<figure><img src="/files/45fee64bf677b55de942b4eb2ddd3c8ae440df9f" alt=""><figcaption></figcaption></figure>

***

## 可操作角色

场景中可以被动作作为目标的其他 NPC 或角色。

### 添加角色

点击 **+** 按钮下的 **可操作角色**:

| 字段         | 说明                                   |
| ---------- | ------------------------------------ |
| **名称**     | 后端用来指代此角色的标识符（例如， `守卫`, `讲师`, `病人`). |
| **Bio**    | 对这个角色身份的简短描述。后端会用它来理解何时将动作指向他们。      |
| **游戏对象引用** | 该角色在场景中的 GameObject。                 |

#### 示例：多 NPC 场景

在一个有两位讲师的学习模拟中：

| 名称     | Bio             | 游戏对象引用                        |
| ------ | --------------- | ----------------------------- |
| `高级讲师` | 站在主控制台旁的首席安全讲师。 | `SeniorInstructor` GameObject |
| `助手`   | 设备存放区附近的初级助手。   | `助手` GameObject               |

<figure><img src="/files/99b07a91b8f70311ca6d8da3213d52300ef812fa" alt=""><figcaption></figcaption></figure>

***

## 初始注意对象

该 **初始关注对象** 字段用于设置在会话开始时 AI 聚焦的对象——用于解析诸如“it”或“that thing”这类模糊的玩家指代。

* 输入 **名称** 中某个已注册对象的
* （不区分大小写）。
* 如果名称与任何 **可操作对象** 条目都不匹配，则会记录警告并忽略该字段。

{% hint style="info" %}
有关 grounding 工作原理的完整说明——包括运行时的注意力更新和如何编写有效描述——请参阅 [注意力与指代锚定](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/actions/attention-and-reference-grounding.md).
{% endhint %}

***

## 重要说明

{% hint style="warning" %}
**更改需要重新连接。** 会话开始时，动作配置会发送一次到 Convai 后端。如果你在 Play Mode 中添加、重命名或移除动作或目标，必须结束并重新开始会话，变更才会生效。
{% endhint %}

{% hint style="info" %}
**对象和角色名称在匹配时不区分大小写。** `灭火器`, `灭火器`，以及 `灭火器` 都解析为同一个对象。空格会被保留，所以 `FireExtinguisher` 是位于 `灭火器` 是 **不同** 名称。
{% endhint %}

{% hint style="info" %}
**执行器组件可以共享。** 多个动作定义可以指向同一个执行器组件。你不需要为每个动作单独创建组件。
{% endhint %}

***

## 高级：连接时覆盖

默认情况下，SDK 从 `ConvaiActionConfigSource`读取配置。如果你的场景是程序生成的、按玩家生成的，或者在运行时构建的，你可以在调用 `RoomSessionConnectOptions` 时提供一个 `ConvaiManager.ConnectAsync` 来替换该会话的配置——无需修改检查器。

在 `RoomSessionConnectOptions`:

| 属性                          | 类型                             | 替换的内容                    |
| --------------------------- | ------------------------------ | ------------------------ |
| `ActionConfigOverride`      | `ConvaiActionConfig`           | 后端发送的配置（动作名称、对象、角色、关注对象） |
| `ActionDefinitionsOverride` | `List<ConvaiActionDefinition>` | 运行时调度器使用的执行器绑定           |

{% hint style="info" %}
覆盖项仅在 **单个会话内生效**。检查器配置永远不会被修改。除非你提供另一个覆盖项，否则下一个会话会再次使用检查器中的值。
{% endhint %}

### 示例：程序生成的场景

```csharp
using Convai.Runtime.Actions;
using Convai.Runtime.Components;
using Convai.Runtime.Room;
using Convai.Shared.Actions;
using System.Collections.Generic;

public sealed class DynamicSessionStarter : MonoBehaviour
{
    [SerializeField] private ConvaiManager _convaiManager;

    public async void StartSession(List<SpawnedProp> spawnedProps)
    {
        var config = new ConvaiActionConfig();
        config.Actions.Add("Move To");
        config.Actions.Add("Inspect");

        foreach (SpawnedProp prop in spawnedProps)
        {
            config.Objects.Add(new ConvaiActionObjectDefinition
            {
                Name = prop.DisplayName,
                Description = prop.Description,
                GameObjectReference = prop.SceneObject
            });
        }

        if (spawnedProps.Count > 0)
            config.CurrentAttentionObject = spawnedProps[0].DisplayName;

        var options = new RoomSessionConnectOptions
        {
            ActionConfigOverride = config
        };

        await _convaiManager.ConnectAsync(options).AsTask();
    }
}
```

你也可以独立覆盖执行器绑定——当你想在运行时切换移动系统而无需修改检查器时，这非常有用：

```csharp
var options = new RoomSessionConnectOptions
{
    ActionDefinitionsOverride = new List<ConvaiActionDefinition>
    {
        new ConvaiActionDefinition
        {
            ActionName = "Move To",
            TargetRequirement = ConvaiActionTargetRequirement.Object,
            Executor = GetComponent<MyCustomMoveExecutor>(),
            TimeoutSeconds = 10f
        }
    }
};
```

{% hint style="warning" %}
当你设置 `ActionConfigOverride`时，整个 `ConvaiActionConfigSource` 后端配置在该会话中都会被忽略——你必须包含所有希望 AI 了解的动作、对象和角色。
{% endhint %}

{% hint style="info" %}
`ActionDefinitionsOverride` 条目会自动 **过滤** 相对于已解析动作配置的 `动作` 列表进行 `动作名称` 不出现在该列表中的定义会被静默忽略。这意味着，如果你将 `ActionConfigOverride` 设置为仅 `["Move To"]`，那么对 `"Wave"` 的覆盖定义即使包含在内也会被丢弃。
{% endhint %}

***

## 结论

`ConvaiActionConfigSource` 是唯一的检查器面板，控制 AI 角色被允许执行的一切内容。精心编写的对象描述会改善 AI 对场景的推理，而正确的目标要求则可防止在没有有效目标时执行器运行。对于动态场景，连接时覆盖允许你在运行时完全替换配置。

下一步：Action Executors —— 探索 SDK 附带的每一个执行器。


---

# 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/actions/configuring-actions.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.