@agentunion/kite 1.5.0 → 1.6.1

package/docs//346/250/241/345/235/227/347/203/255/346/233/264/346/226/260.md

@@ -0,0 +1,89 @@
+# 模块热更新
+
+## 1. 概述
+
+热更新通过一个独立的扩展模块（Hot Updater）实现，不修改 Launcher 核心代码。Hot Updater 通过组合现有的 Launcher API 和事件机制完成模块的不停机更新。
+
+本文档定义热更新流程、事件和接口。Hot Updater 模块本身暂不实现。
+
+## 2. 更新流程
+
+```
+Hot Updater 收到更新指令（API 或事件触发）：
+  │
+  ├─ Step 1: 下载新版本模块包到临时路径
+  │
+  ├─ Step 2: 校验包完整性（hash / 签名）
+  │
+  ├─ Step 3: 调 Launcher API 停止目标模块
+  │    POST /launcher/modules/{name}/stop
+  │    body: { "reason": "hot_update" }
+  │    → Launcher 发 module.shutdown 事件（reason: hot_update）
+  │    → 模块收到后发 module.updating 事件，然后退出
+  │
+  ├─ Step 4: 等待 module.stopped 事件确认模块已退出
+  │
+  ├─ Step 5: 备份旧版本，覆盖模块文件
+  │
+  ├─ Step 6: 调 Launcher API 启动模块
+  │    POST /launcher/modules/{name}/start
+  │
+  ├─ Step 7: 等待 module.ready 事件确认新版本就绪
+  │    ├─ 成功 → 发 module.updated 事件，清理临时文件
+  │    └─ 失败 → 回滚（恢复备份），重新启动旧版本
+  │
+  └─ 完成
+```
+
+## 3. 事件定义
+
+| 事件 | 方向 | 说明 |
+|------|------|------|
+| `module.updating` | 模块 → 广播 | 模块即将热更新（模块收到 shutdown reason=hot_update 后发出） |
+| `module.updated` | Hot Updater → 广播 | 模块热更新完成 |
+| `module.update_failed` | Hot Updater → 广播 | 热更新失败，已回滚 |
+
+### module.updating payload
+
+```json
+{
+  "event": "module.updating",
+  "source": "webchat",
+  "data": { "module_id": "webchat" }
+}
+```
+
+### module.updated payload
+
+```json
+{
+  "event": "module.updated",
+  "source": "hot_updater",
+  "data": {
+    "module_id": "webchat",
+    "old_version": "1.0",
+    "new_version": "1.1"
+  }
+}
+```
+
+## 4. 框架配套要求
+
+热更新模块依赖以下已有或待实现的框架能力：
+
+| 能力 | 状态 | 说明 |
+|------|------|------|
+| `POST .../stop` 支持 reason | 待实现 | stop 接口增加 reason 参数 |
+| `module.shutdown` 事件含 reason | 待实现 | 优雅退出规范 |
+| `module.ready` 事件 | 待实现 | 启动依赖规范 |
+| `module.stopped` 事件 | 已实现 | Launcher 已发布 |
+| Launcher start/stop API | 已实现 | 现有接口 |
+
+## 5. 模块侧规范
+
+模块收到 `module.shutdown`（reason=hot_update）时：
+
+1. 回复 `module.shutdown.ack`（同优雅退出规范）
+2. 发布 `module.updating` 事件
+3. 完成清理，发 `module.shutdown.ready`
+4. 退出

package/docs//346/250/241/345/235/227/350/277/234/347/250/213/351/203/250/347/275/262/345/274/200/345/217/221/350/247/204/350/214/203.md

