@agentunion/kite 1.5.0 → 1.6.1

package/docs//345/220/257/345/212/250/344/274/230/345/214/226/346/226/271/346/241/210.md

@@ -0,0 +1,522 @@
+# Kite 启动优化方案
+
+## 优化目标
+
+将系统启动时间从 ~2400ms 优化到 ~1350ms，提升约 44%。
+
+## 核心思路
+
+**将扩展模块的进程启动和 Python 冷启动提前到 Phase 1，与 Kernel 的 token 生成并行执行。**
+
+## 优化前的启动流程
+
+```
+Phase 1 (0-800ms): Kernel 启动
+  67ms   启动 Kernel 进程
+  177ms  Kernel 返回端口
+         ├─ 扫描模块
+         ├─ 连接 Kernel WS
+         └─ 生成 token（串行）
+  800ms  Phase 1 完成
+
+Phase 2 (800-2400ms): 扩展模块启动
+  805ms  开始启动扩展模块进程
+  994ms  最后一个进程启动完成
+         ├─ 各模块 Python 冷启动（400-500ms）
+         └─ 各模块连接 WS + ready
+  2400ms Phase 2 完成
+```
+
+**瓶颈分析：**
+- Phase 1 的 623ms（177ms → 800ms）期间，扩展模块还没启动
+- 扩展模块的 Python 冷启动（400-500ms）与 token 生成（500ms）串行执行
+- 总浪费时间：~600ms
+
+## 优化后的启动流程
+
+```
+Phase 1 (0-800ms): Kernel 启动 + 扩展模块进程启动（并行）
+  67ms   启动 Kernel 进程
+  177ms  Kernel 返回端口
+         ├─ 设置环境变量 KITE_KERNEL_PORT
+         ├─ 并行路径 A: 扫描模块（23ms）
+         ├─ 并行路径 B: 启动扩展模块进程（立即）← 新增
+         └─ 并行路径 C: 连接 WS + 生成 token（500ms）
+  800ms  Phase 1 完成，发送 token 到各模块 stdin
+
+Phase 2 (800-1350ms): 等待模块就绪
+  800ms  各模块收到 token（冷启动已完成，在 readline() 等待）
+         ├─ 继续初始化
+         ├─ 启动服务器
+         └─ 建立 WS 连接
+  1350ms Phase 2 完成
+```
+
+**优化收益：**
+- Python 冷启动（400-500ms）与 token 生成（500ms）并行
+- 模块初始化与 token 生成并行
+- 总节省时间：~1050ms
+
+## 详细实施方案
+
+### 1. Launcher 端实现
+
+#### 1.1 Phase 1 并行任务
+
+```python
+async def _phase1_start_kernel(self):
+    # ... 启动 Kernel，等待端口 ...
+
+    # 177ms: 拿到 Kernel 端口
+    os.environ["KITE_KERNEL_PORT"] = str(self.kernel_port)
+
+    # 并行执行 3 个任务
+    await asyncio.gather(
+        _scan_and_generate_tokens(),    # A: 扫描 + 生成 token
+        _connect_kernel_ws(),            # B: 连接 WS
+        _start_extension_processes(),    # C: 启动扩展模块进程 ← 新增
+    )
+```
+
+#### 1.2 启动扩展模块进程
+
+```python
+async def _start_extension_processes():
+    """启动扩展模块进程，并在 token 生成后发送。
+
+    流程：
+    1. 等待模块扫描完成
+    2. 启动所有扩展模块进程（不发送 stdin）
+    3. 等待 token 生成完成（带超时）
+    4. 发送 token 到各模块 stdin
+    """
+    # 等待模块扫描完成
+    while not self.modules:
+        await asyncio.sleep(0.01)
+
+    # 确定要启动的模块
+    to_start = [m for m in self.modules.values()
+               if m.state == "enabled" and m.name not in CORE_MODULE_NAMES]
+
+    if not to_start:
+        return
+
+    print(f"[launcher] 提前启动 {len(to_start)} 个扩展模块进程（并行冷启动）...")
+
+    # 启动进程（不发送 stdin）
+    for info in to_start:
+        self._log_lifecycle("starting", info.name)
+        ok = self.process_manager.start_module(info, boot_info=None)
+        if ok:
+            self._launch_counts[info.name] = self._launch_counts.get(info.name, 0) + 1
+            print(f"[launcher] 已启动 {info.name} (PID {self.process_manager.get_pid(info.name)})")
+        else:
+            self._log_lifecycle("start_failed", info.name)
+
+    self.process_manager.persist_records()
+
+    # 等待 token 生成完成（带超时）
+    try:
+        timeout = 10  # 10 秒超时
+        start_time = time.monotonic()
+        while not self._module_tokens:
+            if time.monotonic() - start_time > timeout:
+                raise asyncio.TimeoutError()
+            await asyncio.sleep(0.01)
+    except asyncio.TimeoutError:
+        # 发送失败信息到所有模块
+        print("\033[91m[launcher] 错误: Token 生成超时\033[0m")
+        for info in to_start:
+            if self.process_manager.is_running(info.name):
+                self.process_manager.write_stdin(info.name, {
+                    "error": "token_generation_timeout",
+                    "message": "Kernel token generation timeout"
+                })
+        raise RuntimeError("Token 生成超时")
+
+    # 发送 token 到所有已启动的模块
+    for info in to_start:
+        if self.process_manager.is_running(info.name):
+            token = self._module_tokens.get(info.name, "")
+            if token:
+                self.process_manager.write_stdin(info.name, {"token": token})
+            else:
+                print(f"\033[91m[launcher] 警告: 模块 {info.name} 没有 token\033[0m")
+```
+
+#### 1.3 Phase 2 等待模块就绪
+
+```python
+async def _phase2_start_modules(self):
+    """等待扩展模块就绪（进程已在 Phase 1 启动）。"""
+    to_wait = [m for m in self.modules.values()
+               if self._desired_states.get(m.name) == "running"
+               and m.name not in CORE_MODULE_NAMES
+               and self.process_manager.is_running(m.name)]
+
+    if not to_wait:
+        print("[launcher] 没有模块需要等待")
+        return
+
+    total = len(to_wait)
+    print(f"[launcher] 等待 {total} 个模块就绪...")
+
+    # 并行等待所有模块 ready
+    await asyncio.gather(*(self._wait_module_ready(info) for info in to_wait))
+
+async def _wait_module_ready(self, info: ModuleInfo):
+    """等待单个模块发送 module.ready 事件。"""
+    ready_key = f"module.ready:{info.name}"
+    ready_evt = asyncio.Event()
+    ready_data = {}
+    self._event_waiters[ready_key] = (ready_evt, ready_data)
+
+    timeout = info.launch.timeout
+    t0 = time.monotonic()
+    try:
+        await asyncio.wait_for(ready_evt.wait(), timeout=timeout)
+        ready = ready_data
+    except asyncio.TimeoutError:
+        ready = None
+    finally:
+        self._event_waiters.pop(ready_key, None)
+
+    elapsed = time.monotonic() - t0
+    if ready and ready.get("_exited"):
+        # 模块主动退出
+        reason = ready.get("reason", "unknown")
+        self._exit_reasons[info.name] = reason
+        print(f"[launcher] 模块 '{info.name}' 主动退出: {reason} ({elapsed:.2f}s)")
+    elif ready:
+        # 模块就绪
+        self._graceful_modules[info.name] = bool(ready.get("graceful_shutdown"))
+        self._ready_timestamps[info.name] = time.time()
+        startup_str = f"{elapsed:.3f}s" if elapsed < 10 else f"{elapsed:.2f}s"
+        print(f"[launcher] 模块 '{info.name}' 已就绪 ({startup_str})")
+        self._log_lifecycle("started", info.name)
+        await self._publish_event("module.started", {"module_id": info.name})
+        self.process_manager.close_stdio(info.name)
+    else:
+        # 超时
+        print(f"\033[91m[launcher] 模块 '{info.name}' 启动超时 ({timeout}s)\033[0m")
+        self._log_lifecycle("start_timeout", info.name)
+```
+
+### 2. 模块端实现
+
+#### 2.1 FastAPI 模块（evol/web）
+
+**优化前的流程：**
+```python
+# entry.py main()
+# 1. Python 冷启动 + 导入库（400ms）
+import uvicorn
+from server import EvolServer
+
+# 2. 读取 token（阻塞等待）← 这里阻塞
+line = sys.stdin.readline()
+token = json.loads(line).get("token", "")
+
+# 3. 读取 kernel_port（环境变量）
+kernel_port = int(os.environ.get("KITE_KERNEL_PORT", "0"))
+
+# 4. 创建 Server + 启动 uvicorn
+server = EvolServer(token=token, kernel_port=kernel_port, ...)
+uvicorn.run(server.app, ...)
+```
+
+**优化后的流程：**
+```python
+# entry.py main()
+# 1. Python 冷启动 + 导入库（400ms）← 与 token 生成并行
+import uvicorn
+from server import EvolServer
+
+# 2. 读取 kernel_port（环境变量，立即可用）
+kernel_port = int(os.environ.get("KITE_KERNEL_PORT", "0"))
+
+if not kernel_port:
+    print("[evol] ERROR: Missing KITE_KERNEL_PORT")
+    sys.exit(1)
+
+# 3. 创建 Server（token 占位符）
+server = EvolServer(
+    token="",  # 占位符，稍后读取
+    kernel_port=kernel_port,
+    host=host,
+    port=port,
+    boot_t0=_t0,
+)
+
+# 4. 读取 token（阻塞等待）← 在这里读取，简单直接
+line = sys.stdin.readline().strip()
+if not line:
+    print("[evol] ERROR: stdin closed, no token received")
+    sys.exit(1)
+
+msg = json.loads(line)
+
+# 检查是否是错误消息
+if "error" in msg:
+    print(f"\033[91m[evol] 启动失败: {msg.get('message', 'unknown error')}\033[0m")
+    sys.exit(1)
+
+# 获取 token
+token = msg.get("token", "")
+if not token:
+    print("[evol] ERROR: Missing token in boot_info")
+    sys.exit(1)
+
+# 更新 Server 的 token
+server.token = token
+print(f"[evol] Token received ({len(token)} chars)")
+
+# 5. 启动 uvicorn
+display_host = "localhost" if host == "0.0.0.0" else host
+url = f"http://{display_host}:{port}"
+print(f"[evol] Starting on {host}:{port}")
+print(f"\033[32m✓ Evol UI ready: {url}\033[0m")
+
+try:
+    config = uvicorn.Config(server.app, host=host, port=port, log_level="warning")
+    uvi_server = uvicorn.Server(config)
+    server._uvicorn_server = uvi_server
+    uvi_server.run()
+except Exception as e:
+    print(f"[evol] ERROR: {e}")
+    sys.exit(1)
+```
+
+**server.py 不需要修改：**
+```python
+@app.on_event("startup")
+async def _startup():
+    # 直接使用 server.token（已在 entry.py 中设置）
+    if server.kernel_port:
+        server._ws_task = asyncio.create_task(server._ws_loop())
+    server._test_task = asyncio.create_task(server._test_event_loop())
+    # ... 其他初始化 ...
+```
+
+#### 2.2 轻量模块（event_hub_bench 等）
+
+**流程保持不变：**
+```python
+# entry.py main()
+# 1. Python 冷启动 + 导入库（与 token 生成并行）
+import websockets
+
+# 2. 读取 kernel_port（环境变量）
+kernel_port = int(os.environ.get("KITE_KERNEL_PORT", "0"))
+
+# 3. 读取 token（阻塞等待）
+line = sys.stdin.readline().strip()
+msg = json.loads(line)
+
+if "error" in msg:
+    print(f"[event_hub_bench] 启动失败: {msg.get('message')}")
+    sys.exit(1)
+
+token = msg.get("token", "")
+
+# 4. 连接 WS + 执行任务
+# ...
+```
+
+### 3. 关键技术点
+
+#### 3.1 stdin 管道缓冲机制
+
+**问题：** Launcher 发送 token 时，模块可能还在冷启动，还没执行到 readline()，会丢失吗？
+
+**答案：** 不会。stdin 是管道（pipe），有内核缓冲区：
+- Launcher 写入时，数据进入管道缓冲区
+- 模块 readline() 时，从缓冲区读取
+- 即使写入发生在读取之前，数据也不会丢失
+
+#### 3.2 环境变量传递 kernel_port
+
+**kernel_port 通过环境变量传递，不是 stdin：**
+
+```python
+# Launcher 端（177ms 拿到端口后）
+os.environ["KITE_KERNEL_PORT"] = str(self.kernel_port)
+
+# 模块端（立即可用）
+kernel_port = int(os.environ.get("KITE_KERNEL_PORT", "0"))
+```
+
+**优势：**
+- 模块进程启动后立即可以读取
+- 不需要等待 Launcher 发送
+- 可以提前创建对象和绑定端口
+
+#### 3.3 token 通过 stdin 传递
+
+**token 通过 stdin 传递，需要等待 Launcher 生成：**
+
+```python
+# Launcher 端（800ms token 生成完成后）
+self.process_manager.write_stdin(module_name, {"token": token})
+
+# 模块端（阻塞等待）
+line = sys.stdin.readline()
+msg = json.loads(line)
+token = msg.get("token", "")
+```
+
+**WS 连接需要 token：**
+
+```python
+url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id={module_id}"
+async with websockets.connect(url, ...) as ws:
+    # 连接时 Kernel 验证 token
+```
+
+**所以 token 必须在建立 WS 连接之前获取。**
+
+#### 3.4 错误处理协议
+
+**Launcher 发送错误消息：**
+
+```json
+{
+  "error": "token_generation_timeout",
+  "message": "Kernel token generation timeout"
+}
+```
+
+**模块处理错误消息：**
+
+```python
+msg = json.loads(sys.stdin.readline())
+if "error" in msg:
+    print(f"[{MODULE_NAME}] 启动失败: {msg.get('message')}")
+    sys.exit(1)
+```
+
+### 4. 健壮性保证
+
+#### 4.1 超时处理
+
+**Launcher 端：**
+- Token 生成超时（10 秒）→ 发送错误消息到所有模块 → 模块退出 → Launcher 打印红色警告并退出
+- 模块 ready 超时（各模块配置的 timeout）→ 打印红色警告 → 继续等待其他模块
+
+**模块端：**
+- 收到错误消息 → 打印红色警告 → 立即退出
+
+#### 4.2 进程生命周期管理
+
+**在模块 ready 之前：**
+- 模块的生命周期由 Launcher 控制
+- 如果 stdin 被断开（Launcher 退出），模块应该检测到并退出
+- 如果模块启动失败，Launcher 会尝试重启（根据配置）
+
+**在模块 ready 之后：**
+- 模块独立运行
+- Launcher 通过 WS 监控模块状态
+- 模块异常退出时，Launcher 根据配置决定是否重启
+
+#### 4.3 stdin 断开检测
+
+**模块端应该检测 stdin 断开：**
+
+```python
+line = sys.stdin.readline()
+if not line:  # stdin 被关闭
+    print(f"[{MODULE_NAME}] ERROR: stdin closed, Launcher may have exited")
+    sys.exit(1)
+```
+
+### 5. 优化收益分析
+
+**时间节省：**
+
+| 阶段 | 优化前 | 优化后 | 节省 |
+|------|--------|--------|------|
+| Phase 1 | 800ms | 800ms | 0ms |
+| 模块进程启动 | 200ms（Phase 2） | 0ms（并行） | 200ms |
+| Python 冷启动 | 400ms（Phase 2） | 0ms（并行） | 400ms |
+| 模块初始化 | 600ms（Phase 2） | 150ms（并行） | 450ms |
+| **总计** | **2400ms** | **1350ms** | **1050ms** |
+
+**性能提升：** 约 44%
+
+### 6. 风险评估
+
+#### 风险 1: stdin 时序问题
+
+**风险：** Launcher 发送 token 时，模块还没执行到 readline()。
+
+**缓解：** stdin 管道有内核缓冲区，数据不会丢失。已在 Linux/Windows 验证。
+
+#### 风险 2: 进程过早启动导致资源竞争
+
+**风险：** 10 个模块同时冷启动，CPU/内存压力大。
+
+**缓解：**
+- 现代多核 CPU 可以并行处理
+- Python 冷启动主要是 I/O（加载 .pyc），不是 CPU 密集
+- 实测影响很小
+
+#### 风险 3: 错误处理复杂化
+
+**风险：** Phase 1 失败时，已启动的模块需要清理。
+
+**缓解：**
+- Launcher 的 shutdown 流程已经处理所有运行中的进程
+- 模块收到错误消息后会自动退出
+- 无需额外清理逻辑
+
+### 7. 实施步骤
+
+#### 步骤 1: 修改 Launcher
+
+1. 在 `_phase1_start_kernel` 中添加 `_start_extension_processes()` 并行任务
+2. 实现 `_start_extension_processes()` 函数（启动进程 + 等待 token + 发送 token）
+3. 修改 `_phase2_start_modules()` 为 `_wait_module_ready()` 逻辑
+4. 添加超时处理和错误消息发送
+
+#### 步骤 2: 修改 FastAPI 模块（evol/web）
+
+1. 修改 `entry.py`：
+   - 提前读取 `kernel_port`
+   - 创建 Server（token=""）
+   - 在启动 uvicorn 之前 readline() 读取 token
+   - 更新 `server.token`
+   - 添加错误消息处理
+
+2. `server.py` 不需要修改（直接使用 `self.token`）
+
+#### 步骤 3: 修改轻量模块（event_hub_bench 等）
+
+1. 添加错误消息处理：
+   ```python
+   msg = json.loads(sys.stdin.readline())
+   if "error" in msg:
+       print(f"[{MODULE_NAME}] 启动失败: {msg.get('message')}")
+       sys.exit(1)
+   ```
+
+#### 步骤 4: 测试验证
+
+1. 测试正常启动流程
+2. 测试 token 生成超时场景
+3. 测试模块启动失败场景
+4. 测试 stdin 断开场景
+5. 验证启动时间优化效果
+
+### 8. 后续优化方向
+
+1. **Kernel 端口预分配**：在 Launcher 启动时预分配端口，避免等待 Kernel 返回（节省 ~110ms）
+2. **模块依赖并行启动**：当前按拓扑层串行启动，可以改为依赖满足后立即启动
+3. **Watchdog 延迟启动**：Watchdog 可以在 system.ready 后再启动，不阻塞其他模块
+
+### 9. 参考资料
+
+- `launcher/entry.py` - Launcher 主逻辑
+- `launcher/process_manager.py` - 进程管理
+- `extensions/services/evol/entry.py` - 模块启动入口
+- `extensions/services/evol/server.py` - FastAPI 服务器
+- `docs/日志与异常处理规范.md` - 日志规范

