@agentunion/kite 1.5.0 → 1.6.1

package/docs//344/274/230/351/233/205/351/200/200/345/207/272/350/247/204/350/214/203.md

@@ -0,0 +1,362 @@
+# 优雅退出规范
+
+## 1. 概述
+
+定义 Kite 框架中模块停止的标准流程。通过事件通知机制，让模块有机会完成清理工作后再退出，避免数据丢失和资源泄漏。
+
+所有模块**建议**实现本规范。不实现的模块仍可运行，但会被直接终止（无清理机会）。
+
+## 2. 能力声明
+
+模块通过 `module.ready` 事件的 `data.graceful_shutdown` 字段声明是否支持优雅退出：
+
+```json
+{
+  "event": "module.ready",
+  "source": "webchat",
+  "data": {
+    "module_id": "webchat",
+    "graceful_shutdown": true
+  }
+}
+```
+
+- `graceful_shutdown: true` — 模块实现了本规范，Launcher 停止时会走事件通知流程
+- 不传或 `false` — 模块不支持优雅退出，Launcher 直接 terminate/kill
+
+Launcher 在收到 `module.ready` 时记录该标记，后续停止操作据此决定走优雅流程还是直杀。
+
+## 3. 事件定义
+
+| 事件 | 方向 | 说明 |
+|------|------|------|
+| `module.shutdown` | Launcher → 模块 | 通知模块准备退出 |
+| `module.shutdown.ack` | 模块 → Launcher | 确认收到，附带预估清理时间 |
+| `module.shutdown.ready` | 模块 → Launcher | 清理完成，可安全终止 |
+
+### 3.1 module.shutdown
+
+```json
+{
+  "event": "module.shutdown",
+  "source": "launcher",
+  "data": {
+    "module_id": "webchat",
+    "reason": "stop_requested",
+    "restart": "auto"
+  }
+}
+```
+
+`reason` 取值：
+- `stop_requested` — 手动停止（API 调用）
+- `system_shutdown` — 系统退出（Ctrl+C / SIGTERM）
+- `hot_update` — 热更新
+- `restart` — 重启
+- `resource_critical` — 资源异常（Watchdog 触发）
+
+`restart` 取值：
+- `"yes"` — 明确要求重启
+- `"no"` — 明确不重启
+- `"auto"` — 继承注册中心配置
+
+### 3.2 module.shutdown.ack
+
+```json
+{
+  "event": "module.shutdown.ack",
+  "source": "webchat",
+  "data": {
+    "module_id": "webchat"
+  }
+}
+```
+
+模块收到 shutdown 后立即发送，确认收到关闭请求。
+
+### 3.3 module.shutdown.ready
+
+```json
+{
+  "event": "module.shutdown.ready",
+  "source": "webchat",
+  "data": {
+    "module_id": "webchat"
+  }
+}
+```
+
+模块发出此事件后应立即退出进程（exit code 0）。
+
+## 4. 停止流程
+
+### 4.1 单模块停止
+
+```
+Launcher 要停止模块 X：
+  │
+  ├─ Step 0: 检查 X 是否声明了 graceful_shutdown
+  │    ├─ 未声明 → proc.terminate()，等 0.3s，超时 proc.kill()，结束
+  │    └─ 已声明 → 进入 Step 1
+  │
+  ├─ Step 1: 通过 Kernel 发送 module.shutdown 事件
+  │    target: 模块 X
+  │    source: "launcher"
+  │
+  ├─ Step 2: 等待 module.shutdown.ack（超时 3s）
+  │    ├─ 收到 ack → 进入 Step 3
+  │    └─ 未收到 ack（3s 超时）→ 杀死，发 stopped，结束
+  │
+  ├─ Step 3: 等待 module.exiting（超时 3s）
+  │    ├─ 收到 exiting → 进入 Step 4
+  │    └─ 未收到 exiting（3s 超时）→ 杀死，发 stopped，结束
+  │
+  ├─ Step 4: 等待 module.shutdown.ready（超时 = exiting.timeout，默认 5s，最多 30s）
+  │    ├─ 收到 ready → 杀死，发 stopped，结束
+  │    └─ 超时 → 杀死，发 stopped，结束
+  │
+  └─ 注：所有"杀死"操作均为 proc.terminate() → 等 0.3s → 超时则 proc.kill()
+```
+
+**模块端处理流程**:
+```
+模块收到 module.shutdown：
+  │
+  ├─ Step 1: 立即发送 module.shutdown.ack（确认收到）
+  │    data: {"module_id": "xxx"}
+  │
+  ├─ Step 2: 发送 module.exiting（开始清理）
+  │    data: {
+  │      "module_id": "xxx",
+  │      "type": "passive",
+  │      "reason": "响应 shutdown",
+  │      "restart": "auto",
+  │      "action": "none",
+  │      "timeout": 5.0
+  │    }
+  │
+  ├─ Step 3: 执行清理工作
+  │    - 停止接受新请求
+  │    - 完成进行中的请求
+  │    - flush 缓冲区
+  │    - 关闭连接
+  │    - 持久化状态
+  │
+  ├─ Step 4: 发送 module.shutdown.ready（清理完成）
+  │    data: {"module_id": "xxx"}
+  │
+  └─ Step 5: 退出进程（exit code 0）
+```
+
+### 4.2 全量退出（Launcher 自身退出）
+
+```
+Launcher 收到 Ctrl+C / SIGTERM：
+  │
+  ├─ 设置 _system_shutting_down = True
+  │
+  ├─ 发送 Launcher 自己的 module.exiting 事件
+  │
+  ├─ 将运行中的模块分为三组：
+  │    watchdog: Watchdog 模块
+  │    graceful: 声明了 graceful_shutdown 的模块（不含 Kernel）
+  │    non_graceful: 未声明的模块
+  │    kernel: Kernel 模块（延迟到最后）
+  │
+  ├─ Phase 1: 先通知 Watchdog 退出
+  │    ├─ 发送 module.shutdown(reason=system_shutdown, restart=false)
+  │    ├─ 等待 0.2 秒（确保事件送达，不等待进程退出）
+  │    └─ 目的：防止 Watchdog 监控到其他模块退出后触发重启
+  │
+  ├─ Phase 2: 通知其他模块退出
+  │    ├─ 向 graceful 组发送 module.shutdown 事件
+  │    ├─ 立即 terminate non_graceful 组的模块
+  │    ├─ 等待所有模块退出（最多 5s，包括 Watchdog）
+  │    └─ 超时后强杀未退出的进程
+  │
+  ├─ Phase 3: 最后通知 Kernel 退出
+  │    ├─ 设置 _desired_states["kernel"] = "stopped"
+  │    ├─ 调用 _graceful_stop("kernel", reason=system_shutdown)
+  │    ├─ Kernel 收到 shutdown 事件（在 RPC 处理器中截获）
+  │    ├─ Kernel 发送 ack → exiting → 执行清理 → ready → 退出
+  │    └─ 目的：保证事件路由畅通，所有其他模块的退出事件都能送达
+  │
+  └─ 清空 processes.json，退出
+```
+
+**Kernel 的特殊性**：
+- Kernel 遵循标准优雅退出流程（ack → exiting → ready），但必须最后退出
+- Kernel 没有 WebSocket 连接到自己，事件通过 RPC 处理器 `_event_publish` 截获
+- Kernel 在发送 `shutdown.ready` 后触发 uvicorn 关闭，自行退出（exit code 0）
+
+## 5. 模块实现规范
+
+### 5.1 必须实现
+
+- 在 `module.ready` 事件的 data 中声明 `"graceful_shutdown": true`
+- 订阅 `module.shutdown` 事件
+- 收到 shutdown 事件时验证 `source == "launcher"`
+- **立即回复 `module.shutdown.ack`**（⚠️ 必须在开始清理之前发送）
+- 发送 `module.exiting` 表示开始清理，包含 `timeout` 字段（清理超时，0-30秒）
+- 在 timeout 时间内完成清理
+- 清理完成后发 `module.shutdown.ready`
+- 发完 ready 后立即退出进程（exit code 0）
+
+**⚠️ 重要**: `ack` 必须在 `exiting` 之前发送，顺序为: **ack → exiting → cleanup → ready → exit**
+
+### 5.2 清理工作内容
+
+- 停止接受新请求
+- 完成进行中的请求（有超时保护）
+- flush 缓冲区（outbox、日志等）
+- 关闭网络连接（WebSocket、HTTP）
+- 持久化必要状态
+- 释放系统资源（文件句柄、临时文件等）
+
+### 5.3 退出码约定
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 正常退出（收到 shutdown 后主动退出） |
+| 1 | 启动失败 |
+| 非 0 | 异常退出（崩溃） |
+
+## 6. 向后兼容
+
+未实现本规范的模块（旧模块或简单模块）：
+- 不会在 `module.ready` 中声明 `graceful_shutdown`
+- Launcher 停止时直接 `proc.terminate()` → 等 0.3s → `proc.kill()`
+- 不会发送 `module.shutdown` 事件，不浪费 3s ack 超时
+- 行为与当前一致，不会出错
+
+## 7. SIGTERM 说明
+
+`SIGTERM`（Signal Terminate，编号 15）是 Unix/Linux 的进程终止信号。
+
+- `proc.terminate()` 在 Linux/macOS 上发送 SIGTERM，进程可捕获并做清理
+- `proc.kill()` 发送 SIGKILL（编号 9），进程无法捕获，立即终止
+- Windows 没有 SIGTERM，`proc.terminate()` 调用 `TerminateProcess`，效果类似 SIGKILL
+
+本规范通过事件机制替代 SIGTERM 实现优雅退出，跨平台行为一致。
+
+## 8. 模块主动退出（module.exiting）
+
+当模块自身决定退出（而非被 Launcher 要求停止）时，应在退出前发送 `module.exiting` 事件，告知 Launcher 这是一次有意退出，避免被当作崩溃处理。
+
+### 8.1 事件定义
+
+```json
+{
+  "event": "module.exiting",
+  "source": "event_hub_bench",
+  "data": {
+    "module_id": "event_hub_bench",
+    "type": "active",
+    "reason": "benchmarks complete",
+    "restart": "no",
+    "action": "none",
+    "timeout": 5.0,
+    "restart_delay": 0
+  }
+}
+```
+
+**字段说明**：
+- `type`: `"active"`（主动退出）或 `"passive"`（响应 shutdown）
+- `reason`: 退出原因描述
+- `restart`: `"yes"` | `"no"` | `"auto"`（继承 shutdown 或注册中心配置）
+- `action`: `"none"` | `"restart"` | `"restart_delay"`
+- `timeout`: 清理超时时间（0-30秒）
+- `restart_delay`: 延迟重启时间（仅 action="restart_delay" 时有效）
+
+### 8.2 action 取值
+
+| 值 | 含义 |
+|----|------|
+| `"none"` | 不重启（默认）。Launcher 设 desired_state="stopped"，不计入 fail_count |
+| `"restart"` | 请求立即重启 |
+| `"restart_delay"` | 延迟重启（默认 5s） |
+
+### 8.3 处理流程
+
+```
+模块主动退出：
+  │
+  ├─ Step 1: 模块发送 module.exiting 事件
+  │    data: {
+  │      "type": "active",
+  │      "reason": "任务完成",
+  │      "restart": "no",
+  │      "action": "none",
+  │      "timeout": 5.0
+  │    }
+  │
+  ├─ Step 2: Launcher 收到 exiting，启动清理超时倒计时
+  │
+  ├─ Step 3: 模块执行清理工作
+  │
+  ├─ Step 4: 模块发送 module.shutdown.ready
+  │
+  ├─ Step 5: 模块退出进程（exit code 0）
+  │
+  ├─ Step 6: 监控循环检测到退出，发送 module.stopped 事件
+  │    data: {
+  │      "exit_type": "graceful",
+  │      "restart": false,  # 根据继承链解析
+  │      "ready_received": true
+  │    }
+  │
+  └─ Step 7: Watchdog 收到 stopped，根据 restart 字段决策
+```
+
+**超时处理**：
+- 如果模块在 timeout 时间内未退出，Launcher 主动杀死进程
+- 监控循环发送 stopped 事件，`exit_type="timeout"`
+
+### 8.4 适用场景
+
+- 一次性任务模块（如 benchmark）完成后正常退出
+- 模块检测到缺少必要条件（如环境变量未设置）主动退出
+- 模块自我升级或配置变更后需要重启
+
+### 8.5 注意事项
+
+- 模块应在 `module.exiting` 事件成功发送后再退出进程
+- 如果模块无法连接 Kernel（如 Kernel 尚未就绪），则无法发送事件，退回旧的崩溃重试逻辑
+- `module.exiting` 与 `module.shutdown` 是互补的：前者是模块→Launcher 方向，后者是 Launcher→模块 方向
+
+## 9. 重启决策继承链
+
+**配置文件** → **注册中心** → **shutdown** → **exiting** → **stopped**
+
+1. 模块配置文件定义 `auto_restart: true/false`
+2. 模块注册时上传到注册中心
+3. Launcher 发送 shutdown 时指定 `restart="yes"|"no"|"auto"`
+   - `"auto"` 继承注册中心配置
+4. 模块发送 exiting 时指定 `restart="yes"|"no"|"auto"`
+   - `"auto"` 继承 shutdown（如果有），否则继承注册中心
+5. Launcher 发送 stopped 时解析为明确的 `restart=true/false`
+6. Watchdog 根据 stopped 中的 `restart` 字段决策是否重启
+
+## 10. Launcher / Watchdog 职责划分
+
+| 职责 | Launcher（执行者） | Watchdog（决策者） |
+|------|-------------------|-------------------|
+| 检测进程退出 | `_monitor_loop` 检测 `check_exited()` | — |
+| 发布 `module.stopped` | 主动杀死时立即发送；监控循环检测时根据标记决定是否发送 | 订阅此事件 |
+| 核心模块崩溃 | 直接触发 `_full_restart()` | 不介入 |
+| Watchdog 崩溃 | 直接重启（最多 3 次） | — |
+| 非核心模块崩溃重启 | 不做决策，仅发事件 | 收到 `module.stopped` 后根据 `restart` 字段决策 |
+| `module.exiting` 处理 | 记录状态，启动清理超时 | 不处理 |
+| `module.ready` 跟踪 | 记录 `_graceful_modules`（Phase 1-3 模块） | 订阅并记录（Phase 4+ 模块） |
+| 优雅停止（单模块） | `_graceful_stop()` 发 `module.shutdown` → 等 ack → 等 exiting → 等 ready → 杀死 | 不介入 |
+| 系统退出 | `_graceful_shutdown_all()` → 设 `_system_shutting_down` | 收到 `module.shutdown(system_shutdown)` → 设 `_system_shutting_down`，不触发重启 |
+| 健康检查 | — | 定期 `/health` 检查，不健康时通过 Launcher API 重启 |
+| 资源监控 | — | CPU/内存监控，异常时通过 Launcher API 重启 |
+
+### 10.1 设计原则
+
+- **Launcher 只保活 Watchdog**：Launcher 在 `_monitor_loop` 中仅对 Watchdog 做重启逻辑（本地 `watchdog_fail_count`），其他非核心模块的重启全部委托给 Watchdog
+- **Watchdog 提前启动**：早于其他扩展模块，以便接收所有模块的 `module.ready` 事件
+- **Kernel 支持优雅退出**：Kernel 在 Watchdog 之前启动，Watchdog 的 `_graceful_modules` 中默认为 `True`。Kernel 通过标准事件流程退出（ack → exiting → ready），但事件截获机制特殊（在 RPC 处理器中截获，因为 Kernel 自身没有 WebSocket 连接）
+- **三阶段系统退出**：Launcher 退出时分三阶段关闭模块：① Watchdog（防止误重启）→ ② 其他模块 → ③ Kernel（保证事件路由畅通）

