@agentunion/kite 1.4.0 → 1.6.0

package/docs//344/272/213/344/273/266/350/256/242/351/230/205/351/200/232/351/205/215/347/254/246/350/247/204/350/214/203.md

@@ -0,0 +1,256 @@
+# 事件订阅通配符规范
+
+## 概述
+
+Kite 的事件订阅系统采用 **NATS-style 通配符匹配**，支持灵活的事件过滤和路由。
+
+## 通配符类型
+
+### `*` — 单段通配符
+
+匹配**恰好一个**段（segment）。
+
+**特点：**
+- 只能匹配一个段，不能跨越多个段
+- 可以在模式的任意位置使用
+- 可以多次使用
+
+**示例：**
+
+```python
+# 匹配所有 module 命名空间下的单层事件
+订阅: "module.*"
+✓ "module.ready"
+✓ "module.offline"
+✗ "module.status.changed"  # 3 段，模式只有 2 段
+✗ "watchdog.alert"  # 第一段不匹配
+
+# 匹配所有模块的 status 事件
+订阅: "*.status"
+✓ "module.status"
+✓ "watchdog.status"
+✓ "web.status"
+✗ "module.status.changed"  # 3 段，模式只有 2 段
+
+# 多个 * 组合
+订阅: "*.*.changed"
+✓ "module.status.changed"
+✓ "watchdog.health.changed"
+✗ "module.ready"  # 只有 2 段
+✗ "a.b.c.d"  # 第三段不是 changed
+```
+
+### `>` — 多段通配符（尾部）
+
+匹配**一个或多个**段，只能在模式的**末尾**使用。
+
+**特点：**
+- 匹配剩余所有段（至少一个）
+- 必须是模式的最后一个段
+- 不能在中间或开头使用
+
+**示例：**
+
+```python
+# 匹配 module 命名空间下的所有事件（任意层级）
+订阅: "module.>"
+✓ "module.ready"
+✓ "module.offline"
+✓ "module.status.changed"
+✓ "module.a.b.c.d.e"
+✗ "watchdog.alert"  # 第一段不匹配
+
+# 匹配所有事件
+订阅: ">"
+✓ "module.ready"
+✓ "watchdog.alert"
+✓ "a.b.c.d.e"
+✓ 任何事件类型
+
+# 组合使用
+订阅: "*.status.>"
+✓ "module.status.changed"
+✓ "watchdog.status.ok"
+✓ "web.status.error.critical"
+✗ "module.ready"  # 第二段不是 status
+✗ "status.ok"  # 只有 2 段，但 > 要求至少 3 段
+```
+
+## 匹配规则
+
+### 基本规则
+
+1. **段分割** — 事件类型和模式都按 `.` 分割为段数组
+2. **逐段比较** — 从左到右逐段匹配：
+   - `*` 匹配任意一个段
+   - `>` 匹配剩余所有段（必须在末尾）
+   - 其他字符必须精确匹配
+3. **段数要求**：
+   - 没有 `>` 时，段数必须完全相等
+   - 有 `>` 时，事件段数必须 ≥ 模式段数
+
+### 匹配算法
+
+```python
+def match_parts(pattern_parts: tuple, event_parts: tuple) -> bool:
+    """NATS-style 通配符匹配"""
+    for i, p in enumerate(pattern_parts):
+        # > 匹配剩余所有段
+        if p == ">":
+            return i < len(event_parts)  # 至少要有一个段
+
+        # 事件段数不足
+        if i >= len(event_parts):
+            return False
+
+        # * 匹配任意段，其他必须精确匹配
+        if p != "*" and p != event_parts[i]:
+            return False
+
+    # 没有 > 时，段数必须相等
+    return len(pattern_parts) == len(event_parts)
+```
+
+### 匹配示例表
+
+| 模式 | 事件 | 匹配 | 说明 |
+|------|------|------|------|
+| `module.ready` | `module.ready` | ✓ | 精确匹配 |
+| `module.ready` | `module.offline` | ✗ | 第二段不匹配 |
+| `module.*` | `module.ready` | ✓ | `*` 匹配 `ready` |
+| `module.*` | `module.status.changed` | ✗ | 段数不等（2 vs 3） |
+| `module.>` | `module.ready` | ✓ | `>` 匹配 `ready` |
+| `module.>` | `module.status.changed` | ✓ | `>` 匹配 `status.changed` |
+| `*.status` | `module.status` | ✓ | `*` 匹配 `module` |
+| `*.status` | `module.status.changed` | ✗ | 段数不等（2 vs 3） |
+| `*.status.>` | `module.status.changed` | ✓ | `*` 匹配 `module`，`>` 匹配 `changed` |
+| `>` | `any.event.type` | ✓ | 匹配所有事件 |
+
+## 常见模式
+
+### 订阅所有事件
+
+```python
+订阅: ">"
+```
+
+### 订阅特定命名空间
+
+```python
+# 只订阅 module 命名空间下的所有事件
+订阅: "module.>"
+
+# 只订阅 watchdog 命名空间下的所有事件
+订阅: "watchdog.>"
+```
+
+### 订阅特定类型
+
+```python
+# 订阅所有模块的 ready 事件
+订阅: "*.ready"
+
+# 订阅所有模块的 status 相关事件
+订阅: "*.status.>"
+```
+
+### 订阅多个模式
+
+```python
+# 同时订阅多个模式
+订阅: ["module.ready", "module.offline", "watchdog.>"]
+```
+
+## 性能考虑
+
+### 匹配效率
+
+- **精确匹配** — O(n)，n 为段数
+- **`*` 通配符** — O(n)，逐段比较
+- **`>` 通配符** — O(n)，提前终止
+
+### 订阅建议
+
+1. **优先使用精确匹配** — 性能最好，语义最清晰
+2. **避免过度使用 `>`** — 会接收大量不需要的事件
+3. **合理使用 `*`** — 在需要灵活性时使用
+4. **避免订阅 `>`** — 除非确实需要所有事件
+
+### 路由优化
+
+EventHub 在路由时会：
+1. 遍历所有订阅者的模式列表
+2. 对每个模式进行匹配
+3. 匹配成功后立即 `break`，避免重复入队
+
+```python
+for module_id, patterns in subscriptions.items():
+    for pattern_str, pattern_parts in patterns:
+        if match_parts(pattern_parts, event_parts):
+            queues[module_id].put_nowait(event_json)
+            break  # 同一模块只入队一次
+```
+
+## 错误用法
+
+### `>` 不能在中间
+
+```python
+# ✗ 错误：> 只能在末尾
+订阅: "module.>.status"  # 无效模式
+
+# ✓ 正确：使用 * 代替
+订阅: "module.*.status"
+```
+
+### 段数不匹配
+
+```python
+订阅: "module.*"
+发布: "module.status.changed"
+结果: ✗ 不匹配（2 段 vs 3 段）
+
+# 如果需要匹配多层级，使用 >
+订阅: "module.>"
+发布: "module.status.changed"
+结果: ✓ 匹配
+```
+
+### 空段
+
+```python
+# ✗ 错误：空段无效
+订阅: "module..ready"  # 无效模式
+
+# ✓ 正确：使用有效的段名
+订阅: "module.status.ready"
+```
+
+## 与其他系统对比
+
+### NATS vs fnmatch
+
+| 特性 | NATS-style | fnmatch |
+|------|------------|---------|
+| 单段通配符 | `*` | `*` |
+| 多段通配符 | `>` (尾部) | `**` (任意位置) |
+| 段分隔符 | `.` | `/` 或 `.` |
+| 中间多段 | 不支持 | 支持 `a/**/b` |
+
+### 为什么选择 NATS-style
+
+1. **简单明确** — 只有两种通配符，规则清晰
+2. **性能优秀** — 匹配算法简单高效
+3. **行业标准** — NATS 是成熟的消息系统，规范经过验证
+4. **足够灵活** — 覆盖绝大多数事件订阅场景
+
+## 参考实现
+
+- 匹配算法：`kernel/router.py` — `match_parts()` 函数
+- 路由逻辑：`kernel/event_hub.py` — `_route_event()` 方法
+- 订阅管理：`kernel/event_hub.py` — `handle_subscribe()` 方法
+
+## 相关文档
+
+- [事件处理机制](./事件处理机制.md) — 完整的事件系统说明
+- [模块规范](./Kite框架设计/04-模块规范.md) — 模块如何订阅事件

