转录历史与查询

从代码中查询对话轮次时间线——读取已提交轮次、检测中断，并构建会话后导出或实时分析。

ConvaiManager.Transcripts 为你的代码提供对当前会话中每一次对话回合的结构化访问。订阅 已更改 以便在回合到达时作出响应，或者轮询 CurrentTimeline 以在任意时刻获得完整状态的一致快照。此 API 反映了运行时的状态管理，由 IRoomTranscriptEngine — 它不控制 UI 显示，也不会修改转录历史。

若要基于这些数据驱动视觉显示，请参见 转录 UI.

访问模式

订阅 已更改

ConvaiManager.Transcripts.Changed 每次时间线更新时都会触发。 TranscriptUpdateBatch 载荷告诉你具体发生了什么变化——新增回合、现有回合更新、回合完成以及回合中断——因此你无需对完整时间线做 diff 就能高效响应。

using Convai.Domain.Models;
using Convai.Runtime.Components;
using UnityEngine;

public class TranscriptReactor : MonoBehaviour
{
    private void OnEnable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed += OnTranscriptChanged;
    }

    private void OnDisable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed -= OnTranscriptChanged;
    }

    private void OnTranscriptChanged(TranscriptUpdateBatch batch)
    {
        foreach (string turnId in batch.CompletedTurnIds)
        {
            TranscriptTurnSnapshot turn = batch.Timeline.TurnsById[turnId];
            Debug.Log($"[{turn.Participant.DisplayName}] {turn.DisplayText}");
        }
    }
}

轮询 CurrentTimeline

ConvaiManager.Transcripts.CurrentTimeline 返回一个不可变的 TranscriptTimelineSnapshot — 在你调用时刻提供完整回合状态的一致视图。对于会话后导出、复盘界面或由游戏事件触发的一次性读取，请使用轮询。

public string BuildSessionReport()
{
    var timeline = ConvaiManager.ActiveManager.Transcripts.CurrentTimeline;
    var sb = new System.Text.StringBuilder();

    foreach (TranscriptTurnSnapshot turn in timeline.CommittedTurns)
        sb.AppendLine($"[{turn.StartedAtUtc:HH:mm:ss}] {turn.Participant.DisplayName}: {turn.DisplayText}");

    return sb.ToString();
}

核心数据结构

ConvaiTranscripts — 门面

通过以下方式访问 ConvaiManager.Transcripts。在 ConvaiManager 初始化后，所有成员都可用。

成员	类型	说明
CurrentTimeline	TranscriptTimelineSnapshot	当前完整回合时间线的不可变快照
已更改	event Action<TranscriptUpdateBatch>	每当时间线变化时触发
GetTurns(TranscriptQuery)	IReadOnlyList<TranscriptTurnSnapshot>	带可选筛选条件查询回合
GetTurn(string turnId)	TranscriptTurnSnapshot	通过回合 ID 快速查找
GetLatestTurn(TranscriptParticipantRef)	TranscriptTurnSnapshot	特定参与者的最新回合

TranscriptTimelineSnapshot

整个房间范围内的不可变快照。每个字段都是集合；都可以安全迭代，无需空值检查。

属性	类型	说明
ActiveTurns	IReadOnlyList<TranscriptTurnSnapshot>	当前正在进行中的回合（Streaming 或 Stable）
CommittedTurns	IReadOnlyList<TranscriptTurnSnapshot>	按房间顺序排列的已完成回合
TurnsById	IReadOnlyDictionary<string, TranscriptTurnSnapshot>	通过以下项快速查找 TurnId — 包括进行中和已提交的回合
LatestTurnByParticipant	IReadOnlyDictionary<string, TranscriptTurnSnapshot>	按以下键索引的最新回合 ParticipantId
光标	long	单调递增计数器。可用于检测自上次读取以来时间线是否发生变化。

TranscriptTurnSnapshot

表示来自单一参与者的一段连续语音。不可变——每次更新都会生成一个新的快照。

