@agentunion/kite 1.4.0 → 1.6.0

package/.claude/skills/kite/references/multi-connection.md

@@ -0,0 +1,147 @@
+# 多连接槽管理
+
+## 概述
+
+Kite 支持模块与 Kernel 建立多个 WebSocket 连接（槽/slot）。Slot 0 是主连接，Slot 1+ 是附加连接。
+
+多连接的目的：
+- 分散消息处理压力
+- 支持并行 RPC 处理
+- 提高吞吐量
+
+## 配置
+
+在 `module.md` 中设置：
+
+```yaml
+max_connections: 3  # 最大连接数（1-10，钳位）
+```
+
+## 连接建立流程
+
+```
+模块建立主连接（Slot 0）
+    ↓
+Kernel 收到主连接注册
+    ↓
+Kernel 检查 max_connections > 1
+    ↓
+Kernel 生成 slot token 并发送 system.connection.offer 事件
+    ↓
+模块收到 offer，使用 slot token 建立新连接
+    ↓
+模块通过新连接发送 auth（slot token）
+    ↓
+Kernel 验证 slot token，关联到同一模块
+    ↓
+新连接进入消息接收循环
+```
+
+## 标准实现
+
+### 数据结构
+
+```python
+def __init__(self):
+    self._ws = None                    # 主连接 (Slot 0)
+    self._extra_ws: dict = {}          # {slot_num: websocket}
+    self._extra_ws_tasks: dict = {}    # {slot_num: asyncio.Task}
+```
+
+### 处理 connection.offer
+
+```python
+async def _handle_connection_offer(self, data: dict):
+    """处理 Kernel 发来的连接槽邀请。"""
+    slot = data.get("slot")
+    slot_token = data.get("token")
+
+    if slot is None or not slot_token:
+        print(f"[SLOT] offer 数据不完整: {data}")
+        return
+
+    if slot in self._extra_ws:
+        print(f"[SLOT] 槽 {slot} 已存在，忽略")
+        return
+
+    try:
+        uri = f"ws://127.0.0.1:{self._kernel_port}/ws"
+        ws = await websockets.connect(uri, max_size=16 * 1024 * 1024)
+
+        # 使用 slot token 认证
+        auth_msg = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "auth",
+            "params": {"token": slot_token},
+        }
+        await ws.send(json.dumps(auth_msg))
+
+        resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if resp.get("error") or not resp.get("result", {}).get("ok"):
+            print(f"[SLOT] 槽 {slot} 认证失败")
+            await ws.close()
+            return
+
+        self._extra_ws[slot] = ws
+        # 启动接收循环
+        task = asyncio.create_task(self._slot_recv_loop(ws, slot))
+        self._extra_ws_tasks[slot] = task
+        print(f"[SLOT] 槽 {slot} 已连接")
+
+    except Exception as e:
+        print(f"[SLOT] 槽 {slot} 连接失败: {e}")
+```
+
+### 槽接收循环
+
+```python
+async def _slot_recv_loop(self, ws, slot: int):
+    """附加连接的消息接收循环，逻辑与主连接相同。"""
+    try:
+        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:
+                asyncio.create_task(self._handle_rpc_request(ws, msg))
+            elif has_method and not has_id:
+                asyncio.create_task(self._handle_event_notification(msg))
+            elif has_id and (has_result or has_error):
+                self._handle_rpc_response(msg)
+    except websockets.ConnectionClosedError:
+        print(f"[SLOT] 槽 {slot} 断开")
+    finally:
+        self._extra_ws.pop(slot, None)
+        self._extra_ws_tasks.pop(slot, None)
+```
+
+### 处理 connection.release
+
+```python
+async def _handle_connection_release(self, data: dict):
+    """处理 Kernel 要求释放连接槽。"""
+    slot = data.get("slot")
+    ws = self._extra_ws.pop(slot, None)
+    if ws:
+        try:
+            await ws.close(code=1000, reason="slot released")
+        except Exception:
+            pass
+    task = self._extra_ws_tasks.pop(slot, None)
+    if task:
+        task.cancel()
+    print(f"[SLOT] 槽 {slot} 已释放")
+```
+
+## 关键注意事项
+
+1. **Slot token 有效期 30 秒** — 收到 offer 后必须尽快连接
+2. **附加连接不需要 subscribe 和 register** — 只有主连接做初始化
+3. **附加连接共享 pending_rpc** — 所有连接的 RPC 响应都通过同一个 `_pending_rpc` dict 匹配
+4. **附加连接断开不触发 debounce** — 只有主连接（Slot 0）断开才会触发 5 秒去抖
+5. **关闭时先关附加连接** — 在 shutdown 序列中，先关 extra_ws，再关主连接
+6. **Kernel 会自动恢复** — 非弹性模式下，如果附加连接断开，Kernel 会重新发 offer

