大功告成

DEPLOYMENT_GUIDE.md

@@ -15,7 +15,7 @@
 - 用户语音上行（VAD + ASR）
 - 文本调用在线 LLM
 - 本地 TTS 合成语音
-- 数字人视频下行（MuseTalk 优先，失败回退写实底片）
+- WebRTC 音频下行 + 3D 数字人控制流下行（WebSocket）
 - 前端字幕与指标面板（SSE + WebSocket）
 - 单工仲裁（支持 barge-in 打断）
 
@@ -36,10 +36,10 @@
   - `llm.py`：在线模型 + fallback
   - `tts.py`：Kokoro
   - `vad.py`：Silero VAD
-  - `avatar.py`：MuseTalk 推理调度 + 写实回退帧
+  - `avatar.py`：音频转 3D 控制数据（blendshape / 头部姿态）
 - `webrtc/`
-  - `tracks.py`：实际音视频轨道实现
-  - `gateway.py`、`video_track.py`、`audio_track.py`：结构化封装
+  - `tracks.py`：实际音频轨道实现
+  - `gateway.py`、`audio_track.py`：结构化封装
 - `web/`
   - `index.html`、`app.js`、`style.css`
 - `scripts/`
@@ -192,11 +192,18 @@ bash /home/xsl/product/scripts/gpu_monitor.sh /home/xsl/product/outputs/gpu-1h.c
 ## 7. 前端功能说明
 
 网页包含：
-- 视频窗口（数字人）
+- Three.js 3D 数字人舞台
 - 文本输入框
 - 字幕消息区（WebSocket）
 - 指标面板（SSE）
 
+当前前端能力：
+- 浏览器通过 import map 直接加载 Three.js、GLTFLoader、three-vrm
+- 可加载本地 `VRM`/`GLB` 文件
+- 可加载 URL 形式的 `VRM`/`GLB`/`GLTF` 模型
+- 页面默认会自动尝试加载官方 `three-vrm` 示例模型：`VRM1_Constraint_Twist_Sample.vrm`
+- 未加载真实模型时会显示调试头像，仍可联调动画控制流
+
 当前已支持：
 - 页面刷新自动重连
 - 单连接策略（新连接踢掉旧连接）
@@ -207,9 +214,9 @@ bash /home/xsl/product/scripts/gpu_monitor.sh /home/xsl/product/outputs/gpu-1h.c
 
 ## 8. 当前已知边界
 
-- MuseTalk 结果生成可能有一定延迟，期间使用写实底片回退。
-- 部分“主观体验类”验收项（如口型同步主观评分）需要人工实测判定。
-- Qwen3-TTS 对比方案尚未并入主链路（可后续做 A/B 开关）。
+- 当前后端输出的是可直接对接 3D 引擎的控制数据，不负责最终 3D 渲染。
+- 当前控制数据基于音频能量和频谱特征做启发式推断，适合作为联调骨架，不等同于生产级口型模型。
+- 若要达到更高口型精度，建议后续接入 phoneme/viseme 对齐模型或 Audio2Face 类推理服务。
 
 ---
 
@@ -224,8 +231,9 @@ bash /home/xsl/product/scripts/gpu_monitor.sh /home/xsl/product/outputs/gpu-1h.c
 - 系统是单连接模式，新连接会断开旧连接（预期）
 
 3) 口型不动  
-- 查看 `/health` 中 `avatar.queued_frames` 和 `avatar.last_error`
-- 若 MuseTalk 未产帧，会回退写实底片 + 口型叠加
+- 查看 `/health` 中 `avatar.last_frame_count` 和 `avatar.last_error`
+- 查看前端 `/ws/animation` 是否已连接，控制流预览是否持续刷新
+- 若模型已加载但不动，先检查该模型是否带有 VRM expression 或 morph target
 
 4) 模型异常  
 - 跑 `scripts/model_probe.py` 快速定位 ASR/TTS/VAD