@agentunion/kite 1.4.0 → 1.6.0

package/docs/Relay-Token/346/235/203/351/231/220/351/205/215/347/275/256/351/252/214/350/257/201.md

@@ -0,0 +1,113 @@
+# Relay Token 权限配置验证
+
+## 配置文件
+
+### 1. Launcher 白名单配置
+**文件：** `launcher/module.md`
+
+```yaml
+relay:
+  modules:
+    - evol  # Evol 模块有权限申请 token
+    - web   # Web 模块有权限申请 token
+  token_limits:
+    evol: 100  # Evol 最多申请 100 个 token
+    web: 50    # Web 最多申请 50 个 token
+```
+
+### 2. Evol Relay 配置
+**文件：** `extensions/services/evol/relay_config.json5`
+
+```json5
+{
+  relay: {
+    base_module_id: "evol-client",  // 生成的 module_id 格式: evol-client-{suffix}
+    reconnect_timeout: 6,
+    endpoint: "/ws/relay"
+  }
+}
+```
+
+## 权限检查逻辑
+
+### 命名规范
+- **Evol 模块**申请的 token 必须以 `evol-client-` 开头
+- **Web 模块**申请的 token 必须以 `web-client-` 开头
+- 后缀只能包含字母、数字、下划线、连字符
+
+### 权限验证流程
+1. **调用者身份验证** — Kernel 自动注入 `_caller_id` 参数
+2. **白名单检查** — `caller_id` 必须在 `relay.modules` 列表中
+3. **命名规范检查** — `module_id` 必须以 `{caller_id}-client-` 开头
+4. **限额检查** — 当前已申请的 token 数量不能超过 `token_limits`
+
+### 测试用例
+
+| 调用者 | module_id | 结果 | 原因 |
+|--------|-----------|------|------|
+| evol | evol-client-abc123 | ✓ 通过 | 符合规范 |
+| web | web-client-xyz789 | ✓ 通过 | 符合规范 |
+| evol | web-client-abc123 | ✗ 拒绝 | 命名不匹配 |
+| web | evol-client-xyz789 | ✗ 拒绝 | 命名不匹配 |
+| unknown | unknown-client-test | ✗ 拒绝 | 不在白名单 |
+
+## 验证步骤
+
+### 1. 重启 Kite
+```bash
+# 停止当前实例（按 Ctrl+C 或 'q'）
+# 重新启动
+python main.py
+```
+
+### 2. 检查启动日志
+```bash
+# 查看 Evol 模块是否成功申请 token
+grep "relay" C:/Users/agentcp/.kite/workspace/Kite/evol/log/latest.log
+```
+
+**预期输出：**
+```
+[relay] Requesting kernel_token for evol-client-xsjazu from Launcher
+[relay] Received kernel_token for evol-client-xsjazu
+[relay] New connection: evol-client-xsjazu (role: admin)
+```
+
+### 3. 检查 Launcher 日志
+```bash
+grep "Token generated" C:/Users/agentcp/.kite/workspace/Kite/launcher/log/latest.log
+```
+
+**预期输出：**
+```
+[launcher] Token generated for evol-client-xsjazu (caller: evol)
+```
+
+### 4. 测试未授权模块
+尝试让未配置的模块申请 token，应该被拒绝：
+
+**预期错误：**
+```
+Permission denied: {module_id} not in relay_modules whitelist
+```
+
+## 安全保证
+
+1. **白名单机制** — 只有配置的模块才能申请 token
+2. **命名隔离** — 每个模块只能申请自己命名空间的 token
+3. **限额控制** — 防止单个模块申请过多 token
+4. **审计日志** — 所有 token 申请都会记录到 `launcher/log/token_audit.jsonl`
+
+## 故障排查
+
+### 问题：Permission denied
+**原因：** 模块不在白名单中
+**解决：** 在 `launcher/module.md` 的 `relay.modules` 中添加模块名
+
+### 问题：module_id must start with {prefix}
+**原因：** `base_module_id` 配置错误
+**解决：** 确保 `relay_config.json5` 中的 `base_module_id` 为 `{module_name}-client`
+
+### 问题：Token limit reached
+**原因：** 超过限额
+**解决：** 增加 `launcher/module.md` 中的 `relay.token_limits` 值，或释放不用的 token

package/docs/Watchdog/345/201/245/345/272/267/346/243/200/346/237/245/344/270/216WebSocket-Ping/346/234/272/345/210/266/345/210/206/346/236/220.md