package/.claude/skills/kite/references/rpc-patterns.md

@@ -0,0 +1,199 @@
+# RPC 调用/响应标准模式
+
+## JSON-RPC 2.0 消息格式
+
+### 请求
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid-string",
+  "method": "module_name.method_name",
+  "params": {}
+}
+```
+
+### 成功响应
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid-string",
+  "result": {}
+}
+```
+
+### 错误响应
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid-string",
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+## 标准 _rpc_call 实现（Python）
+
+```python
+async def _rpc_call(self, ws, method: str, params: dict = None,
+                    wait_response: bool = True, timeout: float = 3.0):
+    req_id = str(uuid.uuid4())
+    msg = {
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "method": method,
+        "params": params or {},
+    }
+    await ws.send(json.dumps(msg))
+
+    if not wait_response:
+        return None
+
+    future = asyncio.get_event_loop().create_future()
+    self._pending_rpc[req_id] = future
+
+    try:
+        result = await asyncio.wait_for(future, timeout=timeout)
+        return result
+    except asyncio.TimeoutError:
+        self._pending_rpc.pop(req_id, None)
+        print(f"[RPC] 超时: {method} (id={req_id[:8]})")
+        return {"error": {"code": -32002, "message": f"Timeout: {method}"}}
+```
+
+## 标准 _handle_rpc_response 实现
+
+```python
+def _handle_rpc_response(self, msg: dict):
+    req_id = msg.get("id")
+    future = self._pending_rpc.pop(req_id, None)
+    if future and not future.done():
+        if "error" in msg:
+            future.set_result(msg)  # 返回完整消息，让调用方处理
+        else:
+            future.set_result(msg.get("result", {}))
+```
+
+**注意：error 响应也用 `set_result` 而非 `set_exception`**，这样调用方可以统一通过返回值判断。
+
+## 标准 _handle_rpc_request 实现
+
+```python
+async def _handle_rpc_request(self, ws, msg: dict):
+    method = msg.get("method", "")
+    params = msg.get("params", {})
+    req_id = msg.get("id")
+
+    # 去掉模块前缀：my_module.health → health
+    bare = method.split(".")[-1] if "." in method else method
+
+    # 方法分发表
+    handlers = {
+        "health": self._rpc_health,
+        "status": self._rpc_status,
+        # 更多方法...
+    }
+
+    handler = handlers.get(bare)
+    if not handler:
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {"code": -32601, "message": f"Method not found: {method}"},
+        }))
+        return
+
+    try:
+        result = await handler(params)
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "result": result,
+        }))
+    except Exception as e:
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {"code": -32603, "message": str(e)},
+        }))
+```
+
+## 标准 RPC 方法
+
+每个模块**必须**实现以下 RPC 方法：
+
+### health
+
+```python
+async def _rpc_health(self, params: dict) -> dict:
+    return {
+        "status": "ok",
+        "uptime": time.time() - self._start_time,
+        "module": self._module_name,
+    }
+```
+
+### status
+
+```python
+async def _rpc_status(self, params: dict) -> dict:
+    return {
+        "module": self._module_name,
+        "state": "running",
+        "connections": 1 + len(self._extra_ws),
+        "pending_rpc": len(self._pending_rpc),
+    }
+```
+
+## 跨模块 RPC 调用
+
+模块 A 调用模块 B 的方法，通过 Kernel 转发：
+
+```python
+# 在模块 A 中调用模块 B 的 health 方法
+result = await self._rpc_call(ws, "module_b.health", {})
+```
+
+Kernel 会：
+1. 解析方法名前缀 `module_b`
+2. 在注册中心查找 module_b 的连接
+3. 转发请求到 module_b
+4. 将响应回传给模块 A
+
+## Kernel 内建 RPC 方法
+
+| 方法 | 说明 |
+|------|------|
+| `registry.register` | 注册模块信息 |
+| `registry.lookup` | 查询注册中心 |
+| `registry.get` | 获取模块详细信息 |
+| `event.subscribe` | 订阅事件 |
+| `event.unsubscribe` | 取消订阅 |
+| `event.publish` | 发布事件 |
+| `kernel.health` | Kernel 健康状态 |
+| `kernel.stats` | Kernel 统计信息 |
+| `kernel.latencies` | 模块延迟信息 |
+
+## 错误码
+
+| 码 | 含义 |
+|----|------|
+| -32600 | 无效请求 |
+| -32601 | 方法不存在 |
+| -32602 | 无效参数 |
+| -32603 | 内部错误 |
+| -32001 | 目标模块离线 |
+| -32002 | RPC 超时 |
+| -32006 | 目标模块降级，该方法不可用 |
+
+## 常见坑
+
+1. **忘记 pop pending_rpc** — 超时后必须 pop，否则内存泄漏
+2. **fire-and-forget 用 wait_response=False** — event.publish 等不需要等响应的调用，设 `wait_response=False` 避免积压 pending_rpc
+3. **方法名前缀** — 入站请求的 method 可能带模块前缀（如 `my_module.health`），handler 分发时要去掉前缀
+4. **响应必须发回** — 收到带 `id` 的请求必须回复，否则调用方会超时
+5. **timeout 不要太长** — 默认 3 秒，跨模块调用链最多 5 秒，过长会阻塞调用方

