@agentunion/kite 1.4.0 → 1.6.0

package/docs/web/346/250/241/345/235/227/344/270/255/350/275/254/346/234/215/345/212/241/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,449 @@
+# Web 模块中转服务设计方案
+
+## 概述
+
+中转服务是一个独立的、可复用的组件，允许前端浏览器作为标准 Kite 模块接入 Kernel。前端通过 WebSocket 连接到中转服务，**配对、认证、RPC 通信全部通过 WebSocket 完成**，无需 HTTP API。
+
+## 核心特性
+
+1. **前端作为标准 Kite 模块** - 可以调用任何模块的 RPC，订阅/发布事件
+2. **全 WebSocket 协议** - 配对、认证、RPC 通信全部通过 WebSocket
+3. **平滑重连** - 前端刷新页面时，Kernel 看到的是模块一直在线
+4. **优雅退出** - 前端关闭或超时时，中转服务代为完成优雅退出流程
+5. **独立可复用** - 可以集成到任何模块中，只需复制 `relay.py` 文件
+
+## 架构设计
+
+### 数据流
+
+```
+前端 sessionStorage: session_token (如 "sess_a3f9e2")
+                          ↓
+中转服务映射表: {
+    "sess_a3f9e2": {
+        module_id: "web-client-a3f9e2",
+        kernel_ws: <WebSocket>,
+        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"
+```
+
+### 关键设计
+
+1. **session_token 由前端生成并持久化** - 存储在 sessionStorage
+2. **module_id 由中转服务管理** - 基于 session_token 生成，前端无需关心
+3. **中转服务完全控制模块生命周期** - 包括注册、重连、优雅退出
+4. **全 WebSocket 通信** - 配对、认证、RPC 全部通过 WebSocket
+
+## 连接流程
+
+### 首次配对（未登录）
+
+```
+1. 前端连接 /ws/relay
+
+2. 前端发送配对消息：
+   {
+     type: "pair",
+     code: "DEV123"
+   }
+
+3. 中转服务验证配对码
+
+4. 中转服务：
+   - 生成 frontend_token
+   - 生成 session_token
+   - 生成 module_id
+   - 连接 Kernel
+   - 注册模块
+
+5. 中转服务返回：
+   {
+     type: "paired",
+     token: "tok_xxx",
+     session_token: "sess_a3f9e2",
+     module_id: "web-client-a3f9e2",
+     role: "admin"
+   }
+
+6. 前端保存 token 和 session_token
+7. 连接升级为已认证状态，可以发送 RPC 请求
+```
+
+### 已登录（有 token）
+
+```
+1. 前端连接 /ws/relay
+
+2. 前端发送认证消息：
+   {
+     type: "auth",
+     token: "tok_xxx",
+     session_token: "sess_a3f9e2"
+   }
+
+3. 中转服务验证 token
+
+4. 中转服务检查 session_token：
+   - 不存在 → 创建新连接
+   - 存在 → 恢复连接（重连）
+
+5. 中转服务返回：
+   {
+     type: "authenticated",  // 或 "reconnected"
+     module_id: "web-client-a3f9e2",
+     role: "admin"
+   }
+
+6. 连接升级为已认证状态
+```
+
+### 刷新页面（平滑重连）
+
+```
+1. 前端断开 WebSocket
+
+2. 中转服务检测到客户端断开：
+   - 标记 session 为 "waiting_reconnect"
+   - 保持 Kernel 连接
+   - 启动 6 秒超时计时器
+
+3. 前端重新加载，从 sessionStorage 读取 token 和 session_token
+
+4. 前端重新连接 /ws/relay，发送认证消息
+
+5. 中转服务识别到是重连：
+   - 取消超时计时器
+   - 恢复 client_ws 引用
+   - 标记 session 为 "active"
+   - Kernel 看到的是模块一直在线
+
+6. 中转服务返回：
+   {
+     type: "reconnected",
+     module_id: "web-client-a3f9e2",
+     role: "admin"
+   }
+```
+
+### 关闭标签页（优雅退出）
+
+**场景 A：前端主动发送 disconnect**
+
+```
+1. 前端监听 beforeunload，发送：
+   {type: "disconnect"}
+
+2. 中转服务收到 disconnect：
+   - 代表前端执行优雅退出流程
+   - 发送 module.exiting 事件
+   - 发送 module.shutdown.ready 事件
+   - 断开 Kernel 连接
+   - 删除 session 映射
+```
+
+**场景 B：前端超时（6秒未重连）**
+
+```
+1. 中转服务超时计时器触发：
+   - 代表前端执行优雅退出流程
+   - 发送 module.exiting 事件
+   - 发送 module.shutdown.ready 事件
+   - 断开 Kernel 连接
+   - 删除 session 映射
+```
+
+## WebSocket 消息协议
+
+### 客户端 → 中转服务
+
+**配对消息**:
+```json
+{
+  "type": "pair",
+  "code": "DEV123"
+}
+```
+
+**认证消息**:
+```json
+{
+  "type": "auth",
+  "token": "tok_xxx",
+  "session_token": "sess_a3f9e2"
+}
+```
+
+**断开消息**:
+```json
+{
+  "type": "disconnect"
+}
+```
+
+**RPC 请求**（认证后）:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "method": "launcher.list_modules",
+  "params": {}
+}
+```
+
+### 中转服务 → 客户端
+
+**配对成功**:
+```json
+{
+  "type": "paired",
+  "token": "tok_xxx",
+  "session_token": "sess_a3f9e2",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin"
+}
+```
+
+**认证成功**:
+```json
+{
+  "type": "authenticated",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin"
+}
+```
+
+**重连成功**:
+```json
+{
+  "type": "reconnected",
+  "module_id": "web-client-a3f9e2",
+  "role": "admin"
+}
+```
+
+**错误消息**:
+```json
+{
+  "type": "error",
+  "message": "Invalid pairing code"
+}
+```
+
+**RPC 响应**（来自 Kernel）:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-123",
+  "result": { ... }
+}
+```
+
+**事件通知**（来自 Kernel）:
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event": "module.started",
+    "data": { ... }
+  }
+}
+```
+
+## 认证与权限
+
+### 配对码管理
+
+1. **配对码文件**：`data/pairing_codes.jsonl`
+2. **配对流程**：
+   - 用户输入配对码
+   - web 模块验证配对码
+   - 验证通过 → 生成 frontend_token
+   - 配对码标记为"已使用"，重新生成新的配对码
+
+### Token 管理
+
+1. **frontend_token**：
+   - 存储在 localStorage
+   - 有效期 30 天
+   - 快过期时自动续期（剩余 < 7 天）
+
+2. **kernel_token**：
+   - 临时 token，每次连接时由 web 模块生成
+   - 用于中转服务连接 Kernel
+   - 前端不直接持有
+
+### 权限控制
+
+**当前阶段**：白名单模式
+- 中转服务维护允许的 RPC 列表
+- 例如：允许 `launcher.list_modules`, `launcher.start_module`
+- 禁止 `launcher.shutdown`, `kernel.stop`
+
+**未来扩展**：基于角色的权限
+- 配对码关联角色（admin / operator / viewer）
+- 不同角色有不同的 RPC 白名单
+
+## 配置文件结构
+
+### 模块配置文件：`module.md`
+
+Kite 框架的模块配置（YAML frontmatter）
+
+```yaml
+---
+name: web
+type: service
+preferred_port: 18766
+advertise_ip: 0.0.0.0
+---
+```
+
+### 业务配置文件 1：`web_config.json5`
+
+Web 管理模块的业务配置（AI Phone Agent 相关）
+
+```json5
+{
+  // Web 服务配置
+  server: {
+    host: "0.0.0.0",
+    port: 18766,
+    ssl: false
+  },
+
+  // 其他 AI Phone Agent 相关配置
+  // ...
+}
+```
+
+### 业务配置文件 2：`relay_config.json5`
+
+中转服务的业务配置
+
+```json5
+{
+  // 中转服务配置
+  relay: {
+    // 基础模块 ID（实际 module_id 会加上 session 后缀）
+    base_module_id: "web-client",
+
+    // 重连超时时间（秒）
+    reconnect_timeout: 6,
+
+    // WebSocket 端点路径
+    endpoint: "/ws/relay"
+  },
+
+  // 认证配置
+  auth: {
+    // frontend_token 有效期（秒，30天）
+    token_expiry: 2592000,
+
+    // token 续期阈值（秒，7天）
+    token_renew_threshold: 604800,
+
+    // 配对码长度
+    pairing_code_length: 6,
+
+    // 配对码文件路径
+    pairing_code_file: "data/pairing_codes.jsonl"
+  },
+
+  // 权限配置
+  permissions: {
+    // 管理员角色
+    admin: [
+      "launcher.*",
+      "kernel.health",
+      "*.health",
+      "*.status"
+    ],
+
+    // 操作员角色
+    operator: [
+      "launcher.list_modules",
+      "launcher.start_module",
+      "launcher.stop_module",
+      "*.health"
+    ],
+
+    // 查看者角色
+    viewer: [
+      "launcher.list_modules",
+      "*.health"
+    ]
+  }
+}
+```
+
+## 实现文件
+
+### 核心文件
+
+1. **`relay.py`** - 中转服务核心逻辑（独立可复用）
+2. **`routes/routes_auth.py`** - 认证 API（配对、验证、续期）
+3. **`pairing.py`** - 配对码管理
+4. **`relay_config.json5`** - 中转服务配置
+
+### 前端文件
+
+1. **`static/js/kernel-client.js`** - Kernel 客户端封装
+2. **`static/pairing.html`** - 配对界面（或集成到 index.html）
+
+## 优势
+
+1. **前端无需管理 module_id** - 只需要持久化 session_token
+2. **中转服务完全控制模块生命周期** - 包括优雅退出
+3. **平滑重连对前端透明** - 前端只需要重连，不需要知道 Kernel 的状态
+4. **session_token 可以用于审计** - 追踪哪个 session 做了什么操作
+5. **独立可复用** - 可以集成到任何模块中
+
+## 技术难点
+
+1. **双向消息转发的并发处理** - 使用 asyncio Task 管理
+2. **客户端断开时的清理逻辑** - 使用 try/finally 确保清理
+3. **Kernel 连接失败时的错误处理** - 实现重连机制
+4. **权限控制** - 白名单/黑名单拦截
+5. **断线重连** - 保持状态，恢复连接
+
+## 实现计划
+
+### 阶段 1：配对码管理（HTTP API）
+1. `POST /api/auth/pair` - 配对接口
+2. `POST /api/auth/verify` - 验证接口
+3. 配对码文件管理
+
+### 阶段 2：中转服务（relay.py）
+1. WebSocket 端点：`/ws/relay`
+2. 双向转发 JSON-RPC 消息
+3. RPC 白名单过滤
+4. 平滑重连（保持 Kernel 连接 6 秒）
+
+### 阶段 3：前端客户端
+1. 配对界面（首次访问）
+2. KernelClient 类（封装 WebSocket + JSON-RPC）
+3. 自动重连逻辑
+4. Token 续期处理
+
+## 配置示例
+
+### 开发环境配对码
+
+在 `data/pairing_codes.jsonl` 中预置一个配对码：
+
+```jsonl
+{"code": "DEV123", "role": "admin", "status": "active", "created_at": "2026-03-05T20:00:00Z"}
+```
+
+### 生产环境配对码
+
+通过短信 API 动态生成，有效期 5 分钟。