@agentunion/kite 1.5.0 → 1.6.0

package/docs/WebSocket/351/207/215/350/277/236/346/234/272/345/210/266/346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,169 @@
+# WebSocket 连接韧性与重连机制 - 测试报告
+
+## 测试概览
+
+**测试日期**: 2026-03-15
+**测试范围**: WebSocket 连接韧性与重连机制完整方案
+**测试类型**: 单元测试 + 集成测试
+
+---
+
+## 单元测试结果
+
+✅ **全部通过** (14/14)
+
+### 测试覆盖
+
+#### 1. 重连策略逻辑 (6 项)
+- ✅ never 策略错误码验证
+- ✅ cooldown 策略错误码验证
+- ✅ standard 指数退避序列
+- ✅ Jitter 范围验证
+- ✅ cooldown 固定延迟
+- ✅ 重连成功重置计数器
+
+#### 2. 错误码迁移 (2 项)
+- ✅ 旧码到新码映射
+- ✅ 错误码区段划分
+
+#### 3. Ping/Pong 超时 (3 项)
+- ✅ 连续超时计数
+- ✅ Pong 重置计数
+- ✅ 4012 错误码验证
+
+#### 4. 模块状态机 (3 项)
+- ✅ 状态转换流程
+- ✅ RPC 路由保护
+- ✅ 断开连接状态重置
+
+---
+
+## 集成测试
+
+### 测试文件
+
+1. **test_websocket_integration.py** - 完整集成测试套件
+   - 需要 Kernel 服务器运行
+   - 测试实际 WebSocket 连接行为
+   - 验证错误码、状态机、重连机制
+
+2. **verify_reconnect_integration.py** - 快速验证脚本
+   - 可在运行中的 Kite 系统上执行
+   - 验证核心功能是否正常工作
+   - 适合日常回归测试
+
+### 运行方式
+
+```bash
+# 单元测试（无需 Kernel 运行）
+python -m pytest tests/test_reconnect_mechanism.py -v
+
+# 完整集成测试（需要 Kernel 运行）
+python -m pytest tests/test_websocket_integration.py -v
+
+# 快速验证（需要 Kernel 运行）
+python tests/verify_reconnect_integration.py
+```
+
+---
+
+## 实施总结
+
+### 已完成的变更
+
+#### 阶段 1: 错误码迁移
+- ✅ Kernel: 4029→4020, 4003→4002, 4000→4010, 4010→4011
+- ✅ Relay (evol/kite_console/web): 4029→4020, 4003→4004
+
+#### 阶段 2: Python 模块重连机制统一 (7 个模块)
+- ✅ backup, watchdog, web, model_service, logs, audit, kite_console
+- ✅ 参数: 0.5s 初始, 10s 上限, ×2 增长, Jitter 0.2
+- ✅ 三档策略: never/standard/cooldown
+
+#### 阶段 3: JS 前端重连机制统一 (3 个文件)
+- ✅ evol, kite_console, web 的 kernel-client.js
+- ✅ 参数: 1s 初始, 15s 上限, ×2 增长, Jitter 0.2
+- ✅ 三档策略: never/standard/cooldown
+
+#### 阶段 4: Ping/Pong 超时强断
+- ✅ 新增 4012 错误码
+- ✅ 连续 3 次超时 → 强制断开
+- ✅ 收到 Pong 重置计数
+
+#### 阶段 5: 模块状态机补全
+- ✅ Registry 增加 module_states 字典
+- ✅ 状态: offline/connected/registered/ready
+- ✅ RPC 路由保护: 检查目标模块状态
+- ✅ 非 ready 状态 → 返回 -32001 错误
+
+---
+
+## 代码变更统计
+
+### 修改的文件
+
+**Kernel 核心** (4 个文件)
+- kernel/server.py
+- kernel/event_hub.py
+- kernel/registry_store.py
+- kernel/rpc_router.py
+
+**Python 模块** (7 个文件)
+- extensions/services/backup/entry.py
+- extensions/services/watchdog/entry.py
+- extensions/services/web/server.py
+- extensions/services/model_service/entry.py
+- extensions/services/logs/server.py
+- extensions/services/audit/server.py
+- extensions/services/kite_console/server.py
+
+**Relay 服务** (3 个文件)
+- extensions/services/evol/relay.py
+- extensions/services/kite_console/relay.py
+- extensions/services/web/relay.py
+
+**JS 前端** (3 个文件)
+- extensions/services/evol/static/js/kernel-client.js
+- extensions/services/kite_console/static/js/kernel-client.js
+- extensions/services/web/static/js/kernel-client.js
+
+**测试文件** (3 个文件)
+- tests/test_reconnect_mechanism.py (新增)
+- tests/test_websocket_integration.py (新增)
+- tests/verify_reconnect_integration.py (新增)
+
+**总计**: 20 个文件修改/新增
+
+---
+
+## 下一步
+
+### 建议的后续工作
+
+1. **运行集成测试**
+   - 启动 Kite 系统
+   - 执行 verify_reconnect_integration.py
+   - 观察日志输出，验证行为
+
+2. **压力测试**
+   - 模拟大量模块同时重连
+   - 测试速率限制是否生效
+   - 验证 Ping 超时强断机制
+
+3. **文档归档**
+   - 归档旧文档到 docs-archive/websocket-evolution/
+   - 更新 docs/INDEX.md
+   - 创建归档目录 README
+
+4. **监控与观察**
+   - 在生产环境观察新机制运行情况
+   - 收集重连延迟数据
+   - 监控错误码分布
+
+---
+
+## 参考文档
+
+- **设计文档**: docs/WebSocket连接韧性与重连机制完整方案.md
+- **旧文档**: docs/WebSocket连接韧性方案.md (待归档)
+- **旧文档**: docs/WebSocket重连退避机制方案.md (待归档)

