@agentunion/kite 1.5.0 → 1.6.1

package/docs/Redis/344/270/216/346/250/241/345/235/227/345/244/232/345/256/236/344/276/213/346/226/271/346/241/210.md

@@ -0,0 +1,438 @@
+# Redis 与模块多实例方案
+
+## 概述
+
+本方案包含两个核心改进：
+
+1. **连接与状态驱动模型** — 注册/订阅由 Kernel 状态驱动，连接无类型，崩溃恢复与正常启动走同一条路
+2. **模块多实例** — 支持模块声明多实例，Kernel 根据压力自动弹性扩缩容，Redis 为多实例模块提供无状态基础设施
+
+**Kernel 不依赖 Redis**。
+
+---
+
+## 一、Kernel 连接与状态驱动模型
+
+### 1.1 核心设计变更
+
+**注册/订阅从连接流程变为 Kernel 状态驱动**：
+
+| | 现有设计 | 新设计 |
+|--|---------|--------|
+| 驱动方 | 模块主动（连上就注册） | Kernel 驱动（按需要求注册） |
+| 连接类型 | 区分主连接 / slot 连接 | 不区分，所有连接一样 |
+| 重连行为 | 每次重连都重新注册 | Kernel 有注册信息就不要求 |
+| 崩溃恢复 | 需要全量重启 | 和正常启动走同一条路 |
+
+### 1.2 连接无类型
+
+在 Kernel 看来，所有连接都一样。不管是首次连接、重连、还是多连接的第 N 条，流程都是：
+
+```
+模块连接 Kernel → auth
+  → Kernel 检查：这个模块有没有注册信息？
+      ├─ 没有 → 发送 system.require_init 通知模块注册和订阅
+      └─ 有了 → 什么都不做（只是多了一条连接）
+```
+
+### 1.3 system.require_init 事件
+
+**新增事件**。Kernel 发给单个模块，告诉它「我没有你的注册信息，请注册和订阅」。
+
+- **发送方**：Kernel
+- **接收方**：单个模块（通过该模块的连接发送）
+- **触发条件**：模块 auth 通过后，Kernel 发现无该模块的注册信息
+- **模块收到后**：执行 subscribe + register + module.ready
+
+**关键特性**：同一模块不管有几条连接，只会收到一次 `system.require_init`。因为第一条连接触发注册后，后续连接 auth 时 Kernel 已有注册信息，不再发送。
+
+---
+
+## 二、Kite 启动流程
+
+### 2.1 启动参数
+
+```bash
+python main.py          # 默认：恢复模式（resume）
+python main.py --new    # 全新启动（new）
+```
+
+通过环境变量传递给所有模块：
+
+| 环境变量 | 值 | 含义 |
+|---------|---|------|
+| `KITE_STARTUP_MODE` | `resume` | 恢复上一次状态（默认） |
+| `KITE_STARTUP_MODE` | `new` | 全新实例，不恢复状态 |
+
+**此参数不影响 Kite 启动流程，也不影响 Kernel。** 它仅作为环境变量传递给模块，模块自行根据此变量决定自己的业务行为（如多实例模块决定是否从 Redis 恢复业务状态）。
+
+### 2.2 两阶段启动流程
+
+```
+Phase 1: 核心启动
+  → Kernel 启动，ready
+
+Phase 2: 模块启动
+  → 所有模块启动，连接 Kernel，auth
+  → Kernel 发现无注册信息 → 逐个发 system.require_init
+  → 模块 subscribe + register + module.ready
+  → 所有模块 ready
+
+→ system.ready
+→ Kernel 启动 Ping/Pong
+→ Launcher 调用 watchdog.start_monitor()
+```
+
+**两阶段划分的理由**：
+
+| 阶段 | 名称 | 依赖 | 理由 |
+|------|------|------|------|
+| Phase 1 | 核心启动 | 无 | Kernel 是所有模块的通信基础，必须先就绪 |
+| Phase 2 | 模块启动 | Phase 1 | 模块需要 Kernel 提供注册和通信能力 |
+
+### 2.3 Kernel 崩溃恢复流程
+
+Kernel 崩溃后不再全量重启，流程与正常启动**走同一条路**：
+
+```
+Kernel 崩溃
+  → Launcher 检测到 Kernel 进程退出
+  │
+  ├─ Phase 1: 重启 Kernel
+  │   → Launcher 重启 Kernel
+  │   → Kernel 启动，自生成新 launcher_token
+  │   → Launcher 连接 Kernel，认证
+  │   → Launcher 调用 RPC 回传已有的 Token 映射
+  │   → Kernel ready
+  │
+  ├─ Phase 2: 模块重连（自动）
+  │   → 模块检测到 Kernel 断连，自动重连
+  │   → auth 通过（Launcher 已回传 Token）
+  │   → Kernel 发现无注册信息 → 发 system.require_init
+  │   → 模块 subscribe + register + module.ready
+  │   → 所有模块 ready
+  │
+  └─ system.ready (recovered=true)
+      → Kernel 启动 Ping/Pong
+```
+
+**Token 恢复机制**：Kernel 崩溃时 Token 丢失，但 Launcher 内存中保有所有 Token（`_module_tokens` 字典）。Launcher 重连 Kernel 后通过 RPC 回传 Token 映射，毫秒级恢复，不依赖 Redis。
+
+### 2.4 系统事件体系
+
+| 事件 | 发送方 | 语义 |
+|------|--------|------|
+| `system.require_init` | Kernel → 单个模块 | 请注册和订阅 |
+| `module.ready` | 模块 → Kernel | 模块已就绪（携带 `reason` 字段） |
+| `system.ready` | Launcher → 所有 | 系统就绪 |
+
+**`module.ready` 携带 `reason` 字段**区分注册原因：
+
+| reason | 含义 | 触发场景 |
+|--------|------|---------|
+| `startup` | 首次启动 | 模块进程刚启动，首次收到 `system.require_init` |
+| `recovery` | 崩溃恢复 | Kernel 崩溃恢复后，模块重连并重新注册 |
+| `refresh` | 刷新注册 | 注册/订阅超时（1小时），Kernel 要求重新注册 |
+
+**`system.ready` 携带 `recovered` 标记**区分首次启动和崩溃恢复：
+
+```json
+// 首次启动
+{"event": "system.ready", "data": {"recovered": false, ...}}
+
+// Kernel 崩溃恢复后
+{"event": "system.ready", "data": {"recovered": true, ...}}
+```
+
+**各接收方根据 `recovered` 标记决定行为**：
+
+| 接收方 | recovered=false（首次启动） | recovered=true（崩溃恢复） |
+|--------|---------------------------|--------------------------|
+| Kernel | 启动 Ping/Pong | 重新启动 Ping/Pong |
+| Launcher | 调用 watchdog.start_monitor() | 调用 watchdog.start_monitor()（Launcher 控制） |
+| 其他模块 | 接收，知道系统就绪 | 接收，知道 Kernel 已恢复 |
+
+### 2.5 完整场景矩阵
+
+| 场景 | Phase 1 | Phase 2 | 结束事件 |
+|------|---------|---------|---------|
+| Kite 正常启动 | Kernel 启动 | 模块启动+注册 | system.ready |
+| Kernel 崩溃重启 | Kernel 重启 + Token 回传 | 模块重连+注册 | system.ready (recovered=true) |
+| Redis 崩溃 | — | — | 不影响 Kernel 和启动流程 |
+
+---
+
+## 三、Redis 模块
+
+### 3.1 定位
+
+Redis 模块是一个**普通的 Kite 模块**，为多实例模块提供共享状态基础设施。Kernel 不依赖 Redis。
+
+### 3.2 双层实现
+
+| 优先级 | 条件 | 实现 |
+|--------|------|------|
+| 1 | `redis_mode=external` 且配置了 `KITE_REDIS_URL` | 优先直连外部 Redis/Valkey |
+| 2 | 未走外部 Redis 启动路径，或外部连接失败且 `allow_fallback=true` | 内置简版实现，RESP 协议兼容 |
+
+双层实现对上层完全透明，切换无需改代码。是否允许从外部 Redis 降级到内置 Redis，由 `allow_fallback` 参数控制。
+
+简版自实现无需覆盖完整 Redis 协议，只需支持 Kite 实际使用的命令子集：
+
+```
+GET / SET / DEL / EXPIRE
+HGET / HSET / HDEL / HGETALL
+SADD / SREM / SMEMBERS
+PUBLISH / SUBSCRIBE
+PING
+```
+
+简版自实现使用 Redis RESP 协议（文本协议），客户端代码切换到真 Redis 时零改动。
+
+### 3.3 Redis 模块与 Redis 的区别
+
+**Redis 模块 ready ≠ Redis 可用**：
+
+- Redis 模块 ready = 模块进程启动完成，进入正常工作流程
+- Redis 可用 = Redis 模块成功连接到外部 Redis 或内置简版已就绪，可以提供数据服务
+
+连接外部 Redis 属于 Redis 模块自己的业务逻辑。连接成功后，Redis 模块发布 `system.redis_ready` 事件通知其他模块。
+
+### 3.4 对外暴露
+
+- **注册中心**：发布 Redis 连接信息（host、port、协议版本），其他模块可直连
+- **RPC 接口**：低频操作可走 RPC，无需引入 Redis 客户端库
+- 模块可自由选择直连或走 RPC
+
+### 3.5 约束
+
+- Redis 模块本身**不支持多实例**，它是基础设施单点
+- 未走外部 Redis 启动路径，或外部连接失败且 `allow_fallback=true` 时，简版自实现兜底
+
+### 3.6 Redis 故障处理
+
+外部 Redis 不可用时：
+
+- `allow_fallback=true`：外部 Redis 连接失败后，Redis 模块降级到内置 Redis 继续提供服务
+- `allow_fallback=false`：外部 Redis 连接失败后，不降级，Redis 模块启动失败并退出
+- 无论是否降级，都记录日志和审计，明确提示当前实际使用的是外部 Redis 还是内置 Redis
+
+### 3.7 Redis 重连重试参数
+
+Redis 模块从自己的配置文件读取以下参数：
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `allow_fallback` | `true` | 外部 Redis 连接失败时，是否允许降级到内置 Redis |
+| `redis_retry_initial` | `1` (秒) | 首次重试间隔 |
+| `redis_retry_max` | `30` (秒) | 最大重试间隔 |
+
+采用指数退避策略：1s → 2s → 4s → 8s → 16s → 30s → 30s → ...
+
+---
+
+## 四、模块多实例
+
+### 4.1 配置参数
+
+对齐多连接弹性控制的参数风格：
+
+| 参数 | 默认值 | 硬上限 | 含义 | 对标参数 |
+|------|--------|-------|------|---------|
+| `max_instances` | `1` | `10`（超过则重置为 `1`） | 允许的实例上限 | `max_connections`（默认 `1`） |
+| `instance_elastic` | `false` | — | 是否允许 Kernel 弹性控制实例数 | `connection_elastic`（默认 `false`） |
+
+配置位置：`module.md` frontmatter 或注册时声明。
+
+`max_instances` 硬上限为 10，配置值超过 10 重置为 1（安全阀 — 离谱的值说明配置者不理解该参数，回到安全的单实例模式）。
+
+### 4.2 参数组合语义
+
+| max_instances | instance_elastic | 行为 |
+|---------------|-----------------|------|
+| 1 | false | 单实例（现状，完全向后兼容） |
+| 1 | true/false | 单实例（上限为 1，弹性无意义） |
+| N > 1 | false | 固定 N 个实例，启动时全部拉起，不自动扩缩 |
+| N > 1 | true | 弹性模式：启动 1 个，Kernel 根据压力自动扩缩，上限 N |
+
+### 4.3 对外完全透明
+
+其他模块不知道目标模块有几个实例。调 RPC、发事件和单实例时完全一样。
+
+Kernel 视角：同一 `module_name` 下多个 slot，复用现有多连接路由结构：
+
+```
+"assistant": {
+    0: ws_instance_1,    // 主实例
+    1: ws_instance_2,    // 弹性实例
+    2: ws_instance_3     // 弹性实例
+}
+```
+
+### 4.4 路由策略
+
+- **普通事件**：基于压力的加权随机（优先发给压力低的实例）
+- **保序事件**：粘性路由（同一 ordering_group 绑定到同一实例，实例断开则迁移）
+- **RPC 请求**：随机路由（无状态，谁空闲发谁）
+
+### 4.5 压力报告机制
+
+模块主动上报队列压力，Kernel 被动接收。
+
+**上报事件**：`module.queue_pressure`
+
+```json
+{
+    "event": "module.queue_pressure",
+    "source": "assistant",
+    "data": {
+        "level": "overload",
+        "depth": 156,
+        "capacity": 200
+    }
+}
+```
+
+**上报策略（模块自决）**：
+
+- 压力等级变化时立即上报
+- 压力高时提高频率（如 2s），低时降低（如 30s）
+- 收到事件时顺便检查队列深度，零额外开销
+
+**可靠性保障**：压力报告事件标记为**系统级事件**（不可丢弃、不可压缩），保证传输优先级。
+
+### 4.6 扩缩容 — Kernel 统一决策
+
+**设计原则**：Kernel 拥有所有实例的全局压力视图，由 Kernel 统一决策扩缩容，避免模块侧多实例竞态冲突。
+
+模块只需要做两件事：
+1. 上报队列压力
+2. 保证自己无状态
+
+**扩容流程**：
+
+```
+Kernel 检测到模块所有实例持续 overload 超过阈值
+  → 检查当前实例数 < max_instances
+  → 检查没有「扩容中」的待启动实例
+  → 调用 Launcher RPC 启动新实例
+  → 标记该模块「扩容中」，进入冷却期
+  → Launcher 启动新进程
+  → 新实例连接 Kernel，正常注册
+  → Kernel 将其纳入路由池
+  → 通知所有实例：system.instance.started
+```
+
+**缩容流程**：
+
+```
+Kernel 检测到模块多个实例持续 idle 超过阈值（且实例数 > 1）
+  → 选择缩容目标（优先选无活跃保序绑定的实例）
+  → 将目标实例从路由池移除（不再分发新事件）
+  → 通知目标实例优雅退出（复用现有模块退出机制：优雅退出 + 超时强杀兜底）
+  → 通知其他实例：system.instance.stopped
+```
+
+**防震荡机制**：
+
+| 策略 | 扩容 | 缩容 |
+|------|------|------|
+| 触发阈值 | 所有实例 overload | 多个实例 idle |
+| 持续时间 | 30s | 120s |
+| 冷却时间 | 扩容后 30s 内不再扩容 | 缩容后 60s 内不再缩容 |
+
+扩容激进、缩容保守，和多连接弹性控制的 offer（立即）vs release（空闲 30s）同一思路。
+
+**「扩容中」状态**：Kernel 维护已请求但尚未 ready 的实例数，计入当前实例数，避免扩容响应延迟期间重复触发。
+
+**缩容时的保序安全**：优先缩容没有活跃 ordering_group 绑定的实例。如果所有实例都有绑定，等待绑定自然释放后再缩容。
+
+### 4.7 模块使用 Redis
+
+| 使用者 | 用途 | 获取方式 |
+|--------|------|---------|
+| 多实例模块 | 共享状态（自己的业务数据） | 注册中心获取 Kite Redis 连接信息，或自配独立 Redis |
+
+多实例模块需要保证自身无状态，有状态部分迁移到 Redis。Kernel 不关心模块如何使用 Redis。
+
+---
+
+## 五、多连接与多实例的关系
+
+### 5.1 解决不同层面的问题
+
+```
+事件流：  Kernel → [传输层] → [处理层] → 模块业务逻辑
+
+多连接解决：        ^^^^^^^^
+                   传输瓶颈（Kernel 发不出去）
+
+多实例解决：                   ^^^^^^^^
+                              计算瓶颈（模块处理不过来）
+```
+
+### 5.2 统一的决策模型
+
+两者都由 Kernel 统一决策，执行者不同：
+
+| | 多连接 | 多实例 |
+|--|--------|--------|
+| 瓶颈在 | Kernel 侧（发送队列堆积） | 模块侧（处理队列堆积） |
+| 信息源 | Kernel 自己的队列深度 | 模块上报的压力状态 |
+| 决策者 | Kernel | Kernel |
+| 执行者 | 模块（建连接） | Launcher（启进程） |
+| 弹性开关 | `connection_elastic` | `instance_elastic` |
+| 通知 | offer / release | system.instance.started / stopped |
+
+### 5.3 不冲突，可叠加
+
+每个实例独立拥有自己的多连接，两级路由自然组合：
+
+```
+事件到达
+  → 第一级：选实例（基于实例压力，或保序粘性）
+  → 第二级：选 slot（基于 slot 队列深度，或保序绑定）
+```
+
+示例：`assistant`（max_instances=3, max_connections=4）
+
+```
+实例 1 ─── slot 0 ───→ Kernel
+        ├─ slot 1 ───→ Kernel
+        └─ slot 2 ───→ Kernel
+
+实例 2 ─── slot 0 ───→ Kernel
+        └─ slot 1 ───→ Kernel
+
+实例 3 ─── slot 0 ───→ Kernel
+```
+
+### 5.4 Kernel 区分瓶颈类型
+
+当 Kernel 侧队列堆积时，需要区分原因以「对症下药」：
+
+| Kernel 侧压力 | 模块侧压力 | 瓶颈类型 | 正确操作 |
+|---------------|-----------|---------|---------|
+| 高 | 低 | 传输瓶颈 | 加连接 |
+| 高 | 高 | 计算瓶颈 | 加实例（加连接无用） |
+| 低 | 高 | 纯计算瓶颈 | 加实例 |
+
+---
+
+## 六、方案评估
+
+| 评估维度 | 评分 | 说明 |
+|---------|------|------|
+| 向后兼容 | 10/10 | 默认 `max_instances=1, instance_elastic=false`，和现状完全一致 |
+| 零共享代码依赖 | 10/10 | 模块通过协议（事件、RPC）交互，不引入代码耦合 |
+| 跨语言兼容 | 10/10 | Redis RESP 协议语言无关，任何语言用标准 Redis 客户端即可连接 |
+| 跨平台兼容 | 10/10 | 双层实现均跨平台，无平台特有依赖 |
+| Kernel 独立性 | 10/10 | Kernel 不依赖 Redis，崩溃恢复通过模块重连自动重建 |
+| 故障隔离 | 10/10 | Redis 故障不影响 Kernel；Kernel 崩溃不需要全量重启；实例崩溃其他实例继续服务 |
+| 决策一致性 | 10/10 | 多连接和多实例都由 Kernel 统一决策，模型对称 |
+| 对外透明 | 10/10 | 其他模块完全不知道多实例存在 |
+| 参数设计一致性 | 10/10 | 命名、默认值、语义与多连接弹性控制完全对齐 |
+| 模块开发难度 | 10/10 | 模块只需上报压力 + 保证无状态，无需实现扩缩容逻辑 |
+| 启动流程简洁性 | 10/10 | 两阶段启动，正常启动和崩溃恢复走同一条路，无特殊分支 |
+| 连接模型优雅度 | 10/10 | 连接无类型，注册由 Kernel 状态驱动，新增仅一个事件 |
+

