@agentunion/kite 1.4.0 → 1.6.0

package/docs/stdio/344/270/216/347/253/257/345/217/243/345/217/221/347/216/260/351/207/215/346/236/204.md

@@ -0,0 +1,480 @@
+# stdio 与端口发现重构
+
+## 1. 概述
+
+重构模块启动通信机制，核心变更：
+
+1. **boot_info 精简为只传 token**，其他信息模块自行获取
+2. **消除 port 文件**，Registry 通过 stdout 回传端口，Launcher 写入环境变量
+3. **Registry 延迟发送 module.ready**，等 Event Hub 上线后再发，统一所有模块的就绪协议
+4. **stdio 生命周期统一**：启动阶段保持双向通道，收到 module.ready 后一起断开
+
+## 2. boot_info 精简
+
+### 2.1 变更前
+
+Registry:
+```json
+{"token": "...", "registry_port": 0, "bind": "127.0.0.1", "instance_id": "484"}
+```
+
+普通模块:
+```json
+{"token": "...", "registry_port": 12345, "preferred_port": 0, "advertise_ip": "127.0.0.1"}
+```
+
+### 2.2 变更后
+
+所有模块统一:
+```json
+{"token": "..."}
+```
+
+### 2.3 模块自行获取其他信息
+
+| 信息 | 来源 | 默认值 |
+|------|------|--------|
+| `registry_port` | 环境变量 `KITE_REGISTRY_PORT` | — |
+| `preferred_port` | 自己的 `module.md` | `0`（OS 动态分配） |
+| `advertise_ip` | 自己的 `module.md` | `127.0.0.1` |
+
+## 3. stdio 生命周期
+
+### 3.1 变更前
+
+```
+stdin:  写完 boot_info → 立即关闭
+stdout: daemon 线程读取日志 → 进程退出时自然结束（从不主动关闭）
+```
+
+### 3.2 变更后
+
+```
+stdin:  写入 boot_info → 保持打开（双向通道）
+stdout: 读取结构化消息 + 日志 → 保持打开
+
+断开时机: Launcher 收到该模块的 module.ready 事件后，
+         发布 module.started，然后同时关闭 stdin + stdout
+```
+
+启动阶段和就绪阶段都保持双向 stdio 通道。收到 module.ready 后，模块已连接 Event Hub，后续通信全部走事件和 HTTP，stdio 不再需要。
+
+对于 `launch.boot_stdin: false` 的模块（不通过 stdin 接收 boot_info），stdio 断开时机同样与 module.ready 挂钩。
+
+### 3.3 断开操作
+
+```python
+# Launcher 收到 module.ready 后执行：
+proc.stdin.close()    # 关闭写入端
+proc.stdout.close()   # 关闭读取端 → stdout 线程自然退出
+```
+
+模块侧需处理 stdout 写入时的 BrokenPipeError（静默忽略即可，此时已有 Event Hub 通道）。
+
+### 3.4 跨语言 stdin 读取约束
+
+**stdin 保持打开意味着模块不能等待 EOF 来解析 boot_info。** 所有模块必须使用逐行读取（readline）方式，读取第一行后立即解析，不能等待 stdin 关闭。
+
+Python（正确）：
+```python
+line = sys.stdin.readline()
+boot_info = json.loads(line)
+```
+
+Node.js（正确）：
+```javascript
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+rl.once('line', line => {
+  const bootInfo = JSON.parse(line.trim());
+  rl.close();
+  start(bootInfo);
+});
+```
+
+Node.js（错误 — 会死锁）：
+```javascript
+// ❌ 等待 EOF，stdin 不关闭则永远挂起
+process.stdin.on('end', () => { ... });
+```
+
+### 3.5 超时机制
+
+| 等待项 | 超时 | 超时行为 |
+|--------|------|----------|
+| Registry stdout port 消息 | 6s | FATAL，退出程序 |
+| Event Hub stdout ws_endpoint 消息 | 6s | FATAL，退出程序 |
+| Registry module.ready 事件 | 12s | WARNING，降级处理（仍视为已启动） |
+| Event Hub module.ready 事件 | 15s | WARNING，降级处理 |
+| 普通模块 module.ready 事件 | `launch.timeout`（默认 30s） | WARNING，降级处理 |
+
+## 4. stdout 结构化消息协议
+
+### 4.1 格式
+
+启动阶段，模块可通过 stdout 发送结构化 JSON 消息。每条消息占一行，必须包含 `"kite"` 字段：
+
+```json
+{"kite":"port","port":12345}
+```
+
+### 4.2 Launcher stdout 读取线程逻辑
+
+```python
+for line in iter(proc.stdout.readline, b""):
+    text = line.decode("utf-8", errors="replace").rstrip()
+    if not text:
+        continue
+    # 尝试解析结构化消息
+    try:
+        msg = json.loads(text)
+        if "kite" in msg:
+            handle_kite_message(name, msg)  # 按 kite 类型分发
+            continue
+    except (json.JSONDecodeError, KeyError):
+        pass
+    # 非结构化行作为日志输出
+    print(f"[{name}] {text}")
+```
+
+### 4.3 当前定义的消息类型
+
+| kite 值 | 字段 | 说明 |
+|---------|------|------|
+| `"port"` | `port: int` | 模块 HTTP 服务已启动，端口已绑定成功 |
+| `"ws_endpoint"` | `ws_endpoint: str` | Event Hub WebSocket 端点已就绪 |
+
+后续可扩展其他消息类型（如 `"status"`、`"error"` 等）。
+
+### 4.4 stdin 结构化消息（Launcher → 模块）
+
+stdin 保持打开期间，Launcher 可向模块发送额外的结构化 JSON 消息（boot_info 之后的行）。格式同样为每行一条 JSON，包含 `"kite"` 字段。
+
+当前仅 Event Hub 使用：
+
+| kite 值 | 字段 | 说明 |
+|---------|------|------|
+| `"launcher_ws_token"` | `launcher_ws_token: str` | Launcher 连接 Event Hub WebSocket 时的身份验证 token |
+
+示例：
+```
+第 1 行（boot_info）: {"token":"eh_token"}
+第 2 行（stdin 消息）: {"kite":"launcher_ws_token","launcher_ws_token":"xxx"}
+```
+
+Event Hub 收到后保存该 token。当 WebSocket 连接携带此 token 时，Event Hub 识别为 Launcher 连接，触发 module.ready 流程。
+
+## 5. 完整启动流程
+
+### Phase 1: 引导
+
+```
+Launcher                                Registry
+   │                                       │
+   ├─ 生成 kite_token                      │
+   ├─ 直接读取 core/registry/module.md      │
+   ├─ 启动 Registry 子进程                  │
+   ├─ stdin: {"token":"kite_token"} ───────→│ 读取 token
+   │  （stdin 保持打开）                     │ 读取 module.md → preferred_port, advertise_ip
+   │                                       ├─ 绑定端口
+   │  ┌─ 并行：扫描其他模块 ────┐           ├─ 启动 HTTP 服务
+   │  │  直接读取                │           ├─ HTTP 就绪，端口绑定确认
+   │  │    core/event_hub/      │           ├─ stdout: {"kite":"port","port":12345}
+   │  │  扫描                    │           │
+   │  │    core/ 其余模块        │           │
+   │  │    extensions/           │           │
+   │  └────────────────────────┘           │
+   │◄─ stdout 线程提取 port ────────────────┤
+   │                                       │
+   ├─ self.registry_port = 12345            │
+   ├─ os.environ["KITE_REGISTRY_PORT"] = "12345"
+   │                                       │
+```
+
+要点：
+- Registry 和 Event Hub 都是内置 core 模块，路径硬编码（`core/registry/`、`core/event_hub/`），不依赖扫描发现
+- 等待 Registry 回报端口的同时，并行读取 Event Hub 的 module.md 并扫描其余模块
+- Registry 在 HTTP 服务启动成功后才输出 port 消息，确保端口绑定成功
+- Launcher 拿到端口后立即写入环境变量，后续启动的子进程自动继承
+- 不需要轮询 /health，port 消息本身就是就绪证明
+
+### Phase 2: 启动 Event Hub
+
+```
+Launcher                    Event Hub               Registry
+   │                            │                       │
+   ├─ POST /modules 注册自身    │                       │
+   ├─ POST /tokens 注册模块 token                       │
+   │                            │                       │
+   ├─ 启动 Event Hub 子进程     │                       │
+   ├─ stdin: {"token":"eh_token"} ─→│ 读取 token        │
+   │  stdin: {"kite":"launcher_ws_token",              │
+   │          "launcher_ws_token":"xxx"} ─→│ 保存 token │
+   │  （stdin 保持打开）             │ 读 env KITE_REGISTRY_PORT
+   │                            │ 读 module.md → preferred_port, advertise_ip
+   │                            ├─ 绑定端口             │
+   │                            ├─ 启动 HTTP + WS       │
+   │                            ├─ stdout: {"kite":"ws_endpoint",
+   │                            │           "ws_endpoint":"ws://{advertise_ip}:{port}/ws"}
+   │◄─ stdout 线程提取 ────────┤                       │
+   │   ws_endpoint              │                       │
+   │                            │                       │
+   ├─ WebSocket 连接 ──────────→│ 检测到 Launcher 连入  │
+   │  (携带 launcher_ws_token)   │ 验证 token 匹配      │
+   ├─ 订阅所有事件 [">"]        │                       │
+   │                            │                       │
+   │◄── module.ready ──────────┤                       │
+   │    source: "event_hub"    │                       │
+   │                            │                       │
+   ├─ 发布 module.started       │                       │
+   │   (event_hub)              │                       │
+   ├─ 断开 Event Hub stdio ───╳│                       │
+   │                            │                       │
+   │                            ├─ POST /modules ─────→│ 注册 event_hub
+   │                            │  (含 ws_endpoint)     │  (含 metadata.ws_endpoint)
+   │                            │                       │
+```
+
+要点：
+- Launcher 通过 stdin 向 Event Hub 发送专用的 `launcher_ws_token`（boot_info 之后的第二行 JSON），Event Hub 保存该 token
+- Event Hub 通过 stdout 回传 ws_endpoint
+- Launcher 连接 Event Hub WebSocket 时携带 `launcher_ws_token`，Event Hub 验证身份后确认为 Launcher 连接
+- Launcher 连接 Event Hub 后，Event Hub 立即发送 module.ready
+- Launcher 走标准流程：收到 ready → 发布 started → 断开 stdio
+- stdio 断开后，Event Hub 再注册到 Registry（此时通信已走 WebSocket）
+- Event Hub 注册到 Registry 后，Registry 才能感知并连接 Event Hub
+
+### Phase 3: Registry 延迟就绪 + 启动其他模块
+
+```
+Launcher          Event Hub             Registry
+   │                  │                     │
+   │                  │                     ├─ 收到 event_hub 注册
+   │                  │                     │  (含 metadata.ws_endpoint)
+   │                  │                     ├─ 检测到 Event Hub 可用
+   │                  │◄── WebSocket 连接 ──┤ 主动连接 Event Hub
+   │                  │                     │
+   │                  │◄── module.ready ────┤ 发布:
+   │◄── 转发 ────────┤                     │  event: "module.ready"
+   │                  │                     │  source: "registry"
+   │                  │                     │  data:
+   │                  │                     │    module_id: "registry"
+   │                  │                     │    base_url: "http://{advertise_ip}:{port}"
+   │                  │                     │
+   ├─ 发布 module.started (registry)        │
+   ├─ 断开 Registry stdio ────────────────╳│
+   │                  │                     │
+   │  同时/之后：                            │
+   │                  │                     │
+   ├─ 按拓扑序启动其他 enabled 模块          │
+   │    stdin: {"token":"mod_token"}        │
+   │    （继承 KITE_REGISTRY_PORT 环境变量） │
+   │                  │                     │
+```
+
+### Phase 4: 收尾（所有模块统一行为）
+
+```
+Launcher                                模块
+   │                                       │
+   ├─ 收到 module.ready                     │
+   ├─ 发布 module.started                   │
+   ├─ 关闭 stdin + stdout ────────────────╳│ stdio 断开
+   │                                       │
+   │  （后续通信全部走 Event Hub + HTTP）     │
+```
+
+Registry、Event Hub、普通模块全部走同一个收尾流程，无特殊分支。
+
+### 内置模块校验
+
+Launcher 启动最开始，在生成 token 之前，先校验两个内置 core 模块是否存在。任一缺失则输出明确错误信息并退出程序：
+
+```python
+# 校验内置模块
+project_root = os.environ.get("KITE_PROJECT", ".")
+registry_dir = os.path.join(project_root, "core", "registry")
+event_hub_dir = os.path.join(project_root, "core", "event_hub")
+
+missing = []
+if not os.path.isdir(registry_dir):
+    missing.append(f"  - Registry: {registry_dir}")
+if not os.path.isdir(event_hub_dir):
+    missing.append(f"  - Event Hub: {event_hub_dir}")
+
+if missing:
+    print("[launcher] FATAL: Required core modules not found:")
+    for m in missing:
+        print(m)
+    print("[launcher] Registry and Event Hub are required infrastructure.")
+    print("[launcher] Please ensure the Kite installation is complete.")
+    sys.exit(1)
+```
+
+同时校验 `module.md` 是否存在且可解析：
+
+```python
+for name, dir_path in [("Registry", registry_dir), ("Event Hub", event_hub_dir)]:
+    md_path = os.path.join(dir_path, "module.md")
+    if not os.path.isfile(md_path):
+        print(f"[launcher] FATAL: {name} module.md not found at {md_path}")
+        print(f"[launcher] Cannot start without {name} configuration.")
+        sys.exit(1)
+```
+
+### 时序总览
+
+```
+T0  Launcher 启动
+      生成 kite_token
+      直接读取 core/registry/module.md
+      启动 Registry → stdin 传 token
+      并行：直接读取 core/event_hub/module.md + 扫描其余模块
+
+T1  Registry 就绪（HTTP）
+      stdout 回传端口
+      Launcher 写入 KITE_REGISTRY_PORT 环境变量
+
+T2  Launcher 注册自身 + 注册模块 token
+
+T3  Launcher 启动 Event Hub → stdin 传 token
+      Event Hub 启动 HTTP + WS
+      Event Hub stdout 回传 ws_endpoint
+      Launcher 连接 Event Hub WebSocket，订阅所有事件
+      Event Hub 检测到 Launcher 连入 → 发送 module.ready
+      Launcher 收到 → 发布 module.started → 断开 Event Hub stdio
+
+T4  Event Hub 注册到 Registry（stdio 已断开，走 HTTP）
+      Registry 收到 Event Hub 注册 → 连接 Event Hub WS → 发送 module.ready
+      Launcher 收到 → 发布 module.started → 断开 Registry stdio
+
+T5  Launcher 按拓扑序启动其他 enabled 模块
+      所有模块从 env 读取 KITE_REGISTRY_PORT
+      所有模块从 module.md 读取 preferred_port, advertise_ip
+
+T6  其他模块陆续 module.ready
+      Launcher 逐个 started + 断开 stdio
+
+T7  系统就绪
+```
+
+### 运行时启动 / 重启模块
+
+通过 API 在运行时启动或重启单个模块时，同样遵循标准的 stdio 生命周期：
+
+```
+Launcher                                模块
+   │                                       │
+   ├─ 启动子进程                            │
+   ├─ stdin: {"token":"mod_token"} ───────→│ 读取 token
+   │  （stdin 保持打开）                     │ 读 env KITE_REGISTRY_PORT
+   │                                       ├─ 注册到 Registry
+   │                                       ├─ 连接 Event Hub
+   │                                       ├─ 发送 module.ready
+   │◄── module.ready ─────────────────────┤
+   ├─ 发布 module.started                   │
+   ├─ 关闭 stdin + stdout ────────────────╳│
+   │                                       │
+```
+
+重启 = 先停止旧进程（关闭 stdio + 等待退出），再按上述流程启动新进程。不存在特殊路径。
+
+### 全量重启（Full Restart）
+
+Launcher 的 `_full_restart()` 重新执行 Phase 1 → Phase 2 → Phase 3 的完整流程：
+
+1. 停止所有模块（含 Registry 和 Event Hub）
+2. 断开 Launcher 与 Event Hub 的 WebSocket 连接
+3. 重新生成 kite_token
+4. Phase 1：启动 Registry → 等待 stdout port → 写入 `KITE_REGISTRY_PORT`
+5. Phase 2：启动 Event Hub → 等待 stdout ws_endpoint → Launcher 连接 WS → Event Hub ready → 断开 stdio
+6. Phase 3：Event Hub 注册到 Registry → Registry 连接 Event Hub → Registry ready → 断开 stdio
+7. 按拓扑序启动其他 enabled 模块
+
+## 6. Registry 感知 Event Hub 的机制
+
+Registry 收到模块注册请求（POST /modules）时，检查注册信息中是否包含 `metadata.ws_endpoint`。如果有，说明 Event Hub 已上线：
+
+```python
+# Registry 注册处理器中（伪代码）
+def on_module_register(module_data):
+    # 正常注册逻辑...
+    store.register(module_data)
+
+    # 检测 Event Hub
+    ws_endpoint = module_data.get("metadata", {}).get("ws_endpoint")
+    if ws_endpoint and not self._event_hub_connected:
+        asyncio.create_task(self._connect_event_hub(ws_endpoint))
+
+async def _connect_event_hub(self, ws_endpoint):
+    # 连接 Event Hub
+    ws_url = f"{ws_endpoint}?token={self.launcher_token}"
+    self._ws = await websockets.connect(ws_url)
+    self._event_hub_connected = True
+
+    # 发送 module.ready
+    await self._ws.send(json.dumps({
+        "type": "event",
+        "event": "module.ready",
+        "source": "registry",
+        "data": {
+            "module_id": "registry",
+            "base_url": f"http://{self.advertise_ip}:{self.port}"
+        }
+    }))
+```
+
+## 7. 消除的内容
+
+| 移除项 | 位置 |
+|--------|------|
+| `_write_port_file()` 函数 | `core/registry/entry.py` |
+| port 文件轮询（200ms/10s） | `core/launcher/entry.py: _start_registry()` |
+| /health 轮询 | `core/launcher/entry.py: _start_registry()` |
+| port 文件清理 | `core/launcher/entry.py: shutdown()` |
+| port 文件清理 | `core/launcher/process_manager.py: _cleanup_stale()` |
+| legacy port.txt 兼容 | `core/launcher/process_manager.py: _cleanup_stale()` |
+| `port.txt` | `core/registry/data/port.txt` |
+| `port_484.txt` | `core/registry/data/port_484.txt` |
+| boot_info 中的 `registry_port` | Launcher 所有构造 boot_info 处（4 处） |
+| boot_info 中的 `preferred_port` | Launcher 所有构造 boot_info 处 |
+| boot_info 中的 `advertise_ip` | Launcher 所有构造 boot_info 处 |
+| boot_info 中的 `bind` | Launcher Registry boot_info |
+| boot_info 中的 `instance_id` | Launcher Registry boot_info |
+
+## 8. 代码改动清单
+
+### Launcher 侧
+
+| 文件 | 改动 |
+|------|------|
+| `entry.py: _start_registry()` | 重写：boot_info 只传 token；删除 port 文件逻辑和 /health 轮询；改为等待 stdout port 消息；拿到端口后写环境变量 |
+| `entry.py: _connect_event_hub()` | 重写：启动 Event Hub 后通过 stdin 发送 `launcher_ws_token`；等待 stdout ws_endpoint；携带 token 连接 WebSocket |
+| `entry.py: _start_one_module()` | boot_info 改为 `{"token": token}`；收到 ready + 发布 started 后断开 stdio |
+| `entry.py: start/restart API` | boot_info 改为 `{"token": token}`；遵循标准 ready→started→断开 stdio 流程 |
+| `entry.py: _full_restart()` | 重写：按 Phase 1→2→3 完整流程重启 |
+| `entry.py: shutdown()` | 删除 port 文件删除逻辑 |
+| `process_manager.py: _read_stdout()` | 增加结构化消息识别（`"kite"` 字段）；需要回调/事件机制通知 Launcher |
+| `process_manager.py: start_module()` | stdin 写入 boot_info 后不再关闭 |
+| `process_manager.py: _cleanup_stale()` | 删除 port 文件清理逻辑 |
+
+### Registry 侧
+
+| 文件 | 改动 |
+|------|------|
+| `registry/entry.py` | boot_info 只读 token；从 module.md 读 preferred_port；删除 `_write_port_file()`；HTTP 启动后 stdout 输出 port 消息；新增 Event Hub 感知 + 连接 + 发送 module.ready |
+
+### 模块侧
+
+| 文件 | 改动 |
+|------|------|
+| `event_hub/entry.py` | registry_port 改读 `os.environ["KITE_REGISTRY_PORT"]`；advertise_ip 改读 module.md；boot_info 只读 token；新增 stdin 读取 `launcher_ws_token`；WebSocket 连接时验证 Launcher 身份 |
+| `event_hub_bench/entry.py` | registry_port 改读环境变量 |
+| `test_modules/hello/entry.py` | registry_port 改读环境变量 |
+| `test_modules/hello_node/entry.js` | registry_port 改读 `process.env.KITE_REGISTRY_PORT`；preferred_port 改读 module.md；stdin 读取改用 readline（修复 EOF 死锁） |
+
+### 文件删除
+
+- `core/registry/data/port.txt`
+- `core/registry/data/port_484.txt`
+