package/docs//345/220/257/345/212/250/344/276/235/350/265/226/344/270/216/346/216/222/345/272/217.md

@@ -0,0 +1,105 @@
+# 启动依赖与排序
+
+## 1. 概述
+
+模块可通过 `module.md` 中的 `depends_on` 字段声明启动依赖。Launcher 按拓扑序启动模块，确保依赖模块先就绪。
+
+## 2. module.md 扩展
+
+新增可选字段 `depends_on`：
+
+```yaml
+---
+name: conversation
+depends_on:
+  - event_hub
+  - kernel
+---
+```
+
+## 3. 启动就绪标准
+
+### 3.1 module.ready 事件
+
+模块完成初始化并注册到 Registry 后，**必须**发布 `module.ready` 事件：
+
+```json
+{
+  "event": "module.ready",
+  "source": "webchat",
+  "data": {
+    "module_id": "webchat",
+    "base_url": "http://{advertise_ip}:{port}"
+  }
+}
+```
+
+这是所有模块必须支持的标准事件。Launcher 以收到此事件作为"启动成功"的判定标准。
+
+### 3.2 Launcher 侧行为
+
+Launcher 启动模块时：
+1. 发布 `module.starting` 事件（通知其他模块）
+2. 启动子进程
+3. 等待 `module.ready` 事件（超时 30s）
+4. 收到 ready → 发布 `module.started` 事件，控制台输出日志
+5. 超时未收到 → 打印 WARNING，仍视为已启动（降级处理）
+
+## 4. 启动排序算法
+
+```
+1. 扫描所有 enabled 模块，解析 depends_on
+2. 构建依赖图，检测循环依赖（有则报错退出）
+3. 拓扑排序，得到启动顺序
+4. 按顺序启动：
+   对每个模块 M：
+     for dep in M.depends_on:
+       if dep 未运行且未在启动中:
+         启动 dep（递归处理 dep 的依赖）
+       if dep 正在启动中:
+         等待 dep 的 module.ready 事件（超时 30s）
+     启动 M，等待 M 的 module.ready
+5. 无 depends_on 的模块并行启动
+```
+
+## 5. manual 模块被依赖时的处理
+
+如果模块 A 的 `depends_on` 包含模块 B，而 B 的 state 是 `manual`：
+
+- Launcher **自动启动 B**（即使 B 不在 enabled 列表中）
+- 只有 `disabled` 状态的模块不能被启动，此时报错
+
+## 6. core 模块
+
+core 模块（registry、event_hub、kernel）的启动顺序由 Launcher 硬编码保证，不需要声明 `depends_on`。其他模块可以依赖 core 模块。
+
+## 7. 事件定义
+
+| 事件 | 方向 | 说明 |
+|------|------|------|
+| `module.starting` | Launcher → 广播 | 模块即将启动 |
+| `module.ready` | 模块 → Launcher | 模块服务就绪 |
+| `module.started` | Launcher → 广播 | 模块启动成功（收到 ready 后发出） |
+
+### module.starting payload
+
+```json
+{
+  "event": "module.starting",
+  "source": "launcher",
+  "data": { "module_id": "webchat" }
+}
+```
+
+### module.ready payload
+
+```json
+{
+  "event": "module.ready",
+  "source": "webchat",
+  "data": {
+    "module_id": "webchat",
+    "base_url": "http://{advertise_ip}:{port}"
+  }
+}
+```