@agentunion/kite 1.4.0 → 1.6.0

package/docs//350/277/234/347/250/213/346/250/241/345/235/227/350/256/276/350/256/241.md

@@ -0,0 +1,451 @@
+# 远程模块（Remote Module）设计
+
+## 1. 概述
+
+远程模块功能允许一个 Kite 实例（**卫星 Kite**）通过网络接入另一个 Kite 实例（**中心 Kite**），双方的模块可以互相发现、互相调用工具、互相收发事件，如同在同一台机器上运行。
+
+**核心场景：** 用户在本地运行中心 Kite，在其他机器或其他目录运行卫星 Kite。在中心 Web 管理后台生成配对串，粘贴到卫星 Web 管理后台，即完成接入。
+
+**卫星无需公网 IP。** 卫星主动向中心发起 WebSocket 出站连接，连接建立后双向通信。只要中心 Kite 的 Bridge Server 端口对卫星可达即可（公网、LAN、内网穿透均可）。支持跨域、跨 NAT。
+
+## 2. 架构变化
+
+### 2.1 改造前架构
+
+旧架构有独立的 Registry 和 Event Hub 模块，模块间通过 HTTP REST 通信。
+
+### 2.2 改造后架构（当前）
+
+Registry 和 Event Hub 已合并为 Kernel 模块，所有内部通信改为 WebSocket JSON-RPC 2.0。
+
+**当前单机架构：**
+
+```
+Launcher → Kernel (127.0.0.1, WS RPC)
+  ├─ 模块 A → Kernel (WS RPC)
+  ├─ 模块 B → Kernel (WS RPC)
+  └─ Web → Kernel (WS RPC)
+```
+
+**远程模块架构：**
+
+```
+中心 Kite:
+  Launcher → Kernel
+  ├─ 本地模块 → Kernel (WS RPC)
+  ├─ Web → Kernel (WS RPC)
+  └─ Bridge Server → Kernel (WS RPC)
+
+卫星 Kite:
+  Launcher → Kernel
+  ├─ 远程模块 → Kernel (WS RPC)
+  ├─ Web → Kernel (WS RPC)
+  └─ Bridge Client → Kernel (WS RPC)
+
+Bridge Server ←→ Bridge Client (WSS 隧道)
+```
+
+### 2.3 核心变化
+
+| 方面 | 旧架构 | 新架构 |
+|------|--------|--------|
+| 核心服务 | Registry + Event Hub | Kernel（合并） |
+| 内部通信 | HTTP REST | WebSocket JSON-RPC 2.0 |
+| 模块注册 | HTTP POST /modules | RPC registry.register |
+| 事件订阅 | WebSocket 自定义协议 | RPC event.subscribe |
+| 工具调用 | HTTP POST /tools/{name} | RPC {module}.{tool} |
+| 模块管理 | HTTP POST /launcher/modules/{name}/start | RPC launcher.start_module |
+
+## 3. Bridge Server（中心侧）
+
+### 3.1 职责
+
+1. 接受卫星 WSS 连接（固定端口 28766）
+2. 认证配对码和 session_token
+3. 代理卫星模块注册到中心 Kernel（RPC registry.register）
+4. 代理中心模块注册到卫星 Kernel（通过隧道）
+5. 双向转发事件（RPC event.publish）
+6. 代理工具调用（RPC 转发）
+7. 远程管理卫星模块（RPC launcher.*）
+
+### 3.2 与 Kernel 的交互
+
+Bridge Server 作为普通模块连接 Kernel WS：
+
+```
+Bridge Server 启动
+  ↓
+连接 Kernel WS (127.0.0.1:动态端口)
+  ↓
+RPC registry.register (注册自身)
+  ↓
+RPC event.subscribe (订阅 module.*)
+  ↓
+监听卫星连接 (0.0.0.0:28766)
+```
+
+**代理卫星模块注册：**
+```
+收到卫星 registry.register
+  ↓
+改写 module_id: "assistant" → "office@assistant"
+  ↓
+RPC registry.register 到中心 Kernel
+```
+
+**代理中心模块到卫星：**
+```
+监听 Kernel 事件: module.started
+  ↓
+RPC registry.lookup 获取模块信息
+  ↓
+通过隧道发送给 Bridge Client
+  ↓
+Bridge Client RPC registry.register 到卫星 Kernel
+```
+
+### 3.3 与 Web 模块的交互
+
+通过 Kernel RPC 通信：
+
+| RPC 方法 | 说明 |
+|----------|------|
+| bridge.generate_pairing | 生成配对码 |
+| bridge.list_satellites | 列出卫星 |
+| bridge.disconnect_satellite | 断开卫星 |
+| web.validate_session_token | 验证 token（Web 提供） |
+| web.report_bridge_stats | 上报统计（Web 接收） |
+
+## 4. Bridge Client（卫星侧）
+
+### 4.1 职责
+
+1. 连接中心 Bridge Server（WSS 出站）
+2. 同步本地模块到中心（上行）
+3. 同步中心模块到本地（下行）
+4. 双向转发事件
+5. 代理工具调用
+6. 接收远程管理指令
+
+### 4.2 与 Kernel 的交互
+
+```
+Bridge Client 启动
+  ↓
+连接本地 Kernel WS
+  ↓
+RPC registry.register (注册自身)
+  ↓
+RPC event.subscribe (订阅 module.*)
+  ↓
+连接中心 Bridge Server (WSS)
+  ↓
+双向同步开始
+```
+
+**上行同步（本地 → 中心）：**
+```
+RPC registry.lookup (获取本地模块列表)
+  ↓
+过滤（排除 kernel, launcher, bridge_*, watchdog, web）
+  ↓
+通过隧道发送给 Bridge Server
+  ↓
+Bridge Server 代理注册到中心 Kernel
+```
+
+**下行同步（中心 → 本地）：**
+```
+收到隧道消息: registry.register
+  ↓
+改写 module_id: "model_service" → "main@model_service"
+  ↓
+RPC registry.register 到本地 Kernel
+```
+
+## 5. 隧道协议
+
+单条 WebSocket 承载 5 种通道，消息格式：
+
+```json
+{
+  "id": "msg-uuid",
+  "ch": "registry | event | proxy | control | manage",
+  "action": "具体动作",
+  "data": {...}
+}
+```
+
+### 5.1 Registry 通道
+
+双向同步模块注册信息。
+
+**卫星 → 中心：**
+- `register` — 注册卫星模块
+- `heartbeat` — 心跳
+- `deregister` — 注销
+
+**中心 → 卫星：**
+- `register` — 注册中心模块
+- `heartbeat` — 心跳
+- `deregister` — 注销
+
+### 5.2 Event 通道
+
+双向转发 Kernel 事件。
+
+- `publish` — 转发事件
+- `subscribe` — 订阅同步
+- `unsubscribe` — 取消订阅
+
+### 5.3 Proxy 通道
+
+双向代理 RPC 调用。
+
+**请求：**
+```json
+{
+  "id": "msg-100",
+  "ch": "proxy",
+  "action": "request",
+  "data": {
+    "target_module": "assistant",
+    "method": "search_web",
+    "params": {"query": "kite"}
+  }
+}
+```
+
+**响应：**
+```json
+{
+  "id": "msg-100",
+  "ch": "proxy",
+  "action": "response",
+  "data": {"result": "..."}
+}
+```
+
+### 5.4 Control 通道
+
+- `ping` / `pong` — 心跳保活
+- `status` — 状态上报
+- `disconnect` — 主动断开
+
+### 5.5 Manage 通道
+
+中心远程管理卫星模块。
+
+- `module_start` — 启动模块
+- `module_stop` — 停止模块
+- `list_modules` — 列出模块
+- `module_set_state` — 修改状态
+
+## 6. 配对流程
+
+```
+用户在中心 Web UI 点击「生成配对码」
+  ↓
+Web → Bridge Server: RPC bridge.generate_pairing
+  ↓
+返回配对串: kite://192.168.1.1:28766/a3f8x9k2
+  ↓
+用户复制粘贴到卫星 Web UI
+  ↓
+卫星 Web → Bridge Client: 通过 Kernel 事件传递配对信息
+  ↓
+Bridge Client 连接中心 (WSS + 配对码)
+  ↓
+Bridge Server 验证 → 生成 session_token
+  ↓
+返回 bridge.welcome (含 session_token)
+  ↓
+Bridge Client 持久化 session_token
+  ↓
+后续自动重连使用 session_token
+```
+
+## 7. 命名空间
+
+### 7.1 FQMN 格式
+
+```
+{node_name}@{module_id}
+
+示例:
+  office@assistant      — 卫星 office 的 assistant 模块
+  main@kernel           — 中心的 kernel 模块
+  kernel                — 本地简写（等价于 main@kernel）
+```
+
+### 7.2 解析规则
+
+```python
+def parse_fqmn(name: str) -> tuple[str, str]:
+    if "@" in name:
+        return name.split("@", 1)
+    return ("main", name)
+```
+
+### 7.3 Kernel 路径
+
+```
+office@assistant.tools.search_web
+└─ node ─┘└ module ┘└ 字段路径 ─┘
+```
+
+## 8. 工具调用
+
+### 8.1 直连 vs 代理
+
+| 模式 | 说明 | 使用条件 |
+|------|------|---------|
+| 直连 | 调用方直接 RPC 对端模块 | 网络可达 |
+| 代理 | RPC 通过 Bridge 隧道转发 | 直连不通时降级 |
+
+### 8.2 探测机制
+
+隧道建立后，双方交换模块信息并探测可达性：
+
+```
+Bridge Server 收到卫星模块列表
+  ↓
+逐个探测: RPC {module_id}.health (超时 3s)
+  ↓
+成功 → 标记 direct
+失败 → 标记 proxy
+  ↓
+注册到 Kernel 时携带模式标记
+```
+
+### 8.3 调用流程
+
+**直连模式：**
+```
+中心 Agent → Kernel: RPC registry.lookup(tools.search_web)
+  ↓
+返回: module="office@assistant" (direct)
+  ↓
+Agent → 卫星模块: RPC assistant.search_web
+```
+
+**代理模式：**
+```
+中心 Agent → Kernel: RPC registry.lookup(tools.search_web)
+  ↓
+返回: module="office@assistant" (proxy)
+  ↓
+Agent → Bridge Server: RPC office@assistant.search_web
+  ↓
+Bridge Server → Bridge Client: 隧道 proxy.request
+  ↓
+Bridge Client → 卫星模块: RPC assistant.search_web
+  ↓
+原路返回
+```
+
+## 9. 断线与恢复
+
+### 9.1 断线处理
+
+**中心侧：**
+1. 从 Kernel 注销所有 `{node_name}@*` 模块（RPC registry.deregister）
+2. 清理事件订阅
+3. 保留 session_token
+4. 记录审计日志
+
+**卫星侧：**
+1. 从 Kernel 注销所有 `main@*` 模块
+2. 清理事件订阅
+3. 指数退避重连（1s → 2s → 4s → ... → 60s）
+4. 本地模块继续运行
+
+### 9.2 重连恢复
+
+```
+重连成功
+  ↓
+Bridge Server 发送 bridge.welcome (含中心模块列表)
+  ↓
+Bridge Client 全量同步本地模块
+  ↓
+Bridge Server 全量同步中心模块
+  ↓
+双方重新建立事件订阅
+  ↓
+Bridge Client 重放缓存事件
+```
+
+## 10. 改造清单
+
+### 10.1 Kernel 改动
+
+**文件：** `kernel/rpc_router.py`
+
+**改动：** 新增 `bridge` 角色，允许 Bridge Server 代理注册任意 module_id（约 15 行）
+
+### 10.2 新增模块
+
+**Bridge Server：** `extensions/services/bridge_server/`
+- `module.md` — 模块定义
+- `entry.py` — 启动入口
+- `bridge.py` — 隧道协议
+- `proxy.py` — RPC 代理
+- `probe.py` — 直连探测
+- `audit.py` — 审计日志
+
+**Bridge Client：** `extensions/services/bridge_client/`
+- `module.md` — 模块定义
+- `entry.py` — 启动入口
+- `bridge.py` — 隧道协议
+- `proxy.py` — RPC 代理
+- `probe.py` — 直连探测
+
+### 10.3 Web 模块改动
+
+**中心 Web UI：**
+- 配对码生成界面
+- 卫星列表管理
+- 统计仪表盘
+- 审计日志查看
+
+**卫星 Web UI：**
+- 配对串输入框
+- 连接状态显示
+
+## 11. 实现分阶段
+
+### Phase 1: 隧道 + 单向调用（MVP）
+
+- Kernel 新增 bridge 角色
+- Bridge Server/Client 骨架（WSS、SSL）
+- 隧道协议（registry + control 通道）
+- 配对流程
+- FQMN 命名
+- 单向同步（卫星 → 中心）
+- 工具调用（中心 → 卫星）
+- 事件环路防护
+- 启动时清理残留
+
+### Phase 2: 双向互通
+
+- 双向同步（中心 → 卫星）
+- 双向工具调用
+- 双向事件转发
+- 断线重连 + outbox
+- 周期探测
+- 默认优先级（本地优先）
+
+### Phase 3: 远程管理 + 统计
+
+- Manage 通道
+- 统计数据收集
+- 审计日志
+- Web UI 管理页面
+
+### Phase 4: 增强
+
+- 可配置优先级
+- 健康监控
+- 权限 ACL
+- 事件限流

