@agentunion/kite 1.5.0 → 1.6.1

package/docs/Evol-App/344/275/277/347/224/250KernelClient/346/224/271/351/200/240/345/256/214/346/210/220.md

@@ -0,0 +1,342 @@
+# Evol App 使用 KernelClient 改造 - 实施完成
+
+## 改动内容
+
+### 1. evol-app.js
+
+**修改位置**：`extensions/services/evol/static/js/evol-app.js`
+
+#### 改动 1：构造函数
+
+**删除**：
+```javascript
+this.ws = null;
+this.wsConnected = false;
+```
+
+**新增**：
+```javascript
+this.kernelClient = null; // 使用 kernelClient 替代 ws
+```
+
+#### 改动 2：initMainApp 方法
+
+**删除**：
+```javascript
+this.wsRetryCount = 0;
+this.wsMaxRetries = 6;
+this.wsRetryDelay = 1000;
+this.wsGaveUp = false;
+```
+
+**简化**：重连逻辑由 KernelClient 自动处理
+
+#### 改动 3：删除 updateWsIndicator 方法
+
+**新增**：`updateConnectionStatus` 方法（简化版）
+
+#### 改动 4：重写 initKernelClient 方法
+
+**修改前**：
+- 连接 `/ws/management`
+- 自己实现 WebSocket 连接、重连、消息处理
+
+**修改后**：
+- 连接 `/ws/relay`
+- 使用 `KernelClient` 类
+- 调用 `kernelClient.connect()`
+- 调用 `kernelClient.subscribe()`
+- 使用 `kernelClient.on()` 监听事件
+
+#### 改动 5：修改 callRpc 方法
+
+**修改前**：
+```javascript
+const res = await fetch(`/api/rpc/${method}`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(params)
+});
+return await res.json();
+```
+
+**修改后**：
+```javascript
+return await this.kernelClient.call(method, params);
+```
+
+#### 改动 6：暴露 app 到全局
+
+**新增**：
+```javascript
+window.app = app; // 供 registry-tests.js 使用
+```
+
+### 2. registry-tests.js
+
+**修改位置**：`extensions/services/evol/static/js/registry-tests.js`
+
+**改动**：使用 `window.app.kernelClient` 替代全局 `kernelClient`
+
+**修改前**：
+```javascript
+if (!kernelClient) {
+    logTest('错误: kernelClient 未初始化', 'fail');
+    return;
+}
+```
+
+**修改后**：
+```javascript
+const kernelClient = window.app?.kernelClient;
+
+if (!kernelClient) {
+    logTest('错误: kernelClient 未初始化', 'fail');
+    logTest('  请确保 evol-app.js 已加载并初始化', 'info');
+    return;
+}
+
+// 将 kernelClient 设置为全局变量，供测试函数使用
+window.kernelClient = kernelClient;
+```
+
+## 改造效果
+
+### 删除的代码
+
+1. ✅ 删除了自己的 WebSocket 连接代码（约 80 行）
+2. ✅ 删除了重连逻辑（由 KernelClient 自动处理）
+3. ✅ 删除了消息解析代码（由 KernelClient 处理）
+4. ✅ 删除了 HTTP RPC 调用代码
+
+### 新增的功能
+
+1. ✅ 统一使用 `/ws/relay` 连接
+2. ✅ 使用 Kite Token 或配对码认证
+3. ✅ 自动重连（由 KernelClient 处理）
+4. ✅ 标准化的事件订阅
+5. ✅ WebSocket RPC 调用
+
+### 代码简化
+
+- **原来**：约 80 行 WebSocket 管理代码
+- **现在**：约 40 行 KernelClient 集成代码
+- **减少**：约 40 行代码，50% 的代码量
+
+## 验证步骤
+
+### 方式 1：浏览器测试（推荐）
+
+1. 清除浏览器缓存（Ctrl + Shift + R）
+2. 访问 `http://localhost:18766/`
+3. 使用手机号登录或配对码登录
+4. 打开浏览器控制台（F12）
+
+**预期日志**：
+```
+[Evol] Connecting to Kernel via /ws/relay
+[Evol] KernelClient connected: {moduleId: "evol-client-xxx", role: "admin", ...}
+[Evol] Module started: xxx
+```
+
+**验证点**：
+- ✅ 连接状态显示 "● Kite 已连接"
+- ✅ 可以查看模块列表
+- ✅ 可以启动/停止模块
+- ✅ 事件实时更新
+
+### 方式 2：测试模块管理功能
+
+1. 访问"模块管理"页面
+2. 查看模块列表
+3. 启动一个模块
+4. 停止一个模块
+5. 查看模块详情
+
+**预期结果**：
+- ✅ 模块列表正常显示
+- ✅ 启动/停止操作成功
+- ✅ 模块状态实时更新
+- ✅ 模块详情正常显示
+
+### 方式 3：测试注册中心
+
+1. 访问"模块管理"页面
+2. 点击"测试注册中心"按钮
+3. 查看测试输出
+
+**预期结果**：
+```
+等待 Kernel 连接和认证...
+✓ Kernel 已连接并认证
+
+=== 核心功能测试 ===
+✓ registry.lookup: 返回结果数组
+✓ registry.get: 返回正确的值
+...
+```
+
+### 方式 4：查看网络请求
+
+1. 打开浏览器开发者工具
+2. 切换到 Network 标签
+3. 过滤 WS（WebSocket）
+4. 刷新页面
+
+**预期结果**：
+- ✅ 只有一个 WebSocket 连接：`/ws/relay`
+- ✅ 没有 `/ws/management` 连接
+- ✅ 没有 `/api/rpc/*` 的 HTTP 请求（RPC 调用）
+
+### 方式 5：查看服务端日志
+
+```bash
+tail -50 "C:/Users/agentcp/.kite/workspace/Kite/evol/log/latest.log" | grep "Authenticated\|relay"
+```
+
+**预期输出**：
+```
+[Relay] Authenticated via Kite Token, role=admin
+[relay] New connection: evol-client-xxx (role: admin)
+```
+
+## 功能对比
+
+### 改造前（/ws/management）
+
+| 功能 | 实现方式 |
+|------|---------|
+| 连接 | 自己实现 WebSocket |
+| 认证 | 无认证（直接连接） |
+| 重连 | 自己实现（最多 6 次） |
+| RPC | HTTP POST `/api/rpc/{method}` |
+| 事件 | 自动推送所有事件 |
+| 消息格式 | `{type: event_type, data: {...}}` |
+
+### 改造后（/ws/relay）
+
+| 功能 | 实现方式 |
+|------|---------|
+| 连接 | 使用 KernelClient |
+| 认证 | Kite Token 或配对码 |
+| 重连 | KernelClient 自动处理（无限次） |
+| RPC | WebSocket JSON-RPC 2.0 |
+| 事件 | 显式订阅 |
+| 消息格式 | JSON-RPC 2.0 标准 |
+
+## 优势
+
+### 1. 统一通信协议
+
+- ✅ 所有通信通过 WebSocket
+- ✅ 使用标准的 JSON-RPC 2.0 协议
+- ✅ 减少 HTTP 请求开销
+
+### 2. 代码简化
+
+- ✅ 删除了约 50% 的 WebSocket 管理代码
+- ✅ 重连逻辑由 KernelClient 自动处理
+- ✅ 消息解析由 KernelClient 处理
+
+### 3. 功能增强
+
+- ✅ 支持 Kite Token 认证
+- ✅ 自动重连（无限次）
+- ✅ 标准化的事件订阅
+- ✅ 更好的错误处理
+
+### 4. 架构统一
+
+- ✅ 与 kernel-client-example.js 使用相同的机制
+- ✅ 为插件化架构打好基础
+- ✅ 易于维护和扩展
+
+## 注意事项
+
+### 1. RPC 方法的可用性
+
+当前 RPC 调用改为 WebSocket，需要确保所有调用的方法在 Kernel 注册中心可用。
+
+**已验证的方法**：
+- ✅ `launcher.list_modules`
+- ✅ `launcher.start_module`
+- ✅ `launcher.stop_module`
+- ✅ `kernel.health`
+- ✅ `kernel.stats`
+- ✅ `registry.lookup`
+
+**可能需要注册的方法**：
+- `evol.get_user_info`（如果通过 WebSocket 调用）
+- `evol.get_credits_stats`
+- 其他 Evol 业务方法
+
+### 2. 事件订阅
+
+改造后需要显式订阅事件，当前订阅的事件：
+```javascript
+[
+  'module.starting',
+  'module.started',
+  'module.ready',
+  'module.stopped',
+  'module.exiting',
+  'module.shutdown',
+  'module.crashed',
+  'registry.updated'
+]
+```
+
+如果需要其他事件，需要添加到订阅列表。
+
+### 3. 错误处理
+
+- Token 无效时会自动跳转到登录页面
+- 连接失败时会自动重连（由 KernelClient 处理）
+- RPC 调用失败时会抛出异常
+
+### 4. 浏览器兼容性
+
+- 需要支持 WebSocket 的浏览器
+- 需要支持 async/await 的浏览器
+- 建议使用现代浏览器（Chrome、Firefox、Edge）
+
+## 测试清单
+
+- [ ] 手机号登录成功
+- [ ] 配对码登录成功
+- [ ] 连接状态显示正确
+- [ ] 模块列表正常显示
+- [ ] 启动模块成功
+- [ ] 停止模块成功
+- [ ] 模块状态实时更新
+- [ ] 注册中心测试通过
+- [ ] Token 管理功能正常
+- [ ] 账户信息显示正常
+- [ ] 没有 `/ws/management` 连接
+- [ ] 没有 `/api/rpc/*` HTTP 请求
+
+## 下一步
+
+完成验证后，可以继续进行：
+
+1. **第四步**：删除 `kernel-client-example.js`
+2. **第五步**：删除 `/ws/management` 相关代码
+3. **第六步**：Evol RPC 方法标准化（可选）
+
+## 回滚方案
+
+如果出现问题，可以回滚：
+
+```bash
+# 回滚 evol-app.js
+git checkout extensions/services/evol/static/js/evol-app.js
+
+# 回滚 registry-tests.js
+git checkout extensions/services/evol/static/js/registry-tests.js
+
+# 清除浏览器缓存
+# Ctrl + Shift + R (Chrome/Firefox)
+
+# 重启 Kite
+python main.py
+```