package/.claude/skills/kite/references/shutdown-sequence.md

@@ -0,0 +1,146 @@
+# 优雅关闭完整序列
+
+## ⚠️ 前置条件：module.ready 必须声明支持优雅关闭
+
+**在模块初始化时，`module.ready` 事件必须包含 `graceful_shutdown: True`，否则 Launcher 会直接杀进程而不走优雅关闭流程！**
+
+```python
+await self._publish_event(ws, "module.ready", {
+    "module_id": self._module_name,
+    "graceful_shutdown": True,  # ← 必须！缺少会被直接杀进程
+    "startup_time": time.monotonic() - self._boot_t0,
+    "reason": "startup",
+})
+```
+
+**常见错误**：只发送 `{"module_id": "xxx"}`，导致 Launcher 认为模块不支持优雅关闭。
+
+---
+
+## 关闭流程时序图
+
+```
+Kernel 发布 module.shutdown 事件
+    ↓
+模块收到 module.shutdown
+    ↓
+Step 1: 发布 module.shutdown.ack（确认收到）
+    ↓
+Step 2: 发布 module.exiting（开始清理）
+    ↓
+Step 3: 执行清理操作（关闭资源、保存状态等）
+    ↓
+Step 4: 发布 module.shutdown.ready（清理完成，可以关闭）
+    ↓
+Step 5: 等待 10ms（让 Kernel 处理 shutdown.ready）
+    ↓
+Step 6: 关闭附加连接（extra_ws）
+    ↓
+Step 7: 关闭主 WebSocket 连接
+    ↓
+Step 8: 进程退出
+```
+
+## 标准实现
+
+```python
+async def _handle_shutdown(self, ws):
+    """处理 module.shutdown 事件。"""
+    print(f"[{self._module_name}] 收到 module.shutdown")
+    self._shutting_down = True
+
+    # Step 1: 确认收到
+    await self._publish_event(ws, "module.shutdown.ack", {
+        "module_id": self._module_name,
+        "estimated_cleanup": 2,  # 预估清理时间（秒）
+    })
+
+    # Step 2: 通告开始退出
+    await self._publish_event(ws, "module.exiting", {
+        "module_id": self._module_name,
+        "action": "none",  # 或 "save_state" 等
+    })
+
+    # Step 3: 执行清理（模块自定义）
+    await self._cleanup()
+
+    # Step 4: 通告可以关闭
+    await self._publish_event(ws, "module.shutdown.ready", {
+        "module_id": self._module_name,
+    })
+
+    # Step 5: 给 Kernel 一点时间处理
+    await asyncio.sleep(0.01)
+
+    # Step 6: 关闭附加连接
+    for slot, extra_ws in list(self._extra_ws.items()):
+        try:
+            await extra_ws.close(code=1000, reason="shutdown")
+        except Exception:
+            pass
+    self._extra_ws.clear()
+
+    # Step 7: 关闭主连接
+    try:
+        await ws.close(code=1000, reason="Graceful shutdown")
+    except Exception as e:
+        print(f"[{self._module_name}] WebSocket 关闭失败: {e}")
+```
+
+## 关键注意事项
+
+### 1. _shutting_down 标志
+
+在收到 shutdown 的第一时间设置 `self._shutting_down = True`。
+
+其他代码中需要检查此标志：
+```python
+# 测试事件循环中
+async def _test_event_loop(self):
+    while not self._shutting_down:
+        await asyncio.sleep(12)
+        if self._shutting_down:
+            break
+        # ...
+
+# RPC handler 中（可选，防止关闭过程中还在处理请求）
+async def _handle_rpc_request(self, ws, msg):
+    if self._shutting_down:
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0",
+            "id": msg.get("id"),
+            "error": {"code": -32603, "message": "Module shutting down"},
+        }))
+        return
+```
+
+### 2. shutdown.ready 之后不要再发消息
+
+`shutdown.ready` 发布后，Kernel 认为模块已经完成清理。此后不要再发送任何 RPC 或事件。
+
+### 3. sleep(0.01) 可能不够
+
+当前实现用 10ms 等待 Kernel 处理 shutdown.ready。在高负载下可能不够。但目前所有现有模块都用这个值，保持一致即可。
+
+### 4. HTTP 服务的额外关闭
+
+如果模块有 HTTP 服务（uvicorn），需要在 FastAPI 的 shutdown 事件中清理：
+
+```python
+@app.on_event("shutdown")
+async def _shutdown():
+    if server._ws_task:
+        server._ws_task.cancel()
+    if server._test_task:
+        server._test_task.cancel()
+    if server._ws:
+        await server._ws.close()
+    print(f"[{server._module_name}] HTTP 服务关闭完成")
+```
+
+### 5. 不实现优雅关闭的后果
+
+- Kernel 会等待 shutdown 超时后强制标记模块为 offline
+- 可能导致未保存的数据丢失
+- 其他模块对该模块的 RPC 调用会超时
+- Watchdog 可能报告异常退出

