> 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/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md).

# 聊天和字幕模式

向场景中添加可滚动的聊天历史、实时字幕或两者，并配置每种转录显示的外观和行为。

`ConvaiManager.ActiveManager.Transcripts` (`ConvaiTranscripts`）提供对话的两个独立视图：与实时语音同步的字幕，以及持久化的轮次历史记录。本页介绍如何添加 `SubtitleTranscriptUI` 以显示字幕， `ChatTranscriptUI` 以显示历史记录，或同时添加两者——它们都从同一个 facade 读取数据并独立更新，因此添加其中一个不会移除或替换另一个。

### 选择所需的投影

| 投影  | Facade 成员                                                                 | 使用方                           | 适用场景                           |
| --- | ------------------------------------------------------------------------- | ----------------------------- | ------------------------------ |
| 字幕  | `CurrentCaptions`, `CaptionsChanged`, `SubscribeCaptions(...)`            | `SubtitleTranscriptUI` （参考脚本） | 低延迟、与语音同步的文本。临时内容——不会存储为聊天历史记录 |
| 时间线 | `CurrentTimeline`, `Changed`, `Subscribe(...)`, `SubscribeCommitted(...)` | `ChatTranscriptUI` （内置组件）     | 持久化、可滚动的对话历史记录，适用于查看、回放或导出     |

没有单一的模式开关可以启用一种投影并禁用另一种。自定义组件可以直接从 `ConvaiManager.ActiveManager.Transcripts` 订阅任一投影或同时订阅两者：

```csharp
using System;
using Convai.Domain.Models;
using Convai.Runtime.Components;
using UnityEngine;

public class TranscriptProjectionExample : MonoBehaviour
{
    private IDisposable _captionSubscription;
    private IDisposable _historySubscription;

    private void OnEnable()
    {
        if (!ConvaiManager.ActiveManager.TryGetTranscripts(out ConvaiTranscripts transcripts)) return;

        // 用于屏幕字幕的低延迟字幕
        _captionSubscription = transcripts.SubscribeCaptions(OnCaption);

        // 用于可滚动聊天记录的持久化轮次历史
        _historySubscription = transcripts.Subscribe(
            OnHistoryChange,
            new TranscriptSubscriptionOptions { ReplayExisting = true });
    }

    private void OnDisable()
    {
        _captionSubscription?.Dispose();
        _historySubscription?.Dispose();
    }

    private void OnCaption(TranscriptCaption caption) { /* update subtitle text */ }
    private void OnHistoryChange(TranscriptChange change) { /* update chat bubble */ }
}
```

这两个随附的显示组件也会遵循 `ConvaiTranscripts.IsPresentationEnabled`。当设置面板中的 `Transcript` 开关关闭，或 `ConvaiRuntimeSettingsPatch` 将 `TranscriptEnabled = false`, `ChatTranscriptUI` 和 `SubtitleTranscriptUI` 都会停止渲染，但 `CurrentTimeline` 仍会继续记录。关闭显示不会丢弃历史记录。

### 添加聊天历史记录显示

`ChatTranscriptUI` 会在可滚动列表中将每轮对话显示为一个消息气泡，角色和玩家的对话分别位于不同列中。对话流式传输期间，气泡会实时更新；对话提交后，气泡内容便会固定。

{% stepper %}
{% step %}

#### 将预制件添加到场景中

将 `TranscriptUI_Chat.prefab` 拖入场景。该文件位于软件包中的 `Prefabs/TranscriptUI/TranscriptUI_Chat.prefab` 。预制件自带 <code class="expression">space.vars.sdk\_package\_id</code> 一个 `Canvas` ，请勿将其嵌套在现有的 `Canvas`.

`中。` ChatTranscriptUI 会自动查找 `ConvaiManager.ActiveManager` ，并在找到后调用 `Subscribe(...)` 订阅 `ConvaiManager.ActiveManager.Transcripts` 。无需手动注册。
{% endstep %}

{% step %}

#### 确保场景中存在 EventSystem

聊天输入字段需要场景中存在一个 `EventSystem` 。如果场景中没有，请通过以下菜单添加： **游戏对象 → UI → 事件系统**.
{% endstep %}

{% step %}

#### 运行场景

连接到角色并开始说话。角色语音会显示在一列气泡中，玩家语音则显示在另一列中，面板会自动滚动到最新消息。
{% endstep %}
{% endstepper %}

#### `ChatTranscriptUI` 检查器字段

| 字段                       | 说明                                         |
| ------------------------ | ------------------------------------------ |
| `scrollRect`             | `ScrollRect` 包含消息列表的 ScrollRect。自动滚动需要此字段。 |
| `chatContainer`          | `RectTransform` 消息气泡 GameObject 所属的父对象     |
| `characterMessagePrefab` | 每个角色回合实例化的预制件                              |
| `playerMessagePrefab`    | 每个玩家回合实例化的预制件                              |
| `chatInputField`         | 可选 `TMP_InputField` 用于输入文本                 |
| `fadeDuration`           | 面板淡入/淡出动画的秒数（默认值 `0.5`)                    |
| `canvasFader`            | `CanvasFader` 用于驱动淡入淡出动画                   |
| `canvasGroup`            | `CanvasGroup` 用于控制淡入淡出期间的交互状态              |

