> 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 工具参考

Convai 向编码代理提供的所有 MCP 工具参考，包括默认启用状态和场景修改行为。

Unity 官方 MCP 服务器在 `Convai.*` 命名空间下提供 44 个 Convai 专用工具，工具契约版本为 7，因此连接的编程智能体可以检查、配置或诊断 Convai 组件，而不必由你在 Unity Editor 中手动连接它们。Unity AI Assistant 使用以点分隔的名称调用工具（例如 `Convai.GetGuidance`）；外部 MCP 客户端收到的同一工具使用下划线规范化后的名称（`Convai_GetGuidance`）。44 个工具中有 7 个用于对话目标选择和多角色房间：确定玩家正在与多个角色中的哪一个交谈，以及在已连接的房间中添加、移除角色或等待角色就绪。本页使用以点分隔的名称，介绍每个工具的用途、参数、默认启用状态，以及对场景或项目的修改行为。

### 全部 44 个工具

| 工具                                        | 领域      | 默认启用 | 会修改                                                    |
| ----------------------------------------- | ------- | ---- | ------------------------------------------------------ |
| `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.ConfigureConversationTargeting`   | 对话目标选择  | 是    | 是 — 仅限编辑模式； `dryRun` 默认值为 `true`                       |
| `Convai.SimulateConversationTargeting`    | 对话目标选择  | 是    | 否                                                      |
| `Convai.SetupMultiCharacterRoster`        | 对话目标选择  | 是    | 是 — 仅限编辑模式； `dryRun` 默认值为 `true`                       |
| `Convai.SetConversationTarget`            | 多角色     | 是    | 仅限运行模式；必须明确设置 `dryRun=false`；绝不会更改运行模式                 |
| `Convai.UpdateCharacterRoster`            | 多角色     | 是    | 仅限运行模式；必须明确设置 `dryRun=false`；绝不会更改运行模式                 |
| `Convai.WaitForCharacterReady`            | 多角色     | 是    | 否 — 仅等待；绝不会更改运行模式                                      |
| `Convai.WaitForMultiCharacterState`       | 多角色     | 是    | 否 — 仅等待；绝不会更改运行模式                                      |
| `Convai.ConfigureActions`                 | 角色动作    | 是    | 是 — 仅限编辑模式                                             |
| `Convai.DiagnoseActions`                  | 角色动作    | 是    | 否                                                      |
| `Convai.SimulateAction`                   | 角色动作    | 是    | 仅限运行模式，通过调度器执行                                         |
| `Convai.ConfigureLipSync`                 | 唇形同步    | 是    | 是 — 仅限编辑模式； `dryRun` 默认值为 `true`                       |
| `Convai.DiagnoseLipSync`                  | 唇形同步    | 是    | 否                                                      |
| `Convai.ConfigureTranscripts`             | 转录文本    | 是    | 是 — 仅限编辑模式； `dryRun` 默认值为 `true`                       |
| `Convai.DiagnoseTranscripts`              | 转录文本    | 是    | 否                                                      |
| `Convai.ConfigureNarrative`               | 叙事      | 是    | 是 — 仅限编辑模式； `dryRun` 默认值为 `true`                       |
| `Convai.DiagnoseNarrative`                | 叙事      | 是    | 否                                                      |
| `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 工具，以及文档路径。

| 参数      | 类型                         | 默认值        | 说明         |
| ------- | -------------------------- | ---------- | ---------- |
| `topic` | `enum ConvaiGuidanceTopic` | `Overview` | 要加载的工作流主题。 |

`ConvaiGuidanceTopic` 各个值及其返回内容：

| 主题               | 返回的摘要                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `Overview` （默认）  | 仅将 Convai 工具用于需要了解 SDK 的操作；对于通用项目更改，请组合使用 Unity 官方 MCP 工具。                                          |
| `Setup`          | 主动完成可运行的 Convai 场景设置；明确的设置请求即授权采用安全、可撤销的默认配置。                                                       |
| `Actions`        | 明确声明可执行操作，并绑定本地执行器；绝不要根据场景元数据推断可执行操作。                                                               |
| `DynamicContext` | 通过角色的动态上下文门面发送状态、事件和关注对象的变更。                                                                        |
| `Vision`         | 启用视频模式前，请在房间层级中配置视觉发布器和一个帧源。                                                                        |
| `Narrative`      | 使用 Narrative 模块处理章节状态以及命名或内联触发器工作流。                                                                 |
| `Embodiment`     | 通过各具身模块自带的 Configure/Diagnose 配对项分别进行配置，并从 `Convai.DiagnoseEmbodiment`开始；缺少关联模块时，每项功能都会优雅降级。        |
| `Gaze`           | 添加 Gaze 组件，查看眼神交流效果；Player Anchor 和 watches 模块说明了角色会将谁视为玩家。                                         |
| `BodyAnimation`  | 身体动画受内容限制——在角色的动画集中包含相应片段之前，某些行为会保持无效。这是内容缺失，而非设置故障。                                                |
| `BodyLanguage`   | Body Language 在 Body Animation 和 Gaze 的基础上叠加环境性非语言动作，并会在任一模块存在时自动降低自身表现。                            |
| `Emotion`        | 让角色拥有一张会对话语做出反应的面孔，并调整其气质，而无需重新设计所有共享其个性的其他角色。                                                      |
| `MultiCharacter` | Convai 房间会容纳已加载场景中的所有活动 `ConvaiCharacter` ；无需切换到多角色模式。只需使用 `Convai.ConfigureConversationTargeting`. |
| `Events`         | 对于类型化代码，优先使用 `ConvaiManager.Events` ；对于由 Inspector 驱动的 `UnityEvent`，则使用中继组件。                        |
| `Runtime`        | 使用 `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 创作操作前后调用。返回 `errors`, `warnings`以及 `nextSteps`并纳入活动场景中每个 `ConvaiCharacter` 的所有 embodiment 模块各自的检查结果。

| 参数      | 类型                           | 默认值   | 说明                               |
| ------- | ---------------------------- | ----- | -------------------------------- |
| `scope` | `enum ConvaiValidationScope` | `All` | 验证范围： `All`, `Project`或 `Scene`. |

