@agentunion/kite 1.4.0 → 1.6.0

package/.claude/skills/kite/checklists/feature-checklist.md

@@ -0,0 +1,496 @@
+# 特性检查清单
+
+本清单供「生成新模块」「适配现有项目」「审查现有模块」三条主线共用。
+
+---
+
+## 一、module.md 规范性
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 1.1 | name 字段存在且合法 | 🔴 致命 | 只允许 `[a-zA-Z0-9_-]` |
+| 1.2 | type 字段值合法 | 🔴 致命 | service / channel / agent |
+| 1.3 | runtime 字段值合法 | 🔴 致命 | python / node / binary |
+| 1.4 | entry 字段指向存在的文件 | 🔴 致命 | 如 entry.py 必须存在 |
+| 1.5 | version 用引号包裹 | 🟡 警告 | `'1.0'` 而非 `1.0`（避免被解析为浮点数） |
+| 1.6 | max_connections 在 [1, 10] 范围内 | 🟡 警告 | 超出会被钳位 |
+| 1.7 | max_instances 在 [1, 10] 范围内 | 🟡 警告 | > 10 会被安全阀重置为 1 |
+| 1.8 | 未使用死字段 | 🟢 建议 | 不要用 connection_elastic / graceful_shutdown / tools |
+| 1.9 | events 声明与代码中 publish 的事件一致 | 🟡 警告 | 声明了但没发布 = 误导 |
+| 1.10 | subscriptions 声明与代码中 subscribe 的事件一致 | 🟡 警告 | 同上 |
+
+---
+
+## 二、entry.py 标准模式
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 2.1 | 正确读取 module.md YAML frontmatter | 🔴 致命 | 使用 `---` 分隔符提取 |
+| 2.2 | 验证 name 字段合法性 | 🔴 致命 | 正则 `[a-zA-Z0-9_-]+` |
+| 2.3 | 安全 I/O 包装（_SafeWriter） | 🟡 警告 | 防止 BrokenPipeError 崩溃 |
+| 2.4 | 覆盖 builtins.print 为带时间戳版本 | 🟢 建议 | 便于调试 |
+| 2.5 | 日志目录创建（latest.log + daily） | 🟡 警告 | 路径：`{KITE_MODULE_DATA}/log/` |
+| 2.6 | 崩溃日志（crashes.jsonl） | 🟡 警告 | 含 timestamp, module, traceback, platform |
+| 2.7 | 设置 sys.excepthook | 🟡 警告 | 捕获未处理异常 |
+| 2.8 | 设置 threading.excepthook | 🟢 建议 | 捕获线程中的异常 |
+| 2.9 | 正确读取 stdin boot_info | 🔴 致命 | 一行 JSON：token + max_instances |
+| 2.10 | 检查 error 消息 | 🔴 致命 | boot_info 中有 error 字段时 exit(1) |
+| 2.11 | 验证 token 非空 | 🔴 致命 | 空 token 必须退出 |
+| 2.12 | 支持本地模式（KITE_KERNEL_PORT） | 🔴 致命 | 读取环境变量获取端口 |
+| 2.13 | 支持远程模式（KITE_GATEWAY_URL） | 🟢 可选 | 生产环境需要 |
+| 2.14 | HTTP 服务端口绑定（如适用） | 🟡 警告 | 尝试 preferred → +1 → +2 → OS 分配 |
+| 2.15 | uvicorn 启动配置正确（如适用） | 🟡 警告 | 传入预绑定 socket |
+
+---
+
+## 三、server.py WebSocket 连接
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 3.1 | 认证消息格式正确 | 🔴 致命 | `{jsonrpc, id, method: "auth", params: {token}}` |
+| 3.2 | 认证超时处理（5 秒） | 🟡 警告 | Kernel 在 5 秒后断开 |
+| 3.3 | 认证失败码正确处理 | 🟡 警告 | 4001/4003/4010 不重试，4020 等 10 秒 |
+| 3.4 | 等待 system.require_init 再初始化 | 🔴 致命 | 不能认证后直接初始化 |
+| 3.5 | 初始化顺序正确 | 🔴 致命 | subscribe → register → publish ready |
+| 3.5b | ⚠️ module.ready 必须包含 graceful_shutdown | 🔴 致命 | `{"module_id": ..., "graceful_shutdown": True, "startup_time": ..., "reason": "startup"}` 缺少会被 Launcher 直接杀进程！ |
+| 3.6 | 重连逻辑：指数退避 + 抖动 | 🟡 警告 | 0.3s → 5s max，max 10 retries |
+| 3.7 | Windows 连接拒绝处理 | 🟡 警告 | 处理 WinError 1225 |
+| 3.8 | 断开时清理 pending_rpc | 🟡 警告 | 避免 future 永久挂起 |
+
+---
+
+## 四、server.py 消息接收循环
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 4.1 | 正确区分三类消息 | 🔴 致命 | RPC 请求(method+id) / 事件(method无id) / RPC 响应(id+result) |
+| 4.2 | ⚠️ RPC 请求用 create_task 而非 await | 🔴 致命 | 避免死锁！这是最常见的严重 bug |
+| 4.3 | 事件通知用 create_task | 🟡 警告 | 避免阻塞接收循环 |
+| 4.4 | RPC 响应可以同步处理 | 🟢 信息 | 只是 resolve future |
+
+---
+
+## 五、server.py RPC 处理
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 5.1 | _rpc_call 正确生成 UUID id | 🔴 致命 | 用 `str(uuid.uuid4())` |
+| 5.2 | _rpc_call 有超时机制 | 🟡 警告 | 默认 3 秒 |
+| 5.3 | 超时后 pop pending_rpc | 🟡 警告 | 防止内存泄漏 |
+| 5.4 | fire-and-forget 用 wait_response=False | 🟡 警告 | event.publish 不等响应 |
+| 5.5 | RPC handler 去掉方法前缀 | 🟡 警告 | `my_module.health` → `health` |
+| 5.6 | 未知方法返回 -32601 错误 | 🟡 警告 | 不能静默忽略 |
+| 5.7 | handler 异常返回 -32603 错误 | 🟡 警告 | 包装 try-except |
+| 5.8 | 实现 health 方法 | 🔴 致命 | 返回 status + uptime |
+| 5.9 | 实现 status 方法 | 🟡 警告 | 返回模块状态信息 |
+
+---
+
+## 六、server.py 事件处理
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 6.1 | 处理 system.require_init | 🔴 致命 | 触发 _do_init |
+| 6.2 | 处理 system.ping → 回复 pong | 🟡 警告 | 不回复会被标记为不健康 |
+| 6.3 | 处理 module.shutdown | 🟡 警告 | 触发优雅关闭 |
+| 6.4 | _publish_event 格式正确 | 🔴 致命 | 包含 event_id + event + data |
+| 6.5 | 事件名格式正确 | 🟡 警告 | `{module_name}.{event_type}` |
+| 6.6 | event.subscribe 在 register 之前 | 🟡 警告 | 否则可能漏收事件 |
+
+---
+
+## 六b、健康检查（health RPC）
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 6b.1 | health RPC 方法已注册 | 🔴 致命 | 在 handlers 分发表和 registry.register 中都要有 |
+| 6b.2 | 响应包含 `healthy` 顶层字段 | 🔴 致命 | bool 类型，Watchdog 唯一判据 |
+| 6b.3 | 响应包含 `framework` 字段 | 🟡 警告 | uptime, connections, pending_rpc, active_handlers, handler_capacity, pressure, memory_mb |
+| 6b.4 | 响应包含 `business` 字段 | 🟡 警告 | healthy(bool) + message(string) + details(list) |
+| 6b.5 | business.healthy 有实际判断逻辑 | 🟡 警告 | 不能永远返回 true，应检查关键业务资源 |
+| 6b.6 | health handler 不做耗时操作 | 🟡 警告 | 只查状态不做计算，5 秒超时会被误判为不健康 |
+| 6b.7 | framework.pressure 计算正确 | 🟢 建议 | idle/normal/overload/critical 四级 |
+| 6b.8 | psutil 缺失时降级处理 | 🟢 建议 | memory_mb 用 try-except 包裹 |
+
+---
+
+## 七、优雅关闭
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 7.1 | 设置 _shutting_down 标志 | 🟡 警告 | 阻止后续操作 |
+| 7.2 | 发送 shutdown.ack | 🟡 警告 | 含 estimated_cleanup |
+| 7.3 | 发送 module.exiting | 🟡 警告 | 含 action |
+| 7.4 | 发送 shutdown.ready | 🟡 警告 | 清理完成通知 |
+| 7.5 | sleep(0.01) 后再关连接 | 🟢 建议 | 给 Kernel 处理时间 |
+| 7.6 | 先关附加连接再关主连接 | 🟡 警告 | 顺序不能反 |
+
+---
+
+## 八、多连接（如勾选）
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 8.1 | 处理 system.connection.offer | 🔴 致命 | 接受 slot token |
+| 8.2 | 使用 slot token 认证 | 🔴 致命 | 不是主 token |
+| 8.3 | 附加连接有独立接收循环 | 🔴 致命 | 消息处理逻辑相同 |
+| 8.4 | 处理 system.connection.release | 🟡 警告 | 释放连接 |
+| 8.5 | _extra_ws 和 _extra_ws_tasks 管理 | 🟡 警告 | 断开时清理 |
+| 8.6 | 关闭时先关附加连接 | 🟡 警告 | 在 shutdown 序列中 |
+
+---
+
+## 九、HTTP 服务（如勾选）
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 9.1 | FastAPI app 在 startup 中启动 WS 客户端 | 🔴 致命 | 用 create_task |
+| 9.2 | 端口绑定策略正确 | 🟡 警告 | preferred → +1 → +2 → OS |
+| 9.3 | uvicorn log_level 设为 warning | 🟢 建议 | 减少噪音 |
+| 9.4 | 注册时包含 port 和 base_url | 🟡 警告 | 其他模块需要知道 HTTP 地址 |
+| 9.5 | /health 端点存在 | 🟡 警告 | Watchdog 健康检查用 |
+| 9.6 | 静态文件挂载在所有路由之后 | 🟡 警告 | 否则会覆盖 API 路由 |
+
+---
+
+## 十、测试中心接入（如勾选前端页面）
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 10.1 | 测试文件存在 | 🔴 致命 | `tests/modules/{name}.js` |
+| 10.2 | 函数名与 window 注册一致 | 🔴 致命 | `testXxxModule` |
+| 10.3 | 映射表已更新 | 🔴 致命 | index.js 中 MODULE_TESTS |
+| 10.4 | script 标签已添加 | 🔴 致命 | 在 index.js 之前 |
+| 10.5 | 下拉选项已添加 | 🔴 致命 | `#test-module-select` |
+| 10.6 | 函数是 async | 🟡 警告 | 同步函数会挂起 |
+| 10.7 | 末尾有 runner.log('') | 🟢 建议 | 格式一致性 |
+
+---
+
+## 十一、日志规范
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 11.1 | latest.log 每次启动清空 | 🟡 警告 | 只含本次运行内容 |
+| 11.2 | daily log 按 YYYY-MM/YYYY-MM-DD.log 归档 | 🟢 建议 | 便于历史查看 |
+| 11.3 | crashes.jsonl 含完整信息 | 🟡 警告 | timestamp, module, traceback, platform |
+| 11.4 | crashes 有 daily 归档 | 🟢 建议 | crashes/YYYY-MM/YYYY-MM-DD.jsonl |
+| 11.5 | 多实例日志带后缀 | 🟡 警告 | latest~2.log（实例 > 1 时） |
+
+---
+
+## 十二、启动时间优化
+
+模块从进程启动到发布 `module.ready` 的完整路径，每一步都有优化空间。
+
+### 启动关键路径
+
+```
+进程启动
+  ↓ ① 模块级 import（Python 模块加载）
+  ↓ ② _load_module_config()（读 module.md YAML）
+  ↓ ③ _SafeWriter + logging 设置
+  ↓ ④ Server 类 import（⚠️ 最大瓶颈）
+  ↓ ⑤ stdin.readline()（阻塞等 Launcher 发 boot_info）
+  ↓ ⑥ Server 实例化
+  ↓ ⑦ asyncio.run / uvicorn.run
+  ↓ ⑧ WebSocket 连接 + auth
+  ↓ ⑨ 等待 system.require_init
+  ↓ ⑩ _do_init: subscribe → register → ready
+```
+
+Launcher 视角：**从发出 boot_info 到收到 `module.ready` 事件** = 模块启动时长。
+但 ①~④ 发生在 stdin 读取之前，Launcher 还没发 boot_info 模块就已经在消耗时间了。
+
+### 检查项
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 12.1 | ⚠️ Server 类 import 在 stdin 读取之后 | 🔴 性能 | 最大优化点。在 stdin 之前 import 会阻塞 Launcher 启动流水线。现有模块实测：dataclaw ~300-500ms，web ~200-300ms，acp_channel ~50-100ms。audit 是正确范例（import 在 `_run_local_mode` 内） |
+| 12.2 | 第三方库延迟导入 | 🟡 性能 | FastAPI、uvicorn、websockets 等重型库应随 Server 类一起延迟，不要在文件顶部 import |
+| 12.3 | _do_init 中 subscribe 和 register 并行 | 🟡 性能 | 用 `asyncio.gather(subscribe, register)` 替代顺序 await，可节省 50-100ms |
+| 12.4 | Server.__init__ 不做耗时操作 | 🟡 性能 | 构造函数只存参数。数据库连接、文件加载等放到 `_do_init` 或 startup 事件中 |
+| 12.5 | HTTP 路由延迟注册或懒加载 | 🟢 性能 | 路由多的服务（如 dataclaw 12 个 router），可考虑在 `_create_app()` 中按需加载而非全量 import |
+| 12.6 | 端口绑定在 stdin 之后 | 🟢 性能 | 端口绑定本身很快（~10ms），但确保不在关键路径上阻塞 |
+| 12.7 | 业务初始化异步化 | 🟡 性能 | 数据加载、缓存预热等放在 `asyncio.create_task()` 中，不阻塞 `module.ready` |
+| 12.8 | module.ready 尽早发布 | 🟡 性能 | ready 表示"可以接受请求"，不是"所有数据都加载完"。先 ready，后台继续初始化 |
+| 12.9 | 并行 import + stdin 读取 | 🟢 性能 | 后台线程 import 重型库，主线程同时等 stdin。两步重叠，总时间 = max(import, stdin) |
+| 12.10 | HTTP 端口预绑定复用 | 🟢 性能 | 先 `socket.bind()` 再传给 uvicorn `sockets=[sock]`，避免 uvicorn 重复绑端口。Kernel 已实现此模式 |
+
+### 现有最优范例
+
+**Kernel（最优）**：延迟导入 uvicorn 和 KernelServer，先绑端口先输出，再 import 再创建 server。
+**Evol（后台并行）**：daemon 线程跑前端构建，不阻塞 uvicorn 启动。
+**Audit（正确）**：Server import 在 `_run_local_mode()` 函数内部，stdin 之后。
+
+### 终极启动模式（import 与 stdin 并行）
+
+```python
+import threading
+
+_server_cls = [None]
+def _bg_import():
+    from my_module.server import MyServer
+    _server_cls[0] = MyServer
+
+# 后台 import（不阻塞主线程）
+t = threading.Thread(target=_bg_import, daemon=True)
+t.start()
+
+# 主线程同时读 stdin（两件事并行！）
+line = sys.stdin.readline().strip()
+msg = json.loads(line)
+token = msg["token"]
+
+# 等后台 import 完成（如果 stdin 比 import 快，这里等一下；反之 import 已完成）
+t.join(timeout=10)
+MyServer = _server_cls[0]
+server = MyServer(token=token, ...)
+```
+
+### 标准启动顺序（优化版）
+
+```python
+# ── entry.py ──
+
+# ① 只 import 标准库（轻量）
+import asyncio, json, os, sys, time ...
+
+# ② 加载 module.md 配置（~10-50ms，可接受）
+_module_config = _load_module_config()
+
+# ③ 设置 _SafeWriter + logging（~5ms）
+sys.stdout = _SafeWriter(sys.stdout)
+builtins.print = _tprint
+
+# ④ 不要在这里 import Server 类！
+
+def _run_local_mode(kernel_port):
+    # ⑤ 先设置日志 + 异常 hook
+    _setup_exception_hooks()
+
+    # ⑥ 读 stdin（Launcher 发 boot_info）
+    line = sys.stdin.readline().strip()
+    msg = json.loads(line)
+    token = msg["token"]
+
+    # ⑦ 读完 stdin 后再 import Server 类（重型依赖在这里加载）
+    from my_module.server import MyServer
+
+    # ⑧ 实例化并启动
+    server = MyServer(token=token, kernel_port=kernel_port, ...)
+    asyncio.run(server.run())
+```
+
+```python
+# ── server.py _do_init ──
+
+async def _do_init(self, ws):
+    # subscribe 和 register 可以并行
+    await asyncio.gather(
+        self._rpc_call(ws, "event.subscribe", {"events": [...]}),
+        self._rpc_call(ws, "registry.register", {
+            "module_id": self._module_name, ...
+        }),
+    )
+    # ready 必须在 register 之后
+    await self._publish_event(ws, "module.ready", {"module_id": self._module_name})
+
+    # 业务初始化放后台，不阻塞 ready
+    asyncio.create_task(self._deferred_business_init())
+```
+
+### 现有模块启动时间评估
+
+| 模块 | import 位置 | import 耗时 | 评级 |
+|------|-------------|-------------|------|
+| audit | stdin 之后 ✅ | 0ms（不在关键路径上） | 最优 |
+| acp_channel | stdin 之前 ❌ | ~50-100ms | 需优化 |
+| web | stdin 之前 ❌ | ~200-300ms | 需优化 |
+| dataclaw | 文件顶部 ❌❌ | ~300-500ms | 最差 |
+
+### 优化效果预估
+
+| 指标 | 优化前 | 优化后 | 提升 |
+|------|--------|--------|------|
+| 全量启动（所有模块 ready） | ~1100ms | ~300ms | **73%** |
+| 单模块 ready（从收到 boot_info） | ~200-300ms | ~100-150ms | **50%** |
+
+---
+
+## 十三、退出时间优化
+
+### 退出关键路径
+
+```
+Kernel 发布 module.shutdown
+  ↓ ① 模块收到事件
+  ↓ ② 发布 shutdown.ack
+  ↓ ③ 发布 module.exiting
+  ↓ ④ 执行清理（关闭资源、保存状态）
+  ↓ ⑤ 发布 shutdown.ready
+  ↓ ⑥ 关闭附加连接
+  ↓ ⑦ 关闭主连接
+  ↓ ⑧ 进程退出
+```
+
+Launcher 有三级超时：ack 超时 3s → exiting 超时 3s → 强制终止。
+**实际清理通常只需 50-100ms**，但如果模块卡住，会等满超时。
+
+### 检查项
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 13.1 | shutdown.ack 立即发送 | 🟡 性能 | 收到 shutdown 后第一件事就是发 ack，不要先做清理再 ack |
+| 13.2 | 清理操作有超时保护 | 🟡 性能 | 单个清理操作不应超过 2 秒，否则用 `asyncio.wait_for` 包裹 |
+| 13.3 | 可并行的清理操作用 gather | 🟢 性能 | 多个独立资源（数据库连接、文件句柄、外部连接）可并行关闭 |
+| 13.4 | 附加连接并行关闭 | 🟢 性能 | 多个 slot 的 `ws.close()` 可以用 `asyncio.gather` |
+| 13.5 | _shutting_down 标志立即设置 | 🟡 性能 | 阻止测试事件循环和新 RPC 处理，避免关闭过程中产生新操作 |
+| 13.6 | 长任务支持取消 | 🟢 性能 | 正在执行的长任务应检查 `_shutting_down`，及早退出 |
+| 13.7 | HTTP 服务关闭不阻塞 | 🟡 性能 | uvicorn `should_exit = True` 后不要 await 额外操作 |
+
+### 优化版退出序列
+
+```python
+async def _handle_shutdown(self, ws):
+    self._shutting_down = True  # 立即设置！
+
+    # ack 立即发送，不做任何清理
+    await self._publish_event(ws, "module.shutdown.ack", {
+        "module_id": self._module_name, "estimated_cleanup": 1,
+    })
+
+    # 清理操作并行执行
+    cleanup_tasks = []
+    if self._db_conn:
+        cleanup_tasks.append(self._db_conn.close())
+    if self._cache:
+        cleanup_tasks.append(self._cache.flush())
+    if cleanup_tasks:
+        await asyncio.gather(*cleanup_tasks, return_exceptions=True)
+
+    await self._publish_event(ws, "module.exiting", {
+        "module_id": self._module_name, "action": "cleanup_done",
+    })
+
+    await self._publish_event(ws, "module.shutdown.ready", {
+        "module_id": self._module_name,
+    })
+    await asyncio.sleep(0.01)
+
+    # 附加连接并行关闭
+    close_tasks = [w.close(code=1000, reason="shutdown") for w in self._extra_ws.values()]
+    if close_tasks:
+        await asyncio.gather(*close_tasks, return_exceptions=True)
+    self._extra_ws.clear()
+
+    await ws.close(code=1000, reason="Graceful shutdown")
+
+    if self._uvicorn_server:
+        self._uvicorn_server.should_exit = True
+```
+
+---
+
+## 十四、跨平台兼容性（Windows / Linux / macOS）
+
+Kite 框架核心原则：所有功能必须在三个平台上可用。
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 14.1 | 文件路径使用 `os.path.join` 或 `pathlib` | 🔴 致命 | 禁止硬编码 `/` 或 `\\` |
+| 14.2 | 不依赖平台特有命令 | 🔴 致命 | 禁止直接调用 `tasklist`/`ps`/`wmic` 等。如必须，提供多策略降级 |
+| 14.3 | 进程信号处理兼容 | 🟡 警告 | Windows 不支持 SIGKILL/SIGUSR1。只用 SIGTERM + SIGINT，终止用 `process.terminate()` |
+| 14.4 | 文件编码显式指定 | 🟡 警告 | `open(f, encoding="utf-8")`，不依赖系统默认编码（Windows 可能是 GBK） |
+| 14.5 | 临时文件路径安全 | 🟡 警告 | 用 `tempfile.gettempdir()` 而非硬编码 `/tmp` |
+| 14.6 | Home 目录获取兼容 | 🟡 警告 | `os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")` |
+| 14.7 | 端口绑定地址 | 🟢 建议 | 不要用 `localhost`（某些平台解析为 IPv6），用 `127.0.0.1` 或 `0.0.0.0` |
+| 14.8 | 子进程创建方式 | 🟡 警告 | 用 `subprocess.Popen` 而非 `os.system`。Windows 下 `shell=True` 行为不同 |
+| 14.9 | 文件锁机制 | 🟡 警告 | 不能用 `fcntl.flock`（Unix only）。跨平台方案：原子写 + 临时文件重命名，或 `filelock` 库 |
+| 14.10 | 换行符处理 | 🟢 建议 | JSON/JSONL 输出不受影响，文本文件用 `newline=""` 参数控制 |
+| 14.11 | 环境变量分隔符 | 🟢 建议 | PATH 分隔符用 `os.pathsep`（Windows `;`，Unix `:`） |
+| 14.12 | Windows WinError 处理 | 🟡 警告 | `ConnectionRefusedError` 在 Windows 有时表现为 `OSError(WinError 1225)`，需要额外捕获 |
+
+### 常见平台差异速查
+
+| 操作 | Windows | Linux/macOS | 跨平台方案 |
+|------|---------|-------------|-----------|
+| 路径分隔符 | `\` | `/` | `os.path.join()` |
+| Home 目录 | `%USERPROFILE%` | `$HOME` | `os.path.expanduser("~")` |
+| 临时目录 | `%TEMP%` | `/tmp` | `tempfile.gettempdir()` |
+| 进程终止 | `taskkill` | `kill` | `process.terminate()` |
+| 文件编码 | GBK/CP936 | UTF-8 | 显式 `encoding="utf-8"` |
+| 信号 | 仅 SIGTERM/SIGINT | 全部 | 只用 SIGTERM |
+| 连接拒绝 | WinError 1225 | ECONNREFUSED | 双重 catch |
+
+---
+
+## 十五、跨语言兼容性（Python / Node.js / Binary）
+
+Kite 框架核心原则：模块间通信仅使用语言无关协议。
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 15.1 | 模块间通信仅用 JSON-RPC 2.0 | 🔴 致命 | WebSocket 消息必须是标准 JSON。不能用 pickle、msgpack 等语言特定序列化 |
+| 15.2 | stdin boot_info 是纯 JSON | 🔴 致命 | 一行 JSON 文本，不能有语言特定格式 |
+| 15.3 | 事件数据是 JSON 可序列化的 | 🔴 致命 | data 只能包含 string/number/bool/null/array/object。不能传 datetime、bytes |
+| 15.4 | RPC 参数和返回值 JSON 可序列化 | 🔴 致命 | Python `None` → `null`，`True` → `true`，不能传自定义对象 |
+| 15.5 | 不依赖语言特有 IPC 机制 | 🔴 致命 | 禁止 Python multiprocessing.Queue、Node IPC channel 等 |
+| 15.6 | 时间戳用 Unix timestamp 或 ISO 8601 | 🟡 警告 | `time.time()`（浮点秒）或 `datetime.isoformat()`。不用语言特定时间对象 |
+| 15.7 | 日志格式语言无关 | 🟡 警告 | latest.log 纯文本，crashes.jsonl 标准 JSON Lines |
+| 15.8 | 配置文件格式通用 | 🟡 警告 | module.md（YAML）、config.json5（JSON5）。不用 Python .ini 或 Node .env |
+| 15.9 | 进程管理一视同仁 | 🟡 警告 | Launcher 对 python/node/binary 三种 runtime 使用相同机制 |
+
+---
+
+## 十六、模块独立性（零共享代码依赖）
+
+Kite 框架最高设计原则：模块间不可有任何代码级依赖。
+
+| # | 检查项 | 严重度 | 说明 |
+|---|--------|--------|------|
+| 16.1 | 不 import 其他模块的代码 | 🔴 致命 | 禁止 `from extensions.services.web.xxx import yyy` |
+| 16.2 | 不 import core/ 共享库（或标注为可选） | 🟡 警告 | `core/kite_log.py` 是便利库不是强制依赖。删除 core/ 后模块仍须运行 |
+| 16.3 | 不使用跨模块共享函数或类 | 🔴 致命 | 禁止继承、mixin、trait 等任何形式的代码复用 |
+| 16.4 | 不依赖共享配置文件 | 🟡 警告 | 环境变量可以，共享 config 文件不行 |
+| 16.5 | 模块可独立部署运行 | 🔴 致命 | 单独拷贝模块目录 + 装依赖后，能连任意 Kernel |
+| 16.6 | 模块可用其他语言重写 | 🟢 设计 | 只要遵循相同通信协议，Python 模块可被 Node/Go 替换 |
+| 16.7 | 共享只通过约定 | 🟢 设计 | 允许：环境变量、文件路径约定、文件格式约定、网络协议、事件协议 |
+
+### 违规检测命令
+
+```bash
+# 检查是否 import 了其他 extensions 模块
+grep -r "from extensions\." extensions/{module_name}/ --include="*.py" | grep -v __pycache__
+
+# 检查是否 import 了 core/（kite_log 除外需标注可选）
+grep -r "from core\." extensions/{module_name}/ --include="*.py" | grep -v __pycache__
+
+# 检查是否 import 了 kernel/ 或 launcher/
+grep -r "from kernel\.\|from launcher\." extensions/{module_name}/ --include="*.py" | grep -v __pycache__
+```
+
+**任何一条有输出（除 core/kite_log.py 外）→ 模块独立性不合格。**
+
+### 正确的跨模块交互方式
+
+| 需求 | 错误做法 ❌ | 正确做法 ✅ |
+|------|-----------|-----------|
+| 调用其他模块功能 | `from web.server import WebServer` | `await _rpc_call(ws, "web.method", {})` |
+| 读取其他模块数据 | 直接读对方文件 | 通过 RPC 请求数据 |
+| 共享工具函数 | 放 `core/utils.py` 让大家 import | 各模块独立实现 |
+| 共享配置 | 读同一个 config 文件 | 各自 module.md + 环境变量 |
+| 共享类型定义 | 共享 Pydantic model | JSON schema 约定，各自解析 |
+
+---
+
+## 审查评分规则
+
+- 🔴 致命：不修复则模块无法正常运行
+- 🟡 警告：不修复可能导致异常行为或调试困难
+- 🟢 建议：最佳实践，不影响功能
+
+**审查评分：**
+- 🔴 0 个 + 🟡 ≤ 2 个 → ✅ 合格
+- 🔴 0 个 + 🟡 3-5 个 → ⚠️ 需改进
+- 🔴 ≥ 1 个 → ❌ 不合格

package/.claude/skills/kite/references/event-patterns.md

@@ -0,0 +1,180 @@
+# 事件订阅/发布标准模式
+
+## 事件消息格式
+
+事件通过 JSON-RPC 2.0 通知（无 id）传递：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event": "module.ready",
+    "source": "web",
+    "data": {"module_id": "web"},
+    "event_id": "uuid",
+    "seq": 5,
+    "session_id": "session-uuid"
+  }
+}
+```
+
+## 事件订阅
+
+### 订阅 RPC
+
+```python
+await self._rpc_call(ws, "event.subscribe", {
+    "events": [
+        "module.started",
+        "module.stopped",
+        "module.shutdown",
+        "system.ping",
+    ]
+})
+```
+
+### 通配符订阅
+
+| 模式 | 匹配 | 示例 |
+|------|------|------|
+| `module.*` | module 下所有事件 | module.started, module.stopped |
+| `*.started` | 所有 started 事件 | module.started, system.started |
+| `>` | 所有事件（慎用） | 一切 |
+
+## 事件发布
+
+### 标准 _publish_event 实现
+
+```python
+async def _publish_event(self, ws, event: str, data: dict = None):
+    """发布事件（fire-and-forget，不等响应）。"""
+    await self._rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": event,
+        "data": data or {},
+    }, wait_response=False)
+```
+
+**关键：`wait_response=False`** — 事件发布不需要等响应，否则会积压 pending_rpc。
+
+## 事件通知处理
+
+### 标准 _handle_event_notification 实现
+
+```python
+async def _handle_event_notification(self, msg: dict):
+    params = msg.get("params", {})
+    event_type = params.get("event", "")
+    data = params.get("data", {})
+
+    # ── 第 1 层：系统事件（必须处理） ──
+    if event_type == "system.require_init":
+        asyncio.create_task(self._do_init(self._ws))
+        return
+
+    if event_type == "system.ping":
+        await self._handle_ping(data)
+        return
+
+    if event_type == "system.connection.offer":
+        asyncio.create_task(self._handle_connection_offer(data))
+        return
+
+    if event_type == "system.connection.release":
+        asyncio.create_task(self._handle_connection_release(data))
+        return
+
+    if event_type == "module.shutdown":
+        await self._handle_shutdown(self._ws)
+        return
+
+    # ── 第 2 层：忽略系统广播事件（不需要处理） ──
+    IGNORE_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",
+        "system.instance.started", "system.instance.stopped",
+    }
+    if event_type in IGNORE_EVENTS:
+        return
+
+    # ── 第 3 层：模块自定义事件 ──
+    # 在这里处理你的业务事件
+    print(f"[EVENT] 收到: {event_type}")
+```
+
+### ⚠️ 事件处理的关键规则
+
+1. **system.require_init 必须用 create_task** — 因为 _do_init 内部会调用 _rpc_call，如果 await 会阻塞接收循环
+2. **system.connection.offer 必须用 create_task** — 因为需要建立新的 WebSocket 连接
+3. **module.shutdown 可以 await** — 因为处理完就要关闭了，不需要继续接收
+4. **system.ping 可以 await** — 因为只是发一个 pong，很快
+
+## Ping/Pong 机制
+
+Kernel 定期发送 `system.ping`，模块必须回复 `system.pong`：
+
+```python
+async def _handle_ping(self, data: dict):
+    t1 = data.get("ping_time")
+    t2 = time.time()
+    await self._publish_event(self._ws, "system.pong", {
+        "module_id": self._module_name,
+        "ping_time": t1,
+        "pong_time": t2,
+    })
+```
+
+**不回复 pong 的后果：** Kernel 会记录 timeout，连续多次 timeout 后可能标记模块为不健康。
+
+## 测试事件循环
+
+很多模块实现了定时发布测试事件的循环，用于验证事件系统正常工作：
+
+```python
+async def _test_event_loop(self):
+    """每 12 秒发布测试事件，同时报告压力等级。"""
+    while not self._shutting_down:
+        await asyncio.sleep(12)
+        if self._shutting_down:
+            break
+        if self._ws:
+            await self._publish_event(self._ws, f"{self._module_name}.test", {
+                "timestamp": time.time(),
+                "message": "periodic test",
+            })
+```
+
+## 压力报告事件
+
+支持弹性伸缩的模块需要定期报告压力等级：
+
+```python
+def _compute_pressure_level(self) -> str:
+    depth = self._active_handlers + len(self._pending_rpc)
+    ratio = depth / self._handler_capacity if self._handler_capacity > 0 else 0
+    if ratio >= 0.9:
+        return "critical"
+    elif ratio >= 0.5:
+        return "overload"
+    elif depth > 0:
+        return "normal"
+    return "idle"
+
+# 在测试事件循环中一起报告
+await self._publish_event(self._ws, "module.queue_pressure", {
+    "level": self._compute_pressure_level(),
+    "depth": self._active_handlers + len(self._pending_rpc),
+    "capacity": self._handler_capacity,
+})
+```
+
+## 常见坑
+
+1. **event.publish 不要 wait_response** — 设 `wait_response=False`，否则大量事件会积压 pending_rpc
+2. **event_id 必须唯一** — 用 `uuid.uuid4()`，重复的 event_id 会被 Kernel 静默去重
+3. **事件名命名** — 格式 `{module_name}.{event_type}`，如 `my_service.data_ready`
+4. **不要在事件 handler 中做耗时操作** — 会阻塞接收循环，用 create_task 异步处理
+5. **订阅要在 register 之前** — 否则可能漏收注册后立即到来的事件