@agentunion/kite 1.4.0 → 1.6.0

package/docs/Kernel-Client-Kite-Token/346/224/257/346/214/201/345/256/236/346/226/275/345/256/214/346/210/220.md

@@ -0,0 +1,330 @@
+# Kernel Client Kite Token 支持 - 实施完成
+
+## 改动内容
+
+### kernel-client.js
+
+**修改位置**：`extensions/services/evol/static/js/kernel-client.js`
+
+**改动**：构造函数中的 Token 管理逻辑
+
+**修改前**：
+```javascript
+// Token 管理
+this.token = localStorage.getItem('frontend_token');
+```
+
+**修改后**：
+```javascript
+// Token 管理
+// 优先使用 kiteToken（Evol 业务），其次使用 frontend_token（配对码）
+this.token = localStorage.getItem('kiteToken') || localStorage.getItem('frontend_token');
+```
+
+## 工作原理
+
+### Token 优先级
+
+1. **优先使用 kiteToken**
+   - 如果 `localStorage.kiteToken` 存在，使用它
+   - 这是通过手机号登录获得的 Token
+
+2. **备用 frontend_token**
+   - 如果 `kiteToken` 不存在，使用 `frontend_token`
+   - 这是通过配对码获得的 Token
+
+3. **自动选择**
+   - 使用 JavaScript 的 `||` 运算符自动选择第一个非空值
+   - 无需额外的判断逻辑
+
+### 认证流程
+
+```
+用户打开页面
+    ↓
+KernelClient 构造函数执行
+    ↓
+检查 localStorage.kiteToken
+    ↓
+┌─────────────────────────────┐
+│ kiteToken 存在？            │
+├─────────────────────────────┤
+│ YES → 使用 kiteToken        │
+│ NO  → 检查 frontend_token   │
+│       ├─ 存在 → 使用它      │
+│       └─ 不存在 → token=null│
+└─────────────────────────────┘
+    ↓
+调用 connect() 方法
+    ↓
+发送认证消息到 /ws/relay
+    ↓
+Relay Service 验证 Token
+    ↓
+┌─────────────────────────────┐
+│ Token 类型？                │
+├─────────────────────────────┤
+│ kiteToken → Kite Token 认证 │
+│ frontend_token → 配对码认证 │
+└─────────────────────────────┘
+    ↓
+认证成功，建立连接
+```
+
+## 验证步骤
+
+### 方式 1：使用测试页面（推荐）
+
+1. 访问测试页面：`http://localhost:18766/test_kernel_client_token.html`
+
+2. 页面会自动检查 Token 状态：
+   - 显示 kiteToken 是否存在
+   - 显示 frontend_token 是否存在
+   - 显示将使用哪个 Token
+
+3. 点击"测试连接"按钮：
+   - 查看日志输出
+   - 确认使用的 Token 类型
+   - 验证连接是否成功
+
+4. 点击"测试 RPC"按钮：
+   - 测试 RPC 调用是否正常
+   - 验证权限是否正确
+
+### 方式 2：浏览器控制台测试
+
+1. 打开浏览器控制台（F12）
+
+2. 检查 Token：
+```javascript
+// 查看 kiteToken
+localStorage.getItem('kiteToken')
+
+// 查看 frontend_token
+localStorage.getItem('frontend_token')
+```
+
+3. 创建 KernelClient 实例：
+```javascript
+const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+const client = new KernelClient(`${proto}//${location.host}/ws/relay`);
+
+// 查看使用的 Token
+console.log('Token:', client.token);
+console.log('Session Token:', client.sessionToken);
+```
+
+4. 测试连接：
+```javascript
+client.connect().then(result => {
+    console.log('连接成功:', result);
+}).catch(err => {
+    console.error('连接失败:', err);
+});
+```
+
+### 方式 3：查看网络请求
+
+1. 打开浏览器开发者工具
+2. 切换到 Network 标签
+3. 过滤 WS（WebSocket）
+4. 刷新页面或测试连接
+5. 查看 WebSocket 消息：
+   - 找到 `/ws/relay` 连接
+   - 查看发送的认证消息
+   - 确认 `token` 字段的值
+
+**预期消息**：
+```json
+{
+  "type": "auth",
+  "token": "kite_xxx..." 或 "tok_xxx...",
+  "session_token": "sess_xxx..."
+}
+```
+
+### 方式 4：查看服务端日志
+
+```bash
+tail -50 "C:/Users/agentcp/.kite/workspace/Kite/evol/log/latest.log" | grep "Authenticated"
+```
+
+**预期输出**：
+
+使用 Kite Token 时：
+```
+[Relay] Authenticated via Kite Token, role=admin
+```
+
+使用配对码时：
+```
+[Relay] Authenticated via pairing code, role=admin
+```
+
+## 测试场景
+
+### 场景 1：只有 Kite Token
+
+**设置**：
+```javascript
+localStorage.setItem('kiteToken', 'kite_xxx...');
+localStorage.removeItem('frontend_token');
+```
+
+**预期结果**：
+- ✅ 使用 Kite Token 认证
+- ✅ 认证成功，role=admin
+- ✅ 可以正常调用 RPC
+
+### 场景 2：只有 Frontend Token
+
+**设置**：
+```javascript
+localStorage.removeItem('kiteToken');
+localStorage.setItem('frontend_token', 'tok_xxx...');
+```
+
+**预期结果**：
+- ✅ 使用 Frontend Token 认证
+- ✅ 认证成功，role 根据配对时设置
+- ✅ 可以正常调用 RPC
+
+### 场景 3：两个 Token 都存在
+
+**设置**：
+```javascript
+localStorage.setItem('kiteToken', 'kite_xxx...');
+localStorage.setItem('frontend_token', 'tok_xxx...');
+```
+
+**预期结果**：
+- ✅ 优先使用 Kite Token 认证
+- ✅ Frontend Token 作为备用（不使用）
+- ✅ 认证成功，role=admin
+
+### 场景 4：没有 Token
+
+**设置**：
+```javascript
+localStorage.removeItem('kiteToken');
+localStorage.removeItem('frontend_token');
+```
+
+**预期结果**：
+- ✅ client.token = null
+- ✅ connect() 抛出错误："No token found, please pair first"
+- ✅ 不会发送认证请求
+
+## 兼容性说明
+
+### 向后兼容
+
+- ✅ 现有的配对码流程完全不受影响
+- ✅ 只有 frontend_token 的用户继续正常工作
+- ✅ 不破坏任何现有功能
+
+### 新功能
+
+- ✅ 支持 Kite Token 认证
+- ✅ 自动选择最优 Token
+- ✅ 无需修改其他代码
+
+## 实际测试
+
+### 测试 1：使用现有的 Kite Token
+
+使用之前测试时获取的 Kite Token：
+
+```javascript
+// 在浏览器控制台执行
+localStorage.setItem('kiteToken', 'kite_-H8ZHUkIwwY8izeZ5sBn5yegOFgVInotkekRaSXd-T8');
+
+// 创建客户端
+const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+const client = new KernelClient(`${proto}//${location.host}/ws/relay`);
+
+// 连接
+await client.connect();
+```
+
+**预期结果**：
+- 连接成功
+- module_id: evol-client-xxx
+- role: admin
+
+### 测试 2：清除 Kite Token，使用配对码
+
+```javascript
+// 清除 Kite Token
+localStorage.removeItem('kiteToken');
+
+// 确保有配对码 Token（如果没有，需要先配对）
+// 然后重新创建客户端并连接
+```
+
+## 注意事项
+
+### 1. Token 的存储位置
+
+- **kiteToken**：存储在 `localStorage`
+- **frontend_token**：存储在 `localStorage`
+- **session_token**：存储在 `sessionStorage`
+
+### 2. Token 的生命周期
+
+- **kiteToken**：永久有效（除非手动吊销）
+- **frontend_token**：30 天有效期
+- **session_token**：浏览器会话期间有效
+
+### 3. 安全考虑
+
+- Token 存储在 localStorage，可能被 XSS 攻击窃取
+- 建议在生产环境使用 HTTPS
+- 定期检查和清理无效 Token
+
+### 4. 调试技巧
+
+查看 KernelClient 使用的 Token：
+```javascript
+// 在浏览器控制台
+console.log('Token:', window.kernelClient?.token);
+console.log('Token 来源:',
+    localStorage.getItem('kiteToken') ? 'kiteToken' :
+    localStorage.getItem('frontend_token') ? 'frontend_token' :
+    'none'
+);
+```
+
+## 下一步
+
+完成验证后，可以继续进行：
+
+1. **第三步**：改造 evol-app.js 使用 kernelClient
+2. **第四步**：删除 kernel-client-example.js
+3. **第五步**：删除 /ws/management
+
+## 回滚方案
+
+如果出现问题，可以回滚：
+
+```bash
+# 回滚 kernel-client.js
+git checkout extensions/services/evol/static/js/kernel-client.js
+
+# 删除测试页面
+rm extensions/services/evol/static/test_kernel_client_token.html
+
+# 刷新浏览器缓存
+# Ctrl + Shift + R (Chrome/Firefox)
+```
+
+## 测试清单
+
+- [ ] kiteToken 存在时，优先使用 kiteToken
+- [ ] kiteToken 不存在时，使用 frontend_token
+- [ ] 两个 Token 都不存在时，connect() 抛出错误
+- [ ] 使用 kiteToken 认证成功
+- [ ] 使用 frontend_token 认证成功
+- [ ] 认证成功后可以调用 RPC
+- [ ] 认证成功后可以订阅事件
+- [ ] 不影响现有的配对码流程

package/docs/Kernel/344/270/273/345/212/250Ping/346/234/272/345/210/266-/346/255/243/347/241/256/345/256/236/347/216/260.md

@@ -0,0 +1,235 @@
+# Kernel 主动 Ping 机制 - 正确实现
+
+## 机制概述
+
+Kernel 每 20 秒广播 `system.ping` 事件，所有模块收到后立即回复 `system.pong` 事件。Kernel 通过计算时间差得到往返延迟。
+
+## 时间点定义
+
+- **t1** = Kernel 发送 ping 的时间
+- **t2** = 模块收到 ping 并发送 pong 的时间（同一时刻）
+- **t3** = Kernel 收到 pong 的时间
+
+## 延迟计算
+
+- **去程延迟（outbound）** = t2 - t1（ping 从 Kernel 到模块）
+- **回程延迟（inbound）** = t3 - t2（pong 从模块到 Kernel）
+
+## 三种状态
+
+| 状态 | 说明 | 显示 |
+|-----|------|------|
+| `ok` | 正常收到 pong | 显示延迟数据 |
+| `timeout` | 20 秒内未收到 pong | 显示"超时" |
+| `never` | 从未收到过 pong | 显示"不支持" |
+
+## Kernel 端实现
+
+### 1. Ping 广播循环
+
+```python
+async def _ping_broadcast_loop(self):
+    """Broadcast system.ping event every 20s to all connected modules."""
+    while True:
+        await asyncio.sleep(20)
+
+        # Record ping send time
+        t1 = time.time()
+        for module_id in self.connections.keys():
+            self._ping_sent_times[module_id] = t1
+
+        # Broadcast system.ping event
+        self.event_hub.publish_internal(
+            "system.ping",
+            {"ping_time": t1},
+            source=self.module_id
+        )
+
+        # Check for timeouts after 20s
+        await asyncio.sleep(20)
+        for module_id in self.connections.keys():
+            if module_id in self._ping_sent_times:
+                # If no pong received, mark as timeout
+                if module_id not in self._pong_latencies or \
+                   self._pong_latencies[module_id].get("last_update", 0) < self._ping_sent_times[module_id]:
+                    if self._pong_status.get(module_id) != "never":
+                        self._pong_status[module_id] = "timeout"
+```
+
+### 2. Pong 事件处理
+
+```python
+async def _handle_pong_event(self, data: dict):
+    """处理 system.pong 事件，计算往返延迟"""
+    module_id = data.get("module_id")
+    t1 = data.get("ping_time")  # Kernel 发送 ping 的时间
+    t2 = data.get("pong_time")  # 模块收到 ping 并发送 pong 的时间
+    t3 = time.time()  # Kernel 收到 pong 的时间
+
+    # 计算两个延迟
+    outbound_ms = (t2 - t1) * 1000  # 去程
+    inbound_ms = (t3 - t2) * 1000   # 回程
+
+    self._pong_latencies[module_id] = {
+        "outbound": round(outbound_ms, 2),
+        "inbound": round(inbound_ms, 2),
+        "last_update": t3,
+    }
+    self._pong_status[module_id] = "ok"
+```
+
+### 3. RPC 查询接口
+
+```python
+async def _kernel_latencies(self, caller_id: str, params: dict) -> dict:
+    """Get ping/pong latencies for all connected modules."""
+    result = {}
+    for module_id in self.connections.keys():
+        latency_data = self._pong_latencies.get(module_id, {})
+        status = self._pong_status.get(module_id, "never")
+
+        result[module_id] = {
+            "outbound": latency_data.get("outbound"),
+            "inbound": latency_data.get("inbound"),
+            "status": status,
+        }
+
+    return {"latencies": result}
+```
+
+## 模块端实现（示例）
+
+### 事件处理器
+
+```python
+async def _handle_event_notification(msg: dict):
+    """Handle incoming event notifications."""
+    event_type = msg.get("event", "")
+    data = msg.get("data", {})
+
+    if event_type == "system.ping":
+        # 收到 ping，立即回复 pong
+        await _handle_ping_event(data)
+    elif event_type == "module.shutdown":
+        await _handle_shutdown()
+    # ... 其他事件处理
+```
+
+### Ping 事件处理
+
+```python
+async def _handle_ping_event(data: dict):
+    """Handle system.ping event and reply with system.pong."""
+    import time
+
+    t1 = data.get("ping_time")  # Kernel 发送 ping 的时间
+    t2 = time.time()  # 模块收到 ping 并发送 pong 的时间（同一时刻）
+
+    await _publish_event(_ws_global, {
+        "event": "system.pong",
+        "data": {
+            "module_id": MODULE_NAME,
+            "ping_time": t1,  # 原样返回
+            "pong_time": t2,  # 模块收到并发送的时间
+        },
+    })
+```
+
+## 使用示例
+
+### 查询延迟
+
+```python
+# 通过 RPC 调用
+resp = await rpc_call("kernel.latencies", {})
+latencies = resp["result"]["latencies"]
+
+# 返回示例
+{
+    "latencies": {
+        "launcher": {
+            "outbound": 2.34,  # Kernel → launcher: 2.34ms
+            "inbound": 1.89,   # launcher → Kernel: 1.89ms
+            "status": "ok"
+        },
+        "watchdog": {
+            "outbound": 3.12,
+            "inbound": 2.56,
+            "status": "ok"
+        },
+        "web": {
+            "outbound": null,
+            "inbound": null,
+            "status": "timeout"  # 20 秒内未响应
+        },
+        "backup": {
+            "outbound": null,
+            "inbound": null,
+            "status": "never"  # 从未响应过（不支持 ping）
+        }
+    }
+}
+```
+
+### 在模块列表中显示
+
+```python
+async def _rpc_list_modules(self, params: dict) -> dict:
+    # 获取延迟数据
+    latencies_resp = await self._rpc_call(self._ws, "kernel.latencies", {})
+    latencies = latencies_resp.get("result", {}).get("latencies", {})
+
+    result = []
+    for name, info in self.modules.items():
+        latency_info = latencies.get(name, {})
+        status = latency_info.get("status", "never")
+
+        rec = {
+            "name": name,
+            ...
+            "ping_status": status,
+            "ping_outbound_ms": latency_info.get("outbound"),
+            "ping_inbound_ms": latency_info.get("inbound"),
+        }
+        result.append(rec)
+
+    return {"modules": result}
+```
+
+## 优势
+
+1. **无需模块注册** — `system.ping` 是系统事件，自动广播给所有模块
+2. **双向延迟可见** — 分别测量去程和回程延迟
+3. **三种状态区分** — 正常、超时、不支持
+4. **实现简单** — 模块只需处理一个事件，回复一个事件
+5. **无侵入性** — 不支持 ping 的模块不会报错，只是标记为 "never"
+
+## 注意事项
+
+1. **时间同步** — 所有时间戳使用 `time.time()`（Unix 时间戳）
+2. **立即响应** — 模块收到 ping 后应立即发送 pong，不要延迟
+3. **原样返回 ping_time** — pong 事件中的 `ping_time` 必须与 ping 事件中的一致
+4. **超时判定** — 20 秒内未收到 pong 视为超时
+5. **状态持久化** — `never` 状态会一直保持，直到收到第一个 pong
+
+## 实施步骤
+
+### Kernel 端（已完成）
+- ✅ 添加 ping 广播循环
+- ✅ 订阅 `system.pong` 事件
+- ✅ 实现 pong 事件处理
+- ✅ 实现 `kernel.latencies` RPC 方法
+- ✅ 超时检测逻辑
+
+### 模块端（待实施）
+- ⏳ 在事件处理器中添加 `system.ping` 处理
+- ⏳ 实现 `_handle_ping_event` 函数
+- ⏳ 测试 ping/pong 流程
+
+## 测试方法
+
+1. 启动 Kite
+2. 等待 20 秒（第一次 ping）
+3. 调用 `kernel.latencies` RPC 查看延迟数据
+4. 检查各模块的状态（ok/timeout/never）
+5. 手动停止一个模块，观察是否变为 timeout