@@ -0,0 +1,367 @@
+# Watchdog 健康检查与 WebSocket Ping 机制分析
+
+## 一、Watchdog 健康检查机制
+
+### 1.1 检查频率（动态间隔）
+
+Watchdog 采用**动态检查间隔**，根据模块的资源状态自动调整：
+
+| 资源状态 | 检查间隔 | 说明 |
+|---------|---------|------|
+| NORMAL（正常） | 15 秒 | 所有模块资源使用正常 |
+| WARNING（警告） | 5 秒 | 至少一个模块资源使用超过警告阈值 |
+| CRITICAL（严重） | 2 秒 | 至少一个模块资源使用超过严重阈值 |
+
+**实现逻辑：**
+```python
+# monitor.py:706-710
+def _min_interval(self) -> float:
+    """Return the shortest check interval needed across all modules."""
+    if not self.modules:
+        return self.INTERVALS[NORMAL]
+    return min(self.INTERVALS.get(s.resource_state, 15) for s in self.modules.values())
+```
+
+**取最短间隔** — 如果有任何一个模块处于 CRITICAL 状态，整个检查循环就会加速到 2 秒一次。
+
+### 1.2 检查的模块清单逻辑
+
+#### 模块发现流程
+
+**Step 1: 从 Launcher 获取运行中的模块**
+```python
+# monitor.py:105-120
+async def discover_modules(self):
+    resp = await self.rpc_call("launcher.list_modules", {})
+    result = resp.get("result", {})
+    for m in result.get("modules", []):
+        name = m.get("name", "")
+        # 过滤条件：
+        if name == "watchdog" or not m.get("monitor", True):
+            continue  # 跳过 watchdog 自己和 monitor=false 的模块
+        if m.get("actual_state", "").startswith("running"):
+            monitored[name] = m.get("pid")
+```
+
+**过滤规则：**
+1. ❌ **排除 watchdog 自己** — 不监控自己
+2. ❌ **排除 monitor=false 的模块** — 模块可以在 `module.md` 中设置 `monitor: false` 退出监控
+3. ✅ **只监控运行中的模块** — `actual_state` 必须以 "running" 开头
+
+**Step 2: 同步模块列表**
+```python
+# monitor.py:122-136
+# 添加新模块
+for mid, pid in monitored.items():
+    if mid not in self.modules:
+        self.modules[mid] = ModuleStatus(module_id=mid, pid=pid)
+    else:
+        self.modules[mid].pid = pid  # 更新 PID
+
+# 移除已停止的模块
+for mid in list(self.modules):
+    if mid not in seen:
+        del self.modules[mid]
+```
+
+#### 模块发现频率
+
+| 阶段 | 发现频率 | 说明 |
+|-----|---------|------|
+| 前 2 次 | 每个检查周期 | 快速建立初始监控列表 |
+| 之后 | 每 5 分钟 | 定期刷新模块列表 |
+| 事件触发 | 立即 | 收到 `module.started`/`registry.updated` 事件时 |
+
+```python
+# monitor.py:694-704
+if discovery_count < 2:
+    # First 2 times: discover every cycle
+    await self.discover_modules()
+    discovery_count += 1
+elif now - last_discovery >= discovery_interval:  # 300s = 5 minutes
+    await self.discover_modules()
+```
+
+### 1.3 每次检查的内容
+
+**对每个模块执行两项检查（并行）：**
+
+```python
+# monitor.py:684-688
+for s in self.modules.values():
+    tasks.append(self._check_one(s))        # 健康检查
+    tasks.append(self._check_resources(s))  # 资源监控
+await asyncio.gather(*tasks, return_exceptions=True)
+```
+
+#### 1. 健康检查（`_check_one`）
+
+- **方式**: 通过 RPC 调用 `{module_id}.health`
+- **超时**: 5 秒（RPC 调用超时）
+- **判断标准**:
+  - ✅ 成功：返回 `{"status": "healthy"}`
+  - ❌ 失败：RPC 错误、超时、返回非 healthy 状态
+- **失败处理**: 连续失败 3 次 → 自动重启模块
+
+#### 2. 资源监控（`_check_resources`）
+
+- **方式**: 通过 psutil 读取进程指标
+- **监控指标**:
+  - `memory_rss` — 物理内存使用（MB）
+  - `memory_percent` — 内存使用百分比
+  - `cpu_percent` — CPU 使用百分比
+  - `thread_count` — 线程数量
+
+**资源阈值：**
+
+| 指标 | WARNING | CRITICAL |
+|-----|---------|----------|
+| memory_percent | > 70% | > 85% |
+| cpu_percent | > 80% | > 95% |
+
+**特殊检测：内存泄漏**
+```python
+# monitor.py:298-302
+# 连续 3 次采样，每次都上升，且总增长 > 20%
+if all(recent[i] < recent[i+1] for i in range(len(recent)-1)):
+    if recent[-1] > recent[0] * 1.2:
+        raw_level = CRITICAL  # 判定为内存泄漏
+```
+
+### 1.4 当前监控的模块清单
+
+根据代码分析，以下模块会被监控：
+
+| 模块 | monitor 配置 | 是否被监控 | 说明 |
+|-----|------------|-----------|------|
+| kernel | true | ✅ | 核心模块 |
+| launcher | true | ✅ | 启动器 |
+| watchdog | - | ❌ | 自己不监控自己 |
+| backup | true | ✅ | 备份模块 |
+| model_service | true | ✅ | 模型服务 |
+| web | true | ✅ | Web 管理界面 |
+| evol | true | ✅ | Evol 服务 |
+
+**注意**: 实际监控列表是动态的，取决于：
+1. 模块的 `module.md` 中 `monitor` 字段配置
+2. 模块是否处于运行状态
+3. Launcher 是否成功启动该模块
+
+---
+
+## 二、WebSocket Ping/Pong 机制
+
+### 2.1 实现模块清单
+
+| 模块 | 角色 | ping_interval | ping_timeout | 连接目标 |
+|-----|------|--------------|-------------|---------|
+| **Kernel** | 服务端 | - | - | 监听 `/ws` 端点 |
+| **Launcher** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Watchdog** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Backup** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Model Service** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Web** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Evol** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **ACP Channel** | 客户端 | 20秒 | 20秒 | → Kernel |
+| **Assistant Agent** | 客户端 | 20秒 | 20秒 | → Kernel |
+
+**统一配置：**
+```python
+websockets.connect(
+    ws_url,
+    open_timeout=5,      # 连接超时 5 秒
+    ping_interval=20,    # 每 20 秒发送一次 ping
+    ping_timeout=20,     # 等待 pong 响应超时 20 秒
+    close_timeout=10     # 关闭连接超时 10 秒
+)
+```
+
+### 2.2 Ping/Pong 机制原理
+
+#### 工作流程
+
+```
+客户端                                    服务端（Kernel）
+  │                                           │
+  │────────── WebSocket 连接建立 ──────────────│
+  │                                           │
+  │                                           │
+  ├─ 每 20 秒自动发送 ──────────────────────────┤
+  │   WebSocket Ping 帧                       │
+  │                                           │
+  │                                           │
+  │ ◄────────── WebSocket Pong 帧 ────────────┤
+  │   （服务端自动响应）                        │
+  │                                           │
+  │                                           │
+  ├─ 如果 20 秒内未收到 Pong ───────────────────┤
+  │   → 判定连接断开                           │
+  │   → 触发重连逻辑                           │
+  │                                           │
+```
+
+#### 关键参数说明
+
+**1. ping_interval = 20 秒**
+- 客户端每 20 秒自动发送一个 WebSocket Ping 控制帧
+- 这是 WebSocket 协议层的心跳，不是应用层消息
+- 由 `websockets` 库自动处理，无需手动编码
+
+**2. ping_timeout = 20 秒**
+- 发送 Ping 后，等待 Pong 响应的最长时间
+- 如果 20 秒内未收到 Pong，连接被判定为断开
+- 触发 `WebSocketDisconnect` 异常
+
+**3. 服务端自动响应**
+- Kernel 的 WebSocket 服务端（FastAPI + websockets）自动响应 Ping
+- 无需手动编写 Pong 响应代码
+- 这是 WebSocket 协议的标准行为
+
+### 2.3 为什么需要 Ping/Pong 机制
+
+#### 问题场景
+
+**1. 网络中断检测**
+```
+客户端 ──X──[路由器故障]──X── 服务端
+```
+- TCP 连接可能长时间保持 ESTABLISHED 状态
+- 但实际上网络已经不通
+- 没有数据传输时，双方都不知道连接已断
+
+**2. 防火墙/NAT 超时**
+```
+客户端 ──[NAT 设备]── 服务端
+         ↑
+    空闲 60 秒后清除映射
+```
+- 很多 NAT 设备会清除长时间空闲的连接映射
+- 导致连接实际上已失效，但双方不知道
+
+**3. 进程僵死检测**
+```
+客户端进程正常 ──→ 服务端进程僵死
+                   （事件循环卡死）
+```
+- 服务端进程存活，TCP 连接正常
+- 但事件循环卡死，无法处理任何消息
+- Ping/Pong 能检测出这种情况（无法响应 Pong）
+
+#### Ping/Pong 的作用
+
+✅ **快速检测连接断开** — 最多 40 秒（20s ping + 20s timeout）发现连接失效
+✅ **保持连接活跃** — 防止 NAT/防火墙清除空闲连接
+✅ **检测对端僵死** — 如果对端无法响应 Pong，说明事件循环卡死
+✅ **自动重连触发** — 连接断开后，客户端自动进入重连逻辑
+
+### 2.4 Ping/Pong vs 应用层心跳（已移除）
+
+| 特性 | WebSocket Ping/Pong | 应用层心跳（已移除） |
+|-----|-------------------|------------------|
+| **层级** | 传输层（WebSocket 协议） | 应用层（JSON-RPC） |
+| **实现** | 库自动处理 | 需要手动编码 |
+| **开销** | 极小（控制帧） | 较大（完整 RPC 调用） |
+| **检测内容** | 网络连接 + 事件循环 | 仅证明"能发消息" |
+| **检测速度** | 40 秒 | 60 秒（30s 间隔 + 30s TTL） |
+| **业务信息** | 无 | 无（只是"我还活着"） |
+
+**结论**: WebSocket Ping/Pong 已经足够检测连接状态，应用层心跳是冗余的。
+
+---
+
+## 三、两种机制的配合
+
+### 3.1 分层检测
+
+```
+┌─────────────────────────────────────────────┐
+│  应用层健康检查（Watchdog 主动调用）          │
+│  - 检测业务处理能力                          │
+│  - 获取详细健康信息                          │
+│  - 间隔：15s / 5s / 2s（动态）              │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  WebSocket Ping/Pong（自动）                 │
+│  - 检测网络连接状态                          │
+│  - 检测事件循环是否卡死                      │
+│  - 间隔：20s                                │
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│  TCP 连接（操作系统层）                       │
+│  - 检测物理网络连通性                        │
+│  - TCP keepalive（通常 2 小时）             │
+└─────────────────────────────────────────────┘
+```
+
+### 3.2 故障检测时间对比
+
+| 故障类型 | Ping/Pong 检测时间 | Watchdog 检测时间 | 说明 |
+|---------|------------------|-----------------|------|
+| 网络断开 | 40 秒 | 15-45 秒 | Ping/Pong 更快 |
+| 进程崩溃 | 立即（连接断开） | 15-45 秒 | Ping/Pong 更快 |
+| 事件循环卡死 | 40 秒 | 5-15 秒 | Watchdog 更快（RPC 超时） |
+| 业务逻辑失效 | 无法检测 | 5-15 秒 | 只有 Watchdog 能检测 |
+| 资源耗尽 | 无法检测 | 2-15 秒 | 只有 Watchdog 能检测 |
+
+### 3.3 重连与恢复
+
+**WebSocket 断开后的处理：**
+
+```python
+# 所有客户端模块都有类似的重连逻辑
+async def _ws_loop(token: str, kernel_port: int):
+    retry_delay = 0.3
+    max_delay = 5.0
+    max_retries = 10
+    attempt = 0
+
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port)
+            retry_delay = 0.3  # 重置延迟
+            attempt = 0
+        except Exception as e:
+            attempt += 1
+            if attempt >= max_retries:
+                sys.exit(1)  # 放弃重连
+            await asyncio.sleep(retry_delay)
+            retry_delay = min(retry_delay * 2, max_delay)  # 指数退避
+```
+
+**重连策略：**
+- 初始延迟：0.3 秒
+- 最大延迟：5 秒
+- 最大重试：10 次
+- 退避算法：指数退避（0.3s → 0.6s → 1.2s → 2.4s → 5s）
+
+---
+
+## 四、总结
+
+### Watchdog 健康检查
+
+- **频率**: 15 秒（正常）/ 5 秒（警告）/ 2 秒（严重）
+- **检查对象**: 所有 `monitor=true` 且运行中的模块（除 watchdog 自己）
+- **检查内容**:
+  - 健康检查：RPC 调用 `{module_id}.health`
+  - 资源监控：CPU、内存、线程数、内存泄漏检测
+- **失败处理**: 连续 3 次失败 → 自动重启
+
+### WebSocket Ping/Pong
+
+- **实现模块**: 所有连接到 Kernel 的模块（8 个客户端）
+- **频率**: 每 20 秒发送 Ping，20 秒内未收到 Pong 则断开
+- **作用**:
+  - 检测网络连接状态
+  - 防止 NAT/防火墙超时
+  - 检测事件循环卡死
+  - 触发自动重连
+- **优势**: 协议层实现，开销极小，无需手动编码
+
+### 两者配合
+
+- **Ping/Pong** 负责连接层检测（快速发现断开）
+- **Watchdog** 负责应用层检测（深度健康检查）
+- **互补关系**: Ping/Pong 检测不到的业务层问题，由 Watchdog 检测

