> 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-unreal-engine-plugin/ai-coding-assistant/convai-toolset-reference.md).

# Convai 工具集参考

可由连接的编码代理调用的七个编辑器操作参考，用于设置 Convai 角色、玩家和动作。

Convai 工具集注册了七个 `AICallable` 编辑器操作，使用引擎的 `ToolsetRegistry` 插件，分布在 `UConvaiSetupToolset` 和 `UConvaiActionToolset` 在 `Source/ConvaiToolsetGated/Private/ConvaiToolset.h`。需要 **Unreal Engine 5.8 或更高版本** 以及一个 **编辑器** 构建——该 `ConvaiToolset` 模块在任何非 Editor 目标上都会抛出构建错误，而其受条件限制的部分在 UE 5.8 以下会完全编译排除。

{% hint style="warning" %}
这七个操作是 `AICallable`，而不是 `BlueprintCallable`。连接的编码代理通过引擎的 MCP 服务器调用它们——它们不会出现在 Blueprint 节点面板中，任何 Blueprint 图表都无法调用它们。
{% endhint %}

### 全部七个操作

| Action                             | 工具集类                   | 作用                                   |
| ---------------------------------- | ---------------------- | ------------------------------------ |
| `SetupConvaiCharacter`             | `UConvaiSetupToolset`  | 将角色 Blueprint 转换为可对话的 Convai 角色      |
| `SetupConvaiPlayer`                | `UConvaiSetupToolset`  | 向玩家 Pawn Blueprint 添加 Convai 玩家组件    |
| `SetupConvaiPawnMovement`          | `UConvaiSetupToolset`  | 为角色/pawn Blueprint 设置经过 Convai 调优的移动 |
| `AddNavMeshVolumeForCurrentLevel`  | `UConvaiSetupToolset`  | 生成一个与当前关卡大小匹配的导航网格边界体积               |
| `SetBlueprintPropertyAndPropagate` | `UConvaiSetupToolset`  | 设置一个 Blueprint 属性，并将其传播到已放置的关卡实例     |
| `AddConvaiAction`                  | `UConvaiActionToolset` | 向聊天机器人的操作列表追加一个带参数的操作                |
| `CreateConvaiActionHandler`        | `UConvaiActionToolset` | 为指定操作合成一个 Blueprint 事件处理器            |

每个操作都会返回一条可读的状态字符串，说明它更改了什么，并且是幂等的——使用相同输入再次调用时，会复用现有组件或值，而不是重复创建。

### `SetupConvaiCharacter`

将角色 Blueprint 转换为可对话的 Convai 角色。添加 `BP_ConvaiChatbotComponent` 以及一个原生 `ConvaiFaceSyncComponent` 如果其中任一缺失，则设置聊天机器人角色 ID，并启用 `bAutoFillConversationPartnerFromPlayer`，将面部同步口型同步模式设置为 MetaHuman blendshape 模式（`BS_MHA`），启用插值，并将 Convai MetaHuman 面部和身体动画 Blueprints 分配给名为 `Face` 和 `Body`的骨骼网格组件。编译并保存 Blueprint。

| 参数                       | 类型        | 默认值   | 描述                                                    |
| ------------------------ | --------- | ----- | ----------------------------------------------------- |
| `CharacterBlueprintPath` | `FString` | —（必填） | MetaHuman/角色 Blueprint 的对象路径，例如 `/Game/NPCs/BP_Guard` |
| `CharacterId`            | `FString` | —（必填） | 要分配给聊天机器人组件的 Convai 后端 Character ID                   |

返回一条可读的状态字符串，描述已更改的内容。

### `SetupConvaiPlayer`

将 Convai 玩家组件添加到玩家的 Pawn Blueprint——玩家所控制的角色——使玩家可以与 Convai 角色对话。添加 `BP_ConvaiPlayerComponent` 如果缺失，则编译并保存 Blueprint。

