@agentunion/kite 1.4.0 → 1.6.0

package/.claude/skills/kite/references/test-center-integration.md

@@ -0,0 +1,178 @@
+# 测试中心接入指南
+
+## 概述
+
+Kite 测试中心在 kite_console 前端，支持模块测试和集成测试。要让新模块的测试出现在测试中心，需要修改 4 个文件。
+
+## 接入步骤
+
+### Step 1: 创建测试文件
+
+创建 `extensions/services/kite_console/static/js/tests/modules/{module_name}.js`
+
+```javascript
+/**
+ * {display_name} 模块测试
+ */
+
+async function test{PascalName}Module() {
+  const runner = window.testRunner;
+  const client = runner.kernelClient;
+
+  runner.log('【{display_name} 模块测试】', 'section');
+
+  // ── 存在性检查 ──
+  await runner.runTest('{display_name} 存在性检查', async () => {
+    const result = await client.call('launcher.list_modules', {});
+    const mod = result.modules.find(m => m.name === '{module_name}');
+    if (!mod) throw new Error('{display_name} 模块未找到');
+  });
+
+  // ── RPC 方法注册验证 ──
+  runner.log('', 'info');
+  runner.log('RPC 方法注册验证', 'subsection');
+
+  const rpcMethods = [
+    { method: 'health', path: 'tools.rpc.module.health' },
+    { method: 'status', path: 'tools.rpc.module.status' },
+    // 添加更多 RPC 方法...
+  ];
+
+  for (const { method, path } of rpcMethods) {
+    await runner.runTest(`{module_name}.${method} 注册检查`, async () => {
+      const result = await client.call('registry.lookup', {
+        field: path,
+        module: '{module_name}',
+      });
+      if (!result.results || result.results.length === 0) {
+        throw new Error(`${method} 未注册`);
+      }
+    });
+  }
+
+  // ── 事件注册验证 ──
+  runner.log('', 'info');
+  runner.log('事件注册验证', 'subsection');
+
+  const events = ['{module_name}.test'];
+  for (const event of events) {
+    await runner.runTest(`${event} 事件注册`, async () => {
+      const result = await client.call('registry.lookup', {
+        field: `events_publish.${event.replace('.', '.')}`,
+        module: '{module_name}',
+      });
+      if (!result.results || result.results.length === 0) {
+        throw new Error(`${event} 事件未注册`);
+      }
+    });
+  }
+
+  // ── RPC 方法功能测试 ──
+  runner.log('', 'info');
+  runner.log('RPC 方法功能测试', 'subsection');
+
+  await runner.runTest('{module_name}.health 功能测试', async () => {
+    const result = await client.call('{module_name}.health', {});
+    if (!result || result.error) {
+      throw new Error(`health 调用失败: ${JSON.stringify(result)}`);
+    }
+    if (result.status !== 'ok') {
+      throw new Error(`health 状态异常: ${result.status}`);
+    }
+  });
+
+  runner.log('');
+}
+
+// ⚠️ 必须注册到 window 对象
+window.test{PascalName}Module = test{PascalName}Module;
+```
+
+### Step 2: 添加到映射表
+
+编辑 `extensions/services/kite_console/static/js/tests/index.js`：
+
+在 `MODULE_TESTS` 对象中添加一行：
+
+```javascript
+const MODULE_TESTS = {
+  kernel: 'testKernelModule',
+  launcher: 'testLauncherModule',
+  // ... 现有条目 ...
+  {module_name}: 'test{PascalName}Module',  // ← 添加这行
+};
+```
+
+### Step 3: 加载测试脚本
+
+编辑 `extensions/services/kite_console/static/index.html`：
+
+在测试脚本加载区域（其他 `modules/*.js` 的 `<script>` 标签之后，`index.js` 之前）添加：
+
+```html
+<script src="js/tests/modules/{module_name}.js"></script>
+```
+
+**位置必须在 `index.js` 之前！**
+
+### Step 4: 添加下拉选项
+
+编辑 `extensions/services/kite_console/static/index.html`：
+
+在 `#test-module-select` 下拉框中添加选项：
+
+```html
+<option value="{module_name}">{display_name}</option>
+```
+
+## 命名约定（必须严格遵守）
+
+| 项目 | 约定 | 示例 |
+|------|------|------|
+| 模块名（key） | 小写 + 下划线 | `my_service` |
+| 测试文件名 | 小写 + 下划线 + `.js` | `my_service.js` |
+| 测试函数名 | `test` + PascalCase + `Module` | `testMyServiceModule` |
+| window 注册 | 同函数名 | `window.testMyServiceModule` |
+| 映射表 key | 同模块名 | `my_service: 'testMyServiceModule'` |
+| 下拉框 value | 同模块名 | `<option value="my_service">` |
+
+**任何一个命名不一致，测试都不会出现或不会运行。**
+
+## 常见失败原因（按频率排序）
+
+| 排名 | 问题 | 现象 | 修复 |
+|------|------|------|------|
+| 1 | 函数名与映射不匹配 | 点击运行无反应 | 确认函数名、window 注册、映射表三处一致 |
+| 2 | 未在 HTML 中加载脚本 | `testXxxModule is not a function` | 添加 `<script>` 标签 |
+| 3 | 脚本在 index.js 之后加载 | 测试执行时找不到函数 | 移到 index.js 之前 |
+| 4 | 未添加下拉选项 | 测试不出现在界面上 | 添加 `<option>` |
+| 5 | 函数不是 async | 测试挂起或结果不正确 | 改为 `async function` |
+| 6 | 忘记 `window.xxx = xxx` | 函数存在但找不到 | 添加 window 注册 |
+| 7 | RPC 方法名写错 | 测试报 method not found | 确认与 registry.register 中一致 |
+| 8 | 缺少 `runner.log('')` 结尾 | 格式混乱 | 末尾加空行 |
+| 9 | `await` 漏写 | 返回 Promise 对象而非结果 | 所有 client.call 前加 await |
+
+## 测试 API 参考
+
+### runner 方法
+
+```javascript
+runner.log(message, type)         // type: 'section' | 'subsection' | 'info' | 'warn' | 'error'
+runner.runTest(name, asyncFn)     // 执行测试用例
+runner.pass(name)                 // 手动标记通过
+runner.fail(name, error)          // 手动标记失败
+runner.skip(name, reason)         // 跳过测试
+runner.generateReport()           // 生成报告 {summary, fullLog, errorLog}
+runner.uploadLog(testName)        // 上传日志到后端
+```
+
+### client 方法
+
+```javascript
+const result = await client.call(method, params)   // RPC 调用
+await client.subscribe(events)                      // 订阅事件
+```
+
+## 集成测试接入
+
+集成测试流程类似，但放在 `integration/` 目录，映射表用 `INTEGRATION_TESTS`，下拉框用 `#test-integration-select`。