package/docs/Watchdog/350/265/204/346/272/220/347/233/221/346/216/247/347/255/226/347/225/245.md

@@ -0,0 +1,92 @@
+# Watchdog 资源监控策略
+
+## 1. 概述
+
+Watchdog 是 Kite 的应用层健康监控模块（扩展模块，非 core）。它负责两类监控：
+
+- **健康检查**（已实现）：定期检查模块 `/health` 端点
+- **资源监控**（本文档）：采集模块进程的 CPU/内存等指标，检测异常并处理
+
+Launcher 处理进程级故障（进程退出），Watchdog 处理应用级故障（进程活着但不健康或资源异常）。
+
+## 2. 监控模块列表
+
+Watchdog 通过 Launcher API `GET /launcher/modules` 获取模块列表，根据响应中的 `monitor: true/false` 字段决定是否监控。Watchdog 始终跳过自身。
+
+Launcher 负责保证 Watchdog 模块的启动和运行：Watchdog 崩溃时 Launcher 自动重启它（与其他非 core 模块相同的重启策略）。
+
+## 3. 资源采集
+
+### 3.1 采集指标
+
+| 指标 | 字段名 | 单位 | 说明 |
+|------|--------|------|------|
+| 物理内存 | `memory_rss` | MB | 进程实际占用的物理内存 |
+| 内存占比 | `memory_percent` | % | 占系统总内存的百分比 |
+| CPU 使用率 | `cpu_percent` | % | 采样间隔内的 CPU 使用率 |
+| 文件描述符 | `open_fds` | 个 | 打开的 fd 数（Linux/macOS） |
+| 线程数 | `thread_count` | 个 | 进程内线程数 |
+
+### 3.2 采集方式
+
+通过 `psutil.Process(pid)` 主动采集。pid 从 Launcher API `GET /launcher/modules` 的响应中获取。不依赖模块自身上报。
+
+### 3.3 采集时机
+
+每次健康检查时同时采集资源指标。检查周期根据模块状态动态调整（见第 5 节）。
+
+## 4. 异常判定
+
+### 4.1 三级状态模型
+
+| 状态 | 条件 | 检查周期 |
+|------|------|----------|
+| `normal` | 所有指标在阈值内 | 15s |
+| `warning` | memory_percent > 70% 或 cpu_percent > 80%（连续 2 次） | 5s |
+| `critical` | memory_percent > 85% 或 cpu_percent > 95%（连续 3 次） | 2s |
+
+### 4.2 内存泄漏检测
+
+记录最近 5 次 `memory_rss` 采样值。如果连续 3 次上升且总增幅 > 20%，直接进入 `critical`，不经过 `warning` 阶段。
+
+### 4.3 恢复判定
+
+指标回到 normal 阈值内后，保留 60s 观察期（期间用 5s 周期），观察期内无异常则恢复为 `normal`（15s 周期）。
+
+## 5. 处理策略
+
+### 5.1 warning 阶段
+
+- 缩短检查周期：15s → 5s
+- 发事件通知模块：`watchdog.module.resource_warning`
+
+### 5.2 critical 阶段
+
+- 缩短检查周期：5s → 2s
+- 发事件通知模块：`watchdog.module.resource_critical`
+- 启动 30s 倒计时
+
+### 5.3 超时处理（critical 持续 30s 未恢复）
+
+- 通过 Launcher API 重启模块（stop reason: `resource_critical`）
+- 重启次数计入 `restarted_count`，共享 `MAX_RESTARTS=3` 限制
+- 超过重启限制 → 发 `watchdog.alert` 事件，停止监控该模块
+
+## 6. 事件定义
+
+| 事件 | 说明 | payload |
+|------|------|---------|
+| `watchdog.module.resource_warning` | 资源警告 | module_id, metrics snapshot |
+| `watchdog.module.resource_critical` | 资源危险 | module_id, metrics, remaining_seconds |
+| `watchdog.module.resource_recovered` | 资源恢复 | module_id |
+
+## 7. 现有健康检查机制（已实现）
+
+| 项目 | 值 |
+|------|-----|
+| 检查间隔 | 15s |
+| HTTP 超时 | 5s |
+| 连续失败阈值 | 3 次 |
+| 最大重启次数 | 3 次 |
+| 告警阈值 | 重启 2 次后发 alert |
+| 重启方式 | 通过 Launcher API stop + start |