package/docs//351/207/215/346/236/204/346/234/272/345/210/266/346/270/205/345/215/225.md

@@ -0,0 +1,192 @@
+# 重构机制清单
+
+> 对照 `stdio与端口发现重构.md`，列出代码需要实现的 14 个机制。
+
+---
+
+## 机制 1：启动序列重排
+
+Launcher 启动序列分为四个 Phase：
+
+- **Phase 1（引导）**：启动 Registry 子进程 → 通过 stdout 获取端口 → 写入 `KITE_REGISTRY_PORT` 环境变量 → 启动 Launcher API → 注册自身 + 注册模块 token
+- **Phase 2（启动 Event Hub）**：单独启动 Event Hub → stdin 发送 `launcher_ws_token` → stdout 获取 `ws_endpoint` → Launcher 连接 WebSocket → Event Hub 发送 module.ready → Launcher 发布 module.started → 断开 Event Hub stdio
+- **Phase 3（Registry 延迟就绪）**：Event Hub 注册到 Registry → Registry 检测到 `metadata.ws_endpoint` → Registry 连接 Event Hub WebSocket → Registry 发送 module.ready → Launcher 发布 module.started → 断开 Registry stdio
+- **Phase 4（启动其余模块）**：按拓扑序启动所有 enabled 模块
+
+Event Hub 必须在所有普通模块之前单独启动。Registry 的 ready 延迟到 Event Hub 上线后。扫描模块和读取 Event Hub module.md 可与等待 Registry 端口并行。
+
+---
+
+## 机制 2：Registry 端口发现
+
+Registry 启动 HTTP 服务后，通过 stdout 输出结构化消息 `{"kite":"port","port":12345}`。Launcher 的 stdout 读取线程捕获此消息并提取端口，写入 `KITE_REGISTRY_PORT` 环境变量。后续启动的子进程自动继承。
+
+不需要轮询 /health，port 消息本身就是 HTTP 就绪的证明。超时 6s，超时即 FATAL。
+
+---
+
+## 机制 3：stdin 延迟关闭
+
+stdin 写入 boot_info 后保持打开，Launcher 可继续发送结构化 JSON 消息（如 `launcher_ws_token`）。收到该模块的 module.ready 事件、发布 module.started 后，Launcher 同时关闭该模块的 stdin 和 stdout。
+
+对于 `launch.boot_stdin: false` 的模块，stdio 断开时机同样与 module.ready 挂钩。
+
+模块侧需处理 stdout 写入时的 BrokenPipeError（静默忽略，此时已有 Event Hub 通道）。
+
+---
+
+## 机制 4：stdout 结构化消息
+
+stdout 读取线程对每行输出尝试解析为 JSON。如果包含 `"kite"` 字段，视为结构化消息，按 kite 类型分发给 Launcher 主线程（跨线程回调/事件机制）。不含 `"kite"` 的行作为普通日志输出。
+
+当前定义的消息类型：
+
+| kite 值 | 字段 | 说明 |
+|---------|------|------|
+| `"port"` | `port: int` | HTTP 服务端口已绑定 |
+| `"ws_endpoint"` | `ws_endpoint: str` | Event Hub WebSocket 端点已就绪 |
+
+---
+
+## 机制 5：Event Hub 启动协议
+
+1. boot_info 只读 token
+2. 从 stdin 第二行读取 `{"kite":"launcher_ws_token","launcher_ws_token":"xxx"}` 并保存
+3. registry_port 从环境变量 `KITE_REGISTRY_PORT` 读取
+4. preferred_port 和 advertise_ip 从自身 module.md 读取
+5. 启动 HTTP + WS 服务
+6. stdout 输出 `{"kite":"ws_endpoint","ws_endpoint":"ws://{advertise_ip}:{port}/ws"}`
+7. Launcher 携带 launcher_ws_token 连入 WebSocket → Event Hub 本地验证 → 发送 module.ready
+8. stdio 断开后，Event Hub 再注册到 Registry
+
+---
+
+## 机制 6：Launcher ↔ Event Hub 认证
+
+Launcher 通过 stdin 向 Event Hub 发送专用的 `launcher_ws_token`（boot_info 之后的第二行 JSON）。Event Hub 保存该 token。
+
+Launcher 连接 Event Hub WebSocket 时携带此 token。Event Hub 本地验证（不走 Registry /verify），因为此时 Event Hub 尚未注册到 Registry。
+
+这是特殊的 bootstrap 认证机制，仅用于系统启动阶段。
+
+---
+
+## 机制 7：Registry 延迟就绪
+
+Registry HTTP 就绪后通过 stdout 输出 port 消息，但不发送 module.ready。
+
+等待 Event Hub 注册到 Registry（POST /modules 包含 `metadata.ws_endpoint`）后，Registry 主动连接 Event Hub WebSocket，连接成功后发送 `module.ready` 事件。
+
+Launcher 收到 Registry 的 module.ready 后发布 module.started，断开 Registry stdio。
+
+Registry module.ready 超时 12s，超时降级处理（WARNING，仍视为已启动）。
+
+---
+
+## 机制 8：boot_info 精简
+
+所有模块的 boot_info 统一为 `{"token":"..."}`。
+
+其他信息由模块自行获取：
+
+| 信息 | 来源 | 默认值 |
+|------|------|--------|
+| registry_port | 环境变量 `KITE_REGISTRY_PORT` | — |
+| preferred_port | 自身 module.md | 0（OS 动态分配） |
+| advertise_ip | 自身 module.md | 127.0.0.1 |
+
+Launcher 构造 boot_info 的所有位置（_start_registry / _start_one_module / API start / API restart）统一改为只传 token。
+
+---
+
+## 机制 9：_start_one_module 流程
+
+1. 发布 module.starting 事件
+2. 构造 boot_info `{token}`
+3. 启动子进程（stdin 保持打开）
+4. 等待 module.ready 事件（超时由 launch.timeout 配置，默认 30s，超时降级）
+5. 发布 module.started 事件
+6. 断开该模块的 stdin + stdout
+
+所有模块（Registry、Event Hub、普通模块）最终都走同一个收尾流程：ready → started → 断开 stdio。
+
+---
+
+## 机制 10：全量重启流程
+
+core 模块崩溃时触发全量重启，按 Phase 1 → 2 → 3 → 4 完整流程重启：
+
+1. 停止所有模块 + 断开 Launcher 与 Event Hub 的 WebSocket
+2. 重新生成 kite_token
+3. Phase 1：启动 Registry → stdout 拿 port → 写 KITE_REGISTRY_PORT
+4. Phase 2：启动 Event Hub → stdin launcher_ws_token → stdout ws_endpoint → Launcher 连 WS → Event Hub ready → 断开 stdio
+5. Phase 3：Event Hub 注册 Registry → Registry 连 Event Hub → Registry ready → 断开 stdio
+6. Phase 4：按拓扑序启动其余 enabled 模块
+
+全量重启失败则 Launcher 退出。
+
+---
+
+## 机制 11：端口文件系统移除
+
+移除所有与端口文件相关的逻辑：
+
+- Registry 的 `_write_port_file()` 函数
+- Launcher 的端口文件轮询和 /health 轮询
+- Launcher 退出时的端口文件删除
+- ProcessManager 遗留清理中的端口文件清理
+- 物理文件 `core/registry/data/port.txt` 和 `port_484.txt`
+
+---
+
+## 机制 12：内置模块校验
+
+Launcher 启动最开始（生成 token 之前），校验两个内置 core 模块：
+
+1. `core/registry/` 目录存在且包含可解析的 `module.md`
+2. `core/event_hub/` 目录存在且包含可解析的 `module.md`
+
+任一缺失则输出明确错误信息并 `sys.exit(1)`。
+
+---
+
+## 机制 13：模块自获取信息
+
+所有模块入口文件需要适配新的信息获取方式：
+
+| 模块 | 变更 |
+|------|------|
+| core/event_hub/entry.py | registry_port 改读 `KITE_REGISTRY_PORT`；advertise_ip 改读 module.md |
+| core/event_hub_bench/entry.py | registry_port 改读环境变量 |
+| extensions/services/watchdog/entry.py | registry_port 改读环境变量 |
+| test_modules/hello/entry.py | registry_port 改读环境变量 |
+| test_modules/hello_node/entry.js | registry_port 改读环境变量；stdin 改用 readline 逐行读取（不能等 EOF，否则死锁） |
+
+boot_info 只读 token，不再从中提取 registry_port / preferred_port / advertise_ip。
+
+---
+
+## 机制 14：ProcessManager 职责扩展
+
+ProcessManager 从「写完 stdin 即关」扩展为支持完整 stdio 生命周期管理：
+
+- **stdin 保持打开**：start_module() 写入 boot_info 后不关闭 stdin，保存引用
+- **write_stdin(name, data)**：新方法，向指定模块的 stdin 写入额外的结构化 JSON 消息
+- **close_stdio(name)**：新方法，同时关闭指定模块的 stdin 和 stdout，由 Launcher 在 ready → started 后调用
+- **stdout 结构化消息回调**：stdout 读取线程识别 `"kite"` 字段的 JSON 消息，通过回调/事件机制通知 Launcher 主线程
+
+---
+
+## 实现优先级
+
+| 优先级 | 机制 | 理由 |
+|--------|------|------|
+| P0 | 3, 4, 14 | 底层基础，所有其他机制依赖 |
+| P0 | 2, 11 | 启动第一步（Registry 端口发现） |
+| P0 | 5, 6 | Phase 2 核心（Event Hub 启动协议） |
+| P0 | 7 | Phase 3 核心（Registry 延迟就绪） |
+| P0 | 1 | 串联所有 Phase 的启动序列 |
+| P1 | 8, 9 | 统一协议和模块启动流程 |
+| P1 | 10 | 全量重启跟随新启动序列 |
+| P1 | 13 | 各模块侧适配 |
+| P2 | 12 | 安全增强 |