package/docs//344/276/235/350/265/226/347/256/241/347/220/206/350/257/264/346/230/216.md

@@ -0,0 +1,141 @@
+# Kite 依赖管理说明
+
+## 概述
+
+Kite 现在支持自动依赖检查和安装。当你启动 Kite 时，系统会：
+
+1. 检查 `requirements.txt` 中的所有依赖
+2. 如果有缺失或版本不符的包，自动安装到用户级虚拟环境
+3. 虚拟环境路径：`~/.kite/venv/`
+
+## 虚拟环境路径
+
+- **Windows**: `C:\Users\{用户名}\.kite\venv\`
+- **Linux/macOS**: `~/.kite/venv/`
+
+所有依赖都安装在这个虚拟环境中，不会污染系统 Python 环境。
+
+## 使用方法
+
+### 正常启动（推荐）
+
+直接运行 `main.py`，系统会自动处理依赖：
+
+```bash
+python main.py
+```
+
+首次启动时，如果虚拟环境不存在，会自动创建并安装所有依赖。
+
+### 手动安装依赖
+
+如果自动安装失败，可以手动安装：
+
+```bash
+# 方法 1：使用系统 pip（不推荐）
+pip install -r requirements.txt
+
+# 方法 2：使用虚拟环境 pip（推荐）
+# Windows
+C:\Users\{用户名}\.kite\venv\Scripts\pip.exe install -r requirements.txt
+
+# Linux/macOS
+~/.kite/venv/bin/pip install -r requirements.txt
+```
+
+### 测试依赖检查
+
+运行测试脚本验证功能：
+
+```bash
+python test_dependency_checker.py
+```
+
+## 工作原理
+
+### 1. 虚拟环境管理
+
+- 启动时检查 `~/.kite/venv/` 是否存在
+- 不存在则自动创建虚拟环境
+- 将虚拟环境的 `site-packages` 添加到 `sys.path`
+
+### 2. 依赖检查
+
+- 解析 `requirements.txt`
+- 逐个检查包是否安装且版本满足要求
+- 支持 `>=` 和 `==` 版本约束
+
+### 3. 自动安装
+
+- 使用虚拟环境的 pip 安装缺失的包
+- 安装完成后继续启动 Kite
+- 无需重启
+
+## 添加新依赖
+
+如果你的模块需要新的第三方库：
+
+1. 编辑 `requirements.txt`，添加依赖：
+   ```
+   new-package>=1.0.0
+   ```
+
+2. 重启 Kite，系统会自动安装新依赖
+
+## 跨平台兼容性
+
+依赖检查模块完全跨平台兼容：
+
+- ✅ Windows
+- ✅ Linux
+- ✅ macOS
+
+虚拟环境结构在不同平台上略有差异，但代码会自动处理。
+
+## 故障排查
+
+### 问题：虚拟环境创建失败
+
+**原因**：系统 Python 没有 `venv` 模块
+
+**解决**：
+```bash
+# Ubuntu/Debian
+sudo apt install python3-venv
+
+# 其他系统
+pip install virtualenv
+```
+
+### 问题：依赖安装失败
+
+**原因**：网络问题或 pip 版本过旧
+
+**解决**：
+```bash
+# 升级 pip
+python -m pip install --upgrade pip
+
+# 使用国内镜像
+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+### 问题：import 时找不到包
+
+**原因**：虚拟环境未正确激活
+
+**解决**：检查 `main.py` 是否在依赖检查后才 import 其他模块
+
+## 文件说明
+
+- `requirements.txt` — 依赖列表
+- `core/dependency_checker.py` — 依赖检查和安装模块
+- `test_dependency_checker.py` — 测试脚本
+- `main.py` — 启动入口（已集成依赖检查）
+
+## 注意事项
+
+1. **首次启动较慢**：需要创建虚拟环境和安装依赖，可能需要几分钟
+2. **网络要求**：安装依赖需要联网访问 PyPI
+3. **磁盘空间**：虚拟环境大约占用 100-200 MB
+4. **权限要求**：需要在 `~/.kite/` 目录下创建文件的权限