| 参数                    | 类型        | 默认值   | 描述                                                                                                    |
| --------------------- | --------- | ----- | ----------------------------------------------------------------------------------------------------- |
| `PlayerBlueprintPath` | `FString` | —（必填） | 玩家 Pawn Blueprint（被控制/可操控的角色，拥有摄像机和输入）的对象路径，例如 `/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter` |

返回一条可读的状态字符串，描述已更改的内容。

### `SetupConvaiPawnMovement`

为角色/pawn Blueprint 设置经过 Convai 调优的移动，使其能够导航。如果该 Blueprint 的父类只是一个普通的 `AActor`，则会重新指定父类为 `APawn`。一个 `UFloatingPawnMovement` 组件，如果尚未存在或继承，则添加该组件，并应用 Convai 移动默认值（`MaxSpeed=375`, `Acceleration=200`, `Deceleration=250`, `TurningBoost=3`，以及导航路径跟随默认值）。对于基于 Character 的 Blueprints，继承的 `CharacterMovementComponent` 则会改为调整为等效的行走速度和导航代理默认值。安全时编译 Blueprint 并保存。

| 参数                       | 类型        | 默认值   | 描述                                               |
| ------------------------ | --------- | ----- | ------------------------------------------------ |
| `CharacterBlueprintPath` | `FString` | —（必填） | 角色/pawn Blueprint 的对象路径，例如 `/Game/NPCs/BP_Guard` |

返回一条可读的状态字符串，描述已更改的内容。

### `AddNavMeshVolumeForCurrentLevel`

在当前编辑器关卡中生成一个 `NavMeshBoundsVolume` ，使 Convai 角色可以进行路径查找。默认情况下，该体积居中并调整大小以覆盖关卡中所有 Actor 的合并边界。生成体积后会重建导航。

| 参数   | 类型                   | 默认值 | 描述                                |
| ---- | -------------------- | --- | --------------------------------- |
| `位置` | `TOptional<FVector>` | 未设置 | 体积的可选世界空间中心。若未设置，则使用关卡边界中心        |
| `范围` | `TOptional<FVector>` | 未设置 | 体积盒的可选半范围（厘米）。若未设置，则根据关卡边界并加上边距推导 |

返回一条可读的状态字符串，包含最终体积位置和范围。

### `SetBlueprintPropertyAndPropagate`

设置 Blueprint 上的一个属性，并将新值传播到每个已放置且仍保留旧值的关卡实例，同时保留每个实例的覆盖。既可处理组件模板属性（在其中传入组件变量名 `ComponentName`），也可处理 Actor/Blueprint 级属性（将 `ComponentName` 留空）。当更改也必须影响已经放置在关卡中的角色时，请使用此方法，而不是直接设置属性并编译——引擎自带的属性设置工具或普通的 Blueprint 编译都不会将模板或类默认对象的编辑传播到已放置实例。该值通过属性自身的文本导入器解析，因此任何类型都可以： `300.0` （float）， `true` （bool）， `你好` （字符串/名称）， `（X=0,Y=0,Z=300）` （向量/结构体）， `/Game/P.A` （对象）。编译并保存 Blueprint。

| 参数              | 类型        | 默认值       | 描述                                                                |
| --------------- | --------- | --------- | ----------------------------------------------------------------- |
| `BlueprintPath` | `FString` | —（必填）     | Blueprint 的对象路径，例如 `/Game/NPCs/BP_Guard`                          |
| `ComponentName` | `FString` | —（必填，可为空） | 该组件的 Blueprint 变量名，例如 `ProximitySphere`。对于 Actor/Blueprint 级属性请留空 |
| `PropertyName`  | `FString` | —（必填）     | 属性名称，例如 `SphereRadius` （组件）或 `MyVar` （Actor 级）                    |
| `ValueAsString` | `FString` | —（必填）     | Unreal 文本形式的新值，由属性导入器解析                                           |

返回一条可读的状态字符串，包含已更新的已放置实例数量。