#### `ChatMessageBubble` 检查器字段

每个消息气泡预制件的根对象上都必须包含一个 `ChatMessageBubble` 组件：

| 字段          | 说明                          |
| ----------- | --------------------------- |
| `senderUI`  | `TextMeshProUGUI` 用于显示发言者名称 |
| `messageUI` | `TextMeshProUGUI` 用于显示转录文本  |

`ChatTranscriptUI` 会使用角色配置的 `NameTagColor` （来自 `ConvaiCharacter` 或其角色配置资源）为角色气泡中的发言者名称着色。若要通过脚本覆盖此颜色，请调用 `bubble.SetSenderColor(Color)`.

调用 `ChatTranscriptUI.ClearAll()` 可销毁所有已渲染的消息气泡并重置面板。这只会清除视觉显示，不会影响 `ConvaiManager.ActiveManager.Transcripts.CurrentTimeline` 中的底层回合历史记录。有关注意事项，请参阅 [转录 UI — 清除转录显示](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md#clear-the-transcript-display) 一节。

### 添加字幕

`SubtitleTranscriptUI` 会在固定位置显示一段文本，由 `SubscribeCaptions`驱动。字幕定稿后，文本会在可配置的延迟时间后自动隐藏。

{% hint style="warning" %}
`SubtitleTranscriptUI` 仅作为脚本提供，没有配套预制件。它是一个位于 `SamplesShared`；修改前请先将其复制到自己的程序集，因为 `SamplesShared` SDK 更新时会覆盖脚本。
{% endhint %}

{% stepper %}
{% step %}

#### 将脚本添加到 UI 游戏对象

将 `SubtitleTranscriptUI` （来自 `Scripts/UI/Transcript/Subtitle/SubtitleTranscriptUI.cs` ，位于 `SamplesShared`）添加到一个 `GameObject` （位于 `Canvas`下）。创建或复用两个 `TMP_Text` 元素，分别用于字幕正文和说话者名称；另外添加一个容器 `GameObject` 以切换显示状态。
{% endstep %}

{% step %}

#### 连接检查器字段

为 `subtitleText`, `、`和 `subtitleContainer`赋值。若要使用淡入淡出过渡效果，请添加 `CanvasFader` 和 `CanvasGroup` 。
{% endstep %}

{% step %}

#### 运行场景

进行对话，或让角色说话。字幕会淡入，在对话轮次流式传输期间逐词更新，并在该轮次结束后 `autoHideDelay` 秒隐藏。
{% endstep %}
{% endstepper %}

#### `SubtitleTranscriptUI` 检查器字段

| 字段                  | 默认值   | 说明                             |
| ------------------- | ----- | ------------------------------ |
| `subtitleText`      | —     | `TMP_Text` 用于显示字幕正文            |
| `speakerLabel`      | —     | `TMP_Text` 用于显示说话者名称           |
| `subtitleContainer` | —     | `GameObject` 包含两个文本元素，并切换其显示状态 |
| `fadeDuration`      | `0.3` | 淡入/淡出动画的持续秒数                   |
| `canvasFader`       | —     | `CanvasFader` 用于驱动淡入淡出动画       |
| `canvasGroup`       | —     | `CanvasGroup` 用于控制交互状态         |
| `autoHideDelay`     | `3.0` | 字幕结束后等待多少秒再隐藏                  |

**筛选条件：**

| 字段                    | 默认值         | 说明                                                                                          |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------- |
| `finalOnly`           | `false`     | 当 `true`时，仅显示已定稿的字幕；跳过流式文本                                                                  |
| `filterBySpeakerType` | `false`     | 当 `true`时，将字幕限制为 `speakerType`                                                              |
| `speakerType`         | `Character` | `TranscriptSpeakerType` ，以便在 `filterBySpeakerType` 启用时进行筛选（`Player`, `Character`或 `System`) |
| `speakerIdFilter`     | —           | 将字幕限制为特定的说话者 ID                                                                             |
| `participantIdFilter` | —           | 将字幕限制为特定的房间参与者 ID（多用户房间）                                                                    |

