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

# 动作编辑器

Convai Actions Editor 窗口参考——其四种模式、添加动作目录以及一键执行器配置。

Convai Actions Editor 用于配置 Convai 角色能够执行的操作，包括每个操作的名称、描述和绑定的执行器，无需编辑 `ConvaiActionConfigSource` 本身。还可以从内置执行器目录中添加执行器，并在同一个可撤销步骤中创建该执行器所需的配套组件，例如 `ConvaiGazeController` 或 `ConvaiBodyAnimationController`。

### 打开窗口

选择 **Convai > Actions Editor** 即可打开窗口。工具栏中的 **角色** 字段用于选择窗口显示哪个 `ConvaiCharacter`的操作；如果场景中只有一个角色，还会自动选中该角色。

### 模式

角色选择器下方的模式切换器可在同一角色的四种视图之间切换：

| 模式       | 显示                                                                                                               |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| **动作**   | 默认视图：操作列表和所选操作的详细信息。                                                                                             |
| **场景知识** | 角色的已知对象、已知角色和初始关注对象。                                                                                             |
| **角色设置** | ConvaiActionDispatcher `ConvaiActionDispatcher` （标记为 **Convai Action Runner**）和 `ConvaiActionFeedbackRelay` 的设置。 |
| **实时**   | 仅限播放模式：当前正在运行的批次、近期批次时间线，以及每个操作的运行次数。进入播放模式时会自动切换到此视图；播放模式结束后，如果上次会话的录制仍可用，则会将其标签改为 **会话回顾** 。                   |

除 **实时** 视图外，在编辑器处于播放模式时，所有模式都会禁用编辑功能，并显示说明横幅。

### 操作列表和详细信息

左侧窗格为每个操作列出一张卡片，分组为 **此角色** （直接在此角色上配置的操作），其后是每个已分配 `ConvaiActionSet`各自对应的可折叠分组。选择卡片后，右侧窗格会在四个框中显示其详细信息：

| 框             | 显示                                                                            |
| ------------- | ----------------------------------------------------------------------------- |
| **指令**        | 操作的名称、描述，以及实时渲染的预览，格式为 `This Convai Character can be asked to: "..."`.        |
| **场景行为**      | 已绑定的执行器组件及其解析状态、列出角色层级中所有 `IConvaiActionExecutor` 的下拉列表，以及对象字段备用选项。           |
| **试用**        | 无需开始对话即可运行操作 — 参见 [在没有对话的情况下测试操作](#test-an-action-without-a-conversation) 下文。 |
| **高级** （默认折叠） | 参数、有效目标、超时、失败策略覆盖项和语音门控。                                                      |

### 添加操作目录

点击 **+ Add Action ▾** 工具栏中的按钮可打开目录。目录按固定顺序列出所有带有 `[ConvaiActionArchetype]` 的执行器 — 无论是随附的、示例中的还是项目自定义的。此顺序由 `ConvaiActionArchetypeCatalog.BuildMenuItems()`:

1. **推荐** — 声明了 `FeaturedOrder`的精选内置执行器，按该顺序排列。
2. **更多现成操作** — 其余随附的执行器，按字母顺序排列。
3. **示例操作** — 作为 SDK 示例随附的执行器，单独列在子菜单中。
4. **项目和软件包操作** — 第三方或项目自定义的执行器，按各自类别分组到子菜单中。

一个 **自定义（空白）** 条目位于列表末尾，用于创建不带预设名称、行为或参数的空白操作。项目自定义的执行器永远不会把精选的 **推荐** 部分挤到列表下方 — 无论项目专用执行器有多少，内置执行器始终排在前面。

### 入门卡片

尚无操作的角色会在操作列表的位置显示“添加你的第一个操作”主卡片，其中有四张可一键添加的入门卡片。每张卡片都对应一个内置执行器，该执行器通过 `FeaturedOrder` 中的 1–4 声明自己是入门项：

| 顺序 | 入门项   | 执行器                                |
| -- | ----- | ---------------------------------- |
| 1  | 移动到目标 | `ConvaiWalkToActionExecutor`       |
| 2  | 跟随玩家  | `ConvaiFollowPlayerActionExecutor` |
| 3  | 看向目标  | `ConvaiLookAtActionExecutor`       |
| 4  | 播放手势  | `ConvaiPlayGestureActionExecutor`  |

选择入门卡片会添加该执行器，其方式与从 **+ Add Action ▾** 中选择完全相同 — 参见下文的 [一键添加](#one-click-provisioning) 。 **浏览所有现成操作…**&#x4F4D;于入门卡片旁，会打开与工具栏按钮相同的目录。

### 一键添加

添加内置执行器 — 无论是通过入门卡片还是目录 — 都会作为一个可撤销的操作执行：

1. 新的 `ConvaiActionDefinition` 由执行器的 `[ConvaiActionArchetype]` 属性构建而成：包括其动作名称、描述、目标要求和所有参数。
2. 执行器组件会添加到角色上；如果角色层级中已存在匹配的组件，则会复用该组件。
3. 如果执行器声明了 `RequiredPeerHint` ——例如 `ConvaiGazeController` 或 `ConvaiNavMeshLocomotion` ——而角色尚无匹配组件，则也会添加该组件。
4. 新的定义会绑定到已添加或复用的执行器，并追加到角色的动作列表中。

因此， **看向目标** 入门项可以一键同时添加 `ConvaiLookAtActionExecutor` 和 `ConvaiGazeController` ；而 **走向目标** 则可以同时添加 `ConvaiWalkToActionExecutor` 和 `ConvaiNavMeshLocomotion`。如果组件需要添加到 *目标* 对象而非角色上——例如用于“计数目标组”的 `ConvaiActionTargetGroup` ——则不会以这种方式自动配置，因为由哪个场景对象持有该组件属于创作决策，窗口无法代替你做出选择。

如果执行器的关联组件可以解析，但未自动添加——例如通过 **自定义（空）** 创建动作并在之后绑定到执行器——则 **场景行为** 框中会提供一个一键式的 **添加并绑定** 按钮，按钮名称中会注明执行器，例如 **添加并绑定“看向目标”**.

### 无需进行对话即可测试动作

所选动作的 **试一试** 框会在不调用后端的情况下，运行实际的分发流程：

* **在编辑模式**下， **预览**：在试运行字段中输入短语，系统会使用与运行时相同的目标解析顺序进行检查，并显示该短语会匹配哪个目标以及匹配到哪一步。
* **在播放模式**下， **测试运行**：从以下位置选择一个目标 **有效目标**，填写任意参数，然后点击 **立即运行**。此次运行会经过与真实 Convai 命令完全相同的调度路径，并报告 ✓ 或 ✗、运行时长，以及失败原因（如果失败）。

### 后续步骤

{% content-ref url="/pages/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19" %}
[角色动作快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/quick-start.md)
{% endcontent-ref %}

{% 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/111bca064ba7041a987662d038af4d71d58a32cd" %}
[配置角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.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-editor.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.
