@agentunion/kite 1.5.0 → 1.6.0

package/docs/Launcher/345/220/257/345/212/250/345/231/250/346/226/207/346/241/243.md

@@ -0,0 +1,745 @@
+# Launcher 启动器文档
+
+## 1. 概述
+
+Launcher 是 Kite 框架的入口和控制台，与 `main.py` 运行在同一进程中。它负责整个系统的生命周期管理：启动 Registry、扫描并启动模块、监控子进程状态、提供管理 API、处理优雅退出。
+
+Launcher 的设计原则是**极简、极稳**——代码尽量少，崩溃概率尽量低，因为它是所有模块的父进程。
+
+## 2. 快速开始
+
+### 2.1 启动系统
+
+```bash
+python main.py
+```
+
+启动后你会看到类似输出：
+
+```
+[main] KITE_TOKEN generated (64 chars)
+[launcher] Kite starting...
+[launcher] Project root: /path/to/Kite
+[launcher] Waiting for Registry to report its port...
+[launcher] Registry is ready
+[launcher] API server started on port 52341
+[launcher] Registered self to Registry
+[launcher] Found 3 module(s): event_hub, kernel, webchat
+[launcher] Starting 3 enabled module(s)...
+[launcher] Started event_hub (PID 12345)
+[launcher] Started kernel (PID 12346)
+[launcher] Started webchat (PID 12347)
+[launcher] Entering monitor loop (press Ctrl+C or 'q' to exit)
+```
+
+### 2.2 退出系统
+
+- **Linux/macOS**: `Ctrl+C` 或发送 `SIGTERM`
+- **Windows**: 按 `q` 键或 `Ctrl+C`
+
+退出时 Launcher 会执行优雅退出流程（详见《优雅退出规范》）：
+1. 广播 `module.shutdown` 事件（reason: `system_shutdown`）
+2. 并行等待各模块 ack + ready（总超时 10s）
+3. 超时后强杀未退出的进程
+4. 清空 `processes.json`
+5. 退出
+
+### 2.3 前置依赖
+
+```bash
+pip install fastapi uvicorn httpx
+```
+
+## 3. 启动序列
+
+`main.py` 做两件事：生成 `KITE_TOKEN`（`secrets.token_hex(32)`，64 字符），然后创建 `Launcher` 实例并调用 `run()`。
+
+Launcher 采用 4-Phase 启动序列：
+
+```
+main.py
+  │
+  ├─ 前置：_validate_core_modules()
+  │    检查 core/registry/ 和 core/event_hub/ 存在且包含 entry.py（不通过则 FATAL）
+  │
+  ├─ 前置：cleanup_leftovers()
+  │    读取 processes.json → 检查 PID 存活 + 命令行匹配 → 杀确认的遗留进程
+  │
+  ├─ Phase 1: _phase1_registry()
+  │    ├─ 启动 Registry 子进程，stdin 传入 {"token": "kite_token"}
+  │    ├─ 等待 stdout 结构化消息 {"kite":"port","port":12345}（6s 超时，超时 FATAL）
+  │    ├─ 写入 os.environ["KITE_REGISTRY_PORT"]
+  │    ├─ _start_api_thread()：OS 分配端口，独立线程启动 Launcher FastAPI
+  │    └─ _register_self()：POST /modules 注册 Launcher 的 API 地址
+  │
+  ├─ 扫描 + Token 注册（Phase 1 与 Phase 2 之间）
+  │    ├─ module_scanner.scan()：遍历 core/ 和 extensions/ 下所有 module.md
+  │    └─ _register_module_tokens()：为每个模块生成专属 token → POST /tokens
+  │
+  ├─ Phase 2: _phase2_event_hub()
+  │    ├─ 启动 Event Hub 子进程，stdin 第一行 {"token": "eh_token"}
+  │    ├─ stdin 第二行发送 {"kite":"launcher_ws_token","launcher_ws_token":"xxx"}
+  │    ├─ 等待 stdout 结构化消息 {"kite":"ws_endpoint","ws_endpoint":"ws://..."}（6s 超时）
+  │    ├─ Launcher 用 launcher_ws_token 连接 Event Hub WebSocket
+  │    ├─ Event Hub 验证 launcher_ws_token → 发送 module.ready 事件
+  │    ├─ Launcher 收到 module.ready → 发布 module.started → 断开 Event Hub stdio
+  │    └─ Event Hub 在 Launcher 连入后自动注册到 Registry
+  │
+  ├─ Phase 3: _phase3_registry_ready()
+  │    ├─ Registry 检测到 Event Hub 注册（含 metadata.ws_endpoint）
+  │    ├─ Registry 连接 Event Hub WebSocket
+  │    ├─ Registry 发送 module.ready 事件
+  │    └─ Launcher 收到 → 发布 module.started → 断开 Registry stdio
+  │
+  ├─ Phase 4: _phase4_start_modules()
+  │    ├─ 初始化 desired_state：enabled→running，manual/disabled→stopped
+  │    ├─ 自动启动被依赖的 manual 模块
+  │    └─ 按拓扑序（depends_on）逐个启动，每个模块走 _start_one_module 流程
+  │
+  └─ Post-startup
+       ├─ persist_records()：子进程信息写入 processes.json
+       └─ _monitor_loop()：每秒检查子进程状态，处理崩溃（详见第 6 节）
+```
+
+**模块重启时**：生成新 token → 重新注册到 Registry → 通过 stdin 传给新进程。旧 token 自动失效。
+
+**关键约束**：Registry 和 Event Hub 是串行启动的核心模块（Phase 1→2→3），必须在普通模块之前就绪。Phase 4 中其余模块按 `depends_on` 拓扑序启动，无依赖的模块可并行启动。模块间的运行时依赖通过 Registry 的服务发现机制自行解决。
+
+### 3.1 _register_self() 注册 payload
+
+Launcher 向 Registry `POST /modules` 注册自身，使用 kite_token 认证：
+
+```json
+{
+  "action": "register",
+  "module_id": "launcher",
+  "module_type": "infrastructure",
+  "name": "Launcher",
+  "base_url": "http://127.0.0.1:<api_port>",
+  "health_path": "/launcher/modules",
+  "events_publish": {
+    "module.started": {},
+    "module.stopped": {},
+    "module.state_changed": {}
+  },
+  "events_subscribe": [">"]
+}
+```
+
+Header: `Authorization: Bearer <kite_token>`
+
+## 4. 线程模型
+
+Launcher 进程内有多个线程协作：
+
+| 线程 | 职责 | 类型 |
+|------|------|------|
+| 主线程 | asyncio 事件循环：启动序列 + 监控循环 | 常驻 |
+| API 线程 | 独立运行 uvicorn + FastAPI，提供 Launcher API | daemon |
+| stdout 线程（每个子进程一个） | 逐行读取子进程 stdout，加 `[module_name]` 前缀输出到控制台 | daemon |
+| 键盘监听线程（仅 Windows） | 轮询 `msvcrt.kbhit()`，检测 `q` 键或 Ctrl+C | daemon |
+
+为什么 API 在独立线程？主线程专注进程管理和监控循环，API 线程独立运行保证即使主线程阻塞，管理接口仍可响应。
+
+### 日志汇聚
+
+所有子进程的 stdout/stderr 被重定向到 Launcher 进程。每个子进程有一个 daemon 线程逐行读取输出，加上模块名前缀后打印：
+
+```
+[registry] Server started on port 52340
+[event_hub] WebSocket server ready on port 52341
+[kernel] Connected to Event Hub
+[webchat] Serving static files at http://127.0.0.1:52342
+```
+
+子进程本身没有控制台窗口（Windows 使用 `CREATE_NO_WINDOW` flag）。
+
+## 5. 模块扫描与发现
+
+### 5.1 发现源配置（Discovery）
+
+模块发现由 Launcher 的 `module.md` 中的 `discovery` 字段驱动。支持两种发现源类型，可配置多个，每个独立启用/禁用：
+
+| 字段 | 说明 |
+|------|------|
+| `type` | `scan_dir`（扫描目录）或 `module_list`（模块列表文件） |
+| `path` | 目录或文件路径（相对于项目根目录） |
+| `enabled` | 是否启用（true/false），用开关控制而非删除 |
+| `max_depth` | 仅 `scan_dir`，最大递归深度，默认 2 |
+
+Launcher module.md 示例：
+
+```yaml
+discovery:
+  root:
+    type: scan_dir
+    path: .
+    enabled: true
+  extra:
+    type: module_list
+    path: data/modules.txt
+    enabled: false
+```
+
+**内置扫描**：`core/`（深度 1）和 `extensions/`（深度 2）始终自动扫描，无需配置。`discovery` 字段用于在此基础上添加额外的模块源。
+
+**扫描规则**：
+- `scan_dir`：递归扫描目录下的子目录（最多 `max_depth` 级），找到 `module.md` 即视为模块
+- `module_list`：逐行读取文件，每行一个模块目录路径（支持 `#` 注释）
+- Launcher 自身目录（`core/launcher`）始终跳过
+- **模块名唯一**：以 `module.md` 中的 `name` 字段为准（非目录名），重名模块只加载先发现的，后续跳过并警告
+
+内置扫描覆盖范围：
+
+```
+core/（内置，depth 1）
+  core/registry/module.md            ← ✓
+  core/event_hub/module.md           ← ✓
+  core/launcher/                     ← 跳过（Launcher 自身）
+
+extensions/（内置，depth 2）
+  extensions/services/watchdog/module.md  ← ✓
+```
+
+额外 discovery 源配置的 `scan_dir` 按各自 `max_depth` 独立计算。
+
+多实例场景下，不同实例可通过各自 Launcher 的 `module.md` 指向不同的模块集合。
+
+### 5.2 module.md 格式
+
+```markdown
+---
+name: event_hub
+display_name: "Event Hub"
+version: "1.0"
+type: infrastructure
+state: enabled
+runtime: python
+entry: entry.py
+events:
+  - event.received
+  - event.forwarded
+subscriptions: []
+---
+
+# Event Hub
+
+模块的详细说明文档...
+```
+
+frontmatter 字段说明：
+
+| 字段 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | 是 | — | 模块唯一标识，用于进程管理和 API |
+| `display_name` | 否 | 同 name | 显示名称 |
+| `version` | 否 | `"1.0"` | 版本号 |
+| `type` | 否 | `"infrastructure"` | 模块类型：infrastructure / channel / agent / service / kernel |
+| `state` | 否 | `"enabled"` | 启动状态（见下文） |
+| `runtime` | 否 | `"python"` | 运行时：python / node / binary |
+| `entry` | 否 | `"entry.py"` | 入口文件名（相对于模块目录） |
+| `events` | 否 | `[]` | 本模块会发出的事件类型 |
+| `subscriptions` | 否 | `[]` | 本模块订阅的事件类型 |
+| `preferred_port` | 否 | `0` | 首选端口号。0 表示由 OS 分配；非零则优先尝试该端口，不可用时回退 OS 分配 |
+| `depends_on` | 否 | `[]` | 启动依赖的模块列表，用于拓扑排序 |
+| `monitor` | 否 | `true` | Watchdog 是否监控此模块 |
+| `launch` | 否 | （见下文） | 自定义启动参数，不填则完全保持默认行为 |
+
+#### launch 配置块
+
+`launch` 是可选的嵌套配置，用于自定义模块的启动方式。所有子字段均可选，不填则使用默认值：
+
+```yaml
+launch:
+  cmd: ["python3.11", "-u", "main.py", "--mode", "prod"]
+  env:
+    MY_VAR: "value"
+  cwd: "./subdir"
+  boot_stdin: false
+  timeout: 60
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cmd` | `list[str]` | `[]`（用 runtime+entry） | 完整启动命令，非空时覆盖 `_build_cmd()` 的 runtime+entry 逻辑 |
+| `env` | `dict` | `{}` | 额外环境变量，合并到进程 env（基础 env 始终包含 `PYTHONUTF8=1` 和 `PYTHONUNBUFFERED=1`） |
+| `cwd` | `str` | `""`（用 module_dir） | 工作目录，相对路径基于 module_dir 解析 |
+| `boot_stdin` | `bool` | `true` | 是否通过 stdin 传 boot_info JSON。设为 false 时模块需自行获取 token 和端口 |
+| `timeout` | `int` | `30` | 等待 `module.ready` 事件的超时秒数 |
+
+### 5.3 模块三层状态模型
+
+每个模块有三层状态：
+
+| 层 | 名称 | 值 | 谁写 | 存在哪 |
+|----|------|---|------|--------|
+| 配置状态 | `config_state` | enabled / manual / disabled | owner 修改 module.md | module.md |
+| 期望状态 | `desired_state` | running / stopped | 其他模块通过 Launcher API 改变 | Launcher 内存 |
+| 实际状态 | `actual_state` | running(PID) / stopped | Launcher 观测进程 | Launcher 内存 |
+
+初始化规则：
+- enabled → desired_state 初始为 running
+- manual → desired_state 初始为 stopped
+- disabled → desired_state 固定为 stopped，不可改
+
+core 模块（registry、event_hub、kernel）始终 enabled，不可设为 disabled。
+
+### 5.4 Polyglot 运行时
+
+Launcher 根据 `runtime` 字段选择解释器：
+
+```python
+# runtime: python
+[sys.executable, "entry.py"]
+
+# runtime: node
+["node", "entry.js"]
+
+# runtime: binary
+["./entry"]
+```
+
+如果配置了 `launch.cmd`（非空列表），则直接使用该命令，跳过上述 runtime+entry 逻辑。这允许模块指定自定义解释器版本或额外启动参数。
+
+所有子进程统一通过 **stdin 管道**接收启动信息（一行 JSON，stdin 保持打开直到 module.ready 后断开），除非 `launch.boot_stdin` 设为 `false`：
+
+```json
+{"token": "tok_abc..."}
+```
+
+token 通过 stdin 传递，Registry 端口通过环境变量 `KITE_REGISTRY_PORT` 传递。模块从自己的 `module.md` 读取 `preferred_port` 来决定绑定端口。
+
+## 6. 进程监控与故障恢复
+
+### 6.1 监控循环
+
+Launcher 进入监控循环后，每秒执行一次 `check_exited()`，非阻塞检查所有子进程是否退出。
+
+### 6.2 故障分级处理
+
+| 场景 | 处理策略 |
+|------|----------|
+| core 模块崩溃（registry / event_hub / kernel） | 全量重启：stop_all → 重新执行完整启动序列 |
+| 非 core 模块崩溃 | 记录日志，递增失败计数。由 Watchdog 模块通过 API 决定是否重启 |
+| 同一模块连续失败 3 次 | 标记为 failed，不再自动重启 |
+| 3 个以上模块 failed | Launcher 自身退出（整个 Kite 停止） |
+
+### 6.3 全量重启流程
+
+当 core 模块（Registry / Event Hub）崩溃时触发，按 Phase 1→2→3→4 完整重走：
+
+```
+1. 断开 Launcher 与 Event Hub 的 WebSocket 连接，取消心跳任务
+2. _graceful_shutdown_all() — 广播 module.shutdown，等待超时后强杀所有子进程
+3. 清空失败计数和模块 token
+4. 重新生成 kite_token（旧 token 全部作废）
+5. Phase 1：启动 Registry → stdout 拿 port → 写 KITE_REGISTRY_PORT → 启动 API → 注册自身
+6. 重新扫描模块 + 重新注册模块 token
+7. Phase 2：启动 Event Hub → stdin launcher_ws_token → stdout ws_endpoint → Launcher 连 WS → module.ready → 断开 stdio
+8. Phase 3：Event Hub 注册到 Registry → Registry 连 Event Hub WS → Registry module.ready → 断开 stdio
+9. Phase 4：按拓扑序启动其余 enabled 模块
+10. persist_records() + 恢复心跳 + 恢复监控循环
+```
+
+如果全量重启本身也失败，Launcher 退出。
+
+## 7. 遗留进程清理
+
+每次启动时，Launcher 首先检查上次是否有未正常退出的子进程。
+
+### 7.1 持久化记录
+
+所有子进程信息持久化在 `{KITE_INSTANCE_DIR}/launcher/state/processes.json`：
+
+```json
+[
+  {
+    "name": "registry",
+    "pid": 12345,
+    "cmd": ["python", "/path/to/entry.py"],
+    "module_dir": "/path/to/core/registry",
+    "started_at": 1709020800.0
+  }
+]
+```
+
+注：boot_info（token）通过 stdin 管道传递，不出现在 cmd 中。Registry 端口通过环境变量 `KITE_REGISTRY_PORT` 传递。
+
+### 7.2 清理逻辑
+
+```
+读取 processes.json
+  → 对每条记录：
+     1. 检查 PID 是否存活
+        - Linux/macOS: os.kill(pid, 0)
+        - Windows: tasklist /FI "PID eq {pid}"
+     2. 如果存活，验证命令行匹配
+        - Linux: 读 /proc/{pid}/cmdline
+        - macOS: ps -p {pid} -o command=
+        - Windows: wmic process where ProcessId={pid} get CommandLine
+     3. PID 存活 + 命令行匹配 → 确认是遗留进程，杀掉
+     4. PID 不存在 或 命令行不匹配 → 跳过（PID 已被回收给其他进程）
+  → 清空 processes.json
+```
+
+命令行匹配是关键的安全措施——防止 PID 被操作系统回收后误杀无关进程。
+
+## 8. Launcher API
+
+Launcher 在独立线程运行一个 FastAPI 服务，提供管理接口。其他模块（如 Watchdog）可通过这些接口管理模块生命周期。
+
+### 8.0 权限控制
+
+**所有 `/launcher/*` 接口均需要认证**，包含两层安全机制：
+
+1. **IP 白名单**：仅允许 `127.0.0.1`、`::1`、`localhost` 访问，拒绝远程连接
+   - 非本地访问返回 `403 Forbidden`
+
+2. **Bearer Token 认证**：所有请求必须携带 `Authorization` 头
+   ```
+   Authorization: Bearer {KITE_TOKEN}
+   ```
+   - 缺少或格式错误返回 `401 Unauthorized: Missing or invalid Authorization header`
+   - Token 错误返回 `401 Unauthorized: Invalid token`
+
+**示例请求**：
+```bash
+curl -H "Authorization: Bearer abc123..." http://127.0.0.1:52341/launcher/modules
+```
+
+### 8.1 GET /launcher/modules
+
+列出所有已扫描的模块及其当前状态。
+
+请求：无参数
+
+响应示例：
+```json
+[
+  {
+    "name": "event_hub",
+    "display_name": "Event Hub",
+    "type": "infrastructure",
+    "config_state": "enabled",
+    "desired_state": "running",
+    "actual_state": "running(12345)",
+    "pid": 12345,
+    "monitor": true
+  },
+  {
+    "name": "webchat",
+    "display_name": "WebChat",
+    "type": "channel",
+    "config_state": "manual",
+    "desired_state": "stopped",
+    "actual_state": "stopped",
+    "pid": null,
+    "monitor": true
+  }
+]
+```
+
+### 8.2 POST /launcher/modules/{name}/start
+
+启动指定模块。模块必须处于 `enabled` 或 `manual` 状态。
+
+请求：无 body
+
+响应：
+```json
+{"status": "started", "name": "webchat"}
+```
+
+错误码：
+- `404` — 模块不存在
+- `403` — 模块处于 disabled 状态
+- `500` — 启动失败
+
+### 8.3 POST /launcher/modules/{name}/stop
+
+停止指定模块。通过优雅退出流程停止（详见《优雅退出规范》）。
+
+请求 body（可选）：
+```json
+{"reason": "stop_requested"}
+```
+
+`reason` 取值：`stop_requested`（默认）、`hot_update`、`restart`、`resource_critical`
+
+响应：
+```json
+{"status": "stopped", "name": "webchat"}
+```
+
+错误码：
+- `404` — 模块不存在
+
+### 8.4 POST /launcher/modules/{name}/restart
+
+重启指定模块（stop + start）。
+
+请求 body（可选）：
+```json
+{"reason": "restart"}
+```
+
+响应：
+```json
+{"status": "restarted", "name": "webchat"}
+```
+
+错误码：
+- `404` — 模块不存在
+- `403` — 模块处于 disabled 状态
+
+### 8.5 POST /launcher/rescan
+
+重新扫描模块目录，发现新增或移除的模块。不影响已运行的模块。
+
+请求：无 body
+
+响应：
+```json
+{"added": ["new_module"], "removed": ["old_module"], "total": 5}
+```
+
+### 8.6 PUT /launcher/modules/{name}/state
+
+修改模块的 state 字段，同时写入该模块的 `module.md` 文件。
+
+请求 body：
+```json
+{"state": "manual"}
+```
+
+响应：
+```json
+{
+  "name": "webchat",
+  "old_state": "enabled",
+  "new_state": "manual"
+}
+```
+
+错误码：
+- `404` — 模块不存在
+- `400` — state 值无效（必须是 enabled / manual / disabled）
+- `403` — core 模块不允许设为 disabled
+
+### 8.7 POST /launcher/shutdown
+
+关闭整个 Kite 系统，等价于 `Ctrl+C`。触发完整的优雅退出流程。
+
+请求 body（可选）：
+```json
+{"reason": "api_request"}
+```
+
+响应：
+```json
+{"status": "shutting_down", "reason": "api_request"}
+```
+
+**注意**：
+- 此接口会立即触发系统关闭，Launcher 进程将在优雅退出完成后终止
+- 响应返回后，连接可能会立即断开
+- 适用场景：远程管理、自动化部署、容器编排
+
+## 9. 跨平台行为
+
+Launcher 在 Windows、Linux 和 macOS 上行为一致，但底层实现有差异：
+
+| 功能 | Linux | macOS | Windows |
+|------|-------|-------|---------|
+| 进程存活检查 | `os.kill(pid, 0)` | `os.kill(pid, 0)` | `tasklist /FI "PID eq {pid}"` |
+| 命令行匹配 | 读 `/proc/{pid}/cmdline` | `ps -p {pid} -o command=` | `wmic process ... get CommandLine` |
+| 终止进程 | `SIGTERM` → `SIGKILL` | `SIGTERM` → `SIGKILL` | `proc.terminate()` → `proc.kill()` |
+| 强杀进程 | `os.kill(pid, SIGKILL)` | `os.kill(pid, SIGKILL)` | `taskkill /F /PID {pid}` |
+| 子进程窗口 | 无（默认行为） | 无（默认行为） | `CREATE_NO_WINDOW` flag |
+| 退出信号 | `SIGTERM` / `SIGINT` handler | `SIGTERM` / `SIGINT` handler | daemon 线程轮询 `msvcrt.kbhit()` |
+| 最终退出 | 正常 return | 正常 return | `os._exit(0)`（避免 Windows 线程清理卡死） |
+
+macOS 与 Linux 的主要区别在于命令行匹配：macOS 没有 `/proc` 文件系统，改用 `ps` 命令获取进程命令行。其余行为与 Linux 一致。
+
+## 10. 端口分配
+
+所有模块默认使用 **OS 动态分配端口**（bind port 0），不预设固定端口号：
+
+```
+Registry:     OS 分配 → 启动后通过 stdout 回传端口 → Launcher 写入 KITE_REGISTRY_PORT 环境变量
+Launcher API: OS 分配（_get_free_port()，bind port 0）
+其他模块:     OS 分配（各自绑定后向 Registry 注册 base_url）
+```
+
+**Registry 端口发现流程**：
+1. Launcher 启动 Registry 子进程（不指定端口）
+2. Registry 绑定 port 0，OS 分配实际端口
+3. Registry 通过 stdout 发送端口消息
+4. Launcher 读取 stdout 获取端口（6s 超时）
+5. Launcher 写入 `KITE_REGISTRY_PORT` 环境变量，后续子进程自动继承
+
+**Launcher API 端口分配**：`_get_free_port()` bind port 0 获取 OS 分配的端口，立即用于 uvicorn。
+
+`module.md` 中可选声明 `preferred_port`，模块自行从 module.md 读取，模块自行尝试绑定，绑定失败则回退 OS 分配。
+
+## 11. 安全机制
+
+### KITE_TOKEN + Per-Module Token + stdin 管道
+
+系统使用两层 token 实现身份认证，所有 token 通过 stdin pipe 传递（不使用环境变量）。
+
+**第一层：KITE_TOKEN（全局）**
+
+`main.py` 每次启动生成一个随机 token（`secrets.token_hex(32)`，64 字符）。Launcher 启动 Registry 时，通过 stdin 将此 token 写入 Registry 子进程。只有 Launcher 持有此 token，用于调用 Registry 的特权接口（如 `POST /tokens`）。
+
+**第二层：Per-module Token（模块级）**
+
+模块扫描完成后，Launcher 为每个模块生成独立的 token（同样 64 字符 hex），通过 `POST /tokens` 批量注册到 Registry。启动模块时，Launcher 通过 stdin 将该模块自己的 token 传给子进程。模块用自己的 token 向 Registry 注册，Registry 验证 token 并识别调用者身份。
+
+**stdin boot_info 格式**
+
+Launcher 启动子进程时，向其 stdin 写入一行 JSON（stdin 保持打开直到 module.ready 后断开）：
+
+```json
+{"token": "<module_token>"}
+```
+
+子进程启动后从 stdin 读取这行 JSON，获取自己的 token。Registry 端口从环境变量 `KITE_REGISTRY_PORT` 读取，首选端口从自己的 `module.md` 读取。
+
+**安全特性**：
+- 每个模块只知道自己的 token，无法冒充其他模块
+- kite_token 只有 Launcher 和 Registry 知道，模块无法调用特权接口
+- token 每次启动都不同，不持久化
+- 只在本机 `127.0.0.1` 通信，不暴露到网络
+- token 通过 stdin pipe 传递，不出现在进程命令行或环境变量中
+- 模块重启时生成新 token，旧 token 自动失效
+
+## 12. 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| core 模块目录不存在（registry / event_hub） | `sys.exit(1)`，FATAL（启动前校验） |
+| core 模块 module.md 缺失或解析失败 | `sys.exit(1)`，FATAL（启动前校验） |
+| Registry 启动失败 | 抛 `RuntimeError`，Launcher 退出 |
+| Registry 6s 内未回报端口 | 抛 `RuntimeError`，Launcher 退出 |
+| Event Hub 6s 内未回报 ws_endpoint | 抛 `RuntimeError`，Launcher 退出 |
+| Registry / Event Hub 运行中崩溃 | core 模块崩溃 → 全量重启 |
+| 普通模块 module.md 解析失败 | 跳过该模块，打印 WARNING，继续扫描 |
+| module.md 缺少 name 字段 | 跳过该模块，打印 WARNING |
+| processes.json 损坏 | 跳过遗留清理，打印 WARNING |
+| 端口全部被占用 | 抛 `RuntimeError`，Launcher 退出 |
+| 子进程启动失败 | 打印 ERROR，返回 False，不影响其他模块 |
+| Launcher 向 Registry 注册失败 | 打印 WARNING，继续运行（非致命） |
+
+## 13. 文件结构
+
+```
+core/launcher/
+├── entry.py              ← Launcher 类主逻辑（~900 行）
+├── process_manager.py    ← 子进程生命周期管理（~330 行）
+├── module_scanner.py     ← 扫描 module.md、解析 frontmatter（~170 行）
+├── module.md             ← Launcher 自身的模块描述
+└── __init__.py
+
+运行时状态文件（自动生成）：
+{KITE_INSTANCE_DIR}/launcher/state/
+├── processes.json        ← 子进程记录（每次启动覆盖）
+└── lifecycle.jsonl       ← 启动/停止日志（每次启动清空）
+```
+
+## 14. 核心类参考
+
+### 14.1 Launcher（entry.py）
+
+系统入口类，协调所有组件。
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `kite_token` | `str` | 本次启动的全局认证 token（Launcher 信任根） |
+| `_module_tokens` | `dict[str, str]` | 各模块专属 token 映射（module_name → token） |
+| `project_root` | `str` | Kite 项目根目录绝对路径（即 `KITE_PROJECT` 环境变量） |
+| `registry_port` | `int` | Registry 实际绑定的端口 |
+| `api_port` | `int` | Launcher API 实际绑定的端口 |
+| `modules` | `dict[str, ModuleInfo]` | 扫描到的所有模块 |
+| `_desired_states` | `dict[str, str]` | 各模块期望状态（"running" / "stopped"） |
+| `process_manager` | `ProcessManager` | 子进程管理器 |
+| `module_scanner` | `ModuleScanner` | 模块扫描器 |
+
+| 方法 | 说明 |
+|------|------|
+| `run()` | 同步入口，设置信号处理，运行 asyncio 主循环 |
+| `_async_main()` | 完整启动序列（11 步） |
+| `_start_registry()` | 启动 Registry 子进程并等待就绪（stdout port 消息） |
+| `_register_self()` | 用 kite_token 向 Registry 注册 Launcher |
+| `_register_module_tokens()` | 为各模块生成 token 并注册映射表到 Registry |
+| `_start_enabled_modules()` | 按拓扑序启动所有 desired_state=running 的模块（stdin 传 token） |
+| `_start_one_module(info)` | 启动单个模块：发布 starting 事件 → 启动进程 → 等待 ready 事件 |
+| `_topo_sort(modules)` | 按 depends_on 拓扑排序，检测循环依赖 |
+| `_start_api_thread()` | 在独立线程启动 API 服务器 |
+| `_connect_event_hub()` | 发现 Event Hub WebSocket 端点并启动后台客户端 |
+| `_monitor_loop()` | 每秒检查子进程状态 |
+| `_graceful_stop(name, reason, timeout)` | 优雅停止：发 shutdown 事件 → 等 ack → 等 ready → kill |
+| `_graceful_shutdown_all()` | 广播 shutdown 事件到所有运行中模块 |
+| `_full_restart()` | core 崩溃时的全量重启 |
+| `_final_cleanup()` | 退出时清理所有进程 |
+| `_get_free_port()` | 获取 OS 分配的可用端口（bind port 0） |
+
+### 14.2 ProcessManager（process_manager.py）
+
+子进程生命周期管理器。
+
+| 方法 | 说明 |
+|------|------|
+| `cleanup_leftovers()` | 读 processes.json，杀确认的遗留进程 |
+| `start_module(info, boot_info)` | 根据 runtime 构建命令，启动子进程，通过 stdin 写入 boot_info JSON，启动 stdout 读取线程 |
+| `stop_module(name, timeout=5)` | 底层停止：terminate → wait → 超时 force kill。Launcher 层通过 `_graceful_stop(name, reason, timeout)` 封装，先发 shutdown 事件等 ack/ready 再调用此方法 |
+| `stop_all(timeout=10)` | 批量 terminate → 等待 → 强杀未退出的 |
+| `persist_records()` | 写 processes.json |
+| `check_exited()` | 非阻塞检查已退出的子进程，返回 `[(name, returncode)]` |
+| `is_running(name)` | 检查模块是否在运行 |
+| `get_record(name)` | 获取模块的 ProcessRecord |
+
+### 14.3 ModuleInfo（module_scanner.py）
+
+模块信息数据类，从 module.md frontmatter 解析而来。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | `str` | 模块唯一标识 |
+| `display_name` | `str` | 显示名称 |
+| `version` | `str` | 版本号 |
+| `type` | `str` | 模块类型 |
+| `state` | `str` | 配置状态（config_state） |
+| `runtime` | `str` | 运行时（python / node / binary） |
+| `entry` | `str` | 入口文件名 |
+| `events` | `list` | 发出的事件类型 |
+| `subscriptions` | `list` | 订阅的事件类型 |
+| `preferred_port` | `int` | 首选端口号（0 = OS 分配） |
+| `depends_on` | `list` | 启动依赖的模块名列表 |
+| `monitor` | `bool` | Watchdog 是否监控此模块 |
+| `module_dir` | `str` | 模块目录绝对路径 |
+| `launch` | `LaunchConfig` | 启动配置（cmd / env / cwd / boot_stdin / timeout） |
+
+方法：`is_core(project_root)` — 判断是否为 core 模块（模块目录在 `{KITE_PROJECT}/core/` 下）。（module_scanner.py）
+
+| 方法 | 说明 |
+|------|------|
+| `scan()` | 遍历 core/ 和 extensions/，返回 `dict[name, ModuleInfo]` |
+
+frontmatter 解析器是内置的轻量实现（`_parse_frontmatter`），不依赖 `python-frontmatter` 库。支持：
+- 简单 key-value（`name: xxx`）
+- 列表（`- item` 缩进格式）
+- 空列表（`[]` 内联格式）
+- 引号值（自动去除）
+
+### 14.5 ProcessRecord（process_manager.py）
+
+子进程记录数据类，持久化到 processes.json。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | `str` | 模块名 |
+| `pid` | `int` | 进程 ID |
+| `cmd` | `list` | 启动命令（用于遗留清理时的命令行匹配） |
+| `module_dir` | `str` | 模块目录 |
+| `started_at` | `float` | 启动时间戳 |