### 场景和对话设置

#### `Convai.BootstrapScene`

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

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

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

{% hint style="warning" %}
`Convai.BootstrapScene` 是 44 个工具中唯一默认禁用的工具。其  `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` | `enum ConvaiToolConfigurationMode` | `Inline`    | `Inline` 或 `ExistingProfile`.                                        |
| `profileAssetPath`  | `string`                           | `""`        | 现有 `ConvaiRoomManagerProfile` 资源路径。在 `ExistingProfile` 模式下必填。        |
| `connectionType`    | `enum ConvaiConnectionType`        | `Audio`     | 内联连接类型。                                                              |
| `inputMode`         | `enum ConversationInputMode`       | `HandsFree` | 内联对话输入模式。                                                            |
| `connectOnStart`    | `bool`                             | `true`      | 场景启动时自动连接。                                                           |
| `serverEndpoint`    | `enum ConvaiServerEndpoint`        | `Connect`   | 核心服务端点。                                                              |
| `visionMode`        | `enum ConvaiVisionContextMode`     | `Auto`      | 动态视觉策略。                                                              |
| `pushToTalkKey`     | `string`                           | `"T"`       | Unity `KeyCode` 名称，用作一键通话键。                                          |
| `dryRun`            | `bool`                             | `true`      | 预览更改，不修改场景。                                                          |

#### `Convai.ConfigurePlayer`

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

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

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

#### `Convai.ConfigureCharacter`

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

预览，或添加并配置 `ConvaiCharacter` 并搭配推荐的音频输出—— `AudioSource` 和 `ConvaiAudioOutput` ——在明确指定的目标 `GameObject`上。缺少 Character ID 时仍会明确阻止就绪：工具会返回 `complete=false` 和 `requiredInputs=["characterId"]` ，而不会猜测 ID。仅在编辑模式下可用——如果在播放模式下调用，将返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                  | 类型                                 | 默认值      | 说明                                                            |
| ------------------- | ---------------------------------- | -------- | ------------------------------------------------------------- |
| `targetInstanceId`  | `long`                             | —（必填）    | 目标角色 GameObject 实例 ID。                                        |
| `managerInstanceId` | `long`                             | `0`      | 可选的管理器 GameObject 实例 ID。为零时，会自动解析目标场景中的一个管理器。                 |
| `configurationMode` | `enum ConvaiToolConfigurationMode` | `Inline` | `Inline` 或 `ExistingProfile`.                                 |
| `profileAssetPath`  | `string`                           | `""`     | 现有 `ConvaiCharacterProfile` 资源路径。在 `ExistingProfile` 模式下为必填项。 |
| `characterId`       | `string`                           | `""`     | Convai 控制面板中的 Character ID。创建尚未完成的占位对象时可以省略。                  |
| `characterName`     | `string`                           | `""`     | 角色显示名称。默认为目标 GameObject 的名称。                                  |
| `addAudioOutput`    | `bool`                             | `true`   | 确保存在 `AudioSource` 和 `ConvaiAudioOutput` 配套组件。                |
| `dryRun`            | `bool`                             | `true`   | 预览更改，不修改场景。                                                   |

#### `Convai.SetupConversationScene`

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

在当前场景中预览或执行端到端音频对话设置，并使用安全的占位对象和推荐的默认值。选择顺序为：明确指定的实例 ID、唯一且明确的现有组件，然后是安全占位对象——如果不存在，则创建独立的 `Convai Player` 和一个可见的 Capsule `Convai Character` 。不会保存场景、进入播放模式或设置凭据。仅在编辑模式下可用——如果在播放模式下调用，将返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                          | 类型                           | 默认值                  | 说明                                          |
| --------------------------- | ---------------------------- | -------------------- | ------------------------------------------- |
| `managerInstanceId`         | `long`                       | `0`                  | 可选的管理器目标实例 ID。                              |
| `playerInstanceId`          | `long`                       | `0`                  | 可选的玩家目标实例 ID。                               |
| `characterInstanceId`       | `long`                       | `0`                  | 可选的角色目标实例 ID。                               |
| `roomProfileAssetPath`      | `string`                     | `""`                 | 可选的现有 `ConvaiRoomManagerProfile` 路径。        |
| `characterProfileAssetPath` | `string`                     | `""`                 | 可选的现有 `ConvaiCharacterProfile` 路径。          |
| `characterId`               | `string`                     | `""`                 | Convai 控制面板中的 Character ID。可以在所有独立设置完成之前省略。 |
| `characterName`             | `string`                     | `"Convai Character"` | 角色显示名称。                                     |
| `playerName`                | `string`                     | `"Player"`           | 玩家显示名称。                                     |
| `playerId`                  | `string`                     | `""`                 | 可选的本地转录归属 ID。                               |
| `inputMode`                 | `enum ConversationInputMode` | `HandsFree`          | 建议的房间输入模式。                                  |
| `connectOnStart`            | `bool`                       | `true`               | 场景启动时自动连接。                                  |
| `createPlaceholders`        | `bool`                       | `true`               | 如果不存在，则创建独立的玩家和 Capsule 角色占位对象。             |
| `dryRun`                    | `bool`                       | `true`               | 预览更改，不修改场景。                                 |

#### `Convai.DiagnoseConversation`

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

诊断当前场景中的 Convai 对话就绪状态和运行时状态，并提供按优先级排序的证据及建议修复方法。在编辑模式和播放模式下均可使用。不会修改项目，也不会返回 API 密钥。

| 参数                                  | 类型     | 默认值     | 说明                                   |
| ----------------------------------- | ------ | ------- | ------------------------------------ |
| `characterInstanceId`               | `long` | `0`     | 可选的指定角色 GameObject 实例 ID。            |
| `includeInactive`                   | `bool` | `true`  | 包含非活动场景对象。                           |
| `includeRecentMultiCharacterEvents` | `bool` | `false` | 包含活动跟踪中的最多 20 条经过清理的近期目标、角色阵容和可用性事件。 |

