@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/250/241/345/235/227/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,1824 @@
+# 模块开发指南
+
+本指南面向 Kite 框架的模块开发者，从零开始讲解如何创建、注册和运行一个模块。
+
+## 1. 概述
+
+Kite 中的**模块**是一个独立进程，通过 WebSocket JSON-RPC 2.0 协议与 Kernel 通信。模块可以用 Python、Node.js 或编译型语言编写——框架不关心语言，只关心协议。
+
+每个模块有一个类型，决定它在系统中的角色：
+
+| 类型 | 说明 |
+|------|------|
+| `infrastructure` | 基础设施（Kernel、Launcher） |
+| `service` | 后台服务（Watchdog、Model Service） |
+| `channel` | 消息渠道（WebChat、电话） |
+| `agent` | AI 代理（对话、群组） |
+| `tool` | 工具型模块（一次性任务、基准测试） |
+
+前置知识：了解 WebSocket、JSON-RPC 2.0 基础即可。
+
+## 2. 快速开始
+
+5 分钟创建一个最小 Python 模块。
+
+### 2.1 创建目录和文件
+
+在 `tests/modules/` 下创建模块目录：
+
+```
+tests/modules/my_module/
+├── entry.py      # 入口文件（必须）
+└── module.md     # 模块元数据（必须）
+```
+
+### 2.2 编写 module.md
+
+```markdown
+---
+name: my_module
+display_name: My Module
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+---
+
+# My Module
+
+一个最小的示例模块。
+```
+
+### 2.3 编写 entry.py
+
+```python
+"""最小 Kite 模块示例 - 异步非阻塞版本。"""
+import asyncio
+import json
+import os
+import sys
+import uuid
+
+import websockets
+
+
+# ── SafeWriter：防止 Launcher 关闭 stdio 后 BrokenPipeError ──
+class _SafeWriter:
+    def __init__(self, stream):
+        self._stream = stream
+    def write(self, s):
+        try: self._stream.write(s)
+        except (BrokenPipeError, OSError): pass
+    def flush(self):
+        try: self._stream.flush()
+        except (BrokenPipeError, OSError): pass
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+sys.stdout = _SafeWriter(sys.stdout)
+sys.stderr = _SafeWriter(sys.stderr)
+
+
+async def main():
+    TAG = "[my_module]"
+
+    # ① 读取 boot_info（stdin 第一行 JSON）
+    line = sys.stdin.readline().strip()
+    if not line:
+        print(f"{TAG} ERROR: No boot_info received")
+        sys.exit(1)
+    boot_info = json.loads(line)
+    token = boot_info["token"]
+
+    # ② 读取 kernel_port（stdin 第二行 JSON 或环境变量）
+    kernel_port = os.environ.get("KITE_KERNEL_PORT")
+    if not kernel_port:
+        line = sys.stdin.readline().strip()
+        if line:
+            msg = json.loads(line)
+            if msg.get("kite") == "kernel_port":
+                kernel_port = msg["kernel_port"]
+
+    if not kernel_port:
+        print(f"{TAG} ERROR: KITE_KERNEL_PORT not set")
+        sys.exit(1)
+
+    kernel_port = int(kernel_port)
+    print(f"{TAG} Token received, kernel port: {kernel_port}")
+
+    # ③ 连接 Kernel WebSocket
+    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=my_module"
+    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None) as ws:
+        print(f"{TAG} Connected to Kernel")
+
+        # ④ 订阅事件
+        subscribe_msg = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "event.subscribe",
+            "params": {"events": ["module.>"]}
+        }
+        await ws.send(json.dumps(subscribe_msg))
+        await ws.recv()  # 等待响应
+        print(f"{TAG} Subscribed to events")
+
+        # ⑤ 注册到 Kernel
+        register_msg = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "registry.register",
+            "params": {
+                "module_id": "my_module",
+                "module_type": "service",
+                "name": "My Module",
+                "graceful_shutdown": True,
+                "events_subscribe": ["module.>"],
+            }
+        }
+        await ws.send(json.dumps(register_msg))
+        resp = json.loads(await ws.recv())
+        if "error" in resp:
+            print(f"{TAG} ERROR: Registration failed: {resp['error']}")
+            sys.exit(1)
+        print(f"{TAG} Registered to Kernel")
+
+        # ⑥ 发送 module.ready
+        ready_msg = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "event.publish",
+            "params": {
+                "event_id": str(uuid.uuid4()),
+                "event": "module.ready",
+                "data": {
+                    "module_id": "my_module",
+                    "graceful_shutdown": True,
+                }
+            }
+        }
+        await ws.send(json.dumps(ready_msg))
+        await ws.recv()  # 等待响应
+        print(f"{TAG} Published module.ready")
+
+        # ⑦ 消息循环（异步非阻塞）
+        print(f"{TAG} Entering message loop")
+        try:
+            async for raw in ws:
+                msg = json.loads(raw)
+
+                has_method = "method" in msg
+                has_id = "id" in msg
+
+                if has_method and not has_id:
+                    # 事件通知 — 异步处理（关键！）
+                    asyncio.create_task(handle_event(msg))
+
+                elif has_method and has_id:
+                    # RPC 请求 — 异步处理（关键！）
+                    asyncio.create_task(handle_rpc(ws, msg))
+
+        except KeyboardInterrupt:
+            print(f"{TAG} Interrupted, exiting")
+
+
+async def handle_event(msg: dict):
+    """处理事件通知（异步）"""
+    event = msg["params"]["event"]
+    print(f"[my_module] Received event: {event}")
+
+
+async def handle_rpc(ws, msg: dict):
+    """处理 RPC 请求（异步）"""
+    method = msg["method"]
+    msg_id = msg["id"]
+
+    if method == "my_module.health":
+        # 健康检查
+        response = {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {"status": "healthy"}
+        }
+        await ws.send(json.dumps(response))
+
+    elif method == "my_module.shutdown":
+        # 优雅关闭
+        response = {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {"status": "shutting_down"}
+        }
+        await ws.send(json.dumps(response))
+        print("[my_module] Shutdown requested, closing connection")
+        await ws.close(code=1000, reason="Graceful shutdown")
+
+    else:
+        # 未知方法
+        error_response = {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "error": {
+                "code": -32601,
+                "message": f"Method not found: {method}"
+            }
+        }
+        await ws.send(json.dumps(error_response))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+> **关键点**：
+> - 使用 `asyncio.create_task()` 异步处理事件和 RPC 请求
+> - 接收循环只负责分发消息，不执行业务逻辑
+> - 详见 **[WebSocket 接收循环死锁防范规范](./WebSocket接收循环死锁防范规范.md)**
+
+### 2.4 放置与启动
+
+将模块目录放在 Kite 可以扫描到的位置：
+
+- `extensions/my_module/` — 内置扫描路径，无需额外配置
+- `tests/modules/my_module/` — 需要在 Launcher 的 `module.md` 中配置 `discovery` 扫描此目录
+
+启动 Kite 后，检查 Launcher 日志中是否出现：
+
+```
+[launcher] Module 'my_module' is ready
+```
+
+## 3. 模块结构
+
+标准目录布局：
+
+```
+my_module/
+├── entry.py          # 入口文件（必须）
+├── module.md         # 模块元数据（必须）
+├── tools/            # 提供的工具定义（可选）
+│   └── tool_name/
+│       ├── tool.md   #   工具描述（frontmatter + 使用说明）
+│       └── handler.py#   工具实现
+├── skills/           # 技能定义（可选）
+│   └── skill_name/
+│       ├── skill.md
+│       └── ...
+├── permissions/      # 权限配置（可选）
+│   └── tool_name.json
+└── ...               # 模块自有代码
+```
+
+只有 `entry.py` 和 `module.md` 是必须的。模块可以包含任意额外的代码文件。
+
+## 4. module.md 详解
+
+`module.md` 使用 YAML frontmatter 定义元数据，正文是 Markdown 格式的模块说明文档（LLM 可阅读）。
+
+### 4.1 字段说明
+
+| 字段 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | 是 | — | 模块唯一标识，用于注册和 API 调用 |
+| `display_name` | 否 | 同 name | 显示名称 |
+| `version` | 否 | `"1.0"` | 版本号 |
+| `type` | 否 | `"infrastructure"` | 模块类型：infrastructure / service / channel / agent / tool |
+| `state` | 否 | `"enabled"` | 启动状态（见下文） |
+| `runtime` | 否 | `"python"` | 运行时：python / node / binary |
+| `entry` | 否 | `"entry.py"` | 入口文件名（相对于模块目录） |
+| `preferred_port` | 否 | `0` | 首选端口。0 = OS 动态分配，非零则优先尝试 |
+| `depends_on` | 否 | `[]` | 启动依赖的模块列表 |
+| `events` | 否 | `[]` | 本模块会发出的事件类型 |
+| `subscriptions` | 否 | `[]` | 本模块订阅的事件类型 |
+| `monitor` | 否 | `true` | Watchdog 是否监控此模块 |
+| `launch` | 否 | — | 自定义启动参数（见下文） |
+
+**state 取值：**
+
+| 值 | 说明 |
+|-----|------|
+| `enabled` | Kite 启动时自动启动 |
+| `manual` | 不自动启动，需通过 API 手动启动 |
+| `disabled` | 禁用，需 owner 修改后才能启动 |
+
+### 4.2 launch 配置块
+
+可选，用于自定义启动方式。所有子字段均可选：
+
+```yaml
+launch:
+  cmd: ["python3.11", "-u", "main.py", "--mode", "prod"]  # 覆盖 runtime+entry
+  env:                      # 额外环境变量
+    MY_VAR: "value"
+  cwd: "./subdir"           # 工作目录（相对于模块目录）
+  boot_stdin: false         # 是否通过 stdin 传 boot_info（默认 true）
+  timeout: 60               # 等待 module.ready 的超时秒数（默认 30）
+```
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `cmd` | `[]`（用 runtime+entry） | 非空时覆盖默认启动命令 |
+| `env` | `{}` | 合并到进程环境变量 |
+| `cwd` | `""`（用模块目录） | 相对路径基于模块目录解析 |
+| `boot_stdin` | `true` | 设为 false 时模块需自行获取 token |
+| `timeout` | `30` | 等待 module.ready 的秒数 |
+
+### 4.3 完整示例
+
+参考 `extensions/services/watchdog/module.md`：
+
+```markdown
+---
+name: watchdog
+display_name: Watchdog
+version: "1.0"
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+events:
+  - watchdog.module.unhealthy
+  - watchdog.module.recovered
+  - watchdog.alert
+subscriptions:
+  - module.started
+  - module.stopped
+---
+
+# Watchdog（保活模块）
+
+应用层健康监控扩展模块。
+
+- 心跳检测 — 定期检查各模块的 `/health` 端点
+- 资源监控 — 检测模块健康状态中的异常指标
+- 非 core 模块重启 — 发现异常时通过 Launcher API 重启模块
+```
+
+### 4.4 正文部分
+
+frontmatter 之后的 Markdown 正文是模块的说明文档。LLM 可以通过阅读本文档了解模块的功能和使用方法。建议包含功能说明、使用示例和注意事项。
+
+## 5. 启动协议
+
+这是模块开发的核心。模块启动后需要完成以下步骤才能被框架正式接纳。
+
+### 5.1 读取 boot_info
+
+Launcher 通过 stdin 管道向模块传入一行 JSON：
+
+```json
+{"token": "tok_abc123..."}
+```
+
+**注意事项：**
+- 必须用 **readline**（逐行读取），不能等 EOF — stdin 保持打开直到 module.ready 后才断开
+- token 是模块的身份凭证，后续所有 Registry API 调用都需要它
+
+**Python：**
+```python
+import sys, json
+line = sys.stdin.readline().strip()
+boot_info = json.loads(line)
+token = boot_info["token"]
+```
+
+**Node.js：**
+```javascript
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+rl.once('line', (line) => {
+  const { token } = JSON.parse(line.trim());
+  rl.close();
+  start(token);
+});
+```
+
+**错误写法（会死锁）：**
+```javascript
+// ❌ 等待 EOF — stdin 不关闭则永远挂起
+process.stdin.on('end', () => { ... });
+```
+
+### 5.2 SafeWriter 包装
+
+Launcher 在收到 module.ready 后会关闭 stdio 管道。此后模块的 stdout/stderr 写入会触发 BrokenPipeError。必须包装：
+
+```python
+class _SafeWriter:
+    def __init__(self, stream):
+        self._stream = stream
+    def write(self, s):
+        try: self._stream.write(s)
+        except (BrokenPipeError, OSError): pass
+    def flush(self):
+        try: self._stream.flush()
+        except (BrokenPipeError, OSError): pass
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+sys.stdout = _SafeWriter(sys.stdout)
+sys.stderr = _SafeWriter(sys.stderr)
+```
+
+Node.js 中 stdout 写入失败不会抛异常，通常无需额外处理。
+
+### 5.3 读取 kernel_port
+
+Launcher 通过 stdin 第二行 JSON 或环境变量传递 Kernel 端口：
+
+```python
+kernel_port = os.environ.get("KITE_KERNEL_PORT")
+if not kernel_port:
+    line = sys.stdin.readline().strip()
+    if line:
+        msg = json.loads(line)
+        if msg.get("kite") == "kernel_port":
+            kernel_port = msg["kernel_port"]
+
+kernel_port = int(kernel_port)
+```
+
+### 5.4 读取环境变量
+
+Launcher 通过环境变量向模块传递系统信息：
+
+| 环境变量 | 说明 | 示例 |
+|---------|------|------|
+| `KITE_KERNEL_PORT` | Kernel WebSocket 端口 | `52340` |
+| `KITE_PROJECT` | 框架代码根目录 | `/path/to/Kite` |
+| `KITE_CWD` | 用户工作目录 | `/home/user/project` |
+| `KITE_INSTANCE_DIR` | 当前实例工作区 | `~/.kite/workspace/project/` |
+| `KITE_DATA` | 用户级共享数据目录 | `~/.kite/data/` |
+| `KITE_MODULE_DATA` | 本模块的实例级数据目录 | `~/.kite/workspace/project/my_module/` |
+| `KITE_INSTANCE` | 实例标识 | `abc123` |
+| `KITE_DEBUG` | 调试模式（`1` = 开启） | `1` |
+| `KITE_ENV` | 运行环境 | `development` / `production` |
+
+最常用的是 `KITE_KERNEL_PORT`，它是连接 Kernel 的唯一入口：
+
+```python
+kernel_port = int(os.environ["KITE_KERNEL_PORT"])
+ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id={module_id}"
+```
+
+### 5.5 连接 Kernel WebSocket
+
+使用 token 和 module_id 连接 Kernel：
+
+```python
+import websockets.sync.client as ws_sync
+
+ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=my_module"
+ws = ws_sync.connect(ws_url)
+```
+
+**Node.js：**
+```javascript
+const WebSocket = require('ws');
+const ws = new WebSocket(`ws://127.0.0.1:${kernelPort}/ws?token=${token}&id=my_module`);
+```
+
+**连接失败处理：** 首次连接也使用与重连相同的退避策略（初始 0.3s、上限 5s、最多 10 次）。超过重试次数后 `sys.exit(1)`。详见 5.11 连接韧性。
+
+### 5.6 订阅事件（先于注册）
+
+**必须先订阅再注册。** 注册是报告，不能报告还没做的事。
+
+通过 JSON-RPC 调用 `event.subscribe`：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "event.subscribe",
+  "params": {
+    "events": ["module.>", "channel.message.*"]
+  }
+}
+```
+
+订阅模式语法详见 6.2 节。
+
+### 5.7 注册到 Kernel（在订阅之后）
+
+通过 JSON-RPC 调用 `registry.register`：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "registry.register",
+  "params": {
+    "module_id": "my_module",
+    "module_type": "service",
+    "name": "My Module",
+    "graceful_shutdown": true,
+    "events_subscribe": ["module.>"]
+  }
+}
+```
+
+注册返回：`{"ok": true, "ttl": 60, "heartbeat_interval": 30}`
+
+**Payload 字段说明：**
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | `"register"` |
+| `module_id` | 是 | 模块唯一标识（来自 module.md 的 `name`） |
+| `module_type` | 是 | 模块类型 |
+| `name` | 否 | 显示名称 |
+| `base_url` | 否 | HTTP 服务完整地址（如 `http://127.0.0.1:8080`） |
+| `health_path` | 否 | 健康检查的相对路径（如 `/health`） |
+| `display` | 否 | 展示信息，含 `urls` 子字段（如 `{"urls": {"Web 管理后台": "http://..."}}` |
+| `tools` | 否 | 字典：工具名 → {endpoint, description, parameters} |
+| `hooks` | 否 | 字典：hook 点名 → {endpoint, priority} |
+| `events_publish` | 否 | 字典：事件类型名 → 扩展信息 |
+| `events_subscribe` | 否 | 字典/列表：订阅的事件类型 |
+| `metadata` | 否 | 自定义元数据 |
+
+### 5.8 发送 module.ready
+
+**这是必须的。** Launcher 以收到此事件作为"启动成功"的判定标准。
+
+通过 JSON-RPC 调用 `event.publish` 发布 `module.ready`：
+
+```json
+{
+  "event": "module.ready",
+  "data": {
+    "module_id": "my_module",
+    "graceful_shutdown": true
+  }
+}
+```
+
+`data.graceful_shutdown: true` 声明模块支持优雅退出（详见第 7 节）。不声明或为 false 时，Launcher 停止模块时会直接 terminate。
+
+Launcher 收到 module.ready 后：
+1. 发布 `module.started` 事件（通知其他模块）
+2. 关闭该模块的 stdin 管道
+3. 后续通信全部走 Kernel WebSocket JSON-RPC
+
+### 5.9 心跳
+
+Kernel 通过 WebSocket 连接状态判断模块在线。模块可选实现应用层心跳，调用 `kernel.ping`：
+
+```json
+{"jsonrpc": "2.0", "id": "uuid", "method": "kernel.ping", "params": {}}
+```
+
+每 30 秒发送一次，超过 60 秒无心跳会被标记为 offline。
+
+### 5.10 完整启动流程概览
+
+```mermaid
+flowchart TD
+    Start([entry.py 启动]) --> Wrap[包装 SafeWriter<br/>防 BrokenPipeError]
+    Wrap --> ReadStdin[从 stdin 读取 token]
+    ReadStdin --> ReadPort[读取 kernel_port<br/>env 优先 / stdin 备选]
+    ReadPort --> Connect[连接 Kernel WebSocket<br/>ws://127.0.0.1:port/ws?token=...&id=...]
+    Connect --> Subscribe[④ RPC event.subscribe<br/>订阅需要的事件 — 先做!]
+    Subscribe --> Register[⑤ RPC registry.register<br/>注册到 Kernel — 后做，注册是报告]
+    Register --> Ready[⑥ RPC event.publish<br/>发布 module.ready — 必须!]
+    Ready --> Loop([⑦ 进入主循环<br/>监听事件 + 处理 RPC])
+
+    style Subscribe fill:#e1f5ff
+    style Register fill:#fff4e1
+    style Ready fill:#e8f5e9
+```
+
+**文字版（方便搜索）：**
+
+```
+entry.py 启动
+  │
+  ├─ ① 读 stdin → 拿到 token + kernel_port
+  ├─ ② 包装 SafeWriter（防 BrokenPipeError）
+  ├─ ③ 连接 Kernel WebSocket（ws://127.0.0.1:{port}/ws?token={token}&id={module_id}）
+  ├─ ④ RPC event.subscribe → 订阅事件（先做！）
+  ├─ ⑤ RPC registry.register → 注册到 Kernel（后做，注册是报告）
+  ├─ ⑥ RPC event.publish → 发送 module.ready 事件（必须）
+  ├─ ⑦ 进入主循环（监听事件 + 处理 RPC 请求）
+  └─ ⑧ 退出时 RPC registry.deregister
+```
+
+**关键设计原则：**
+
+- **先订阅，再注册** — 订阅是实际操作（"请给我发事件"），注册是声明报告（"我订阅了这些事件"）。不能报告还没做的事
+- **Kernel 生成所有 token** — 谁需要验证谁生成。Launcher 的 token 由 Kernel 通过 stdout 传递，其他模块的 token 由 Kernel 通过 RPC 生成后经 Launcher stdin 分发
+- **module.ready 必须发** — Launcher 以此为"启动成功"的判定标准
+
+### 5.11 连接韧性
+
+模块与 Kernel 的 WebSocket 连接可能因网络抖动、Kernel 重启等原因断开。所有模块必须实现自动重连机制，确保短暂断开后能恢复正常工作。
+
+#### 5.11.1 重连策略
+
+**参数：**
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 初始延迟 | 0.3s | 首次重连等待 |
+| 退避方式 | 指数翻倍 | 0.3 → 0.6 → 1.2 → 2.4 → 4.8 → 5 → 5 → ... |
+| 延迟上限 | 5s | 不超过此值 |
+| 最大重试次数 | 10 | 超过后 `sys.exit(1)` |
+| 总最大耗时 | ≈34s | 10 次重试的总等待时间 |
+
+**重连成功后必须重新执行完整握手：**
+
+1. `event.subscribe` — 重新订阅事件（Kernel 断开后订阅表已清空）
+2. `registry.register` — 重新注册（Kernel 断开后注册表已清空）
+3. `event.publish module.ready` — 重新发送就绪通知
+
+**成功连接后重置计数器：** `retry_delay = 0.3`，`attempt = 0`。
+
+#### 5.11.2 不重连的情况
+
+以下情况断开后应直接退出，不进行重连：
+
+- **收到 `module.shutdown` 后断开** — 被主动关闭，重连无意义
+- **认证失败** — Kernel 返回 WebSocket 关闭码 `4001`（认证失败）或 `4003`（权限拒绝），token 已失效，重连也会被拒绝
+
+#### 5.11.3 module.exiting 发送
+
+**所有退出路径都必须在退出前发送 `module.exiting` 事件，** 否则 Launcher 会将退出视为崩溃并触发重启。
+
+需要发送 `module.exiting` 的场景：
+- 优雅退出（`_handle_shutdown` 流程中，在 ack 之前）
+- 主动退出（任务完成、缺少条件等）
+- 重连耗尽退出（`_ws_loop` 中 `max_retries` 超限时）
+
+不需要发送的场景：
+- 崩溃退出（未捕获异常）— 此时 WS 已断开，无法发送
+
+#### 5.11.4 module.ready 可重复性
+
+`module.ready` 是一个**可重复的生命周期事件**，不应使用一次性标记（如 `_ready_sent`）限制发送。
+
+模块可能经历多次断开→重连循环。每次重连成功后都必须重新发送 `module.ready`，让 Kernel 和其他模块更新对该模块的可用性认知。
+
+**错误写法：**
+```python
+# ❌ 只发一次，重连后不再发送
+if not self._ready_sent:
+    await publish_module_ready()
+    self._ready_sent = True
+```
+
+**正确写法：**
+```python
+# ✅ 每次连接成功后都发送
+if not self._shutting_down:
+    await publish_module_ready()
+```
+
+#### 5.11.5 消息循环与 RPC 调用模式
+
+**消息循环三分支路由：** 模块的 WebSocket 消息循环需区分三类消息：
+
+| 消息类型 | 特征 | 处理方式 |
+|----------|------|----------|
+| 事件通知 | 有 `method`，无 `id` | 转发给事件处理器 |
+| RPC 请求 | 有 `method`，有 `id` | 执行并返回响应 |
+| RPC 响应 | 有 `id`，无 `method` | 路由到对应的等待者 |
+
+**RPC 调用两种模式：**
+
+- **Fire-and-forget（只发不等）** — 发送后不等响应。适用于 `event.publish`、`event.subscribe` 等不需要返回值的调用
+- **Request-Response（发送并等待）** — 发送后通过 waiter 表等待响应匹配。适用于 `registry.lookup`、`launcher.list_modules` 等需要读取返回值的调用。超时默认 5s，超时返回错误 dict
+
+**选择依据：** 需要读取响应 `result` 字段 → Request-Response；仅发送通知 → Fire-and-forget。
+
+> **参考实现：** `extensions/services/watchdog/entry.py` 中的 `_rpc_call`、`_rpc_call_with_response`、消息循环三分支路由。其他模块（web、assistant、acp_channel）也遵循相同模式。
+
+## 5.5 RPC 死锁防范（CRITICAL）
+
+**这是所有模块必须遵守的架构规范，违反会导致 RPC 超时死锁。**
+
+### 问题根源
+
+WebSocket 接收循环是单线程的 `async for` 循环，处理三种消息：
+
+1. **事件通知**（无 id）— 单向推送，不需要响应
+2. **入站 RPC 请求**（有 id + method）— 需要执行 handler 并返回响应
+3. **出站 RPC 响应**（有 id + result/error）— 匹配之前发出的请求
+
+**死锁场景：** 如果在处理入站 RPC 时 `await` 了 handler，而 handler 内部又调用 `rpc_call_with_response()` 发出站请求并等待响应，那么：
+
+- 接收循环被 `await handler()` 阻塞
+- 出站 RPC 的响应到达，但接收循环无法处理（正在等 handler 返回）
+- handler 在等出站响应，出站响应在等接收循环 → **死锁，5s 超时**
+
+### 正确处理策略
+
+**所有模块的接收循环必须遵循以下模式：**
+
+```python
+# CRITICAL: RPC 死锁防范
+# - 入站 RPC 请求必须用 create_task() 异步执行，不可 await
+# - 原因：如果 handler 内部调用 rpc_call() 发出站请求，出站响应需要本接收循环来分发
+# - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
+# - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
+
+async for raw in ws:
+    try:
+        msg = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        continue
+
+    try:
+        has_method = "method" in msg
+        has_id = "id" in msg
+
+        if has_method and not has_id:
+            # 事件通知 — 同步处理（快速，不会发 RPC）
+            await handle_event_notification(msg)
+        elif has_method and has_id:
+            # 入站 RPC 请求 — 异步执行，防止死锁
+            asyncio.create_task(handle_rpc_request(ws, msg))
+        elif has_id:
+            # 出站 RPC 响应 — 同步匹配 waiter
+            match_rpc_response(msg)
+    except Exception as e:
+        print(f"[module] 消息处理异常（已忽略）: {e}")
+```
+
+### 关键点
+
+1. **入站 RPC 必须 `create_task`**，不可 `await`
+2. **事件通知可以 `await`**（它们不会反向发 RPC）
+3. **RPC 响应匹配必须同步**（直接写 dict + set Event）
+4. **所有模块都要遵守**，即使当前 handler 不发 RPC（未来可能会加）
+
+### 已知案例
+
+- **Launcher** — `_rpc_restart_module` 调用 `kernel.register_tokens`，修复前超时 5s
+- **Watchdog** — `_restart_module_by_id` 调用 `launcher.restart_module`，修复前超时 5s
+
+### 参考实现
+
+所有现有模块已修复：
+- `launcher/entry.py:665` — Launcher 接收循环
+- `extensions/services/watchdog/entry.py:460` — Watchdog 接收循环
+- `extensions/services/web/server.py:266` — Web 接收循环
+- `extensions/services/backup/entry.py:426` — Backup 接收循环
+- `extensions/services/model_service/entry.py:426` — Model Service 接收循环
+- `extensions/agents/assistant/server.py:122` — Assistant 接收循环
+- `extensions/channels/acp_channel/server.py:122` — ACP Channel 接收循环
+
+**新模块开发时，直接复制上述任一模块的接收循环结构即可。**
+
+## 6. 事件系统
+
+### 6.1 发布事件
+
+通过 Kernel WebSocket 发送 JSON-RPC 请求：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid-string",
+  "method": "event.publish",
+  "params": {
+    "event_id": "uuid-string",
+    "event": "my_module.something_happened",
+    "data": {
+      "key": "value"
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `event_id` | 是 | 唯一 ID（UUID），用于去重 |
+| `event` | 是 | 事件类型（点分层级，如 `channel.message.received`） |
+| `data` | 否 | 事件数据 |
+
+Kernel 返回 JSON-RPC 响应：`{"jsonrpc": "2.0", "id": "uuid", "result": {}}`
+
+### 6.2 订阅模式
+
+使用 NATS 风格通配符，事件类型以 `.` 分隔：
+
+| 模式 | 说明 | 匹配示例 | 不匹配 |
+|------|------|---------|--------|
+| `session.started` | 精确匹配 | `session.started` | `session.ended` |
+| `channel.*` | `*` 匹配恰好一段 | `channel.connected` | `channel.message.received` |
+| `channel.>` | `>` 匹配一段或多段（只能在末尾） | `channel.connected`、`channel.message.received` | `session.started` |
+| `>` | 匹配所有事件 | 任何事件 | — |
+
+订阅和取消订阅：
+
+```json
+{"jsonrpc": "2.0", "id": "uuid", "method": "event.subscribe", "params": {"events": ["channel.message.*", "session.*"]}}
+{"jsonrpc": "2.0", "id": "uuid", "method": "event.unsubscribe", "params": {"events": ["channel.message.*"]}}
+```
+
+### 6.3 发布确认
+
+发布事件是 JSON-RPC 请求，Kernel 返回标准 JSON-RPC 响应作为确认：
+
+```json
+{"jsonrpc": "2.0", "id": "请求id", "result": {"ok": true, "routed": 3}}
+```
+
+如果发布失败（格式错误、去重等），返回 error：
+
+```json
+{"jsonrpc": "2.0", "id": "请求id", "error": {"code": -32602, "message": "duplicate event_id"}}
+```
+
+### 6.4 接收事件
+
+订阅的事件以 **JSON-RPC Notification** 形式推送给模块（有 `method` 字段，无 `id` 字段）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event_id": "uuid",
+    "event": "channel.message.received",
+    "source": "acp_channel",
+    "timestamp": "2026-03-03T12:00:00Z",
+    "data": {"message": "hello"}
+  }
+}
+```
+
+消息循环需区分三类消息（事件通知 / RPC 请求 / RPC 响应），判断方法和处理模式详见 5.11.5。
+
+### 6.5 常用系统事件
+
+| 事件 | 来源 | 说明 |
+|------|------|------|
+| `module.starting` | Launcher | 模块即将启动 |
+| `module.ready` | 模块 | 模块就绪（必须发送） |
+| `module.started` | Launcher | 模块启动成功 |
+| `module.stopped` | Launcher | 模块已停止 |
+| `module.shutdown` | Launcher | 通知模块准备退出 |
+| `module.shutdown.ack` | 模块 | 确认收到关闭通知 |
+| `module.shutdown.ready` | 模块 | 清理完成，可以终止 |
+| `module.exiting` | 模块 | 模块主动退出通知 |
+| `module.offline` | Kernel | 模块 WS 断开超过 5s 防抖后确认离线（系统事件，自动广播给所有模块，无需显式订阅） |
+| `session.started` | Kernel | 会话开始 |
+| `session.ended` | Kernel | 会话结束 |
+| `channel.message.received` | Channel | 渠道收到消息 |
+| `channel.message.sent` | Channel | 渠道发出消息 |
+| `channel.connected` | Channel | 渠道上线 |
+| `channel.disconnected` | Channel | 渠道断线 |
+
+### 6.6 事件处理与 RPC 调用的并发陷阱
+
+**核心原则:不要在事件处理函数中直接 await RPC 调用,否则会阻塞消息接收循环,导致后续事件(如 shutdown)无法及时处理。**
+
+#### 问题场景
+
+假设你在事件处理函数中调用 RPC:
+
+```python
+async def handle_event(event):
+    if event["event"] == "module.started":
+        # ❌ 错误:直接 await RPC 调用会阻塞消息循环
+        result = await rpc_call("launcher.list_modules")
+        # 在等待 RPC 响应期间,WebSocket 消息队列中的其他事件(如 shutdown)无法被处理
+```
+
+**后果:**
+- 如果 RPC 响应延迟(如对方正在处理其他任务),消息接收循环会被阻塞
+- 在此期间到达的 `module.shutdown` 等关键事件会积压在队列中
+- 可能导致模块无法及时响应 shutdown,被 Launcher 强制 kill
+
+#### 解决方案
+
+**方案 1:使用 asyncio.create_task 异步执行**
+
+```python
+async def handle_event(event):
+    if event["event"] == "module.started":
+        # ✅ 正确:将 RPC 调用放到后台任务中
+        asyncio.create_task(self._handle_module_started())
+
+async def _handle_module_started(self):
+    result = await rpc_call("launcher.list_modules")
+    # 处理结果...
+```
+
+**方案 2:将 RPC 调用放到独立的循环中**
+
+```python
+# 主消息循环:只处理事件,不阻塞
+async for raw in ws:
+    msg = json.loads(raw)
+    if msg.get("method") == "event":
+        await handle_event(msg["params"])  # 快速处理,不阻塞
+
+# 独立的后台任务:定期执行 RPC 调用
+async def background_task():
+    while running:
+        result = await rpc_call("some.method")
+        # 处理结果...
+        await asyncio.sleep(interval)
+
+# 启动时创建后台任务
+asyncio.create_task(background_task())
+```
+
+#### 架构建议
+
+- **消息接收循环**:只负责接收和分发消息,保持快速响应
+- **事件处理函数**:只做轻量级处理(更新状态、触发回调),不阻塞
+- **RPC 调用**:放到独立的后台任务或使用 `create_task` 异步执行
+- **关键事件**(如 `module.shutdown`):必须在事件处理函数中立即处理,不能延迟
+
+#### 实际案例
+
+Watchdog 模块的修复:
+
+```python
+# ❌ 旧代码:阻塞消息循环
+async def handle_event(event):
+    if event["event"] == "module.started":
+        await self.discover_modules()  # RPC 调用,阻塞 10 秒
+
+# ✅ 新代码:异步执行
+async def handle_event(event):
+    if event["event"] == "module.started":
+        asyncio.create_task(self.discover_modules())  # 不阻塞
+```
+
+修复后,Watchdog 能够在 RPC 调用期间正常接收 shutdown 事件,退出时间从 5.38s 降到 1.36s。
+
+## 7. 优雅退出
+
+优雅退出让模块有机会完成清理工作后再退出，避免数据丢失和资源泄漏。所有模块**建议**实现，不实现的模块仍可运行，但会被直接终止。
+
+### 7.1 声明支持
+
+在 `module.ready` 事件的 `data` 中声明 `graceful_shutdown: true`：
+
+```json
+{
+  "event": "module.ready",
+  "data": {
+    "module_id": "my_module",
+    "graceful_shutdown": true
+  }
+}
+```
+
+不声明或为 `false` 时，Launcher 停止时直接 terminate，不走事件通知流程。
+
+### 7.2 停止流程总览
+
+```mermaid
+sequenceDiagram
+    participant L as Launcher
+    participant K as Kernel
+    participant M as 模块
+
+    L->>K: event.publish: module.shutdown<br/>(target: my_module, timeout: 10)
+    K-->>M: 转发 module.shutdown 通知
+
+    M->>K: event.publish: module.shutdown.ack<br/>(estimated_cleanup: 5)
+    K-->>L: 转发 ack
+
+    Note over M: 执行清理工作...
+
+    M->>K: event.publish: module.shutdown.ready<br/>(module_id: my_module)
+    K-->>L: 转发 ready
+
+    Note over L: 收到 ready → 终止进程
+```
+
+### 7.3 Launcher 侧决策逻辑
+
+```
+Launcher 要停止模块 X：
+  │
+  ├─ Step 0: 检查 X 是否声明了 graceful_shutdown
+  │    ├─ 未声明 → 直接 proc.terminate()，等 5s，超时 proc.kill()，结束
+  │    └─ 已声明 → 进入 Step 1
+  │
+  ├─ Step 1: 通过 Kernel 发送 module.shutdown 事件
+  │
+  ├─ Step 2: 等待 module.shutdown.ack（超时 3s）
+  │    ├─ 收到 ack:
+  │    │    wait_time = min(ack.estimated_cleanup, launcher_timeout)
+  │    │    → 进入 Step 3
+  │    │
+  │    └─ 未收到 ack（3s 超时）:
+  │         → proc.terminate()，等 5s，超时 proc.kill()
+  │
+  ├─ Step 3: 等待 module.shutdown.ready 或超时
+  │    ├─ 收到 ready → 立即 proc.kill()，结束
+  │    └─ 超时 → proc.terminate()，等 3s，超时 proc.kill()
+  │
+  └─ 清理: 从进程表移除，发 module.stopped 事件
+```
+
+### 7.4 事件定义
+
+#### module.shutdown（Launcher / Kernel → 模块）
+
+`module.shutdown` 有两种使用模式：
+
+**模式 1：定向关闭**（Launcher 关闭特定模块）
+
+```json
+{
+  "event": "module.shutdown",
+  "data": {
+    "module_id": "my_module",
+    "reason": "stop_requested",
+    "timeout": 10
+  }
+}
+```
+
+**模式 2：广播关闭**（Kernel 通知所有模块系统即将关闭）
+
+```json
+{
+  "event": "module.shutdown",
+  "data": {
+    "reason": "launcher_lost"
+  }
+}
+```
+
+注意：广播模式**没有 `module_id` 字段**，所有模块都应响应。
+
+**模块接收判断逻辑：**
+
+```python
+if event_type == "module.shutdown":
+    target = data.get("module_id", "")
+    reason = data.get("reason", "")
+    # 定向关闭（target == 自己）或广播关闭（无 target 或 launcher_lost）
+    if target == "my_module" or not target or reason == "launcher_lost":
+        await handle_shutdown()
+```
+
+**reason 取值：**
+
+| reason | 模式 | 说明 |
+|--------|------|------|
+| `stop_requested` | 定向 | 手动停止（API 调用） |
+| `system_shutdown` | 定向 | 系统退出（Ctrl+C / SIGTERM） |
+| `hot_update` | 定向 | 热更新 |
+| `restart` | 定向 | 重启 |
+| `resource_critical` | 定向 | 资源异常（Watchdog 触发） |
+| `launcher_lost` | 广播 | Launcher 异常终止超过 35s，Kernel 触发系统关闭 |
+
+#### module.shutdown.ack（模块 → Launcher）
+
+```json
+{
+  "event": "module.shutdown.ack",
+  "data": {
+    "module_id": "my_module",
+    "estimated_cleanup": 5
+  }
+}
+```
+
+`estimated_cleanup`：模块预估的清理时间（秒）。Launcher 取 `min(estimated_cleanup, launcher_timeout)` 作为实际等待时间。
+
+#### module.shutdown.ready（模块 → Launcher）
+
+```json
+{
+  "event": "module.shutdown.ready",
+  "data": {
+    "module_id": "my_module"
+  }
+}
+```
+
+模块发出此事件后应立即退出进程（exit code 0）。
+
+### 7.5 模块实现清单
+
+收到 `module.shutdown` 后，模块应按顺序执行：
+
+1. **立即回复 ack** — 含合理的 `estimated_cleanup` 秒数
+2. **停止接受新请求**
+3. **完成进行中的请求**（有超时保护）
+4. **flush 缓冲区**（日志等）
+5. **关闭网络连接**（WebSocket、HTTP）
+6. **持久化必要状态**
+7. **释放系统资源**（文件句柄、临时文件等）
+8. **发送 shutdown.ready**
+9. **立即退出进程**（exit code 0）
+
+### 7.6 参考实现
+
+- **Python**：`extensions/services/watchdog/entry.py` 中的 `_handle_shutdown()`
+- **Node.js**：`test_modules/hello_node/entry.js` 中的 shutdown 处理
+
+核心流程：收到 `module.shutdown` → 发 `module.exiting` → 发 `module.shutdown.ack` → 清理 → 发 `module.shutdown.ready` → `exit(0)`。
+
+### 7.8 不实现的后果
+
+- Launcher 直接 `proc.terminate()`（Linux 发 SIGTERM，Windows 调 TerminateProcess）
+- 等待 5 秒后 `proc.kill()`（强杀）
+- 无清理机会，可能丢失未持久化的数据
+
+详细规范见 [优雅退出规范](优雅退出规范.md)。
+
+### 7.9 异步退出的常见陷阱与最佳实践
+
+**问题：在异步协程中调用 `sys.exit()` 导致未捕获异常**
+
+当 `_handle_shutdown()` 是通过 `asyncio.create_task()` 启动的后台任务时，在其中调用 `sys.exit()` 会抛出 `SystemExit` 异常，导致 "Task exception was never retrieved" 错误。虽然进程仍会退出，但会留下错误日志。
+
+**错误示例：**
+
+```python
+async def _handle_shutdown(self, ws):
+    # ... 清理逻辑 ...
+    await self._rpc_call(ws, "event.publish", {
+        "event": "module.shutdown.ready",
+        "data": {"module_id": "my_module"},
+    })
+    sys.exit(0)  # ❌ 在协程中直接退出，抛出 SystemExit 异常
+```
+
+**正确做法：根据模块类型选择退出方式**
+
+#### 纯 WebSocket 客户端模块
+
+特点：只连接 Kernel WebSocket，无 HTTP 服务（如 assistant、backup、model_service、watchdog）
+
+```python
+async def _handle_shutdown(self, ws):
+    # Step 1-4: 发送 ack → exiting → 清理 → ready
+    await self._rpc_call(ws, "event.publish", {
+        "event": "module.shutdown.ready",
+        "data": {"module_id": "my_module"},
+    })
+
+    # Step 5: 关闭 WebSocket 连接
+    try:
+        await ws.close(code=1000, reason="Graceful shutdown")
+        print("[my_module] WebSocket closed")
+    except Exception as e:
+        print(f"[my_module] Failed to close WebSocket: {e}")
+
+    # ✅ 不调用 sys.exit()，让事件循环自然结束
+```
+
+#### HTTP 服务模块
+
+特点：提供 HTTP API，使用 uvicorn 运行（如 audit、logs）
+
+```python
+async def _handle_shutdown(self):
+    # Step 1-4: 发送 ack → exiting → 清理 → ready
+    if self._ws:
+        await self._rpc_call(self._ws, "event.publish", {
+            "event": "module.shutdown.ready",
+            "data": {"module_id": "my_module"},
+        })
+
+    # Step 5: 触发 uvicorn 优雅关闭
+    if self._uvicorn_server:
+        self._uvicorn_server.should_exit = True
+
+    # ✅ 让 uvicorn 自然退出，不调用 sys.exit()
+```
+
+#### HTTP + WebSocket 混合模块（最佳实践）
+
+特点：提供 HTTP API + 服务端 WebSocket + 连接 Kernel WebSocket（如 web、evol）
+
+```python
+async def _handle_shutdown(self):
+    # Step 1-2: 发送 ack → exiting
+
+    # Step 3: 清理后台任务
+    if self._test_task:
+        self._test_task.cancel()
+
+    # Step 4: 关闭服务端 WebSocket 连接（带超时保护）
+    if hasattr(self.app.state, 'relay_service'):
+        try:
+            await asyncio.wait_for(
+                self.app.state.relay_service.close_all_sessions(),
+                timeout=1.0  # ✅ 超时保护，防止挂起
+            )
+        except asyncio.TimeoutError:
+            print("[my_module] Relay service close timeout")
+        except Exception as e:
+            print(f"[my_module] Failed to close relay sessions: {e}")
+
+    # Step 5: 发送 ready
+    await self._rpc_call(self._ws, "event.publish", {
+        "event": "module.shutdown.ready",
+        "data": {"module_id": "my_module"},
+    })
+
+    # Step 6: 等待事件发送完成
+    await asyncio.sleep(0.1)
+
+    # Step 7: 关闭 Kernel WebSocket
+    if self._ws:
+        try:
+            await self._ws.close(code=1000, reason="Graceful shutdown")
+        except Exception as e:
+            print(f"[my_module] Failed to close Kernel WebSocket: {e}")
+
+    # Step 8: 触发 uvicorn 优雅关闭
+    if self._uvicorn_server:
+        self._uvicorn_server.should_exit = True
+
+    # ✅ 让 uvicorn 自然退出，不调用 sys.exit()
+```
+
+**关键要点：**
+
+1. **永远不要在异步协程中调用 `sys.exit()`** — 让事件循环自然结束
+2. **关闭 WebSocket 连接要加异常处理** — 防止关闭失败导致挂起
+3. **关闭服务端 WebSocket 要加超时保护** — 使用 `asyncio.wait_for(timeout=1.0)`
+4. **HTTP 服务模块使用 `uvicorn_server.should_exit = True`** — 触发优雅关闭
+5. **发送 ready 后等待一小段时间** — 确保事件发送完成（0.1s 足够）
+
+**参考实现：**
+
+- 纯 WS 客户端：`extensions/agents/assistant/server.py`
+- HTTP 服务：`extensions/services/audit/server.py`
+- 混合模块（最佳实践）：`extensions/services/evol/server.py`
+
+## 8. 模块主动退出
+
+当模块自身决定退出时，**必须**先发送 `module.exiting` 事件，避免被 Launcher 当作崩溃重启。
+
+**所有退出路径都要发 `module.exiting`：** 无论是任务完成退出、缺少条件退出，还是重连耗尽退出，只要 WS 连接仍然可用，就必须在退出前发送此事件。详见 5.11.3。
+
+`module.exiting` 事件 `data` 字段：
+
+```json
+{
+  "module_id": "my_module",
+  "reason": "task complete",
+  "action": "none"
+}
+```
+
+**action 取值：**
+
+| 值 | 说明 |
+|----|------|
+| `none` | 不重启（默认），Launcher 设 desired_state=stopped |
+| `restart` | 请求立即重启 |
+| `restart_delay` | 延迟重启（默认 5s） |
+
+适用场景：一次性任务完成后退出、缺少必要条件主动退出、自我升级需要重启。
+
+## 9. 提供工具
+
+### 9.1 工具定义
+
+在模块的 `tools/` 目录下创建工具子目录：
+
+```
+my_module/
+└── tools/
+    └── my_tool/
+        ├── tool.md       # 工具定义
+        └── handler.py    # 工具实现
+```
+
+**tool.md** 示例：
+
+```markdown
+---
+name: my_tool
+description: "一句话描述工具功能"
+parameters:
+  arg1:
+    type: string
+    description: "参数说明"
+    required: true
+  arg2:
+    type: integer
+    description: "可选参数"
+---
+
+# My Tool
+
+详细使用说明...
+```
+
+### 9.2 handler.py 签名
+
+```python
+async def execute(args: dict, context: dict) -> str:
+    """执行工具，返回结果字符串。"""
+    arg1 = args.get("arg1", "")
+    # 处理逻辑...
+    return "工具执行结果"
+
+
+async def check_permission(args: dict, context: dict) -> str | None:
+    """权限检查。返回 None 表示允许，返回字符串表示拒绝原因。"""
+    return None  # 允许所有调用
+```
+
+**context 包含的字段：**
+
+| 字段 | 说明 |
+|------|------|
+| `task_info` | 当前任务信息 |
+| `webhook` | Webhook 回调 |
+| `engine` | 对话引擎实例 |
+| `data_dir` | 数据目录 |
+| `root_dir` | 项目根目录 |
+| `is_owner` | 是否为 owner |
+| `permission_files` | 权限文件列表 |
+
+### 9.3 在 Registry 注册工具
+
+注册 payload 的 `tools` 字段中声明工具：
+
+```json
+{
+  "tools": {
+    "my_tool": {
+      "endpoint": "/tools/my_tool",
+      "description": "工具描述",
+      "parameters": {"arg1": "string"}
+    }
+  }
+}
+```
+
+其他模块（如 Agent）通过 Registry 的 `/lookup?field=tools.my_tool` 发现工具，再通过 HTTP 调用 `base_url + endpoint`。
+
+## 10. 启动依赖
+
+### 10.1 声明依赖
+
+在 `module.md` 中使用 `depends_on`：
+
+```yaml
+---
+name: my_module
+depends_on:
+  - event_hub
+  - kernel
+---
+```
+
+### 10.2 排序保证
+
+Launcher 按拓扑序启动模块：依赖模块的 `module.ready` 收到后，才启动当前模块。
+
+core 模块（Kernel）的启动顺序由 Launcher 硬编码保证，不需要在 `depends_on` 中声明。
+
+如果依赖的模块是 `manual` 状态，Launcher 会自动启动它。`disabled` 状态的模块不可被依赖，会报错。
+
+## 11. 模块发现与放置
+
+### 11.1 内置扫描路径
+
+Launcher 自动扫描以下目录（无需配置）：
+
+| 路径 | 深度 | 说明 |
+|------|------|------|
+| `extensions/` | 2 | 扩展模块（可嵌套一层，如 `extensions/services/watchdog/`） |
+
+### 11.2 用户扩展路径
+
+`KITE_MODULES` 环境变量指向用户安装的扩展模块目录（如 `~/.kite/modules/`）。
+
+### 11.3 自定义发现源
+
+在 Launcher 的 `module.md` 中配置 `discovery`，添加额外的扫描目录或模块列表文件：
+
+```yaml
+discovery:
+  test:
+    type: scan_dir
+    path: test_modules
+    enabled: true
+  extra:
+    type: module_list
+    path: data/modules.txt
+    enabled: false
+```
+
+- `scan_dir` — 递归扫描目录，找到 `module.md` 即视为模块
+- `module_list` — 逐行读取文件，每行一个模块目录路径
+
+### 11.4 模块名唯一性
+
+以 `module.md` 中的 `name` 字段（非目录名）为准。重名模块只加载先发现的，后续跳过并打印警告。
+
+## 12. 数据存储
+
+模块有三个可用的存储位置：
+
+| 位置 | 环境变量 | 生命周期 | 用途 |
+|------|---------|---------|------|
+| 实例级数据 | `KITE_MODULE_DATA` | 每次运行隔离 | 日志、缓存、运行时状态 |
+| 共享级数据 | `KITE_DATA` | 跨实例持久 | 用户数据、全局配置 |
+| 用户可见 | `KITE_CWD/.kite/` | 用户项目目录 | 用户需要查看的文件 |
+
+```python
+import os
+
+# 实例级（写运行日志、临时状态）
+module_data = os.environ.get("KITE_MODULE_DATA", "")
+my_state = os.path.join(module_data, "state.json")
+
+# 共享级（写持久数据）
+data_dir = os.environ.get("KITE_DATA", "")
+my_persist = os.path.join(data_dir, "my_module", "history.jsonl")
+
+# 用户可见（写用户需要查看的内容）
+cwd = os.environ.get("KITE_CWD", "")
+user_log = os.path.join(cwd, ".kite", "logs", "my_module.log")
+```
+
+## 12.5 日志与异常处理
+
+每个模块必须实现 `latest.log`（运行日志）和 `crashes.jsonl`（崩溃日志），均位于 `{KITE_MODULE_DATA}/log/` 下，每次启动时清空。Python 模块可直接使用 `core/kite_log.py` 工具库：
+
+```python
+from core.kite_log import init_module_log, setup_exception_hooks, install_log_hook
+
+def main():
+    init_module_log("my_module")       # 初始化 latest.log + crashes.jsonl
+    setup_exception_hooks("my_module") # 全局异常钩子（主线程 + 子线程）
+    install_log_hook()                 # stdout 自动写入日志文件
+    # ... 模块业务逻辑 ...
+```
+
+完整规范（日志目录结构、JSONL 字段定义、module.crash 事件、控制台输出格式、Node.js 实现示例等）见 [日志与异常处理规范](日志与异常处理规范.md)。
+
+## 13. 业务配置
+
+模块可以有自己的业务配置文件，与框架层面的模块配置（module.md）分离。
+
+### 13.1 配置分层
+
+Kite 框架中有两层配置：
+
+| 配置层 | 文件 | 用途 | 格式 |
+|--------|------|------|------|
+| **模块配置** | `module.md` | 框架层面的元数据（name、type、runtime、entry 等），用于 Launcher 发现和启动模块 | YAML frontmatter |
+| **业务配置** | `*.json5` | 模块自身的业务逻辑配置，与框架无关 | JSON5 |
+
+**设计原则：**
+- 模块配置是框架契约，变更需谨慎
+- 业务配置是模块内部实现细节，可以自由调整
+- 两者分离，职责清晰
+
+### 13.2 声明业务配置
+
+在 `module.md` 的 frontmatter 中添加 `businesses` 块：
+
+```yaml
+---
+name: web
+display_name: Web Management
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+
+# 业务配置列表
+businesses:
+  - name: web_server
+    type: http_service
+    description: Web 管理界面和 API 服务
+    config_file: web_config.json5
+
+  - name: relay_service
+    type: kernel_relay
+    description: Kernel WebSocket 中转服务
+    config_file: relay_config.json5
+---
+```
+
+**字段说明：**
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 业务名称（唯一标识） |
+| `type` | 否 | 业务类型（自定义，用于分类） |
+| `description` | 否 | 业务描述 |
+| `config_file` | 是 | 配置文件路径（相对于模块目录） |
+
+### 13.3 配置文件格式
+
+推荐使用 **JSON5** 格式（支持注释和尾随逗号）：
+
+```json5
+// web_config.json5
+{
+  // Web 服务配置
+  server: {
+    host: "0.0.0.0",
+    port: 18766,
+    ssl: false,
+    ssl_cert: null,
+    ssl_key: null
+  },
+
+  // 静态文件配置
+  static: {
+    directory: "static",
+    cache_max_age: 3600  // 秒
+  },
+
+  // CORS 配置
+  cors: {
+    enabled: false,
+    origins: ["*"]
+  }
+}
+```
+
+### 13.4 加载业务配置
+
+使用 `config_loader.py` 工具（零共享代码依赖，可复制到任何模块）：
+
+```python
+from pathlib import Path
+from config_loader import load_business_configs, get_business_config
+
+# 方式 1：加载所有业务配置
+module_dir = Path(__file__).parent
+configs = load_business_configs(str(module_dir))
+
+# 返回格式：
+# {
+#     "web_server": {
+#         "metadata": {"name": "web_server", "type": "http_service", ...},
+#         "config": { ... }  # JSON5 配置内容
+#     },
+#     "relay_service": { ... }
+# }
+
+# 方式 2：加载单个业务配置
+relay_config = get_business_config(str(module_dir), "relay_service")
+if relay_config:
+    config = relay_config['config']
+    print(f"Relay port: {config['relay']['reconnect_timeout']}")
+```
+
+### 13.5 config_loader.py 实现
+
+这是一个独立的工具文件，可以直接复制到任何模块使用：
+
+```python
+"""
+配置加载工具
+
+用于加载模块的业务配置。支持从 module.md 读取业务配置块，
+并动态加载对应的 JSON5 配置文件。
+
+零共享代码依赖 - 此文件可以独立拷贝到其他模块使用。
+"""
+
+import os
+import re
+import json5
+import yaml
+
+
+def load_module_metadata(module_dir: str) -> dict:
+    """读取 module.md 的 YAML frontmatter。"""
+    md_path = os.path.join(module_dir, "module.md")
+    if not os.path.exists(md_path):
+        return {}
+
+    try:
+        with open(md_path, "r", encoding="utf-8") as f:
+            text = f.read()
+        # 提取 YAML frontmatter (--- ... ---)
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if m:
+            return yaml.safe_load(m.group(1)) or {}
+    except Exception as e:
+        print(f"[config_loader] Error loading module.md: {e}")
+    return {}
+
+
+def load_business_configs(module_dir: str) -> dict:
+    """
+    加载所有业务配置。
+
+    Returns:
+        业务配置字典，格式：
+        {
+            "business_name": {
+                "metadata": {...},
+                "config": {...}
+            }
+        }
+    """
+    metadata = load_module_metadata(module_dir)
+    businesses = metadata.get('businesses', [])
+
+    configs = {}
+    for business in businesses:
+        name = business.get('name')
+        config_file = business.get('config_file')
+
+        if not name or not config_file:
+            print(f"[config_loader] Warning: Invalid business entry: {business}")
+            continue
+
+        config_path = os.path.join(module_dir, config_file)
+        if os.path.exists(config_path):
+            try:
+                with open(config_path, "r", encoding="utf-8") as f:
+                    configs[name] = {
+                        'metadata': business,
+                        'config': json5.load(f)
+                    }
+            except Exception as e:
+                print(f"[config_loader] Error loading {config_file}: {e}")
+        else:
+            print(f"[config_loader] Warning: Config file not found: {config_file}")
+
+    return configs
+
+
+def get_business_config(module_dir: str, business_name: str) -> dict | None:
+    """获取指定业务的配置。"""
+    configs = load_business_configs(module_dir)
+    return configs.get(business_name)
+```
+
+### 13.6 使用示例
+
+参考 `extensions/services/web/` 模块：
+
+**目录结构：**
+```
+web/
+├── module.md              # 模块配置 + businesses 声明
+├── entry.py               # 模块入口
+├── config_loader.py       # 配置加载工具
+├── web_config.json5       # Web 服务配置
+├── relay_config.json5     # 中转服务配置
+└── server.py              # 业务逻辑
+```
+
+**在 server.py 中使用：**
+```python
+from pathlib import Path
+from config_loader import load_business_configs
+
+module_dir = Path(__file__).parent
+business_configs = load_business_configs(str(module_dir))
+
+# 获取 Web 服务配置
+web_config = business_configs.get('web_server')['config']
+host = web_config['server']['host']
+port = web_config['server']['port']
+
+# 获取中转服务配置
+relay_config = business_configs.get('relay_service')['config']
+reconnect_timeout = relay_config['relay']['reconnect_timeout']
+```
+
+### 13.7 配置验证（可选）
+
+推荐使用 JSON Schema 验证配置文件：
+
+```python
+import jsonschema
+
+# 定义 schema
+web_schema = {
+    "type": "object",
+    "properties": {
+        "server": {
+            "type": "object",
+            "properties": {
+                "host": {"type": "string"},
+                "port": {"type": "integer", "minimum": 1, "maximum": 65535}
+            },
+            "required": ["host", "port"]
+        }
+    },
+    "required": ["server"]
+}
+
+# 验证配置
+try:
+    jsonschema.validate(config, web_schema)
+except jsonschema.ValidationError as e:
+    print(f"配置验证失败: {e.message}")
+```
+
+### 13.8 配置热重载（可选）
+
+如果需要运行时更新配置，可以监听配置文件变化：
+
+```python
+import time
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+class ConfigReloadHandler(FileSystemEventHandler):
+    def on_modified(self, event):
+        if event.src_path.endswith('.json5'):
+            print(f"配置文件变更: {event.src_path}")
+            # 重新加载配置
+            reload_config()
+
+observer = Observer()
+observer.schedule(ConfigReloadHandler(), path=module_dir, recursive=False)
+observer.start()
+```
+
+### 13.9 注意事项
+
+1. **零共享代码依赖** — `config_loader.py` 可以复制到任何模块，不依赖框架代码
+2. **配置文件位置** — 业务配置文件放在模块目录下，不要放在 `data/` 目录（那是运行时数据）
+3. **敏感信息** — API Key 等敏感信息不要写在配置文件中，使用环境变量或单独的 secrets 文件
+4. **版本兼容** — 配置文件格式变更时，注意向后兼容或提供迁移脚本
+
+## 14. 跨平台与跨语言注意事项
+
+### 14.1 Windows 差异
+
+- Windows 没有 SIGTERM — 使用事件机制替代（module.shutdown 事件），不要依赖信号处理
+- `proc.terminate()` 在 Windows 上等同 SIGKILL（无法捕获），优雅退出必须走事件
+- 路径分隔符 — 使用 `os.path.join()` 或 `pathlib`，不要硬编码 `/`
+
+### 14.2 多语言支持
+
+| runtime | 启动命令 | entry 文件 |
+|---------|---------|-----------|
+| `python` | `python entry.py` | `.py` |
+| `node` | `node entry.js` | `.js` |
+| `binary` | `./entry` | 可执行文件 |
+
+通信协议完全语言无关：stdin JSON + WebSocket JSON-RPC 2.0。任何能读 stdin、连 WebSocket 的语言都可以实现 Kite 模块。
+
+## 15. 常见问题
+
+**模块启动后 Launcher 报 "未发送 module.ready"**
+
+原因：模块没发布 module.ready 事件或事件格式错误。检查：
+1. 是否成功连接 Kernel WebSocket
+2. 是否通过 JSON-RPC `event.publish` 发布了 `module.ready` 事件
+3. `data.module_id` 是否与注册时一致
+4. 是否先订阅再注册（顺序错误可能导致 Kernel 无法正确路由事件）
+
+**stdout 报 BrokenPipeError**
+
+原因：Launcher 收到 module.ready 后关闭了 stdio 管道。解决：在入口文件最开头包装 SafeWriter（见 5.2 节）。
+
+**Kernel WebSocket 连接被拒绝（close code 4001）**
+
+原因：token 验证失败。确认使用的是 boot_info 中的 token。模块重启后 token 会变，请确保每次启动都从 stdin 读取最新 token。
+
+**模块被当作崩溃反复重启**
+
+原因：模块主动退出但没发 `module.exiting` 事件。解决：退出前发送 module.exiting（见第 8 节），或声明 `graceful_shutdown` 并正确处理 shutdown 流程。
+
+**模块的 /health 端点被 Watchdog 标记为 unhealthy**
+
+确保 `/health` 返回 JSON 格式，status 字段为 `"healthy"` / `"degraded"` / `"unhealthy"`：
+```json
+{"status": "healthy", "details": {}}
+```
+
+## 16. 附录：完整示例代码
+
+### 16.1 Python 完整模块模板
+
+见第 2.3 节的 `entry.py`，包含完整启动协议。
+
+生产模块参考：`extensions/services/watchdog/entry.py`（异步 + 重连 + 日志 + 崩溃处理）。
+
+### 16.2 Node.js 完整模块模板
+
+参考 `test_modules/hello_node/entry.js`，包含：
+
+- 读取 boot_info（readline）
+- HTTP 服务 + `/health` 端点
+- Kernel WebSocket 连接 + 订阅 + 注册 + module.ready
+- 消息循环（事件通知 + RPC 请求）
+- 优雅退出处理
+
+### 16.3 一次性任务模块示例
+
+参考 `extensions/event_hub_bench/entry.py` — 一个完成基准测试后自动退出的模块：
+
+1. 读取 boot_info（token + kernel_port）
+2. 连接 Kernel WebSocket
+3. 订阅 → 注册 → 发送 module.ready
+4. 执行业务逻辑（跑基准测试）
+5. 发送 `module.exiting`（action: `"none"`）
+6. 退出进程