「律动律政（Legal Canvas）」——全语音 3D 具身交互智能AI 庭审质询与抗辩演练系统

lialaka

260人浏览 · 2026-07-24 16:23:37

lialaka · 2026-07-24 16:23:37 发布

「律动律政（Legal Canvas）」——全语音 3D 具身交互智能AI 庭审质询与抗辩演练系统

7-5律动律政数字人-视频演示

一、项目背景与痛点

传统的法律实务培训长期依赖"模拟法庭"线下场景——由真人扮演法官、控辩双方进行对抗演练。这种模式存在三大痛点：一是陪练师资稀缺，难以随时开展高频演练；二是缺乏即时反馈，学员无法量化自己的抗辩表现；三是场景单一，难以模拟高压、刁钻的真实质询节奏。

与此同时，主流的语音交互产品大多采用"半双工"模式——用户说一句，必须等 AI 完全回答完毕后才能说下一句，交互体验类似对讲机。在法庭质询这种信息密度极高、攻防节奏极快的场景下，半双工的迟滞感尤为致命：当"对方律师"正在长篇陈述时，学员根本无法随时插话提出异议或追问。

为了解决上述痛点，本项目「律动律政（Legal Canvas）」基于魔珐星云（XmovAvatar）3D 数字人 SDK，构建了一位资深诉讼大律师 Harvey 的全语音 3D 具身交互智能数字人AI 形象。系统支持全双工实时交互，学员可随时打断 Harvey 的质询并提出抗辩，实现真正的庭审攻防双向对话，并实时量化抗辩胜率与心流指数。

作为一名代码基础较弱的开发者，本次开发全程通过 AI Coding 工具辅助，结合魔珐星云底层 SDK 的 API，几乎由 AI 辅助完成了全部的核心链路。本文将从技术架构、全双工状态机、VAD 防抖控流以及核心交互逻辑四个维度，分享整个开发流程与踩坑经验。

二、核心技术亮点与架构

本系统在前端和交互控流层主要实现了以下几个技术要点：

魔珐星云 SDK 接入与 3D 形象渲染：通过 XmovAvatar 构造器传入 containerId、appId、appSecret、gatewayServer 与 config.layout（含容器尺寸与数字人缩放比例），并调用 init({ initModel: 'normal', onDownloadProgress }) 完成形象资源下载与初始化。配合 hardwareAcceleration: "prefer-hardware" 与 enableClientInterrupt: true，保障渲染流畅并支持客户端打断。
四态有限状态机管理：系统维护 idle | listening | processing | speaking 四种核心交互状态。通过状态机平滑切换，保障数字人语音、波形动画与庭审笔录的丝滑同步，并严格管控 ASR 的启停时机。
VAD 防抖端点检测替代 ****onaudioend：由于 Web Speech API 在 continuous: true 模式下 onaudioend 不会在每次 final result 后触发，系统改用 800ms 防抖定时器作为 VAD 端点，连续说话时积累文本，停顿超过阈值后统一投递大模型。
低延迟全双工打断机制：结合前端回声消除（文本相似度阈值 0.55）与 SDK 的 interrupt 接口，用户可在 Harvey 质询过程中随时插话，系统毫秒级中止当前播报并进入新一轮倾听。
大模型流式控流：大模型通过 SSE 流式输出，前端配合 SDK 的 speak 方法进行逐句缓冲与播报，降低首字响应延迟。
启动期最小显示时长保障：全屏 Loading 遮罩在数字人资源命中缓存、加载极快时，通过缓出动画将进度平滑过渡至 100%，确保加载过程至少可见 1.2 秒，避免一闪而过。

三、核心功能与交互效果展示

1. 核心交互体验：随时打断质询

Harvey 大律师正在对学员进行高压质询时，学员可随时开口提出异议或追问。系统通过 ASR 实时监测用户语音，一旦检测到插话，立即执行以下链路：

回声消除校验 -> 调用 SDK 打断接口中止当前播报 -> 自动切换至倾听状态 -> VAD 防抖积累完整抗辩文本 -> 投递大模型 -> Harvey 重新质询。

在这里插入图片描述

2. 3D 多模态联动与沉浸式法庭氛围

全屏入庭 Loading：点击"开庭聆讯"后，展示符合法庭主题风格的全屏遮罩，含旋转天平图标、圆形进度环、线性进度条与分阶段状态文案（"正在建立法庭连接…"→"正在下载数字人形象资源…“→"Harvey 大律师已就位”），数字人完全加载完毕后才进入主界面。
庭审笔录实时同步：右侧面板实时显示双方对话，识别中的 interim 文本以半透明斜体 + 闪烁光标呈现，final 文本落定后正式入卷，并自动滚动。
抗辩数据看板：底部实时计算"抗辩胜率"与"心流指数"，基于法律术语命中率、质询轮次等维度量化演练表现。
天平重力模拟：启动页天平随鼠标位置倾斜，但托盘通过嵌套反向旋转始终垂直悬挂，模拟真实重力效果。