package/.claude/skills/kite/references/stdin-protocol.md

@@ -0,0 +1,147 @@
+# stdin boot_info 协议
+
+## 概述
+
+Kite 模块通过 stdin 接收启动信息（boot_info），这是 Launcher → 模块的唯一初始化通道。
+
+## 协议流程
+
+### 本地模式（KITE_KERNEL_PORT 已设置）
+
+```
+Launcher 启动模块进程
+    ↓
+设置环境变量：
+  KITE_KERNEL_PORT=端口号
+  KITE_MODULE_DATA=模块数据目录
+  KITE_INSTANCE_DIR=实例目录
+  KITE_INSTANCE_NUM=实例编号（多实例时）
+    ↓
+通过 stdin 发送一行 JSON：
+  {"token": "模块认证令牌", "max_instances": 3}
+    ↓
+模块读取并解析
+```
+
+### 远程模式（KITE_GATEWAY_URL 已设置）
+
+```
+模块自行启动
+    ↓
+读取环境变量 KITE_GATEWAY_URL 或 module.md 中的 gateway_url
+    ↓
+读取 token：优先 KITE_TOKEN 环境变量 → 缓存文件 → 报错退出
+    ↓
+连接 Gateway WebSocket
+```
+
+## boot_info 消息格式
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIs...",
+  "max_instances": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `token` | string | Kernel 分配的认证令牌 |
+| `max_instances` | int | 允许的最大实例数 |
+
+### 错误消息
+
+如果 Launcher 无法启动模块，会发送错误消息：
+
+```json
+{
+  "error": "错误描述"
+}
+```
+
+模块收到后应打印错误并 `sys.exit(1)`。
+
+## 标准读取代码（Python）
+
+```python
+import sys
+import json
+
+line = sys.stdin.readline().strip()
+if not line:
+    print("[FATAL] stdin 为空，无法获取 boot_info")
+    sys.exit(1)
+
+try:
+    msg = json.loads(line)
+except json.JSONDecodeError as e:
+    print(f"[FATAL] boot_info JSON 解析失败: {e}")
+    sys.exit(1)
+
+if "error" in msg:
+    print(f"[FATAL] Launcher 报错: {msg['error']}")
+    sys.exit(1)
+
+token = msg.get("token", "")
+if not token:
+    print("[FATAL] boot_info 中缺少 token")
+    sys.exit(1)
+
+max_instances = msg.get("max_instances", 1)
+```
+
+## 标准读取代码（Node.js）
+
+```javascript
+const readline = require('readline');
+
+async function readBootInfo() {
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({ input: process.stdin });
+    const timer = setTimeout(() => {
+      rl.close();
+      reject(new Error('boot_info 读取超时'));
+    }, 10000);
+
+    rl.once('line', (line) => {
+      clearTimeout(timer);
+      rl.close();
+      try {
+        const msg = JSON.parse(line.trim());
+        if (msg.error) {
+          reject(new Error(`Launcher 报错: ${msg.error}`));
+          return;
+        }
+        if (!msg.token) {
+          reject(new Error('boot_info 中缺少 token'));
+          return;
+        }
+        resolve(msg);
+      } catch (e) {
+        reject(new Error(`boot_info JSON 解析失败: ${e.message}`));
+      }
+    });
+  });
+}
+```
+
+## 环境变量
+
+模块启动时可用的环境变量：
+
+| 变量 | 说明 | 本地模式 | 远程模式 |
+|------|------|----------|----------|
+| `KITE_KERNEL_PORT` | Kernel WebSocket 端口 | ✅ | ❌ |
+| `KITE_MODULE_DATA` | 模块数据目录 | ✅ | ❌ |
+| `KITE_INSTANCE_DIR` | 实例根目录 | ✅ | ❌ |
+| `KITE_INSTANCE_NUM` | 实例编号 | ✅ 多实例时 | ❌ |
+| `KITE_GATEWAY_URL` | Gateway 地址 | ❌ | ✅ |
+| `KITE_TOKEN` | 认证令牌 | ❌ | ✅ 可选 |
+
+## 关键注意事项
+
+1. **只读一行** — boot_info 是 stdin 的第一行 JSON，读完后 stdin 不再使用
+2. **Kernel 特殊** — Kernel 读取两条 stdin 消息：`{token}` 和 `{kite: "tokens", tokens: {...}}`
+3. **超时处理** — 建议设置 10 秒超时，防止 stdin 永久阻塞
+4. **编码** — JSON 使用 UTF-8 编码
+5. **不要在 stdin 读取前有 stdout 输出** — 某些模块（如 Kernel）在读取 stdin 前先通过 stdout 输出端口信息，这是特殊情况