@agentunion/kite 1.4.0 → 1.6.0

package/docs//344/272/213/344/273/266/345/244/204/347/220/206/346/234/272/345/210/266.md

@@ -0,0 +1,388 @@
+# Kite 事件处理机制
+
+## 概述
+
+Kite 的事件系统基于发布-订阅模式，所有模块通过 Kernel 的 EventHub 进行事件通信。事件流转采用统一的队列缓冲架构，确保高并发场景下的稳定性和可靠性。
+
+## 核心架构
+
+### 事件流转路径
+
+```
+发布者 → EventHub 路由 → 订阅者队列 → 消费循环 → 事件处理
+```
+
+所有模块（包括 Kernel 自身）都遵循相同的流程：
+
+1. **事件发布** — 模块通过 RPC 或内部调用发布事件
+2. **事件路由** — EventHub 根据订阅关系匹配目标模块
+3. **队列缓冲** — 事件序列化为 JSON-RPC 2.0 格式并入队
+4. **异步消费** — 每个模块的独立消费循环从队列取出事件
+5. **事件处理** — 模块接收并处理事件
+
+### 架构特点
+
+- **统一队列** — 所有模块（包括 Kernel）都有独立的事件队列
+- **异步消费** — 每个模块有独立的消费循环，互不阻塞
+- **背压控制** — 队列满时自动阻塞发送者，防止内存溢出
+- **异常隔离** — 单个模块的处理异常不影响其他模块
+
+## 事件格式
+
+### JSON-RPC 2.0 Notification
+
+所有事件都使用 JSON-RPC 2.0 Notification 格式：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event_id": "uuid-string",
+    "event": "event.type",
+    "source": "module_id",
+    "timestamp": "2026-03-07T10:00:00+00:00",
+    "data": {}
+  }
+}
+```
+
+**字段说明：**
+- `event_id` — 事件唯一标识（UUID）
+- `event` — 事件类型（如 `module.ready`）
+- `source` — 发布者模块 ID
+- `timestamp` — 事件发布时间（ISO 8601 格式）
+- `data` — 事件数据（任意 JSON 对象）
+
+## 事件类型
+
+### 系统事件
+
+由 Kernel 发布的框架级事件：
+
+- `module.registered` — 模块注册成功
+- `module.ready` — 模块启动完成
+- `module.offline` — 模块下线
+- `module.heartbeat_timeout` — 模块心跳超时
+- `kernel.shutdown` — Kernel 即将关闭
+
+### 业务事件
+
+由各模块发布的业务逻辑事件，命名规范：`{namespace}.{action}`
+
+示例：
+- `watchdog.alert` — Watchdog 发出告警
+- `backup.completed` — 备份任务完成
+- `web.request` — Web 模块收到请求
+
+## 订阅机制
+
+### 订阅规则
+
+模块通过 `event.subscribe` RPC 方法订阅事件：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event.subscribe",
+  "params": {
+    "events": ["module.ready", "watchdog.*"]
+  },
+  "id": 1
+}
+```
+
+**通配符支持（NATS-style）：**
+- `*` — 匹配**恰好一个**段（segment）
+- `>` — 匹配**一个或多个**段（只能在末尾使用）
+
+### 匹配机制
+
+Kite 使用 **NATS-style 通配符匹配**，事件类型按 `.` 分割为多个段，然后逐段匹配。
+
+**精确匹配：**
+```python
+订阅: "module.ready"
+匹配: "module.ready" ✓
+不匹配: "module.offline" ✗
+```
+
+**单段通配符 `*`：**
+```python
+订阅: "module.*"
+匹配: "module.ready" ✓
+匹配: "module.offline" ✓
+不匹配: "module.status.changed" ✗  # 3 段，但模式只有 2 段
+不匹配: "watchdog.alert" ✗  # 第一段不匹配
+```
+
+**多段通配符 `>`（尾部）：**
+```python
+订阅: "module.>"
+匹配: "module.ready" ✓
+匹配: "module.offline" ✓
+匹配: "module.status.changed" ✓  # 匹配 module 后的所有段
+不匹配: "watchdog.alert" ✗  # 第一段不匹配
+
+订阅: ">"
+匹配: "module.ready" ✓
+匹配: "watchdog.alert" ✓
+匹配: "a.b.c.d.e" ✓  # 匹配所有事件
+```
+
+**组合使用：**
+```python
+订阅: "*.status.>"
+匹配: "module.status.changed" ✓
+匹配: "watchdog.status.ok" ✓
+匹配: "web.status.error.critical" ✓
+不匹配: "module.ready" ✗  # 第二段不是 status
+不匹配: "status.ok" ✗  # 只有 2 段，但模式要求至少 3 段
+```
+
+**匹配规则总结：**
+
+1. 事件类型和模式都按 `.` 分割为段数组
+2. 逐段比较：
+   - `*` 匹配任意一个段
+   - `>` 匹配剩余所有段（必须在末尾）
+   - 其他字符必须精确匹配
+3. `>` 之前的段数必须匹配，`>` 之后可以有任意多段
+4. 没有 `>` 时，段数必须完全相等
+
+**路由逻辑：**
+
+当事件发布时，EventHub 遍历所有订阅关系：
+
+```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.*", "module.ready"]
+发布: "module.ready"
+结果: 只收到 1 次事件（路由时遇到第一个匹配就 break）
+```
+
+### 订阅生命周期
+
+1. **注册时订阅** — 模块在 `boot_info` 中声明初始订阅
+2. **运行时订阅** — 通过 RPC 动态添加订阅
+3. **取消订阅** — 通过 `event.unsubscribe` RPC 取消订阅
+4. **自动清理** — 模块下线时自动清理所有订阅
+
+## 发布机制
+
+### 外部模块发布
+
+通过 `event.publish` RPC 方法：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event.publish",
+  "params": {
+    "event": "watchdog.alert",
+    "data": {
+      "level": "warning",
+      "message": "CPU usage high"
+    }
+  },
+  "id": 2
+}
+```
+
+### Kernel 内部发布
+
+Kernel 通过 `publish_internal()` 方法直接发布：
+
+```python
+self.event_hub.publish_internal("module.ready", {
+    "module_id": "kernel",
+    "ws_endpoint": "ws://127.0.0.1:8080/ws"
+}, source="kernel")
+```
+
+## 队列与背压
+
+### 队列配置
+
+每个模块的事件队列默认配置：
+
+- **队列大小** — 1000 条消息
+- **溢出策略** — 阻塞发送者（背压）
+- **消费模式** — 异步 FIFO
+
+### 背压机制
+
+当队列满时：
+
+1. `queue.put_nowait()` 抛出 `asyncio.QueueFull` 异常
+2. EventHub 捕获异常并记录溢出计数
+3. 发送者被阻塞，等待队列有空位
+4. 消费者处理完事件后，队列自动释放空位
+
+### 性能特征
+
+- 支持每秒 10,000+ 事件的高并发场景
+- 队列满时自动背压，防止内存溢出
+- 统一的溢出跟踪和告警机制
+
+## 消费循环
+
+### 外部模块消费
+
+通过 WebSocket 接收事件：
+
+```python
+async def _ws_receiver(self):
+    async for msg in self.ws:
+        data = json.loads(msg.data)
+        if data.get("method") == "event":
+            params = data["params"]
+            event_type = params["event"]
+            event_data = params["data"]
+            await self._handle_event(event_type, event_data)
+```
+
+### Kernel 内部消费
+
+通过回调函数处理事件：
+
+```python
+async def _callback_sender_loop(self, mid: str, callback: callable, queue: asyncio.Queue):
+    while True:
+        raw = await queue.get()
+        msg = json.loads(raw)
+        params = msg["params"]
+        event_type = params["event"]
+        data = params["data"]
+        await callback(event_type, data)
+```
+
+## 异常处理
+
+### 消费异常隔离
+
+单个模块的事件处理异常不影响其他模块：
+
+```python
+try:
+    await callback(event_type, data)
+except Exception as e:
+    print(f"[kernel] Internal callback error for {mid} on {event_type}: {e}")
+    traceback.print_exc()
+```
+
+### 路由异常处理
+
+EventHub 路由过程中的异常会被捕获并记录：
+
+```python
+try:
+    queue.put_nowait(raw_json)
+except asyncio.QueueFull:
+    self._cnt_overflow += 1
+    print(f"[kernel] Queue full for {mid}, event dropped")
+```
+
+## 事件去重
+
+### 去重策略
+
+EventHub 对外部模块发布的事件进行去重：
+
+- **去重窗口** — 最近 1000 个事件
+- **去重键** — `(source, event_type, data_hash)`
+- **去重逻辑** — 相同键的事件在窗口内只处理一次
+
+### 内部事件不去重
+
+Kernel 发布的内部事件（如 `module.ready`）不进行去重检查，因为这些事件天然唯一。
+
+## 优雅退出
+
+### 退出流程
+
+1. **发送 shutdown 事件** — Kernel 向所有模块广播 `kernel.shutdown`
+2. **等待 ack** — 模块收到后回复 `shutdown.ack`
+3. **等待 exiting** — 模块清理完成后发送 `module.exiting`
+4. **强制超时** — 超时后强制终止未响应的模块
+
+### 事件序列
+
+```
+Kernel → module.shutdown (broadcast)
+Module → shutdown.ack (targeted)
+Module → module.exiting (broadcast)
+Kernel → 清理资源并退出
+```
+
+## 调试与监控
+
+### 事件统计
+
+EventHub 提供实时统计：
+
+```python
+{
+    "received": 1234,      # 接收事件总数
+    "routed": 5678,        # 路由事件总数
+    "overflow": 0,         # 队列溢出次数
+    "subscribers": {       # 订阅者列表
+        "watchdog": ["module.ready", "kernel.shutdown"],
+        "web": ["**"]
+    }
+}
+```
+
+### 日志输出
+
+事件系统的关键操作都会输出日志：
+
+```
+[kernel] Event received: module.ready from watchdog
+[kernel] Routing to 3 subscribers: web, backup, model_service
+[kernel] Queue full for web, event dropped
+```
+
+## 最佳实践
+
+### 事件命名
+
+- 使用小写字母和点号分隔（如 `module.ready`）
+- 命名空间与模块 ID 一致（如 `watchdog.alert`）
+- 动作使用过去时（如 `completed`）或现在时（如 `ready`）
+
+### 订阅粒度
+
+- 优先订阅具体事件类型，避免过度使用通配符
+- 只订阅必要的事件，减少不必要的消息传递
+- 使用 `*` 而非 `**`，除非确实需要所有事件
+
+### 数据大小
+
+- 事件数据应保持精简，避免传递大对象
+- 大数据应通过文件路径或 URL 引用，而非直接嵌入
+- 单个事件数据建议不超过 10KB
+
+### 异常处理
+
+- 事件处理函数必须捕获所有异常，避免崩溃
+- 关键事件处理失败时应记录日志并告警
+- 不要在事件处理中执行长时间阻塞操作
+
+## 参考实现
+
+- EventHub 核心实现：`core/kernel/event_hub.py`
+- 模块订阅示例：`extensions/services/watchdog/entry.py`
+- 事件发布示例：`extensions/services/web/entry.py`

package/docs//344/272/213/344/273/266/345/244/204/347/220/206/350/247/204/350/214/203.md

@@ -0,0 +1,113 @@
+# 事件处理规范
+
+## 系统广播事件
+
+以下事件会自动广播给所有连接的模块（无论是否订阅），模块收到这些事件是正常的：
+
+```python
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready",           # 模块就绪
+    "module.registered",      # 模块已注册
+    "module.started",         # 模块已启动
+    "module.stopped",         # 模块已停止
+    "module.crashed",         # 模块崩溃
+    "module.exiting",         # 模块正在退出
+    "module.offline",         # 模块离线
+    "module.shutdown.ack",    # 模块确认关闭
+    "module.shutdown.ready",  # 模块关闭就绪
+    "system.ready",           # 系统就绪
+    "registry.updated",       # 注册表更新
+}
+```
+
+## 三层处理模式
+
+所有模块的事件处理应遵循以下三层模式：
+
+### Layer 1: 处理订阅的事件（业务逻辑）
+
+模块只处理自己订阅的事件，每个事件都应有明确的处理逻辑。
+
+### Layer 2: 忽略系统广播事件（静默）
+
+对于 `SYSTEM_BROADCAST_EVENTS` 中的事件，如果模块不需要处理，应静默忽略（不打印日志）。
+
+### Layer 3: 警告未知事件（可选）
+
+对于既不在订阅列表、也不在系统广播列表的事件，可以打印警告（开发环境）或静默忽略（生产环境）。
+
+## 标准实现模板
+
+### 核心模块（Kernel、Watchdog）
+
+```python
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready", "module.registered", "module.started", "module.stopped",
+    "module.crashed", "module.exiting", "module.offline",
+    "module.shutdown.ack", "module.shutdown.ready",
+    "system.ready", "registry.updated",
+}
+
+async def _handle_event(event_type: str, data: dict):
+    # Layer 1: 处理订阅的事件
+    if event_type == "module.shutdown":
+        await handle_shutdown(data)
+        return
+    elif event_type == "module.started":
+        await handle_module_started(data)
+        return
+    # ... 其他订阅的事件
+
+    # Layer 2: 忽略系统广播事件
+    elif event_type in SYSTEM_BROADCAST_EVENTS:
+        pass
+
+    # Layer 3: 警告未知事件
+    else:
+        print(f"[module] Warning: Received unhandled event: {event_type}")
+```
+
+### 简单模块（Backup、Web、Assistant、ACP Channel）
+
+```python
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready", "module.registered", "module.started", "module.stopped",
+    "module.crashed", "module.exiting", "module.offline",
+    "module.shutdown.ack", "module.shutdown.ready",
+    "system.ready", "registry.updated",
+}
+
+async def _handle_event_notification(msg: dict):
+    params = msg.get("params", {})
+    event_type = params.get("event", "")
+    data = params.get("data", {})
+
+    # Layer 1: 处理订阅的事件
+    if event_type == "module.shutdown":
+        await _handle_shutdown(data)
+        return
+
+    # Layer 2: 忽略系统广播事件
+    if event_type in SYSTEM_BROADCAST_EVENTS:
+        return
+
+    # Layer 3: 警告未知事件（仅开发环境）
+    if os.environ.get("KITE_ENV") == "development":
+        print(f"[module] Debug: Unhandled event: {event_type}")
+```
+
+## 实施优先级
+
+1. **Kernel**（已完成）
+2. **Watchdog**（复杂业务逻辑，需要保留完整的 if-elif 分支）
+3. **Web**（需要转发部分事件到前端）
+4. **Backup**（简单模块）
+5. **Assistant**（简单模块）
+6. **ACP Channel**（简单模块）
+
+## 注意事项
+
+1. **不要删除有用的日志**：如果模块需要记录某些事件（如 Backup 记录所有事件），保留日志打印
+2. **保持一致性**：所有模块使用相同的 `SYSTEM_BROADCAST_EVENTS` 定义
+3. **开发环境调试**：可以在 Layer 3 添加 `KITE_ENV == "development"` 条件，方便调试
+4. **文档同步**：新增系统事件时，更新本文档的 `SYSTEM_BROADCAST_EVENTS` 列表