{% hint style="info" %}
通过以下方式编辑属性 `SetBlueprintPropertyAndPropagate` 从一开始。先前通过原始属性设置而已失同步的值，在传播逻辑看来会像是每实例覆盖，因此不会被更新。
{% endhint %}

### `AddConvaiAction`

将一个带参数的操作追加到聊天机器人的 Environment 操作列表中。定位 `BP_ConvaiChatbotComponent` （或任何 `UConvaiChatbotComponent`）于给定 Blueprint 上，启用 `EnvironmentData.bEnableActions`，并添加一个 `FConvaiAction` ，其名称、描述和参数按给定内容设置，同时保留现有操作。若存在同名操作，则会原地替换。编译并保存 Blueprint。这些操作会在聊天机器人下次连接时生效——它们准备的是下一次会话，而不是当前在线会话。

| 参数                       | 类型                                  | 默认值   | 描述                                       |
| ------------------------ | ----------------------------------- | ----- | ---------------------------------------- |
| `CharacterBlueprintPath` | `FString`                           | —（必填） | 拥有聊天机器人组件的 Blueprint 的对象路径               |
| `ActionName`             | `FString`                           | —（必填） | 规范化操作名称，例如 `Wave`, `拾取`, `说`。应与处理器事件名称匹配 |
| `描述`                     | `FString`                           | —     | 该操作作用的人类可读描述                             |
| `Parameters`             | `TArray<FConvaiToolsetActionParam>` | —     | 调用时代理应填写的已声明参数有序列表（名称、描述、类型和可选项）         |

`FConvaiToolsetActionParam` 镜像了面向代理的以下子集： `FConvaiActionParam`:

| 字段        | 类型                       | 描述                                                                                                                            |
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `名称`      | `FString`                | 代理看到的占位符名称，例如 `文本`, `destination`, `秒数`                                                                                       |
| `描述`      | `FString`                | 可选的人类可读参数含义描述                                                                                                                 |
| `类型`      | `EConvaiActionParamType` | 该值的解释方式： `String`, `Number`, `Reference` （根据聊天机器人已知的 Objects/Characters 解析）， `Bool`, `Enum`，或 `Auto` （默认，在解析时推断）              |
| `Choices` | `TArray<FString>`        | 对于固定选项集参数，允许的值，与以下项一起使用： `Type=String`. `AddConvaiAction` 无法提供一个 `UEnum`，因此一个 `Type=Enum` 参数会被强制转换为 `String` ，其选项列在 `Choices` |

返回一条可读的状态字符串，描述已更改的内容。

### `CreateConvaiActionHandler`

在 Blueprint 的事件图中合成一个 Convai 操作处理器。创建一个名称完全为以下内容的 Custom Event： `ActionName` ，并带有一个类型为以下内容的单个输入引脚： `FConvaiResultAction`，并将其执行输出连接到一个 `HandleActionCompletion` 对 Blueprint 的聊天机器人组件的调用；如果存在，则自动从组件变量连接聊天机器人 self 引脚。这是以下内容在运行时的契约： `UConvaiChatbotComponent::TriggerNamedBlueprintAction` 所期望的。编译 Blueprint。

| 参数              | 类型        | 默认值   | 描述                               |
| --------------- | --------- | ----- | -------------------------------- |
| `BlueprintPath` | `FString` | —（必填） | 要添加处理器的 Blueprint 的对象路径          |
| `ActionName`    | `FString` | —（必填） | 精确的操作名称；创建的 Custom Event 也使用相同名称 |

成功时返回创建的事件名称，或返回以前缀以下内容开头的错误字符串： `错误：`.

### 下一步

{% content-ref url="/pages/6c5b338b9a5aeacf26b73bf6839fa355e17f8687" %}
[AI 编码助手](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant.md)
{% endcontent-ref %}

{% content-ref url="/pages/50ad5ea121945ebc9be68f274b2be07d5ff35a2d" %}
[AI 编码助手快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/7c626321bfe9ecc73b233eae6e2ceeeb539c83b0" %}
[Convai AgentSkills](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/convai-agent-skills.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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/convai-toolset-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.