**说话者标签颜色：** 角色发言 — 青色；玩家发言 — 绿色。

### 为聊天消息添加反馈按钮

聊天气泡可以包含赞成/反对反馈按钮，让用户为各条 AI 回复评分。

{% stepper %}
{% step %}

#### 将 FeedbackButtons 添加到气泡预制件

添加 `FeedbackButtons.prefab` 作为子对象添加到角色消息气泡预制件中。可在此处找到： `Prefabs/TranscriptUI/FeedbackButtons.prefab` 位于 <code class="expression">space.vars.sdk\_package\_id</code> 包中。该预制件包含反馈按钮的视觉元素和一个 `FeedbackHandler` 组件。
{% endstep %}

{% step %}

#### 允许用户为消息评分前，先设置交互 ID

调用 `ChatMessageBubble.SetInteractionID(string)` 为你想要启用评分的轮次设置交互 ID。可以从以下事件获取交互 ID： `ConvaiManager.ActiveManager.Events.OnInteractionCreated` (`InteractionCreated.InteractionId`，以 `CharacterId`).
{% endstep %}

{% step %}

#### 运行场景

使用赞成/反对按钮为角色回复评分。选中的按钮会高亮显示；另一个按钮则会停用。 `FeedbackHandler.ResetState()` 调用时会将两个按钮重置为未选中状态。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
当前发布的组件中，没有组件会调用 `ChatMessageBubble.SetInteractionID(string)` 自动执行。在你的代码针对某一轮调用它之前， `ChatMessageBubble.SendFeedback(bool)` 会返回 `false` ，且该消息对应的按钮不会高亮。
{% endhint %}

#### `ChatMessageBubble` 反馈 API

| 方法                                               | 说明                                                               |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `SetInteractionID(string interactionID)`         | 必须先设置，才能为此气泡发送反馈                                                 |
| `SetAgentRegistry(IAgentRegistry agentRegistry)` | 角色查找所必需。由 `ChatTranscriptUI`                                     |
| `bool SendFeedback(bool isPositiveFeedback)`     | 返回 `true` （如果 `interactionID` 已设置，且在智能体注册表中找到该角色）。否则返回 `false` 。 |

`FeedbackHandler.ResetState()` 会停用正向和负向按钮的填充视觉效果，使按钮恢复到中性状态。反馈按钮仅适用于角色消息气泡——玩家气泡不会收到交互 ID。

### 使用示例

#### 安全培训——用于课后复盘的聊天记录

一款职场安全培训模拟应用使用聊天记录，让学员在完成情景模拟后回顾 AI 指导员的完整对话：

* 将 `TranscriptUI_Chat.prefab` 拖入场景中的 `Canvas`
* 将 `fadeDuration` 设置 `0.3` 为某个值，以便在情景模拟进行期间实现灵敏的过渡效果
* 在新情景开始时调用 `ChatTranscriptUI.ClearAll()` ，避免遗留消息延续到新情景中

运行时，学员可以查看 AI 指导员所说内容的完整记录，并在复盘时滚动浏览，然后进入下一个模块。

#### 医疗模拟——用于简洁叠加层的字幕

一款医疗操作模拟应用使用字幕，让 AI 患者的语音以简洁的叠加层显示在患者模型上方，同时不遮挡屏幕上的临床读数：

