> 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/ai-coding-assistant/mcp-tools-reference.md).

# MCP 工具参考

Unity 的官方 MCP 服务器在 `Convai.*` 命名空间中公开了 37 个 Convai 专用工具，工具契约版本为 4，因此已连接的编码代理可以检查、配置或诊断 Convai 组件，而不是由你在 Unity 编辑器中手动接线。Unity AI Assistant 会通过点分隔名称调用工具（例如 `Convai.GetGuidance`）；外部 MCP 客户端会以统一为下划线的名称接收同一工具（`Convai_GetGuidance`）。自那以来，大部分新增内容都来自 `4.4.0` 具现化模块浪潮——Gaze、Body Animation、Body Language 和 Emotion 各自都配套提供了自己的 Configure、Diagnose 和内容检查工具，并由三个 Embodiment 核心工具串联起来。本页记录每个工具的用途、参数、默认启用状态，以及对场景或项目的修改行为，全文统一使用点分隔名称。

### 全部 37 个工具

| 工具                                        | 领域        | 默认启用 | 会修改                                                        |
| ----------------------------------------- | --------- | ---- | ---------------------------------------------------------- |
| `Convai.GetGuidance`                      | 指导        | 是    | 没有                                                         |
| `Convai.GetProjectStatus`                 | 基础        | 是    | 没有                                                         |
| `Convai.InspectScene`                     | 基础        | 是    | 没有                                                         |
| `Convai.ValidateSetup`                    | 基础        | 是    | 没有                                                         |
| `Convai.BootstrapScene`                   | 场景和对话设置   | 没有   | 是——仅限编辑模式； `dryRun` 默认值因调用方而异（见下文）                         |
| `Convai.ConfigureRoom`                    | 场景和对话设置   | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.ConfigurePlayer`                  | 场景和对话设置   | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.ConfigureCharacter`               | 场景和对话设置   | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.SetupConversationScene`           | 场景和对话设置   | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseConversation`             | 场景和对话设置   | 是    | 没有                                                         |
| `Convai.ConfigureActions`                 | 角色动作      | 是    | 是——仅限编辑模式                                                  |
| `Convai.DiagnoseActions`                  | 角色动作      | 是    | 没有                                                         |
| `Convai.SimulateAction`                   | 角色动作      | 是    | 仅限播放模式，通过调度器                                               |
| `Convai.ConfigureLipSync`                 | 口型同步      | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseLipSync`                  | 口型同步      | 是    | 没有                                                         |
| `Convai.ConfigureTranscripts`             | 转录文本      | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseTranscripts`              | 转录文本      | 是    | 没有                                                         |
| `Convai.ConfigureNarrative`               | Narrative | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseNarrative`                | Narrative | 是    | 没有                                                         |
| `Convai.TraceRuntimeEvents`               | 运行时诊断     | 是    | 否——仅管理仅编辑器可用的跟踪缓冲区                                         |
| `Convai.ConfigureEmbodiment`              | 实体化       | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseEmbodiment`               | 实体化       | 是    | 没有                                                         |
| `Convai.InspectEmbodimentPresets`         | 实体化       | 是    | 没有                                                         |
| `Convai.ConfigureGaze`                    | 注视        | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseGaze`                     | 注视        | 是    | 没有                                                         |
| `Convai.MarkGazeTarget`                   | 注视        | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.ConfigureBodyAnimation`           | 身体动画      | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseBodyAnimation`            | 身体动画      | 是    | 没有                                                         |
| `Convai.InspectBodyAnimationContent`      | 身体动画      | 是    | 没有                                                         |
| `Convai.TuneBodyAnimationPersonality`     | 身体动画      | 是    | 是——仅限编辑模式；还会复制一个共享配置资源，其操作受以下条件控制： `makeConfigUnique`      |
| `Convai.ConfigureBodyLanguage`            | 肢体语言      | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseBodyLanguage`             | 肢体语言      | 是    | 没有                                                         |
| `Convai.InspectBodyLanguagePersonalities` | 肢体语言      | 是    | 没有                                                         |
| `Convai.ConfigureEmotion`                 | 情绪        | 是    | 是——仅限编辑模式； `dryRun` 默认为 `true`                             |
| `Convai.DiagnoseEmotion`                  | 情绪        | 是    | 没有                                                         |
| `Convai.InspectEmotionPersonalities`      | 情绪        | 是    | 没有                                                         |
| `Convai.TuneEmotionPersonality`           | 情绪        | 是    | 是——仅限编辑模式；还会复制一个共享人格资源，其操作受以下条件控制： `makePersonalityUnique` |

在以下位置切换任意工具 **Edit > Project Settings > AI > Unity MCP Server**.

### 指导

#### `Convai.GetGuidance`

**区域：** 指导 · **默认启用：** 是 · **修改：** 没有

为单个主题加载简明的 Convai SDK 工作流指导。在配置或调试 Convai 功能之前调用它；它不用于通用 Unity 操作。响应包含摘要、前提条件、按顺序排列的工作流、相关的 Convai 和 Unity 工具，以及文档路径。

| 参数   | 类型                       | 默认值  | 描述         |
| ---- | ------------------------ | ---- | ---------- |
| `主题` | `枚举 ConvaiGuidanceTopic` | `概览` | 要加载的工作流主题。 |

`ConvaiGuidanceTopic` 取值及其返回内容：