@@ -0,0 +1,460 @@
+# 模块远程部署开发规范
+
+## 概述
+
+**远程部署**是指将 Kite 模块部署到远程服务器或设备上，通过 Gateway 接入 Kernel，而不是由本地 Launcher 启动。
+
+### 适用场景
+
+- 模块需要部署在特定的硬件设备上（如边缘计算节点）
+- 模块需要访问远程网络资源（如内网数据库）
+- 模块需要独立运维（独立于 Kite 主实例的启停）
+- 分布式部署（多个节点运行同一套 Kite 系统）
+
+### 核心特征
+
+远程部署的模块与本地模块在**功能层面完全等价**：
+- ✅ 可以注册能力（RPC、API、Hook）
+- ✅ 可以订阅和发布事件
+- ✅ 可以调用其他模块的 RPC
+- ✅ 可以建立多连接（收到 offer）
+
+但在**运维层面有差异**：
+- ⚠️ 用户手动启动（不是 Launcher 启动）
+- ⚠️ 通过 Gateway 中继（双跳通信）
+- ⚠️ 无进程控制权（Launcher 无法 kill）
+- ⚠️ 需要自行处理 shutdown 信号
+
+---
+
+## 一、配置要求
+
+### 1.1 module.md 新增字段
+
+在模块的 `module.md` frontmatter 中添加 `gateway_url` 字段：
+
+```yaml
+---
+name: watchdog
+version: 1.0.0
+max_connections: 3
+
+# 远程部署配置（可选）
+gateway_url: wss://my-kite.example.com/ws
+---
+```
+
+**说明**：
+- `gateway_url` 存在 → 启用远程模式
+- `gateway_url` 不存在 → 本地模式（向后兼容）
+- 可以在部署时通过环境变量覆盖：`KITE_GATEWAY_URL`
+
+### 1.2 Token 缓存目录
+
+远程模块的 token 缓存在用户主目录：
+
+```
+~/.kite/remote/{module_name}/
+├── tokens/
+│   ├── my-kite.com-443.json    # wss://my-kite.com/ws 的 token
+│   └── localhost-8000.json     # ws://localhost:8000/ws 的 token
+└── log/                         # 可选：模块日志
+```
+
+**Token 文件格式**：
+
+```json
+{
+  "token": "kite_abc123...",
+  "gateway_url": "wss://my-kite.com/ws",
+  "created_at": 1710734933.0
+}
+```
+
+---
+
+## 二、代码适配清单
+
+### 2.1 启动模式判断（必须）
+
+模块启动时需要判断是本地模式还是远程模式：
+
+```python
+def main():
+    # 优先级 1：检查环境变量（本地模式）
+    kernel_port = os.environ.get("KITE_KERNEL_PORT")
+    if kernel_port:
+        return _run_local_mode(kernel_port)
+
+    # 优先级 2：检查 module.md 的 gateway_url（远程模式）
+    config = _load_module_config()
+    gateway_url = config.get("gateway_url") or os.environ.get("KITE_GATEWAY_URL")
+
+    if gateway_url:
+        return _run_remote_mode(gateway_url)
+
+    # 都没有 → 报错
+    print(f"[{MODULE_NAME}] ERROR: No KITE_KERNEL_PORT and no gateway_url")
+    sys.exit(1)
+```
+
+**关键点**：
+- `KITE_KERNEL_PORT` 优先级最高（被 Launcher 启动时必须响应）
+- `gateway_url` 次之（远程部署配置）
+- 环境变量可以覆盖 module.md 的配置
+
+### 2.2 本地模式（无需改动）
+
+本地模式保持现有逻辑：
+
+```python
+def _run_local_mode(kernel_port: str):
+    # 1. 从 stdin 读取 boot_info
+    boot_info = json.loads(sys.stdin.readline())
+    token = boot_info["token"]
+
+    # 2. 连接 Kernel
+    kernel_url = f"ws://127.0.0.1:{kernel_port}/ws?id={MODULE_NAME}"
+
+    # 3. 认证、注册、运行
+    asyncio.run(_connect_and_run(kernel_url, token))
+```
+
+### 2.3 远程模式（新增）
+
+远程模式需要实现以下流程：
+
+**步骤 1：获取 kite_token**
+
+```python
+def _get_kite_token(module_name: str, gateway_url: str) -> str:
+    # 1. 环境变量优先
+    token = os.environ.get("KITE_TOKEN")
+    if token:
+        return token
+
+    # 2. 从缓存加载
+    cache = _load_token_cache(module_name, gateway_url)
+    if cache:
+        return cache["token"]
+
+    # 3. 提示首次配对
+    print(f"No token found. Please authenticate:")
+    print(f"  kite-cli auth --module {module_name} --gateway {gateway_url}")
+    sys.exit(1)
+```
+
+**步骤 2：连接 Gateway**
+
+```python
+async def _connect_remote(gateway_url: str, kite_token: str, module_id: str):
+    async with websockets.connect(gateway_url, open_timeout=10) as ws:
+        # 1. 接收 challenge
+        challenge = json.loads(await ws.recv())
+        nonce = challenge["params"]["nonce"]
+
+        # 2. 发送 auth.connect
+        auth_req = {
+            "jsonrpc": "2.0",
+            "id": "auth",
+            "method": "auth.connect",
+            "params": {
+                "nonce": nonce,
+                "module_id": module_id,
+                "auth": {"method": "kite_token", "token": kite_token},
+                "client": {"type": "module"}
+            }
+        }
+        await ws.send(json.dumps(auth_req))
+
+        # 3. 等待 hello-ok
+        hello_resp = json.loads(await ws.recv())
+        if "error" in hello_resp:
+            error = hello_resp["error"]
+            # 认证失败 → 清除缓存
+            if error.get("code") in (4001, 4010, 4011):
+                _clear_token_cache(module_id, gateway_url)
+                print(f"Token invalid, please re-authenticate")
+                sys.exit(1)
+            raise Exception(f"Connection failed: {error}")
+
+        # 4. 进入正常模块流程
+        await _module_lifecycle(ws)
+```
+
+**步骤 3：模块生命周期**
+
+```python
+async def _module_lifecycle(ws):
+    # 1. 订阅事件
+    await _rpc_call(ws, "event.subscribe", {
+        "events": ["system.ready", "module.shutdown", "system.connection.offer"]
+    })
+
+    # 2. 注册模块
+    await _rpc_call(ws, "registry.register", {
+        "module_id": MODULE_NAME,
+        "version": "1.0.0",
+        "max_connections": 3,
+        "tools": {...},
+        "events_subscribe": [...],
+        "events_publish": {...}
+    })
+
+    # 3. 发布 module.ready
+    await _rpc_call(ws, "event.publish", {
+        "event": "module.ready",
+        "data": {"module_id": MODULE_NAME}
+    })
+
+    # 4. 进入消息循环
+    await _message_loop(ws)
+```
+
+---
+
+## 三、生命周期适配
+
+### 3.1 优雅关闭（必须）
+
+远程模块收到 `module.shutdown` 事件后，必须**自行退出进程**：
+
+```python
+async def _handle_shutdown(ws, data: dict):
+    module_id = data.get("module_id")
+    if module_id != MODULE_NAME:
+        return
+
+    # 1. 发送 shutdown.ack
+    await _rpc_call(ws, "event.publish", {
+        "event": "module.shutdown.ack",
+        "data": {"module_id": MODULE_NAME}
+    })
+
+    # 2. 清理资源
+    cleanup_timeout = await _cleanup_resources()
+
+    # 3. 发送 module.exiting
+    await _rpc_call(ws, "event.publish", {
+        "event": "module.exiting",
+        "data": {
+            "module_id": MODULE_NAME,
+            "cleanup_timeout": cleanup_timeout,
+            "action": "none"
+        }
+    })
+
+    # 4. 发送 module.shutdown.ready
+    await _rpc_call(ws, "event.publish", {
+        "event": "module.shutdown.ready",
+        "data": {"module_id": MODULE_NAME}
+    })
+
+    # 5. 关闭连接
+    await ws.close()
+
+    # 6. 退出进程（关键！）
+    sys.exit(0)
+```
+
+**关键点**：
+- 本地模块：Launcher 会 kill 进程
+- 远程模块：必须自己调用 `sys.exit(0)`
+
+### 3.2 崩溃自报（可选）
+
+远程模块崩溃时，Kernel 会通过 WebSocket 断开检测到 `module.offline`，但无法发送 `module.stopped` 事件（因为没有进程句柄）。
+
+如果需要精确的崩溃报告，模块可以在退出前自行发送：
+
+```python
+def _setup_exit_handler():
+    def _on_exit():
+        # 发送 module.stopped 事件
+        asyncio.run(_send_stopped_event("crash"))
+
+    atexit.register(_on_exit)
+```
+
+---
+
+## 四、多连接支持
+
+### 4.1 接收 Offer
+
+远程模块注册时声明 `max_connections`，Kernel 会发送 `system.connection.offer` 事件：
+
+```python
+async def _handle_connection_offer(ws, data: dict):
+    slots = data.get("slots", {})
+
+    for slot_id, slot_info in slots.items():
+        slot_token = slot_info["token"]
+        expires_in = slot_info["expires_in"]
+
+        # 建立附加连接
+        asyncio.create_task(_connect_slot(slot_id, slot_token))
+```
+
+### 4.2 建立附加连接
+
+附加连接仍然通过 Gateway：
+
+```python
+async def _connect_slot(slot_id: str, slot_token: str):
+    gateway_url = _get_gateway_url()  # 与主连接相同
+
+    async with websockets.connect(gateway_url) as ws:
+        # 1. 接收 challenge
+        challenge = json.loads(await ws.recv())
+        nonce = challenge["params"]["nonce"]
+
+        # 2. 发送 auth.connect_slot
+        auth_req = {
+            "jsonrpc": "2.0",
+            "id": "auth",
+            "method": "auth.connect_slot",
+            "params": {
+                "nonce": nonce,
+                "slot_token": slot_token,
+                "module_id": MODULE_NAME
+            }
+        }
+        await ws.send(json.dumps(auth_req))
+
+        # 3. 等待响应
+        hello_resp = json.loads(await ws.recv())
+        if "error" in hello_resp:
+            print(f"Slot {slot_id} connection failed: {hello_resp['error']}")
+            return
+
+        # 4. 进入消息循环
+        await _message_loop(ws, slot_id=slot_id)
+```
+
+---
+
+## 五、首次配对
+
+### 5.1 配对工具
+
+用户首次部署远程模块时，需要使用 `kite-cli` 工具进行配对：
+
+```bash
+# 方式 1：配对码
+$ kite-cli auth --module watchdog --gateway wss://my-kite.com/ws
+Enter pairing code: 123456
+✓ Authenticated successfully
+Token saved to ~/.kite/remote/watchdog/tokens/my-kite.com-443.json
+
+# 方式 2：环境变量（临时）
+$ export KITE_TOKEN=kite_abc123...
+$ python watchdog/entry.py
+```
+
+### 5.2 配对流程
+
+配对工具的实现逻辑：
+
+1. 连接 Gateway
+2. 接收 challenge（nonce）
+3. 用配对码/账号进行认证
+4. 获得 kite_token
+5. 保存到 `~/.kite/remote/{module}/tokens/{gateway}.json`
+
+### 5.3 Token 永久有效
+
+配对一次后，token 永久有效（除非被撤销）。模块后续启动时自动使用缓存的 token。
+
+如果认证失败（401），模块会清除缓存并提示重新配对。
+
+---
+
+## 六、测试验证
+
+### 6.1 本地测试
+
+在本地 Kite 实例中测试模块的远程模式：
+
+```bash
+# 1. 启动本地 Kite（包含 Gateway）
+$ python main.py
+
+# 2. 在另一个终端，配对模块
+$ kite-cli auth --module my-module --gateway ws://localhost:8001/ws
+Enter pairing code: (从控制台获取)
+
+# 3. 启动远程模块
+$ cd extensions/services/my-module
+$ python entry.py
+[my-module] Connected via Gateway ws://localhost:8001/ws
+[my-module] Registered successfully
+```
+
+### 6.2 验证清单
+
+- [ ] 模块能通过 Gateway 连接到 Kernel
+- [ ] 模块能注册能力（`registry.register`）
+- [ ] 模块能发布 `module.ready` 事件
+- [ ] 其他模块能调用该模块的 RPC
+- [ ] 模块能订阅和接收事件
+- [ ] 模块能响应 `module.shutdown` 并自行退出
+- [ ] 模块能接收 `system.connection.offer` 并建立多连接
+- [ ] Token 缓存和重用正常工作
+- [ ] 认证失败时能清除缓存并提示重新配对
+
+---
+
+## 七、注意事项
+
+### 7.1 模块名冲突
+
+如果本地已有同名模块在运行，远程模块会接入失败（module_id 冲突）。
+
+**解决方案**：
+- 确保同一时间只有一个实例在线
+- 或使用不同的 module_id（在 module.md 中配置）
+
+### 7.2 延迟增加
+
+远程模块的所有消息都经过 Gateway 中继，延迟比本地模块高（双跳 vs 单跳）。
+
+**适用场景**：
+- 对延迟不敏感的模块（如定时任务、数据同步）
+- 必须部署在远程的模块（如硬件控制、内网访问）
+
+### 7.3 Gateway 可用性
+
+Gateway 是单点故障。如果 Gateway 不可用，远程模块无法连接。
+
+**缓解措施**：
+- 配置多个 Gateway（主备）
+- 模块支持重连和故障转移
+
+### 7.4 日志收集
+
+远程模块的 stdout 无人接收，日志不会被 Launcher 收集。
+
+**解决方案**：
+- 模块自行管理日志文件（写入 `~/.kite/remote/{module}/log/`）
+- 或通过 logs 模块的 RPC 上报日志
+
+---
+
+## 八、参考实现
+
+完整的远程部署适配示例，请参考：
+
+- `extensions/services/watchdog/entry.py` - 双模式启动判断
+- `extensions/services/gateway/ws_server.py` - Gateway 握手协议
+- `extensions/services/auth/entry.py` - Token 验证机制
+
+---
+
+## 附录：环境变量
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| `KITE_KERNEL_PORT` | Kernel 端口（本地模式） | `8000` |
+| `KITE_GATEWAY_URL` | Gateway 地址（远程模式） | `wss://my-kite.com/ws` |
+| `KITE_TOKEN` | kite_token（临时覆盖缓存） | `kite_abc123...` |