package/docs/Relay-Kite-Token/350/256/244/350/257/201/345/256/236/346/226/275/345/256/214/346/210/220.md

@@ -0,0 +1,178 @@
+# Relay Service Kite Token 认证 - 实施完成
+
+## 改动内容
+
+### 1. relay.py
+
+**修改位置**：`extensions/services/evol/relay.py`
+
+**改动 1：`__init__` 方法**
+- 新增 `auth_manager` 参数（可选）
+- 保存到实例变量 `self.auth_manager`
+
+**改动 2：`_handle_auth` 方法**
+- 新增 Kite Token 认证逻辑
+- 认证流程：
+  1. 先尝试配对码认证（`pairing_manager.verify_token()`）
+  2. 如果失败，尝试 Kite Token 认证（`auth_manager.verify_kite_token()`）
+  3. 如果都失败，返回错误
+- Kite Token 用户默认 role 为 `admin`
+- 添加日志输出，标识认证类型
+
+### 2. server.py
+
+**修改位置**：`extensions/services/evol/server.py`
+
+**改动**：创建 `KernelRelay` 实例时传递 `auth_manager`
+- 在 `_startup()` 方法中
+- 传递 `server.auth_manager` 给 `KernelRelay`
+
+## 验证步骤
+
+### 方式 1：通过浏览器测试
+
+#### 测试配对码认证
+
+1. 启动 Kite：`python main.py`
+2. 打开浏览器，访问 `http://localhost:18766/pairing.html`
+3. 生成配对码并配对
+4. 验证连接成功，可以正常使用控制台
+
+**预期结果**：
+- 配对成功
+- 控制台显示 "● 已连线"
+- 可以查看模块列表、执行操作
+
+#### 测试 Kite Token 认证
+
+1. 清除浏览器 localStorage 和 sessionStorage
+2. 访问 `http://localhost:18766/`
+3. 使用手机号登录（获得 kiteToken）
+4. 刷新页面
+5. 打开浏览器控制台，查看 WebSocket 连接
+
+**预期结果**：
+- 自动使用 kiteToken 连接 `/ws/relay`
+- 连接成功，显示 "● 已连线"
+- 可以正常使用控制台
+
+**验证方法**：
+```javascript
+// 在浏览器控制台执行
+localStorage.getItem('kiteToken')  // 应该有值
+localStorage.getItem('frontend_token')  // 可能为空
+
+// 查看 WebSocket 连接
+// Network 面板 -> WS -> 查看消息
+// 应该看到 {"type": "auth", "token": "kite_xxx..."}
+// 响应：{"type": "authenticated", "role": "admin", ...}
+```
+
+### 方式 2：通过测试脚本
+
+1. 启动 Kite
+2. 获取有效的 Kite Token（通过手机号登录）
+3. 修改 `test_relay_auth.py` 中的 token
+4. 运行测试脚本：`python test_relay_auth.py`
+
+**预期输出**：
+```
+=== 测试 Kite Token 认证 ===
+响应: {'type': 'authenticated', 'module_id': 'evol-client-test02', 'role': 'admin', ...}
+✓ Kite Token 认证成功
+  - module_id: evol-client-test02
+  - role: admin
+
+测试 RPC 调用...
+✓ RPC 调用成功
+  - 模块数量: 5
+```
+
+### 方式 3：查看日志
+
+启动 Kite 后，查看 Evol 模块日志：
+
+```bash
+# 查看最新日志
+cat C:/Users/agentcp/.kite/workspace/Kite/evol/log/latest.log | grep -i "relay\|auth"
+```
+
+**预期日志**：
+
+使用配对码认证时：
+```
+[Relay] Authenticated via pairing code, role=admin
+[relay] New connection: evol-client-abc123 (role: admin)
+```
+
+使用 Kite Token 认证时：
+```
+[Relay] Authenticated via Kite Token, role=admin
+[relay] New connection: evol-client-xyz789 (role: admin)
+```
+
+## 兼容性说明
+
+### 向后兼容
+
+- ✅ 配对码认证完全保持不变
+- ✅ 现有的配对码 token 继续有效
+- ✅ 不影响已配对的客户端
+
+### 新功能
+
+- ✅ 支持 Kite Token 认证
+- ✅ 两种认证方式可以并存
+- ✅ Kite Token 用户默认为 admin 角色
+
+## 下一步
+
+完成验证后，可以继续进行：
+
+1. **第二步**：修改 `kernel-client.js` 支持 Kite Token
+2. **第三步**：改造 `evol-app.js` 使用 kernelClient
+3. **第四步**：删除 `kernel-client-example.js`
+4. **第五步**：删除 `/ws/management`
+
+## 回滚方案
+
+如果出现问题，可以回滚：
+
+```bash
+# 回滚 relay.py
+git checkout extensions/services/evol/relay.py
+
+# 回滚 server.py
+git checkout extensions/services/evol/server.py
+
+# 重启 Kite
+python main.py
+```
+
+## 注意事项
+
+1. **auth_manager 为 None 的情况**
+   - 如果 `auth_manager` 未传递（为 None），Kite Token 认证会被跳过
+   - 只使用配对码认证
+   - 不会报错，向后兼容
+
+2. **Kite Token 的有效期**
+   - Kite Token 永久有效（除非手动吊销）
+   - 配对码 token 有 30 天有效期
+   - 两者的过期策略不同
+
+3. **Role 权限**
+   - Kite Token 用户默认为 `admin`
+   - 配对码用户的 role 由配对时指定
+   - 权限控制基于 `relay_config.json5` 中的 `permissions` 配置
+
+## 测试清单
+
+- [ ] 配对码认证成功
+- [ ] Kite Token 认证成功
+- [ ] 无效 token 认证失败
+- [ ] 配对码和 Kite Token 可以并存
+- [ ] 认证成功后可以调用 RPC
+- [ ] 认证成功后可以订阅事件
+- [ ] 日志输出正确
+- [ ] 不影响现有功能