| 主题               | 返回摘要                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `概览` (默认)        | 仅将 Convai 工具用于了解 SDK 的操作；通用项目更改请组合使用官方 Unity MCP 工具。                                      |
| `设置`             | 主动完成可运行的 Convai 场景设置；显式的设置请求即授权使用安全、可逆的默认值。                                               |
| `动作`             | 明确编写动作能力并绑定本地执行器；绝不要从场景元数据推断能力。                                                           |
| `DynamicContext` | 通过角色动态上下文外观来发送状态、事件和注意对象变更。                                                               |
| `视觉`             | 在启用视频模式之前，先在房间层级下配置一个视觉发布器和一个帧源。                                                          |
| `Narrative`      | 将 Narrative 模块用于章节状态以及命名或内联触发工作流。                                                         |
| `实体化`            | 从每个具现化模块各自的品牌化 Configure/Diagnose 对开始配置； `Convai.DiagnoseEmbodiment`；当同伴模块缺失时，每个功能都会优雅降级。 |
| `注视`             | 添加 Gaze 组件并查看眼神接触是否生效；Player Anchor 和 watches 区块说明了角色将什么视为玩家。                             |
| `身体动画`           | 身体动画受内容门控——若角色的动画集合没有包含对应片段，若干行为会保持不活跃；这是内容缺口，不是设置故障。                                     |
| `BodyLanguage`   | Body Language 会在 Body Animation 和 Gaze 之上叠加环境化的非语言动作，并在任一模块存在时自动隐藏自身。                     |
| `情绪`             | 让角色拥有会对所说内容作出反应的面部，并在不重塑与其共享该人格的其他角色的前提下调整其性情。                                            |
| `事件`             | 优先使用 `ConvaiManager.Events` 用于类型化代码，并将组件用于由 Inspector 驱动的 `UnityEvent`设置。                 |
| `运行时`            | 使用 `ConvaiManager` 用于会话所有权，Audio 用于房间音频，Transcripts 用于规范历史记录。                             |

### 基础

#### `Convai.GetProjectStatus`

**区域：** 基础 · **默认启用：** 是 · **修改：** 没有

读取 Convai SDK、Unity AI Assistant 和非机密项目配置状态。绝不返回 Convai API 密钥。

无输入参数。

返回 `sdkVersion`, `unityVersion`, `assistantVersion`, `toolContractVersion`, `credentialsConfigured`, `serverUrl`, `transcriptSystemEnabled`, `notificationSystemEnabled`, `backgroundPolicy`, `defaultMicrophoneDeviceId`, `connectionTimeoutSeconds`, `isPlaying`, `isCompiling`，以及 `packageRoot`.

#### `Convai.InspectScene`

**区域：** 基础 · **默认启用：** 是 · **修改：** 没有

检查打开的场景中的 `ConvaiManager`, `ConvaiRoomManager`, `ConvaiPlayer`，以及 `ConvaiCharacter` 组件，并返回精确的实例 ID，以便后续修改。

| 参数                | 类型     | 默认值    | 描述                        |
| ----------------- | ------ | ------ | ------------------------- |
| `includeInactive` | `bool` | `true` | 包括已禁用的 `GameObject`对象和组件。 |

#### `Convai.ValidateSetup`

**区域：** 基础 · **默认启用：** 是 · **修改：** 没有

在不更改资源或场景的情况下验证 Convai 项目和场景就绪状态。在 Convai 编写操作之前和之后调用。返回 `错误`, `警告`，以及 `下一步`，并折叠汇总每个具现化模块自身的发现，针对活动场景中的每个 `ConvaiCharacter` 活动场景中的。

| 参数   | 类型                         | 默认值  | 描述                       |
| ---- | -------------------------- | ---- | ------------------------ |
| `范围` | `枚举 ConvaiValidationScope` | `所有` | 验证范围： `所有`, `项目`，或 `场景`. |

### 场景和对话设置

#### `Convai.BootstrapScene`

**区域：** 场景和对话设置 · **默认启用：** 否 · **修改：** 是

以幂等方式将所需的 `ConvaiManager` 和 `ConvaiRoomManager` 添加到活动场景中。不会添加玩家、角色，不会保存场景，也不会设置凭据。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数       | 类型     | 默认值                                                 | 描述             |
| -------- | ------ | --------------------------------------------------- | -------------- |
| `dryRun` | `bool` | `true` 通过 Unity AI Assistant； `false` 通过外部 MCP 工具契约 | 预览所需更改，而不修改场景。 |

{% hint style="warning" %}
`Convai.BootstrapScene` 是 37 个工具中唯一默认禁用的工具。其 `dryRun` 默认值也取决于代理如何调用它：Unity AI Assistant 的点名封装默认 `dryRun` 到 `true` 与其他所有会修改的工具一样，但外部 MCP 客户端所使用的底层 MCP 工具契约（下划线命名的 `Convai_BootstrapScene`) 默认 `dryRun` 到 `false` ——这些客户端会立即应用更改，除非它们传入 `dryRun: true` 显式地。优先使用 `Convai.SetupConversationScene` 用于端到端设置； `Convai.BootstrapScene` 仅在管理器/仅房间工作时使用。
{% endhint %}

#### `Convai.ConfigureRoom`

**区域：** 场景和对话设置 · **默认启用：** 是 · **修改：** 是

预览或配置一个 Convai 房间—— `ConvaiManager` 和 `ConvaiRoomManager` ——在明确目标上 `GameObject`，使用内联设置或现有的 `ConvaiRoomManagerProfile`。使用 Unity 的撤销系统，绝不保存场景，也绝不更改凭据。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                  | 类型                               | 默认值         | 描述                                                                  |
| ------------------- | -------------------------------- | ----------- | ------------------------------------------------------------------- |
| `targetInstanceId`  | `long`                           | ——（必填）      | 拥有或将要拥有该对象的 GameObject 实例 ID `ConvaiManager` 和 `ConvaiRoomManager`. |
| `configurationMode` | `枚举 ConvaiToolConfigurationMode` | `内联`        | `内联` 或 `现有配置文件`.                                                    |
| `profileAssetPath`  | `string`                         | `""`        | 现有 `ConvaiRoomManagerProfile` 资源路径。在以下情况下必填： `现有配置文件` 模式使用。         |
| `connectionType`    | `枚举 ConvaiConnectionType`        | `音频`        | 内联连接类型。                                                             |
| `inputMode`         | `枚举 ConversationInputMode`       | `HandsFree` | 内联对话输入模式。                                                           |
| `connectOnStart`    | `bool`                           | `true`      | 场景启动时自动连接。                                                          |
| `serverEndpoint`    | `枚举 ConvaiServerEndpoint`        | `连接`        | 核心服务端点。                                                             |
| `visionMode`        | `枚举 ConvaiVisionContextMode`     | `自动`        | 动态视觉策略。                                                             |
| `pushToTalkKey`     | `string`                         | `"T"`       | Unity `键码` 按住说话使用的名称。                                               |
| `dryRun`            | `bool`                           | `true`      | 预览更改，而不修改场景。                                                        |

