> 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 在各版本中的变化，包括新功能、错误修复和配置更改。当前版本是 <code class="expression">space.vars.unity\_sdk\_version</code>.

{% 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`, `Proximity`，或 `手动`; `ConvaiManager.TalkTo(character)` 用于脚本化时刻显式指定对话对象
* 现在房间会打开在玩家正在看的角色上，而不是始终按场景顺序中的第一个角色。已指定的 **Convai Manager > Initial Character** 仍然优先生效，且控制台会说明它打开在谁身上以及原因
* 加入或离开已连接房间的角色会实时添加或移除，无需重新连接——实例化角色预制体，或启用一个角色 `游戏对象`，就是完整的集成方式。与单个角色连接的房间不包含成员列表，也不能实时扩展；控制台会说明这种情况以及应改用什么方式
* `ConvaiManager.Events` 新增 `OnConversationAvailabilityChanged`, `OnConversationTargetChanged` （含阶段 `Requested`, `Confirmed`, `Failed`），以及 `OnRoomRosterChanged`
* `Convai.ConfigureConversationTargeting` 加入 MCP 和 Unity Assistant 工具集，且 `Convai.DiagnoseConversation` 会报告成员列表、被指定角色以及目标定位裁决。工具契约版本 `7`
* 一个 **多角色示例** 与现有 Basic 和 LipSync 示例一同发布

**对话可用性**

* `ConvaiManager.ConversationAvailability` 回答玩家此刻是否可以交谈—— `Offline`, `Connecting`, `Preparing`, `就绪`, `Answering`, `Unavailable` ——针对 `ConvaiManager.AddressedCharacter`，以及 `ConversationAvailabilityChanged` 会报告每次变化，而 `CanAcceptPlayerInput()` 是 UI 提问所依据的问题。每个角色上也可通过 `ConvaiCharacter.ConversationAvailability`
* 现在，随附的聊天输入框、按住说话和免持输入都会检查这一状态。聊天输入框会在角色能够听见之前保持禁用，而 `ConvaiPlayer.TrySendTextMessage` 会给出原因供项目展示，而不是静默丢弃消息
* **行为变更：** 在多角色场景中，麦克风现在会在房间确认其第一个角色时打开，而不是在传输连接时打开——通常会晚几分之一秒。单角色房间不受影响

**注视**

* **听众关注** 在 Gaze 组件中现在会跟随对话主权——玩家、另一个角色或两者——只要角色还没轮到自己发言，这样在多于一名参与者的房间里，监听者会对正在说话的人作出反应，而不是呆在 `空闲`。配置文件的四个新设置在 **Conversation** 组中用于调整模型： **转向前的典型停顿**, **反应变化幅度**, **注意力衰减持续时长**以及 **听众开始转头之间的最短间隔**
* 现在，听众注意力是按参与者分别计算的：在有人开始说话时上升，并持续衰减，修复了听众晚转向、同时转向或转向错误对象的问题
* 头部和胸部现在会持续跟随移动目标，而不是分段跟随，从而消除了导致停驻式卡顿和鞭打式修正的死区。镜头切换现在会被视为普通视线变化，而不是惊跳反应。 **头部速度上限** 从 240°/秒降至 150°/秒，且 **转向速度（无转身动画的骨架）** 从 140°/秒降至 90°/秒——二者都是安全上限；已创建的配置文件会保留其已保存的值

**语音与性能**

* 在带 Lip Sync 的角色上，发言轮次现在会依据 lip sync 自身的帧数据结束，而不是等待静音检测器或服务确认，因此角色会在声音停止时停止表演，而不是最多晚两秒。 `ConvaiCharacter.IsSpeaking`, `OnSpeechStopped`以及 `OnTurnCompleted` 不受影响。Conversation Flow 配置文件带有一个 `stopWhenTheVoiceStops` 切换项用于旧的时序，但它默认开启且不会在配置文件 Inspector 中暴露，也不会通过公共 setter 暴露，因此新的时序会应用到每个角色
* 角色的嘴巴现在会在句尾自然闭合，而不是悬空张开或突然闭上：Lip Sync 组件上的新 **Settling 持续时间** （0.35 秒）通过基于弹簧的闭合来驱动，且 `LipSyncPlaybackEngine.SettleToRest()` 可从代码中触发它
* 当回应结束时，正在说话的手势不再会在动作中途冻结——手势现在会随着权重减弱而减速回到静止，从 **Talk Release Lead 秒** （0.6 秒）开始，早于回应实际结束之前
* lip sync 在会话中的第一次回应后不再卡住；此后每次回应现在都会带着活动嘴型播放，而不是静止嘴型
* `ConvaiCharacter.OnTranscriptReceived` 会触发。它之前读取的是服务不会发送的消息，所以在任何房间里都不会触发，而其下游的一切都会处于空转状态——凝视指涉、以及任何 `IConvaiCharacterBehavior` 对角色所说内容作出反应。现在它读取房间转录流，其 `isFinal` 参数来自消息自身的生命周期，而不是硬编码为 `否`，因此基于最终发言进行门控的消费者可以正常工作。两个结果：文本按句子到达，而不是按合成块到达；而且在句子稳定前就开始流式传输的行会被发送两次——一次中间态，一次最终态

**编辑器与 Inspector 工作**

* 中的多角色控制 **Convai Manager** Inspector 中的命名已为清晰起见而更改： *Include in Next Room* 现在是 **加入房间的角色**, *Within* 是 **范围（米）**, *Seen From* 是 **Player Camera**, *Scene Characters* 是 **场景中的角色数**以及 *Roster room* / *Single character* 是 **多个角色** / **仅一个角色**
* “ **Convai Manager** Inspector 的 Live 部分现在会显示当前正在被指定给谁、玩家是否能与其交谈，以及房间中每个角色的一行状态
* Character Inspector 现在会在 Play 模式前标记重复的 Character ID，而不是只在房间拒绝连接时才提示
* “ **Convai Player** 和 **Convai Room Manager** Validation 部分已重新设计，使用一个反映发现的最严重检查结果的标题，而不是永久显示琥珀色标题
* 每个 Convai Inspector 部分现在都共享同一种左边缘对齐和分区内边距系统

**Unity 6000.5 兼容性**

* 该包现在再次可在 Unity 6000.5 上编译。Unity 将场景标识迁移为 64 位 `EntityId`，以及弃用 `Object.GetInstanceID()`，现在都通过兼容层（`ConvaiSceneId`, `ConvaiObjectId`, `ConvaiObjectFind`）来处理，因此在 `6000.0` 通过 `6000.3` 上 ID 不变，并且与 `6000.4` 及之后版本中的旧 ID 保持一致

**包依赖项**

* `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°/秒` 移动到 `90°/秒`。现有配置文件保留其已保存的值——只有新配置文件会采用新默认值。要让现有配置文件采用新默认值，请手动设置这两个值
* **行为变更：** 在多角色场景中，麦克风现在会在房间确认其第一个角色时打开，而不是在传输连接时打开
  {% endupdate %}

{% update date="2026-08-14" tags="v4.5.0" %}

## v4.5.0

**角色具身**

五个行为模块现在在 **Add Component > 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 Editor** 窗口（**Convai > Actions Editor**）新增了可复用的 Action Set、场景知识、角色设置，以及带批量进度、时间线、目标注册表和按动作洞察的 Live 模式。 **Try It** 框可在 Edit 模式预览动作并在 Play 模式分发执行
* 新增四个内置执行器：Lead Player To Target、Scan Environment、Count Target Group 和 Measure Distance
* `ConvaiActionExecutionResult.Answered("…")` 允许动作提供一句角色可以说的话，与诊断信息分离 `消息`. **完成时** 可为每个动作编写此内容
* `ConvaiActionFailureReason` 在 `ConvaiActionExecutionResult` 和 `ConvaiActionStepReport`. `ConvaiActionParameterValue.Presence` 上报告带类型的失败原因，用于区分未填写的槽位与空白槽位。 `ConvaiActionDispatcher` 公开了 `IsBusy`, `PendingBatchCount`以及 `CurrentActionName`
* `ConvaiActionExecutorBase`, `ConvaiTargetedActionExecutor`以及 `ConvaiCharacterActionExecutor<TPeer>` 是自定义行为的基类。 `ConvaiPlayerBody` 现在是 public，并且 `ConvaiActionExecutorBase.ResolvePlayer()` 是 `virtual`，因此移动子胶囊体的第一人称骨架会解析到玩家的真实位置
* 对大量丢失和乱码命令情况的 Wire 解析已得到修正，而且场景中放置的 `ConvaiActionTarget` 现在可在会话中途与 Convai 同步

**身份验证**

* 认证现在是项目级选择，可在 API Key 模式与 Auth Token 模式之间切换。Auth Token 模式会从已配置的端点或一个 `IConvaiAuthTokenProvider` 在每次房间连接前解析出新的短期凭证，可用于 Native 和 WebGL 传输，并通过 `API-AUTH-TOKEN` 请求头发送该凭证，同时在保留 Editor 工具所需密钥的前提下，从玩家构建中移除已保存的账号 API key
* `ConvaiManager.ConnectWithAuthTokenAsync` 是一个一次性连接方式，适用于登录层已持有 Convai auth token 的项目。它还提供 `end_user_id` 和 `end_user_metadata.name` ，而无需注册 provider 或配置端点

**会话生命周期**

空闲警告和空闲截止事件， `ResetIdleTimer` 和 `ExtendIdleTimeout`，以及显式的暂停、继续和重新连接控制都可在运行时使用。后台行为通过 `ContinueAudibly`, `PauseTimeline`以及 `MuteButCatchUp` 策略设置，并提供一个可观察的 WebGL 回退方案，来自 `PauseTimeline` 移动到 `MuteButCatchUp`.

**编辑器工具**

* **Convai > Troubleshooter** 会按每个角色报告所有 Convai 能力的配置状态：已设置、被阻止，或已设置但无效，并提供一键修复和一个 **全部修复** 操作。可通过 `IConvaiSetupHealthProvider` 和 `ConvaiSetupHealthRegistry.Register`
* “ **Convai** 菜单已从 17 行缩减为 9 行——见下方破坏性变更与迁移
* 每个 Convai Inspector 和窗口都已迁移到共享编辑器设计系统，Character Rig Inspector 也已重写为以 Ready 或 Needs Attention 裁决开头，并显示分层检测置信度
* 打开包内随附的设置资源是只读的，并提供 **Create A Project Copy**，会将副本放到 `Assets/Convai/`

**需求与依赖项**

最低 Unity 版本为 `6000.0.80f1`。该包新增了三个依赖项： `com.unity.ai.navigation`, `com.unity.collections`以及 `com.unity.modules.xr`.

**LipSync、示例和平台**

* 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 组件迁移：** 替换 `ConvaiAttentionController`, `ConvaiGazeCoordinator`, `ConvaiHeadLookActuator`以及 `ConvaiEyeGazeActuator` 为单个 `ConvaiGazeController` (**Add Component > Convai > Embodiment > Gaze**）。删除你的 `ConvaiAttentionProfile`, `ConvaiGazeCoordinationProfile`, `ConvaiGazeEyeProfile`以及 `ConvaiGazeHeadProfile` 资源——这些类型已不存在，资源也将无法反序列化。调优值不会继承；请在 `ConvaiGazeProfile`上重新调优，或不指定并从默认值开始。将自定义的 `IFocusTargetProvider` 或 `IGazeIntentProvider` 与 `IGazeTargetProvider` 通过 `RegisterTargetProvider`, `ConvaiAttentionDynamicContextBridge` 与 `GazeDynamicContextBridge`以及 `ConvaiWorldObjectFocusProvider` 与 `ConvaiGazeTarget`替换。 `ConvaiWorldObjectFocusProvider` 在保存受影响场景之前先执行此操作，因为 Unity 会在下次保存时静默移除已删除组件
* **从 Dialogue Animation 迁移：** 替换 `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 > 身体动画编辑器**, **Convai > 情感编辑器**, **Convai > 凝视编辑器**, **Convai > 具身编辑器**；以及诊断—— **Convai > Troubleshooter**。该 `ConvaiConfigurationWindowEditor` 直接打开某个部分的方法仍然是 public
* **`UnityEventActionExecutor` 已重命名为 `ConvaiUnityEventActionExecutor` 并拥有新的 GUID。** Unity 不会迁移该组件：它会从所有包含它的场景和 prefab 中移除，连同其中绑定的事件一起被丢弃，且没有任何升级步骤能恢复它们。升级前请记录每个事件调用了什么。之后，在每个受影响的对象上添加 `ConvaiUnityEventActionExecutor` (**添加组件 > Convai > Actions > Raise Unity Event**) ，手动重新连接其事件，并重新指向任何绑定到旧组件的动作。序列化字段仍然是 `_onExecute`
* **三个实验性的动作执行器已从公开目录中移除：** Guided Tour、Address The Group 和 Perform Gesture At Target。 `LookAtTargetActionExecutor` 也已移除——请添加 `ConvaiLookAtActionExecutor` (**添加组件 > Convai > Actions > Look At Target**) 代替，并为角色添加 Gaze，因为替代方案通过 `ConvaiGazeController`。六个示例动作行为， `ConvaiActionTestSetup`以及 `ConvaiActionDebugWindow` 已移除；Actions Editor 已覆盖它们的功能
* **Point At Target 的 `保持秒数` 仅表示动作中间的暂停**，而不是整个手势的时长。现在有两个设置会影响指向层： **手势速度** 会放大上升和下降，且 **释放** 设置为 `混合` 在保持结束时放下姿势。两者默认与之前行为一致，因此现有场景无需更改；大约一秒的指向由 Gesture Speed `1.5` 配合 Release `混合`
* **十四种编辑器类型现在已 `internal`,** 其中包括 `ConvaiVisionBaseEditor`, `ConvaiCharacterEditor`以及 `TurnTakingOptionsDrawer`。不再支持继承 Convai 编辑器或属性绘制器，也没有替代的扩展点——请删除该子类，并通过单独的 `MonoBehaviour` 自定义实现来添加项目特定控件。 `[CustomEditor]` 注册不受影响，因此每个 Convai 检视器的绘制方式与之前相同
* **Emotion 模块的 slot-list 面部输出路径已移除：** `EmotionSlotBinding`, `BlendshapeEmotionBinding`, `AnimatorParameterEmotionBinding`, `RealisticEmotionSlots`, `NeutralAlternator`，以及 `SemanticExpressionsEnabled` 和 `NeutralAlternationEnabled` 开启 `ConvaiEmotionProfile`。只要启用语义表达，运行时就会丢弃这些数据，而所有已发布配置文件都启用了该功能，因此无需迁移任何内容。Shader 属性输出不受影响
* **共享的 Emotion 术语分类和配置资源已更名并变更身份。** `ConvaiSamplesShared_EmotionTaxonomy.asset` 已重建，且 `ConvaiSamplesShared_EmotionProfile.asset` 已被四个命名人格替代。打开每个受影响角色并重新指向术语分类和人格；没有术语分类的角色仍可运行，但所有情感下拉菜单都会为空
* **具身类型已重命名，但资源 GUID 保持不变：** `EmbodimentProfileReceiver<T>` 移动到 `ConvaiCharacterModule<T>`, `CharacterEmbodimentPreset` 移动到 `ConvaiEmbodimentPreset`, `EmbodimentPresetLibrary` 移动到 `ConvaiEmbodimentPresetLibrary`以及 `ConvaiCharacterEmbodimentBinding` 移动到 `ConvaiEmbodimentPresetBinding`。只需更新源码引用。 `EmbodimentContext` 将其按 seam 的注册成员替换为一个 `CharacterServiceRegistry` ——实现 `IEmbodimentTickable` 并调用 `EmbodimentContext.RegisterTickable(this)` 来自 `OnEnable` 以加入角色 tick。 `EmbodimentContext.TryResolve` 不再会在非 Convai 角色的 GameObject 上创建上下文；请调用 `TryResolveFor` 以获得可诊断的失败
* **`ActionResponsePayload` 以及公开的 `UnityObjectCompatibility` 类已移除。** 动作命令仍通过 `ConvaiCharacter.OnActionsReceived` 和 `ConvaiManager.Events.OnCharacterActionReceived`替换。 `UnityObjectCompatibility.FindObjectsByType<T>(mode)` 配合 Unity 的 `Object.FindObjectsByType<T>`以及 `UnityObjectCompatibility.GetId(value)` 与 `value.GetInstanceID()` 在 Unity 6000.4 及更早版本中，或 `value.GetEntityId()` 在 6000.2 及更新版本中
* **Camila 示例角色已移除。** 引用她的 prefab、材质或纹理的场景或 prefab 会报告缺失引用。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 保留旧版回退
* 通过移除不可用的伪模块依赖并固定 `com.unity.collections` 移动到 `2.6.8`，修复了 Unity 6.0 项目解析问题，避免了已知的 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` 回调，恢复了首轮 LipSync
  {% endupdate %}

{% update date="2026-07-21" tags="v4.4.0" %}

## v4.4.0

**规范转录时间线**

`ConvaiManager.Transcripts` 现在公开了按房间范围的 `TranscriptTimeline` ，由不可变的 `TranscriptTurn` 和 `TranscriptChange` 模型构建而成，取代了之前基于快照的契约。 `CurrentTimeline` 返回 `TranscriptTimeline` 而不是时间线快照， `已变更` 提供 `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`）会让新批次的第一个动作在执行前等待角色发言，并带有可选的 `机器人发言后延迟秒数` 暂停以及分发器级别的语音门限超时，这样沉默轮次也不会卡住批次

**AI 编码助手集成**

**Convai > AI 编码设置** 打开一个新的 Editor 部分，用于配置基于 Unity MCP 的 AI 编码辅助，支持 Codex、Claude Code、Cursor、Gemini 和 VS Code Copilot。专门的文档部分对该集成有完整说明。

**动态视觉上下文**

房间可以通过 `ConvaiRoomManager` 和 `ConvaiRoomManagerProfile`.

**Convai SDK 设置**

“ **Convai SDK** 项目设置页面（**Edit > Project Settings > Convai SDK**）以及 Editor 窗口的新 **Convai > 设置** 部分共享同一实现，涵盖 Setup Health、Credentials、Runtime Defaults、Diagnostics、Advanced 和 About。Credentials 增加了 API 密钥混淆，并可自动从明文迁移，提供 Environment 预设（Production、Beta 或 Custom），以及带缓存验证徽章的 Validate & Save 操作。

**LipSync**

播放对齐加固将 NeuroSync lipsync 锚定到语音开始的确切音频帧，从而减少长响应或中断响应中的漂移。

**破坏性变更**

* `ConvaiSettings.DefaultMicrophoneIndex` 已替换为 `DefaultMicrophoneDeviceId` （string）——整数索引不会迁移；请在 Settings > Runtime Defaults 中重新选择麦克风
* `ConvaiSettings.ServerUrl` 现在从 Environment 预设派生——序列化的 URL 仅在环境为 `Custom`
* “ **Convai > 日志设置** 菜单已移除——日志配置位于 **Convai > 设置** （诊断）
* `ConvaiRespondMode` 统一了应答模式术语（`ConvaiContextReactionMode` 已移除）——仅对基于未发布 beta 构建保存的场景相关
  {% endupdate %}

{% update date="2026-06-23" tags="v4.3.0" %}

## v4.3.0

* **VAD 设置：** 可配置的连接时用户语音活动检测（VAD）设置，用于房间连接，提供房间和配置文件的 Inspector 控件以及服务器默认值处理
* **动态上下文 v2：** 整合了带跟踪状态和事件的动态上下文流程、批处理、确认/结果事件，以及 `ConvaiDynamicContextRelay` 创作界面
* **世界对象上下文：** 同步的世界对象上下文会通过动态上下文发送已跟踪的场景元数据和当前焦点对象
* **叙事触发器：** 为已保存触发器、内联事件和脚本化语音提供独立的触发模式
* **转录 UI：** 用于空间 UI 设置的世界空间聊天转录 prefab
* **动作：** 动作配置验证和重复绑定保留，并提供步骤诊断和动作调试探测
* **聊天输入：** 聊天输入的按回车聚焦行为

**迁移说明**

* 动态上下文现在使用 v2 跟踪更新流程——请优先使用 `ConvaiCharacter.DynamicContext` 或 `ConvaiDynamicContextRelay` 而不是已移除的命令式动态上下文 UI
* 叙事触发请求现在带有明确模式——根据所需的后端行为使用已保存触发器、内联事件或脚本化语音
* 自定义 VAD 值仅在房间连接期间发送——当后端应接管 VAD 默认值时，请使用服务器默认选项
  {% endupdate %}

{% update date="2026-05-08" tags="v4.2.0" %}

## v4.2.0

**动作系统**

角色可以通过结构化运行时执行场景内命令。本版本新增：

* `ConvaiActionDispatcher` 支持队列派发——动作按顺序执行，不会产生竞态条件
* `IConvaiActionExecutor` 自定义执行器接口
* 六个内置执行器：move-to（Transform 和 NavMesh）、pick-up、look-at、Animator 触发器和 UnityEvent
* 由 Inspector 驱动的配置——标准动作设置无需编写脚本
* 用于监控动作队列状态的运行时诊断

**Meta Quest 透视视觉**

`QuestVisionFrameSource` 可在 Quest 3 和 Quest 3S 设备上启用 Vision 模块，无需外接摄像头。在混合现实会话期间，角色通过设备的透视摄像头看见外界。

**运行时轮流发言模式切换**

在实时会话中使用 `ConvaiManager.SetConversationInputModeAsync()` 或运行时 Settings Panel 在免提和按住说话模式之间切换——无需重新加载场景。

**动态上下文扩展**

* Tracker API 可让你从脚本中监控当前上下文状态
* 用于无需代码编写上下文命令的 Inspector 工具
* `SampleDynamicContextUI` prefab 演示运行时注入模式

**场景设置工具与验证**

通过菜单创建组件（**GameObject > Convai > Setup Required Components**）和场景验证（**GameObject > Convai > Validate Scene Setup**）可在进入 Play 模式前防止配置错误。

**设置面板输入模式控制**

运行时 Settings Panel 现在提供输入模式切换——玩家或开发者无需脚本即可在会话期间更改轮流发言模式。
{% 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

**编辑器工具：** 场景设置、验证、Project Settings 集成，以及 Convai 欢迎窗口
{% endupdate %}
{% endupdates %}

### 下一步

要开始使用该 SDK，请按照入门指南操作。

{% 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 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/overview/release-notes.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.