返回 `readyToRun`、配置和运行时快照，以及一个 `issues` 数组，其中包含稳定的代码、证据、 `autoFixable`和 `suggestedTool`/`suggestedArguments` ，用于描述每个问题。

configuration `快照包含一个` conversationTargeting `区块，用于报告目标选择规则及其值——` mode `、`, `within` （范围，单位为米）、 `lookAngle`, `、`switchMargin `和` switchDelaySeconds `——以及`isShippedDefault `；只有当所有值仍与随附默认值一致时，它才为` true `。` runtime `快照会报告当前正在与之对话的角色的` addressedCharacter `和` addressedCharacterInstanceId `conversationAvailability` addressedCharacter `playerCanTalk` 表示可用性判定结果，以及一个 `multiCharacter` 块。没有处于活动状态的多角色房间时， `multiCharacter` 仅报告 `isMultiCharacterRoom: false`；有活动的多角色房间时，还会报告房间会话 ID、路由和成员列表的 epoch、当前对话目标、目标选择模式和判定结果，以及包含每个角色成员状态的完整成员列表。

### 对话目标选择

Convai 房间包含已加载场景中所有处于活动状态的 `ConvaiCharacter` ，SDK 会确定玩家正在对哪一个角色说话。这些工具用于配置该规则，并在房间连接前预览；下方的 [多角色](#multi-character) 工具则用于操作已经连接的房间。

#### `Convai.ConfigureConversationTargeting`

**领域：** 对话目标选择 · **默认启用：** 是 · **会修改内容：** 是

预览或配置哪些角色将加入下一个 Convai 房间，以及 SDK 如何确定玩家正在与其中的哪一个角色对话。每个字段都是可选的；省略字段会使该设置保持项目中原有的值。整个请求会在写入任何内容之前完成规划。此操作支持撤销，不会保存场景，也不会更改凭据。仅在编辑模式下可用——如果在播放模式下调用，将返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                             | 类型                               | 默认值       | 说明                                                                                                                                                        |
| ------------------------------ | -------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `managerInstanceId`            | `long`                           | `0`       | 要配置的 `ConvaiManager` 。值为零时，使用已加载场景中唯一的实例。                                                                                                                 |
| `targetingMode`                | `enum ConversationTargetingMode` | 省略 = 保持不变 | 选择对话对象的方式： `LookAt`, `Proximity`或 `Manual`. `LookAt` 选择最靠近视野中心的角色； `Proximity` 选择距离最近的角色，不受玩家视线方向影响； `Manual` 仅当游戏调用以下方法时才切换对话对象： `ConvaiManager.TalkTo`. |
| `maxDistance`                  | `float`                          | 省略 = 保持不变 | 范围：角色可成为对话对象的最大距离，以米为单位。出厂默认值为 `30`.                                                                                                                      |
| `maxAngle`                     | `float`                          | 省略 = 保持不变 | 视线角度：角色与视野中心之间的最大夹角，以度为单位。仅适用于 `LookAt` 。出厂默认值为 `35` （70 度的锥形视野）。                                                                                         |
| `switchMargin`                 | `float`                          | 省略 = 保持不变 | 切换余量：切换对话对象前，另一个角色的视线角度必须优于当前角色的最小差值，以度为单位。仅适用于 `LookAt` 。出厂默认值为 `10`.                                                                                    |
| `switchDelaySeconds`           | `float`                          | 省略 = 保持不变 | 切换延迟：切换对话对象前，角色必须持续保持为最佳选择的时间。出厂默认值为 `0.2`.                                                                                                               |
| `viewCameraInstanceId`         | `long`                           | 省略 = 保持不变 | 玩家摄像机： `Camera` 被视为玩家视角的 GameObject 实例 ID。                                                                                                                |
| `clearViewCamera`              | `bool`                           | 省略 = 保持不变 | 清除玩家摄像机设置，以便再次使用主摄像机。                                                                                                                                     |
| `initialCharacterInstanceId`   | `long`                           | 省略 = 保持不变 | 初始角色：房间打开时显示的角色，无论玩家正在看向何处。                                                                                                                               |
| `clearInitialCharacter`        | `bool`                           | 省略 = 保持不变 | 清除初始角色设置，以便房间打开时显示玩家正在看向的角色。                                                                                                                              |
| `includedCharacterInstanceIds` | `long[]`                         | 省略 = 保持不变 | 加入房间的角色：要发送的确切角色集合。未列出的角色将被排除；之后添加到场景中的角色也不会加入，除非将其添加到此集合中。更改前，请从 `Convai.DiagnoseConversation` 读取当前集合。                                                   |
| `includeAllCharacters`         | `bool`                           | 省略 = 保持不变 | 将所有活动角色发送到下一个房间，这是随附配置中的默认设置。                                                                                                                             |
| `dryRun`                       | `bool`                           | `true`    | 预览更改，不修改场景。                                                                                                                                               |

#### `Convai.SimulateConversationTargeting`

**区域：** 对话目标 · **默认启用：** 是 · **是否修改数据：** 否

说明由已配置的 `LookAt` 或 `Proximity` 目标规则生成的几何方案，以及任何实时房间顺序恢复回退方案；但不表示 Switch Delay 等时间切换门控已确认该方案。无论在编辑模式还是播放模式下均为只读；绝不会联系 Convai。

| 参数                     | 类型     | 默认值    | 说明                                                     |
| ---------------------- | ------ | ------ | ------------------------------------------------------ |
| `managerInstanceId`    | `long` | `0`    | 要模拟的 `ConvaiManager` 实例。零表示使用已加载场景中唯一的实例。              |
| `viewCameraInstanceId` | `long` | `0`    | 摄像机 GameObject 实例 ID。零表示依次使用管理器中配置的摄像机、主摄像机，然后是其拥有的玩家。 |
| `includeInactive`      | `bool` | `true` | 在报告中包含非活动角色；这些角色仍不符合参与条件。                              |

返回目标模式、当前目标和拟议目标、是否应用了恢复回退方案、每个候选角色的距离、角度和符合条件的依据，以及为拟议方案评分时采用的设置。

#### `Convai.SetupMultiCharacterRoster`

**领域：** 对话目标选择 · **默认启用：** 是 · **会修改内容：** 是

预览或配置下一个房间中至少两个角色的确切名单，并可选择哪位角色先发言。应用前会验证每个角色是否拥有自己的 Character ID，并通过 `Convai.ConfigureConversationTargeting`使用 Unity 的撤销系统应用设置。仅在编辑模式下可用——若在播放模式下调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                           | 类型       | 默认值    | 说明                                                            |
| ---------------------------- | -------- | ------ | ------------------------------------------------------------- |
| `characterInstanceIds`       | `long[]` | —（必填）  | 下一个房间中至少两个角色 GameObject 实例 ID 的确切集合。                          |
| `managerInstanceId`          | `long`   | `0`    | 要配置的 `ConvaiManager` 。值为零时，使用已加载场景中唯一的实例。                     |
| `initialCharacterInstanceId` | `long`   | `0`    | 可选的名单成员，由其首先发言。零表示保持已配置的值不变。该角色也必须包含在 `characterInstanceIds`. |
| `dryRun`                     | `bool`   | `true` | 预览更改，不修改场景。                                                   |

### 多角色

这些工具用于操作已连接的多角色房间。此处的所有修改工具都要求处于播放模式，并且必须显式设置 `dryRun=false`；它们都不会改变播放模式本身。

#### `Convai.SetConversationTarget`

**区域：** 多角色 · **默认启用：** 是 · **是否修改数据：** 仅限播放模式；必须显式设置 `dryRun=false`

预览或更改玩家在活动多角色房间中正在对话的角色。

| 参数                    | 类型      | 默认值    | 说明                                        |
| --------------------- | ------- | ------ | ----------------------------------------- |
| `characterInstanceId` | `long`  | —（必填）  | 要对话的角色 GameObject 实例 ID。                  |
| `managerInstanceId`   | `long`  | `0`    | 要使用的 `ConvaiManager` 。值为零时，使用已加载场景中唯一的实例。 |
| `dryRun`              | `bool`  | `true` | 预览更改，不联系活动房间。                             |
| `timeoutSeconds`      | `float` | `10`   | 等待权威响应的最长时间（秒），限制在 `0.1` 和 `60`.          |

如果在玩家仍在说话时请求更改，工具会报告 `executed=false` 和 `queued=true` ——请求已在本地排队，在玩家当前的话语结束之前不会发送到房间。话语结束后，使用 `Convai.WaitForMultiCharacterState` 查看最终确定的目标。

#### `Convai.UpdateCharacterRoster`

**区域：** 多角色 · **默认启用：** 是 · **是否修改数据：** 仅限播放模式；必须显式设置 `dryRun=false`

预览或在活动多角色房间中添加或移除一个角色，并返回权威角色名单及路由周期编号。

| 参数                                     | 类型                                    | 默认值    | 说明                                                    |
| -------------------------------------- | ------------------------------------- | ------ | ----------------------------------------------------- |
| `operation`                            | `enum ConvaiCharacterRosterOperation` | `Add`  | `Add` 或 `Remove`.                                     |
| `characterInstanceId`                  | `long`                                | —（必填）  | 要添加或移除的角色 GameObject 实例 ID。                           |
| `roomManagerInstanceId`                | `long`                                | `0`    | 要使用的 `ConvaiRoomManager` 。值为零时，使用已加载场景中唯一的实例。         |
| `replacementTargetCharacterInstanceId` | `long`                                | `0`    | 可选的角色 GameObject 实例 ID，指定移除当前目标后要对话的角色。仅适用于 `Remove`. |
| `dryRun`                               | `bool`                                | `true` | 预览更改，不联系活动房间。                                         |
| `timeoutSeconds`                       | `float`                               | `15`   | 等待权威响应的最长时间（秒），限制在 `0.1` 和 `15`.                      |

#### `Convai.WaitForCharacterReady`

**领域：** 多角色 · **默认启用：** 是 · **修改状态：** 否——仅等待；绝不更改 Play 模式

等待活动多角色房间中已有的一个角色进入就绪状态。等待过程不会取消角色启动。

| 参数                      | 类型      | 默认值   | 说明                                            |
| ----------------------- | ------- | ----- | --------------------------------------------- |
| `characterInstanceId`   | `long`  | —（必填） | 角色 GameObject 实例 ID，该角色当前在房间中的成员状态必须变为就绪。     |
| `roomManagerInstanceId` | `long`  | `0`   | 要使用的 `ConvaiRoomManager` 。值为零时，使用已加载场景中唯一的实例。 |
| `timeoutSeconds`        | `float` | `30`  | 最长等待时间（秒），限制在 `0.1` 和 `60`.                   |

需要 Play 模式，否则返回 `PLAY_MODE_REQUIRED` 失败代码。如果成员已启动失败，工具会立即返回其失败代码，而不会等待。

#### `Convai.WaitForMultiCharacterState`

**领域：** 多角色 · **默认启用：** 是 · **修改状态：** 否——仅等待；绝不更改 Play 模式

等待活动多角色房间满足权威目标、名单周期编号、路由周期编号、名单大小、就绪状态或对话可用性条件。如果未设置任何条件，则返回当前快照而不等待。此操作为只读，且需要 Play 模式。

| 参数                                  | 类型      | 默认值     | 说明                                        |
| ----------------------------------- | ------- | ------- | ----------------------------------------- |
| `managerInstanceId`                 | `long`  | `0`     | 要使用的 `ConvaiManager` 。值为零时，使用已加载场景中唯一的实例。 |
| `expectedActiveCharacterInstanceId` | `long`  | `0`     | 可选的角色 GameObject 实例 ID，该角色必须成为权威目标。       |
| `expectedRosterSize`                | `int`   | `-1`    | 预期的成员名单大小。负值表示忽略此条件。                      |
| `minimumRosterEpoch`                | `int`   | `-1`    | 权威成员名单纪元的最小值。负值表示忽略此条件。                   |
| `minimumRouteEpoch`                 | `int`   | `-1`    | 权威路由纪元的最小值。负值表示忽略此条件。                     |
| `requireAllCharactersReady`         | `bool`  | `false` | 等待当前成员名单中的所有角色都变为 Ready。                  |
| `requireConversationAvailable`      | `bool`  | `false` | 等待目标角色能够接受玩家输入。                           |
| `timeoutSeconds`                    | `float` | `30`    | 最长等待时间（秒），限制在 `0.1` 和 `60`.               |

### 角色动作

#### `Convai.ConfigureActions`

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

预览或安全地更新 Convai 角色上的类型化动作定义，以及明确指定的对象或角色目标。使用撤销操作，且不会保存。没有绑定执行器的定义会收到一个未连接的 `UnityEvent` 占位符，在完成连接前始终处于未完成状态。仅在编辑模式下可用——如果在播放模式下调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                       | 类型       | 默认值    | 说明                                                                                                                                                                           |
| ------------------------ | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characterInstanceId`    | `long`   | —（必填）  | 角色 GameObject 或组件实例 ID。                                                                                                                                                      |
| `definitions`            | `array`  | `[]`   | 要按名称更新的类型化动作定义。完整字段列表请参阅 [角色动作脚本编写参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 。 |
| `objects`                | `array`  | `[]`   | 要按名称更新的明确指定的可执行操作的 GameObject。                                                                                                                                               |
| `characters`             | `array`  | `[]`   | 要按名称更新的明确指定的可执行操作角色。                                                                                                                                                         |
| `initialAttentionObject` | `string` | `""`   | 用作初始关注对象的可选已创作对象名称。                                                                                                                                                          |
| `dryRun`                 | `bool`   | `true` | 预览更改，不修改场景。                                                                                                                                                                  |

#### `Convai.DiagnoseActions`

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

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

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

#### `Convai.SimulateAction`

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

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

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

在编辑模式下，工具会返回 `executed=false` 和 `requiresPlayMode=true` （在验证有效负载后）。在播放模式下，工具会将命令加入角色的调度器队列，并等待 `ConvaiActionStepReport`，如果步骤未能在 `SIMULATION_TIMEOUT` 内完成，则返回 `timeoutSeconds`.

### 唇形同步

#### `Convai.ConfigureLipSync`

**区域：** 唇形同步 · **默认启用：** 是 · **是否修改：** 是

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

| 参数                    | 类型                        | 默认值        | 说明                                                                       |
| --------------------- | ------------------------- | ---------- | ------------------------------------------------------------------------ |
| `characterInstanceId` | `long`                    | —（必填）      | 角色 GameObject 实例 ID。                                                     |
| `meshInstanceIds`     | `long[]`                  | `[]`       | 目标网格实例 ID。留空则解析角色下的所有 `SkinnedMeshRenderer` 。                            |
| `profile`             | `string`                  | `"Auto"`   | `Auto`, `arkit`, `cc4_extended`或 `metahuman`. `Auto` 要求目标网格中的混合形状名称唯一匹配。 |
| `mappingAssetPath`    | `string`                  | `""`       | 现有 `ConvaiLipSyncMapAsset` 路径。                                           |
| `latencyMode`         | `enum LipSyncLatencyMode` | `Balanced` | `Balanced`, `UltraLowLatency`, `NetworkSafe`，或 `Custom`.                 |
| `dryRun`              | `bool`                    | `true`     | 预览更改，不修改场景。                                                              |

请参阅 [添加口型同步](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/add-lip-sync.md) ，了解此工具自动化的 Inspector 工作流。

#### `Convai.DiagnoseLipSync`

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

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

| 参数                      | 类型     | 默认值    | 说明                                                                     |
| ----------------------- | ------ | ------ | ---------------------------------------------------------------------- |
| `characterInstanceId`   | `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。                      |
| `mode`              | `enum ConvaiTranscriptToolMode` | `EventRelay` | `EventRelay`, `ChatUI`，或 `WorldSpaceChatUI`. |
| `finalOnly`         | `bool`                          | `false`      | 仅转发最终更新。                                     |
| `ignoreInterim`     | `bool`                          | `true`       | 忽略中间更新。                                      |
| `characterIdFilter` | `string`                        | `""`         | 可选的角色 ID 筛选条件。                               |
| `dryRun`            | `bool`                          | `true`       | 预览更改，不修改场景。                                  |

请参阅 [Transcript API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md) 了解此工具接入的运行时外观层。

#### `Convai.DiagnoseTranscripts`

**领域：** 转录 · **默认启用：** 是 · **是否修改数据：** 否

诊断转录功能的启用状态、外观层就绪情况、中继、UI，以及经过清理的运行时时间线元数据。

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

### 叙事

#### `Convai.ConfigureNarrative`

**领域：** 叙事 · **默认启用：** 是 · **是否修改数据：** 是

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

| 参数                      | 类型      | 默认值    | 说明                                                                                                                                                                     |
| ----------------------- | ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characterInstanceId`   | `long`  | —（必填）  | 角色 GameObject 实例 ID。                                                                                                                                                   |
| `managerHostInstanceId` | `long`  | `0`    | 叙事管理器所在宿主 GameObject 的可选实例 ID。                                                                                                                                         |
| `sections`              | `array` | `[]`   | 要新增或更新的叙事章节，每项格式为 `{ sectionId, sectionName }`.                                                                                                                        |
| `templateKeys`          | `array` | `[]`   | 要新增或更新的模板键，每项格式为 `{ key, value }`.                                                                                                                                     |
| `triggers`              | `array` | `[]`   | 要新增或更新的触发器。完整触发器字段集请参阅 [叙事设计脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/scripting-narrative-design.md) 。 |
| `dryRun`                | `bool`  | `true` | 预览更改，不修改场景。                                                                                                                                                            |

#### `Convai.DiagnoseNarrative`

**领域：** 叙事 · **默认启用：** 是 · **是否修改数据：** 否

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

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

### 运行时诊断

#### `Convai.TraceRuntimeEvents`

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

启动、读取、清除或停止编辑器专用的 Convai 运行时事件跟踪，最多可记录 256 条。退出播放模式或重新加载域时，跟踪记录会被清除。默认不捕获转录内容。

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

### 角色化身

Embodiment 工具会设置组合根，供每个表现模块接入—— `EmbodimentContext` 和 `StandardRigBinding` ——然后交由下方各模块专用的工具处理。 `Convai.DiagnoseEmbodiment` 这是每个角色首先应调用的工具：它会报告角色绑定、角色包含的所有模块、哪些模块实际会发挥作用，以及接下来应调用的模块专用工具名称。

#### `Convai.ConfigureEmbodiment`

**区域：** Embodiment · **默认启用：** 是 · **是否修改：** 是

设置 Convai 角色：立即解析其绑定，而不是等到运行时；添加指定的表现模块——本项目已安装的注视、情绪、身体动画、肢体语言和对话流程模块；并分配项目中已有的 Embodiment 预设。绝不会创建或编辑资源，也不会调整单个模块；每个模块都有自己的配置工具。仅在编辑模式下可用——如果在播放模式期间调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                    | 类型         | 默认值    | 说明                                         |
| --------------------- | ---------- | ------ | ------------------------------------------ |
| `characterInstanceId` | `long`     | —（必填）  | 要设置的 Convai 角色。 `0` 使用活动场景中唯一的角色。          |
| `setUpRig`            | `bool`     | `true` | 添加 Character Rig 组件，并立即解析角色的骨骼和面部网格。       |
| `capabilities`        | `string[]` | `[]`   | 要添加的表现模块，可按显示名称或模块 ID 指定。角色上已有的模块会保留，不作更改。 |
| `presetAssetPath`     | `string`   | `""`   | 要分配的现有 Embodiment 预设的项目路径。绝不会创建预设。         |
| `dryRun`              | `bool`     | `true` | 预览更改，不修改场景。                                |

#### `Convai.DiagnoseEmbodiment`

**区域：** Embodiment · **默认启用：** 是 · **会修改：** 否

端到端检查一个 Convai 角色：检查其绑定是否已识别、包含哪些表情模块、哪些模块实际会执行操作、哪些模块被阻止或处于无效状态及其原因、这些模块使用哪些设置资源、其 Embodiment Preset，以及在 Play Mode 下它当前正在做什么。

| 参数                    | 类型     | 默认值    | 说明                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `characterInstanceId` | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中唯一的角色。 |
| `includeCapabilities` | `bool` | `true` | 包含各模块的详细信息。                       |
| `includeRuntimeState` | `bool` | `true` | 包含实时对话和情绪状态。仅限 Play Mode。         |

#### `Convai.InspectEmbodimentPresets`

**区域：** Embodiment · **默认启用：** 是 · **会修改：** 否

列出项目中的 Embodiment Preset 及其有效性，并列出每个预设可包含的所有表情模块，以及用于创建其设置资源的菜单路径。绝不创建或编辑资源。

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

### 注视

#### `Convai.ConfigureGaze`

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

向角色添加 `ConvaiGazeController` 并调整其眼神交流方式——将谁视为玩家、注视的投入程度、身体转向方式，以及启用哪些可选功能。如果项目中存在现有的 Gaze Profile，则分配该配置；绝不创建或编辑资源。未指定的调整字段保持不变。仅在 Edit Mode 下可用——如果在 Play Mode 下调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                          | 类型                        | 默认值       | 说明                                                            |
| --------------------------- | ------------------------- | --------- | ------------------------------------------------------------- |
| `characterInstanceId`       | `long`                    | —（必填）     | 要配置的 Convai 角色。 `0` 使用活动场景中唯一的角色。                             |
| `eyeContactMode`            | `enum GazeEyeContactMode` | 省略 = 保持不变 | `Natural`, `SpeakingFocus`, `ConversationLock`或 `AlwaysLock`. |
| `focusFidelity`             | `enum GazeFocusFidelity`  | 省略 = 保持不变 | `Social` 或 `Exact`.                                           |
| `playerAnchorInstanceId`    | `long`                    | 省略 = 保持不变 | 此角色应视为玩家的变换。                                                  |
| `clearPlayerAnchorOverride` | `bool`                    | 省略 = 保持不变 | 清除覆盖设置，让角色重新注视主摄像机。                                           |
| `playerAnchorAimMode`       | `enum GazeAnchorAimMode`  | 省略 = 保持不变 | `Auto`, `ExactTransform`或 `LocalOffset`.                      |
| `bodyTurnStyle`             | `enum GazeBodyTurnStyle`  | 省略 = 保持不变 | `SteppingTurn` 或 `SmoothRotation`.                            |
| `profileAssetPath`          | `string`                  | `""`      | 要分配的现有 Gaze Profile。不会创建新的 Profile。                           |
| `capabilities`              | `string[]`                | 省略 = 保持不变 | 角色最终应具有的 Gaze 可选附加项的确切集合。                                     |
| `dryRun`                    | `bool`                    | `true`    | 预览更改，不修改场景。                                                   |

#### `Convai.DiagnoseGaze`

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

说明角色正在或没有看向玩家的原因：解析到哪些头部和眼睛骨骼、角色骨架朝向是否正确、系统将谁视为玩家以及该判断由哪个设置决定、正在使用哪个 Gaze Profile、角色具有哪些可选附加项，以及 Play Mode 下的实时注视状态。

| 参数                    | 类型     | 默认值    | 说明                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `characterInstanceId` | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中唯一的角色。 |
| `includeRuntimeState` | `bool` | `true` | 包含角色此刻正在看的对象。仅限 Play Mode。        |

#### `Convai.MarkGazeTarget`

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

将场景对象标记为值得注视的对象，让 Convai 角色看向它们——例如画作、屏幕或道具。向指定对象添加 `ConvaiGazeTarget` ；不会创建资源。仅在 Edit Mode 下可用——如果在 Play Mode 期间调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                      | 类型       | 默认值          | 说明                                        |
| ----------------------- | -------- | ------------ | ----------------------------------------- |
| `gameObjectInstanceIds` | `long[]` | —（必填）        | 要标记为值得注视的 GameObject。                     |
| `priority`              | `int`    | 省略 = 默认值 `5` | 对象的重要程度。玩家的优先级为 `10`；高于此值时，角色会看向此对象而不是玩家。 |
| `baseRelevance`         | `float`  | 省略 = 保持不变    | 对象近距离内的吸引力，范围从 `0` 到 `1`.                 |
| `maxDistance`           | `float`  | 省略 = 保持不变    | 角色不再注意该对象的距离（米）。                          |
| `fullRelevanceDistance` | `float`  | 省略 = 保持不变    | 对象最具吸引力的范围距离（米）。                          |
| `remove`                | `bool`   | `false`      | 改为取消标记这些对象。                               |
| `dryRun`                | `bool`   | `true`       | 预览更改，不修改场景。                               |

### 身体动画

#### `Convai.ConfigureBodyAnimation`

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

向角色添加 `ConvaiBodyAnimationController` 并进行配置——包括随附的动画内容、角色是否可以行走以及角色的移动方式。分配现有内容资源；不会创建、编辑或测量资源，也不会触碰 Animator Controller。仅在 Edit Mode 下可用——如果在 Play Mode 期间调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                                   | 类型                            | 默认值       | 说明                                                                         |
| ------------------------------------ | ----------------------------- | --------- | -------------------------------------------------------------------------- |
| `characterInstanceId`                | `long`                        | —（必填）     | 要配置的 Convai 角色。 `0` 使用活动场景中唯一的角色。                                          |
| `includeMovement`                    | `bool`                        | `true`    | 添加 `ConvaiNavMeshLocomotion` 使角色能够行走、慢跑、转向和停止。                             |
| `profileAssetPath`                   | `string`                      | `""`      | 现有的 Body Animation Profile，其中包含一个 Animation Set 和一个 Config。不会创建新的 Profile。 |
| `animationSetAssetPath`              | `string`                      | `""`      | 现有 Animation Set，供未使用 Profile 的角色使用。                                       |
| `configAssetPath`                    | `string`                      | `""`      | 现有的身体动画配置，适用于未使用配置档案的角色。                                                   |
| `speedProfile`                       | `enum LocomotionSpeedProfile` | 省略 = 保持不变 | 用于指定移动方式是步行还是慢跑。                                                           |
| `accelerationMetersPerSecondSquared` | `float`                       | 省略 = 保持不变 | 角色达到目标速度的快慢。                                                               |
| `dryRun`                             | `bool`                        | `true`    | 预览更改，不修改场景。                                                                |

#### `Convai.DiagnoseBodyAnimation`

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

说明角色的身体动画实际在做什么：是否已完成设置、绑定架是否能够驱动动画、解析到哪些动画内容、哪些行为可以正常运行、哪些行为因角色没有对应动画片段而不起作用、绑定架的缩放如何校准，以及播放模式下的实时状态。

| 参数                    | 类型     | 默认值    | 说明                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `characterInstanceId` | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中唯一的角色。 |
| `includeRuntimeState` | `bool` | `true` | 包含角色当前正在播放的动画。仅限播放模式。             |

#### `Convai.InspectBodyAnimationContent`

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

列出角色的动画集实际能够执行的内容——待机、交谈、聆听和思考动画池，以及每个动作和手势可接受的名称 `PlayAction` 、行走动画覆盖情况和指向方向。在编写使用这些内容的代码前，请先调用此项。 `PlayAction`.

| 参数                      | 类型       | 默认值  | 说明                                                    |
| ----------------------- | -------- | ---- | ----------------------------------------------------- |
| `characterInstanceId`   | `long`   | `0`  | 要列出其动画内容的 Convai 角色。当指定 `animationSetAssetPath` 时会忽略。 |
| `animationSetAssetPath` | `string` | `""` | 要直接检查的动画集，无需关联角色。                                     |

#### `Convai.TuneBodyAnimationPersonality`

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

调整角色的表现力、沉稳程度，以及独处时是否会自发进行活动。多个角色可以共用一个身体动画配置，因此此工具会先为指定角色创建一份专用副本，再进行任何更改——这与检查器提供的“ **为此角色设置专属配置** ”命令相同，而不是修改其他角色或 SDK 内置默认值仍在使用的配置。仅在编辑模式下可用——若在播放模式下调用，将返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                    | 类型                            | 默认值       | 说明                                                      |
| --------------------- | ----------------------------- | --------- | ------------------------------------------------------- |
| `characterInstanceId` | `long`                        | —（必填）     | 要调整的 Convai 角色。 `0` 若只有一个角色，则使用当前场景中的唯一角色。              |
| `archetype`           | `enum BodyAnimationArchetype` | 省略 = 保持不变 | 命名的个性预设： `Composed`, `Warm`, `Energetic`或 `Reserved`.   |
| `howExpressive`       | `float`                       | 省略 = 保持不变 | 说话时手势的幅度和频率，从 `0` 到 `2`.                                |
| `howCalm`             | `float`                       | 省略 = 保持不变 | 角色保持姿势的时长，以及动作收尾的柔和程度，从 `0` 到 `2`.                      |
| `keepsBusyWhenAlone`  | `bool`                        | 省略 = 保持不变 | 指定角色在静默期间是否会自行进行一些小活动。                                  |
| `makeConfigUnique`    | `bool`                        | `false`   | 同意在配置被多个角色共用或随 SDK 一同提供时复制配置。应用更改前必须同意；预览始终会报告是否需要创建副本。 |
| `dryRun`              | `bool`                        | `true`    | 预览更改及是否需要创建副本，不会写入任何内容。                                 |

{% hint style="info" %}
`Convai.TuneBodyAnimationPersonality` 和 `Convai.TuneEmotionPersonality` 是此目录中仅有的两个会写入磁盘的工具。两者都会为单个角色复制共享设置资源或 SDK 自带的设置资源，而不是直接修改原资源；并且只有在预览显示需要创建副本后，获得明确的 `makeConfigUnique`/`makePersonalityUnique` 同意后才会应用更改。
{% endhint %}

### 肢体语言

#### `Convai.ConfigureBodyLanguage`

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

为角色添加 `ConvaiBodyLanguageController` ，使其在说话时呼吸、调整重心、摇摆并做手势；还可为其指定项目中已有的肢体语言配置文件，以赋予个性。绝不会创建或编辑资源；如果角色的骨架无法驱动该模块，则会拒绝添加，而不会添加无效组件。仅在编辑模式下可用——如果在播放模式下调用，则会返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                         | 类型       | 默认值     | 说明                                                     |
| -------------------------- | -------- | ------- | ------------------------------------------------------ |
| `characterInstanceId`      | `long`   | —（必填）   | 要配置的 Convai 角色。 `0` 使用活动场景中唯一的角色。                      |
| `personalityAssetPath`     | `string` | `""`    | 要指定的现有肢体语言配置文件。绝不会创建配置文件。省略此项则保持个性设置不变。                |
| `assignDefaultPersonality` | `bool`   | `false` | 为没有个性设置的角色指定 SDK 自带的配置文件，或项目中的第一个配置文件。若角色已有个性设置，则保持不变。 |
| `dryRun`                   | `bool`   | `true`  | 预览更改，不修改场景。                                            |

#### `Convai.DiagnoseBodyLanguage`

**领域：** 肢体语言 · **默认启用：** 是 · **会修改：** 否

说明角色的身体在做什么以及原因：骨架支持哪些功能、哪种个性配置会调节这些功能以及该配置会关闭哪些行为、还有哪些 Convai 模块共用其身体以及各模块会带来哪些变化；并且在播放模式下，还会说明角色当前的姿势、呼吸、重心移动和手势抑制状态。

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

#### `Convai.InspectBodyLanguagePersonalities`

**领域：** 肢体语言 · **默认启用：** 是 · **会修改：** 否

列出项目中的肢体语言配置文件——包括每个配置文件的表现力、它会关闭哪些行为，以及当前打开的场景中有哪些角色已在使用它。

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

### 情绪

#### `Convai.ConfigureEmotion`

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

为角色添加 `ConvaiEmotionController` ，使其面部能对说话内容做出反应，为其指定项目中已有的个性配置，并设置情绪检测方式及角色的默认情绪。它只会写入角色自身的字段，绝不会创建或编辑个性资源，因此不会意外改变其他角色的风格。仅在编辑模式下可用——如果在播放模式下调用，则会返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                     | 类型       | 默认值         | 说明                                        |
| ---------------------- | -------- | ----------- | ----------------------------------------- |
| `characterInstanceId`  | `long`   | —（必填）       | 要配置的 Convai 角色。 `0` 使用活动场景中唯一的角色。         |
| `personalityAssetPath` | `string` | `""`        | 要指定的现有 `ConvaiEmotionProfile` 。绝不会创建配置文件。 |
| `emotionDetection`     | `string` | `""` （保持不变） | 角色自身的情绪检测设置。                              |
| `restingMood`          | `string` | `""` （保持不变） | 此角色自身的默认情绪覆盖值。                            |
| `restingMoodStrength`  | `float`  | 省略 = 保持不变   | 默认情绪覆盖值的强度。                               |
| `dryRun`               | `bool`   | `true`      | 预览更改，不修改场景。                               |

#### `Convai.DiagnoseEmotion`

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

说明 Convai 角色的面部实际会做出什么反应以及原因：它是否能表现情绪、如何检测情绪、由哪种个性设定来调节、默认处于什么状态以及由哪个设置决定，以及哪些行为已关闭或被其他设置悄然限制。

| 参数                    | 类型     | 默认值    | 说明                                |
| --------------------- | ------ | ------ | --------------------------------- |
| `characterInstanceId` | `long` | `0`    | 要诊断的 Convai 角色。 `0` 使用活动场景中唯一的角色。 |
| `includeRuntimeState` | `bool` | `true` | 包含当前的主导情绪和心情。仅限播放模式。              |

#### `Convai.InspectEmotionPersonalities`

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

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

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

#### `Convai.TuneEmotionPersonality`

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

更改角色的感受方式——包括角色类型、默认状态、表现情绪的强度和速度，以及情绪表现开关。这些设置位于其他角色可能共用的个性资源中，因此此工具会先预览；经明确同意后，为该角色创建独立副本，并且只修改该副本。它绝不会直接修改共享个性或随 SDK 提供的个性。仅在编辑模式下可用——如果在播放模式下调用，则返回 `PLAY_MODE_ACTIVE` 失败代码。

| 参数                            | 类型       | 默认值         | 说明                                         |
| ----------------------------- | -------- | ----------- | ------------------------------------------ |
| `characterInstanceId`         | `long`   | —（必填）       | 要调整的 Convai 角色。 `0` 若只有一个角色，则使用当前场景中的唯一角色。 |
| `characterType`               | `string` | `""` （保持不变） | 适用于该角色类型的命名个性预设。                           |
| `restingMood`                 | `string` | `""` （保持不变） | 该个性自身的默认心情。                                |
| `howStronglyItShows`          | `float`  | 省略 = 保持不变   | 情绪在面部表现出的强度。                               |
| `howQuicklyItReacts`          | `float`  | 省略 = 保持不变   | 面部对感受变化做出反应的速度。                            |
| `neverSitsPerfectlyStill`     | `bool`   | 省略 = 保持不变   | 是否播放对话节拍中的细微反应。                            |
| `picksUpOtherCharactersMoods` | `bool`   | 省略 = 保持不变   | 该角色的心情是否会受到其他角色心情的影响。在只有一个角色的场景中不会产生可见效果。  |
| `makePersonalityUnique`       | `bool`   | `false`     | 同意在此个性被多个角色共用或随 SDK 一同提供时复制该个性。应用前必须获得同意。  |
| `dryRun`                      | `bool`   | `true`      | 预览更改及是否需要创建副本，不会写入任何内容。                    |

### 后续步骤

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

{% content-ref url="/pages/ec47f18f1ec454c3afecbec3a73f8ab46981f55c" %}
[受支持的编码代理](https://docs.convai.com/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 编码助手设置问题](https://docs.convai.com/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 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/ai-coding-assistant/mcp-tools-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.