属性	类型	说明
TurnId	string	此回合的稳定标识符。也可作为 MessageId
RoomSequence	long	房间会话内的单调排序位置
参与者	TranscriptParticipantRef	谁产生了此回合（见下文）
StartedAtUtc	DateTime	回合开始的 UTC 时间
LastUpdatedAtUtc	DateTime	此回合最近一次更新的 UTC 时间
CompletedAtUtc	DateTime?	回合最终完成的 UTC 时间。 null 在仍处于活动状态时
生命周期	TranscriptLifecycle	当前稳定性状态（Streaming / Stable / Completed）
CommittedText	string	转录中最终确认的部分
InterimText	string	当前部分内容（尚未确认）
DisplayText	string	拼接自 CommittedText + InterimText — 用于显示
WasInterrupted	bool	true 如果该回合被其他发言者打断而提前结束
HasText	bool	true 如果 DisplayText 包含非空白内容
ConversationTargetCharacterId	string	此玩家回合所面向的角色（仅适用于玩家回合）
Segments	IReadOnlyList<TranscriptSegmentSnapshot>	回合内按顺序排列的子片段（高级用法）

TranscriptParticipantRef

附加到每个 TranscriptTurnSnapshot.

属性	类型	说明
类型	TranscriptParticipantKind	玩家 或 角色
PlayerOrCharacterId	string	玩家或角色的稳定 SDK 标识符
DisplayName	string	在转录 UI 中显示的人类可读名称
ParticipantId	string	房间范围内的参与者标识符（适用于多人房间）
IsEmpty	bool	true 如果 PlayerOrCharacterId 为 null 或空白字符

TranscriptLifecycle

描述在给定时间点回合文本的稳定程度。

值	说明
流式传输	文本正在主动变化——临时语音识别结果不断到达
稳定	此时点的文本已锁定，但回合仍未结束
已完成	回合已完全完成——不会再有后续更新

TranscriptUpdateBatch

传递给 已更改 订阅者的载荷。描述自上一批次以来发生了什么变化。

属性	类型	说明
时间线	TranscriptTimelineSnapshot	此批次后的完整时间线状态
光标	long	此批次后的时间线光标
已更改回合	IReadOnlyList<TranscriptTurnSnapshot>	所有已更改回合的完整回合快照
新增回合 ID	IReadOnlyList<string>	自上一批次以来新增的回合 ID
已更新回合 ID	IReadOnlyList<string>	已更新的回合 ID（文本已变化）
已完成回合 ID	IReadOnlyList<string>	已转换为以下状态的回合 ID： 已完成
被中断回合 ID	IReadOnlyList<string>	其中回合 ID WasInterrupted 变为 true
已移除回合 ID	IReadOnlyList<string>	从时间线中移除的回合 ID

筛选回合，使用 TranscriptQuery

传入一个 TranscriptQuery 到 GetTurns() 以检索时间线的子集。所有字段都是可选的——省略某个字段会禁用对应筛选条件。

字段	类型	默认值	说明
参与者类型	TranscriptParticipantKind?	null （任意）	仅限于 玩家 或 角色 回合
PlayerOrCharacterId	string	null （任意）	按 ID 限定为特定玩家或角色
ParticipantId	string	null （任意）	按房间范围内的参与者 ID 限定（多用户）
包含活动回合	bool	true	结果中包含进行中的回合
包含已提交回合	bool	true	结果中包含已完成的回合

示例——所有已提交的角色回合：

var query = new TranscriptQuery
{
    ParticipantKind = TranscriptParticipantKind.Character,
    IncludeActiveTurns = false,
    IncludeCommittedTurns = true
};

IReadOnlyList<TranscriptTurnSnapshot> characterTurns =
    ConvaiManager.ActiveManager.Transcripts.GetTurns(query);

使用示例

会话后报告——导出已提交回合

企业入职模拟会在受训者完成入职对话后生成一份会话转录：

using Convai.Domain.Models;
using Convai.Runtime.Components;
using System.Text;
using UnityEngine;

public class SessionReporter : MonoBehaviour
{
    public string GenerateReport()
    {
        var timeline = ConvaiManager.ActiveManager.Transcripts.CurrentTimeline;
        var sb = new StringBuilder();
        sb.AppendLine("=== 会话转录 ===");

        foreach (TranscriptTurnSnapshot turn in timeline.CommittedTurns)
        {
            string speaker = turn.Participant.Kind == TranscriptParticipantKind.Character
                ? $"[AI] {turn.Participant.DisplayName}"
                : $"[受训者] {turn.Participant.DisplayName}";

            sb.AppendLine($"{turn.StartedAtUtc:HH:mm:ss}  {speaker}: {turn.DisplayText}");
        }

        return sb.ToString();
    }
}

