@agentunion/kite 1.5.0 → 1.6.0

package/docs/Kite/347/263/273/347/273/237/345/220/257/345/212/250/346/265/201/347/250/213.md

@@ -0,0 +1,567 @@
+# Kite 系统启动流程
+
+本文档完整描述 Kite 框架从 `main.py` 到所有模块就绪的全部流程和机制细节。
+
+## 启动阶段总览
+
+```
+main.py
+  └─ Launcher.__init__() → .run()
+       └─ _async_main()
+            ├─ Phase 1: 启动 Kernel + 并行任务
+            │   ├─ 1. 启动 Kernel 进程
+            │   ├─ 2. 等待 Kernel 输出端口 + launcher_token
+            │   ├─ 3. 设置 KITE_KERNEL_PORT 环境变量
+            │   └─ 4. 并行执行:
+            │       ├─ A: 扫描模块
+            │       ├─ B: 连接 Kernel WS → 注册 → 生成 token → 等待 Kernel ready
+            │       └─ C: 启动扩展模块进程 → 等 token → 发送 token
+            ├─ 清理残留进程（非阻塞）
+            ├─ Phase 2: 发 module.starting → 等待扩展模块就绪
+            ├─ system.ready 事件
+            └─ 监控循环
+```
+
+**典型时间线（优化后）：**
+
+| 时间点 | 事件 |
+|--------|------|
+| 0ms | Launcher 启动 Kernel 进程 |
+| ~67ms | Kernel 进程已创建 |
+| ~177ms | Kernel 输出端口 + launcher_token |
+| ~177ms | 并行: 扫描模块 / 连接 WS / 启动扩展模块 |
+| ~200ms | 扩展模块进程已创建，开始 Python 冷启动 |
+| ~700ms | 扩展模块冷启动完成，等待 stdin（阻塞在 readline） |
+| ~800ms | Token 生成完成，发送到各模块 stdin |
+| ~800ms | Kernel module.ready |
+| ~1350ms | 所有扩展模块 module.ready |
+| ~1400ms | system.ready |
+
+## Phase 1: 启动 Kernel
+
+### 1.1 Kernel 进程启动
+
+Launcher 构造 `ModuleInfo` 并调用 `ProcessManager.start_module()` 启动 Kernel 进程。
+
+```
+Launcher
+  └─ process_manager.start_module(kernel_info, boot_info=None)
+       └─ subprocess.Popen(cmd, stdin=PIPE, stdout=PIPE, stderr=STDOUT)
+```
+
+**stdin 管道规则：所有模块一律创建 stdin 管道（`stdin=subprocess.PIPE`），无论是否有初始数据要写。** 即使是 Kernel 也创建管道，为后续扩展预留通道（如 Launcher 向 Kernel 报告启动进度）。`boot_info` 参数仅控制是否在启动时立即写入数据，不影响管道的创建。
+
+关键代码路径：`launcher/entry.py:_phase1_start_kernel()`
+
+### 1.2 Kernel 端口绑定与输出
+
+Kernel 进程启动后的执行顺序（关键在于 **延迟导入**）：
+
+1. 加载 `module.md` 配置（模块名、preferred_port）
+2. 绑定端口（优先使用 preferred_port，失败则系统分配）
+3. 生成 `launcher_token`（`secrets.token_urlsafe(32)`）
+4. **立即输出端口信息到 stdout**（结构化 JSON）
+5. **延迟导入** `uvicorn` 和 `KernelServer`（重量级依赖）
+6. 创建 `KernelServer`、自注册
+7. 启动 uvicorn
+
+**端口输出协议（Kernel → Launcher）：**
+
+```json
+{"kite": "port", "port": 19900, "token": "launcher_kite_token_xxx"}
+```
+
+- `kite: "port"` — 结构化消息标识
+- `port` — Kernel 实际绑定的端口
+- `token` — launcher_token，Launcher 用此 token 连接 Kernel WS
+
+关键代码路径：`kernel/entry.py:main()`
+
+### 1.3 Launcher 等待端口
+
+Launcher 通过 `_wait_kite_message()` 等待 Kernel stdout 输出端口信息：
+
+- ProcessManager 的 stdout reader 线程逐行读取子进程 stdout
+- 检测到 `{"kite": "port"}` 格式后，通过 `_on_kite_message` 回调通知 Launcher
+- Launcher 主线程通过 `threading.Event` 等待（带 6s 超时）
+- 等待过程中每 0.5s 检查一次 shutdown 标志，确保 Ctrl+C 响应
+
+拿到端口后：
+- 设置 `KITE_KERNEL_PORT` 环境变量（子进程继承）
+- 保存 `launcher_token` 到 `_module_tokens["launcher"]`
+
+### 1.4 并行任务
+
+拿到 Kernel 端口后，Launcher 用 `asyncio.gather()` 并行执行三个任务：
+
+#### 任务 A: 扫描模块
+
+```
+扫描 extensions/ 下所有模块目录（读取 module.md）
+  → 得到模块列表（名称、状态、运行时、依赖等）
+  → set _modules_scanned 事件（通知任务 B、C）
+```
+
+扫描很快（~23ms），完成后任务 B 和 C 都可以继续推进。
+
+#### 任务 B: 连接 Kernel WS + 生成 token
+
+```
+连接 Kernel WS（连接后首条消息认证）
+  → 启动接收循环（_ws_receiver）
+  → 订阅所有事件（event.subscribe）
+  → 注册 Launcher 自身到注册中心
+  → 发布 Launcher 的 module.ready 事件
+  → 等待模块扫描完成（_modules_scanned）
+  → 通过 RPC 调用 kernel.generate_tokens 生成各模块 token
+  → set _tokens_generated 事件（通知任务 C）
+  → 等待 Kernel 的 module.ready 事件
+```
+
+Token 生成依赖 WS 连接就绪 + 模块扫描完成，由 Kernel 通过 RPC 完成。每个模块有唯一的 token，用于连接 Kernel WS 时的身份认证。
+
+**Token 生成失败处理：** 如果 RPC 失败或返回错误，设置 `_token_error` 标志并 set `_tokens_generated` 事件，让任务 C 检测到错误并向所有模块发送失败消息后退出。
+
+**注意事项：**
+- 接收循环必须先启动，再发送 RPC 请求（否则死锁）
+- `module.ready:kernel` 的 event waiter 必须在订阅事件之前注册（防止竞态）
+
+#### 任务 C: 启动扩展模块进程（优化核心）
+
+```
+等待模块扫描完成（_modules_scanned，带超时）
+  → 筛选 enabled 且非核心的模块
+  → 启动进程（boot_info=None，创建管道但不写数据）
+  → 等待 token 生成完成（_tokens_generated，带 10s 超时）
+  → 检查 _token_error:
+      有错误 → 向所有模块 stdin 发送错误消息 → 抛异常
+      无错误 → 向所有模块 stdin 发送 token
+```
+
+**任务间同步使用 `asyncio.Event`**，不使用忙等待（`while not ...: sleep`）：
+
+- `_modules_scanned` — 任务 A 完成后 set
+- `_tokens_generated` — 任务 B 生成 token 后 set（成功或失败都 set）
+
+两处等待都通过 `asyncio.wait_for(..., timeout=N)` 设置超时，避免永久阻塞。
+
+**这是启动优化的核心：** 扩展模块的 Python 冷启动（~400ms）与 Kernel 的 token 生成（~500ms）并行执行，节省 ~1050ms。
+
+### 1.5 Phase 1 完成后
+
+- 发布 `module.started` 事件（Kernel）
+- 关闭 Kernel 的 stdin（`close_stdio("kernel")`）
+- 执行残留进程清理（本地 + 全局，非阻塞）
+
+## Phase 2: 等待模块就绪
+
+Phase 2 **只等待**，不启动进程（进程已在 Phase 1 的任务 C 中启动）。
+
+```
+筛选 desired_state == "running" 的扩展模块
+  → 对每个模块: 发布 module.starting 事件
+  → asyncio.gather(*(wait_module_ready(info) for info in to_wait))
+```
+
+**`module.starting` 事件在 Phase 2 发布**，不在 Phase 1 任务 C 中发布。原因：任务 C 启动进程时 WS 可能还没连上，无法发布事件。Phase 2 时 WS 已就绪，事件能正常路由。
+
+每个模块的等待逻辑：
+
+```
+注册 module.ready:{module_name} 事件等待器
+  → asyncio.wait_for(ready_evt.wait(), timeout=模块配置的 timeout)
+  → 收到 module.ready:
+      记录 ready_timestamp
+      记录 graceful_shutdown 能力
+      发布 module.started 事件
+      关闭 stdin（close_stdio）
+  → 收到 module.exiting（_exited 标记）:
+      模块主动退出，记录原因
+  → 超时:
+      见下方"模块启动超时"章节
+```
+
+关键代码路径：`launcher/entry.py:_phase2_start_modules()` 和 `_wait_module_ready()`
+
+### 首次启动 vs 运行时重启
+
+| | 首次启动（Phase 1 + 2） | 运行时重启（`_start_one_module`） |
+|---|---|---|
+| 进程创建 | 任务 C 提前创建，boot_info=None | 创建时直接写 boot_info={"token":"xxx"} |
+| token 发送 | 任务 C 等 token 后通过 write_stdin 发送 | 创建时已包含在 boot_info 中 |
+| module.starting | Phase 2 进入等待时发布 | _start_one_module 内发布 |
+| 目的 | 并行冷启动，优化启动速度 | 标准流程，简单直接 |
+
+模块端无需区分两种场景——都是从 stdin 读到 `{"token":"xxx"}` 后继续执行。
+
+## Token 认证机制
+
+### Token 类型
+
+| Token | 生成方 | 用途 |
+|-------|--------|------|
+| `launcher_token` | Kernel（启动时） | Launcher 连接 Kernel WS 的凭证 |
+| 模块 token | Kernel（RPC 生成） | 各模块连接 Kernel WS 的凭证 |
+
+### Token 流转
+
+```
+Kernel 启动
+  → 生成 launcher_token
+  → stdout 输出给 Launcher
+  → Launcher 连接 WS → 首条消息认证
+  → Launcher 通过 RPC kernel.generate_tokens 请求模块 token
+  → Kernel 生成并返回 {module_name: token} 映射
+  → Launcher 通过 stdin 发送 token 给各模块
+  → 各模块连接 Kernel WS → 首条消息认证
+```
+
+### WS 连接认证
+
+**Token 不放在 URL 中**，通过连接后首条消息认证，避免 token 泄露到日志：
+
+```
+WS 连接建立: ws://127.0.0.1:{port}/ws?id={module_name}
+  → 模块发送: {"jsonrpc":"2.0", "id":"1", "method":"auth", "params":{"token":"xxx"}}
+  → Kernel 校验 token 与 module_name 是否匹配
+    → 通过: 返回 {"jsonrpc":"2.0", "id":"1", "result":{"ok":true}}
+            连接进入已认证状态，开始正常 JSON-RPC 2.0 通信
+    → 失败: 返回 error → 关闭连接（4001）
+    → 超时（5s 内未收到 auth）: 关闭连接（4003）
+```
+
+**未认证状态下 Kernel 的行为：**
+- 只接受 `method: "auth"` 请求
+- 拒绝所有其他 RPC 请求和事件订阅
+- 不转发任何事件
+
+使用 JSON-RPC 2.0 格式（而非自定义 kite 消息）进行认证，保持协议统一——连接上来第一条消息就是标准 RPC 调用，Kernel 正常返回 response。
+
+### 调试模式
+
+设置 `KITE_DEBUG=1` 时，Kernel 接受所有 token（跳过验证），用于开发调试。启动时输出红色警告：
+
+```
+[kernel] ⚠ 调试模式已启用 (KITE_DEBUG=1)，接受所有令牌，请勿在生产环境使用
+```
+
+## stdin/stdout 协议
+
+### stdout 协议（子进程 → Launcher）
+
+子进程 stdout 的每一行被 ProcessManager 的 reader 线程读取：
+
+- **结构化消息：** 以 `{` 开头的 JSON，且包含 `"kite"` 字段 → 通过 `_on_kite_message` 回调分发
+- **普通日志：** 其他内容 → 添加 `[module_name]` 前缀后打印
+
+已知的结构化消息类型：
+
+| kite 类型 | 方向 | 说明 |
+|-----------|------|------|
+| `port` | Kernel → Launcher | Kernel 端口 + launcher_token |
+
+### stdin 协议（Launcher → 子进程）
+
+**所有模块启动时一律创建 stdin 管道（`stdin=subprocess.PIPE`）。** `boot_info` 参数仅控制是否立即写入数据，不影响管道创建。
+
+Launcher 通过 `write_stdin()` 向模块发送 JSON 行（`\n` 结尾）：
+
+| 场景 | 数据格式 |
+|------|----------|
+| 正常启动（首次） | `{"token": "xxx"}`（延迟发送） |
+| 正常启动（运行时重启） | `{"token": "xxx"}`（创建时立即写入） |
+| Token 生成超时 | `{"error": "token_generation_timeout", "message": "..."}` |
+
+**管道缓冲机制：** Launcher 写入 stdin 时，即使模块还没执行到 `readline()`，数据也不会丢失。stdin 是管道（pipe），操作系统提供内核缓冲区，写入的数据会保留直到被读取。
+
+### stdin 关闭检测
+
+模块端 `sys.stdin.readline()` 在 stdin 被关闭时返回空字符串 `""`：
+
+```python
+line = sys.stdin.readline()
+if not line:  # stdin 被关闭，Launcher 可能已退出
+    sys.exit(1)
+```
+
+## 环境变量传递
+
+### Launcher 设置的环境变量
+
+| 变量 | 设置时机 | 说明 |
+|------|----------|------|
+| `KITE_PROJECT` | main.py 启动时 | 项目根目录 |
+| `KITE_INSTANCE` | Launcher.__init__ | 实例 ID（PID） |
+| `KITE_INSTANCE_DIR` | Launcher.__init__ | 实例数据目录 |
+| `KITE_WORKSPACE` | Launcher.__init__ | 工作区根目录 |
+| `KITE_KERNEL_PORT` | Phase 1 拿到端口后 | Kernel 端口号 |
+| `KITE_MODULE_DATA` | 启动模块时 | 模块数据目录 |
+| `KITE_INSTANCE_SUFFIX` | Launcher.__init__ | 多实例后缀 |
+| `KITE_CWD` | main.py 启动时 | 原始工作目录 |
+| `KITE_DEBUG` | 用户设置 | 调试模式标志 |
+
+### 模块可用的环境变量
+
+模块进程启动时继承 Launcher 的环境变量。其中：
+
+- `KITE_KERNEL_PORT` — 立即可用，模块可在冷启动阶段就读取
+- `KITE_MODULE_DATA` — 每个模块不同，由 ProcessManager 设置
+- Token — **不通过环境变量**，通过 stdin 传递
+
+## 模块端启动流程
+
+### FastAPI 模块（evol / web）
+
+```
+Python 冷启动 + import 依赖库     ← 与 token 生成并行
+  → 读取 KITE_KERNEL_PORT（环境变量，立即可用）
+  → 绑定端口
+  → 创建 Server 对象（token=""，占位）
+  → sys.stdin.readline() 阻塞等待 token  ← 简单直接
+  → 解析 JSON，检查 error 字段
+  → 设置 server.token
+  → 启动 uvicorn
+  → FastAPI startup 事件:
+      → 连接 Kernel WS → 首条消息 auth
+      → 发布 module.ready
+```
+
+**关键设计决策：** `readline()` 放在 `entry.py main()` 中，在创建 Server 之后、启动 uvicorn 之前。不放在 FastAPI startup 事件中（太"机巧"，容易出错）。
+
+参考代码：`extensions/services/evol/entry.py:main()`
+
+### 轻量模块（watchdog / backup / model_service 等）
+
+```
+Python 冷启动 + import
+  → 读取 KITE_KERNEL_PORT
+  → sys.stdin.readline() 等待 token
+  → 解析 JSON，检查 error
+  → 连接 Kernel WS → 首条消息 auth
+  → 注册 + 发布 module.ready
+  → 进入主循环
+```
+
+### 手动启动模式（计划中）
+
+当模块不通过 Launcher 启动（开发/调试场景），`sys.stdin.isatty()` 返回 `True`：
+
+```python
+if sys.stdin.isatty():
+    # 手动启动模式
+    token = os.environ.get("KITE_MODULE_TOKEN", "")
+    if not token:
+        token = input("请输入配对码: ").strip()
+else:
+    # Launcher 启动模式
+    line = sys.stdin.readline()
+    if not line:
+        sys.exit(1)  # stdin 关闭
+    msg = json.loads(line)
+    if "error" in msg:
+        sys.exit(1)  # Launcher 报告错误
+    token = msg.get("token", "")
+```
+
+**配对码机制：** 配对码就是 token，由 Kernel 生成。手动启动时，用户需要从 Launcher 日志或 Web UI 获取配对码。
+
+### 当前实现状态
+
+**注意：** 当前 evol/web 的实现是在 FastAPI startup 事件中通过 `asyncio.to_thread(sys.stdin.readline)` 读取 token，WS 认证仍使用 URL 参数。计划按本文档设计改造。
+
+## close_stdio 生命周期
+
+### 关闭时机
+
+模块就绪后（收到 `module.ready` 事件），Launcher 调用 `close_stdio(module_name)`。
+
+### 只关闭 stdin
+
+`close_stdio()` **只关闭 stdin，不关闭 stdout**：
+
+- **stdin 关闭原因：** module.ready 后不需要再向模块发送消息
+- **stdout 保持原因：** stdout reader 线程需要继续转发模块日志
+- **Windows 限制：** 在 Windows 上，如果 reader 线程正在 `readline()` 阻塞时关闭 stdout，会导致死锁。stdout 让其自然关闭（进程退出时）
+
+关键代码：`launcher/process_manager.py:close_stdio()`
+
+### stdout reader 线程生命周期
+
+stdout reader 是 daemon 线程，生命周期跟随子进程：
+
+```
+start_module()
+  → 创建 daemon thread: _read_stdout()
+  → 循环 proc.stdout.readline()
+  → 进程退出 → readline() 返回 b"" → 线程自然退出
+```
+
+## 错误处理
+
+### Token 生成超时
+
+```
+Launcher 任务 C:
+  await asyncio.wait_for(_tokens_generated.wait(), timeout=10)
+    → 超时 → 发送错误消息到所有已启动模块
+    → {"error": "token_generation_timeout", "message": "..."}
+    → raise RuntimeError → Launcher 打印红色警告退出
+
+模块端:
+  readline() → 解析 JSON → 检查 "error" 字段
+    → 有 error → 打印错误 → sys.exit(1)
+```
+
+### Token 生成失败（RPC 错误）
+
+```
+Launcher 任务 B:
+  _generate_module_tokens() RPC 返回 error
+    → 设置 _token_error 标志
+    → set _tokens_generated 事件
+
+Launcher 任务 C:
+  检测到 _token_error
+    → 向所有模块发送 {"error": "token_generation_failed", "message": "..."}
+    → 抛异常
+```
+
+### Launcher 异常退出
+
+如果 Launcher 进程退出（崩溃/被杀），stdin 管道断开：
+
+```
+模块端 readline() 返回空字符串 ""
+  → 检测到 stdin 关闭
+  → 打印错误日志
+  → sys.exit(1)
+```
+
+### 模块启动超时
+
+每个模块在 `module.md` 中配置 `launch.timeout`（默认 30s）。超时后的处理分两种场景：
+
+**首次启动（system_startup）：标记跳过，不阻塞系统**
+
+- 不杀进程、不重试
+- 标记 `_timeout_modules[name] = True`
+- 继续走完 Phase 2，正常发 system.ready
+- 理由：启动阶段不应因一个非核心模块卡住整个系统。Watchdog 上线后会接管监控
+
+**运行时重启（Watchdog / 手动）：杀掉 + 上报**
+
+- 超时后杀掉进程
+- 发布 `module.stopped`（exit_type: "timeout"）
+- 由 Watchdog 或用户决定是否再次重启
+- 理由：运行时重启有明确期望，超时意味着出了问题，应快速失败
+
+### Kernel 连接失败
+
+Launcher 连接 Kernel WS 失败时，指数退避重试（0.3s → 0.6s → ... → 5s），最多 10 次。认证失败（4001/4003）不重试，直接退出。
+
+## 关闭流程（三阶段）
+
+关闭触发方式：Ctrl+C、信号（SIGTERM/SIGINT）、按 q 键、RPC 调用 `launcher.shutdown`。
+
+### Phase 1: 关闭 Watchdog
+
+**目的：** 防止 Watchdog 检测到其他模块退出后触发重启。
+
+```
+标记 desired_state = "stopped"
+  → _graceful_stop(watchdog, reason="system_shutdown")
+  → 串行等待完成
+```
+
+### Phase 2: 关闭其他模块
+
+**并发关闭所有非 Kernel 模块：**
+
+```
+标记所有模块 desired_state = "stopped"
+  → asyncio.gather(*(_graceful_stop(name) for name in others))
+```
+
+### Phase 3: 关闭 Kernel
+
+**最后关闭 Kernel，确保事件路由在 Phase 2 中仍可用：**
+
+```
+_graceful_stop(kernel, reason="system_shutdown")
+  → 最终安全网: process_manager.stop_all()
+```
+
+### _graceful_stop 流程
+
+```
+发送 module.shutdown 事件
+  → 等待 shutdown.ack（3s）
+  → 等待 module.exiting（3s）
+  → 等待清理完成（cleanup_timeout，模块声明的清理时间）
+  → 发送 SIGTERM
+  → 等待退出（超时后 force kill）
+  → 发布 module.stopped 事件
+```
+
+### 安全网
+
+- 20s 强制退出线程：如果正常关闭未在 20s 内完成，调用 `os._exit(1)`
+- ESC 键：立即 `os._exit(0)`
+
+## 模块生命周期事件
+
+```
+module.starting   ← Launcher 发布（Phase 2 进入等待时）
+module.ready      ← 模块自己发布（初始化完成）
+module.started    ← Launcher 发布（确认就绪）
+system.ready      ← Launcher 发布（所有模块就绪）
+module.exiting    ← 模块发布（准备退出）
+module.stopped    ← Launcher 发布（确认停止）
+module.shutdown   ← Launcher 发布（请求模块关闭）
+```
+
+**注意：** `module.starting` 不在 Phase 1 任务 C 中发布（此时 WS 可能未就绪），而是在 Phase 2 进入等待时发布。
+
+## 多实例支持
+
+同一工作目录可以运行多个 Launcher 实例：
+
+- 第 1 个实例：`processes.json`, `latest.log`, `crashes.jsonl`
+- 第 N 个实例：`processes~N.json`, `latest~N.log`, `crashes~N.jsonl`
+
+实例号分配：扫描 `processes*.json`，找到最小可用号（已退出的实例号可复用）。
+
+## 残留进程清理
+
+### 清理时机
+
+Phase 1 完成后（Kernel 就绪后），执行本地 + 全局清理。
+
+### 清理逻辑
+
+```
+扫描 processes*.json
+  → 跳过自己的（launcher_pid == my_pid）
+  → 跳过活着的并行实例（launcher_pid alive）
+  → 死掉的 Launcher 的子进程 → 并行清理
+       依赖顺序：Watchdog 先杀 → 中间模块并行杀 → Kernel 最后杀
+       安全校验：PID 存活 + 命令行匹配（防止 PID 复用误杀）
+```
+
+## 参考文件索引
+
+| 文件 | 说明 |
+|------|------|
+| `launcher/entry.py` | Launcher 主逻辑 |
+| `launcher/process_manager.py` | 进程管理（stdin/stdout/生命周期） |
+| `launcher/module_scanner.py` | 模块扫描 |
+| `kernel/entry.py` | Kernel 入口（端口绑定、token 生成） |
+| `kernel/server.py` | Kernel WebSocket 服务器 |
+| `extensions/services/evol/entry.py` | Evol 模块入口 |
+| `extensions/services/evol/server.py` | Evol FastAPI 服务器 |
+| `extensions/services/web/entry.py` | Web 模块入口 |
+| `extensions/services/web/server.py` | Web FastAPI 服务器 |
+| `extensions/services/watchdog/entry.py` | Watchdog 模块入口 |
+| `docs/启动优化方案.md` | 启动优化方案（并行冷启动） |
+| `docs/优雅退出规范.md` | 关闭流程详细规范 |
+| `docs/日志与异常处理规范.md` | 日志目录和格式规范 |