package/docs//344/272/213/344/273/266/351/230/237/345/210/227/345/274/271/346/200/247/347/256/241/347/220/206.md

@@ -0,0 +1,449 @@
+# 事件队列弹性管理
+
+## 概述
+
+Kernel 为每个连接维护独立的事件队列（`asyncio.Queue(maxsize=10000)`）。当模块消费速度跟不上事件产生速度时，队列压力升高，需要一套渐进式的管理机制来保护系统稳定性。
+
+核心设计哲学：**协商式**——Kernel 根据队列压力主动通知模块，由模块自行决定如何降压，而非 Kernel 单方面丢弃或断开。
+
+## 队列限制（双重指标）
+
+每个连接的队列有两个独立限制：
+
+- **消息数量限制**：10,000 条消息
+- **字节大小限制**：10 MB
+
+压力评定时取两者中**较高的使用率**作为综合压力指标。
+
+示例：
+- 队列有 3,000 条消息（30% 使用率）
+- 队列占用 7 MB（70% 使用率）
+- **综合压力 = 70%**（取较高者）→ 触发 `overload` 级别
+
+## 模块能力声明
+
+模块发送 `module.ready` 事件时，通过 `queue_elastic` 字段声明是否支持弹性队列管理：
+
+```json
+{
+  "event": "module.ready",
+  "data": {
+    "module_id": "web",
+    "queue_elastic": true
+  }
+}
+```
+
+- **支持（`queue_elastic: true`）**：完整压力管理——四级压力等级、压力通知、分级丢弃、消息压缩、60 秒倒计时
+- **不支持（未声明或 `false`）**：极简策略——无压力等级、无压力通知、无分级丢弃、无压缩，先进先发溢出即丢，队列使用率 ≥ 85% 时启动 30 秒倒计时
+
+**注意：** 压力通知事件（`system.queue_pressure`）仅发送给弹性模块。警告事件（`system.queue_warning`）在倒计时期间发送给所有模块。这些事件由 Kernel 直接发送到目标模块的队列，**不需要模块订阅**。
+
+Kernel 在 `RegistryStore.set_ready()` 中提取并存储此标记。
+
+## 压力分级（仅弹性模块）
+
+四级压力等级，基于队列使用率（消息数量和字节大小取较高者）。**仅对声明了 `queue_elastic: true` 的模块生效**，非弹性模块不计算压力等级。
+
+| 等级 | 中文 | 升级阈值 | 降级阈值 | Kernel 行为 |
+|------|------|---------|---------|------------|
+| **idle** | 空闲 | — | <20% | 正常路由 |
+| **busy** | 繁忙 | >30% | <20% | 发送压力通知 |
+| **overload** | 过载 | >60% | <45% | 通知 + 丢弃 `droppable` 事件 |
+| **critical** | 极限 | >85% | <70% | 通知 + 启动压缩 + 全部非系统事件丢弃 + 启动倒计时 |
+
+升降级使用不同阈值（滞回防抖），防止在边界值附近频繁抖动。
+
+## 事件可丢弃标记
+
+模块发布事件时可通过 `droppable` 字段声明该事件在压力大时可被丢弃：
+
+```json
+{
+  "method": "event.publish",
+  "params": {
+    "event": "stats.update",
+    "droppable": true,
+    "data": { ... }
+  }
+}
+```
+
+- 未标记的事件默认不可丢弃（向后兼容）
+- 系统事件（`module.offline`、`module.ready`、`module.shutdown`）永远不可丢弃
+- `overload` 时只丢弃 `droppable: true` 的事件
+- `critical` 时除系统事件外全部丢弃（或压缩）
+
+`publish_internal()` 发出的事件不允许标记 `droppable`。
+
+## 会话序列号机制
+
+### 目的
+
+让客户端能够检测消息丢失（gap 检测），而不仅仅是被动接收压力通知。
+
+### 实现
+
+每个连接维护独立的会话状态：
+
+- **session_id**：连接建立时生成的 UUID，标识当前会话
+- **seq**：会话序列号，从 1 开始递增，每发送一条事件 +1
+
+每条事件消息包含：
+
+```json
+{
+  "method": "event",
+  "params": {
+    "event_id": "evt_xxx",
+    "event": "phone.call.update",
+    "seq": 42,
+    "session_id": "a1b2c3d4-...",
+    "data": { ... }
+  }
+}
+```
+
+### 认证响应
+
+客户端认证成功后，Kernel 返回当前会话信息：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "auth-1",
+  "result": {
+    "ok": true,
+    "session_id": "a1b2c3d4-...",
+    "seq": 0
+  }
+}
+```
+
+### 客户端 Gap 检测
+
+客户端维护 `lastSeq`，收到事件时检查：
+
+```javascript
+if (seq > lastSeq + 1) {
+    // 检测到 gap：期望 lastSeq+1，但收到了 seq
+    onGap({
+        expected: lastSeq + 1,
+        received: seq,
+        missing: seq - lastSeq - 1
+    });
+}
+lastSeq = seq;
+```
+
+### 会话变更检测
+
+Kernel 重启后会生成新的 `session_id`，客户端检测到变更时应重新同步状态：
+
+```javascript
+if (oldSessionId && newSessionId !== oldSessionId) {
+    onSessionChange({
+        oldSession: oldSessionId,
+        newSession: newSessionId,
+        reason: 'server_restart'
+    });
+    // 重新同步状态
+    client.rpc('registry.get_all').then(rebuildUI);
+}
+```
+
+## 消息压缩机制（仅弹性模块，Critical 级别）
+
+### 触发条件
+
+仅在弹性模块的 **critical 级别（85%+ 使用率）** 时启用压缩。非弹性模块不触发压缩。
+
+压缩是临近极限时的最后手段，类似信息损失，只在即将强制断开连接前使用。
+
+### 压缩逻辑
+
+在 `_sender_loop` 发送时检查压力，如果达到 critical 级别：
+
+1. 从队列中取出多条可压缩消息（最多 100 条或 100KB）
+2. 遇到不可压缩消息（系统事件、压力事件）时停止
+3. 生成 `system.events_compressed` 摘要事件
+4. 发送摘要，继续下一轮
+
+### 压缩摘要格式
+
+```json
+{
+  "event": "system.events_compressed",
+  "seq": 150,
+  "session_id": "a1b2c3d4-...",
+  "data": {
+    "module_id": "web",
+    "compressed_count": 87,
+    "event_types": {
+      "phone.call.update": 60,
+      "sms.received": 20,
+      "stats.update": 7
+    },
+    "sources": {
+      "phone_channel": 80,
+      "sms_channel": 7
+    },
+    "seq_range": [103, 149],
+    "level": "critical",
+    "total_bytes": 95432
+  }
+}
+```
+
+### 序列号连续性
+
+压缩摘要本身也有序列号，客户端收到后更新 `lastSeq` 到 `seq_range[1]`，跳过压缩范围，不会误报 gap。
+
+### 压缩效果
+
+- **减少传输数据量**：87 条完整事件 → 1 条摘要（只有统计信息）
+- **加快发送速度**：发送 1 条小消息比发送 87 条大消息快得多
+- **间接排空队列**：因为发送速度变快，队列排空速度加快
+- **保留关键信息**：虽然丢失详细数据，但保留事件类型统计和来源信息
+
+## 压力通知事件
+
+### `system.queue_pressure`（仅弹性模块）
+
+**仅发送给声明了 `queue_elastic: true` 的模块。** 非弹性模块不会收到此事件。
+
+**发送时机：**
+
+| 压力等级 | 通知频率 |
+|---------|---------|
+| **idle** | 仅在等级变化时发送 |
+| **busy** | 首次进入时发送 + 每 3 秒定期发送 |
+| **overload** | 首次进入时发送 + 每 3 秒定期发送 |
+| **critical** | 首次进入时发送 + 每 3 秒定期发送 |
+
+进入 busy 及以上级别后，Kernel 会启动定期提醒任务，每 3 秒发送一次当前状态通知，直到压力回落到 idle。
+
+**通知格式：**
+
+等级变化时：
+
+```json
+{
+  "event": "system.queue_pressure",
+  "data": {
+    "module_id": "web",
+    "level": "overload",
+    "old_level": "busy",
+    "direction": "upgrade",  // "upgrade" | "downgrade" | null
+
+    // 消息数量
+    "queue_size": 7500,
+    "queue_max": 10000,
+    "count_usage_percent": 75.0,
+
+    // 字节大小
+    "queue_bytes": 8388608,
+    "queue_max_bytes": 10485760,
+    "bytes_usage_percent": 80.0,
+
+    // 综合使用率（取较高者）
+    "usage_percent": 80.0,
+    "suggestion": "减少事件发送"
+  }
+}
+```
+
+定期提醒时（无变化）：
+
+```json
+{
+  "event": "system.queue_pressure",
+  "data": {
+    "module_id": "web",
+    "level": "busy",
+    "old_level": "busy",
+    "direction": null,  // 无变化
+    "usage_percent": 35.0,
+    "suggestion": "注意队列压力"
+    // ... 其他字段同上
+  }
+}
+```
+
+**字段说明：**
+
+- `level`: 当前压力等级
+- `old_level`: 之前的压力等级（首次通知时为 `null`）
+- `direction`: 变化方向
+  - `"upgrade"`: 压力升级
+  - `"downgrade"`: 压力降级
+  - `null`: 无变化（定期提醒）
+- `queue_size` / `queue_max`: 消息数量及上限
+- `count_usage_percent`: 消息数量使用率
+- `queue_bytes` / `queue_max_bytes`: 字节大小及上限
+- `bytes_usage_percent`: 字节使用率
+- `usage_percent`: 综合使用率（取两者较高值）
+- `suggestion`: 人类可读的建议（15 字以内）
+
+`suggestion` 取值：
+- `"正常发送"` — idle，可以正常发送
+- `"注意队列压力"` — busy，不建议增加压力
+- `"减少事件发送"` — overload，建议减小压力
+- `"立即停止发送"` — critical，立即停止
+
+此事件作为系统事件直接发送到目标模块队列，不受压力过滤影响。
+
+### `system.queue_warning`（所有模块）
+
+倒计时期间的警告事件，弹性和非弹性模块都会收到：
+
+```json
+{
+  "event": "system.queue_warning",
+  "data": {
+    "module_id": "web",
+    "remaining_seconds": 20,
+    "reason": "queue_critical_timeout",
+    "message": "Queue pressure critical, will disconnect in 20s"
+  }
+}
+```
+
+## 弹性模块 vs 非弹性模块——差异化对比
+
+| 特性 | 弹性模块 (`queue_elastic: true`) | 非弹性模块 (默认) |
+|------|--------------------------------|-----------------|
+| **队列上限** | 10,000 条 / 10 MB | 10,000 条 / 10 MB（相同） |
+| **压力等级** | idle → busy → overload → critical | 无（不计算） |
+| **压力通知** | 等级变化 + 每 3 秒定期提醒 | 无 |
+| **分级丢弃** | overload 丢 droppable，critical 丢非系统 | 无（溢出才丢） |
+| **压缩** | critical 时压缩 | 无 |
+| **丢弃策略** | 按压力等级分级丢弃 | 先进先发，队列满时丢弃新消息 |
+| **倒计时触发** | 压力等级达到 critical | 队列使用率 ≥ 85% |
+| **倒计时时长** | 60 秒 | 30 秒 |
+| **倒计时退出** | 压力等级降到 overload 以下 | 队列使用率降到 85% 以下 |
+| **警告事件** | `system.queue_warning`（倒计时中每 5 秒） | `system.queue_warning`（倒计时中每 5 秒） |
+| **序列号** | ✅ | ✅（通用机制） |
+
+### 非弹性模块的极简策略
+
+非弹性模块不会收到 `system.queue_pressure` 事件，也不会触发分级丢弃或消息压缩。
+
+| 阶段 | 行为 |
+|------|------|
+| 队列未满 | 正常入队，先进先发 |
+| 队列满（`QueueFull`） | 丢弃新消息 |
+| 队列使用率 ≥ 85% | 启动 30s 倒计时 |
+| 倒计时期间 | 每 5s 发送 `system.queue_warning` 事件 |
+| 使用率降到 85% 以下 | 取消倒计时 |
+| 倒计时归零 | 断开 WebSocket 连接（close code 4011, reason: "queue_pressure_critical"） |
+
+### 弹性模块的完整策略
+
+弹性模块享受完整的压力管理机制：
+
+| 阶段 | 行为 |
+|------|------|
+| 队列达到 `critical` | 压缩 + 丢弃非系统事件 + 启动 60s 倒计时 |
+| 倒计时期间 | 每 5s 发送 `system.queue_warning` 事件 |
+| 压力回落到 overload 以下 | 取消倒计时 |
+| 倒计时归零 | 断开 WebSocket 连接（close code 4011, reason: "queue_pressure_critical"） |
+
+## 检测时机
+
+在 `_enqueue_with_pressure()` 中每次入队时，根据模块类型走不同路径：
+
+**弹性模块：**
+1. 检查字节限制（`current_bytes + msg_size > QUEUE_MAX_BYTES`）
+2. 检查压力等级（`_calc_pressure_level()` 计算消息数量和字节使用率，取较高者）
+3. 等级变化时触发通知（`_on_pressure_change`）
+4. 根据压力等级决定是否丢弃（`_should_drop`）
+
+**非弹性模块：**
+1. 直接 `put_nowait` 入队，`QueueFull` 时丢弃新消息
+2. 入队后检查队列使用率，≥ 85% 时启动 30 秒倒计时
+
+`qsize()` 和字节计数都是 O(1) 操作，零额外开销。
+
+## 统计暴露
+
+`get_stats()` 和 `get_health()` 返回每模块的压力信息：
+
+```json
+{
+  "queue_pressure": {
+    "web": {
+      "level": "busy",
+      "usage_percent": 35,
+      "queue_size": 3500,
+      "queue_bytes": 3670016,
+      "count_usage_percent": 35.0,
+      "bytes_usage_percent": 35.0
+    },
+    "watchdog": {
+      "level": "idle",
+      "usage_percent": 0,
+      "queue_size": 0,
+      "queue_bytes": 0
+    }
+  }
+}
+```
+
+## 改造范围
+
+| 文件 | 改动 |
+|------|------|
+| `kernel/event_hub.py` | 核心：字节计数、压力检测、分级、`droppable` 过滤、通知、倒计时、压缩、序列号、stats 暴露 |
+| `kernel/registry_store.py` | `set_ready()` 存储 `queue_elastic` 标记 |
+| `kernel/rpc_router.py` | `_event_publish()` 提取 `droppable` 透传 |
+| `kernel/server.py` | 认证响应返回 `session_id` 和 `seq`；`publish_ready()` 声明 `queue_elastic`；断开时清理倒计时 |
+| `extensions/services/evol/static/js/kernel-client.js` | 会话管理、序列号检测、gap 回调、压缩事件处理 |
+
+新增系统事件：`system.queue_pressure`、`system.queue_warning`、`system.events_compressed`
+
+## 客户端使用示例
+
+```javascript
+// 监听消息丢失
+client.onGap = (gapInfo) => {
+    console.warn(`检测到 ${gapInfo.missing} 个事件丢失`);
+    if (gapInfo.missing > 10) {
+        // 丢失较多，重新同步状态
+        client.rpc('registry.get_all').then(rebuildUI);
+    }
+};
+
+// 监听会话变更（服务端重启）
+client.onSessionChange = (info) => {
+    console.log('服务端重启，重新同步状态');
+    client.rpc('registry.get_all').then(rebuildUI);
+};
+
+// 监听压缩事件
+client.on('system.events_compressed', (data) => {
+    console.log(`压缩了 ${data.compressed_count} 个事件`);
+    // 根据压缩的事件类型决定响应策略
+    if (data.event_types['phone.call.update'] > 10) {
+        client.rpc('phone.get_active_calls').then(updateCallList);
+    }
+});
+
+// 监听压力通知
+client.on('system.queue_pressure', (data) => {
+    if (data.direction === 'upgrade') {
+        console.warn(`⚠️ 压力升级: ${data.old_level} → ${data.level}`);
+        // 减少发送频率
+        slowDownSending();
+    } else if (data.direction === 'downgrade') {
+        console.log(`✅ 压力降级: ${data.old_level} → ${data.level}`);
+        // 可以恢复正常发送
+        if (data.level === 'idle') {
+            resumeNormalSending();
+        }
+    } else if (data.direction === null && data.level !== 'idle') {
+        // 定期提醒（无变化）
+        console.log(`📊 当前压力: ${data.level} (${data.usage_percent}%)`);
+    }
+});
+```