save code

README.md

@@ -2,7 +2,7 @@
 
 这个项目提供一个浏览器侧渲染的 3D 数字人语音交互原型：
 
-- 浏览器通过 WebRTC 上传麦克风音频，并接收服务端回传的 AI 语音。
+- 浏览器通过 WebSocket 上传麦克风 PCM 音频，并接收服务端回传的 AI 语音片段。
 - 浏览器通过 WebSocket 订阅字幕和口型/头部控制数据。
 - 服务端执行 VAD -> ASR -> DeepSeek LLM -> TTS，并把音频特征转换为驱动 3D 数字人的控制帧。
 
@@ -14,13 +14,13 @@
 
 ```text
 Browser Mic
-  -> WebRTC audio upstream
-  -> FastAPI / aiortc
+  -> /ws/audio
+  -> FastAPI / websocket audio
   -> VAD
   -> ASR
   -> LLM
   -> TTS
-  -> WebRTC audio downstream
+  -> /ws/audio
   -> browser audio playback
 ```
 
@@ -44,7 +44,7 @@ ASR text / LLM segmented reply
 
 ## 关键目录
 
-- [main.py](main.py): FastAPI 入口，聚合 WebRTC、WebSocket、健康状态和文本对话接口。
+- [main.py](main.py): FastAPI 入口，聚合音频 WebSocket、字幕/动画 WebSocket、健康状态和文本对话接口。
 - [core/pipeline.py](core/pipeline.py): 语音/文本对话流水线，负责 ASR、LLM、TTS 编排。
 - [core/state_machine.py](core/state_machine.py): 简单会话状态机，处理用户说话、思考、数字人说话之间的切换。
 - [services/asr.py](services/asr.py): ASR 封装，优先使用 FunASR，失败时进入降级模式。
@@ -52,7 +52,7 @@ ASR text / LLM segmented reply
 - [services/tts.py](services/tts.py): TTS 封装，优先使用 Kokoro，失败时返回静音兜底。
 - [services/vad.py](services/vad.py): VAD 封装，基于 silero-vad。
 - [services/avatar.py](services/avatar.py): 把音频转换成 blendshape 和头部控制帧。
-- [web/app.js](web/app.js): 浏览器端 3D 舞台、WebRTC 建连、字幕和动画消费逻辑。
+- [web/app.js](web/app.js): 浏览器端 3D 舞台、音频 WebSocket、字幕和动画消费逻辑。
 - [scripts](scripts): 启动、证书生成、巡检和服务管理脚本。
 
 ## 快速启动
@@ -71,6 +71,17 @@ export LLM_BASE_URL="https://api.deepseek.com/v1"
 export LLM_MODEL="deepseek-chat"
 ```
 
+也可以直接复制 [.env.example](.env.example) 作为本地配置模板。
+
+语音如果偏快、偏硬，可以优先调这几个参数：
+
+- `LLM_SYSTEM_PROMPT`：先把回答风格约束成口语化、非书面化，并明确禁止客服套话，再去调 TTS，收益更大。
+- `LLM_TEMPERATURE`：默认 `0.55`，能减少奇怪人设和跑偏表达。
+- `TTS_SPEED`：默认 `0.90`，比 `1.0` 更像真人正常说话速度。
+- `TTS_SENTENCE_MAX_LEN`：默认 `64`，避免回复被切得太碎。
+- `TTS_SEGMENT_PAUSE_MS`：默认 `90`，给分段之间留一点停顿，但不要太拖。
+- `TTS_FADE_MS`：默认 `12`，减轻段间拼接的突兀感。
+
 本地启动：
 
 ```bash
@@ -83,6 +94,14 @@ python main.py
 bash scripts/start-public.sh
 ```
 
+基础自检：
+
+```bash
+python scripts/model_probe.py
+python scripts/qa_check.py --base-url http://127.0.0.1:8080 --rounds 3
+python scripts/smoke_test.py --text "你好，请做一个简短自我介绍。"
+```
+
 启动后访问：
 
 - `http://127.0.0.1:8080/`
@@ -96,15 +115,20 @@ bash scripts/gen-self-signed-cert.sh
 
 再在环境变量或 `.env` 中配置 `SSL_CERTFILE` 和 `SSL_KEYFILE`。
 
+监听规则：
+
+- 服务监听地址固定按 `0.0.0.0` 规则执行。
+- 即使把 `WEBRTC_HOST` 写成 `127.0.0.1`、`localhost` 或 `::1`，启动时也会自动归一化成 `0.0.0.0`，避免局域网访问被误伤。
+
 ## 核心接口
 
 - `GET /`: 前端页面。
-- `POST /webrtc/offer`: 建立 WebRTC 音频连接。
 - `POST /chat/text`: 文本输入链路，跳过 ASR/VAD。
 - `POST /chat/reset`: 清空上下文和运行时状态。
 - `GET /health`: 返回后端运行指标和组件健康状态。
 - `GET /meta`: 返回 STUN、HTTPS、端口和动画协议配置。
 - `GET /events`: Server-Sent Events 运行状态流。
+- `WS /ws/audio`: 双向语音通道，上传麦克风 PCM 并接收回复语音。
 - `WS /ws/subtitles`: 字幕流。
 - `WS /ws/animation`: 数字人控制流。
 - `GET /avatar/schema`: 当前控制协议 schema。