376 lines
11 KiB
Markdown
376 lines
11 KiB
Markdown
# 下行音频卡死后的会话恢复：问题原因与修复方案
|
||
|
||
## 1. 对应提交
|
||
|
||
```text
|
||
a94df95 fix(multimodal): recover stalled downstream sessions
|
||
```
|
||
|
||
本文说明云端 TTS 下行音频在播放过程中长时间不再推进时，设备可能一直停留在“云端正在响应”的状态，导致后续无法唤醒或开始下一轮对话的问题。
|
||
|
||
## 2. 用户可见现象
|
||
|
||
典型过程如下：
|
||
|
||
1. 设备已经成功唤醒并发送用户语音；
|
||
2. 云端开始返回 TTS，设备也开始播放；
|
||
3. 播放中途音频包停止到达，或播放器长时间没有进展；
|
||
4. 音频管线的保护逻辑终止本地播放；
|
||
5. 设备表面上不再播放，但云端会话仍可能保持 responding 或 active；
|
||
6. 后续再次说唤醒词或按键，无法顺利开始新会话；
|
||
7. 断开连接或重启设备后才恢复。
|
||
|
||
这个问题和“偶尔停顿后继续播放”不同。短暂网络抖动可以通过预缓冲或重缓冲吸收；这里处理的是已经超过保护阈值、被判定为不可继续等待的长时间 stall。
|
||
|
||
## 3. 原有逻辑的问题
|
||
|
||
### 3.1 stall 被当作普通 stopped
|
||
|
||
修复前，音频管线检测到下行播放长期无进展后，会推进 playback generation、停止播放任务并通知：
|
||
|
||
```text
|
||
MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STOPPED
|
||
```
|
||
|
||
但 `STOPPED` 本身可能代表多种正常情况：
|
||
|
||
- 用户主动打断；
|
||
- 上层主动停止；
|
||
- 会话正常切换；
|
||
- transport 关闭导致播放结束；
|
||
- 播放器因长时间无数据被保护逻辑强制终止。
|
||
|
||
把 stall 和正常 stopped 混在一起后，上层无法判断是否需要恢复云端会话。
|
||
|
||
### 3.2 本地播放器停止不等于云端任务结束
|
||
|
||
播放器只负责消费并播放已经收到的 Opus 数据。播放器停止后，服务端并不会自动知道设备已经放弃本次响应。
|
||
|
||
因此可能形成状态分裂：
|
||
|
||
```text
|
||
设备音频管线：已经停止播放
|
||
control-plane：仍认为任务存在
|
||
云端：仍认为本轮响应或任务未结束
|
||
WebSocket：物理连接可能仍显示 connected
|
||
```
|
||
|
||
此时“WebSocket 还连着”并不代表会话可复用。旧任务没有收尾，新一轮 RequestToSpeak、Start 或唤醒流程可能被旧状态阻塞。
|
||
|
||
### 3.3 直接重连会造成不必要的恢复开销
|
||
|
||
一旦 stall 就立刻关闭 WebSocket 虽然能清空状态，但会带来：
|
||
|
||
- 重新鉴权和建连延迟；
|
||
- 额外网络请求；
|
||
- 正常可用的 WebSocket 被浪费；
|
||
- 偶发的服务端响应异常被放大为完整断线。
|
||
|
||
因此需要先尝试只结束当前任务，失败后再退休连接。
|
||
|
||
## 4. 根本原因
|
||
|
||
问题的根本原因是下行播放状态和云端会话状态之间缺少针对 stall 的闭环：
|
||
|
||
```text
|
||
下行长时间没有新数据或播放进展
|
||
↓
|
||
音频保护逻辑停止本地播放器
|
||
↓
|
||
仅上报普通 STOPPED
|
||
↓
|
||
上层无法识别这是异常卡死
|
||
↓
|
||
没有向云端结束当前任务，也没有退休 transport
|
||
↓
|
||
旧会话长期保持 active，后续唤醒被阻塞
|
||
```
|
||
|
||
## 5. 修复方案
|
||
|
||
修复采用“两级恢复”，优先保留 WebSocket，无法收敛时再重连。
|
||
|
||
### 5.1 增加独立的 STALLED 事件
|
||
|
||
音频管线在保护 watchdog 判定响应卡死时，不再发送普通 `STOPPED`，而是发送：
|
||
|
||
```text
|
||
MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STALLED
|
||
```
|
||
|
||
该事件逐层传递：
|
||
|
||
```text
|
||
audio pipeline
|
||
↓
|
||
platform callback
|
||
↓
|
||
domain event
|
||
↓
|
||
control-plane session service
|
||
↓
|
||
CONTROL_PLANE_MULTIMODAL_EVENT_DOWNSTREAM_STALLED
|
||
```
|
||
|
||
这样上层可以准确区分：
|
||
|
||
| 事件 | 含义 | 是否启动异常恢复 |
|
||
| --- | --- | --- |
|
||
| `STOPPED` | 主动停止、打断或普通停止 | 否 |
|
||
| `COMPLETED` | 正常播放完成 | 否 |
|
||
| `STALLED` | 下行响应长期无进展，被保护机制终止 | 是 |
|
||
|
||
### 5.2 只对云端响应启动会话恢复
|
||
|
||
session service 收到 `STALLED` 后，会检查当前是否确实存在云端响应：
|
||
|
||
- 当前有有效 task id；
|
||
- 并且云端仍处于 responding，或者本轮已经收到过云端音频。
|
||
|
||
如果只是本地提示音卡住，不会修改云端 WebSocket 状态，避免本地素材问题误伤云端连接。
|
||
|
||
### 5.3 第一级恢复：请求服务端 Stop
|
||
|
||
确认是云端下行响应 stall 后：
|
||
|
||
1. 停止音频上行；
|
||
2. 设置 `s_downstream_stall_stop_pending`；
|
||
3. 停止继续接收和播放本轮迟到音频；
|
||
4. 发送 `finish-task / Stop` 指令；
|
||
5. 最多等待 2000 ms 的服务端确认。
|
||
|
||
如果收到服务端 `Stopped`：
|
||
|
||
- 重置当前 session state；
|
||
- 停止残留的本地下行播放；
|
||
- 通知上层服务端已经不再 listening；
|
||
- 清除 stall recovery 状态；
|
||
- 保留当前 WebSocket，供下一轮对话复用。
|
||
|
||
这是成本最低的恢复路径。
|
||
|
||
### 5.4 第二级恢复：退休 transport 并重新连接
|
||
|
||
以下情况会进入第二级恢复：
|
||
|
||
- Stop 指令发送失败；
|
||
- 发送 Stop 后 2000 ms 内没有收到服务端确认；
|
||
- 当前连接已经断开。
|
||
|
||
对于前两种情况，旧 transport 会被标记为：
|
||
|
||
```text
|
||
CONTROL_PLANE_TRANSPORT_LOSS_DOWNSTREAM_STALL
|
||
```
|
||
|
||
随后执行：
|
||
|
||
```text
|
||
清除 stall recovery 状态
|
||
↓
|
||
将旧 transport 标记为不可用
|
||
↓
|
||
停止旧 WebSocket
|
||
↓
|
||
调度新的 WebSocket 启动
|
||
↓
|
||
重新进入鉴权和建连流程
|
||
```
|
||
|
||
这样即使服务端任务已经卡死、无法响应 Stop，设备也不会无限等待。
|
||
|
||
### 5.5 watchdog 负责有界等待
|
||
|
||
恢复流程由已有多模态 watchdog 推进，而不是在音频回调里阻塞等待。
|
||
|
||
内部记录三个状态：
|
||
|
||
```text
|
||
s_downstream_stall_recovery_pending
|
||
s_downstream_stall_stop_sent
|
||
s_downstream_stall_recovery_started_ms
|
||
```
|
||
|
||
它们分别表示：
|
||
|
||
- 是否存在待处理的 stall 恢复；
|
||
- Stop 是否已经发出；
|
||
- 等待 Stop 确认的起始时间。
|
||
|
||
这样音频线程只负责报告事实，控制层异步完成网络操作和超时处理，避免阻塞播放任务或 WebSocket 回调。
|
||
|
||
### 5.6 启停和连接异常时清理恢复状态
|
||
|
||
以下场景会主动清除 stall recovery 状态：
|
||
|
||
- transport disconnected；
|
||
- transport error；
|
||
- task failed；
|
||
- 多模态客户端重新启动；
|
||
- 多模态客户端停止。
|
||
|
||
目的是避免旧会话的 stall 标记污染下一条连接或下一轮任务。
|
||
|
||
## 6. 修复后的状态流转
|
||
|
||
### 6.1 服务端正常确认 Stop
|
||
|
||
```text
|
||
检测到下行 stall
|
||
↓
|
||
上报 STALLED
|
||
↓
|
||
确认是云端响应
|
||
↓
|
||
发送 Stop
|
||
↓
|
||
服务端返回 Stopped（不超过 2 秒）
|
||
↓
|
||
清理当前任务状态
|
||
↓
|
||
保留 WebSocket
|
||
↓
|
||
下一轮可以继续使用
|
||
```
|
||
|
||
### 6.2 Stop 失败或确认超时
|
||
|
||
```text
|
||
检测到下行 stall
|
||
↓
|
||
发送 Stop 失败，或等待超过 2 秒
|
||
↓
|
||
将旧 transport 标记为 downstream_stall
|
||
↓
|
||
关闭旧 WebSocket
|
||
↓
|
||
调度重新鉴权和建连
|
||
↓
|
||
恢复到可接受新会话的状态
|
||
```
|
||
|
||
### 6.3 本地提示音 stall
|
||
|
||
```text
|
||
检测到本地播放 stall
|
||
↓
|
||
没有有效云端响应
|
||
↓
|
||
仅结束本地播放
|
||
↓
|
||
不发送云端 Stop
|
||
↓
|
||
不关闭 WebSocket
|
||
```
|
||
|
||
## 7. 为什么等待时间是 2 秒
|
||
|
||
`CONTROL_PLANE_DOWNSTREAM_STALL_STOP_GRACE_MS` 当前为 2000 ms。
|
||
|
||
它不是播放提示音或采集音频的固定延迟，而只是 stall 已经发生后，等待服务端确认 Stop 的最长保护时间。
|
||
|
||
选择有界等待的原因是：
|
||
|
||
- 完全不等待会导致每次 stall 都立刻重连；
|
||
- 无限等待会让设备再次卡死；
|
||
- 2 秒给正常的服务端控制消息留出响应时间；
|
||
- 超时后仍能保证设备最终自愈。
|
||
|
||
在这 2 秒内，当前异常会话不会被当作正常会话继续使用。
|
||
|
||
## 8. 修复的影响范围
|
||
|
||
### 会改变的行为
|
||
|
||
- 云端 TTS 被确认 stall 后，会主动结束当前任务；
|
||
- Stop 无法确认时会关闭并重建 WebSocket；
|
||
- stall 恢复期间会停止音频上行并丢弃当前响应的迟到音频；
|
||
- 最坏情况下，下一轮对话需要等待旧连接退休和新连接建立。
|
||
|
||
### 不会改变的行为
|
||
|
||
- 正常 TTS 播放完成不会触发恢复；
|
||
- 用户主动打断产生的普通 stopped 不会误触发 stall 重连；
|
||
- 本地提示音 stall 不会主动关闭云端连接；
|
||
- 该提交不负责修复 Opus Decoder 内存泄漏；
|
||
- 该提交不负责 Wi-Fi STA 重新关联路由器；
|
||
- 该提交不解决短时抖动导致的普通卡顿，短时抖动由缓冲策略处理。
|
||
|
||
## 9. 关键日志
|
||
|
||
正常进入恢复时：
|
||
|
||
```text
|
||
Cloud downstream playback stalled; request bounded session recovery
|
||
Downstream stall recovery queued for watchdog worker
|
||
Downstream stall recovery started: request Stop and wait up to 2000 ms
|
||
Request Stop for stalled downstream response
|
||
```
|
||
|
||
服务端及时确认时：
|
||
|
||
```text
|
||
Downstream stall Stop acknowledged; transport remains reusable
|
||
Downstream stall recovered by server Stop acknowledgement; keep WebSocket
|
||
```
|
||
|
||
Stop 发送失败时：
|
||
|
||
```text
|
||
Downstream stall Stop request failed: ...; retire transport now
|
||
```
|
||
|
||
等待超时时：
|
||
|
||
```text
|
||
Downstream stall Stop acknowledgement timed out after 2000 ms; retire transport
|
||
```
|
||
|
||
如果进入 transport 退休，还应继续看到重新调度 WebSocket 的日志。
|
||
|
||
## 10. 建议验证方法
|
||
|
||
### 10.1 正常流程回归
|
||
|
||
1. 连续完成至少 20 轮正常对话；
|
||
2. 验证正常 TTS 完成不会出现 `DOWNSTREAM_STALLED`；
|
||
3. 验证用户按键打断和唤醒打断不会触发不必要的 WebSocket 重连。
|
||
|
||
### 10.2 stall 后服务端能够确认 Stop
|
||
|
||
1. 人为阻断下行音频数据，但保持 WebSocket 控制消息可用；
|
||
2. 等待本地 watchdog 判断 stall；
|
||
3. 确认设备发送 Stop；
|
||
4. 确认收到 `Stopped` 后保留原 WebSocket；
|
||
5. 立即开始下一轮唤醒，确认可以正常对话。
|
||
|
||
### 10.3 stall 后服务端不确认 Stop
|
||
|
||
1. 人为阻断服务端响应或所有 WebSocket 数据；
|
||
2. 确认设备等待不超过 2000 ms；
|
||
3. 确认旧 transport 被退休；
|
||
4. 恢复网络后确认设备自动建立新连接；
|
||
5. 确认无需重启设备即可再次唤醒。
|
||
|
||
### 10.4 本地提示音回归
|
||
|
||
1. 播放本地唤醒提示音或系统提示音；
|
||
2. 人为制造本地播放异常；
|
||
3. 确认日志显示本地 stall；
|
||
4. 确认没有发送云端 Stop，也没有关闭健康的 WebSocket。
|
||
|
||
## 11. 涉及文件
|
||
|
||
```text
|
||
components/control_plane/internal/control_plane_internal.h
|
||
components/control_plane/src/multimodal/control_plane_multimodal_runtime.c
|
||
components/control_plane/src/multimodal/control_plane_multimodal_session_service.c
|
||
components/domain/include/domain.h
|
||
components/domain/src/runtime/domain_runtime_adapters.c
|
||
components/platform/include/platform.h
|
||
components/platform/internal/multimodal/audio_pipeline.h
|
||
components/platform/src/multimodal/audio_pipeline/audio_pipeline_runtime_impl.c
|
||
components/platform/src/runtime/platform_multimodal_runtime.c
|
||
```
|
||
|