@agentunion/kite 1.5.0 → 1.6.1

package/.claude/skills/kite/references/health-check.md

@@ -0,0 +1,202 @@
+# 健康检查机制
+
+## 两层架构
+
+| 层 | 机制 | 执行者 | 方式 | 判断什么 | 触发重启？ |
+|---|------|--------|------|----------|-----------|
+| **框架层** | Ping/Pong | Kernel | 事件广播 | 连通性（进程活着、WebSocket 通） | ❌ 只断连 |
+| **业务层** | health RPC | Watchdog | `{module}.health` RPC | 业务是否正常 | ✅ 3 次不健康 → 重启 |
+
+### 两层的关系
+
+```
+Ping/Pong 3次超时 → 断连(code 4012) → 5秒去抖 → module.offline
+                                                      ↓
+                        Watchdog 的 health RPC 也会失败（模块已离线）
+                                                      ↓
+                                          fail_count++ → 达到 3 → 重启
+```
+
+Ping/Pong 超时**间接**导致重启：断连 → health RPC 失败 → 触发阈值。
+
+---
+
+## 框架层：Ping/Pong
+
+Kernel 定期广播 `system.ping`，模块回复 `system.pong`。
+
+- **间隔**：活跃监控 5 秒，空闲 60 秒
+- **超时**：5 秒内无 pong → 标记 timeout
+- **阈值**：连续 3 次 timeout → 强制断连（code 4012）
+- **不直接重启**，只切断 WebSocket 连接
+
+详见 `event-patterns.md` 中的 Ping/Pong 部分。
+
+---
+
+## 业务层：health RPC
+
+### Watchdog 检查逻辑
+
+```python
+# Watchdog monitor.py
+async def _check_one(self, status):
+    resp = await self.rpc_call(f"{status.module_id}.health", {})
+    result = resp.get("result", {})
+
+    if result.get("healthy") == True:
+        fail_count = 0  # 重置
+    else:
+        fail_count += 1
+        if fail_count >= 3:
+            restart()
+```
+
+- **频率**：正常 15 秒，警告 5 秒，危急 2 秒
+- **超时**：单次 RPC 5 秒
+- **阈值**：连续 3 次 `healthy != true` → 重启
+- **降级保护**：降级状态的模块不重启（`is_degraded` 检查）
+
+### health 响应格式规范
+
+```json
+{
+  "healthy": true,
+  "framework": {
+    "uptime": 3600.5,
+    "connections": 2,
+    "pending_rpc": 3,
+    "active_handlers": 5,
+    "handler_capacity": 100,
+    "pressure": "normal",
+    "memory_mb": 128.5
+  },
+  "business": {
+    "healthy": true,
+    "message": "正常运行中",
+    "details": [
+      {"key": "任务队列", "status": "ok", "value": "12/1000"},
+      {"key": "模型连接", "status": "warn", "value": "响应变慢，平均 2.3s"}
+    ]
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 必填 | 谁看 | 说明 |
+|------|------|------|------|------|
+| `healthy` | bool | ✅ | Watchdog | **顶层判据。Watchdog 只看这个字段。** |
+| `framework` | dict | ✅ | 日志/审计 | 框架层指标，业务无关 |
+| `framework.uptime` | float | ✅ | - | 运行秒数 |
+| `framework.connections` | int | ✅ | - | 当前连接数（含附加连接） |
+| `framework.pending_rpc` | int | ✅ | - | 等待响应的 RPC 请求数 |
+| `framework.active_handlers` | int | ✅ | - | 正在处理的入站请求数 |
+| `framework.handler_capacity` | int | ✅ | - | 处理能力上限 |
+| `framework.pressure` | string | ✅ | - | 压力等级：idle/normal/overload/critical |
+| `framework.memory_mb` | float | ✅ | - | 进程内存占用 MB |
+| `business` | dict | ✅ | 人类/大模型 | 业务层状态 |
+| `business.healthy` | bool | ✅ | 模块自判 | 业务是否健康，影响顶层 `healthy` |
+| `business.message` | string | ✅ | 人类/大模型 | 一句话状态描述 |
+| `business.details` | list | 🟢 可选 | 人类/大模型 | 结构化的业务指标列表 |
+
+### details 条目格式
+
+```json
+{"key": "指标名称", "status": "ok|warn|error", "value": "描述值"}
+```
+
+- `key`：业务指标名（如"任务队列"、"数据库连接"、"模型服务"）
+- `status`：`ok` / `warn` / `error`
+- `value`：当前值的文本描述（语义化，给人类和大模型看）
+
+### 标准实现（Python）
+
+```python
+import os
+import psutil
+import time
+
+async def _rpc_health(self, params: dict) -> dict:
+    # 框架层指标
+    process = psutil.Process(os.getpid())
+    fw = {
+        "uptime": time.time() - self._start_time,
+        "connections": 1 + len(self._extra_ws),
+        "pending_rpc": len(self._pending_rpc),
+        "active_handlers": self._active_handlers,
+        "handler_capacity": self._handler_capacity,
+        "pressure": self._compute_pressure_level(),
+        "memory_mb": round(process.memory_info().rss / 1024 / 1024, 1),
+    }
+
+    # 业务层指标（模块自己实现）
+    biz = self._check_business_health()
+
+    # 顶层判据：业务健康 + 框架没过载
+    healthy = biz["healthy"] and fw["pressure"] != "critical"
+
+    return {
+        "healthy": healthy,
+        "framework": fw,
+        "business": biz,
+    }
+
+def _check_business_health(self) -> dict:
+    """模块自定义业务健康检查。默认实现直接返回健康。"""
+    return {
+        "healthy": True,
+        "message": "正常运行中",
+        "details": [],
+    }
+```
+
+### healthy 判定规则
+
+模块自己决定 `healthy`，推荐逻辑：
+
+```python
+healthy = (
+    business.healthy                          # 业务层自判
+    and framework.pressure != "critical"       # 框架层没到危急
+)
+```
+
+**业务层 `business.healthy` 应该由模块根据自身业务逻辑判断：**
+- 数据库连接是否正常
+- 外部 API 是否可达
+- 关键资源是否可用
+- 任务队列是否积压到不可接受的程度
+
+**Kite 框架不规定 business.healthy 的判断逻辑**，因为框架是业务无关的。
+
+---
+
+## 其他重启触发器
+
+除了 health RPC，Watchdog 还有两个独立的重启触发器：
+
+### 资源监控
+
+```
+CPU > 95% 或 Memory > 85% 持续 30 秒 → 重启
+连续 3 次内存上涨且总涨幅 > 20% → 内存泄漏 → 重启
+```
+
+### 进程崩溃
+
+```
+module.stopped 事件（stop_type != graceful_stop）
+  → 运行时崩溃：指数退避重启（1s, 2s, 4s... 最大 10 分钟）
+  → 启动失败：最多重试 5 次
+```
+
+---
+
+## 常见坑
+
+1. **health 返回 `{"status": "ok"}` 而非 `{"healthy": true}`** — Watchdog 看的是 `healthy` 字段
+2. **health handler 中做了耗时操作** — 导致 5 秒超时，被误判为不健康。health 应该只查状态，不做计算
+3. **psutil 未安装** — `memory_mb` 计算失败。用 try-except 降级处理
+4. **business.healthy 始终返回 true** — 等于没有业务级健康检查，应该根据实际业务判断
+5. **Ping 超时 ≠ health 失败** — Ping 超时只断连不重启，但断连后 health RPC 也会失败从而触发重启

package/.claude/skills/kite/references/http-service.md

@@ -0,0 +1,199 @@
+# HTTP 服务接入模式
+
+## 概述
+
+Kite 模块可以同时提供 HTTP API 和 WebSocket 连接。HTTP 服务使用 FastAPI + uvicorn，WebSocket 客户端在后台任务中运行。
+
+## 架构
+
+```
+                    ┌──────────────────────────────────┐
+                    │         Module Process            │
+                    │                                    │
+  HTTP Client ──→  │  FastAPI App (uvicorn)              │
+                    │    ├─ /health                      │
+                    │    ├─ /api/...                     │
+                    │    └─ startup event                │
+                    │         ↓                          │
+                    │    WebSocket Client Task ──→ Kernel │
+                    │    (后台运行)                       │
+                    └──────────────────────────────────┘
+```
+
+## 入口（entry.py）中的端口绑定
+
+```python
+import socket
+
+def _bind_port(preferred: int, host: str = "0.0.0.0") -> tuple:
+    """绑定端口，返回 (socket, port)。"""
+    # 策略：尝试 preferred, preferred+1, preferred+2
+    for offset in range(3):
+        port = preferred + offset
+        if port <= 0:
+            continue
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind((host, port))
+            sock.listen(1)
+            return sock, port
+        except OSError:
+            sock.close()
+
+    # 回退：让 OS 分配
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind((host, 0))
+    sock.listen(1)
+    port = sock.getsockname()[1]
+    return sock, port
+```
+
+## uvicorn 启动
+
+```python
+import uvicorn
+
+# 创建 server 实例
+server = MyServer(token=token, kernel_port=kernel_port, host=host, port=port, ...)
+
+# 创建 uvicorn 配置
+config = uvicorn.Config(
+    app=server.app,
+    host=host,
+    port=port,
+    log_level="warning",
+)
+uvi_server = uvicorn.Server(config)
+server._uvicorn_server = uvi_server  # 保存引用，用于关闭
+
+# 传入预绑定的 socket
+uvi_server.config.loaded = True  # 跳过 uvicorn 的端口绑定
+await uvi_server.serve(sockets=[bound_sock])
+```
+
+**注意：**
+- 使用预绑定 socket 避免端口冲突
+- `log_level="warning"` 减少 uvicorn 日志噪音
+
+## server.py 中的 FastAPI 集成
+
+```python
+from fastapi import FastAPI
+
+class MyServer:
+    def __init__(self, token, kernel_port, host, port, boot_t0, max_connections, ...):
+        self.token = token
+        self._kernel_port = kernel_port
+        self._host = host
+        self._port = port
+        self._module_name = "my_service"
+
+        self._ws = None
+        self._ws_task = None
+        self._test_task = None
+        self._shutting_down = False
+        self._pending_rpc = {}
+        self._extra_ws = {}
+        self._extra_ws_tasks = {}
+
+        self.app = self._create_app()
+
+    def _create_app(self) -> FastAPI:
+        app = FastAPI(title=self._module_name)
+        server = self  # 闭包引用
+
+        @app.on_event("startup")
+        async def _startup():
+            # 启动 WebSocket 客户端连接 Kernel
+            server._ws_task = asyncio.create_task(server._ws_loop())
+            # 启动测试事件循环
+            server._test_task = asyncio.create_task(server._test_event_loop())
+
+        @app.on_event("shutdown")
+        async def _shutdown():
+            server._shutting_down = True
+            if server._ws_task:
+                server._ws_task.cancel()
+            if server._test_task:
+                server._test_task.cancel()
+            # 关闭 WebSocket 连接
+            if server._ws:
+                try:
+                    await server._ws.close()
+                except Exception:
+                    pass
+
+        @app.get("/health")
+        async def health():
+            return {"status": "ok", "module": server._module_name}
+
+        # 添加业务路由
+        # app.include_router(my_router, prefix="/api")
+
+        return app
+```
+
+## 关键注意事项
+
+### 1. WebSocket 客户端在 startup 中启动
+
+不要在 `__init__` 中启动 WebSocket 连接。必须在 FastAPI 的 `startup` 事件中用 `create_task` 启动。
+
+原因：`__init__` 时 asyncio event loop 还没运行。
+
+### 2. 端口通告
+
+HTTP 服务模块需要在 `registry.register` 中告知 Kernel 自己的 HTTP 端口：
+
+```python
+await self._rpc_call(ws, "registry.register", {
+    "module_id": self._module_name,
+    "module_type": "service",
+    "port": self._port,
+    "base_url": f"http://{self._host}:{self._port}",
+    # ...
+})
+```
+
+### 3. 并行运行不冲突
+
+FastAPI/uvicorn 和 WebSocket 客户端在同一个 asyncio event loop 中并行运行，不会冲突。
+
+### 4. 优雅关闭
+
+HTTP 服务模块的关闭需要同时停止 uvicorn：
+
+```python
+async def _handle_shutdown(self, ws):
+    # ... 标准关闭序列 ...
+
+    # 停止 uvicorn
+    if self._uvicorn_server:
+        self._uvicorn_server.should_exit = True
+```
+
+### 5. CORS（如果需要外部访问）
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### 6. 静态文件（如果有前端页面）
+
+```python
+from fastapi.staticfiles import StaticFiles
+
+static_dir = os.path.join(os.path.dirname(__file__), "static")
+app.mount("/", StaticFiles(directory=static_dir, html=True), name="static")
+```
+
+**注意：静态文件挂载必须放在所有路由之后**，因为 `/` 会匹配所有路径。

package/.claude/skills/kite/references/module-md-spec.md

@@ -0,0 +1,172 @@
+# module.md 字段规范
+
+## 概述
+
+每个 Kite 模块的根目录必须有一个 `module.md` 文件，由 YAML frontmatter + Markdown 文档组成。
+Launcher 的 `module_scanner.py` 解析 YAML frontmatter 来发现和配置模块。
+
+## 完整字段参考
+
+### 必填字段
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `name` | string | 模块唯一标识，只允许 `[a-zA-Z0-9_-]` | `my_service` |
+
+### 基础字段（有默认值）
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `display_name` | string | 同 name | UI 显示名称 |
+| `version` | string | `"1.0"` | 语义化版本号 |
+| `type` | string | `"infrastructure"` | 模块类型：`service` / `channel` / `agent` / `infrastructure` |
+| `state` | string | `"enabled"` | 启动状态：`enabled`（自动启动）/ `manual`（手动）/ `disabled`（禁用） |
+| `runtime` | string | `"python"` | 运行时：`python` / `node` / `binary` |
+| `entry` | string | `"entry.py"` | 入口文件名 |
+
+### 网络字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `preferred_port` | int | `0` | 首选端口（0 = OS 分配）。仅 HTTP 服务需要 |
+| `advertise_ip` | string | `""` | 对外通告的 IP。本地模块用 `127.0.0.1`，外部可访问用 `0.0.0.0` |
+
+### 连接与实例
+
+| 字段 | 类型 | 默认值 | 说明 | 验证规则 |
+|------|------|--------|------|----------|
+| `max_connections` | int | `1` | 到 Kernel 的最大 WebSocket 连接数 | 钳位到 [1, 10] |
+| `connection_elastic` | bool | `false` | 连接扩展策略：`false` = 模块 ready 后立刻建满所有连接，断线自动补充；`true` = Kernel 按压力动态扩容/收缩 | 字符串 "true"/"1"/"yes" → true |
+| `max_instances` | int | `1` | 最大进程实例数 | 钳位到 [1, 10]；> 10 重置为 1（安全阀） |
+| `instance_elastic` | bool | `false` | 是否允许 Kernel 根据负载自动伸缩实例 | 字符串 "true"/"1"/"yes" → true |
+
+### UI 控制
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `display_order` | int | `0` | UI 中的显示顺序，钳位到 [0, 100] |
+| `manual_control` | bool | `true` | 是否允许用户在 UI 中手动启动/停止 |
+| `monitor` | bool | `true` | 是否由 Watchdog 监控健康状态 |
+
+### 事件与订阅
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `events` | list | `[]` | 本模块发布的事件列表 |
+| `subscriptions` | list | `[]` | 本模块订阅的事件列表 |
+
+### 业务配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `businesses` | list[dict] | `[]` | 业务配置对象列表 |
+
+businesses 中每个对象格式：
+```yaml
+businesses:
+  - name: my_config
+    type: custom
+    config_file: config.json5
+```
+
+### 自定义启动（高级）
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `launch` | dict | `{}` | 自定义启动配置 |
+
+launch 子字段：
+```yaml
+launch:
+  cmd: ["custom_command", "--flag"]    # 自定义启动命令（覆盖 runtime + entry）
+  env: { MY_VAR: "value" }            # 额外环境变量
+  cwd: "/custom/path"                 # 工作目录
+  boot_stdin: true                    # 是否通过 stdin 发送 boot_info（默认 true）
+  timeout: 30                         # 启动超时秒数（默认 30，最小 1）
+```
+
+## 未被解析的字段（出现在现有模块但不生效）
+
+以下字段出现在部分现有 module.md 中，但 `module_scanner.py` **不解析**它们：
+
+| 字段 | 出现位置 | 状态 |
+|------|----------|------|
+| `graceful_shutdown` | audit, logs | ❌ 不生效，关闭序列由代码实现 |
+| `tools` | audit, logs | ❌ 不生效，工具注册在 registry.register RPC 中完成 |
+
+**生成新模块时不要使用这些字段。**
+
+## 标准 module.md 模板
+
+### 最小模块
+
+```yaml
+---
+name: my_module
+display_name: My Module
+version: '1.0'
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+max_connections: 1
+monitor: true
+---
+# My Module
+
+模块功能描述。
+```
+
+### 完整示例（service + HTTP + 多连接 + 事件）
+
+```yaml
+---
+name: my_service
+display_name: 我的服务
+version: '1.0'
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+preferred_port: 18800
+advertise_ip: 127.0.0.1
+max_connections: 3
+max_instances: 1
+instance_elastic: false
+monitor: true
+display_order: 50
+manual_control: true
+events:
+  - my_service.data_ready
+  - my_service.error
+subscriptions:
+  - module.started
+  - module.stopped
+  - module.shutdown
+businesses:
+  - name: main_config
+    type: custom
+    config_file: config.json5
+---
+# 我的服务
+
+服务功能描述。
+
+## 事件
+
+- `my_service.data_ready` — 数据处理完成时发布
+- `my_service.error` — 发生错误时发布
+
+## RPC 方法
+
+- `my_service.health` — 健康检查
+- `my_service.status` — 状态查询
+```
+
+## 常见错误
+
+1. **name 包含非法字符** — 只允许字母、数字、下划线、连字符
+2. **max_instances 设为 > 10** — 会被安全阀重置为 1
+3. **使用 tools 字段声明 RPC 方法** — 不会生效，RPC 方法在 `registry.register` 调用中注册
+4. **漏掉 version 的引号** — YAML 中 `1.0` 会被解析为浮点数，用 `'1.0'` 包裹
+5. **events/subscriptions 写成字符串** — 解析器会自动转为列表，但建议直接写列表格式