@agentunion/kite 1.5.0 → 1.6.0

package/docs//350/231/232/346/213/237/346/250/241/345/235/227/344/270/255/350/275/254/346/234/215/345/212/241/345/256/214/346/225/264/350/256/276/350/256/241.md

@@ -0,0 +1,1496 @@
+# 虚拟模块中转服务完整设计
+
+## 概述
+
+中转服务（Relay Service）是一个独立的、可复用的组件，允许远程客户端（如浏览器、移动应用）作为标准 Kite 模块接入 Kernel。通过中转服务，远程客户端可以调用任何模块的 RPC、订阅/发布事件，就像一个真正的 Kite 模块一样。
+
+## 核心特性
+
+1. **远程客户端作为标准 Kite 模块** - 可以调用任何模块的 RPC，订阅/发布事件
+2. **全 WebSocket 协议** - 配对、认证、RPC 通信全部通过 WebSocket
+3. **平滑重连** - 客户端刷新页面时，Kernel 看到的是模块一直在线
+4. **优雅退出** - 客户端关闭或超时时，中转服务代为完成优雅退出流程
+5. **独立可复用** - 可以集成到任何模块中，只需复制 `relay.py` 文件
+6. **动态 Token 管理** - 通过 Launcher 动态申请和释放 Kernel Token
+7. **多种配对方式** - 支持配对码配对和手机验证码配对
+
+## 架构设计
+
+### 整体架构
+
+```
+┌──────────────┐
+│ 远程客户端    │ (浏览器/移动应用)
+│ - 配对/认证   │
+│ - RPC 调用    │
+│ - 事件订阅    │
+└──────┬───────┘
+       │ WebSocket
+       │ /ws/relay
+       ↓
+┌──────────────┐
+│ 中转服务      │ (relay.py)
+│ - 配对管理    │
+│ - Token 申请  │
+│ - 消息转发    │
+│ - 重连管理    │
+└──────┬───────┘
+       │ RPC: launcher.request_client_token
+       ↓
+┌──────────────┐
+│ Launcher     │
+│ - Token 生成  │
+│ - 权限控制    │
+│ - Token 注册  │
+└──────┬───────┘
+       │ RPC: kernel.register_tokens
+       ↓
+┌──────────────┐
+│ Kernel       │
+│ - Token 验证  │
+│ - RPC 路由    │
+│ - 事件分发    │
+└──────────────┘
+```
+
+### 数据流
+
+```
+远程客户端 sessionStorage: session_token (如 "sess_a3f9e2")
+                          ↓
+中转服务映射表: {
+    "sess_a3f9e2": {
+        module_id: "web-client-a3f9e2",
+        kernel_ws: <WebSocket>,
+        kernel_token: "abc123...",
+        client_ws: <WebSocket>,
+        frontend_token: "tok_xxx",
+        role: "admin",
+        created_at: timestamp,
+        last_active: timestamp,
+        status: "active" | "waiting_reconnect"
+    }
+}
+                          ↓
+Kernel 注册: module_id = "web-client-a3f9e2"
+            token_map["abc123..."] = "web-client-a3f9e2"
+```
+
+### 关键设计
+
+1. **session_token 由客户端生成并持久化** - 存储在 sessionStorage/localStorage
+2. **module_id 由中转服务管理** - 基于 session_token 生成，客户端无需关心
+3. **kernel_token 由 Launcher 动态生成** - 通过 RPC 申请，用于连接 Kernel
+4. **中转服务完全控制模块生命周期** - 包括注册、重连、优雅退出、Token 释放
+5. **全 WebSocket 通信** - 配对、认证、RPC 全部通过 WebSocket
+
+## Token 管理机制
+
+### Token 类型
+
+1. **frontend_token** - 客户端认证凭证
+   - 由中转服务生成（通过 PairingManager）
+   - 存储在客户端 localStorage
+   - 有效期 30 天，快过期时自动续期
+   - 用于客户端连接中转服务时的身份验证
+
+2. **kernel_token** - Kernel 连接凭证
+   - 由 Launcher 生成
+   - 通过 `launcher.request_client_token` RPC 申请
+   - 中转服务保存在 session 映射表中
+   - 用于中转服务连接 Kernel
+   - 整个虚拟模块生命周期内有效，可多次重连使用
+
+3. **session_token** - 会话标识
+   - 由客户端生成（如 `sess_a3f9e2`）
+   - 存储在客户端 sessionStorage
+   - 用于识别重连（刷新页面时保持会话）
+
+### Token 生命周期
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 阶段 1: 配对/认证                                            │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 客户端连接中转服务                                        │
+│ 2. 客户端发送配对码/验证码                                   │
+│ 3. 中转服务验证配对码                                        │
+│ 4. 中转服务生成 frontend_token                              │
+│ 5. 中转服务生成 session_token                               │
+│ 6. 中转服务返回 frontend_token + session_token              │
+│ 7. 客户端保存到 localStorage + sessionStorage               │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 阶段 2: 申请 Kernel Token                                    │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 中转服务生成 module_id (基于 session_token)              │
+│ 2. 中转服务调用 launcher.request_client_token(module_id)    │
+│ 3. Launcher 检查权限（中转服务是否在白名单中）              │
+│ 4. Launcher 生成 kernel_token                               │
+│ 5. Launcher 调用 kernel.register_tokens 注册到 Kernel       │
+│ 6. Launcher 返回 kernel_token 给中转服务                    │
+│ 7. 中转服务保存 kernel_token 到 session 映射表              │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 阶段 3: 连接 Kernel                                          │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 中转服务使用 kernel_token 连接 Kernel                    │
+│    ws://kernel/ws?token={kernel_token}&id={module_id}       │
+│ 2. Kernel 验证 token，返回 module_id                        │
+│ 3. 中转服务注册模块到 Kernel                                │
+│ 4. 中转服务发布 module.ready 事件                           │
+│ 5. 连接建立，开始双向转发消息                               │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 阶段 4: 重连（客户端刷新页面）                               │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 客户端断开 WebSocket                                     │
+│ 2. 中转服务保持 Kernel 连接（6 秒等待）                     │
+│ 3. 客户端重新连接，发送 frontend_token + session_token      │
+│ 4. 中转服务识别重连，恢复 client_ws 引用                    │
+│ 5. 复用已有的 kernel_ws 和 kernel_token                     │
+│ 6. Kernel 看到的是模块一直在线（无感知）                    │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 阶段 5: 优雅退出                                             │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 客户端主动断开 或 超时未重连                             │
+│ 2. 中转服务发布 module.exiting 事件                         │
+│    data: {module_id, token_revoked: true}                   │
+│ 3. 中转服务发布 module.shutdown.ready 事件                  │
+│ 4. 中转服务关闭 Kernel 连接                                 │
+│ 5. 中转服务删除 session 映射                                │
+│ 6. Launcher 监听 module.exiting 事件，标记 token 失效       │
+│ 7. 客户端再次连接时，必须重新申请 kernel_token              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 配对机制
+
+### 方式 1: 配对码配对
+
+**适用场景：** 开发环境、内网环境、桌面浏览器
+
+**流程：**
+
+```
+1. 用户请求配对码
+   - 通过 Launcher UI 或命令行
+   - Launcher 调用 relay 模块的 RPC: relay.generate_pairing_code(role)
+   - relay 生成临时配对码（6 位大写字母+数字，5 分钟有效）
+   - Launcher 显示配对码给用户
+
+2. 客户端配对
+   - 客户端连接 /ws/relay
+   - 发送配对消息: {type: "pair", code: "ABC123"}
+   - 中转服务验证配对码
+   - 验证成功 → 生成 frontend_token + session_token
+   - 返回: {type: "paired", token, session_token, module_id, role}
+
+3. 配对码失效
+   - 使用后立即失效（一次性）
+   - 5 分钟后自动过期
+```
+
+**配对码格式：**
+```json
+{
+  "code": "ABC123",
+  "role": "admin",
+  "status": "pending",
+  "created_at": "2026-03-08T12:00:00Z"
+}
+```
+
+### 方式 2: 手机验证码配对
+
+**适用场景：** 生产环境、移动应用、公网访问
+
+**流程：**
+
+```
+1. 客户端请求验证码
+   - 客户端连接 /ws/relay
+   - 发送请求: {type: "request_sms", phone: "+8613800138000"}
+   - 中转服务调用短信 API 发送验证码
+   - 验证码 6 位数字，5 分钟有效
+
+2. 客户端验证
+   - 发送验证消息: {type: "verify_sms", phone: "+8613800138000", code: "123456"}
+   - 中转服务验证验证码
+   - 验证成功 → 生成 frontend_token + session_token
+   - 返回: {type: "paired", token, session_token, module_id, role}
+
+3. 角色分配
+   - 首次验证的手机号 → admin 角色
+   - 后续手机号 → 根据配置分配角色（operator/viewer）
+```
+
+**验证码记录格式：**
+```json
+{
+  "phone": "+8613800138000",
+  "code": "123456",
+  "role": "admin",
+  "status": "pending",
+  "created_at": "2026-03-08T12:00:00Z",
+  "expires_at": "2026-03-08T12:05:00Z"
+}
+```
+
+## 连接流程
+
+### 首次配对（配对码）
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │ Launcher │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. WebSocket 连接           │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │ 2. 配对消息                 │                             │
+     │ {type:"pair",code:"ABC123"} │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 3. 验证配对码               │
+     │                             │                             │
+     │                             │ 4. 生成 frontend_token      │
+     │                             │    session_token            │
+     │                             │    module_id                │
+     │                             │                             │
+     │                             │ 5. RPC: request_client_token│
+     │                             ├────────────────────────────>│
+     │                             │   {module_id: "web-client-xxx"}
+     │                             │                             │
+     │                             │                             │ 6. 生成 kernel_token
+     │                             │                             │    注册到 Kernel
+     │                             │                             │
+     │                             │ 7. 返回 kernel_token        │
+     │                             │<────────────────────────────┤
+     │                             │   {token: "abc123..."}      │
+     │                             │                             │
+     │                             │ 8. 连接 Kernel              │
+     │                             │    注册模块                 │
+     │                             │                             │
+     │ 9. 配对成功                 │                             │
+     │ {type:"paired",token,...}   │                             │
+     │<────────────────────────────┤                             │
+     │                             │                             │
+     │ 10. 保存 token 到本地       │                             │
+     │                             │                             │
+     │ 11. 连接升级为已认证状态    │                             │
+     │     可以发送 RPC 请求       │                             │
+     │                             │                             │
+```
+
+### 首次配对（手机验证码）
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │  短信API  │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. WebSocket 连接           │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │ 2. 请求验证码               │                             │
+     │ {type:"request_sms",        │                             │
+     │  phone:"+8613800138000"}    │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 3. 生成验证码               │
+     │                             │                             │
+     │                             │ 4. 发送短信                 │
+     │                             ├────────────────────────────>│
+     │                             │                             │
+     │ 5. 请求成功                 │                             │
+     │ {type:"sms_sent"}           │                             │
+     │<────────────────────────────┤                             │
+     │                             │                             │
+     │ 6. 用户收到短信             │                             │
+     │                             │                             │
+     │ 7. 提交验证码               │                             │
+     │ {type:"verify_sms",         │                             │
+     │  phone:"+8613800138000",    │                             │
+     │  code:"123456"}             │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 8. 验证验证码               │
+     │                             │                             │
+     │                             │ 9-11. 同配对码流程          │
+     │                             │ (申请 token, 连接 Kernel)   │
+     │                             │                             │
+     │ 12. 配对成功                │                             │
+     │<────────────────────────────┤                             │
+     │                             │                             │
+```
+
+### 已登录（有 token）
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │ Launcher │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. WebSocket 连接           │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │ 2. 认证消息                 │                             │
+     │ {type:"auth",               │                             │
+     │  token:"tok_xxx",           │                             │
+     │  session_token:"sess_xxx"}  │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 3. 验证 frontend_token      │
+     │                             │                             │
+     │                             │ 4. 检查 session_token       │
+     │                             │    - 不存在 → 创建新连接    │
+     │                             │    - 存在 → 恢复连接(重连)  │
+     │                             │                             │
+     │                             │ 5. 如果是新连接:            │
+     │                             │    申请 kernel_token        │
+     │                             ├────────────────────────────>│
+     │                             │                             │
+     │                             │<────────────────────────────┤
+     │                             │                             │
+     │                             │ 6. 连接 Kernel              │
+     │                             │                             │
+     │ 7. 认证成功                 │                             │
+     │ {type:"authenticated",      │                             │
+     │  module_id:"web-client-xxx"}│                             │
+     │<────────────────────────────┤                             │
+     │                             │                             │
+     │ 8. 连接升级为已认证状态    │                             │
+     │                             │                             │
+```
+
+### 刷新页面（平滑重连）
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │  Kernel  │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. 前端断开 WebSocket       │                             │
+     ├─────────────────────────X   │                             │
+     │                             │                             │
+     │                             │ 2. 检测到客户端断开         │
+     │                             │    - 标记 session 为        │
+     │                             │      "waiting_reconnect"    │
+     │                             │    - 保持 Kernel 连接       │
+     │                             │    - 启动 6 秒超时计时器    │
+     │                             │                             │
+     │ 3. 前端重新加载             │                             │
+     │    从 sessionStorage 读取   │                             │
+     │    token + session_token    │                             │
+     │                             │                             │
+     │ 4. 重新连接 /ws/relay       │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │ 5. 发送认证消息             │                             │
+     │ {type:"auth",               │                             │
+     │  token:"tok_xxx",           │                             │
+     │  session_token:"sess_xxx"}  │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 6. 识别到是重连:            │
+     │                             │    - 取消超时计时器         │
+     │                             │    - 恢复 client_ws 引用    │
+     │                             │    - 标记 session 为 active │
+     │                             │    - 复用 kernel_ws         │
+     │                             │    - Kernel 无感知          │
+     │                             │                             │
+     │ 7. 重连成功                 │                             │
+     │ {type:"reconnected",        │                             │
+     │  module_id:"web-client-xxx"}│                             │
+     │<────────────────────────────┤                             │
+     │                             │                             │
+```
+
+### 关闭标签页（优雅退出）
+
+**场景 A：客户端主动发送 disconnect**
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │  Kernel  │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. 监听 beforeunload        │                             │
+     │    发送断开消息             │                             │
+     │ {type:"disconnect"}         │                             │
+     ├────────────────────────────>│                             │
+     │                             │                             │
+     │                             │ 2. 发布 module.exiting      │
+     │                             │    data: {                  │
+     │                             │      module_id,             │
+     │                             │      token_revoked: true    │
+     │                             │    }                        │
+     │                             ├────────────────────────────>│
+     │                             │                             │
+     │                             │ 3. 发布 module.shutdown.ready│
+     │                             ├────────────────────────────>│
+     │                             │                             │
+     │                             │ 4. 关闭 Kernel 连接         │
+     │                             ├─────────────────────────X   │
+     │                             │                             │
+     │                             │ 5. 删除 session 映射        │
+     │                             │                             │
+     │ 6. 关闭客户端连接           │                             │
+     ├─────────────────────────X   │                             │
+     │                             │                             │
+```
+
+**场景 B：超时未重连（6秒）**
+
+```
+┌──────────┐                 ┌──────────┐                 ┌──────────┐
+│  客户端   │                 │ 中转服务  │                 │  Kernel  │
+└────┬─────┘                 └────┬─────┘                 └────┬─────┘
+     │                             │                             │
+     │ 1. 客户端断开               │                             │
+     ├─────────────────────────X   │                             │
+     │                             │                             │
+     │                             │ 2. 启动 6 秒超时计时器      │
+     │                             │                             │
+     │                             │ 3. 等待 6 秒...             │
+     │                             │                             │
+     │                             │ 4. 超时触发                 │
+     │                             │    执行优雅退出流程         │
+     │                             │                             │
+     │                             │ 5. 发布 module.exiting      │
+     │                             │    data: {                  │
+     │                             │      module_id,             │
+     │                             │      token_revoked: true    │
+     │                             │    }                        │
+     │                             ├────────────────────────────>│
+     │                             │                             │
+     │                             │ 6-8. 同场景 A               │
+     │                             │                             │
+```
+
+## WebSocket 消息协议
+
+### 客户端 → 中转服务
+
+**配对消息（配对码）**:
+```json
+{
+  "type": "pair",
+  "code": "ABC123"
+}
+```
+
+**配对消息（手机验证码 - 请求）**:
+```json
+{
+  "type": "request_sms",
+  "phone": "+8613800138000"
+}
+```
+
+**配对消息（手机验证码 - 验证）**:
+```json
+{
+  "type": "verify_sms",
+  "phone": "+8613800138000",
+  "code": "123456"
+}
+```
+
+**认证消息**:
+```json
+{
+  "type": "auth",
+  "token": "tok_xxx",
+  "session_token": "sess_a3f9e2"
+}
+```
+
+**断开消息**:
+```json
+{
+  "type": "disconnect"
+}
+```
+
+**心跳消息**:
+```json
+{
+  "type": "ping"
+}
+```
+
+**RPC 请求**（认证后）:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "method": "launcher.list_modules",
+  "params": {}
+}
+```
+
+**事件订阅**（认证后）:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "sub-123",
+  "method": "event.subscribe",
+  "params": {
+    "events": ["module.started", "module.stopped"]
+  }
+}
+```
+
+### 中转服务 → 客户端
+
+**配对成功**:
+```json
+{
+  "type": "paired",
+  "token": "tok_xxx",
+  "session_token": "sess_a3f9e2",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin",
+  "expires_at": "2026-04-07T12:00:00Z"
+}
+```
+
+**短信发送成功**:
+```json
+{
+  "type": "sms_sent",
+  "phone": "+8613800138000",
+  "expires_in": 300
+}
+```
+
+**认证成功**:
+```json
+{
+  "type": "authenticated",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin"
+}
+```
+
+**重连成功**:
+```json
+{
+  "type": "reconnected",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin"
+}
+```
+
+**心跳响应**:
+```json
+{
+  "type": "pong"
+}
+```
+
+**错误消息**:
+```json
+{
+  "type": "error",
+  "code": "invalid_code",
+  "message": "Invalid pairing code"
+}
+```
+
+**RPC 响应**（来自 Kernel）:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "result": { ... }
+}
+```
+
+**事件通知**（来自 Kernel）:
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event_id": "evt-123",
+    "event": "module.started",
+    "source": "launcher",
+    "timestamp": "2026-03-08T12:00:00Z",
+    "data": {
+      "module_id": "watchdog"
+    }
+  }
+}
+```
+
+## Launcher 扩展
+
+### 配置文件扩展
+
+**launcher/config.yaml** 新增配置块：
+
+```yaml
+# 允许申请动态 Token 的模块白名单
+relay_modules:
+  - evol
+  - web
+
+# 每个 relay 模块的 Token 限额
+relay_token_limits:
+  evol: 100   # 最多 100 个并发虚拟模块
+  web: 50     # 最多 50 个并发虚拟模块
+```
+
+### RPC 方法扩展
+
+#### 1. launcher.request_client_token
+
+**描述：** 为 relay 模块申请虚拟客户端 Token
+
+**权限：** 只有在 `relay_modules` 白名单中的模块可调用
+
+**请求：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "method": "launcher.request_client_token",
+  "params": {
+    "module_id": "web-client-a3f9e2"
+  }
+}
+```
+
+**响应（成功）：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "result": {
+    "token": "abc123...",
+    "module_id": "web-client-a3f9e2"
+  }
+}
+```
+
+**响应（失败）：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "error": {
+    "code": -32001,
+    "message": "Permission denied: caller not in relay_modules whitelist"
+  }
+}
+```
+
+**错误码：**
+- `-32001`: 权限拒绝（调用者不在白名单中）
+- `-32002`: module_id 格式不合法
+- `-32003`: module_id 已存在
+- `-32004`: Token 限额已满
+
+**实现逻辑：**
+```python
+async def _rpc_request_client_token(self, caller_id: str, params: dict) -> dict:
+    """为 relay 模块申请虚拟客户端 token"""
+
+    # 1. 权限检查
+    relay_modules = self.config.get("relay_modules", [])
+    if caller_id not in relay_modules:
+        raise PermissionError(f"Permission denied: {caller_id} not in relay_modules whitelist")
+
+    # 2. 参数验证
+    module_id = params.get("module_id")
+    if not module_id:
+        raise ValueError("module_id is required")
+
+    # 3. 命名规范验证
+    expected_prefix = f"{caller_id}-client-"
+    if not module_id.startswith(expected_prefix):
+        raise ValueError(f"module_id must start with {expected_prefix}")
+
+    suffix = module_id[len(expected_prefix):]
+    if not re.match(r'^[a-zA-Z0-9_-]+$', suffix):
+        raise ValueError("Invalid module_id suffix")
+
+    # 4. 检查是否已存在
+    if module_id in self._client_tokens:
+        # 已存在，返回已有 token（幂等）
+        return {
+            "token": self._client_tokens[module_id],
+            "module_id": module_id
+        }
+
+    # 5. 检查限额
+    limits = self.config.get("relay_token_limits", {})
+    limit = limits.get(caller_id, 100)
+    current_count = sum(1 for mid in self._client_tokens if mid.startswith(expected_prefix))
+    if current_count >= limit:
+        raise RuntimeError(f"Token limit reached: {current_count}/{limit}")
+
+    # 6. 生成 token
+    token = secrets.token_hex(32)
+
+    # 7. 注册到 Kernel
+    await self._rpc_call(self._ws, "kernel.register_tokens", {module_id: token})
+
+    # 8. 保存到本地映射
+    self._client_tokens[module_id] = token
+
+    # 9. 记录审计日志
+    self._log_token_request(caller_id, module_id, True)
+
+    return {
+        "token": token,
+        "module_id": module_id
+    }
+```
+
+#### 2. launcher.release_client_token（可选）
+
+**描述：** 释放虚拟客户端 Token
+
+**权限：** 只有在 `relay_modules` 白名单中的模块可调用
+
+**请求：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-124",
+  "method": "launcher.release_client_token",
+  "params": {
+    "module_id": "web-client-a3f9e2"
+  }
+}
+```
+
+**响应：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-124",
+  "result": {}
+}
+```
+
+**实现逻辑：**
+```python
+async def _rpc_release_client_token(self, caller_id: str, params: dict) -> dict:
+    """释放虚拟客户端 token"""
+
+    # 1. 权限检查
+    relay_modules = self.config.get("relay_modules", [])
+    if caller_id not in relay_modules:
+        raise PermissionError(f"Permission denied")
+
+    # 2. 参数验证
+    module_id = params.get("module_id")
+    if not module_id:
+        raise ValueError("module_id is required")
+
+    # 3. 验证所有权
+    expected_prefix = f"{caller_id}-client-"
+    if not module_id.startswith(expected_prefix):
+        raise ValueError(f"module_id does not belong to {caller_id}")
+
+    # 4. 删除 token
+    if module_id in self._client_tokens:
+        del self._client_tokens[module_id]
+
+    # 5. 记录审计日志
+    self._log_token_release(caller_id, module_id)
+
+    return {}
+```
+
+### 事件监听
+
+Launcher 监听 `module.exiting` 事件，自动释放 Token：
+
+```python
+async def _handle_module_exiting(self, event_data: dict):
+    """处理模块退出事件"""
+    module_id = event_data.get("module_id")
+    token_revoked = event_data.get("token_revoked", False)
+
+    if token_revoked and module_id in self._client_tokens:
+        # 标记 token 失效
+        del self._client_tokens[module_id]
+        print(f"[launcher] Token revoked for {module_id}")
+```
+
+## 中转服务实现
+
+### 核心数据结构
+
+```python
+class SessionInfo:
+    """前端会话信息"""
+    session_token: str          # 会话标识（如 "sess_a3f9e2"）
+    module_id: str              # 虚拟模块 ID（如 "web-client-a3f9e2"）
+    kernel_ws: WebSocket        # Kernel 连接
+    kernel_token: str           # Kernel Token
+    client_ws: WebSocket        # 客户端连接（可能为 None）
+    frontend_token: str         # 前端认证 Token
+    role: str                   # 用户角色（admin/operator/viewer）
+    created_at: float           # 创建时间戳
+    last_active: float          # 最后活跃时间戳
+    status: str                 # "active" | "waiting_reconnect"
+```
+
+### 关键方法
+
+#### 1. 配对/认证处理
+
+```python
+async def handle_client(self, client_ws: WebSocket):
+    """处理客户端连接"""
+    await client_ws.accept()
+
+    try:
+        # 接收第一条消息（配对/认证）
+        raw = await client_ws.receive_text()
+        msg = json.loads(raw)
+
+        if msg.get("type") == "pair":
+            # 配对码配对
+            await self._handle_pairing(client_ws, msg)
+        elif msg.get("type") == "request_sms":
+            # 请求手机验证码
+            await self._handle_sms_request(client_ws, msg)
+        elif msg.get("type") == "verify_sms":
+            # 验证手机验证码
+            await self._handle_sms_verify(client_ws, msg)
+        elif msg.get("type") == "auth":
+            # 已有 token，认证
+            await self._handle_auth(client_ws, msg)
+        else:
+            await client_ws.send_json({
+                "type": "error",
+                "message": "Invalid message type"
+            })
+            await client_ws.close()
+    except Exception as e:
+        print(f"[relay] Error handling client: {e}")
+        await client_ws.close()
+```
+
+#### 2. 申请 Kernel Token
+
+```python
+async def _request_kernel_token(self, module_id: str) -> str:
+    """向 Launcher 申请 Kernel Token"""
+    if not self.evol_server or not self.evol_server._ws:
+        raise RuntimeError("Not connected to Kernel")
+
+    # 调用 Launcher RPC
+    result = await self.evol_server._rpc_call(
+        self.evol_server._ws,
+        "launcher.request_client_token",
+        {"module_id": module_id}
+    )
+
+    if "error" in result:
+        raise RuntimeError(f"Failed to request token: {result['error']}")
+
+    return result["result"]["token"]
+```
+
+#### 3. 连接 Kernel
+
+```python
+async def _connect_kernel(self, module_id: str, kernel_token: str):
+    """使用 kernel_token 连接到 Kernel"""
+    url = f"ws://{self.kernel_host}:{self.kernel_port}/ws?token={kernel_token}&id={module_id}"
+
+    kernel_ws = await websockets.connect(
+        url,
+        open_timeout=5,
+        ping_interval=None,
+        close_timeout=10
+    )
+
+    # 注册模块
+    await self._send_to_kernel(kernel_ws, {
+        "jsonrpc": "2.0",
+        "id": str(uuid.uuid4()),
+        "method": "registry.register",
+        "params": {
+            "module_id": module_id,
+            "module_type": "web_client",
+        }
+    })
+
+    # 发送 module.ready
+    await self._send_to_kernel(kernel_ws, {
+        "jsonrpc": "2.0",
+        "id": str(uuid.uuid4()),
+        "method": "event.publish",
+        "params": {
+            "event_id": str(uuid.uuid4()),
+            "event": "module.ready",
+            "data": {
+                "module_id": module_id,
+                "graceful_shutdown": True,
+            }
+        }
+    })
+
+    return kernel_ws
+```
+
+#### 4. 优雅退出
+
+```python
+async def _graceful_shutdown(self, session: SessionInfo):
+    """执行优雅退出流程"""
+    try:
+        # 发布 module.exiting 事件（标记 token 失效）
+        await self._send_to_kernel(session.kernel_ws, {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "event.publish",
+            "params": {
+                "event_id": str(uuid.uuid4()),
+                "event": "module.exiting",
+                "data": {
+                    "module_id": session.module_id,
+                    "token_revoked": True  # 关键：标记 token 失效
+                }
+            }
+        })
+
+        # 发布 module.shutdown.ready 事件
+        await self._send_to_kernel(session.kernel_ws, {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "event.publish",
+            "params": {
+                "event_id": str(uuid.uuid4()),
+                "event": "module.shutdown.ready",
+                "data": {
+                    "module_id": session.module_id
+                }
+            }
+        })
+
+        # 关闭 Kernel 连接
+        await session.kernel_ws.close()
+
+        print(f"[relay] Graceful shutdown completed: {session.module_id}")
+    except Exception as e:
+        print(f"[relay] Graceful shutdown error: {e}")
+```
+
+#### 5. 重连处理
+
+```python
+async def _handle_reconnect(self, client_ws: WebSocket, session_token: str, token_info: dict):
+    """处理客户端重连"""
+    session = self.sessions.get(session_token)
+    if not session:
+        # session 不存在，创建新连接
+        await self._create_new_connection(client_ws, session_token, token_info)
+        return
+
+    # 取消超时计时器
+    if session_token in self.reconnect_timers:
+        self.reconnect_timers[session_token].cancel()
+        del self.reconnect_timers[session_token]
+
+    # 恢复客户端连接
+    session.client_ws = client_ws
+    session.status = "active"
+    session.last_active = time.time()
+
+    # 返回重连成功
+    await client_ws.send_json({
+        "type": "reconnected",
+        "module_id": session.module_id,
+        "role": session.role
+    })
+
+    print(f"[relay] Reconnected: {session.module_id}")
+
+    # 继续双向转发
+    await self._relay_messages(session)
+```
+
+## 权限控制
+
+### 权限配置
+
+```json5
+// relay_config.json5
+{
+  permissions: {
+    // 管理员角色 - 完全权限
+    admin: [
+      "event.*",              // 事件订阅（必需）
+      "registry.*",           // 注册表查询（必需）
+      "launcher.*",           // 所有 launcher RPC
+      "kernel.health",        // Kernel 健康检查
+      "kernel.stats",         // Kernel 统计信息
+      "*.health",             // 所有模块的健康检查
+      "*.status",             // 所有模块的状态查询
+      "watchdog.*",           // Watchdog 相关
+      "backup.*",             // Backup 相关
+      "model_service.*",      // Model Service 相关
+      "web.*"                 // Web 管理相关
+    ],
+
+    // 操作员角色 - 模块管理权限
+    operator: [
+      "event.*",              // 事件订阅（必需）
+      "registry.*",           // 注册表查询（必需）
+      "launcher.list_modules",
+      "launcher.start_module",
+      "launcher.stop_module",
+      "launcher.restart_module",
+      "*.health",
+      "*.status"
+    ],
+
+    // 查看者角色 - 只读权限
+    viewer: [
+      "event.*",              // 事件订阅（必需）
+      "registry.*",           // 注册表查询（必需）
+      "launcher.list_modules",
+      "*.health",
+      "*.status"
+    ]
+  }
+}
+```
+
+### 权限检查
+
+```python
+def _check_permission(self, role: str, msg: dict) -> bool:
+    """检查 RPC 权限"""
+    method = msg.get("method")
+    if not method:
+        return True  # 非 RPC 消息，放行
+
+    # 获取角色的权限列表
+    permissions = self.permissions.get(role, [])
+
+    # 检查是否匹配
+    for pattern in permissions:
+        if self._match_pattern(pattern, method):
+            return True
+
+    return False
+
+def _match_pattern(self, pattern: str, method: str) -> bool:
+    """匹配通配符模式"""
+    if pattern == method:
+        return True
+    if pattern.endswith(".*"):
+        prefix = pattern[:-2]
+        return method.startswith(prefix + ".")
+    return False
+```
+
+## 连接韧性设计
+
+### 三层重连机制
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 层次 1: 客户端 ↔ 中转服务                               │
+│ - 客户端断开 → 中转服务保持 Kernel 连接 6 秒            │
+│ - 客户端重连 → 中转服务复用 Kernel 连接                 │
+│ - 超时 → 中转服务执行优雅退出                           │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 层次 2: 中转服务 ↔ Kernel                               │
+│ - 中转服务断开 → Kernel 启动 5 秒 debounce              │
+│ - 中转服务重连 → Kernel 取消 debounce（使用同一 token） │
+│ - 超时 → Kernel 标记模块 offline                        │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 层次 3: 中转服务模块 ↔ Kernel                           │
+│ - 中转服务模块断开 → 自动重连（指数退避，最多 10 次）   │
+│ - 每次重连使用同一 token                                │
+│ - 认证失败 → 退出（token 无效）                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Token 复用机制
+
+**关键点：** Token 不是一次性的，可以多次重连使用。
+
+**客户端重连：**
+- 客户端刷新页面 → 中转服务保持 Kernel 连接
+- 客户端重连 → 复用已有的 `kernel_ws` 和 `kernel_token`
+- 无需重新申请 token
+
+**中转服务重连：**
+- 中转服务模块重启 → 使用同一 token 重连 Kernel
+- Kernel 验证 token，恢复连接
+- 虚拟模块的 token 需要重新申请（因为 session 映射丢失）
+
+**Token 失效：**
+- 只有在优雅退出时，通过 `module.exiting` 事件标记 `token_revoked: true`
+- Launcher 监听事件，删除 token 映射
+- 客户端再次连接时，必须重新申请 token
+
+## 安全机制
+
+### 1. 权限白名单
+
+**Launcher 配置：**
+```yaml
+relay_modules:
+  - evol
+  - web
+```
+
+只有在白名单中的模块可以调用 `launcher.request_client_token`。
+
+### 2. Token 限额
+
+**Launcher 配置：**
+```yaml
+relay_token_limits:
+  evol: 100
+  web: 50
+```
+
+防止单个 relay 模块申请过多 token，避免资源耗尽。
+
+### 3. 命名规范验证
+
+**规则：** `module_id` 必须以 `{caller_id}-client-` 开头
+
+**示例：**
+- evol 模块申请：`evol-client-a3f9e2` ✅
+- evol 模块申请：`web-client-a3f9e2` ❌（不属于 evol）
+- web 模块申请：`web-client-xyz123` ✅
+
+**目的：** 防止 relay 模块冒充其他模块。
+
+### 4. 审计日志
+
+**Launcher 记录所有 token 申请：**
+
+```jsonl
+{"timestamp":"2026-03-08T12:00:00Z","caller_id":"evol","module_id":"evol-client-a3f9e2","action":"request","success":true}
+{"timestamp":"2026-03-08T12:05:00Z","caller_id":"evol","module_id":"evol-client-a3f9e2","action":"release","success":true}
+```
+
+**日志文件：** `launcher/log/token_requests.jsonl`
+
+### 5. RPC 权限控制
+
+中转服务根据用户角色过滤 RPC 请求：
+
+```python
+# 检查权限
+if not self._check_permission(session.role, msg):
+    await session.client_ws.send_json({
+        "jsonrpc": "2.0",
+        "id": msg.get("id"),
+        "error": {
+            "code": -32001,
+            "message": f"Permission denied: {msg.get('method')}"
+        }
+    })
+    return
+```
+
+### 6. Token 续期
+
+**frontend_token 续期机制：**
+
+```python
+def verify_token(self, token: str) -> Optional[dict]:
+    """验证 frontend_token，自动续期"""
+    record = self._find_token_record(token)
+    if not record:
+        return None
+
+    # 检查是否过期
+    expires_at = datetime.fromisoformat(record["expires_at"])
+    now = datetime.now(timezone.utc)
+
+    if now > expires_at:
+        return None  # 已过期
+
+    # 检查是否需要续期（剩余 < 7 天）
+    remaining = (expires_at - now).total_seconds()
+    if remaining < 604800:  # 7 天
+        # 续期 30 天
+        new_expires_at = now + timedelta(seconds=2592000)
+        self._renew_token(token, new_expires_at)
+
+    return {
+        "role": record["role"],
+        "expires_at": record["expires_at"]
+    }
+```
+
+## 配置文件
+
+### relay_config.json5
+
+```json5
+{
+  // 中转服务配置
+  relay: {
+    // 基础模块 ID（实际 module_id 会加上 session 后缀）
+    base_module_id: "web-client",
+
+    // 重连超时时间（秒）
+    // 客户端刷新页面或短暂断网时，中转服务保持 Kernel 连接的时长
+    reconnect_timeout: 6,
+
+    // WebSocket 端点路径
+    endpoint: "/ws/relay"
+  },
+
+  // 认证配置
+  auth: {
+    // frontend_token 有效期（秒，30天）
+    token_expiry: 2592000,
+
+    // token 续期阈值（秒，7天）
+    // 当 token 剩余有效期小于此值时，自动续期
+    token_renew_threshold: 604800,
+
+    // 配对码长度
+    pairing_code_length: 6,
+
+    // 配对码文件路径（相对于模块数据目录）
+    pairing_code_file: "pairing_codes.jsonl"
+  },
+
+  // 短信配置（可选）
+  sms: {
+    // 短信 API 提供商（aliyun/tencent/twilio）
+    provider: "aliyun",
+
+    // API 密钥
+    access_key_id: "your_access_key",
+    access_key_secret: "your_secret",
+
+    // 短信模板
+    template_code: "SMS_123456",
+    sign_name: "Kite管理平台",
+
+    // 验证码有效期（秒）
+    code_expiry: 300
+  },
+
+  // 权限配置（基于角色的 RPC 白名单）
+  permissions: {
+    // 管理员角色 - 完全权限
+    admin: [
+      "event.*",
+      "registry.*",
+      "launcher.*",
+      "kernel.health",
+      "kernel.stats",
+      "*.health",
+      "*.status",
+      "watchdog.*",
+      "backup.*",
+      "model_service.*",
+      "web.*"
+    ],
+
+    // 操作员角色 - 模块管理权限
+    operator: [
+      "event.*",
+      "registry.*",
+      "launcher.list_modules",
+      "launcher.start_module",
+      "launcher.stop_module",
+      "launcher.restart_module",
+      "*.health",
+      "*.status"
+    ],
+
+    // 查看者角色 - 只读权限
+    viewer: [
+      "event.*",
+      "registry.*",
+      "launcher.list_modules",
+      "*.health",
+      "*.status"
+    ]
+  }
+}
+```
+
+## 实现文件清单
+
+### 中转服务模块（evol/web）
+
+1. **relay.py** - 中转服务核心逻辑（独立可复用）
+2. **pairing.py** - 配对码管理
+3. **sms.py** - 短信验证码管理（可选）
+4. **relay_config.json5** - 中转服务配置
+
+### Launcher 扩展
+
+1. **launcher/config.yaml** - 新增 `relay_modules` 和 `relay_token_limits` 配置
+2. **launcher/entry.py** - 新增 RPC 方法：
+   - `launcher.request_client_token`
+   - `launcher.release_client_token`（可选）
+3. **launcher/log/token_requests.jsonl** - Token 申请审计日志
+
+### 前端文件
+
+1. **static/js/kernel-client.js** - Kernel 客户端封装
+2. **static/pairing.html** - 配对界面
+3. **static/sms-verify.html** - 手机验证界面（可选）
+
+## 实施计划
+
+### 阶段 1: Launcher 扩展
+
+1. 修改 `launcher/config.yaml`，新增配置块
+2. 实现 `launcher.request_client_token` RPC 方法
+3. 实现 `launcher.release_client_token` RPC 方法（可选）
+4. 实现 `module.exiting` 事件监听
+5. 实现审计日志记录
+
+### 阶段 2: 中转服务核心
+
+1. 实现 `relay.py` 核心逻辑
+2. 实现配对码配对流程
+3. 实现 Token 申请和管理
+4. 实现双向消息转发
+5. 实现重连管理
+6. 实现优雅退出
+
+### 阶段 3: 手机验证码（可选）
+
+1. 实现 `sms.py` 短信管理
+2. 集成短信 API（阿里云/腾讯云/Twilio）
+3. 实现验证码验证流程
+
+### 阶段 4: 前端客户端
+
+1. 实现 `KernelClient` 类
+2. 实现配对界面
+3. 实现手机验证界面（可选）
+4. 实现自动重连逻辑
+5. 实现 Token 续期处理
+
+### 阶段 5: 测试与优化
+
+1. 单元测试（配对、认证、权限）
+2. 集成测试（完整流程）
+3. 压力测试（并发连接）
+4. 安全测试（权限绕过、Token 伪造）
+5. 性能优化
+
+## 优势总结
+
+1. **安全可控** - Token 由 Launcher 集中管理，权限白名单控制
+2. **平滑重连** - 客户端刷新页面时，Kernel 无感知
+3. **灵活配对** - 支持配对码和手机验证码两种方式
+4. **独立可复用** - relay.py 可以集成到任何模块
+5. **完整生命周期** - 从配对到退出，全流程管理
+6. **连接韧性** - 三层重连机制，Token 可复用
+7. **审计追踪** - 所有 Token 申请都有日志记录
+8. **权限细粒度** - 基于角色的 RPC 白名单
+
+## 技术难点与解决方案
+
+### 1. Token 管理复杂性
+
+**难点：** 需要协调 Launcher、中转服务、Kernel 三方
+
+**解决：**
+- Launcher 作为 Token 管理中心
+- 中转服务通过 RPC 申请 Token
+- Kernel 只负责验证 Token
+
+### 2. 重连状态同步
+
+**难点：** 客户端重连时，如何恢复状态
+
+**解决：**
+- 使用 `session_token` 识别重连
+- 中转服务保持 Kernel 连接 6 秒
+- 复用已有的 `kernel_ws` 和 `kernel_token`
+
+### 3. 优雅退出时机
+
+**难点：** 如何判断客户端是刷新还是真正关闭
+
+**解决：**
+- 客户端主动发送 `disconnect` 消息（beforeunload）
+- 超时机制（6 秒未重连 → 优雅退出）
+- 通过 `module.exiting` 事件标记 Token 失效
+
+### 4. 权限控制
+
+**难点：** 如何防止客户端绕过权限检查
+
+**解决：**
+- 中转服务在转发前检查权限
+- 基于角色的白名单机制
+- 拒绝的请求不转发到 Kernel
+
+### 5. 并发连接管理
+
+**难点：** 大量客户端同时连接时的性能
+
+**解决：**
+- Token 限额机制
+- 异步 I/O（asyncio）
+- 连接池管理
+
+## 附录
+
+### 错误码定义
+
+| 错误码 | 说明 |
+|--------|------|
+| -32001 | 权限拒绝 |
+| -32002 | module_id 格式不合法 |
+| -32003 | module_id 已存在 |
+| -32004 | Token 限额已满 |
+| -32005 | 配对码无效 |
+| -32006 | 验证码无效 |
+| -32007 | frontend_token 无效或过期 |
+
+### 日志格式
+
+**Token 申请日志：**
+```jsonl
+{"timestamp":"2026-03-08T12:00:00Z","caller_id":"evol","module_id":"evol-client-a3f9e2","action":"request","success":true}
+```
+
+**Token 释放日志：**
+```jsonl
+{"timestamp":"2026-03-08T12:05:00Z","caller_id":"evol","module_id":"evol-client-a3f9e2","action":"release","success":true}
+```
+
+**配对日志：**
+```jsonl
+{"timestamp":"2026-03-08T12:00:00Z","type":"pair","code":"ABC123","role":"admin","success":true,"module_id":"evol-client-a3f9e2"}
+```
+
+**验证码日志：**
+```jsonl
+{"timestamp":"2026-03-08T12:00:00Z","type":"sms","phone":"+8613800138000","code":"123456","success":true,"module_id":"evol-client-a3f9e2"}
+```