在这里插入图片描述

四、全双工打断与 VAD 防抖的底层控制流实现

全双工交互的核心难点在于状态流转的时序控制与端点检测的可靠性。以下是系统在检测到用户插话时的完整控流逻辑：

// 核心逻辑：onresult 中的 VAD 防抖与回声消除
recognition.onresult = (event) => {
    let finalTranscript = '', interimTranscript = '';
    for (let i = event.resultIndex; i < event.results.length; i++) {
      if (event.results[i].isFinal) finalTranscript += event.results[i][0].transcript;
      else interimTranscript += event.results[i][0].transcript;
    }
    // 1. 实时显示 interim 识别结果
    if (interimTranscript.trim() && S.currentPhase === 'listening') {
      showInterimDisplay(interimTranscript.trim());
    }
    if (!finalTranscript.trim()) return;

    // 2. 回声消除：数字人正在说话时，比对识别文本与 Harvey 上一句台词的相似度
    if (S.avatarSpeaking && S.lastAvatarText) {
      const sim = textSimilarity(finalTranscript.trim(), S.lastAvatarText);
      if (sim > ECHO_SIMILARITY_THRESHOLD) return; // 判定为回声，丢弃
    }

    // 3. 积累 final 文本（支持长句拼接）
    S.pendingTranscript = (S.pendingTranscript + ' ' + finalTranscript.trim()).trim();

    // 4. VAD 防抖：800ms 无新 final result 则认为用户说完，触发处理
    if (vadTimer) clearTimeout(vadTimer);
    vadTimer = setTimeout(() => flushPendingTranscript(), 800);
};

// 全双工打断：用户在 Harvey 说话期间提出抗辩
function flushPendingTranscript() {
    if (S.avatarSpeaking) {
      S.isInterrupted = true;
      avatarInterrupt();        // 调用 SDK 打断接口
      processUserInput(text);   // 立即处理用户抗辩
      return;
    }
    if (S.currentPhase !== 'processing') processUserInput(text);
}

完整交互生命周期流程：

用户开口 -> ASR onresult 持续产出 interim/final，interim 实时上屏。
回声校验 -> 若与 Harvey 上一句台词相似度 > 0.55，判定为回声并丢弃。
VAD 端点 -> 800ms 无新 final result，触发 flushPendingTranscript。
状态切换 -> 状态机切至 processing，将抗辩文本投递大模型。
流式返回 -> 大模型逐句返回，状态机切至 speaking，驱动唇形同步，ASR 暂停。
播报结束 -> onVoiceStateChange('end') 回调触发 restartRecognition，重新进入 listening 循环。

ASR 自动重启的严格管控

recognition.onend 仅在 listening 阶段自动重启 ASR；在 processing 与 speaking 阶段不自动重启，避免与数字人语音播放产生竞争，由 onVoiceStateChange('end') 负责恢复监听。

五、开发踩坑记录与解决方案

1. 魔珐星云 SDK 接入参数缺失导致初始化崩溃

现象：按示例代码调用 new XmovAvatar({ el, appId, appSecret }) 后执行 init()，控制台报 Cannot read properties of undefined (reading 'onDownloadProgress')。
根因：SDK 构造器要求 containerId（选择器字符串）而非 el（DOM 元素），且必须传入 gatewayServer 与 config.layout（含容器尺寸与 avatar scale）；init() 必须传入 { initModel, onDownloadProgress } 对象。
解决：按官方接入说明补全参数，并根据容器高度动态计算 scale = containerHeight / 1920，数字人形象得以正确渲染。

2. 数字人加载后 ASR 收不到声音

现象：数字人成功加载并显示，但用户说话时 ASR 毫无反应，控制台偶现 [ASR Error] network。
根因：ASR 在数字人 SDK 之前启动。魔珐星云 SDK 加载时会创建自己的音频上下文（WebGL/WebAudio），与 enableClientInterrupt 的客户端打断检测功能争抢麦克风通道，导致已运行的 Web Speech API 被干扰失效。
解决：调整初始化顺序为 数字人先加载 → 请求麦克风权限 → ASR 启动，并在 ASR 启动前主动调用 navigator.mediaDevices.getUserMedia({ audio: true }) 确保权限就绪。

3. 控制台打印了识别结果，页面却不显示用户文本

现象：onresult 中 [ASR] Buffered final: "..." 正常打印，但庭审笔录面板始终不出现用户消息。
根因：原逻辑依赖 onaudioend 消费 pendingTranscript，但 continuous: true 模式下 onaudioend 只在整个音频会话结束时触发，而非每次 final result 后触发，导致文本被缓存却永不被消费。
解决：改用 800ms 防抖定时器作为 VAD 端点，每次 final result 重置定时器，超时后统一处理；同时新增 interim 实时上屏，提升交互反馈感。