@agentunion/kite 1.4.0 → 1.6.0

package/docs/Kite/346/216/247/345/210/266/345/217/260/347/273/237/344/270/200WebSocket/346/224/271/351/200/240/346/226/271/346/241/210.md

@@ -0,0 +1,821 @@
+# Kite 控制台统一 WebSocket 改造方案
+
+## 概述
+
+本文档描述将 Evol 模块改造为统一使用 `/ws/relay` 的阶段性过渡方案。改造完成后，前端将通过单一 WebSocket 连接与 Kernel 通信，删除冗余的 `/ws/management` 连接，为未来的插件化架构打好基础。
+
+## 改造目标
+
+### 当前问题
+
+1. **双 WebSocket 连接**
+   - `kernel-client-example.js` 连接 `/ws/relay`（只被 registry-tests.js 使用）
+   - `evol-app.js` 连接 `/ws/management`（主应用使用）
+   - 两个连接功能重叠，浪费资源
+
+2. **认证机制不统一**
+   - `/ws/relay` 使用配对码认证
+   - `/ws/management` 无认证（直接连接）
+   - Kite Token 无法用于 `/ws/relay` 认证
+
+3. **RPC 调用方式混乱**
+   - `registry-tests.js` 使用 WebSocket RPC
+   - `evol-app.js` 使用 HTTP RPC (`/api/rpc/{method}`)
+   - 两种方式并存，代码不统一
+
+4. **文件冗余**
+   - `kernel-client-example.js` 只为测试服务
+   - 可以删除，简化代码结构
+
+### 改造目标
+
+1. **统一 WebSocket 连接**
+   - 删除 `/ws/management`
+   - 所有前端代码统一使用 `/ws/relay`
+   - 删除 `kernel-client-example.js`
+
+2. **支持双认证机制**
+   - 配对码认证（Kite 基础功能）
+   - Kite Token 认证（Evol 业务功能）
+   - 两种认证方式并存
+
+3. **统一 RPC 调用**
+   - 所有 RPC 调用通过 WebSocket
+   - 保留 HTTP API 作为备用（向后兼容）
+
+4. **代码简化**
+   - evol-app.js 使用 kernelClient
+   - 删除自己的 WebSocket 代码
+   - 统一错误处理和重连逻辑
+
+## 改造步骤
+
+### 第一步：Relay Service 支持 Kite Token 认证
+
+#### 1.1 修改 relay.py
+
+**目标**：在 `_handle_auth()` 方法中新增 Kite Token 验证逻辑。
+
+**改动位置**：`extensions/services/evol/relay.py`
+
+**改动内容**：
+
+```python
+# relay.py
+class KernelRelay:
+    def __init__(
+        self,
+        kernel_host: str,
+        kernel_port: int,
+        kernel_token: str,
+        base_module_id: str,
+        reconnect_timeout: int,
+        permissions: dict,
+        pairing_manager,
+        evol_server,
+        auth_manager,  # 新增：AuthManager 实例
+    ):
+        # ... 现有代码 ...
+        self.auth_manager = auth_manager  # 新增
+
+    async def _handle_auth(self, client_ws: WebSocket, msg: dict):
+        """处理认证请求（已有 token）"""
+        frontend_token = msg.get("token")
+        session_token = msg.get("session_token")
+
+        if not frontend_token or not session_token:
+            await client_ws.send_json({
+                "type": "error",
+                "message": "Missing token or session_token"
+            })
+            await client_ws.close(code=4000, reason="Missing credentials")
+            return
+
+        # 1. 尝试配对码认证
+        token_info = self.pairing_manager.verify_token(frontend_token)
+        if token_info:
+            role = token_info["role"]
+            auth_type = "pairing"
+            print(f"[Relay] Authenticated via pairing code, role={role}")
+
+        # 2. 尝试 Kite Token 认证（新增）
+        elif self.auth_manager.verify_kite_token(frontend_token):
+            role = "admin"  # Kite Token 用户默认为 admin
+            auth_type = "kite_token"
+            print(f"[Relay] Authenticated via Kite Token, role={role}")
+
+        # 3. 认证失败
+        else:
+            await client_ws.send_json({
+                "type": "error",
+                "message": "Invalid or expired token"
+            })
+            await client_ws.close(code=4001, reason="Invalid token")
+            return
+
+        # 检查是否是重连
+        if session_token in self.sessions:
+            await self._handle_reconnect(client_ws, session_token, {"role": role})
+        else:
+            await self._create_new_connection(
+                client_ws,
+                session_token,
+                frontend_token,
+                role
+            )
+```
+
+#### 1.2 修改 server.py
+
+**目标**：将 `auth_manager` 传递给 `KernelRelay`。
+
+**改动位置**：`extensions/services/evol/server.py`
+
+**改动内容**：
+
+```python
+# server.py
+# 在创建 relay_service 时传入 auth_manager
+relay_service = KernelRelay(
+    kernel_host=relay_config["kernel"]["host"],
+    kernel_port=relay_config["kernel"]["port"],
+    kernel_token=relay_config["kernel"]["token"],
+    base_module_id=relay_config["relay"]["base_module_id"],
+    reconnect_timeout=relay_config["relay"]["reconnect_timeout"],
+    permissions=relay_config["permissions"],
+    pairing_manager=pairing_manager,
+    evol_server=server,
+    auth_manager=server.auth_manager,  # 新增
+)
+```
+
+#### 1.3 测试验证
+
+**测试步骤**：
+
+1. 启动 Kite
+2. 打开浏览器控制台
+3. 使用配对码登录，验证功能正常
+4. 使用 Kite Token 登录，验证功能正常
+
+**验证点**：
+- 配对码认证成功，role 正确
+- Kite Token 认证成功，role 为 admin
+- 无效 token 认证失败，返回错误
+
+### 第二步：修改 kernel-client.js 支持 Kite Token
+
+#### 2.1 修改 KernelClient 构造函数
+
+**目标**：优先使用 `kiteToken`，其次使用 `frontend_token`。
+
+**改动位置**：`extensions/services/evol/static/js/kernel-client.js`
+
+**改动内容**：
+
+```javascript
+// kernel-client.js
+class KernelClient {
+    constructor(url) {
+        this.url = url;
+        this.ws = null;
+        this.moduleId = null;
+        this.role = null;
+        this.connected = false;
+        this.authenticated = false;
+
+        // RPC 请求管理
+        this.rpcId = 0;
+        this.pendingRpcs = new Map();
+
+        // 事件监听器
+        this.eventListeners = new Map();
+
+        // 重连配置
+        this.reconnectDelay = 1000;
+        this.maxReconnectDelay = 10000;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.fatalError = false;
+
+        // 心跳配置
+        this.heartbeatInterval = 20000;
+        this.heartbeatTimer = null;
+
+        // Token 管理（改动）
+        // 优先使用 kiteToken，其次使用 frontend_token
+        this.token = localStorage.getItem('kiteToken') || localStorage.getItem('frontend_token');
+        this.sessionToken = sessionStorage.getItem('session_token');
+
+        // 生成 session_token（如果没有）
+        if (!this.sessionToken) {
+            this.sessionToken = 'sess_' + this._randomString(6);
+            sessionStorage.setItem('session_token', this.sessionToken);
+        }
+    }
+
+    // ... 其他方法保持不变 ...
+}
+```
+
+#### 2.2 测试验证
+
+**测试步骤**：
+
+1. 清除 localStorage 和 sessionStorage
+2. 使用 Evol 手机号登录（获得 kiteToken）
+3. 刷新页面，验证自动使用 kiteToken 连接
+
+**验证点**：
+- kiteToken 存在时，使用 kiteToken 认证
+- kiteToken 不存在时，使用 frontend_token 认证
+- 认证成功后，可以正常调用 RPC
+
+### 第三步：改造 evol-app.js 使用 kernelClient
+
+#### 3.1 删除自己的 WebSocket 代码
+
+**目标**：删除 `initKernelClient()` 方法和相关的 WebSocket 管理代码。
+
+**改动位置**：`extensions/services/evol/static/js/evol-app.js`
+
+**删除的代码**：
+
+```javascript
+// 删除这些属性
+this.ws = null;
+this.wsConnected = false;
+this.wsRetryCount = 0;
+this.wsMaxRetries = 6;
+this.wsRetryDelay = 1000;
+this.wsGaveUp = false;
+
+// 删除这个方法
+initKernelClient() {
+    // ... 整个方法删除 ...
+}
+
+// 删除这个方法
+updateWsIndicator(status, text, color) {
+    // ... 整个方法删除 ...
+}
+```
+
+#### 3.2 新增 kernelClient 初始化
+
+**新增代码**：
+
+```javascript
+// evol-app.js
+class EvolApp {
+  constructor() {
+    this.kiteToken = this._getKiteToken();
+    this.userInfo = null;
+    this.kernelClient = null;  // 新增：使用 kernelClient
+    this.currentPage = 'account';
+    this.deviceInfo = this._getDeviceInfo();
+    // ... 其他属性 ...
+  }
+
+  async initKernelClient() {
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    this.kernelClient = new KernelClient(`${proto}//${location.host}/ws/relay`);
+
+    try {
+      // 连接并认证
+      const result = await this.kernelClient.connect();
+      console.log('[Evol] KernelClient connected:', result);
+
+      // 订阅事件
+      await this.kernelClient.subscribe([
+        'module.starting',
+        'module.started',
+        'module.ready',
+        'module.stopped',
+        'module.exiting',
+        'module.shutdown',
+        'module.crashed',
+        'registry.updated'
+      ]);
+
+      // 监听模块状态变化
+      this.kernelClient.on('module.started', (data) => {
+        console.log('[Evol] Module started:', data.module_id);
+        if (this.currentPage === 'modules') {
+          this.loadModules();
+        }
+      });
+
+      this.kernelClient.on('module.stopped', (data) => {
+        console.log('[Evol] Module stopped:', data.module_id);
+        if (this.currentPage === 'modules') {
+          this.loadModules();
+        }
+      });
+
+      this.kernelClient.on('module.crashed', (data) => {
+        console.log('[Evol] Module crashed:', data.module_id);
+        if (this.currentPage === 'modules') {
+          this.loadModules();
+        }
+      });
+
+      this.kernelClient.on('registry.updated', (data) => {
+        console.log('[Evol] Registry updated:', data);
+        // 触发缓存失效
+        if (this.currentPage === 'modules') {
+          this.loadModules();
+        }
+      });
+
+      // 更新连接状态
+      this.updateConnectionStatus(true);
+
+    } catch (err) {
+      console.error('[Evol] KernelClient connection failed:', err);
+      this.updateConnectionStatus(false);
+
+      // 如果是 token 无效，跳转到配对页面
+      if (err.message.includes('Invalid') || err.message.includes('expired')) {
+        // 清除 token
+        localStorage.removeItem('kiteToken');
+        localStorage.removeItem('frontend_token');
+        // 显示登录页面
+        this.showLoginPage();
+      }
+    }
+  }
+
+  updateConnectionStatus(connected) {
+    const indicator = document.getElementById('ws-indicator');
+    if (indicator) {
+      if (connected) {
+        indicator.innerHTML = '● Kite 已连接';
+        indicator.style.color = '#27ae60';
+      } else {
+        indicator.innerHTML = '○ 未连接';
+        indicator.style.color = '#e74c3c';
+      }
+    }
+  }
+
+  // ... 其他方法 ...
+}
+```
+
+#### 3.3 修改 callRpc 方法
+
+**目标**：改用 WebSocket RPC 替代 HTTP RPC。
+
+**改动内容**：
+
+```javascript
+// evol-app.js
+async callRpc(method, params = {}) {
+  try {
+    // 改用 WebSocket RPC
+    return await this.kernelClient.call(method, params);
+  } catch (err) {
+    console.error(`[Evol] RPC ${method} failed:`, err);
+    throw err;
+  }
+}
+```
+
+#### 3.4 修改 initMainApp 方法
+
+**改动内容**：
+
+```javascript
+// evol-app.js
+initMainApp() {
+  // 初始化 KernelClient（替代原来的 initKernelClient）
+  this.initKernelClient();
+
+  // 加载账户信息
+  this.loadAccountInfo();
+
+  // 设置导航
+  this.setupNavigation();
+
+  // 监听页面可见性变化
+  document.addEventListener('visibilitychange', () => {
+    if (!document.hidden && this.kernelClient && !this.kernelClient.connected) {
+      // 页面重新可见且未连接，尝试重连
+      this.initKernelClient();
+    }
+  });
+}
+```
+
+### 第四步：删除 kernel-client-example.js
+
+#### 4.1 从 index.html 移除引用
+
+**改动位置**：`extensions/services/evol/static/index.html`
+
+**改动内容**：
+
+```html
+<!-- 删除这一行 -->
+<!-- <script src="js/kernel-client-example.js"></script> -->
+
+<!-- 保留这些 -->
+<script src="js/dialog.js"></script>
+<script src="js/kernel-client.js?v=2"></script>
+<script src="js/registry-tests.js"></script>
+<script src="js/evol-app.js?v=2"></script>
+```
+
+#### 4.2 删除文件
+
+**操作**：
+
+```bash
+rm extensions/services/evol/static/js/kernel-client-example.js
+```
+
+#### 4.3 修改 registry-tests.js
+
+**目标**：registry-tests.js 依赖全局的 `kernelClient`，需要确保它由 evol-app.js 创建。
+
+**改动位置**：`extensions/services/evol/static/js/registry-tests.js`
+
+**改动内容**：
+
+在测试开始前，等待 `kernelClient` 就绪：
+
+```javascript
+// registry-tests.js
+async function runAllTests() {
+    // 清空输出
+    const output = document.getElementById('test-output');
+    if (output) {
+        output.innerHTML = '';
+    }
+
+    // 重置统计
+    TEST_STATS.total = 0;
+    TEST_STATS.passed = 0;
+    TEST_STATS.failed = 0;
+    TEST_STATS.skipped = 0;
+
+    logTest('='.repeat(60), 'section');
+    logTest('Kite 注册中心全面测试', 'section');
+    logTest('='.repeat(60), 'section');
+    logTest('', 'info');
+
+    try {
+        // 等待 kernelClient 连接和认证（改动）
+        // 使用全局的 app.kernelClient
+        const kernelClient = window.app?.kernelClient;
+
+        if (!kernelClient) {
+            logTest('错误: kernelClient 未初始化', 'fail');
+            return;
+        }
+
+        if (!kernelClient.connected || !kernelClient.authenticated) {
+            logTest('等待 Kernel 连接和认证...', 'info');
+
+            // 等待最多 10 秒
+            const maxWait = 10000;
+            const startTime = Date.now();
+
+            while ((!kernelClient.connected || !kernelClient.authenticated) && (Date.now() - startTime < maxWait)) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+
+            if (!kernelClient.connected || !kernelClient.authenticated) {
+                logTest('错误: Kernel 连接或认证超时', 'fail');
+                logTest(`  connected: ${kernelClient.connected}, authenticated: ${kernelClient.authenticated}`, 'info');
+                return;
+            }
+
+            logTest('Kernel 已连接并认证', 'info');
+        }
+
+        // 继续测试...
+        // 将所有 kernelClient.call() 改为 window.app.kernelClient.call()
+
+    } catch (err) {
+        logTest(`测试执行失败: ${err.message}`, 'fail');
+        console.error(err);
+    }
+}
+```
+
+#### 4.4 修改 evol-app.js 暴露 kernelClient
+
+**改动内容**：
+
+```javascript
+// evol-app.js
+// 在文件末尾，将 app 实例暴露到全局
+document.addEventListener('DOMContentLoaded', async () => {
+  const app = new EvolApp();
+  window.app = app;  // 新增：暴露到全局，供 registry-tests.js 使用
+  await app.init();
+
+  // ... 其他事件监听器 ...
+});
+```
+
+### 第五步：删除 /ws/management
+
+#### 5.1 删除 routes_management_ws.py
+
+**操作**：
+
+```bash
+rm extensions/services/evol/routes/routes_management_ws.py
+```
+
+#### 5.2 修改 server.py
+
+**改动位置**：`extensions/services/evol/server.py`
+
+**删除的代码**：
+
+```python
+# 删除导入
+# from extensions.services.evol.routes.routes_management_ws import router as management_ws_router, broadcast_event
+
+# 删除路由挂载
+# app.include_router(management_ws_router)  # /ws/management
+```
+
+#### 5.3 删除事件广播调用
+
+**搜索并删除**：
+
+在 `server.py` 中搜索 `broadcast_event` 的调用，全部删除。
+
+**示例**：
+
+```python
+# 删除类似这样的代码
+# await broadcast_event("module.started", {"module_id": module_name})
+```
+
+### 第六步：Evol RPC 方法标准化（可选）
+
+**目标**：将 Evol 的 HTTP RPC 方法注册到 Kite RPC 系统，使其可以通过 WebSocket 调用。
+
+**说明**：这一步是可选的，因为当前 HTTP RPC 仍然可用。但为了统一，建议逐步迁移。
+
+#### 6.1 创建 rpc_methods.py
+
+**新建文件**：`extensions/services/evol/rpc_methods.py`
+
+**内容**：
+
+```python
+# rpc_methods.py
+"""Evol 模块的 RPC 方法实现"""
+
+async def get_user_info(params: dict, context: dict):
+    """获取用户信息"""
+    # 从 context 中获取 kite_token
+    kite_token = context.get("kite_token")
+
+    # 调用业务逻辑
+    # ... 实现 ...
+
+    return {"success": True, "data": {...}}
+
+async def get_credits_stats(params: dict, context: dict):
+    """获取积分统计"""
+    # ... 实现 ...
+    pass
+
+async def list_kite_tokens(params: dict, context: dict):
+    """列出 Kite Token"""
+    # ... 实现 ...
+    pass
+
+# ... 其他 RPC 方法 ...
+```
+
+#### 6.2 在 entry.py 中注册
+
+**改动位置**：`extensions/services/evol/entry.py`
+
+**改动内容**：
+
+```python
+# entry.py
+from extensions.services.evol import rpc_methods
+
+async def register_rpc_methods(rpc_router):
+    """注册 Evol 的 RPC 方法"""
+    rpc_router.register("evol.get_user_info", rpc_methods.get_user_info)
+    rpc_router.register("evol.get_credits_stats", rpc_methods.get_credits_stats)
+    rpc_router.register("evol.list_kite_tokens", rpc_methods.list_kite_tokens)
+    # ... 注册其他方法 ...
+
+# 在模块启动时调用
+await register_rpc_methods(rpc_router)
+```
+
+#### 6.3 修改 relay.py 传递 context
+
+**目标**：在转发 RPC 请求时，将 kite_token 信息传递到 context。
+
+**改动位置**：`extensions/services/evol/relay.py`
+
+**改动内容**：
+
+```python
+# relay.py
+async def _forward_to_kernel(self, session: SessionInfo, msg: dict):
+    """转发消息到 Kernel"""
+    # 如果是 RPC 请求，添加 context 信息
+    if msg.get("method"):
+        # 添加 context（包含 kite_token）
+        if "params" not in msg:
+            msg["params"] = {}
+
+        msg["params"]["__context__"] = {
+            "module_id": session.module_id,
+            "role": session.role,
+            "kite_token": session.frontend_token if session.role == "admin" else None
+        }
+
+    # 转发到 Kernel
+    await session.kernel_ws.send(json.dumps(msg))
+```
+
+**注意**：这需要 Kernel 的 RPC 路由支持 `__context__` 参数传递。
+
+## 测试验证
+
+### 测试清单
+
+#### 1. 认证测试
+
+- [ ] 配对码认证成功
+- [ ] Kite Token 认证成功
+- [ ] 无效 token 认证失败
+- [ ] Token 过期后重新认证
+
+#### 2. 连接测试
+
+- [ ] 首次连接成功
+- [ ] 刷新页面后重连成功
+- [ ] 网络断开后自动重连
+- [ ] 多个标签页同时连接
+
+#### 3. RPC 测试
+
+- [ ] launcher.list_modules 调用成功
+- [ ] launcher.start_module 调用成功
+- [ ] launcher.stop_module 调用成功
+- [ ] kernel.health 调用成功
+- [ ] registry.lookup 调用成功
+
+#### 4. 事件测试
+
+- [ ] 订阅 module.* 事件成功
+- [ ] 接收 module.started 事件
+- [ ] 接收 module.stopped 事件
+- [ ] 接收 registry.updated 事件
+
+#### 5. UI 测试
+
+- [ ] 模块列表正常显示
+- [ ] 模块启动/停止正常
+- [ ] 连接状态指示器正常
+- [ ] 注册中心测试正常运行
+
+#### 6. 错误处理测试
+
+- [ ] Token 无效时显示登录页面
+- [ ] 网络错误时显示重连状态
+- [ ] RPC 调用失败时显示错误提示
+
+### 测试步骤
+
+#### 步骤 1：配对码认证测试
+
+1. 清除所有 localStorage 和 sessionStorage
+2. 访问控制台，应跳转到配对页面
+3. 生成配对码并配对
+4. 验证连接成功，可以正常使用
+
+#### 步骤 2：Kite Token 认证测试
+
+1. 清除所有 localStorage 和 sessionStorage
+2. 使用手机号登录（获得 kiteToken）
+3. 刷新页面，验证自动使用 kiteToken 连接
+4. 验证连接成功，可以正常使用
+
+#### 步骤 3：功能测试
+
+1. 打开模块管理页面
+2. 启动/停止模块，验证功能正常
+3. 查看模块详情，验证数据正确
+4. 运行注册中心测试，验证测试通过
+
+#### 步骤 4：多标签页测试
+
+1. 打开多个浏览器标签页
+2. 验证每个标签页都能正常连接
+3. 在一个标签页操作，验证其他标签页实时更新
+
+## 回滚方案
+
+如果改造过程中出现问题，可以按以下步骤回滚：
+
+### 回滚步骤
+
+1. **恢复 kernel-client-example.js**
+   ```bash
+   git checkout extensions/services/evol/static/js/kernel-client-example.js
+   ```
+
+2. **恢复 index.html**
+   ```bash
+   git checkout extensions/services/evol/static/index.html
+   ```
+
+3. **恢复 evol-app.js**
+   ```bash
+   git checkout extensions/services/evol/static/js/evol-app.js
+   ```
+
+4. **恢复 routes_management_ws.py**
+   ```bash
+   git checkout extensions/services/evol/routes/routes_management_ws.py
+   ```
+
+5. **恢复 server.py**
+   ```bash
+   git checkout extensions/services/evol/server.py
+   ```
+
+6. **重启 Kite**
+   ```bash
+   python main.py
+   ```
+
+## 注意事项
+
+### 1. 向后兼容
+
+- 保留 HTTP RPC API，确保旧版本客户端仍可使用
+- 配对码认证机制保持不变
+- 不破坏现有的配对码 token
+
+### 2. 性能考虑
+
+- WebSocket 连接数减少，降低服务器负载
+- 事件订阅需要显式调用，避免不必要的事件推送
+- RPC 调用通过 WebSocket，减少 HTTP 开销
+
+### 3. 安全考虑
+
+- Kite Token 认证默认 role 为 admin，需要确保 token 安全
+- 配对码认证保持原有的 role 控制
+- 所有 token 都有过期时间，定期清理
+
+### 4. 调试建议
+
+- 在浏览器控制台查看 WebSocket 消息
+- 在服务端日志查看认证和 RPC 调用
+- 使用 Chrome DevTools 的 Network 面板查看 WebSocket 连接
+
+## 后续工作
+
+完成本次改造后，可以继续进行以下工作：
+
+1. **RPC 方法标准化**
+   - 将所有 HTTP RPC 迁移到 Kite RPC
+   - 统一错误处理
+   - 统一参数验证
+
+2. **插件化准备**
+   - 设计插件接口
+   - 实现插件管理器
+   - 拆分 Evol 业务逻辑
+
+3. **控制台改名**
+   - 将 evol 模块改名为 kite-console
+   - 更新所有引用
+   - 更新文档
+
+4. **UI 优化**
+   - 统一 UI 风格
+   - 优化交互体验
+   - 添加加载状态
+
+## 总结
+
+本次改造的核心目标是**统一 WebSocket 连接**，为未来的插件化架构打好基础。改造完成后：
+
+- 前端只有一个 WebSocket 连接（`/ws/relay`）
+- 支持配对码和 Kite Token 两种认证方式
+- 代码更简洁，维护更容易
+- 为插件化架构做好准备
+
+改造过程中需要注意向后兼容和充分测试，确保不影响现有功能。