@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/250/241/345/235/227/345/244/232/350/277/236/346/216/245/346/216/247/345/210/266/347/255/226/347/225/245.md

@@ -0,0 +1,220 @@
+# 模块多连接控制策略
+
+## 概述
+
+远程模块通过 Gateway 接入时，面临传输延迟、性能瓶颈和连接可靠性问题。本方案支持模块与 Kernel 之间建立多条 WebSocket 连接（slot），从传输层加固健壮性和吞吐量。
+
+**核心原则：连接是业务无关的传输通道，所有连接完全等效，状态维系在模块上而非连接上。**
+
+## 术语
+
+| 术语 | 含义 |
+|------|------|
+| slot | 一条物理 WebSocket 连接，编号从 0 开始 |
+| slot 0 | 主连接，走标准认证流程，重建 session |
+| slot N (N>0) | 附加连接，走 slot token 认证，不重建 session |
+| slot token | 一次性令牌，Kernel 通过 `system.connection.offer` 事件下发 |
+| 保序集合 | 模块声明的事件 key 分组，同组事件绑定同一 slot 发送 |
+| 弹性模式 | 模块在 `module.ready` 中声明 `connection_elastic: true`，允许 Kernel 动态增减连接 |
+
+## 配置
+
+模块在 `module.md` frontmatter 中声明：
+
+```yaml
+max_connections: 3   # 最大连接数，默认 1（单连接，向后兼容）
+```
+
+模块在 `registry.register` 时传递两个字段：
+
+- `max_connections` — 最大连接数
+- `connection_elastic` — 是否启用弹性模式（true/false）
+
+这两个字段存入注册中心。同时 `module.ready` 事件的 data 中也声明 `connection_elastic`，Kernel 在 `set_ready()` 时提取并更新注册中心。
+
+## 连接生命周期
+
+### 建立
+
+1. **slot 0**：模块通过标准 token 认证连接 Kernel，流程与现有完全一致
+2. Kernel 从 `registry.modules[mid]["max_connections"]` 读取目标连接数
+3. 若 `max_connections > 1`，Kernel 生成 slot token 并通过 `system.connection.offer` 事件通知模块
+4. 模块收到 offer 后，使用 slot token 建立 slot N 连接
+
+### 认证
+
+slot token 认证流程：
+
+1. `ws_endpoint` 中 `verify_token` 返回 None 后，尝试 `verify_slot_token(token)`
+2. 返回 `(module_id, slot)` → 附加连接模式
+3. auth 响应返回 `{"ok": true, "session_id": ..., "seq": ..., "slot": slot}`
+4. 附加 slot 不触发 debounce 取消、不更新 launcher_connected、不重置 session
+
+### 断开
+
+- 部分 slot 断开 → 不触发 debounce，不发 `module.offline`；非弹性模式发 recovery offer
+- 所有 slot 断开 → 触发现有 debounce 逻辑 → 5 秒后发 `module.offline`
+
+## 双层队列架构
+
+```
+事件源 → 共享队列(mid) → 分发器(_sender_loop) → slot 队列(mid, slot) → slot 发送器(_slot_sender) → WebSocket
+```
+
+### 分发器 (_sender_loop)
+
+- 从共享队列取消息 → 添加 seq → `_pick_slot` 选 slot → 放入 slot 队列
+- 永不 `await send`，不阻塞
+- 压缩逻辑保留在分发器中（弹性模块 critical 级别时压缩后分发）
+
+### slot 发送器 (_slot_sender)
+
+- 每个 slot 独立协程
+- 从 slot 队列取消息 → `asyncio.wait_for(ws.send_text(raw), timeout=10.0)`
+- 超时则关闭该 slot
+
+## 保序机制
+
+模块通过 `kernel.set_ordering_groups` RPC 声明保序集合：
+
+```json
+{
+  "groups": [
+    {"name": "session", "keys": ["session.started", "session.ended", "session.updated"]}
+  ]
+}
+```
+
+### 分发规则
+
+1. 查 `(mid, key)` → OrderingGroup
+2. 有绑定 slot 且存活 → 用该 slot
+3. 无绑定 → 轮询选 slot，绑定
+4. 不在任何集合 → 轮询（round-robin）
+
+### 绑定释放
+
+slot_sender 发送完后检查 `seq == group.last_enqueued_seq` → 是则释放绑定。
+
+## Offer / Release 协议
+
+`system.connection.offer` 和 `system.connection.release` 是**点对点系统事件**：
+
+- **不需要模块订阅**，Kernel 直接发给目标模块
+- **只发给 `max_connections > 1` 的模块**，单连接模块永远不会收到
+- 模块侧在事件处理代码中识别这两个事件类型即可（与 `system.ping` 同理）
+
+### system.connection.offer
+
+Kernel → 模块，批量下发 slot token：
+
+```json
+{
+  "event": "system.connection.offer",
+  "data": {
+    "slots": {
+      "1": {"token": "abc123...", "expires_in": 30},
+      "2": {"token": "def456...", "expires_in": 30}
+    }
+  }
+}
+```
+
+### system.connection.release
+
+Kernel → 模块，请求释放指定 slot：
+
+```json
+{
+  "event": "system.connection.release",
+  "data": {
+    "slots": [2],
+    "reason": "idle_shrink",
+    "grace_period": 2
+  }
+}
+```
+
+模块收到后应在 grace_period 内主动关闭对应 slot。超时 Kernel 强制关闭。
+
+## 弹性模式
+
+模块在 `module.ready` 中声明 `connection_elastic: true`：
+
+- **非弹性（false）**：Kernel 立即发 offer 建满所有连接，断线立即补充，永不 release
+- **弹性（true）**：Kernel 按需扩容，空闲收缩
+
+### 连接触发机制
+
+弹性模式下，Kernel 通过以下场景触发 offer：
+
+**场景1：路由时无备用连接**
+
+Kernel 在路由消息（事件分发或 RPC 转发）到目标模块时：
+
+1. 选中 slot X 发送消息
+2. 检查该模块其他 slot 中有几个是**空闲的**（不在发送阻塞中）
+3. 如果空闲备用 slot == 0 且当前连接数 < max_connections → 立即 offer 新 slot
+4. 下次调用时新 slot 已就绪，避免所有连接被阻塞
+
+**场景2：队列压力升高**
+
+共享队列压力等级达到 high 或 critical 时，如果当前连接数 < max_connections → 触发 offer 扩容，增加并行发送能力缓解压力。
+
+### Slot 忙闲状态
+
+slot sender 在 `ws.send_text()` 期间标记为"发送中"（busy），发送完成后恢复"空闲"（idle）。路由时按需 offer 检查的是空闲状态，不是队列深度。
+
+### RPC 路由 slot 选择
+
+RPC 转发应选择空闲优先的 slot，而非固定取第一个 slot。
+
+### 弹性收缩
+
+- idle 30s → release 1 个最空闲 slot（避开保序绑定的 slot）
+- 间隔 30s 再 release 1 个
+- 最少保留 2 个
+
+## Slot Token 管理
+
+- 存储在 `RegistryStore._slot_tokens` 和 `_slot_token_expires`
+- 有效期 30 秒，一次性使用（验证后删除）
+- 过期清理集成在 `_dedup_loop` 中
+
+## 向后兼容
+
+- `max_connections` 默认 1，不配置的模块行为 100% 不变
+- slot 0 走现有认证路径，单连接模式退化为原逻辑
+- 保序集合不声明则不生效
+- 所有新增事件类型（`system.connection.offer`、`system.connection.release`）仅在多连接场景触发
+
+## 涉及文件
+
+| 文件 | 改动 |
+|------|------|
+| `kernel/registry_store.py` | slot token 生成/验证/清理；`connection_elastic` 存入注册中心 |
+| `kernel/event_hub.py` | 双层队列、保序集合、slot sender、slot 忙闲标记、路由时按需 offer |
+| `kernel/server.py` | 连接表变更、offer/release 点对点发送、debounce 改造 |
+| `kernel/rpc_router.py` | RPC 转发 slot 选择、路由时按需 offer |
+| `launcher/module_scanner.py` | max_connections 字段解析 |
+
+## 模块侧实现清单
+
+模块要支持多连接，需要实现以下 7 个点：
+
+| # | 关键点 | 说明 |
+|---|--------|------|
+| 1 | module.md 声明 `max_connections` | frontmatter 中添加，Launcher 解析传给 Kernel |
+| 2 | registry.register 传递 `max_connections` + `connection_elastic` | 注册时两个字段都传，存入注册中心 |
+| 3 | module.ready 声明 `connection_elastic` | ready 事件 data 中声明，Kernel `set_ready()` 时提取更新 |
+| 4 | offer handler | 收到 `system.connection.offer` 后用 slot token 建立附加 WS 连接 + recv loop |
+| 5 | release handler | 收到 `system.connection.release` 后优雅关闭指定 slot |
+| 6 | shutdown 清理 | 模块退出时关闭所有附加连接并清理 task |
+| 7 | 连接状态管理 | `_extra_ws`（slot→ws 映射）、`_extra_ws_tasks`（slot→recv task）、`_kernel_port` 缓存 |
+
+### 注意事项
+
+- `system.connection.offer/release` 是系统事件，**不需要订阅**
+- `connection_elastic: false` 的模块（如 watchdog、auth、logs）由 Kernel 一次性建满连接，断线自动补充
+- `connection_elastic: true` 的模块由 Kernel 按需扩容、空闲收缩
+- 附加连接的 recv loop 只需消费消息防缓冲区溢出，不需要处理业务逻辑