> 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/overview/release-notes.md).
# 发行说明
Convai Unity SDK 的发行说明——当前版本亮点、以前的发行说明、错误修复以及每个版本的迁移指南。
跟踪 Convai Unity SDK 各版本之间的变化，包括新功能、错误修复和配置更改。当前版本是 space.vars.unity\_sdk\_version.
{% updates format="full" %}
{% update date="2026-09-04" tags="v4.6.0,Current" %}
## v4.6.0
**本版本的破坏性更改：** `SetExplicitConversationTarget` 更名为 `SetInitialCharacter`，移除了并替换了三个 Gaze 配置文件的 Conversation Attention 字段， `headStabilityDegrees` 被移除，两个 Gaze 配置文件默认值发生变化，并且多角色场景中的麦克风开启时机也发生了变化。参见 **破坏性更改和迁移** 下文。
**多角色对话**
* 会话目标定位已移入 SDK：无需添加组件、碰撞体、图层或填写字段。 `ConvaiManager.ConversationTargeting` 默认读取玩家视角，并按角度对每个候选对象打分，以距离作为平局判定，因此在鼠标、手柄和头戴显示设备上的表现一致。 `模式` 会选择 `LookAt`, `接近`，或 `手动`; `ConvaiManager.TalkTo(character)` 为脚本化时刻显式指定对话目标
* 现在房间会打开到玩家正在注视的角色，而不再总是场景顺序中的第一个角色。已指定的 **Convai Manager > Initial Character** 仍然会直接生效，而控制台会说明它打开到了哪个角色以及原因
* 加入或离开已连接房间的角色会实时添加或移除，无需重新连接——实例化角色预制体，或启用某个角色 `GameObject`，就是完整集成。以单个角色连接的房间不包含名册，也无法实时扩展；控制台会说明这种情况以及应如何处理
* `ConvaiManager.Events` 新增 `OnConversationAvailabilityChanged`, `OnConversationTargetChanged` （带有阶段 `Requested`, `Confirmed`, `Failed`），以及 `OnRoomRosterChanged`
* `Convai.ConfigureConversationTargeting` 加入 MCP 和 Unity Assistant 工具集，并且 `Convai.DiagnoseConversation` 报告名册、被指向的角色以及目标判定结果。工具契约版本 `7`
* 一个 **多角色示例** 与现有的 Basic 和 LipSync 示例一同发布
**对话可用性**
* `ConvaiManager.ConversationAvailability` 回答玩家此刻是否可以说话—— `离线`, `连接中`, `Preparing`, `Ready`, `Answering`, `Unavailable` ——适用于 `ConvaiManager.AddressedCharacter`，并将 `ConversationAvailabilityChanged` 报告每次变化，并 `CanAcceptPlayerInput()` 作为 UI 询问的问题。同样的答案也可在每个角色的 `ConvaiCharacter.ConversationAvailability`
* 现在发布的聊天输入框、按键说话和免手操作输入都会查询它。聊天输入框会在角色能够听见之前保持禁用，而 `ConvaiPlayer.TrySendTextMessage` 会返回失败原因，项目可以将其显示出来，而不是悄悄丢弃消息
* **行为变更：** 在多角色场景中，麦克风现在会在房间确认其第一个角色时开启，而不是在传输连接时开启——通常会晚几分之一秒。单角色房间不受影响
**凝视**
* **关注说话者** 在 Gaze 组件上现在会跟随对话当前发言方——玩家、另一个角色或两者——只要该角色还未轮到自己发言，因此一个房间里有多个参与者时，听众会对正在说话的人做出反应，而不是坐在那里 `空闲`。配置文件中的四个新设置位于 **对话** 组，用于调节模型： **转向前的典型停顿**, **反应变化幅度**, **注意力衰减持续多久**，以及 **听众转头之间的最短间隔**
* 现在听众注意力是每个参与者单独的数值，会在开始说话时上升并持续衰减，从而修复听众晚转向、新说话者、同时转向或转向错误对象的问题
* 头部和胸部现在会连续跟随移动目标，而不是分段跟随，消除了导致停驻式卡顿和鞭甩式纠正的死区。摄像机切换现在被视为普通的注视，而不是惊跳反应。 **头部速度上限** 从 240°/s 降至 150°/s，且 **转向速度（无转身动画的骨架）** 从 140°/s 降至 90°/s——两者都是安全上限；已创建的配置文件会保留其已保存的值
**语音与性能**
* 在带有 Lip Sync 的角色上，说话轮次现在在 Lip Sync 自己的帧数据结束时就会结束，而不是等待静音检测器或服务确认，因此角色会在声音停止时停止表演，而不是最多再晚两秒。 `ConvaiCharacter.IsSpeaking`, `OnSpeechStopped`，以及 `OnTurnCompleted` 不受影响。Conversation Flow 配置文件包含一个 `stopWhenTheVoiceStops` 开关，用于旧的时序方式，但它默认开启，并且不在配置文件的 Inspector 中公开，也没有公开的 setter，因此新的时序就是每个角色采用的方式
* 角色的嘴现在会在句子结束时自然闭合，而不会一直张着或突然闭上：Lip Sync 组件上的新 **收束时长** （0.35 秒）通过基于弹簧的闭合来驱动，且 `LipSyncPlaybackEngine.SettleToRest()` 从代码中触发它
* 当响应结束时，说话手势不再会在中途冻结——手势现在会随着权重衰减而减速回到静止状态，从 **Talk Release Lead Seconds** （0.6 秒）开始，在响应真正结束之前
* 在会话中的第一个响应之后，Lip Sync 不再停滞；现在后续每个响应都会伴随活动嘴型播放，而不是静止嘴型
* `ConvaiCharacter.OnTranscriptReceived` 会触发。它之前读取的是服务不会发送的消息，因此在任何房间里都从未触发，而其下游的一切都处于闲置状态——凝视指代性瞥视，以及任何 `IConvaiCharacterBehavior` 对角色所说内容作出反应。现在它读取房间转录流，而其 `isFinal` 参数来自消息自身的生命周期，而不是硬编码为 `false`，因此依赖最终发言进行门控的消费者可以正常工作。其有两个后果：文本按句子到达，而不是按合成块到达；并且在句子稳定之前流入的一行会被发送两次——一次中间态，一次最终态
**编辑器和 Inspector 工作**
* 中的多角色控件 **Convai Manager** Inspector 中的名称已为清晰起见重命名： *包含到下一个房间中* 现在是 **加入房间的角色**, *在内* 是 **范围（米）**, *从以下视角* 是 **玩家相机**, *场景角色* 是 **场景中的角色**，以及 *名册房间* / *单个角色* 是 **多个角色** / **仅一个角色**
* 该 **Convai Manager** Inspector 的 Live 部分现在会显示正在被指向的是谁、玩家是否可以与其对话，以及房间中每个角色各自的状态
* Character Inspector 现在会在 Play 模式之前标记重复的 Character ID，而不是只在房间拒绝连接时才提示
* 该 **Convai Player** 和 **Convai Room Manager** 验证部分已重新设计，其标题会反映发现的最严重检查结果，而不再是永久显示琥珀色的标题
* 现在每个 Convai Inspector 部分都共享同一种左侧对齐方式和同一种分区内边距系统
**Unity 6000.5 兼容性**
* 该包现在重新可以在 Unity 6000.5 上编译。Unity 的场景标识迁移到了 64 位 `EntityId`，以及 `Object.GetInstanceID()`的弃用，现在都通过兼容层（`ConvaiSceneId`, `ConvaiObjectId`, `ConvaiObjectFind`）进行处理，因此标识在 `6000.0` 到 `6000.3` 上保持不变，并且在 `6000.4` 及更高版本上与旧标识一致
**包依赖**
* `com.unity.ai.inference` `2.2.1` 是一个新依赖，用于客户端语音活动检测
* `com.unity.nuget.newtonsoft-json` `3.2.2`, `com.unity.ugui` `2.0.0`，以及 `com.unity.inputsystem` `1.19.0` 得以保留
* `com.unity.ai.navigation`, `com.unity.collections`，以及 `com.unity.modules.xr` 不再被声明为依赖项
**破坏性更改和迁移**
* **`ConvaiManager.SetExplicitConversationTarget` 更名为 `ConvaiManager.SetInitialCharacter`.** 旧名称仍可调用，并标记为 `[Obsolete]`。之所以更名，是因为旧名称看起来像是在改变玩家正在和谁对话的动词，但实际上它决定的是谁先发言；对已连接的房间调用它，会排队触发所有权重新连接，而不是移动对话目标。将 `SetExplicitConversationTarget(character)` 使用 `SetInitialCharacter(character)` 替换为可获得相同行为；要 `TalkTo(character)` 来在运行中的房间中切换对话
* **Gaze 配置文件中的 Conversation Attention 字段已被移除：** **转向前最短/最长延迟**, **在对话中保持多久**，以及 **看向下一位作答者**，以及 `ConvaiGazeProfile.SpeakerAttentionReactionDelayMin/Max`, `SpeakerAttentionLingerSeconds`，以及 `SpeakerAttentionHandOffGlanceChance`。它们的替代项是 **转向前的典型停顿**, **反应变化幅度**, **注意力衰减持续多久**，以及 **听众转头之间的最短间隔**。携带已移除字段的配置文件在下次保存时会静默丢失这些字段——重新应用一种人格，或者保留默认值，以采用新的注意力模型调优
* **Gaze 配置文件中的 Ignore Small Target Movement（`headStabilityDegrees`）已被移除。** 其替代项位于 **头部与身体** 是 **头部跟随运动的速度有多快** (`HeadFollowSeconds`，默认 0.2 秒）以及 **胸部跟随运动的速度有多快** (`TorsoFollowSeconds`，默认 0.35 秒）。携带已移除字段的配置文件从加载那一刻起会忽略该字段，并在下次保存时丢弃它；如果快速目标让头部落后太多，请降低 **头部跟随运动的速度有多快** 。
* **Gaze 配置文件的两个默认值已更改：** **转身期间颈部放松** (`bodyTurnHeadRelief`）从 `0.4` 为 `1`，以及 **胸部速度上限** (`maxTorsoAngularSpeed`）从 `180°/s` 为 `90°/s`。现有配置文件会保留其已保存值——只有新配置文件会采用新默认值。要在现有配置文件上采用新默认值，请手动设置这两个值
* **行为变更：** 在多角色场景中，麦克风现在会在房间确认其第一个角色时开启，而不是在传输连接时开启
{% endupdate %}
{% update date="2026-08-14" tags="v4.5.0" %}
## v4.5.0
**角色 Embodiment**
现在有五个行为模块在 **添加组件 > Convai > Embodiment**下共享同一组件家族，并且每个模块读取相同的对话状态。
* **Convai Gaze** (`ConvaiGazeController`）取代了之前的 Gaze 实现和 Attention 模块。它在一个组件中决定角色看向哪里并执行注视：眼神接触样式（`自然`, `Speaking Focus`, `Conversation Lock`, `Always Lock`), `ConvaiGazeTarget` 用于带有优先级层级和瞄准偏移的场景对象， `PlayerAttentionSensor` 用于“玩家是否在看我”，提供从眼睛到头部再到胸部再到脚部的整套全身注视共享阶梯，以及通过 `IPlayerGazeRaySource`
* **Convai Body Animation** (`ConvaiBodyAnimationController`）取代了 Dialogue Animation。它在代码中构建自己的分层 `PlayableGraph` ，因此无需编写 Animator Controller 资源。它涵盖待机与对话变体、伴随语音的手势、朝向目标的手势，以及与 NavMesh 同步的行走，支持定向起步、定点停步和原地转身。动画片段和 `ConvaiBodyAnimationSet_Female` 随模块一同提供
* **Convai Body Language** (`ConvaiBodyLanguageController`）是新增内容：呼吸、重心转移、摆动、姿态脉冲、随语音节奏的头部点头、聆听时前倾、待机小动作，以及受惊或觉得有趣时的反应。它叠加在 Animator 之上，但不拥有任何片段，也不需要导入内容
* **情绪** 获得了语义表情方案，可在 ARKit、Reallusion CC3 和 CC4 以及 MetaHuman 绑定上解析，无需为每个角色单独制作，同时还增加了静止情绪、情绪漂移、微表情待机层和着色器属性输出。 `ConvaiEmotionController.SetMood(label, intensity, transitionSeconds)` 和 `ClearMood(transitionSeconds)` 在运行时控制情绪，并且 `DominantEmotionChanged` 和 `MoodChanged` 报告解析后的表情。随包提供四种人格：Composed、Warm、Energetic 和 Reserved
* **对话流程** 提供其他四个模块读取的对话状态
**角色动作**
* 该 **Actions 编辑器** 窗口（**Convai > Actions Editor**）增加了可复用的 Action Sets、Scene Knowledge、Character Settings，以及带有批量进度、时间线、目标注册表和逐项操作洞察的 Live 模式。 **试一试** 框在编辑模式下预览一个动作，并在播放模式下分发它
* 新增四个内置执行器：Lead Player To Target、Scan Environment、Count Target Group 和 Measure Distance
* `ConvaiActionExecutionResult.Answered("…")` 允许动作提供一句角色可以说出的句子，与诊断信息分开 `Message`. **完成时** 为每个动作单独编写这一内容
* `ConvaiActionFailureReason` 在 `ConvaiActionExecutionResult` 和 `ConvaiActionStepReport`. `ConvaiActionParameterValue.Presence` 上报告类型化的失败原因，将未填写的槽位与空白槽位区分开来。 `ConvaiActionDispatcher` 公开 `IsBusy`, `PendingBatchCount`，以及 `CurrentActionName`
* `ConvaiActionExecutorBase`, `ConvaiTargetedActionExecutor`，以及 `ConvaiCharacterActionExecutor` 是自定义行为的基类。 `ConvaiPlayerBody` 现在是 public，并且 `ConvaiActionExecutorBase.ResolvePlayer()` 是 `virtual`，因此移动子胶囊的第一人称骨架会解析到玩家真实位置
* Wire 解析已在大量丢失和乱码命令的情况中得到修正，并且场景中放置的 `ConvaiActionTarget` 现在可在会话中同步到 Convai
**身份验证**
* 身份验证现在是在 API Key 模式和 Auth Token 模式之间进行的项目级选择。Auth Token 模式会从配置的端点或 `IConvaiAuthTokenProvider` 在每次房间连接前解析一个新的短期凭据，可在原生和 WebGL 传输中工作，并将凭据发送到 `API-AUTH-TOKEN` 标头中，同时从玩家构建中移除已保存的账号 API 密钥，但在 Editor 工具中仍保留它
* `ConvaiManager.ConnectWithAuthTokenAsync` 是一个一次性连接，适用于其登录层已持有 Convai auth token 的项目。它还会提供 `end_user_id` 和 `end_user_metadata.name` ，即使没有已注册的提供程序或已配置的端点
**会话生命周期**
空闲警告和空闲截止事件， `ResetIdleTimer` 和 `ExtendIdleTimeout`以及显式的暂停、恢复和重新连接控制现在都可在运行时使用。后台行为通过 `ContinueAudibly`, `PauseTimeline`，以及 `MuteButCatchUp` 策略进行设置，并带有一个可观测的 WebGL 回退行为，来自 `PauseTimeline` 为 `MuteButCatchUp`.
**编辑器工具**
* **Convai > 故障排除** 按角色报告每项 Convai 能力的状态：已设置、被阻止，或已设置但处于无效状态，并提供一键修复和一个 **全部修复** 操作。可通过以下方式扩展它： `IConvaiSetupHealthProvider` 和 `ConvaiSetupHealthRegistry.Register`
* 该 **Convai** 菜单从 17 行缩减到 9 行——见下方“破坏性更改和迁移”
* 每个 Convai Inspector 和窗口都迁移到了共享的编辑器设计系统，而 Character Rig Inspector 也被重写为以 Ready 或 Needs Attention 判定以及分段的检测置信度开头
* 打开包内附带的设置资源是只读的，并提供 **创建项目副本**，会将副本放到 `Assets/Convai/`
**要求和依赖项**
最低 Unity 版本是 `6000.0.80f1`。该包增加了三个依赖项： `com.unity.ai.navigation`, `com.unity.collections`，以及 `com.unity.modules.xr`.
**LipSync、samples 和 platforms**
* Lip Sync 示例以 Sofia（一名 Reallusion CC4 角色）取代了 Camila
* 内置 viseme 映射和 lip sync 配置文件已从 `SamplesShared/Resources/` 移入 LipSync 模块，并通过代码构建。位于 `Resources/LipSync/ProfileRegistries/` 下的项目注册表仍会被发现并仍然会优先
* `ConvaiLipSyncSpeechEnergyAdapter` 从未被采样，因此所有读取语音能量的特性都读到的是一条平坦信号。现在它会加入角色 tick，并逐帧采样
* 该包随附 `ConvaiSampleFirstPersonController` 和 `ConvaiSampleFirstPersonInputs`，它是对 Unity Starter Assets 第一人称控制器的重命名副本
* Meta Quest 按键说话释放现在通过 Unity 的 XR 输入 API 读取 A、B、X 和 Y 按钮，而控制器读取失败或断开会默认失败，因此麦克风采集不会一直保持开启
* Quest Vision Frame Source 具有精心设计的 Inspector 和实时采集读数。升级后，Vision 组件折叠状态会重置一次
**破坏性更改和迁移**
* **Unity 6000.0.80f1 是最低编辑器版本。** 低于此门槛不受支持。升级包之前请先升级编辑器
* **三个模块已退役，每个都有一个后继者。** Attention 由 Convai Gaze 取代，Dialogue Animation 由 Convai Body Animation 取代，而面部片段系统由 Emotion 模块的微表情层取代。它们的程序集、配置文件资源和预设槽位也一并移除
* **从 Attention 或之前的 Gaze 组件迁移：** replace `ConvaiAttentionController`, `ConvaiGazeCoordinator`, `ConvaiHeadLookActuator`，以及 `ConvaiEyeGazeActuator` 替换为一个单独的 `ConvaiGazeController` (**添加组件 > Convai > Embodiment > Gaze**）。删除你的 `ConvaiAttentionProfile`, `ConvaiGazeCoordinationProfile`, `ConvaiGazeEyeProfile`，以及 `ConvaiGazeHeadProfile` 资源——这些类型已经消失，资源将无法反序列化。调优值不会继承；请在一个 `ConvaiGazeProfile`上重新调优，或者不指定任何项并从默认值开始。将自定义的 `IFocusTargetProvider` 或 `IGazeIntentProvider` 使用 `IGazeTargetProvider` 通过 `RegisterTargetProvider`, `ConvaiAttentionDynamicContextBridge` 使用 `GazeDynamicContextBridge`，以及 `ConvaiWorldObjectFocusProvider` 使用 `ConvaiGazeTarget`替换为 `ConvaiWorldObjectFocusProvider` 在保存受影响的场景之前完成，因为 Unity 会在下一次保存时静默移除已删除的组件
* **从 Dialogue Animation 迁移：** replace `ConvaiDialogueAnimationController` 使用 `ConvaiBodyAnimationController`，将片段从 `DialogueAnimationLibrary` 到一个 `ConvaiBodyAnimationSet`移动到 `ConvaiBodyAnimationConfig`。删除 `DialogueAnimatorContract` 资源、其四个 Animator 层、乒乓状态以及 `ConvaiDialogueSlot_*` 占位片段；保留一个 Animator Controller 会与图形争夺同样的骨骼。按片段进行的性别过滤（`CharacterGender`）和按片段的情绪亲和标签（`DialogueEmotionAffinity`）没有字段级迁移——请为每种角色类型各自编写一套，而不是在运行时过滤混合集合。 `AnimationRiggingGazeBridge` 已移除，Convai Gaze 不再需要 rigging 包
* **从面部片段迁移：** 删除 `ConvaiFacialClipPlayer`, `ConvaiFacialClipRuntimePlayer`及其配置文件资源，并让 Emotion 模块的微表情层生成待机面部生动效果——它默认开启，无需任何移植。对有意设计的面部表演，在此版本中没有受支持的替代方案；请自行使用 `SkinnedMeshRenderer.SetBlendShapeWeight` 在一个不再由任何 Convai 模块组合的网格上驱动它。升级前请先将你的片段烘焙到你自己的资源中，因为 `ConvaiFacialAnimationProfile` 模块消失后，资源将无法反序列化
* **Convai 编辑器菜单已重新组织。** **Convai > 欢迎**, **Convai > 账户**, **Convai > 长期记忆**, **Convai > 更新**, **Convai > 联系我们**，以及 **Convai > AI 编码设置** 已经移除；这些部分现在要再点一次，位于会打开的窗口中 **Convai > Convai Editor** 打开后。当前的九个条目分为三组：Convai 编辑器窗口及其设置—— **Convai > Convai Editor**, **Convai > 设置**, **Convai > 文档**；各功能的创作编辑器—— **Convai > Actions Editor**, **Convai > Body Animation Editor**, **Convai > 情绪编辑器**, **Convai > Gaze Editor**, **Convai > 具身编辑器**；以及诊断—— **Convai > 故障排除**。 `ConvaiConfigurationWindowEditor` 直接打开某个部分的方法仍然是 public
* **`UnityEventActionExecutor` 已重命名为 `ConvaiUnityEventActionExecutor` 并带有新的 GUID。** Unity 不会迁移该组件：它会从所有使用它的场景和预制体中移除，连同接入其中的事件一起删除，而且没有任何升级步骤能恢复它们。升级前请记录每个事件的调用情况。之后，在每个受影响的对象上添加 `ConvaiUnityEventActionExecutor` (**添加组件 > Convai > 动作 > 触发 Unity 事件**）到每个受影响的对象上，手动重新连接其事件，并重新指向任何绑定到旧组件的动作。序列化字段仍然是 `_onExecute`
* **三个实验性的动作执行器已从公共目录中移除：** Guided Tour、Address The Group 和 Perform Gesture At Target。 `LookAtTargetActionExecutor` 也已移除——请添加 `ConvaiLookAtActionExecutor` (**添加组件 > Convai > 动作 > 注视目标**）来替代，并让角色使用 Gaze，因为替代方案通过 `ConvaiGazeController`。六个示例动作行为， `ConvaiActionTestSetup`，以及 `ConvaiActionDebugWindow` 已移除；这些工作已由 Actions Editor 覆盖
* **指向目标的 `持续秒数` 仅表示手势中途的停顿**，而不是整个手势的时长。现在有两个设置会影响指向层： **手势速度** 会乘以上抬和下落速度，而 **释放** 设置为 `Blend` 在持续结束时放下姿势。两者默认都与之前行为一致，因此现有场景无需更改；约一秒钟的指向效果由 Gesture Speed 搭配 Release 实现 `1.5` 配合 Release `Blend`
* **现在有十四种编辑器类型 `internal`,** 其中包括 `ConvaiVisionBaseEditor`, `ConvaiCharacterEditor`，以及 `TurnTakingOptionsDrawer`。不再支持对 Convai 编辑器或属性绘制器进行子类化，也没有替代的扩展点——请删除该子类，并通过单独的 `MonoBehaviour` 自定义项添加项目专属控件。 `[CustomEditor]` 注册不受影响，因此每个 Convai 检视器都会像以前一样绘制
* **Emotion 模块的槽位列表面部输出路径已移除：** `EmotionSlotBinding`, `BlendshapeEmotionBinding`, `AnimatorParameterEmotionBinding`, `RealisticEmotionSlots`, `NeutralAlternator`，以及 `SemanticExpressionsEnabled` 和 `NeutralAlternationEnabled` 开启时 `ConvaiEmotionProfile`。只要启用语义表情，运行时就会丢弃这些数据，而所有已发布的配置文件都启用了该功能，因此无需迁移任何内容。Shader 属性输出不受影响
* **共享的 Emotion 分类法和配置文件资源已变更身份。** `ConvaiSamplesShared_EmotionTaxonomy.asset` 已重建，并且 `ConvaiSamplesShared_EmotionProfile.asset` 被四个命名人格所取代。打开每个受影响的角色，重新指向分类法和人格；没有分类法的角色仍可运行，但每个情绪下拉框都会是空的
* **身体化类型已重命名，资源 GUID 保持不变：** `EmbodimentProfileReceiver` 为 `ConvaiCharacterModule`, `CharacterEmbodimentPreset` 为 `ConvaiEmbodimentPreset`, `EmbodimentPresetLibrary` 为 `ConvaiEmbodimentPresetLibrary`，以及 `ConvaiCharacterEmbodimentBinding` 为 `ConvaiEmbodimentPresetBinding`。只需更新源代码引用。 `EmbodimentContext` 用一个替换了其按缝注册成员 `CharacterServiceRegistry` ——实现 `IEmbodimentTickable` 并调用 `EmbodimentContext.RegisterTickable(this)` 来自 `OnEnable` 以加入角色 tick。 `EmbodimentContext.TryResolve` 不再会在非 Convai 角色的 GameObject 上创建上下文；请调用 `TryResolveFor` 以获得可诊断的失败信息
* **`ActionResponsePayload` 以及公开的 `UnityObjectCompatibility` 类已移除。** 动作命令仍然通过 `ConvaiCharacter.OnActionsReceived` 和 `ConvaiManager.Events.OnCharacterActionReceived`替换为 `UnityObjectCompatibility.FindObjectsByType(mode)` 与 Unity 的 `Object.FindObjectsByType`，以及 `UnityObjectCompatibility.GetId(value)` 使用 `value.GetInstanceID()` 最高到 Unity 6000.4，或 `value.GetEntityId()` 在 6000.2 及更新版本中
* **Camila 示例角色已移除。** 引用她的预制体、材质或纹理的场景或预制体会报告缺失引用。Sofia 使用相同的 blendshape 约定，因此 Convai 配置可以迁移。升级前请将任何自定义的 Camila 资源从包中复制出来
{% endupdate %}
{% update date="2026-07-30" tags="v4.4.1" %}
## v4.4.1
**修复**
* 为对象 ID 和对象搜索添加了 Unity 6.0 到 6.5+ 的兼容路径。Unity 6.4 及更新版本使用 64 位 `EntityId` 且使用无排序搜索 API，而 Unity 6.0 到 6.3 保留旧版回退
* 通过移除不可用的伪模块依赖并固定，修复了 Unity 6.0 项目解析 `com.unity.collections` 为 `2.6.8`，避免了已知的 Collections `2.6.7` 和 AI Assistant `xxHash3`/`Unsafe` 编译器回归问题
* 通过对齐两种 URP 渲染层序列化格式，使 LipSync 示例背景灯在 Unity 6.0 和 6.4+ 上保持隔离，防止灯光使示例角色过曝
* 即按住说话松开后，在等待最终转录结果时现在会保持麦克风和语音识别开启。当可配置的 `PushToTalkPolicy.ReleaseTailMs` 窗口到期时，SDK 会发出权威停止信号，并在关闭采集前再允许一个受限的窗口
* 修复了 WebGL 构建因过期的 `NativeLib` 引用而崩溃的问题，位于 `livekit-bridge.jslib`，并通过修正音频计时注册顺序、预热 WebGL 分析器以及恢复丢失的 `PlaybackStarted` 回调
{% endupdate %}
{% update date="2026-07-21" tags="v4.4.0" %}
## v4.4.0
**规范化转录时间线**
`ConvaiManager.Transcripts` 现在公开了一个房间范围的 `TranscriptTimeline` 由不可变 `TranscriptTurn` 和 `TranscriptChange` 模型构建的接口，取代了之前基于快照的契约。 `CurrentTimeline` 返回 `TranscriptTimeline` 而不是时间线快照， `Changed` 提供 `TranscriptChangeBatch`，以及 `Subscribe`/`SubscribeCommitted` 回调接收 `TranscriptChange` 值。对于任何使用旧快照类型的代码来说，这是一个破坏性变更——请参见 [转录 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md) 参考文档获取完整迁移路径。
**角色动作**
* `ConvaiActionConfigPatch` 在活动会话期间更新角色动作、角色目标、对象目标和当前注意对象，并采用“省略列表”与“空列表”不同语义，以及生成的更新 ID
* `ConvaiActionDefinition.WaitForBotSpeech` （在 `ConvaiActionCommand`）上的镜像使新批次中的第一个动作在执行前等待角色发言，并可选地使用 `DelayAfterBotSpeechSeconds` 暂停和分发器级语音门限超时，这样静默回合就不会卡住批处理
**AI 编码助手集成**
**Convai > AI 编码设置** 打开一个新的编辑器部分，用于配置基于 Unity MCP 的 AI 编码辅助，并支持 Codex、Claude Code、Cursor、Gemini 和 VS Code Copilot。专门的文档部分已完整介绍此集成。
**动态视觉上下文**
房间可以通过位于以下位置的新“动态视觉上下文”部分选择启用后端帧采样： `ConvaiRoomManager` 和 `ConvaiRoomManagerProfile`.
**Convai SDK 设置**
该 **Convai SDK** 项目设置页面（**Edit > Project Settings > Convai SDK**）以及编辑器窗口的新 **Convai > 设置** 部分共用同一实现，涵盖 Setup Health、Credentials、Runtime Defaults、Diagnostics、Advanced 和 About。Credentials 新增 API 密钥混淆，并可从明文自动迁移，提供 Environment 预设（Production、Beta 或 Custom），以及带缓存验证标记的 Validate & Save 操作。
**唇形同步**
播放对齐加固将 NeuroSync 唇形同步锚定到语音开始的精确音频帧，从而减少长响应或中断响应中的漂移。
**破坏性变更**
* `ConvaiSettings.DefaultMicrophoneIndex` 已替换为 `DefaultMicrophoneDeviceId` （字符串）——整数索引不会迁移；请在 设置 > 运行时默认值 中重新选择麦克风
* `ConvaiSettings.ServerUrl` 现在从 Environment 预设派生——序列化的 URL 仅在环境为 `Custom`
* 该 **Convai > 日志设置** 菜单已移除——日志配置位于 **Convai > 设置** （Diagnostics）
* `ConvaiRespondMode` 统一了响应模式术语（`ConvaiContextReactionMode` 已移除）——仅与针对未发布 beta 版本保存的场景相关
{% endupdate %}
{% update date="2026-06-23" tags="v4.3.0" %}
## v4.3.0
* **VAD 设置：** 可配置的连接时用户语音活动检测（VAD）设置用于房间连接，提供房间和配置文件的 Inspector 控件以及服务器默认值处理
* **动态上下文 v2：** 整合后的动态上下文流程，包含跟踪状态和事件、批处理、确认/结果事件，以及 `ConvaiDynamicContextRelay` 创作界面
* **世界对象上下文：** 同步的世界对象上下文会通过动态上下文发送跟踪到的场景元数据和当前焦点对象
* **叙事触发器：** 为已保存触发器、内联事件和脚本化语音提供独立的触发模式
* **转录 UI：** 用于空间 UI 配置的世界空间聊天转录预制体
* **动作：** 动作配置验证和重复绑定保留，并带有步骤诊断和动作调试探测
* **聊天输入：** 聊天输入的回车聚焦行为
**迁移说明**
* 动态上下文现在使用 v2 跟踪更新流程——请优先使用 `ConvaiCharacter.DynamicContext` 或 `ConvaiDynamicContextRelay` 而不是已移除的命令式动态上下文 UI
* 叙事触发请求现在携带明确的模式——请根据所需的后端行为使用已保存触发器、内联事件或脚本化语音
* 自定义 VAD 值仅在房间连接期间发送——当后端应负责 VAD 默认值时，请使用服务器默认选项
{% endupdate %}
{% update date="2026-05-08" tags="v4.2.0" %}
## v4.2.0
**动作系统**
角色可以通过结构化运行时执行场景内命令。本版本新增：
* `ConvaiActionDispatcher` 通过队列分发——动作按顺序执行，不会发生竞态条件
* `IConvaiActionExecutor` 自定义执行器接口
* 六个内置执行器：移动到（Transform 和 NavMesh）、拾取、注视、Animator 触发器和 UnityEvent
* 由 Inspector 驱动的配置——标准动作设置无需编写脚本
* 用于监控动作队列状态的运行时诊断
**Meta Quest 透视视觉**
`QuestVisionFrameSource` 无需外部摄像头即可在 Quest 3 和 Quest 3S 设备上启用 Vision 模块。在混合现实会话期间，角色可通过设备的透视摄像头查看。
**运行时轮流发言模式切换**
在实时会话期间使用以下方式在免提和按住说话模式之间切换： `ConvaiManager.SetConversationInputModeAsync()` 或运行时设置面板——无需重新加载场景。
**动态上下文扩展**
* 跟踪器 API 让你可以从脚本中监控当前上下文状态
* 用于无需代码编写上下文命令的 Inspector 工具
* `SampleDynamicContextUI` 预制体演示了运行时注入模式
**场景设置工具与验证**
通过菜单驱动的组件创建（**GameObject > Convai > Setup Required Components**）和场景验证（**GameObject > Convai > Validate Scene Setup**）可在进入 Play 模式前防止配置错误。
**设置面板输入模式控制**
运行时设置面板现在提供输入模式切换——玩家或开发者无需脚本即可在会话期间更改轮流发言模式。
{% endupdate %}
{% update date="2026-04-09" tags="v4.1.0" %}
## v4.1.0
* **动态上下文：** `ConvaiDynamicContextCommand` 组件可在运行时将状态和事件注入角色知识中
* **LipSync 示例：** 已从 LipSync 示例场景中移除对摄像机的依赖——可与任何摄像机设置配合使用
* **Vision 模块：** 提升了帧源生命周期和重连处理的可靠性
* **iOS：** 修复了首次访问麦克风时崩溃的问题，当 `NSMicrophoneUsageDescription` 未包含在构建设置中时
* **示例场景：** 改进了 Basic 和 LipSync 示例的设置与场景结构
* **编辑器：** 改善了包含大量场景的项目启动时间
{% endupdate %}
{% update date="2026-03-12" tags="v4.0.0,Initial Release" %}
## v4.0.0
Convai Unity SDK 的首次公开发布。
**核心组件：** `ConvaiManager`, `ConvaiRoomManager`, `ConvaiCharacter`, `ConvaiPlayer`
**会话管线：** 语音转文本、语言理解与生成、文本转语音——全部实时流式传输
**模块：** LipSync、Emotion、Vision、Narrative Design、Dynamic Context、Long-Term Memory、Scene Metadata、Dialogue Animation、Gaze 和 Attention
**平台支持：** Windows、macOS、Linux、Android、iOS、WebGL
**编辑器工具：** 场景设置、验证、项目设置集成以及 Convai 欢迎窗口
{% endupdate %}
{% endupdates %}
### 下一步
要开始使用该 SDK，请按照 Getting Started 操作。
{% content-ref url="/pages/5ea68df21c8a54f95779af92056a9ab831531be5" %}
[快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started.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/overview/release-notes.md?ask=&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.