package/.claude/skills/kite/references/ws-lifecycle.md

@@ -0,0 +1,301 @@
+# WebSocket 连接生命周期
+
+## 完整时序
+
+```
+模块进程启动
+  ↓
+读取 boot_info（stdin）
+  ↓
+连接 Kernel WebSocket（ws://127.0.0.1:{port}/ws）
+  ↓
+发送 auth 消息 ──→ Kernel 验证 token
+  ↓                    ↓
+收到 auth 响应 ←── {ok: true, session_id, seq}
+  ↓
+等待 system.require_init 事件（Kernel 发出，表示可以初始化）
+  ↓
+执行 _do_init()：
+  ├─ event.subscribe（订阅事件）
+  ├─ registry.register（注册模块信息）
+  └─ event.publish module.ready（通告就绪）
+  ↓
+进入消息接收循环
+  ↓
+运行中...处理 RPC 请求、事件通知
+  ↓
+收到 module.shutdown 事件
+  ↓
+执行优雅关闭序列（见 shutdown-sequence.md）
+```
+
+## 1. WebSocket 连接
+
+```python
+import websockets
+
+uri = f"ws://127.0.0.1:{kernel_port}/ws"
+ws = await websockets.connect(uri, max_size=16 * 1024 * 1024)
+```
+
+**注意事项：**
+- `max_size` 设为 16MB，防止大消息被截断
+- 不要在 URI 中附加 query 参数（如 `?id=xxx`），认证通过 auth 消息完成
+
+## 2. 认证
+
+连接后立即发送 auth 消息，**必须在 5 秒内完成**，否则 Kernel 会断开连接（code 4002）。
+
+### 发送
+
+```python
+auth_msg = {
+    "jsonrpc": "2.0",
+    "id": str(uuid.uuid4()),
+    "method": "auth",
+    "params": {"token": token}
+}
+await ws.send(json.dumps(auth_msg))
+```
+
+### 接收
+
+```python
+resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+if resp.get("error") or not resp.get("result", {}).get("ok"):
+    # 认证失败，关闭连接
+    await ws.close()
+    return
+session_id = resp["result"]["session_id"]
+```
+
+### 认证失败错误码
+
+| Close Code | 含义 | 是否重试 |
+|------------|------|----------|
+| 4001 | token 无效 | ❌ 致命，不重试 |
+| 4002 | 认证超时 | ⚠️ 可重试 |
+| 4003 | 模块已被停止 | ❌ 致命 |
+| 4004 | token 已过期 | ❌ 致命 |
+| 4010 | 被禁止 | ❌ 致命 |
+| 4020 | 速率限制 | ⚠️ 等 10 秒后重试，最多 5 次 |
+| 1008 | 协议违规 | ❌ 致命 |
+
+## 3. 等待 system.require_init
+
+认证成功后，**不要立即执行初始化**。必须等待 Kernel 发送 `system.require_init` 事件。
+
+```python
+# 在消息接收循环中
+if event_type == "system.require_init":
+    asyncio.create_task(self._do_init(ws))
+```
+
+**为什么不能立即初始化：**
+- Kernel 可能处于恢复模式（recovery），此时 init gate 关闭
+- 必须等 Launcher 就绪后 Kernel 才会打开 gate
+- 如果直接初始化，registry.register 可能失败或数据丢失
+
+## 4. 初始化序列 (_do_init)
+
+**顺序严格，不可调换：**
+
+```python
+async def _do_init(self, ws):
+    # 第 1 步：订阅事件
+    await self._rpc_call(ws, "event.subscribe", {
+        "events": [
+            "module.started", "module.stopped", "module.crashed",
+            "module.ready", "module.exiting", "module.shutdown",
+            "module.shutdown.ack", "module.shutdown.ready",
+            "system.ping",
+        ]
+    })
+
+    # 第 2 步：注册到注册中心
+    await self._rpc_call(ws, "registry.register", {
+        "module_id": self._module_name,
+        "module_type": "service",  # 或 channel / agent
+        "name": self._display_name,
+        "tools": {
+            "rpc": {
+                "module": {
+                    "health": {"description": "健康检查"},
+                    "status": {"description": "状态查询"},
+                }
+            }
+        },
+        "events_publish": {
+            self._module_name: {
+                "test": {"description": "测试事件"},
+            }
+        },
+        "events_subscribe": [
+            "module.started", "module.stopped", "module.shutdown",
+        ],
+    })
+
+    # 第 3 步：发布 module.ready
+    await self._publish_event(ws, "module.ready", {
+        "module_id": self._module_name,
+    })
+```
+
+**关键坑：**
+1. 必须先 subscribe 再 register，否则可能漏收注册完成后立即到来的事件
+2. registry.register 中的 `events_subscribe` 是声明性的（告诉注册中心"我订阅了什么"），实际订阅靠 `event.subscribe` RPC
+3. `module.ready` 必须在 register 之后发布，否则 Kernel 会认为模块还没注册就上报了 ready
+
+## 5. 运行阶段（三个子阶段）
+
+### 5a. 连接扩展（紧跟 ready 之后）
+
+如果 `max_connections > 1`，Kernel 在模块 ready 后自动发送 `system.connection.offer`：
+
+```
+module.ready 发布
+    ↓
+Kernel 检测 max_connections > 1
+    ↓
+Kernel → system.connection.offer {slot: 1, token: "slot_token_1"}
+Kernel → system.connection.offer {slot: 2, token: "slot_token_2"}
+    ↓
+模块建立 Slot 1, 2 附加连接（各自独立 WebSocket）
+    ↓
+运行中可能收到 system.connection.release（释放某个槽）
+```
+
+详见 `multi-connection.md`。
+
+### 5b. 稳态运行
+
+模块进入消息接收循环，持续处理以下内容：
+
+| 内容 | 频率 | 说明 |
+|------|------|------|
+| RPC 请求/响应 | 按需 | 其他模块或 Kernel 发来的调用 |
+| 事件通知 | 按需 | 订阅的事件到达 |
+| system.ping / pong | 5-60 秒 | 框架层连通性检查，3 次超时断连 |
+| health RPC | 2-15 秒 | Watchdog 业务层健康检查，3 次不健康重启 |
+| 压力上报 | 12 秒 | `module.queue_pressure` 事件，弹性伸缩用 |
+| 测试事件 | 12 秒 | `{module}.test` 事件，验证事件系统正常 |
+
+健康检查详见 `health-check.md`。
+
+### 5c. 实例伸缩（Launcher 层面）
+
+Kernel 根据压力报告决定扩缩，通过 RPC 通知 Launcher：
+
+```
+模块上报 module.queue_pressure {level: "overload"}
+    ↓
+Kernel instance_scaler_loop（每 5 秒检查）
+    ↓
+所有实例都 overload 且持续 → 通知 Launcher 启动新实例
+    ↓
+新实例是独立进程，走完整生命周期（连接→认证→初始化→ready）
+    ↓
+所有实例都 idle 且实例数 > 1 → 通知 Launcher 停止多余实例
+```
+
+- 冷却期：伸缩操作之间至少 30 秒
+- 上限：`max_instances`（module.md 中声明，最大 10）
+- 需要 `instance_elastic: true` 才启用
+
+## 6. 消息接收循环
+
+```python
+async for raw in ws:
+    msg = json.loads(raw)
+
+    has_method = "method" in msg
+    has_id = "id" in msg
+    has_result = "result" in msg
+    has_error = "error" in msg
+
+    if has_method and has_id:
+        # RPC 请求（来自其他模块或 Kernel）
+        asyncio.create_task(self._handle_rpc_request(ws, msg))
+    elif has_method and not has_id:
+        # 事件通知（来自 Kernel Event Hub）
+        asyncio.create_task(self._handle_event_notification(msg))
+    elif has_id and (has_result or has_error):
+        # RPC 响应（我之前发出的请求的回复）
+        self._handle_rpc_response(msg)
+```
+
+### ⚠️ 致命坑：RPC 死锁
+
+**绝对不可以 await 入站 RPC handler！必须用 `asyncio.create_task()`。**
+
+原因：
+```
+1. 收到入站 RPC 请求 A
+2. handler 中需要调用 _rpc_call() 发出站 RPC 请求 B
+3. 请求 B 的响应需要当前接收循环来分发
+4. 如果接收循环被 await handler 阻塞 → 响应 B 永远收不到 → 超时死锁
+```
+
+**正确写法：**
+```python
+asyncio.create_task(self._handle_rpc_request(ws, msg))  # ✅ 不阻塞接收循环
+```
+
+**错误写法：**
+```python
+await self._handle_rpc_request(ws, msg)  # ❌ 会导致死锁
+```
+
+**RPC 响应可以同步处理**（它只是 resolve 一个 future，不会阻塞）：
+```python
+self._handle_rpc_response(msg)  # ✅ 同步 OK
+```
+
+## 6. 重连逻辑
+
+```python
+retry_delay = 0.3  # 初始延迟
+max_delay = 5.0    # 最大延迟
+max_retries = 10   # 最大重试次数
+
+for attempt in range(max_retries):
+    try:
+        ws = await websockets.connect(uri)
+        await self._ws_connect(ws)
+        retry_delay = 0.3  # 连接成功后重置
+        break
+    except websockets.ConnectionClosedError as e:
+        if e.code in (4001, 4003, 4004, 1008, 4010):
+            print(f"[FATAL] 致命错误 code={e.code}，不重试")
+            return
+        if e.code == 4020:  # 速率限制
+            await asyncio.sleep(10)
+            continue
+    except (ConnectionRefusedError, OSError) as e:
+        pass
+
+    # 指数退避 + 随机抖动
+    jitter = retry_delay * 0.2 * random.random()
+    await asyncio.sleep(retry_delay + jitter)
+    retry_delay = min(retry_delay * 2, max_delay)
+```
+
+**Windows 特殊处理：**
+```python
+except OSError as e:
+    # Windows 下 ConnectionRefusedError 有时表现为 WinError 1225
+    if hasattr(e, 'winerror') and e.winerror == 1225:
+        pass  # 等同于 ConnectionRefusedError
+    else:
+        raise
+```
+
+## 7. 连接断开后的清理
+
+```python
+# 清理所有未完成的 RPC 请求
+for req_id, future in self._pending_rpc.items():
+    if not future.done():
+        future.set_exception(ConnectionError("WebSocket 断开"))
+self._pending_rpc.clear()
+```