#### `Convai.ConfigurePlayer`

**区域：** 场景和对话设置 · **默认启用：** 是 · **修改：** 是

预览或添加并配置 `ConvaiPlayer` 在明确目标上 `GameObject`，然后绑定一个唯一明确的管理器。绝不修改 `主摄像机`。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                  | 类型       | 默认值        | 描述                                             |
| ------------------- | -------- | ---------- | ---------------------------------------------- |
| `targetInstanceId`  | `long`   | ——（必填）     | 目标玩家 GameObject 实例 ID。                         |
| `managerInstanceId` | `long`   | `0`        | 可选的管理器 GameObject 实例 ID。为 0 时会在目标场景中自动解析一个管理器。 |
| `playerName`        | `string` | `“Player”` | 玩家显示名称。                                        |
| `playerId`          | `string` | `""`       | 可选的本地转录归属 ID。默认为玩家名称。                          |
| `dryRun`            | `bool`   | `true`     | 预览更改，而不修改场景。                                   |

#### `Convai.ConfigureCharacter`

**区域：** 场景和对话设置 · **默认启用：** 是 · **修改：** 是

预览或添加并配置 `ConvaiCharacter` 并采用推荐的音频输出—— `AudioSource` 和 `ConvaiAudioOutput` ——在明确目标上 `GameObject`。缺少角色 ID 仍然是明确的就绪阻塞项：该工具会返回 `complete=false` 和 `requiredInputs=["characterId"]` ，而不是自行猜测。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                  | 类型                               | 默认值    | 描述                                                        |
| ------------------- | -------------------------------- | ------ | --------------------------------------------------------- |
| `targetInstanceId`  | `long`                           | ——（必填） | 目标角色 GameObject 实例 ID。                                    |
| `managerInstanceId` | `long`                           | `0`    | 可选的管理器 GameObject 实例 ID。为 0 时会在目标场景中自动解析一个管理器。            |
| `configurationMode` | `枚举 ConvaiToolConfigurationMode` | `内联`   | `内联` 或 `现有配置文件`.                                          |
| `profileAssetPath`  | `string`                         | `""`   | 现有 `ConvaiCharacterProfile` 资源路径。在以下情况下必填： `现有配置文件` 模式使用。 |
| `characterId`       | `string`                         | `""`   | Convai 仪表板角色 ID。在编写不完整的占位符时可以省略。                          |
| `characterName`     | `string`                         | `""`   | 角色显示名称。默认为目标 GameObject 名称。                               |
| `addAudioOutput`    | `bool`                           | `true` | 确保 `AudioSource` 和 `ConvaiAudioOutput` 同伴。                |
| `dryRun`            | `bool`                           | `true` | 预览更改，而不修改场景。                                              |

#### `Convai.SetupConversationScene`

**区域：** 场景和对话设置 · **默认启用：** 是 · **修改：** 是

使用安全占位符和推荐默认值，在活动场景中预览或执行端到端音频对话设置。选择顺序依次为明确的实例 ID、一个明确无歧义的现有组件，然后是一个安全占位符——一个独立的 `Convai 玩家` 以及一个可见的胶囊体 `Convai 角色` ——当不存在时。绝不保存场景、进入播放模式或设置凭据。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                  | 类型                         | 默认值           | 描述                                   |
| ------------------- | -------------------------- | ------------- | ------------------------------------ |
| `managerInstanceId` | `long`                     | `0`           | 可选的管理器目标实例 ID。                       |
| `玩家实例 ID`           | `long`                     | `0`           | 可选的玩家目标实例 ID。                        |
| `角色实例 ID`           | `long`                     | `0`           | 可选的角色目标实例 ID。                        |
| `房间配置文件资源路径`        | `string`                   | `""`          | 可选的现有 `ConvaiRoomManagerProfile` 路径。 |
| `角色配置文件资源路径`        | `string`                   | `""`          | 可选的现有 `ConvaiCharacterProfile` 路径。   |
| `characterId`       | `string`                   | `""`          | Convai 仪表板角色 ID。在所有独立设置完成之前可以省略。     |
| `characterName`     | `string`                   | `"Convai 角色"` | 角色显示名称。                              |
| `playerName`        | `string`                   | `“Player”`    | 玩家显示名称。                              |
| `playerId`          | `string`                   | `""`          | 可选的本地转录归属 ID。                        |
| `inputMode`         | `枚举 ConversationInputMode` | `HandsFree`   | 推荐的房间输入模式。                           |
| `connectOnStart`    | `bool`                     | `true`        | 场景启动时自动连接。                           |
| `创建占位符`             | `bool`                     | `true`        | 当不存在时，创建独立的玩家和胶囊体角色占位符。              |
| `dryRun`            | `bool`                     | `true`        | 预览更改，而不修改场景。                         |

#### `Convai.DiagnoseConversation`

**区域：** 场景和对话设置 · **默认启用：** 是 · **修改：** 没有

诊断活动场景中的 Convai 对话就绪状态和运行时状态，提供排序后的证据和建议修复。可在编辑模式和播放模式下工作。绝不修改项目，也不返回 API 密钥。

| 参数                | 类型     | 默认值    | 描述                        |
| ----------------- | ------ | ------ | ------------------------- |
| `角色实例 ID`         | `long` | `0`    | 可选的聚焦角色 GameObject 实例 ID。 |
| `includeInactive` | `bool` | `true` | 包含非活动场景对象。                |

