@agentunion/kite 1.4.0 → 1.6.0

package/docs/WebSocket/350/277/236/346/216/245/351/237/247/346/200/247/344/270/216/351/207/215/350/277/236/346/234/272/345/210/266/345/256/214/346/225/264/346/226/271/346/241/210.md

@@ -0,0 +1,531 @@
+# WebSocket 连接韧性与重连机制完整方案
+
+> 状态：待实施
+> 创建时间：2026-03-14
+> 版本：v2.0（融合韧性方案 + 重连退避方案 + 断线检测增强）
+
+---
+
+## 一、方案概述
+
+本方案融合三个维度的连接管理机制：
+
+1. **连接韧性**：模块状态机、防抖机制、Launcher 异常恢复
+2. **重连退避**：三档策略（never/standard/cooldown）、错误码区段化、Jitter 防惊群
+3. **断线检测**：Ping/Pong 超时处理、握手超时控制、连接质量监控
+
+目标：构建一个优雅、健壮、完备的 WebSocket 连接管理体系。
+
+---
+
+## 二、错误码体系
+
+### 2.1 设计原则
+
+- **1000-1011**：标准 WebSocket 关闭码
+- **4001-4009**：认证类（Authentication）
+- **4010-4019**：连接管理类（Connection）
+- **4020-4029**：流控类（Flow Control）
+- 每个区段预留扩展位
+
+### 2.2 完整错误码表
+
+#### 标准 WebSocket 关闭码
+
+| 码值 | 含义 | 重连策略 | 发送方 | 场景 |
+|------|------|---------|--------|------|
+| 1000 | 正常关闭 | never | Kernel | 优雅关闭流程完成 |
+| 1001 | 服务器关闭 | standard | Kernel | Kernel 正在关闭 |
+| 1008 | 策略违反 | never | Kernel / Relay | TLS 要求、权限拒绝 |
+| 1011 | 服务器内部错误 | standard | Relay | 处理异常 |
+
+#### 4001-4009 认证类
+
+| 码值 | 含义 | 重连策略 | 发送方 | 场景 |
+|------|------|---------|--------|------|
+| 4001 | Token 无效 / 认证失败 | never | Kernel / Relay | Token 不存在、已过期、已吊销 |
+| 4002 | 认证握手超时 | standard | Kernel | 5s 内未收到认证消息（网络抖动可恢复） |
+| 4003 | 认证格式错误 | never | Kernel | jsonrpc/method/params 格式不合法 |
+| 4004 | MFA 验证失败 | never | Relay | TOTP 码错误，需用户重新输入 |
+
+#### 4010-4019 连接管理类
+
+| 码值 | 含义 | 重连策略 | 发送方 | 场景 |
+|------|------|---------|--------|------|
+| 4010 | 连接被替换 | never | Kernel | 同一模块新连接覆盖旧连接 |
+| 4011 | 队列压力强断 | standard | Kernel | critical 状态倒计时到期 |
+| 4012 | Ping/Pong 超时 | standard | Kernel | 连续 N 次 Ping 无响应（新增） |
+
+#### 4020-4029 流控类
+
+| 码值 | 含义 | 重连策略 | 发送方 | 场景 |
+|------|------|---------|--------|------|
+| 4020 | 速率限制 | cooldown | Kernel / Relay | 10s 内同 IP/module_id 超 20 次认证 |
+
+### 2.3 旧码迁移映射
+
+| 旧码 | 新码 | 变更说明 |
+|------|------|---------|
+| 4000 | **4010** | 连接被替换，移入连接管理区段 |
+| 4001 | 4001 | 不变 |
+| 4003（超时场景） | **4002** | 超时语义独立，可重试 |
+| 4003（格式场景） | 4003 | 语义收窄为格式错误 |
+| — | **4004** | 新增 MFA 失败 |
+| 4010 | **4011** | 队列压力，让出 4010 给连接被替换 |
+| 4029 | **4020** | 速率限制，归入流控区段 |
+| — | **4012** | 新增 Ping/Pong 超时 |
+
+---
+
+## 三、连接韧性机制
+
+### 3.1 Kernel 模块状态机
+
+Kernel 为每个模块维护完整的生命周期状态：
+
+```
+offline → connected → registered → ready
+            ↑                        │
+            └────────────────────────┘  (WS 断开 → 5s 防抖 → offline，重连后从 connected 重走)
+```
+
+| 状态 | 含义 | 触发条件 |
+|------|------|---------|
+| **offline** | 未连接 | 初始状态 / WS 断开 5s 后 |
+| **connected** | WS 已连接 | 认证成功 |
+| **registered** | 已注册 | subscribe + register 完成 |
+| **ready** | 可提供服务 | 发布 module.ready |
+
+**状态变更通知：**
+- `offline` → `ready`：广播 `module.ready` 事件
+- `ready` → `offline`：广播 `module.offline` 事件
+- 这些是系统级事件，Kernel 自动推送给所有已连接模块
+
+**RPC 路由保护：**
+- 外部调用某模块 RPC 时，Kernel 检查目标模块状态
+- 如果不是 `ready`，立即返回错误码 `-32001`（模块离线），不等待超时
+
+### 3.2 防抖机制（5s）
+
+模块 WS 断开后，Kernel 不立即标记 offline，而是等待 **5s**：
+
+- **5s 内重连**：取消防抖，状态从断开前继续，不发送 `module.offline` 事件
+- **5s 后未重连**：标记 `offline`，广播 `module.offline` 事件
+
+**实现位置：** `kernel/server.py` `_debounce_offline()` 方法
+
+### 3.3 Launcher 异常终止保护（35s）
+
+Launcher 是 Kite 实例的生命线，其断连需要特殊处理：
+
+| 阶段 | 时机 | 动作 |
+|------|------|------|
+| 防抖等待 | 0~5s | 等待重连，不通知 |
+| 离线通知 | 5s | 广播 `module.offline (launcher)` |
+| 重连窗口 | 5~35s | 继续等待 Launcher 重连 |
+| 优雅退出 | 35s | 触发全实例优雅退出流程 |
+
+**优雅退出流程（35s 触发）：**
+
+1. Kernel 向所有模块发布 `module.shutdown`（reason: `launcher_lost`）
+2. 等待各模块优雅退出（保存状态、清理资源、ack）
+3. 等待 10s 超时后，Kernel 自己退出
+
+**Watchdog 的异常恢复逻辑：**
+
+```
+Launcher WS 断开
+  → [0~5s]   Kernel 防抖等待
+  → [5s]     Kernel 广播 module.offline (launcher)
+  →          Watchdog 收到，标记状态，不做决策
+  → [5~35s]  Kernel 继续等待 Launcher 重连
+  → [35s]    Kernel 触发优雅退出，发布 module.shutdown (reason: launcher_lost)
+  →          Watchdog 收到 module.shutdown，判断：
+               有 module.exiting (launcher) → 正常退出 → 跟随退出
+               无 module.exiting (launcher) → 异常退出 → 启动新 Kite 实例
+```
+
+**正常 vs 异常退出的判断依据：**
+- **正常退出**：Launcher 在断开前发送过 `module.exiting` 事件
+- **异常退出**：Launcher 直接断开，没有 `module.exiting`（崩溃、被 kill）
+
+**实现位置：**
+- `kernel/server.py` `_launcher_loss_timeout()` 方法
+- `extensions/services/watchdog/monitor.py` `_handle_launcher_lost()` 方法
+
+### 3.4 残留清理顺序
+
+新 Launcher 启动时清理上一个实例的残留进程，按依赖关系排序：
+
+| 顺序 | 模块 | 理由 |
+|------|------|------|
+| 1 | Watchdog | 防止清理过程中 Watchdog 自动恢复其他模块 |
+| 2 | 普通模块 | 顺序无所谓 |
+| 3 | Kernel | 最后杀，防止连锁退出导致其他模块状态不可控 |
+
+**实现位置：** `launcher/process_manager.py` `_get_process_dependencies()` 方法
+
+---
+
+## 四、重连退避机制
+
+### 4.1 三档策略总览
+
+| 策略 | 适用场景 | 行为 |
+|------|---------|------|
+| **never** | 永久性错误，重试无意义 | 立即停止，不重连 |
+| **standard** | 临时性错误，可自动恢复 | 指数退避 + Jitter |
+| **cooldown** | 速率限制，需等待冷却 | 固定等待，有限重试 |
+
+### 4.2 错误码 → 策略映射
+
+| 策略 | 错误码 |
+|------|--------|
+| never | 1000, 1008, 4001, 4003, 4004, 4010 |
+| standard | 1001, 1011, 4002, 4011, 4012, 网络断开（无码） |
+| cooldown | 4020 |
+
+### 4.3 参数定义
+
+**内部模块** = Python 模块连 Kernel（localhost，网络可靠，Kernel 重启秒级恢复）
+**远程模块** = JS 前端连 Relay（跨网络，延迟高，抖动多）
+
+#### never
+
+| 参数 | 内部模块 | 远程模块 |
+|------|---------|---------|
+| 最大重试 | 0 | 0 |
+| 行为 | 设 `_shutting_down = True`，退出进程 | 设 `fatalError = true`，停止重连 |
+
+#### standard
+
+| 参数 | 内部模块（Python） | 远程模块（JS） |
+|------|-------------------|---------------|
+| 初始延迟 | 0.5s | 1.0s |
+| 增长因子 | ×2 | ×2 |
+| 最大延迟 | 10s | 15s |
+| 最大重试 | 无限制 | 无限制 |
+| Jitter | 0.2（±20%） | 0.2（±20%） |
+
+退避公式：
+
+```
+base = initial_delay × factor ^ (attempt - 1)
+jitter = base × jitter_ratio × random()
+delay = min(base + jitter, max_delay)
+```
+
+退避序列（不含 jitter）：
+- 内部：`0.5 → 1.0 → 2.0 → 4.0 → 8.0 → 10.0 → 10.0 → ...`
+- 远程：`1.0 → 2.0 → 4.0 → 8.0 → 15.0 → 15.0 → ...`
+
+#### cooldown
+
+| 参数 | 内部模块（Python） | 远程模块（JS） |
+|------|-------------------|---------------|
+| 初始延迟 | 10s | 10s |
+| 增长因子 | ×1（固定） | ×1（固定） |
+| 最大延迟 | 10s | 10s |
+| 最大重试 | 5 | 5 |
+| Jitter | 0 | 0 |
+
+cooldown 达到最大重试次数后，转为 never（停止重连）。
+
+### 4.4 重连成功后的重置
+
+连接成功并完成认证后，重置所有计数器：
+
+- `attempt = 0`
+- `retry_delay = initial_delay`
+- `cooldown_attempts = 0`
+
+---
+
+## 五、断线检测机制
+
+### 5.1 三层检测体系
+
+| 层级 | 机制 | 间隔 | 超时 | 作用 | 局限 |
+|------|------|------|------|------|------|
+| **网络层** | WebSocket Ping/Pong | 动态 5~60s | 5s | 检测 TCP 连接存活 | 无法检测应用层僵死 |
+| **应用层** | system.ping 事件 | 同上 | 5s | 检测事件循环响应 | 无法检测业务逻辑卡死 |
+| **业务层** | Watchdog Health RPC | 15s/5s/2s | 5s | 检测业务处理能力 | 需要模块实现 health 接口 |
+
+### 5.2 Ping/Pong 机制详解
+
+#### 动态间隔策略
+
+Kernel 根据系统活跃度自动调整 Ping 间隔：
+
+| 场景 | 间隔 | 触发条件 |
+|------|------|---------|
+| 活跃 | 5s | 最近 30s 内有 RPC 调用 |
+| 空闲 | 60s | 超过 30s 无 RPC 调用 |
+
+**实现位置：** `kernel/server.py` `_ping_broadcast_loop()` 方法（行 430-501）
+
+#### Ping 流程
+
+1. Kernel 广播 `system.ping` 事件（含 `ping_time` 时间戳）
+2. 各模块收到后立即回复 `system.pong` 事件（含原始 `ping_time` + 自己的 `pong_time`）
+3. Kernel 等待 5s，检查哪些模块未响应
+4. 计算延迟统计：
+   - **outbound**：模块收到 ping 的延迟（`pong_time - ping_time`）
+   - **inbound**：Kernel 收到 pong 的延迟（`recv_time - pong_time`）
+
+#### 超时处理（新增）
+
+**当前状态：** Ping 超时仅记录统计，不触发断线
+
+**新增机制：**
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 连续超时阈值 | 3 次 | 连续 3 次 Ping 无响应 |
+| 超时判定窗口 | 15s | 3 次 × 5s 间隔 |
+| 触发动作 | 关闭连接 | 发送关闭码 4012 |
+
+**实现逻辑：**
+
+```python
+# kernel/server.py 新增字段
+self._ping_timeout_counts = {}  # module_id -> consecutive_timeout_count
+
+async def _check_ping_timeouts(self):
+    for module_id in list(self.connections.keys()):
+        if module_id in self._ping_sent_times:
+            # 检查是否超时
+            if module_id not in self._pong_latencies or \
+               self._pong_latencies[module_id].get("last_update", 0) < self._ping_sent_times[module_id]:
+                # 超时
+                self._ping_timeout_counts[module_id] = self._ping_timeout_counts.get(module_id, 0) + 1
+
+                if self._ping_timeout_counts[module_id] >= 3:
+                    # 连续 3 次超时，强制断开
+                    print(f"[kernel] {module_id} ping timeout 3 times, closing connection")
+                    ws = self.connections.get(module_id)
+                    if ws:
+                        await ws.close(code=4012, reason="Ping timeout")
+            else:
+                # 收到 pong，重置计数
+                self._ping_timeout_counts[module_id] = 0
+```
+
+### 5.3 握手超时控制
+
+#### 当前实现
+
+| 阶段 | 超时 | 错误码 | 实现位置 |
+|------|------|--------|---------|
+| 认证握手 | 5s | 4002 | `kernel/server.py:166` |
+| Relay Challenge | 30s | 4000 | `relay.py` |
+
+#### 新增：认证响应超时
+
+**场景：** 模块发送认证请求后，Kernel 处理超时（如 token 验证卡死）
+
+**实现：**
+
+```python
+# kernel/server.py 认证处理
+try:
+    raw = await asyncio.wait_for(ws.receive_text(), timeout=5.0)
+    auth_msg = _loads(raw)
+
+    # 验证 token（新增超时保护）
+    token = auth_msg["params"]["token"]
+    module_id = await asyncio.wait_for(
+        asyncio.get_event_loop().run_in_executor(
+            None, server.registry.verify_token, token
+        ),
+        timeout=2.0  # token 验证最多 2s
+    )
+
+    if module_id is None:
+        # 认证失败
+        await ws.close(code=4001, reason="Authentication failed")
+        return
+
+except asyncio.TimeoutError:
+    # 握手超时或 token 验证超时
+    await ws.close(code=4002, reason="Auth timeout")
+    return
+```
+
+### 5.4 连接质量监控
+
+Kernel 持续监控每个模块的连接质量：
+
+| 指标 | 存储位置 | 用途 |
+|------|---------|------|
+| Ping 延迟（outbound/inbound） | `_pong_latencies` | 网络质量评估 |
+| Ping 状态（ok/timeout/never） | `_pong_status` | 连接健康度 |
+| 连续超时次数 | `_ping_timeout_counts` | 触发强制断开 |
+
+**查询接口：** `kernel.get_connection_stats` RPC 方法（可新增）
+
+---
+
+## 六、实施清单
+
+### 6.1 Kernel 端变更
+
+| 文件 | 变更内容 |
+|------|---------|
+| `kernel/server.py` | 1. 错误码迁移（4029→4020, 4003→4002, 4000→4010, 4010→4011）<br>2. 新增 4012（Ping 超时）<br>3. 新增 `_ping_timeout_counts` 字段<br>4. `_check_ping_timeouts()` 增加连续超时判断<br>5. 认证流程增加 token 验证超时保护 |
+| `kernel/event_hub.py` | 错误码迁移（4000→4010, 4010→4011） |
+| `kernel/registry_store.py` | 新增模块状态机（offline/connected/registered/ready） |
+
+### 6.2 Relay 端变更
+
+| 文件 | 变更内容 |
+|------|---------|
+| `extensions/services/evol/relay.py` | 1. 4029→4020<br>2. 4003(MFA)→4004 |
+| `extensions/services/kite_console/relay.py` | 同上 |
+| `extensions/services/web/relay.py` | 同上（如有） |
+
+### 6.3 Python 模块端变更（7 个模块）
+
+| 模块 | 文件 | 变更内容 |
+|------|------|---------|
+| backup | `extensions/services/backup/entry.py` | 统一重连参数 + 三档策略 |
+| watchdog | `extensions/services/watchdog/entry.py` | 同上 |
+| web | `extensions/services/web/server.py` | 同上 |
+| model_service | `extensions/services/model_service/entry.py` | 同上 |
+| logs | `extensions/services/logs/server.py` | 同上 |
+| audit | `extensions/services/audit/server.py` | 同上 |
+| kite_console | `extensions/services/kite_console/server.py` | 同上 |
+
+每个模块的改动：
+1. 参数更新：`retry_delay = 0.3` → `0.5`，`max_delay = 5.0` → `10.0`，删除 `max_retries = 10`
+2. 增加 Jitter：`import random`，sleep 时加 `retry_delay * 0.2 * random.random()`
+3. 错误分类：
+   - never：4001, 4003, 4004, 1008, 4010
+   - cooldown：4020（固定 10s，最多 5 次）
+   - standard：4002, 4011, 4012, 其他
+4. 删除 max_retries 上限
+
+### 6.4 JS 前端端变更（3 个文件）
+
+| 服务 | 文件 | 变更内容 |
+|------|------|---------|
+| evol | `extensions/services/evol/static/js/kernel-client.js` | 统一重连参数 + 三档策略 |
+| kite_console | `extensions/services/kite_console/static/js/kernel-client.js` | 同上 |
+| web | `extensions/services/web/static/js/kernel-client.js` | 同上 |
+
+每个文件的改动：
+1. 参数更新：`maxReconnectDelay = 30000/10000` → `15000`，增长因子 `1.5` → `2`，新增 `jitterRatio = 0.2`
+2. 新增属性：`lastCloseCode = null`，`cooldownAttempts = 0`
+3. `_scheduleReconnect` 重写：按错误码分三档处理
+4. Web 端补齐 `fatalError` 机制
+
+---
+
+## 七、时间线示例
+
+### 场景 A：网络抖动，3s 后恢复
+
+```
+T+0s     模块 WS 断开
+T+3s     模块重连成功
+         → Kernel 未发任何通知（5s 防抖内）
+         → 对所有模块完全透明，无感知
+```
+
+### 场景 B：Launcher 崩溃，Watchdog 自动恢复
+
+```
+T+0s     Launcher 崩溃，WS 断开
+T+5s     Kernel 广播 module.offline (launcher)
+         Watchdog 标记，不行动
+T+35s    Kernel 触发优雅退出
+         Watchdog 判断：无 module.exiting → 异常退出 → 启动新实例
+         其他模块收到 module.shutdown → 优雅退出
+T+37s    新实例启动，清理残留（Watchdog → 普通模块 → Kernel）
+T+40s    新实例完全就绪
+```
+
+### 场景 C：模块 Ping 连续超时
+
+```
+T+0s     Kernel 发送 Ping
+T+5s     模块未响应，超时计数 = 1
+T+10s    Kernel 发送 Ping
+T+15s    模块未响应，超时计数 = 2
+T+20s    Kernel 发送 Ping
+T+25s    模块未响应，超时计数 = 3
+         → Kernel 强制断开连接（code 4012）
+         → 模块进入 standard 重连流程
+```
+
+### 场景 D：速率限制触发
+
+```
+T+0s     模块快速重连 20 次
+T+10s    第 21 次认证请求
+         → Kernel 返回 4020（速率限制）
+         → 模块进入 cooldown 策略，等待 10s
+T+20s    第 1 次 cooldown 重试
+         → 仍在限制窗口内，再次 4020
+T+30s    第 2 次 cooldown 重试
+         → 限制窗口过期，认证成功
+```
+
+---
+
+## 八、兼容性与迁移
+
+### 8.1 向后兼容
+
+- 旧错误码在过渡期内保持兼容（Kernel 同时接受新旧码）
+- 客户端优先处理新码，回退到旧码逻辑
+
+### 8.2 迁移步骤
+
+1. **第一阶段**：Kernel 端实施（错误码迁移 + Ping 超时 + 握手超时）
+2. **第二阶段**：Python 模块端实施（重连参数统一 + 三档策略）
+3. **第三阶段**：JS 前端端实施（重连参数统一 + 三档策略）
+4. **第四阶段**：Relay 端实施（错误码迁移）
+5. **第五阶段**：移除旧码兼容逻辑
+
+---
+
+## 九、监控与可观测性
+
+### 9.1 连接质量指标
+
+| 指标 | 查询方式 | 用途 |
+|------|---------|------|
+| Ping 延迟 | `kernel.get_connection_stats` | 网络质量评估 |
+| 超时次数 | 同上 | 连接稳定性 |
+| 重连次数 | 模块日志 | 故障频率 |
+| 模块状态 | `registry.list_modules` | 可用性监控 |
+
+### 9.2 日志规范
+
+| 事件 | 日志格式 | 级别 |
+|------|---------|------|
+| 认证失败 | `[module] 致命错误 (code {code})，退出` | ERROR |
+| 速率限制 | `[module] 速率限制，{delay}s 后重试 ({attempt}/{max})` | WARN |
+| Ping 超时 | `[kernel] {module_id} ping timeout {count} times` | WARN |
+| 连接被替换 | `[kernel] Closed old connection for {module_id}` | INFO |
+| 防抖取消 | `[kernel] {module_id} reconnected within debounce window` | INFO |
+
+---
+
+## 十、不做的事
+
+- ❌ 不抽公共函数/共享库（遵守零共享代码依赖原则）
+- ❌ 不改变 WebSocket 协议本身（仍使用 JSON-RPC 2.0）
+- ❌ 不引入外部依赖（如 Redis、消息队列）
+- ❌ 不改变模块间通信模式（仍通过 Kernel 中转）
+
+---
+
+## 十一、后续优化方向
+
+1. **自适应退避**：根据历史重连成功率动态调整退避参数
+2. **连接池**：支持模块多连接（负载均衡、故障转移）
+3. **断线预测**：基于 Ping 延迟趋势预测即将断线的连接
+4. **健康状态分级**：支持 healthy/degraded/unhealthy 三级状态
+5. **连接质量评分**：综合延迟、超时、重连频率计算连接质量分数

