# WebSocket 断线后使用新鉴权上下文重连：问题原因与修复方案

## 1. 对应提交

```text
273550b fix(multimodal): reconnect websocket with fresh auth
```

本文说明多模态 WebSocket 在运行过程中断开后，设备可能持续重连失败、无法继续唤醒对话，而重启设备后又可以恢复的问题。

## 2. 用户可见现象

典型表现如下：

1. 设备启动后能够正常连接并完成若干轮对话；
2. 运行过程中 WebSocket 出现 error 或 disconnected；
3. 后续日志反复出现连接失败，设备无法重新进入可用的语音会话；
4. Wi-Fi 本身可能仍显示已连接；
5. 重启设备后，连接通常能够立即恢复。

“重启后恢复”说明问题不一定来自远端服务长期不可用。如果远端服务或公网一直不可达，重启设备一般也不会立刻解决。这个现象更符合设备内部旧 WebSocket、旧鉴权 Header 或重连状态没有被完整清理。

## 3. 原有设计的问题

### 3.1 WebSocket 重连存在两个控制者

修复前，底层 WebSocket 客户端配置为：

```c
.disable_auto_reconnect = false,
.enable_close_reconnect = true,
```

这意味着底层库可以自行重连。同时，项目的 control-plane 也负责鉴权、创建连接、处理断线和调度下一次启动。

因此一次断线后可能同时存在两条恢复路径：

```text
底层 WebSocket 库
    └─ 使用原客户端和原 Header 自动重连

control-plane
    └─ 将会话标记为不可用，准备重新鉴权和创建连接
```

两套状态机并不共享完整状态，容易产生以下不一致：

- control-plane 已认为连接不可用，但底层仍在自动重连；
- control-plane 已清空当前会话鉴权信息，但旧客户端仍持有创建时的 Header；
- 新一轮启动与旧客户端的关闭、回调或重连交错；
- 上层看到“未连接”，底层却可能仍处于 connecting、closing 或 reconnecting；
- 旧连接的异步回调可能影响新一轮连接。

### 3.2 WebSocket error/disconnected 没有强制回收旧 transport

修复前，`control_plane_multimodal_mark_transport_unavailable()` 会清理上层状态，但只有部分原因会触发底层 transport stop：

- 协议错误；
- 文本发送失败；
- listening 超时；
- no-response 超时。

以下两个最直接代表 WebSocket 已失效的原因却没有进入强制关闭条件：

```text
CONTROL_PLANE_TRANSPORT_LOSS_WS_ERROR
CONTROL_PLANE_TRANSPORT_LOSS_WS_DISCONNECTED
```

结果是上层状态已经退休，底层旧客户端却可能继续存在并自行重连。

### 3.3 断线事件没有稳定地调度新一轮连接

修复前，收到 transport error/disconnected 后主要执行：

- 清理待处理的云端业务状态；
- 停止音频上行。

但没有在这两个事件中明确调度一次新的 WebSocket 启动。因此恢复可能依赖底层自动重连，或者依赖后续其他状态变化碰巧触发连接。

### 3.4 一次启动失败后，重试请求可能被消费掉

Wi-Fi 状态任务会消费 `ws_start_requested`。修复前，如果本次 `control_plane_try_start_multimodal_from_state_machine()` 返回失败，请求已经被消费，但没有立即重新挂起。

这样会出现：

```text
收到重连请求
    ↓
本次启动失败
    ↓
请求被消费
    ↓
没有新的触发条件
    ↓
设备长期停留在未连接状态
```

## 4. 根本原因

根本原因不是单次网络错误，而是 WebSocket 恢复流程的所有权不唯一：

```text
底层库自动重连旧客户端
        ＋
control-plane 清理并重建会话
        ＋
WS 错误时旧 transport 未被强制回收
        ＋
启动失败后重试请求可能丢失
        ↓
旧连接、旧 Header 和新会话状态互相干扰
        ↓
运行中持续连接失败，重启后因全部状态重建而恢复
```

## 5. 修复方案

### 5.1 禁止底层 WebSocket 自动重连

配置改为：

```c
.disable_auto_reconnect = true,
.enable_close_reconnect = false,
```

底层 transport 只负责一条连接的建立、收发和关闭，不再私自决定重连。

重连所有权统一交给 control-plane：

```text
WebSocket 异常
    ↓
通知 control-plane
    ↓
退休旧 transport
    ↓
重新进入多模态启动流程
    ↓
重新取得当前有效鉴权信息并生成连接 Header
    ↓
创建新的 WebSocket 客户端
```

### 5.2 WS error/disconnected 必须关闭旧 transport

以下原因被加入 `close_transport` 判断：

```text
CONTROL_PLANE_TRANSPORT_LOSS_WS_ERROR
CONTROL_PLANE_TRANSPORT_LOSS_WS_DISCONNECTED
```