package/docs/WebSocket/351/207/215/350/277/236/351/200/200/351/201/277/346/234/272/345/210/266/346/226/271/346/241/210.md

@@ -0,0 +1,394 @@
+# WebSocket 重连退避机制方案
+
+## 一、背景与目标
+
+Kite 框架中 Python 模块（内部）和 JS 前端（远程）的 WebSocket 重连退避参数不一致：
+
+| 参数 | Python 旧值 | JS 旧值 (Evol/Console) | JS 旧值 (Web) |
+|------|------------|----------------------|--------------|
+| 初始延迟 | 0.3s | 1s | 1s |
+| 增长因子 | ×2 | ×1.5 | ×1.5 |
+| 最大延迟 | 5s | 30s | 10s |
+| 最大重试 | 10 次 | 无限 | 无限 |
+| Jitter | 无 | 无 | 无 |
+| 致命错误 | 仅 4001/4003 | 4001/4003 + fatal | 无 |
+| 速率限制处理 | 无 | 无 | 无 |
+
+**目标：**
+
+1. 统一 Python 端和 JS 端的重连退避机制
+2. 引入三档重连策略（never / standard / cooldown），按错误类型分类处理
+3. 重整错误码区段，消除语义重载
+4. 增加 Jitter 防惊群
+5. 遵守零共享代码依赖原则——每个模块内联自己的退避逻辑，参数值保持一致
+
+---
+
+## 二、错误码体系
+
+### 2.1 设计原则
+
+- 1000-1011：使用标准 WebSocket 关闭码，语义不变
+- 4001-4009：**认证类**（Authentication）
+- 4010-4019：**连接管理类**（Connection）
+- 4020-4029：**流控类**（Flow Control）
+- 每个区段预留扩展位
+
+### 2.2 完整错误码表
+
+#### 标准 WebSocket 关闭码
+
+| 码值 | 含义 | 重连策略 | 发送方 |
+|------|------|---------|--------|
+| 1000 | 正常关闭 | never | Kernel（优雅关闭完成） |
+| 1001 | 服务器关闭 | standard | 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 状态倒计时到期 |
+
+#### 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** | 速率限制，归入流控区段 |
+
+---
+
+## 三、三档重连策略
+
+### 3.1 策略总览
+
+| 策略 | 适用场景 | 行为 |
+|------|---------|------|
+| **never** | 永久性错误，重试无意义 | 立即停止，不重连 |
+| **standard** | 临时性错误，可自动恢复 | 指数退避 + Jitter |
+| **cooldown** | 速率限制，需等待冷却 | 固定等待，有限重试 |
+
+### 3.2 错误码 → 策略映射
+
+| 策略 | 错误码 |
+|------|--------|
+| never | 1000, 1008, 4001, 4003, 4004, 4010 |
+| standard | 1001, 1011, 4002, 4011, 网络断开（无码） |
+| cooldown | 4020 |
+
+### 3.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（停止重连）。
+
+### 3.4 重连成功后的重置
+
+连接成功并完成认证后，重置所有计数器：
+
+- `attempt = 0`
+- `retry_delay = initial_delay`
+- `cooldown_attempts = 0`
+
+---
+
+## 四、变更清单
+
+### 4.1 Kernel 端（错误码发送方）
+
+| 文件 | 行 | 变更 |
+|------|-----|------|
+| `kernel/server.py` | 160 | `code=4029` → `code=4020` |
+| `kernel/server.py` | 179 | `code=4001` 不变（格式错误，原 -32600 错误码保留） |
+| `kernel/server.py` | 193 | `code=4001` 不变 |
+| `kernel/server.py` | 209 | `code=4003` → `code=4002`（超时） |
+| `kernel/server.py` | 213 | `code=4001` 不变（异常） |
+| `kernel/event_hub.py` | 127 | `code=4000` → `code=4010`（连接被替换） |
+| `kernel/event_hub.py` | 383 | `code=4010` → `code=4011`（队列压力） |
+
+### 4.2 Relay 端（错误码发送方）
+
+| 文件 | 变更 |
+|------|------|
+| `extensions/services/evol/relay.py` | 4029 → 4020，4003(MFA) → 4004，4000(协议错误) 保留语义不变 |
+| `extensions/services/kite_console/relay.py` | 同上 |
+| `extensions/services/web/relay.py` | 同上（如有） |
+
+> 注意：Relay 中 `code=4000` 用于协议错误（缺少字段、超时等），这些是 Relay 层握手协议错误，
+> 与 Kernel 的 4000（连接被替换）是不同场景。Relay 的 4000 保持不变，不迁移。
+
+### 4.3 Python 模块端（7 个模块，统一改法）
+
+| 模块 | 文件 | `_ws_loop` 位置 |
+|------|------|----------------|
+| backup | `extensions/services/backup/entry.py` | 行 399-431 |
+| watchdog | `extensions/services/watchdog/entry.py` | 行 415-452 |
+| web | `extensions/services/web/server.py` | 行 269-311 |
+| model_service | `extensions/services/model_service/entry.py` | 行 390-422 |
+| logs | `extensions/services/logs/server.py` | 行 106-189 |
+| audit | `extensions/services/audit/server.py` | 行 95-176 |
+| kite_console | `extensions/services/kite_console/server.py` | 行 595-633 |
+
+每个模块的改动：
+
+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. **错误分类**：
+   - `_is_auth_failure` 扩展判断码：4001, 4003, 4004, 1008, 4010 → never
+   - 新增 4020 判断 → cooldown（固定 10s，最多 5 次）
+   - 4002 不再视为致命错误 → standard
+   - 其他错误 → standard
+4. **删除 max_retries 上限**：standard 策略无限重试
+
+### 4.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. **参数更新**：
+   - `reconnectDelay = 1000` → `1000`（不变）
+   - `maxReconnectDelay = 30000/10000` → `15000`
+   - 增长因子 `1.5` → `2`
+   - 新增 `jitterRatio = 0.2`
+2. **新增属性**：
+   - `lastCloseCode = null`（在 `ws.onclose` 中记录关闭码）
+   - `cooldownAttempts = 0`
+3. **`_scheduleReconnect` 重写**：按错误码分三档处理
+4. **Web 端补齐**：`fatalError` 机制（被三档策略覆盖）
+5. **重连成功重置**：`reconnectAttempts = 0`，`cooldownAttempts = 0`，`reconnectDelay = 1000`
+
+---
+
+## 五、实现参考
+
+> 遵守零共享代码依赖原则，以下为各模块内联实现的参考逻辑，不作为共享代码。
+
+### 5.1 Python 模块参考逻辑
+
+```python
+import random
+
+# ── 重连参数 ──
+RETRY_INITIAL = 0.5
+RETRY_MAX = 10.0
+RETRY_FACTOR = 2
+RETRY_JITTER = 0.2
+COOLDOWN_DELAY = 10.0
+COOLDOWN_MAX_ATTEMPTS = 5
+
+# never 类错误码
+FATAL_CODES = (4001, 4003, 4004, 1008, 4010)
+# cooldown 类错误码
+COOLDOWN_CODES = (4020,)
+
+
+def _get_close_code(e: Exception) -> int:
+    """从 websockets 异常中提取关闭码"""
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        return getattr(e.rcvd, 'code', 0)
+    return 0
+
+
+async def _ws_loop(token, kernel_port, t0):
+    retry_delay = RETRY_INITIAL
+    attempt = 0
+    cooldown_attempts = 0
+
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port, t0)
+            # 成功后重置
+            retry_delay = RETRY_INITIAL
+            attempt = 0
+            cooldown_attempts = 0
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down:
+                return
+            code = _get_close_code(e)
+
+            # never: 永不重连
+            if code in FATAL_CODES:
+                print(f"[module] 致命错误 (code {code})，退出")
+                _exit(1)
+                return
+
+            # cooldown: 速率限制
+            if code in COOLDOWN_CODES:
+                cooldown_attempts += 1
+                if cooldown_attempts >= COOLDOWN_MAX_ATTEMPTS:
+                    print(f"[module] 速率限制重试 {COOLDOWN_MAX_ATTEMPTS} 次，退出")
+                    _exit(1)
+                    return
+                print(f"[module] 速率限制，{COOLDOWN_DELAY}s 后重试 ({cooldown_attempts}/{COOLDOWN_MAX_ATTEMPTS})")
+                await asyncio.sleep(COOLDOWN_DELAY)
+                continue
+
+            # standard: 指数退避 + jitter
+            attempt += 1
+            jitter = retry_delay * RETRY_JITTER * random.random()
+            sleep_time = retry_delay + jitter
+            print(f"[module] 连接错误: {e}, {sleep_time:.1f}s 后重试 (attempt {attempt})")
+            await asyncio.sleep(sleep_time)
+            retry_delay = min(retry_delay * RETRY_FACTOR, RETRY_MAX)
+```
+
+### 5.2 JS 前端参考逻辑
+
+```javascript
+// ── 重连参数 ──
+const RETRY_INITIAL = 1000;
+const RETRY_MAX = 15000;
+const RETRY_FACTOR = 2;
+const RETRY_JITTER = 0.2;
+const COOLDOWN_DELAY = 10000;
+const COOLDOWN_MAX_ATTEMPTS = 5;
+
+// never 类错误码
+const FATAL_CODES = [1000, 1008, 4001, 4003, 4004, 4010];
+// cooldown 类错误码
+const COOLDOWN_CODES = [4020];
+
+_scheduleReconnect() {
+    if (this.fatalError || this.reconnectTimer) return;
+
+    const code = this.lastCloseCode;
+
+    // never: 永不重连
+    if (FATAL_CODES.includes(code)) {
+        this.fatalError = true;
+        if (this.onConnectionChange) {
+            this.onConnectionChange('error', '连接失败（永久性错误）');
+        }
+        return;
+    }
+
+    let delay;
+
+    // cooldown: 速率限制
+    if (COOLDOWN_CODES.includes(code)) {
+        this.cooldownAttempts = (this.cooldownAttempts || 0) + 1;
+        if (this.cooldownAttempts >= COOLDOWN_MAX_ATTEMPTS) {
+            this.fatalError = true;
+            if (this.onConnectionChange) {
+                this.onConnectionChange('error', '速率限制，停止重连');
+            }
+            return;
+        }
+        delay = COOLDOWN_DELAY;
+    } else {
+        // standard: 指数退避 + jitter
+        this.reconnectAttempts++;
+        const base = Math.min(
+            RETRY_INITIAL * Math.pow(RETRY_FACTOR, this.reconnectAttempts - 1),
+            RETRY_MAX
+        );
+        const jitter = base * RETRY_JITTER * Math.random();
+        delay = base + jitter;
+    }
+
+    if (this.onConnectionChange) {
+        this.onConnectionChange('reconnecting',
+            `正在重连... (${this.reconnectAttempts})`);
+    }
+
+    this.reconnectTimer = setTimeout(() => {
+        this.reconnectTimer = null;
+        this.connect().catch(err => {
+            console.error('[KernelClient] Reconnect failed:', err);
+        });
+    }, delay);
+}
+```
+
+---
+
+## 六、变更前后对比
+
+| 参数 | Python 旧 | JS 旧 (Evol) | JS 旧 (Web) | Python 新 | JS 新 |
+|------|-----------|-------------|-------------|-----------|-------|
+| 初始延迟 | 0.3s | 1s | 1s | **0.5s** | **1.0s** |
+| 增长因子 | ×2 | ×1.5 | ×1.5 | **×2** | **×2** |
+| 最大延迟 | 5s | 30s | 10s | **10s** | **15s** |
+| 最大重试 | 10 次 | 无限 | 无限 | **无限** | **无限** |
+| Jitter | 无 | 无 | 无 | **0.2** | **0.2** |
+| 致命错误码 | 4001/4003 | 4001/4003 | 无 | **4001/4003/4004/1008/4010** | **同左** |
+| 速率限制 | 无 | 无 | 无 | **cooldown 10s×5** | **cooldown 10s×5** |
+
+---
+
+## 七、不做的事
+
+- **不抽公共函数/共享库**：遵守零共享代码依赖原则，每个模块内联自己的退避逻辑
+- **不改 Kernel 核心架构**：仅修改错误码数值和 Relay 的 MFA 关闭码
+- **不做每错误码独立参数矩阵**：三档策略足够覆盖所有场景，过细增加维护成本