* 添加 `SubtitleTranscriptUI` 并将 `subtitleContainer` 锚定在底部中央
* 将 `autoHideDelay` 设置 `2.0` 为某个值——患者每次作答后快速清除字幕，保持屏幕整洁
* 保留 `filterBySpeakerType` 关闭，这样患者和实习医生的发言都会显示为字幕

运行时，每条患者回复都会短暂显示为字幕，并在不累积历史记录的情况下清除，让整个操作过程中模拟界面保持简洁。

#### 博物馆互动展台——字幕和对话历史同时运行

自然历史博物馆为访客设置了一块展览屏幕，并为讲解员设置了一个独立的回顾工作站；两者由同一段对话驱动：

* 将 `SubtitleTranscriptUI` 添加到展览屏幕的 `Canvas`中， `filterBySpeakerType` 设为启用，并将 `speakerType` 设为 `Character`，这样只有展览角色的发言会显示为字幕
* 将 `TranscriptUI_Chat.prefab` 添加到讲解员工作站的 `Canvas`
* 两者都从同一个 `ConvaiManager.ActiveManager.Transcripts` 读取数据并独立更新——无需针对不同模式进行配置

运行时，访客在展览区看到持续滚动的简洁字幕，而讲解员工作站则累积完整对话，供其回顾；这一切都来自同一个会话。

### 故障排查

| 症状                                                                             | 可能原因                                                | 解决方法                                                                                                             |
| ------------------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `[ChatTranscriptUI] chatContainer is not assigned - messages will not display` | `chatContainer` 未在 Inspector 中连接                    | 将消息气泡应挂载到的 `RectTransform` 分配给该字段                                                                                |
| `[ChatTranscriptUI] scrollRect is not assigned - auto-scroll will not work`    | `scrollRect` 未在 Inspector 中连接                       | 分配 `ScrollRect` 组件；自动滚动不会生效，但消息气泡仍会显示                                                                            |
| `[ChatTranscriptUI] No active ConvaiManager found.`                            | `ConvaiManager` 缺失或尚未初始化                            | 将 `ConvaiManager` 添加到场景中，并确认它在此组件查找之前已完成初始化                                                                      |
| `[ChatTranscriptUI] Cannot send message - dependencies not injected`           | 依赖注入前输入到 `chatInputField` 中的文本                      | 确保 `ConvaiManager` 和一个 `ConvaiPlayer` 已存在于场景中并完成初始化                                                              |
| `[SubtitleTranscriptUI] No active ConvaiManager found.`                        | 与上文原因相同，但针对字幕脚本                                     | 将 `ConvaiManager` 添加到场景中                                                                                         |
| 字幕始终不显示                                                                        | 场景中没有组件调用 `SubscribeCaptions` ，或者字幕说话者与配置的筛选条件不匹配   | 添加 `SubtitleTranscriptUI`，确认已分配其 `TMP_Text` 字段，并检查 `filterBySpeakerType`/`speakerIdFilter`/`participantIdFilter` |
| 聊天和字幕显示均未更新                                                                    | `ConvaiTranscripts.IsPresentationEnabled` 为 `false` | 检查设置面板中的 `Transcript` 开关，或通过 `TranscriptEnabled = true` 应用 `ConvaiRuntimeSettingsPatch`                          |
| 反馈按钮始终不高亮                                                                      | `SendFeedback` 返回 `false`                           | 确认代码针对该轮对话调用了 `ChatMessageBubble.SetInteractionID(string)` ——没有任何随附组件会自动执行此操作                                    |

### 后续步骤

你已添加聊天记录显示、字幕，或两者都已添加，并为聊天消息接入了反馈按钮。若要自定义气泡的视觉外观或构建完全自定义的转录内容显示，请参阅“自定义 UI 组件”。若要允许用户在运行时显示或隐藏转录内容，请参阅“设置面板”。

{% content-ref url="/pages/5f60eaa8d444f5ee8a995392852da827736d3b54" %}
[自定义 UI 组件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/customizing-ui-components.md)
{% endcontent-ref %}

{% content-ref url="/pages/dddf624ca0ae7ec32afa0c9e601f2cb7c7ab2b6a" %}
[设置面板](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.md)
{% endcontent-ref %}

{% content-ref url="/pages/b846767a1ed5a04b3cfb93646c3c8472baf91067" %}
[转录历史与查询](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/transcript-history-and-queries.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/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.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.