这保证上层判定 WebSocket 不可用时，底层旧客户端也会被停止，而不是留在后台继续使用旧状态重连。

### 5.3 断线和错误事件主动调度重连

处理以下事件时，明确调用 `control_plane_schedule_websocket_wait_task()`：

```text
CONTROL_PLANE_MULTIMODAL_EVENT_TRANSPORT_DISCONNECTED
CONTROL_PLANE_MULTIMODAL_EVENT_TRANSPORT_ERROR
```

因此恢复不再依赖底层自动重连或其他偶发事件。

### 5.4 启动失败后重新挂起重试请求

Wi-Fi 状态任务尝试启动 WebSocket 后会检查结果：

```c
if (!ws_started) {
    (void)control_plane_schedule_websocket_wait_task();
}
```

本次失败不会永久吃掉重试机会。后续仍由既有状态机和退避节奏继续尝试。

### 5.5 增加架构守卫

架构检查脚本增加规则，防止后续修改重新引入以下行为：

- 再次开启底层 WebSocket 自动重连；
- WS error/disconnected 不再回收旧 transport；
- transport error/disconnected 不再调度 control-plane 重连；
- 启动失败后不重新安排重试。

这条守卫的目的不是运行时恢复，而是在构建或代码检查阶段阻止同类设计回退。

## 6. “fresh auth”的准确含义

这里的 `fresh auth` 更准确地说是：

> 不复用旧 WebSocket 客户端内部固化的鉴权 Header，而是销毁旧 transport，重新通过 control-plane 的鉴权与建连流程构造连接。

它不必然表示每次断线都强制向服务端申请一个全新的 JWT。设备鉴权模块仍可能复用尚未过期、权限范围正确的有效 JWT。

两者的区别是：

| 概念 | 含义 |
| --- | --- |
| 重新走鉴权建连流程 | 重新检查当前鉴权状态，并为新客户端生成当前有效的连接参数和 Header。此次修复保证做到这一点。 |
| 强制刷新 JWT | 无论现有 JWT 是否有效，都向鉴权服务申请新 JWT。此次提交并没有要求每次都这样做。 |

## 7. 修复后的影响

### 正面影响

- WebSocket 重连只有一个控制者；
- 每轮重连前会回收旧客户端；
- 避免旧连接回调污染新会话；
- 重连会重新经过项目自己的鉴权和状态检查；
- 单次启动失败后仍能继续重试；
- 运行中断线后的行为更接近重启设备后的干净启动流程。

### 代价

- 每次 WebSocket error/disconnected 都需要销毁并新建 transport；
- 相比底层直接原地自动重连，会多经过一次清理和 control-plane 调度；
- 如果需要刷新鉴权，还会增加鉴权请求时间；
- 但换来的是状态一致性和可恢复性，避免设备陷入长期不可用状态。

该提交只重建多模态 WebSocket，不会主动让 Wi-Fi STA 断开并重新关联路由器。Wi-Fi 重关联属于另一层恢复策略。

## 8. 关键日志

修复后重点关注：

```text
Schedule fresh-auth reconnect after transport disconnect
Schedule fresh-auth reconnect after transport error
Retire unavailable transport: reason=...; next start requires fresh auth
```

预期顺序大致为：

```text
transport error/disconnected
    ↓
Retire unavailable transport
    ↓
Schedule fresh-auth reconnect
    ↓
旧 transport 完成清理
    ↓
鉴权准备
    ↓
新 WebSocket 建立成功
```

如果只看到反复的 schedule，但没有旧 transport 清理完成或新鉴权开始，应继续检查 transport stop 是否卡住。如果鉴权成功但新 WebSocket 仍连接失败，应继续区分 DNS、TCP/TLS 和远端拒绝问题。

## 9. 建议验证方法

1. 正常完成多轮语音对话，确认基础流程不受影响；
2. 对话空闲时短暂关闭路由器或屏蔽网络，制造 WebSocket disconnect；
3. 恢复网络，确认设备会退休旧 transport，并自动创建新连接；
4. 在 TTS 播放或音频上行期间制造断网，确认上行停止且不会留下假连接；
5. 连续重复断网、恢复至少 10 次，确认不需要重启设备；
6. 检查每次新连接前是否都有明确的旧 transport 清理过程；
7. 检查没有出现底层 WebSocket 自行无限重连的日志循环。

## 10. 涉及文件

```text
components/control_plane/src/multimodal/control_plane_multimodal_runtime.c
components/control_plane/src/multimodal/control_plane_multimodal_session_service.c
components/control_plane/src/runtime/control_plane_runtime_workers.c
components/platform/src/multimodal/transport_ws/transport_ws_workers_impl.c
tools/check_architecture_guards.sh
```