package/docs/WebSocket/350/277/236/346/216/245/351/237/247/346/200/247/346/226/271/346/241/210.md

@@ -0,0 +1,169 @@
+# Kite WebSocket 连接韧性方案
+
+> 状态：待实施
+> 创建时间：2026-03-04
+
+## 背景
+
+当前所有模块连接 Kernel 的 WebSocket 断开后直接 `sys.exit(1)` 退出，没有重连能力。Launcher 异常终止（崩溃、被 kill）后，所有子进程变成孤儿进程并连锁崩溃。残留清理顺序不合理（先杀 Kernel 导致其他模块连锁退出）。
+
+本方案从三个层面解决：WebSocket 重连机制、Launcher 异常终止善后、残留清理顺序。
+
+---
+
+## 1. WebSocket 断开重连机制
+
+### 1.1 Kernel 侧 — 模块状态机
+
+Kernel 为每个模块维护生命周期状态：
+
+```
+offline → connected → registered → ready
+            ↑                        │
+            └────────────────────────┘  (WS 断开 → 5s 防抖 → offline，重连后从 connected 重走)
+```
+
+| 状态 | 含义 |
+|---|---|
+| **offline** | 未连接（初始 / WS 断开防抖后确认离线） |
+| **connected** | WS 已连接，尚未完成注册 |
+| **registered** | subscribe + register 完成 |
+| **ready** | 已发布 module.ready，可提供服务 |
+
+**防抖机制：** 模块 WS 断开后，Kernel 不立即标记 offline，而是等待 **5s**。如果模块在 5s 内重连成功，则状态直接从断开前的状态继续，不发送 `module.offline` 事件。超过 5s 未重连，才标记 `offline` 并广播通知。
+
+**状态变更通知：** 当模块状态变更为 `offline` 或 `ready` 时，Kernel 向所有模块广播事件（`module.offline` / `module.ready`）。这些属于系统级事件，Kernel 自动推送给所有已连接模块，不需要模块显式订阅。
+
+**RPC 路由保护：** 外部通过 Kernel 调用某模块的 RPC 时，Kernel 检查目标模块状态。如果不是 `ready`，立即返回错误（如 `"error": "module_offline"`），不等待超时。
+
+**`module.ready` 是可重复的生命周期事件：** 模块可能经历多次 `offline → ready` 循环（网络抖动、Kernel 重启等）。各模块应持续处理 `module.ready` / `module.offline` 事件，维护对其他模块的可用性认知。
+
+### 1.2 客户端模块 — 重连策略
+
+适用于所有连接 Kernel 的模块（Launcher、Watchdog、普通模块）。
+
+**重连参数：**
+
+- 指数退避：初始 0.3s，翻倍增长，上限 5s
+- 最多 10 次重试，总耗时约 34s
+- 具体间隔：`0.3 → 0.6 → 1.2 → 2.4 → 4.8 → 5 → 5 → 5 → 5 → 5`
+
+**重连成功后的握手：** 重新执行完整流程 — subscribe → register → publish module.ready。模块内部业务状态保持不变，不需要重置。
+
+**首次连接失败：** 与重连相同的退避策略和次数限制。超过后 `sys.exit(1)`。
+
+**不重连的情况：**
+
+- 收到 `module.shutdown` 事件后断开（被主动关闭）
+- 认证失败（token 无效，Kernel 返回 4001/4003 等 WebSocket 关闭码）
+
+**实现约束：** 由于零共享代码原则，每个模块独立实现重连逻辑。Python 模块可参考相同模式，Node.js/Binary 模块自行实现等效逻辑。
+
+---
+
+## 2. Launcher 异常终止后的处理
+
+### 2.1 Kernel 的行为
+
+**两阶段响应：**
+
+| 阶段 | 时机 | 动作 |
+|---|---|---|
+| 防抖等待 | Launcher WS 断开后 0~5s | 等待重连，不通知 |
+| 离线通知 | 5s 未重连 | 广播 `module.offline (launcher)` |
+| 重连窗口 | 5s~35s | 继续等待 Launcher 重连 |
+| 优雅退出 | 35s 未重连 | 触发全实例优雅退出流程 |
+
+**优雅退出流程（35s 触发）：**
+
+1. Kernel 向所有模块发布 `module.shutdown`（reason: `launcher_lost`）
+2. 等待各模块优雅退出（保存状态、清理资源、ack）
+3. 等待超时后，Kernel 自己退出
+
+### 2.2 Watchdog 的行为
+
+```
+Launcher WS 断开
+  → [0~5s]   Kernel 防抖等待
+  → [5s]     Kernel 广播 module.offline (launcher)
+  →          Watchdog 收到，标记状态，不做决策（可能只是网络抖动）
+  → [5~35s]  Kernel 继续等待 Launcher 重连
+  → [35s]    Kernel 触发优雅退出，发布 module.shutdown (reason: launcher_lost)
+  →          Watchdog 收到 module.shutdown，此时判断：
+               有 module.exiting (launcher) → 正常退出 → 跟随退出
+               无 module.exiting (launcher) → 异常退出 → 启动新 Kite 实例
+```
+
+**正常 vs 异常退出的判断依据：**
+
+- **正常退出：** Launcher 在断开前发送过 `module.exiting` 事件（包括 ESC、Ctrl+C、q 等主动退出）
+- **异常退出：** Launcher 直接断开，没有 `module.exiting`（崩溃、被 kill、意外断电）
+
+**ESC 退出的改造：** 当前 ESC 调用 `os._exit(0)` 什么都不发。需要改为：先发送 `module.exiting` 事件，再退出。这样 Kernel/Watchdog 能识别为正常退出。
+
+**Watchdog 启动新实例：**
+
+- 执行 `python main.py`（或等效命令）启动全新 Kite 实例
+- 新实例自动清理旧实例的残留进程
+- 整个恢复耗时约 2~3s（不含 35s 等待窗口）
+
+### 2.3 Launcher 重连成功的情况
+
+如果 Launcher 在 35s 内重连成功：
+
+- Kernel 取消优雅退出计划
+- 如果已发过 `module.offline (launcher)`（超过 5s），则再发一次 Launcher 的 `module.ready`
+- 各模块（包括 Watchdog）清除之前标记的状态
+- 整个实例恢复正常运行
+
+---
+
+## 3. 残留清理顺序
+
+新 Launcher 启动时清理上一个实例的残留进程，按以下顺序：
+
+| 顺序 | 模块 | 理由 |
+|---|---|---|
+| 1 | Watchdog | 防止清理过程中 Watchdog 自动恢复其他模块 |
+| 2 | 普通模块 | 顺序无所谓（assistant、backup、web 等） |
+| 3 | Kernel | 最后杀，防止连锁退出导致其他模块状态不可控 |
+
+**实现方式：** 在清理逻辑（`_cleanup_file`）中对 records 排序，不改 `processes.json` 的写入格式。排序规则：`watchdog` 排首位，`kernel` 排末位，其余保持原序。
+
+---
+
+## 整体时间线示例
+
+### 场景 A：Launcher 网络抖动，3s 后恢复
+
+```
+T+0s     Launcher WS 断开
+T+3s     Launcher 重连成功
+         → Kernel 未发任何通知（5s 防抖内）
+         → 对所有模块完全透明，无感知
+```
+
+### 场景 B：Launcher 崩溃，无法恢复
+
+```
+T+0s     Launcher 崩溃，WS 断开
+T+5s     Kernel 广播 module.offline (launcher)
+         Watchdog 标记，不行动
+T+35s    Kernel 触发优雅退出
+         Watchdog 判断：无 module.exiting → 异常退出 → 启动新实例
+         其他模块收到 module.shutdown → 优雅退出
+T+37s    新实例启动，清理残留（Watchdog → 普通模块 → Kernel）
+T+40s    新实例完全就绪
+```
+
+### 场景 C：用户按 ESC 退出
+
+```
+T+0s     ESC 按下
+         Launcher 发送 module.exiting → 退出
+T+5s     Kernel 广播 module.offline (launcher)
+T+35s    Kernel 触发优雅退出
+         Watchdog 判断：有 module.exiting → 正常退出 → 跟随退出
+         所有模块优雅退出
+         → 不启动新实例
+```