返回 `可运行就绪`、配置和运行时快照，以及一个 `问题` 数组，包含稳定的代码、证据， `可自动修复`，以及 `建议工具`/`建议参数` 针对每个问题。

### 角色动作

#### `Convai.ConfigureActions`

**区域：** 角色动作 · **默认启用：** 是 · **修改：** 是

预览或安全地按名称更新类型化动作定义，以及在 Convai 角色上的明确对象或角色目标。使用 Undo 且绝不保存。若定义没有绑定执行器，则会获得一个未接线的 `UnityEvent` 占位符，并在接线之前保持不完整。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数        | 类型       | 默认值    | 描述                                                                                                                                                  |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `角色实例 ID` | `long`   | ——（必填） | 角色 GameObject 或组件实例 ID。                                                                                                                             |
| `定义`      | `数组`     | `[]`   | 按名称更新的类型化动作定义。参见 [角色动作脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 以了解完整字段集。 |
| `对象`      | `数组`     | `[]`   | 按名称更新的明确可执行 GameObject。                                                                                                                             |
| `角色`      | `数组`     | `[]`   | 按名称更新的明确可执行角色。                                                                                                                                      |
| `初始注意对象`  | `string` | `""`   | 可选的编写对象名称，用作初始注意对象。                                                                                                                                 |
| `dryRun`  | `bool`   | `true` | 预览更改，而不修改场景。                                                                                                                                        |

#### `Convai.DiagnoseActions`

**区域：** 角色动作 · **默认启用：** 是 · **修改：** 没有

诊断动作定义、执行器、目标、注意对象、调度器是否存在以及运行时可用性，不做修改。

| 参数                | 类型     | 默认值    | 描述          |
| ----------------- | ------ | ------ | ----------- |
| `角色实例 ID`         | `long` | `0`    | 可选的角色实例 ID。 |
| `includeInactive` | `bool` | `true` | 包含非活动对象。    |

#### `Convai.SimulateAction`

**区域：** 角色动作 · **默认启用：** 是 · **修改：** 仅限播放模式

在编辑模式下验证动作负载，或在播放模式下通过真实运行时 `ConvaiActionDispatcher` 进行分发。绝不更改播放模式本身。

| 参数        | 类型                           | 默认值    | 描述                       |
| --------- | ---------------------------- | ------ | ------------------------ |
| `角色实例 ID` | `long`                       | ——（必填） | 角色实例 ID。                 |
| `动作名称`    | `string`                     | ——（必填） | 已配置的动作名称。                |
| `目标`      | `string`                     | `""`   | 可选目标名称。                  |
| `参数`      | `dictionary<string, string>` | `{}`   | 以编写时的参数名称为键的可选动作参数值。     |
| `超时时间（秒）` | `float`                      | `10`   | 完成超时，限制在 `0.1` 和 `60` 秒。 |

在编辑模式下，该工具返回 `executed=false` 和 `requiresPlayMode=true` 在验证负载之后。在播放模式下，它会将命令排入角色的调度器，并等待一个 `ConvaiActionStepReport`，并返回 `SIMULATION_TIMEOUT` 如果该步骤未在以下时间内完成 `超时时间（秒）`.

### 口型同步

#### `Convai.ConfigureLipSync`

**区域：** 口型同步 · **默认启用：** 是 · **修改：** 是

使用现有网格、随附配置文件和可选的现有口型同步映射资源，预览或配置 Convai 口型同步。绝不创建或修改资源。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                 | 类型                      | 默认值    | 描述                                                                                |
| ------------------ | ----------------------- | ------ | --------------------------------------------------------------------------------- |
| `角色实例 ID`          | `long`                  | ——（必填） | 角色 GameObject 实例 ID。                                                              |
| `meshInstanceIds`  | `long[]`                | `[]`   | 目标网格实例 ID。为空时会解析角色下的每个 `SkinnedMeshRenderer` 下的对象。                                |
| `配置文件`             | `string`                | `"自动"` | `自动`, `arkit`, `cc4_extended`，或 `metahuman`. `自动` 要求在目标网格之间存在唯一的 blendshape 名称匹配。 |
| `mappingAssetPath` | `string`                | `""`   | 现有 `ConvaiLipSyncMapAsset` 路径。                                                    |
| `latencyMode`      | `枚举 LipSyncLatencyMode` | `平衡`   | `平衡`, `超低延迟`, `网络安全`，或 `Custom`.                                                  |
| `dryRun`           | `bool`                  | `true` | 预览更改，而不修改场景。                                                                      |

参见 [添加口型同步](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync.md) 用于该工具自动化的 Inspector 工作流。

#### `Convai.DiagnoseLipSync`

**区域：** 口型同步 · **默认启用：** 是 · **修改：** 没有

诊断 `ConvaiLipSyncComponent`、目标网格、blendshape 兼容性、映射、配置文件以及已清理的运行时缓冲区状态。

| 参数                      | 类型     | 默认值    | 描述                                                                        |
| ----------------------- | ------ | ------ | ------------------------------------------------------------------------- |
| `角色实例 ID`               | `long` | `0`    | 角色 GameObject 实例 ID。                                                      |
| `includeRuntimeMetrics` | `bool` | `true` | 包含 `isPlaying`, `isTalking`, `isFadingOut`, `engineState`、缓冲和流式持续时间，以及余量。 |

### 转录文本

#### `Convai.ConfigureTranscripts`

**区域：** 转录 · **默认启用：** 是 · **修改：** 是

预览或配置规范的转录外观、事件中继或随附聊天 UI。绝不更改 `ConvaiSettings` 或暴露转录文本。仅限编辑模式——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                  | 类型                            | 默认值     | 描述                             |
| ------------------- | ----------------------------- | ------- | ------------------------------ |
| `managerInstanceId` | `long`                        | `0`     | 可选的管理器实例 ID。                   |
| `hostInstanceId`    | `long`                        | `0`     | 可选的主机 GameObject 实例 ID。        |
| `模式`                | `枚举 ConvaiTranscriptToolMode` | `事件中继`  | `事件中继`, `聊天 UI`，或 `世界空间聊天 UI`. |
| `finalOnly`         | `bool`                        | `false` | 仅转发最终更新。                       |
| `ignoreInterim`     | `bool`                        | `true`  | 忽略中间更新。                        |
| `角色 ID 过滤器`         | `string`                      | `""`    | 可选的角色 ID 过滤器。                  |
| `dryRun`            | `bool`                        | `true`  | 预览更改，而不修改场景。                   |

参见 [转录 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md) 用于该工具接线的运行时外观。

#### `Convai.DiagnoseTranscripts`

**区域：** 转录 · **默认启用：** 是 · **修改：** 没有

诊断转录启用状态、外观就绪状态、中继、UI，以及已清理的运行时时间线元数据。

| 参数                  | 类型     | 默认值     | 描述             |
| ------------------- | ------ | ------- | -------------- |
| `managerInstanceId` | `long` | `0`     | 可选的管理器实例 ID。   |
| `包含文本`              | `bool` | `false` | 仅在明确请求时包含转录文本。 |

### Narrative

#### `Convai.ConfigureNarrative`

**区域：** 叙事 · **默认启用：** 是 · **修改：** 是

预览或配置 Unity 侧的叙事章节映射、模板键和触发器—— `ConvaiNarrativeDesignManager` 和 `ConvaiNarrativeDesignTrigger`。保留无关条目和 `UnityEvent`s，并且从不联系 Convai。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                      | 类型     | 默认值    | 描述                                                                                                                                                 |
| ----------------------- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `角色实例 ID`               | `long` | ——（必填） | 角色 GameObject 实例 ID。                                                                                                                               |
| `managerHostInstanceId` | `long` | `0`    | 叙事管理器的可选宿主 GameObject 实例 ID。                                                                                                                       |
| `sections`              | `数组`   | `[]`   | 要新增或更新的叙事分区，每个 `{ sectionId, sectionName }`.                                                                                                       |
| `templateKeys`          | `数组`   | `[]`   | 要新增或更新的模板键，每个 `{ key, value }`.                                                                                                                    |
| `triggers`              | `数组`   | `[]`   | 要新增或更新的触发器。参见 [叙事设计脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/scripting-narrative-design.md) 以获取完整的触发器字段集。 |
| `dryRun`                | `bool` | `true` | 预览更改，而不修改场景。                                                                                                                                       |

#### `Convai.DiagnoseNarrative`

**区域：** 叙事 · **默认启用：** 是 · **修改：** 没有

诊断 Unity 端叙事角色绑定、重复或孤立的分区、模板键、触发器、玩家筛选器、缓存的同步错误以及运行时触发器状态。

| 参数                | 类型     | 默认值     | 描述                   |
| ----------------- | ------ | ------- | -------------------- |
| `角色实例 ID`         | `long` | `0`     | 角色 GameObject 实例 ID。 |
| `includeInactive` | `bool` | `true`  | 包含非活动对象。             |
| `includeContent`  | `bool` | `false` | 包含模板值和触发器名称。默认隐藏内容。  |

### 运行时诊断

#### `Convai.TraceRuntimeEvents`

**区域：** 运行时诊断 · **默认启用：** 是 · **修改：** 否（仅管理编辑器专用跟踪缓冲区）

启动、读取、清除或停止一个有上限的、仅限编辑器的 Convai 运行时事件跟踪，最多 256 条条目。该跟踪会在退出播放模式和域重新加载时清空。默认关闭转录捕获。

| 参数                   | 类型                                 | 默认值     | 描述                          |
| -------------------- | ---------------------------------- | ------- | --------------------------- |
| `operation`          | `enum ConvaiRuntimeTraceOperation` | `读取`    | `Start`, `读取`, `清除`，或 `停止`. |
| `managerInstanceId`  | `long`                             | `0`     | 可选的活动场景管理器实例 ID。            |
| `角色实例 ID`            | `long`                             | `0`     | 可选的活动场景角色实例 ID 筛选器。         |
| `eventFilters`       | `string[]`                         | `[]`    | 可选的事件类型或类别筛选器。              |
| `limit`              | `int`                              | `100`   | 要返回的条目数，夹在 `1` 和 `256`.     |
| `captureTranscripts` | `bool`                             | `false` | 捕获转录事件和文本。默认关闭。             |

### 实体化

实体化工具设置了所有表现模块都会接入的组合根—— `EmbodimentContext` 和 `StandardRigBinding` ——然后交给下面按模块划分的工具。 `Convai.DiagnoseEmbodiment` 是任何角色首先要调用的工具：它会报告骨架、该角色拥有的每个模块、哪些模块实际上会起作用，并指出接下来要调用的按模块工具名称。

#### `Convai.ConfigureEmbodiment`

**区域：** 实体化 · **默认启用：** 是 · **修改：** 是

为 Convai 角色完成设置：现在就确定其骨架，而不是等到运行时；添加项目已安装的表现模块——注视、情绪、身体动画、肢体语言和对话流程中该项目具备的任意组合——并分配一个项目中已有的实体化预设。绝不创建或编辑资源，也不会单独调校某个模块；每个模块都有自己的配置工具可做这件事。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                | 类型         | 默认值    | 描述                                      |
| ----------------- | ---------- | ------ | --------------------------------------- |
| `角色实例 ID`         | `long`     | ——（必填） | 要设置的 Convai 角色。 `0` 使用活动场景中的唯一一个。       |
| `setUpRig`        | `bool`     | `true` | 添加角色骨架组件，并立即确定角色的骨骼和面部网格。               |
| `capabilities`    | `string[]` | `[]`   | 要添加哪些表现模块，按显示名称或模块 ID 指定。角色上已有的模块会保持不变。 |
| `presetAssetPath` | `string`   | `""`   | 要分配的现有实体化预设的项目路径。绝不创建新的。                |
| `dryRun`          | `bool`     | `true` | 在不触碰场景的情况下预览更改。                         |

#### `Convai.DiagnoseEmbodiment`

**区域：** 实体化 · **默认启用：** 是 · **修改：** 没有

端到端地检查一个 Convai 角色：是否已理解其骨架、拥有哪些表现模块、哪些模块实际上会起作用、哪些被阻止或不起作用以及原因、它们各自运行在哪些设置资源上、它的实体化预设，以及——在播放模式中——它当前正在做什么。

| 参数                    | 类型     | 默认值    | 描述                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `角色实例 ID`             | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中的唯一一个。 |
| `includeCapabilities` | `bool` | `true` | 包含按模块划分的明细。                       |
| `includeRuntimeState` | `bool` | `true` | 包含实时对话和情绪状态。仅播放模式。                |

#### `Convai.InspectEmbodimentPresets`

**区域：** 实体化 · **默认启用：** 是 · **修改：** 没有

列出项目中的实体化预设，以及每个预设是否有效，还包括预设可携带的每个表现模块及其创建设置资源的菜单路径。绝不创建或编辑资源。

| 参数            | 类型         | 默认值  | 描述                   |
| ------------- | ---------- | ---- | -------------------- |
| `folderPaths` | `string[]` | `[]` | 要搜索的项目文件夹。省略则搜索整个项目。 |

### 注视

#### `Convai.ConfigureGaze`

**区域：** 注视 · **默认启用：** 是 · **修改：** 是

新增 `ConvaiGazeController` 为一个角色配置注视方式，并调校它如何进行眼神接触——谁被视为玩家、投入程度有多强、身体如何转向，以及有哪些可选附加项。会为项目中已有的注视配置文件分配现有实例；绝不创建或编辑资源。省略的调校字段保持不变。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                          | 类型                        | 默认值       | 描述                                                        |
| --------------------------- | ------------------------- | --------- | --------------------------------------------------------- |
| `角色实例 ID`                   | `long`                    | ——（必填）    | 要配置的 Convai 角色。 `0` 使用活动场景中的唯一一个。                         |
| `eyeContactMode`            | `enum GazeEyeContactMode` | omit = 不变 | `自然`, `SpeakingFocus`, `ConversationLock`，或 `AlwaysLock`. |
| `focusFidelity`             | `enum GazeFocusFidelity`  | omit = 不变 | `社交` 或 `精确`.                                              |
| `playerAnchorInstanceId`    | `long`                    | omit = 不变 | 此角色应将其视为玩家的变换。                                            |
| `clearPlayerAnchorOverride` | `bool`                    | omit = 不变 | 清除覆盖项，让角色再次注视主摄像机。                                        |
| `playerAnchorAimMode`       | `enum GazeAnchorAimMode`  | omit = 不变 | `自动`, `ExactTransform`，或 `LocalOffset`.                   |
| `bodyTurnStyle`             | `enum GazeBodyTurnStyle`  | omit = 不变 | `SteppingTurn` 或 `SmoothRotation`.                        |
| `profileAssetPath`          | `string`                  | `""`      | 要分配的现有注视配置文件。绝不创建新的。                                      |
| `capabilities`              | `string[]`                | omit = 不变 | 此角色最终应拥有的完整可选注视附加项集合。                                     |
| `dryRun`                    | `bool`                    | `true`    | 在不触碰场景的情况下预览更改。                                           |

#### `Convai.DiagnoseGaze`

**区域：** 注视 · **默认启用：** 是 · **修改：** 没有

解释为什么角色是否在看玩家：解析了哪些头部和眼睛骨骼、骨架是否朝向正确、它将谁视为玩家以及由哪个设置决定、正在使用哪个注视配置文件、拥有哪些可选附加项，以及播放模式中的实时注视状态。

| 参数                    | 类型     | 默认值    | 描述                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `角色实例 ID`             | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中的唯一一个。 |
| `includeRuntimeState` | `bool` | `true` | 包含角色此刻正在看什么。仅播放模式。                |

#### `Convai.MarkGazeTarget`

**区域：** 注视 · **默认启用：** 是 · **修改：** 是

将场景对象标记为值得注视，因此 Convai 角色会瞥向它们——一幅画、一块屏幕、一个道具。将 `ConvaiGazeTarget` 添加到所命名的对象；绝不创建资源。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                      | 类型       | 默认值           | 描述                                       |
| ----------------------- | -------- | ------------- | ---------------------------------------- |
| `gameObjectInstanceIds` | `long[]` | ——（必填）        | 要标记为值得注视的 GameObject。                    |
| `priority`              | `int`    | omit = 默认 `5` | 对象的重要程度。玩家的优先级为 `10`；高于该值时，角色会注视这里而不是玩家。 |
| `baseRelevance`         | `float`  | omit = 不变     | 对象在近处有多有趣，范围从 `0` 到 `1`.                 |
| `maxDistance`           | `float`  | omit = 不变     | 超过多少米后角色不再注意该对象。                         |
| `fullRelevanceDistance` | `float`  | omit = 不变     | 在多少米内对象最有吸引力。                            |
| `remove`                | `bool`   | `false`       | 改为取消标记这些对象。                              |
| `dryRun`                | `bool`   | `true`        | 在不触碰场景的情况下预览更改。                          |

### 身体动画

#### `Convai.ConfigureBodyAnimation`

**区域：** 身体动画 · **默认启用：** 是 · **修改：** 是

新增 `ConvaiBodyAnimationController` 为一个角色配置身体动画——随附的动画内容、角色是否能行走，以及它如何移动。会分配现有内容资源；绝不创建、编辑或测量资源，也绝不触碰 Animator Controller。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                                   | 类型                            | 默认值       | 描述                                                  |
| ------------------------------------ | ----------------------------- | --------- | --------------------------------------------------- |
| `角色实例 ID`                            | `long`                        | ——（必填）    | 要配置的 Convai 角色。 `0` 使用活动场景中的唯一一个。                   |
| `includeMovement`                    | `bool`                        | `true`    | 添加 `ConvaiNavMeshLocomotion` 这样角色就可以行走、慢跑、转身和停下。    |
| `profileAssetPath`                   | `string`                      | `""`      | 现有的身体动画配置文件，它捆绑了一个 Animation Set 和一个 Config。绝不创建新的。 |
| `animationSetAssetPath`              | `string`                      | `""`      | 现有的 Animation Set，供未使用配置文件的角色使用。                    |
| `configAssetPath`                    | `string`                      | `""`      | 现有的身体动画 Config，供未使用配置文件的角色使用。                       |
| `speedProfile`                       | `enum LocomotionSpeedProfile` | omit = 不变 | 一次移动是走路还是慢跑。                                        |
| `accelerationMetersPerSecondSquared` | `float`                       | omit = 不变 | 角色达到目标速度的快慢。                                        |
| `dryRun`                             | `bool`                        | `true`    | 在不触碰场景的情况下预览更改。                                     |

#### `Convai.DiagnoseBodyAnimation`

**区域：** 身体动画 · **默认启用：** 是 · **修改：** 没有

解释角色身体动画实际在做什么：是否已设置好、骨架是否能驱动它、解析出了哪些动画内容、哪些行为可用、哪些因为角色没有对应片段而处于静默无效状态、骨架比例如何校准，以及播放模式中的实时状态。

| 参数                    | 类型     | 默认值    | 描述                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `角色实例 ID`             | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中的唯一一个。 |
| `includeRuntimeState` | `bool` | `true` | 包含角色此刻正在播放的动画。仅播放模式。              |

#### `Convai.InspectBodyAnimationContent`

**区域：** 身体动画 · **默认启用：** 是 · **修改：** 没有

列出角色的 Animation Set 实际能执行什么——静止、说话、聆听和思考的动作池，以及每个动作和手势及其名称 `PlayAction` 接受的内容、行走覆盖范围和指向方向。在编写使用 `PlayAction`.

| 参数                      | 类型       | 默认值  | 描述                                       |
| ----------------------- | -------- | ---- | ---------------------------------------- |
| `角色实例 ID`               | `long`   | `0`  | 的代码之前先调用这个。 `animationSetAssetPath` 时给出。 |
| `animationSetAssetPath` | `string` | `""` | 直接检查一个 Animation Set，不涉及任何角色。            |

#### `Convai.TuneBodyAnimationPersonality`

**区域：** 身体动画 · **默认启用：** 是 · **修改：** 是

调节角色的表现力和沉稳程度，以及独处时是否会保持忙碌。身体动画配置可被多个角色共享，因此此工具会在更改任何内容之前，为所命名的角色创建一份私有副本——就像 **为此角色使用其专属设置** 命令一样——而不是编辑其他角色或 SDK 附带默认值仍在依赖的配置。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                   | 类型                            | 默认值       | 描述                                                   |
| -------------------- | ----------------------------- | --------- | ---------------------------------------------------- |
| `角色实例 ID`            | `long`                        | ——（必填）    | 要调节的 Convai 角色。 `0` 使用活动场景中的唯一一个。                    |
| `archetype`          | `enum BodyAnimationArchetype` | omit = 不变 | 一个命名的人格预设： `沉稳`, `温暖`, `充满活力`，或 `内敛`.                |
| `howExpressive`      | `float`                       | omit = 不变 | 说话手势的幅度和频率有多大，范围从 `0` 到 `2`.                         |
| `howCalm`            | `float`                       | omit = 不变 | 角色保持姿势的时长以及恢复的轻柔程度，范围从 `0` 到 `2`.                    |
| `keepsBusyWhenAlone` | `bool`                        | omit = 不变 | 角色在沉默时是否会自行进行一些小动作。                                  |
| `makeConfigUnique`   | `bool`                        | `false`   | 当配置被多个角色共享或随 SDK 一起提供时，同意复制该配置。应用前必需；预览会始终报告是否需要此操作。 |
| `dryRun`             | `bool`                        | `true`    | 预览更改，以及是否需要副本，而不写入任何内容。                              |

{% hint style="info" %}
`Convai.TuneBodyAnimationPersonality` 和 `Convai.TuneEmotionPersonality` 是此目录中唯一会写入磁盘的两个工具。二者都会为某个角色复制共享的或 SDK 附带的设置资源，而不是就地编辑；并且二者都拒绝在没有明确 `makeConfigUnique`/`makePersonalityUnique` 同意的情况下应用，一旦预览显示需要副本。
{% endhint %}

### 肢体语言

#### `Convai.ConfigureBodyLanguage`

**区域：** 肢体语言 · **默认启用：** 是 · **修改：** 是

新增 `ConvaiBodyLanguageController` 为角色添加肢体语言，让它在说话时呼吸、重心移动、摇摆和做手势，并通过分配项目中已有的 Body Language Profile 来赋予它个性。绝不创建或编辑资源，并且会拒绝骨架无法驱动该模块的角色，而不是添加无效内容。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                         | 类型       | 默认值     | 描述                                             |
| -------------------------- | -------- | ------- | ---------------------------------------------- |
| `角色实例 ID`                  | `long`   | ——（必填）  | 要配置的 Convai 角色。 `0` 使用活动场景中的唯一一个。              |
| `personalityAssetPath`     | `string` | `""`    | 要分配的现有 Body Language Profile。绝不创建新的。省略则保留个性不变。 |
| `assignDefaultPersonality` | `bool`   | `false` | 为没有个性的角色提供随附的默认个性，或使用项目中的第一个个性。保留已有个性不变。       |
| `dryRun`                   | `bool`   | `true`  | 在不触碰场景的情况下预览更改。                                |

#### `Convai.DiagnoseBodyLanguage`

**区域：** 肢体语言 · **默认启用：** 是 · **修改：** 没有

解释角色身体正在做什么以及原因：其骨架提供了什么、哪种个性在调校它以及该个性关闭了哪些行为、还有哪些其他 Convai 模块共享其身体以及各自改变了什么，以及——在播放模式中——其实时姿势、呼吸、重心移动和手势抑制情况。

| 参数                    | 类型     | 默认值    | 描述                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `角色实例 ID`             | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中的唯一一个。 |
| `includeRuntimeState` | `bool` | `true` | 包含实时姿势和手势状态。仅播放模式。                |

#### `Convai.InspectBodyLanguagePersonalities`

**区域：** 肢体语言 · **默认启用：** 是 · **修改：** 没有

列出项目中的 Body Language Profiles——每个配置的表现力、它关闭了哪些行为，以及开放场景中哪些角色已经在使用它。

| 参数            | 类型         | 默认值  | 描述                   |
| ------------- | ---------- | ---- | -------------------- |
| `folderPaths` | `string[]` | `[]` | 要搜索的项目文件夹。省略则搜索整个项目。 |

### 情绪

#### `Convai.ConfigureEmotion`

**区域：** 情绪 · **默认启用：** 是 · **修改：** 是

新增 `ConvaiEmotionController` 为角色设置情绪，让它的面部对所说内容作出反应，赋予它项目中已有的个性，并设置它如何检测情绪以及停留在什么基调。只会写入角色自身的字段——绝不会创建或编辑个性资源，因此也绝不会意外重塑其他角色。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                     | 类型       | 默认值       | 描述                                       |
| ---------------------- | -------- | --------- | ---------------------------------------- |
| `角色实例 ID`              | `long`   | ——（必填）    | 要配置的 Convai 角色。 `0` 使用活动场景中的唯一一个。        |
| `personalityAssetPath` | `string` | `""`      | 现有 `ConvaiEmotionProfile` 要分配的个性。绝不创建新的。 |
| `emotionDetection`     | `string` | `""` （不变） | 角色自身的情绪检测设置。                             |
| `restingMood`          | `string` | `""` （不变） | 此角色自身的静息情绪覆盖项。                           |
| `restingMoodStrength`  | `float`  | omit = 不变 | 静息情绪覆盖项的强度。                              |
| `dryRun`               | `bool`   | `true`    | 在不触碰场景的情况下预览更改。                          |

#### `Convai.DiagnoseEmotion`

**区域：** 情绪 · **默认启用：** 是 · **修改：** 没有

解释 Convai 角色的面部实际会做什么以及原因：它是否能显示情绪、如何检测情绪、由哪种个性调校、静止时处于什么状态以及由哪个设置决定，以及哪些行为被其他设置关闭或静默限制。

| 参数                    | 类型     | 默认值    | 描述                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `角色实例 ID`             | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中的唯一一个。 |
| `includeRuntimeState` | `bool` | `true` | 包含实时主导情绪和心情。仅播放模式。                |

#### `Convai.InspectEmotionPersonalities`

**区域：** 情绪 · **默认启用：** 是 · **修改：** 没有

列出项目中的 Convai 情绪个性——每个个性对应哪种角色类型、它处于什么静息状态、开启了哪些行为、是否随 SDK 一起提供，以及哪些角色已经在使用它。

| 参数            | 类型         | 默认值  | 描述                   |
| ------------- | ---------- | ---- | -------------------- |
| `folderPaths` | `string[]` | `[]` | 要搜索的项目文件夹。省略则搜索整个项目。 |

#### `Convai.TuneEmotionPersonality`

**区域：** 情绪 · **默认启用：** 是 · **修改：** 是

更改角色的情绪感受——其角色类型、静息状态、表现情绪的强弱与速度，以及情绪开关。这些内容保存在其他角色也可能共享的个性资源上，因此此工具会先预览，并在明确同意后为该角色生成自己的副本并仅写入该副本。它绝不会就地编辑共享的或随 SDK 提供的个性。仅在编辑模式下可用——返回一个 `PLAY_MODE_ACTIVE` 如果在播放模式下调用，则返回失败代码。

| 参数                            | 类型       | 默认值       | 描述                                    |
| ----------------------------- | -------- | --------- | ------------------------------------- |
| `角色实例 ID`                     | `long`   | ——（必填）    | 要调节的 Convai 角色。 `0` 使用活动场景中的唯一一个。     |
| `characterType`               | `string` | `""` （不变） | 适用于该角色类型的命名个性预设。                      |
| `restingMood`                 | `string` | `""` （不变） | 个性自身的静息情绪。                            |
| `howStronglyItShows`          | `float`  | omit = 不变 | 情绪在脸上表现得有多强烈。                         |
| `howQuicklyItReacts`          | `float`  | omit = 不变 | 面部对情绪变化反应的速度。                         |
| `neverSitsPerfectlyStill`     | `bool`   | omit = 不变 | 是否播放对话节拍的微反应。                         |
| `picksUpOtherCharactersMoods` | `bool`   | omit = 不变 | 此角色的心情是否会受其他角色心情影响。在只有一个角色的场景中没有可见效果。 |
| `makePersonalityUnique`       | `bool`   | `false`   | 当个性被多个角色共享或随 SDK 一起提供时，同意复制该个性。应用前必需。 |
| `dryRun`                      | `bool`   | `true`    | 预览更改，以及是否需要副本，而不写入任何内容。               |

### 下一步

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

{% content-ref url="/pages/ec47f18f1ec454c3afecbec3a73f8ab46981f55c" %}
[受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md)
{% endcontent-ref %}

{% content-ref url="/pages/19bff3d08fa0ba480410597a8a790b68a4f73b14" %}
[排查 AI 编码助手设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/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 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-unity-sdk/ai-coding-assistant/mcp-tools-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.