@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-/346/227/247/347/211/210.md

@@ -0,0 +1,1117 @@
+# 远程模块（Remote Module）设计
+
+## 1. 概述
+
+远程模块功能允许一个 Kite 实例（**卫星 Kite**）通过网络接入另一个 Kite 实例（**中心 Kite**），双方的模块可以互相发现、互相调用工具、互相收发事件，如同在同一台机器上运行。
+
+**核心场景：** 用户在本地运行中心 Kite，在其他机器或其他目录运行卫星 Kite。在中心 Web 管理后台生成配对串，粘贴到卫星 Web 管理后台，即完成接入。
+
+**卫星无需公网 IP。** 卫星主动向中心发起 WebSocket 出站连接，连接建立后双向通信。只要中心 Kite 的 Bridge Server 端口对卫星可达即可（公网、LAN、内网穿透均可）。支持跨域、跨 NAT。
+
+## 2. 架构总览
+
+### 2.1 当前单机架构
+
+```mermaid
+graph TB
+    subgraph "单机 Kite"
+        L[Launcher<br/>进程管理] --> K[Kernel<br/>127.0.0.1:动态端口]
+        L --> M1[模块 A]
+        L --> M2[模块 B]
+        L --> W[Web<br/>0.0.0.0:18766]
+
+        M1 -->|WS RPC| K
+        M2 -->|WS RPC| K
+        W -->|WS RPC| K
+    end
+```
+
+### 2.2 远程模块架构
+
+```mermaid
+graph TB
+    subgraph hub["中心 Kite（Hub）"]
+        L[Launcher] --> K[Kernel<br/>127.0.0.1]
+        L --> M1[本地模块 A]
+        L --> M2[本地模块 B]
+        L --> W[Web 模块<br/>0.0.0.0:18766]
+        L --> BS[Bridge Server<br/>0.0.0.0:固定端口]
+
+        M1 -->|WS RPC| K
+        M2 -->|WS RPC| K
+
+        BS -->|Kernel 代理| K
+
+        W -.->|配对管理 RPC| BS
+    end
+
+    subgraph sat["卫星 Kite（Satellite）"]
+        SL[Launcher] --> SK[Kernel<br/>127.0.0.1]
+        SL --> BC[Bridge Client]
+        SL --> SW[Web 模块]
+        SL --> SM1[远程模块 X]
+        SL --> SM2[远程模块 Y]
+
+        SM1 -->|WS RPC| SK
+        SM2 -->|WS RPC| SK
+        SM1 -->|WS RPC| SK
+        SM2 -->|WS RPC| SK
+
+        BC -->|Kernel 代理| SK
+        BC -->|Launcher 代理| SL
+    end
+
+    BC ===|"WSS 隧道<br/>wss://hub:端口/ws/bridge<br/>卫星主动出站连接"| BS
+
+    style BS fill:#f96,stroke:#333
+    style BC fill:#f96,stroke:#333
+    style W fill:#9cf,stroke:#333
+    style SW fill:#9cf,stroke:#333
+```
+
+### 2.3 三个角色的职责边界
+
+| 组件 | 所属 | 职责 |
+|------|------|------|
+| **Web 模块** | 两侧 | 仅负责配对操作（生成/粘贴配对串）、session_token 生命周期管理、卫星使用统计与审计查看 |
+| **Bridge Server** | 中心侧 | 独立模块，固定端口。接受卫星 WSS 连接，代理 Kernel RPC，承载工具调用代理 |
+| **Bridge Client** | 卫星侧 | 独立模块。连接中心 Bridge Server，双向同步 Kernel 注册和事件，代理中心对卫星模块的管理操作 |
+
+### 2.4 设计理念
+
+| 原则 | 决策 |
+|------|------|
+| 零侵入 | 不修改 Kernel、Launcher 核心代码 |
+| 模块独立 | Bridge Server 和 Bridge Client 是独立模块，Web 模块保持轻量 |
+| 模块无感知 | 两侧的普通模块无需知道对方的存在，照常连接 Kernel WS |
+| 双向对等 | 两侧模块可互相发现、互相调用工具、互相收发事件 |
+| 隧道复用 | 单条 WebSocket 承载 Registry + Event + Proxy + Control + Manage 五种通道 |
+| 卫星无需公网 | 卫星主动出站连接，穿透 NAT，无需开放任何端口 |
+
+## 3. 核心概念
+
+### 3.1 角色定义
+
+| 角色 | 说明 |
+|------|------|
+| **中心 Kite（Hub）** | 运行完整 Kite 实例，Bridge Server 对外暴露固定端口，接受卫星接入 |
+| **卫星 Kite（Satellite）** | 运行完整 Kite 实例，Bridge Client 主动连接中心，双方模块互通 |
+| **Bridge Server** | 中心侧独立模块，固定端口，WSS 端点，隧道的服务端 |
+| **Bridge Client** | 卫星侧独立模块，主动连接中心，隧道的客户端 |
+
+### 3.2 信息流向（双向）
+
+```mermaid
+graph LR
+    subgraph "中心 Kite"
+        HM[中心模块]
+        HK[Kernel]
+        BS[Bridge Server]
+    end
+
+    subgraph "卫星 Kite"
+        SM[卫星模块]
+        SK[Kernel]
+        BC[Bridge Client]
+    end
+
+    HM -->|"① 注册到"| HK
+    SM -->|"① 注册到"| SK
+
+    BS -->|"② 同步卫星模块到"| HK
+    BC -->|"② 同步中心模块到"| SK
+
+    HM -->|"③ 发现卫星模块 → 调用工具"| BS
+    SM -->|"③ 发现中心模块 → 调用工具"| BC
+
+    BS <-->|"隧道"| BC
+
+    HK <-->|"④ 事件双向转发"| BS
+    SK <-->|"④ 事件双向转发"| BC
+```
+
+**双向能力说明：**
+
+- **中心 → 卫星：** 中心模块通过 Kernel 发现卫星模块 → 通过 Bridge 隧道代理调用卫星工具
+- **卫星 → 中心：** 卫星模块通过 Kernel 发现中心模块 → 通过 Bridge 隧道代理调用中心工具
+- **事件互通：** 两侧 Kernel 的事件通过 Bridge 隧道双向转发
+
+## 4. 连接与认证
+
+### 4.1 配对流程
+
+用户在中心 Web UI 生成一段配对串（包含 Bridge Server 地址 + 一次性配对码），复制后粘贴到卫星 Web UI。
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant HW as 中心 Web UI
+    participant BS as Bridge Server
+    participant BC as Bridge Client
+    participant SW as 卫星 Web UI
+
+    Note over HW: 中心 Kite 正常运行
+
+    U->>HW: 点击「生成配对码」
+    HW->>BS: RPC bridge.generate_pairing
+    BS-->>HW: 返回配对 token
+    HW-->>U: 显示配对串<br/>如 "kite://192.168.1.1:28766/a3f8x9k2"
+
+    U->>U: 复制配对串
+
+    U->>SW: 粘贴配对串
+    SW->>BC: 传递配对信息（通过 Kernel 事件）
+
+    BC->>BS: WSS 连接 + 配对码认证
+    BS->>BS: 验证配对码，生成持久 session_token
+    BS-->>BC: bridge.welcome（含 session_token）
+
+    BC->>BC: 持久化 session_token
+
+    BC-->>SW: 通知配对成功
+    SW-->>U: 显示「已连接到 中心Kite」
+
+    Note over BC,BS: 后续重连自动使用 session_token
+```
+
+### 4.2 配对串格式
+
+```
+kite://{bridge_server_host}:{bridge_server_port}/{one_time_code}
+
+示例：
+kite://192.168.1.100:28766/a3f8x9k2
+kite://my-server.example.com:28766/b7c2m4p1
+```
+
+- 用户只需复制粘贴，无需手动填写 IP 和端口
+- 一次性码 5 分钟有效，用完即废
+- 配对串可通过任意方式传递（聊天、扫码、口头等）
+
+### 4.3 认证机制
+
+| 阶段 | 凭证 | 说明 |
+|------|------|------|
+| 首次配对 | 一次性配对码 | 从中心 Web UI 生成，5 分钟有效 |
+| 正常连接 | session_token | 配对成功后颁发，持久保存 |
+| 断线重连 | session_token | 自动重连，无需用户介入 |
+| 吊销 | 中心主动吊销 | 中心可随时吊销某卫星的 session_token |
+
+### 4.4 网络要求
+
+```mermaid
+graph LR
+    subgraph "卫星侧（无需公网 IP）"
+        BC[Bridge Client]
+    end
+
+    subgraph "中心侧（需固定端口可达）"
+        BS[Bridge Server<br/>0.0.0.0:28766]
+    end
+
+    BC -->|"WSS 出站连接<br/>卫星主动发起"| BS
+
+    style BC fill:#fbf
+    style BS fill:#f96
+```
+
+| 场景 | 中心 | 卫星 | 是否支持 |
+|------|------|------|---------|
+| 同一局域网 | LAN IP | LAN IP | ✅ |
+| 中心有公网 IP | 公网 IP | NAT 内 | ✅ |
+| 中心有域名 | 域名 | 任意 | ✅ |
+| 双方都在 NAT 内 | 需内网穿透 | 任意 | ✅（frp/ngrok 等穿透中心端口即可） |
+| 卫星在公网，中心在 NAT | — | — | ❌ 不支持（中心必须可达） |
+
+## 5. 隧道协议
+
+Bridge Server 和 Bridge Client 之间通过单条 WebSocket 连接传输所有消息，分为五个通道。
+
+### 5.1 消息信封
+
+```json
+{
+  "id": "消息唯一ID（用于请求-响应配对）",
+  "ch": "registry | event | proxy | control | manage",
+  "action": "具体动作",
+  "data": { ... }
+}
+```
+
+### 5.2 Registry 通道（`ch: "registry"`）
+
+双向同步模块注册信息。
+
+**方向 A：卫星模块 → 中心 Kernel（Bridge Client → Server）**
+
+| action | 说明 |
+|--------|------|
+| `register` | 注册卫星模块到中心 |
+| `heartbeat` | 卫星模块心跳 |
+| `deregister` | 注销卫星模块 |
+
+**方向 B：中心模块 → 卫星 Kernel（Bridge Server → Client）**
+
+| action | 说明 |
+|--------|------|
+| `register` | 注册中心模块到卫星 |
+| `heartbeat` | 中心模块心跳 |
+| `deregister` | 注销中心模块 |
+
+**响应（双向）：**
+
+| action | 说明 |
+|--------|------|
+| `register_ack` | 注册确认 |
+| `heartbeat_ack` | 心跳确认 |
+
+**示例（卫星模块注册到中心）：**
+```json
+{
+  "id": "msg-001",
+  "ch": "registry",
+  "action": "register",
+  "data": {
+    "module_id": "assistant",
+    "module_type": "agent",
+    "name": "对话助手",
+    "tools": { "search_web": { "description": "搜索网页" } },
+    "events_publish": { "assistant.response": {} },
+    "events_subscribe": { "channel.message.*": {} },
+    "metadata": {}
+  }
+}
+```
+
+### 5.3 Event 通道（`ch: "event"`）
+
+双向转发 Kernel 事件。
+
+| action | 方向 | 说明 |
+|--------|------|------|
+| `publish` | 双向 | 转发事件 |
+| `subscribe` | 双向 | 订阅同步 |
+| `unsubscribe` | 双向 | 取消订阅 |
+| `ack` | 双向 | 事件确认 |
+
+### 5.4 Proxy 通道（`ch: "proxy"`）
+
+双向代理工具调用（RPC 请求通过隧道转发）。
+
+**请求（双向发起）：**
+```json
+{
+  "id": "msg-100",
+  "ch": "proxy",
+  "action": "request",
+  "data": {
+    "target_module": "assistant",
+    "method": "search_web",
+    "params": {"query": "kite framework"}
+  }
+}
+```
+
+**响应：**
+```json
+{
+  "id": "msg-100",
+  "ch": "proxy",
+  "action": "response",
+  "data": {
+    "result": "搜索结果..."
+  }
+}
+```
+
+### 5.5 Control 通道（`ch: "control"`）
+
+桥接管理和状态同步。
+
+| action | 方向 | 说明 |
+|--------|------|------|
+| `ping` / `pong` | 双向 | 30s 心跳保活 |
+| `status` | 卫星 → 中心 | 卫星状态上报（模块列表、资源使用等） |
+| `disconnect` | 中心 → 卫星 | 主动断开（如 token 吊销） |
+
+### 5.6 Manage 通道（`ch: "manage"`）
+
+中心远程管理卫星模块生命周期。
+
+**模块启停（中心 → 卫星）：**
+```json
+{
+  "id": "msg-200",
+  "ch": "manage",
+  "action": "module_start",
+  "data": { "module_name": "model_service" }
+}
+```
+
+```json
+{
+  "id": "msg-201",
+  "ch": "manage",
+  "action": "module_stop",
+  "data": { "module_name": "model_service" }
+}
+```
+
+**模块列表查询（中心 → 卫星）：**
+```json
+{
+  "id": "msg-202",
+  "ch": "manage",
+  "action": "list_modules"
+}
+```
+
+**响应（卫星 → 中心）：**
+```json
+{
+  "id": "msg-202",
+  "ch": "manage",
+  "action": "list_modules_ack",
+  "data": {
+    "modules": [
+      { "name": "assistant", "config_state": "enabled", "desired_state": "running", "actual_state": "running" },
+      { "name": "model_service", "config_state": "manual", "desired_state": "stopped", "actual_state": "stopped" }
+    ]
+  }
+}
+```
+
+**状态变更（中心 → 卫星）：**
+```json
+{
+  "id": "msg-203",
+  "ch": "manage",
+  "action": "module_set_state",
+  "data": { "module_name": "model_service", "state": "enabled" }
+}
+```
+
+## 6. Bridge Server（中心侧独立模块）
+
+### 6.1 模块定义
+
+```yaml
+# extensions/services/bridge_server/module.md
+---
+name: bridge_server
+display_name: Bridge Server
+version: "1.0"
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+preferred_port: 28766        # 固定端口，对外暴露
+advertise_ip: 0.0.0.0
+depends_on:
+  - kernel
+events:
+  - bridge.satellite.connected
+  - bridge.satellite.disconnected
+  - bridge.satellite.module_synced
+subscriptions:
+  - module.started
+  - module.stopped
+  - module.ready
+---
+```
+
+### 6.2 职责
+
+1. **接受卫星连接** — `/ws/bridge` WebSocket 端点（WSS，自签名 SSL）
+2. **认证** — 验证配对码或 session_token（token 数据由 Web 模块管理，Bridge Server 通过 RPC 查询）
+3. **Kernel 双向代理** — 卫星模块注册到中心 Kernel + 中心模块注册到卫星 Kernel
+4. **Event 双向代理** — 中心 Kernel ↔ 隧道 ↔ 卫星 Kernel
+5. **Proxy 双向代理** — RPC 请求通过隧道转发到对端模块
+6. **Manage 代理** — 中心对卫星模块的远程启停管理
+7. **统计上报** — 向 Web 模块上报使用数据（事件/调用次数、流量、在线时长等）
+
+### 6.3 架构
+
+```mermaid
+graph TB
+    subgraph "Bridge Server 模块"
+        EP["/ws/bridge 端点<br/>WSS, 端口 28766"]
+        RP[Kernel 代理<br/>双向同步]
+        EVP[Event 代理<br/>双向转发]
+        PP[Proxy 代理<br/>双向工具调用]
+        MP[Manage 代理<br/>远程模块管理]
+        SM[卫星管理器<br/>连接/统计跟踪]
+        AU[审计记录器<br/>操作日志]
+    end
+
+    SAT1[卫星 A] -->|WSS| EP
+    SAT2[卫星 B] -->|WSS| EP
+
+    RP -->|WS RPC| K[中心 Kernel]
+    EVP -->|WS RPC| K
+    PP -->|WS RPC| LOCAL[中心本地模块]
+
+    SM -->|统计数据| W[Web 模块]
+    AU -->|审计日志| DISK[持久化存储]
+
+    style EP fill:#f96
+```
+
+### 6.4 Kernel 双向代理
+
+**卫星模块 → 中心 Kernel：**
+
+```
+收到卫星的 registry.register
+  │
+  ├─① 改写 module_id：添加节点前缀
+  │     原始: "assistant"
+  │     改写: "{satellite_name}@assistant"（如 "office@assistant"）
+  │
+  ├─② 自适应探测（详见第 8 节）：
+  │     探测卫星模块是否可达
+  │     可达 → 直连
+  │     不可达 → 代理
+  │
+  └─③ 通过 Kernel WS RPC 注册到中心
+        RPC: registry.register
+```
+
+**中心模块 → 卫星 Kernel（通过隧道）：**
+
+```
+监听中心 module.started / module.stopped 事件
+  │
+  ├─① 从中心 Kernel 获取模块完整注册信息
+  │     RPC: registry.lookup
+  │
+  ├─② 改写 module_id：添加节点前缀
+  │     原始: "model_service"
+  │     改写: "main@model_service"
+  │
+  ├─③ 通过隧道将中心模块信息发给 Bridge Client
+  │     Bridge Client 探测中心模块是否可达
+  │     可达 → 直连
+  │     不可达 → 代理
+  │
+  └─④ Bridge Client 通过 RPC 注册到卫星 Kernel
+```
+
+### 6.5 与 Web 模块的接口
+
+Bridge Server 和 Web 模块之间通过 Kernel WS RPC 交互：
+
+**Bridge Server 提供的 RPC 方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `bridge.generate_pairing` | 生成配对码 |
+| `bridge.revoke_pairing` | 撤销未使用的配对码 |
+| `bridge.list_satellites` | 列出所有卫星（含在线状态） |
+| `bridge.disconnect_satellite` | 吊销卫星 session_token 并断开 |
+| `bridge.list_satellite_modules` | 查看卫星的模块列表 |
+| `bridge.start_satellite_module` | 远程启动卫星模块 |
+| `bridge.stop_satellite_module` | 远程停止卫星模块 |
+
+**Web 模块提供的 RPC 方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `web.report_bridge_stats` | 接收统计数据上报 |
+| `web.validate_session_token` | 查询 session_token 有效性 |
+
+## 7. Bridge Client（卫星侧独立模块）
+
+### 7.1 模块定义
+
+```yaml
+# extensions/services/bridge_client/module.md
+---
+name: bridge_client
+display_name: Bridge Client
+version: "1.0"
+type: service
+state: manual              # 默认不启动，配对后启用
+runtime: python
+entry: entry.py
+preferred_port: 0          # 动态端口（用于代理中心模块的工具调用）
+depends_on:
+  - kernel
+events:
+  - bridge.connected
+  - bridge.disconnected
+  - bridge.module.synced
+subscriptions:
+  - module.started
+  - module.stopped
+  - module.ready
+---
+```
+
+### 7.2 职责
+
+1. **连接中心** — 主动出站 WSS 连接到 Bridge Server
+2. **注册同步（上行）** — 将本地模块注册信息同步到中心 Kernel
+3. **注册同步（下行）** — 将中心模块注册信息注册到本地 Kernel
+4. **事件桥接** — 本地 Kernel ↔ 隧道 ↔ 中心 Kernel
+5. **工具代理（入站）** — 代理中心对卫星模块的工具调用
+6. **工具代理（出站）** — 代理卫星模块对中心模块的工具调用
+7. **管理代理** — 接收中心的模块启停指令，转发给本地 Launcher
+8. **断线重连** — 指数退避自动重连
+
+### 7.3 工作流程
+
+```mermaid
+sequenceDiagram
+    participant BC as Bridge Client
+    participant LK as 卫星 Kernel
+    participant LL as 卫星 Launcher
+    participant BS as 中心 Bridge Server
+
+    Note over BC: 启动
+
+    BC->>LK: RPC registry.register（注册自身）
+    BC->>LK: RPC event.subscribe（订阅 module.*）
+
+    BC->>BS: WSS 连接（session_token）
+    BS-->>BC: bridge.welcome + 中心模块列表
+
+    Note over BC: 双向同步
+
+    BC->>LK: RPC registry.lookup（获取所有本地模块）
+    loop 每个本地模块（过滤后）
+        BC->>BS: registry.register（上行：同步到中心）
+    end
+
+    loop 每个中心模块（从 welcome 获取）
+        BC->>LK: RPC registry.register（下行：注册到本地）
+    end
+
+    Note over BC,BS: 持续运行
+
+    LK-->>BC: 本地事件
+    BC->>BS: event.publish（上行转发）
+
+    BS-->>BC: 中心事件
+    BC->>LK: RPC event.publish（下行转发）
+
+    BS-->>BC: manage.module_stop（远程管理）
+    BC->>LL: RPC launcher.stop_module
+
+    BS-->>BC: proxy.request（中心调卫星工具）
+    BC->>LK: RPC 查找目标模块
+    BC-->>BS: proxy.response
+```
+
+### 7.4 模块过滤
+
+**默认排除（不同步到对端）：**
+- `kernel` — 本地基础设施
+- `launcher` — 本地进程管理
+- `bridge_server` / `bridge_client` — 桥接自身
+- `watchdog` — 本地监控
+- `web` — Web 管理界面（两侧互相注册无意义）
+
+**配置文件 `data/config/bridge.yaml`：**
+```yaml
+bridge:
+  hub_url: ""                          # 配对时自动填充
+  session_token: ""                    # 配对时自动填充
+  satellite_name: "办公室的笔记本"
+  auto_connect: true                   # 启动时自动连接
+  sync:
+    include: []                        # 白名单（空=全部）
+    exclude:                           # 黑名单（追加到默认排除列表）
+      - backup                         # 示例：不同步备份模块
+    sync_tools: true
+    sync_hooks: false
+    sync_events: true
+  reconnect:
+    max_interval: 60                   # 最大重连间隔（秒）
+```
+
+## 8. 双向工具调用（自适应直连/代理）
+
+### 8.1 两种调用路径
+
+工具调用需要网络可达性。Bridge 自动探测最优路径：
+
+| 路径 | 说明 | 延迟 | 使用条件 |
+|------|------|------|---------|
+| **直连** | 调用方直接访问对端模块 | 最低 | 网络可达（同 LAN） |
+| **代理** | RPC 请求通过 Bridge WSS 隧道转发 | 多一跳 | 直连不通时自动降级 |
+
+**原则：能直连就直连，代理是降级方案。**
+
+### 8.2 自适应探测机制
+
+```mermaid
+sequenceDiagram
+    participant BC as Bridge Client
+    participant BS as Bridge Server
+
+    Note over BC,BS: 隧道建立后，交换网络信息
+
+    BC->>BS: control.status<br/>{satellite_ip: "192.168.1.10",<br/> modules: [{id: "assistant", ...}, ...]}
+    BS->>BS: 逐个探测卫星模块端点<br/>RPC {module_id}.health
+
+    alt 探测成功（直连可达）
+        BS->>BS: 标记 assistant → direct
+    else 探测失败（直连不通）
+        BS->>BS: 标记 assistant → proxy
+    end
+
+    BS->>BS: 注册到中心 Kernel（使用对应模式）
+
+    Note over BC,BS: 反向同理：BS 告知中心模块信息，BC 探测可达性
+```
+
+**探测流程详细说明：**
+
+1. **信息交换：** 隧道建立后，双方通过 `control.status` 交换各自的模块列表和 IP
+2. **可达性探测：** 收到对端信息后，逐个尝试 RPC `{module_id}.health`（超时 3s）
+3. **结果分类：**
+   - 探测成功 → 该模块标记为 `direct`，注册时使用对端原始地址
+   - 探测失败 → 该模块标记为 `proxy`，注册时使用 Bridge 代理
+4. **混合模式：** 同一个卫星的不同模块可能有不同结果
+5. **周期复查：** 每 5 分钟重新探测一次，网络环境变化时自动切换
+
+### 8.3 中心调用卫星工具
+
+**直连模式（LAN，自动探测可达）：**
+
+```mermaid
+sequenceDiagram
+    participant Agent as 中心 Agent
+    participant HK as 中心 Kernel
+    participant RM as 卫星模块 X
+
+    Agent->>HK: RPC registry.lookup(tools.search_web)
+    HK-->>Agent: module: "office@module_x"
+
+    Agent->>RM: RPC module_x.search_web
+    RM-->>Agent: {"result": "搜索结果"}
+
+    Note over Agent,RM: 直连，无隧道开销
+```
+
+**代理模式（跨 NAT，自动降级）：**
+
+```mermaid
+sequenceDiagram
+    participant Agent as 中心 Agent
+    participant HK as 中心 Kernel
+    participant BS as Bridge Server
+    participant BC as Bridge Client
+    participant RM as 卫星模块 X
+
+    Agent->>HK: RPC registry.lookup(tools.search_web)
+    HK-->>Agent: module: "office@module_x"<br/>(标记为 proxy)
+
+    Agent->>BS: RPC office@module_x.search_web
+    BS->>BC: 隧道: proxy.request
+    BC->>RM: RPC module_x.search_web
+    RM-->>BC: {"result": "搜索结果"}
+    BC-->>BS: 隧道: proxy.response
+    BS-->>Agent: {"result": "搜索结果"}
+```
+
+### 8.4 卫星调用中心工具
+
+**直连模式：**
+
+```mermaid
+sequenceDiagram
+    participant SM as 卫星模块 Y
+    participant SK as 卫星 Kernel
+    participant HM as 中心模块 A
+
+    SM->>SK: RPC registry.lookup(tools.read_file)
+    SK-->>SM: module: "main@kernel"
+
+    SM->>HM: RPC kernel.read_file
+    HM-->>SM: {"content": "文件内容"}
+```
+
+**代理模式：**
+
+```mermaid
+sequenceDiagram
+    participant SM as 卫星模块 Y
+    participant SK as 卫星 Kernel
+    participant BC as Bridge Client
+    participant BS as Bridge Server
+    participant HM as 中心模块 A
+
+    SM->>SK: RPC registry.lookup(tools.read_file)
+    SK-->>SM: module: "main@kernel"<br/>(标记为 proxy)
+
+    SM->>BC: RPC main@kernel.read_file
+    BC->>BS: 隧道: proxy.request
+    BS->>HM: RPC kernel.read_file
+    HM-->>BS: {"content": "文件内容"}
+    BS-->>BC: 隧道: proxy.response
+    BC-->>SM: {"content": "文件内容"}
+```
+
+## 9. 远程模块管理
+
+### 9.1 中心管理卫星模块
+
+中心可以通过 Web UI 或 RPC 管理卫星上的模块生命周期：
+
+```mermaid
+sequenceDiagram
+    participant U as 用户（中心 Web UI）
+    participant HW as 中心 Web 模块
+    participant BS as Bridge Server
+    participant BC as Bridge Client
+    participant SL as 卫星 Launcher
+
+    U->>HW: 点击「启动卫星模块 model_service」
+    HW->>BS: RPC bridge.start_satellite_module
+    BS->>BC: 隧道: manage.module_start
+    BC->>SL: RPC launcher.start_module
+    SL-->>BC: {"ok": true}
+    BC-->>BS: 隧道: manage.module_start_ack
+    BS-->>HW: {"ok": true}
+    HW-->>U: 显示「模块已启动」
+
+    Note over BC: 模块启动后自动同步注册到中心
+```
+
+### 9.2 管理能力
+
+| 操作 | 说明 | 通过 |
+|------|------|------|
+| 查看卫星模块列表 | 含三层状态（config/desired/actual） | manage.list_modules |
+| 启动卫星模块 | 调用卫星 Launcher RPC | manage.module_start |
+| 停止卫星模块 | 调用卫星 Launcher RPC | manage.module_stop |
+| 修改模块 state | 修改卫星 module.md 的 state | manage.module_set_state |
+| 查看卫星模块日志 | 读取卫星模块 latest.log | manage.get_log |
+
+### 9.3 权限控制
+
+- 远程管理需要中心侧的 session_token 有效
+- 卫星侧 Bridge Client 可配置允许的管理操作范围：
+
+```yaml
+# data/config/bridge.yaml
+bridge:
+  manage:
+    allow_start: true          # 允许中心启动模块
+    allow_stop: true           # 允许中心停止模块
+    allow_set_state: false     # 禁止中心修改模块 state（安全敏感）
+    allow_get_log: true        # 允许中心查看日志
+```
+
+## 10. 命名空间与标识规范
+
+### 10.1 分隔符
+
+整个系统只使用两种分隔符：
+
+| 分隔符 | 用途 | 示例 |
+|--------|------|------|
+| `@` | 节点边界（节点名 与 模块名 的分界） | `office@assistant` |
+| `.` | Kernel 路径层级 | `office@assistant.tools.search_web` |
+
+`@` 分隔"谁的"，`.` 分隔"的什么"。**本地模块可省略 `@` 前缀**，保持向后兼容。
+
+### 10.2 FQMN（Fully Qualified Module Name）
+
+远程模块在 Kernel 中注册时，使用完全限定名（FQMN）以区分来源节点：
+
+```
+格式: {node_name}@{module_id}
+
+示例:
+  office@assistant          ← 卫星节点 office 的 assistant 模块
+  server2@model_service     ← 卫星节点 server2 的 model_service 模块
+  main@kernel               ← 中心节点的 kernel 模块（完整写法）
+  kernel                    ← 中心节点的 kernel 模块（本地简写，等价于 main@kernel）
+```
+
+**与 Kernel `.` 路径无歧义：**
+
+```
+office@assistant.tools.search_web
+└─ node ─┘└ module ┘└ Kernel 字段路径 ┘
+```
+
+解析规则：看到 `@` → 前面是节点名，后面是 `module_id.field.path`。没有 `@` → 本地模块。**一行代码，零歧义。**
+
+### 10.3 节点命名规则
+
+**节点名（node_name）：**
+
+| 问题 | 回答 |
+|------|------|
+| 谁来命名？ | 用户命名。中心固定 `main`；卫星在 `bridge.yaml` 的 `satellite_name` 中配置 |
+| 什么时候命名？ | 中心：固定不可改；卫星：配对前由用户在 Web UI 设置 |
+| 可以修改吗？ | 卫星可以。修改后下次连接生效。Bridge Server 先清理旧名注册，再用新名重新注册 |
+| 命名规则？ | `[a-z0-9_-]+`，1-32 字符。"My Laptop" → `my-laptop`。允许中文（`办公室`） |
+| 保留名？ | `main`（中心专用）、`local`。卫星不可使用这些名称 |
+| 冲突怎么办？ | Bridge Server 检测到同名卫星已存在时，拒绝连接并返回错误 |
+
+**示例：**
+```
+main           → 中心节点（固定名称）
+office         → 卫星 "办公室"
+my-laptop      → 卫星 "我的笔记本"
+server2        → 卫星 "服务器2"
+```
+
+### 10.4 工具/事件的完整路径
+
+**工具查询：**
+
+```
+# 查询远程节点的工具
+RPC registry.get("office@assistant.tools.search_web")
+
+# 查询本地工具（简写，不变）
+RPC registry.get("kernel.tools.read_file")
+
+# 跨节点搜索
+RPC registry.lookup(field="tools.read_file")
+
+# 返回示例
+[
+  {
+    "field": "tools.read_file",
+    "module": "kernel",                      ← 本地模块返回简写
+    "value": {...}
+  },
+  {
+    "field": "tools.read_file",
+    "module": "office@assistant",            ← 远程模块返回 FQMN
+    "value": {...}
+  }
+]
+```
+
+**glob 查询：**
+```
+module=office@*             → 办公室卫星的所有模块
+module=*@assistant          → 所有节点的 assistant 模块
+module=*@model_service      → 所有节点的 model_service
+```
+
+**事件订阅：**
+```
+subscribe: ["session.started"]                    # 所有节点
+subscribe: ["office@*.session.started"]           # 节点级过滤
+```
+
+### 10.5 工具冲突与优先级
+
+当多个节点提供同名工具时（如 `read_file`），调用方需要选择。
+
+**两层优先级：**
+
+```
+第 1 层：节点优先级（哪个节点优先）
+第 2 层：模块优先级（同一节点内哪个模块优先）
+```
+
+**节点优先级配置（中心侧 `data/config/runtime.yaml`）：**
+```yaml
+remote_modules:
+  node_priority:             # 越靠前越优先
+    - main                   # 本地优先（可省略，默认第一位）
+    - office                 # 办公室卫星次之
+    - server2                # 服务器卫星最后
+```
+
+**默认行为（无需配置）：**
+- 本地优先（无 `@` 的模块排最前）
+- 远程模块按字母序
+
+## 11. 断线与恢复
+
+### 11.1 断线处理
+
+**中心侧（Bridge Server 检测到卫星断线）：**
+
+1. 从中心 Kernel 注销该卫星的所有远程模块（`{node_name}@*`）
+2. 清理该卫星在 Kernel 上的聚合订阅
+3. 保留 session_token（允许重连）
+4. 记录审计日志 `satellite.disconnected`
+5. 发布 `bridge.satellite.disconnected` 事件
+6. 更新统计数据
+
+**卫星侧（Bridge Client 检测到与中心断线）：**
+
+1. 从卫星 Kernel 注销所有中心模块（`main@*`）
+2. 清理 Kernel 聚合订阅
+3. 进入指数退避重连（1s → 2s → 4s → ... → 60s 上限）
+4. 本地模块继续正常运行
+5. 事件缓存到 outbox（复用现有 outbox 机制）
+
+### 11.2 重连恢复
+
+重连成功后，双方执行完整的全量同步：
+
+1. Bridge Server 发送 `bridge.welcome`（含中心模块列表快照）
+2. Bridge Client 发送所有本地模块注册信息（全量，幂等覆盖）
+3. Bridge Server 将中心模块列表通过隧道同步到卫星
+4. 双方重新建立事件订阅
+5. Bridge Client 重放 outbox 中的缓存事件
+
+## 12. 安全模型
+
+### 12.1 威胁分析
+
+| 威胁 | 缓解措施 |
+|------|---------|
+| 未授权卫星接入 | 配对码一次性 + session_token 可吊销 |
+| 中间人攻击 | WSS（TLS）加密 |
+| 恶意远程模块 | `{node}@` 前缀隔离，中心侧按节点名设权限 |
+| 隧道滥用 | 每卫星模块数上限（20）、事件限流（100/s）、代理超时（30s） |
+| 远程管理误操作 | 卫星侧可配置允许的管理操作范围 |
+| 核心服务暴露 | Kernel 保持 127.0.0.1，不对外暴露 |
+
+### 12.2 信任边界
+
+```mermaid
+graph TB
+    subgraph "信任域 A：中心 Kite"
+        K[Kernel<br/>127.0.0.1]
+        K --- HM[本地模块]
+        BS[Bridge Server<br/>0.0.0.0:28766]
+        BS ---|内部信任| K
+    end
+
+    subgraph "信任域 B：卫星 Kite"
+        SK[Kernel<br/>127.0.0.1]
+        SK --- SM[本地模块]
+        BC[Bridge Client]
+        BC ---|内部信任| SK
+    end
+
+    BS <-->|"TLS 隧道<br/>session_token 认证<br/>限流 + 审计"| BC
+
+    style BS fill:#f96
+    style BC fill:#f96
+```
+
+## 13. 配置参考
+
+### 13.1 中心侧 Bridge Server 配置
+
+`extensions/services/bridge_server/module.md`：
+
+```yaml
+bridge_server:
+  port: 28766                          # 固定对外端口
+  ssl: true                            # 启用 TLS（自签名证书自动生成）
+  max_satellites: 10                   # 最大卫星数
+  max_modules_per_satellite: 20        # 每卫星最大模块数
+  event_rate_limit: 100                # 事件限流（条/秒/卫星）
+  proxy_timeout: 30                    # 工具代理超时（秒）
+  audit_log: true                      # 启用审计日志
+```
+
+### 13.2 卫星侧 Bridge Client 配置
+
+`data/config/bridge.yaml`：
+
+```yaml
+bridge:
+  hub_url: ""                          # 配对时自动填充（Bridge Server 地址）
+  session_token: ""                    # 配对时自动填充
+  satellite_name: "办公室的笔记本"
+  auto_connect: true
+  sync:
+    include: []
+    exclude: []                        # 追加到默认排除列表
+    sync_tools: true
+    sync_hooks: false
+    sync_events: true
+  manage:
+    allow_start: true
+    allow_stop: true
+    allow_set_state: false
+    allow_get_log: true
+  reconnect:
+    max_interval: 60
+```
+
+## 14. 改造清单
+
+### 14.1 必须改动现有代码
+
+| 改动 | 涉及文件 | 说明 |
+|------|---------|------|
+| Kernel 新增 `bridge` 角色 | `kernel/rpc_router.py` | 允许 Bridge Server 代理注册/心跳/注销任意 module_id（约 15 行） |
+
+### 14.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`（直连探测） |
+
+### 14.3 Web 模块改动
+
+| 改动 | 说明 |
+|------|------|
+| 中心 Web UI | 配对码生成、卫星列表、统计仪表盘、审计日志查看 |
+| 卫星 Web UI | 粘贴配对串输入框、连接状态显示 |
+| 首次配对流程 | 解析配对串 → 写 bridge.yaml → 调 Launcher RPC 启动 Bridge Client |
+
+### 14.4 设计要点备忘
+
+| 要点 | 说明 |
+|------|------|
+| 事件环路防护 | Bridge 注入 Kernel 的事件记录 event_id，收到自己注入的事件时丢弃 |
+| session_token 归属 | 由 Bridge Server 全权管理（生成/存储/验证），持久化到自己的数据目录 |
+| Bridge Client 首次启动 | Web 模块解析配对串 → 写 bridge.yaml → 调 Launcher RPC 启动 Bridge Client |
+| 卫星 IP 获取 | 优先从 WSS 连接源 IP 获取 > bridge.yaml 手动配置 > 自动探测网卡 |
+| 重连时序 | 先交换 IP → 探测直连 → 再注册（用探测结果决定模式） |
+| Bridge Server 启动清理 | 启动时按节点名清理中心 Kernel 中的残留（`{node_name}@*`） |
+| 超时语义 | proxy_timeout 是 Bridge 端到端总时间（含隧道），调用方超时应大于此值 |
+| web 模块排除 | 加入默认排除列表（两侧 Web 模块互相注册无意义） |
+| 同名工具默认路由 | 按节点优先级选择，默认本地优先 |
+
+## 15. 实现分阶段
+
+### Phase 1：隧道 + 单向调用（MVP）
+
+- [ ] Kernel 新增 `bridge` 角色（允许代理注册）
+- [ ] Bridge Server 模块骨架（固定端口、WSS、SSL）
+- [ ] Bridge Client 模块骨架（WSS 连接、断线重连）
+- [ ] 隧道协议（消息信封 + registry/control 通道）
+- [ ] 配对流程（Web UI 生成配对串 → 粘贴 → 连接）
+- [ ] FQMN 命名（`{node_name}@{module_id}`）
+- [ ] Kernel 单向同步（卫星 → 中心）+ 心跳代理
+- [ ] 自适应直连/代理探测 + 工具调用（中心 → 卫星）
+- [ ] 事件环路防护（event_id 去重）
+- [ ] Bridge Server 启动时清理残留
+
+### Phase 2：双向互通
+
+- [ ] Kernel 双向同步（中心 → 卫星，`main@{module_id}`）
+- [ ] 自适应探测反向（卫星探测中心模块可达性）
+- [ ] 工具调用双向（卫星 → 中心）
+- [ ] Event 双向转发 + 事件过滤
+- [ ] outbox 机制（断线期间事件缓存）
+- [ ] 周期复查（5 分钟重新探测直连/代理）
+- [ ] 默认工具选择策略（本地优先）
+
+### Phase 3：远程管理 + 统计
+
+- [ ] Manage 通道（中心启停卫星模块）
+- [ ] 统计数据收集与上报
+- [ ] 审计日志
+- [ ] 中心 Web UI：卫星管理页面 + 统计仪表盘 + 审计日志查看
+- [ ] 每个远程模块显示当前调用模式（直连/代理）
+
+### Phase 4：增强
+
+- [ ] 可配置节点优先级（`node_priority` 列表）
+- [ ] 各节点可配置模块优先级
+- [ ] 卫星健康监控（中心 Watchdog 通过 Bridge 监控远程模块）
+- [ ] 节点级权限 ACL
+- [ ] 事件限流与反压