在运行时，调用 GenerateReport() 在会话结束后生成带时间戳、按顺序排列的转录，供受训者或主管审阅。

实时分析——跟踪玩家词数

一项沟通技巧模拟会实时跟踪受训者说了多少词，并在对话进行时在复盘 HUD 上更新实时计数器：

using Convai.Domain.Models;
using Convai.Runtime.Components;
using UnityEngine;
using TMPro;

public class WordCountTracker : MonoBehaviour
{
    [SerializeField] private TMP_Text _wordCountLabel;

    private void OnEnable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed += OnTranscriptChanged;
    }

    private void OnDisable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed -= OnTranscriptChanged;
    }

    private void OnTranscriptChanged(TranscriptUpdateBatch batch)
    {
        bool playerTurnChanged = false;
        foreach (TranscriptTurnSnapshot turn in batch.ChangedTurns)
        {
            if (turn.Participant.Kind == TranscriptParticipantKind.Player)
            {
                playerTurnChanged = true;
                break;
            }
        }

        if (!playerTurnChanged) return;

        int wordCount = 0;
        var query = new TranscriptQuery { ParticipantKind = TranscriptParticipantKind.Player };

        foreach (TranscriptTurnSnapshot turn in ConvaiManager.ActiveManager.Transcripts.GetTurns(query))
            wordCount += turn.DisplayText.Split(' ', System.StringSplitOptions.RemoveEmptyEntries).Length;

        _wordCountLabel.text = $"已说词数：{wordCount}";
    }
}

中断检测——训练评分扣分

客户服务培训模拟会在 AI 角色的回合被中断时对受训者进行扣分——这表示受训者插话盖过了讲师：

using Convai.Domain.Models;
using Convai.Runtime.Components;
using UnityEngine;

public class InterruptionDetector : MonoBehaviour
{
    [SerializeField] private string _instructorCharacterId;
    private int _interruptionCount;

    private void OnEnable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed += OnTranscriptChanged;
    }

    private void OnDisable()
    {
        ConvaiManager.ActiveManager.Transcripts.Changed -= OnTranscriptChanged;
    }

    private void OnTranscriptChanged(TranscriptUpdateBatch batch)
    {
        foreach (string turnId in batch.InterruptedTurnIds)
        {
            if (!batch.Timeline.TurnsById.TryGetValue(turnId, out var turn)) continue;
            if (turn.Participant.PlayerOrCharacterId != _instructorCharacterId) continue;

            _interruptionCount++;
            Debug.Log($"检测到中断。总计：{_interruptionCount}");
        }
    }

    public int GetInterruptionCount() => _interruptionCount;
}

故障排查

症状	可能原因	修复
ConvaiManager.Transcripts 是 null	ConvaiManager 尚未初始化	在 OnEnable 中订阅并检查 ConvaiManager.IsBootstrapped 在访问之前
已更改 从不触发	未订阅，或在会话结束后才订阅	在 OnEnable 在房间连接之前；在 OnDisable
CommittedTurns 会话期间为空	会话尚未开始，或所有回合仍处于活动状态	检查 ActiveTurns 在活动对话期间； CommittedTurns 会随着回合完成而填充
GetTurns() 使用筛选条件时返回 0 个结果	PlayerOrCharacterId 或 ParticipantId 与任何参与者都不匹配	日志 turn.Participant.PlayerOrCharacterId 从 已更改 处理程序中查找正确的 ID
WasInterrupted 从不 true	会话未使用多说话者模式	WasInterrupted 当一位说话者与另一位重叠时，由运行时设置——请确认已配置多说话者。

下一步

你现在已拥有对房间转录时间线的完整读取权限。若要在场景中显示这些数据，请参见 Transcript UI。若要配置运行时启用的视觉模式，请参见 Settings Panel。

转录 UI设置面板