@agentunion/kite 1.5.0 → 1.6.0

package/docs//351/231/215/347/272/247/347/255/226/347/225/245/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,618 @@
+# 降级策略设计方案
+
+> 状态：P0-P2 已实施，P3 待实施
+> 创建时间：2026-03-16
+> 更新时间：2026-03-16
+> 版本：v2.0
+
+## 1. 问题与目标
+
+### 1.1 当前状况
+
+Kite 现有的故障处理策略是"崩溃 → 重启"：模块崩溃后 Watchdog 自动拉起，Kernel 崩溃触发全量重启。这在多数场景有效，但存在盲区：
+
+| 场景 | 当前行为 | 用户感知 |
+|------|---------|---------|
+| Model Service 调用 LLM API 被限流 | 每次调用等超时 → 返回错误 | 发消息无响应，反复报错 |
+| TTS 服务不可用 | 语音回复失败 | 以为系统死了 |
+| 模块重启中（3-5s） | RPC 返回 `-32001 Module offline` | 看到技术性错误信息 |
+| 非核心模块启动失败 | 不阻塞启动，但无任何提示 | 某功能不可用，不知道为什么 |
+
+核心问题：**模块"活着但能力受损"时，框架没有机制传递这个信息，调用方只能得到一个冷冰冰的错误。**
+
+### 1.2 目标
+
+1. 模块能主动声明"我降级了"，说清楚哪些能力受损、哪些还能用
+2. 其他模块能感知降级状态，自行决定降级行为
+3. 用户看到友好的提示而不是技术性错误
+4. 不引入共享代码，通过事件协议和 RPC 错误格式协调
+
+### 1.3 设计原则
+
+- **模块自治**：谁知道自己坏了，谁负责说出来
+- **协议驱动**：通过事件和错误格式传递信息，不引入共享降级库
+- **零侵入**：不改变现有行为，纯增量；旧模块忽略新字段即可
+- **渐进式**：每个模块按需实现降级逻辑，非强制
+
+---
+
+## 2. 降级等级定义
+
+| 等级 | 含义 | 典型场景 | 模块状态 |
+|------|------|---------|---------|
+| `full` | 模块完全不可用 | 所有外部 provider 都在冷却中 | 进程活着但无法提供任何服务 |
+| `partial` | 部分能力不可用 | LLM chat 限流但 embeddings 可用 | 部分 RPC 方法可调用 |
+| `slow` | 全部能力可用但变慢 | CPU/内存高、网络延迟大 | 所有功能可用，响应变慢 |
+
+---
+
+## 3. 事件协议
+
+### 3.1 `module.degraded`（系统事件，自动广播）
+
+模块检测到自身能力受损时，调用 `kernel.report_degraded` RPC 方法报告降级。Kernel 验证数据后更新 Registry 状态，并通过 `publish_internal()` 广播系统事件给所有已连接模块。
+
+**模块不可直接发布此事件**——`event.publish` RPC 会拒绝系统事件类型，返回错误。
+
+**模块调用方式：**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "method": "kernel.report_degraded",
+  "params": {
+    "level": "partial",
+    "reason": "upstream_rate_limit",
+    "affected": ["chat_completion"],
+    "available": ["embeddings", "tokenize"],
+    "estimated_recovery_ms": 60000,
+    "detail": "OpenAI API 返回 429，Retry-After: 60s"
+  }
+}
+```
+
+Watchdog 代发时需额外指定 `module_id`：
+
+```json
+{
+  "method": "kernel.report_degraded",
+  "params": {
+    "module_id": "model_service",
+    "level": "slow",
+    "reason": "resource_pressure",
+    "detail": "CPU 使用率连续 3 次超过 80%"
+  }
+}
+```
+
+**Kernel 广播的事件格式（模块收到的）：**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event_id": "uuid",
+    "event": "module.degraded",
+    "source": "model_service",
+    "timestamp": "2026-03-16T10:30:45+00:00",
+    "data": {
+      "module_id": "model_service",
+      "level": "partial",
+      "reason": "upstream_rate_limit",
+      "affected": ["chat_completion"],
+      "available": ["embeddings", "tokenize"],
+      "estimated_recovery_ms": 60000,
+      "detail": "OpenAI API 返回 429，Retry-After: 60s"
+    }
+  }
+}
+```
+
+**字段说明：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `module_id` | string | ✓ | 降级模块 ID |
+| `level` | string | ✓ | 降级等级：`full` / `partial` / `slow` |
+| `reason` | string | ✓ | 降级原因（机器可读，见 3.3） |
+| `affected` | string[] | — | 受影响的能力/RPC 方法列表（`partial` 时必填） |
+| `available` | string[] | — | 仍可用的能力/RPC 方法列表 |
+| `estimated_recovery_ms` | number | — | 预计恢复时间（毫秒），无法估计时省略 |
+| `detail` | string | — | 人类可读的详细说明 |
+
+### 3.2 `module.recovered`（系统事件，自动广播）
+
+模块从降级状态恢复时，调用 `kernel.report_recovered` RPC 方法报告恢复。Kernel 验证模块确实处于 degraded 状态后，清除 Registry 降级信息并广播系统事件。
+
+**模块调用方式：**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-2",
+  "method": "kernel.report_recovered",
+  "params": {}
+}
+```
+
+Kernel 自动计算 `previous_level` 和 `duration_ms`，模块无需提供。
+
+**Kernel 广播的事件格式（模块收到的）：**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event",
+  "params": {
+    "event_id": "uuid",
+    "event": "module.recovered",
+    "source": "model_service",
+    "timestamp": "2026-03-16T10:31:50+00:00",
+    "data": {
+      "module_id": "model_service",
+      "previous_level": "partial",
+      "duration_ms": 65000
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `module_id` | string | ✓ | 恢复模块 ID |
+| `previous_level` | string | — | 之前的降级等级 |
+| `duration_ms` | number | — | 降级持续时长（毫秒） |
+
+### 3.3 降级原因枚举
+
+| reason | 含义 | 典型触发 |
+|--------|------|---------|
+| `upstream_rate_limit` | 上游 API 限流 | 收到 429 / Retry-After |
+| `upstream_timeout` | 上游 API 超时 | 连续 N 次超时 |
+| `upstream_auth` | 上游 API 认证失败 | 收到 401/403 |
+| `upstream_unavailable` | 上游服务不可用 | 连接被拒、DNS 失败 |
+| `all_providers_down` | 所有 provider 不可用 | 全部在冷却中 |
+| `resource_pressure` | 资源压力（CPU/内存） | Watchdog 检测到指标异常 |
+| `dependency_offline` | 依赖的内部模块离线 | 所依赖的模块 offline |
+| `internal_error` | 模块内部错误 | 关键组件初始化失败 |
+| `manual` | 手动降级 | 运维手动触发 |
+
+模块可自定义 reason，以上为推荐值。
+
+---
+
+## 4. RPC 错误响应增强
+
+### 4.1 当前格式
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "error": {
+    "code": -32001,
+    "message": "Module offline: model_service"
+  }
+}
+```
+
+### 4.2 增强格式
+
+在 `error` 中增加 `data` 字段，携带模块状态信息：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "error": {
+    "code": -32001,
+    "message": "Module offline: model_service",
+    "data": {
+      "module_status": "offline",
+      "retry_after_ms": 5000
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `module_status` | string | 模块当前状态：`offline` / `connected` / `degraded` |
+| `retry_after_ms` | number | 建议重试间隔（毫秒） |
+
+**新增错误码**：
+
+| 错误码 | 含义 | 场景 |
+|--------|------|------|
+| `-32001` | 模块离线（不变） | 模块未连接或未就绪 |
+| `-32006` | 模块降级 | 模块处于 degraded 状态，调用的方法在 affected 列表中 |
+
+当模块处于 `degraded` 状态时，Kernel RPC Router 的行为：
+
+| 调用的方法 | 在 affected 中？ | 行为 |
+|-----------|:---------------:|------|
+| 是 | ✓ | 返回 `-32006`（模块降级），附带 `retry_after_ms` |
+| 否 | ✗ | 正常转发（available 的能力不受影响） |
+
+---
+
+## 5. Registry 状态扩展
+
+### 5.1 现有状态机
+
+```
+offline → connected → registered → ready
+```
+
+### 5.2 扩展后的状态机
+
+```
+offline → connected → registered → ready ⇄ degraded
+                                     ↑        │
+                                     └────────┘ (recovered)
+```
+
+`degraded` 状态的特殊性：
+- 只能从 `ready` 进入（模块必须先正常运行，才能"降级"）
+- 可以直接回到 `ready`（模块发布 `module.recovered`）
+- 也可以变为 `offline`（WebSocket 断开）
+- `degraded` 期间，RPC Router 根据 `affected` 列表决定是否转发
+
+### 5.3 降级信息存储
+
+`RegistryStore` 中每个模块的记录增加可选的 `degraded_info` 字段：
+
+```python
+self.modules["model_service"] = {
+    "status": "degraded",          # 状态字段
+    "degraded_info": {             # 降级详情（仅 degraded 时存在）
+        "level": "partial",
+        "reason": "upstream_rate_limit",
+        "affected": ["chat_completion"],
+        "available": ["embeddings"],
+        "estimated_recovery_ms": 60000,
+        "degraded_at": 1710579045.123
+    },
+    # ... 其他已有字段
+}
+```
+
+---
+
+## 6. 降级判定标准
+
+### 6.1 核心原则
+
+**谁知道自己坏了，谁负责说出来。** 降级事件由模块自身发布，不由框架统一判定。
+
+### 6.2 判定触发条件
+
+| 故障类型 | 判定者 | 触发条件 | 降级等级 |
+|---------|--------|---------|---------|
+| 外部 API 限流 | 模块自身 | 收到 429 / Retry-After | `partial` |
+| 外部 API 连续超时 | 模块自身 | 60s 内连续 3 次超时 | `partial` 或 `slow` |
+| 外部 API 认证失败 | 模块自身 | 收到 401/403 | `partial` |
+| 所有 provider 不可用 | 模块自身 | 全部在冷却中 | `full` |
+| 子功能初始化失败 | 模块自身 | 启动时某组件失败 | `partial` |
+| CPU/内存告警 | Watchdog | 资源指标超过 warning 阈值 | `slow` |
+
+### 6.3 降级参数推荐值
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| 连续失败阈值 | 3 次 | 连续 3 次同类失败触发降级 |
+| 统计窗口 | 60s | 60s 内的失败才算"连续" |
+| 错误率阈值 | 50% | 60s 内错误率超过 50% 也触发 |
+
+### 6.4 参考实现（模块内部，非共享代码）
+
+每个模块自行实现以下逻辑，参数保持一致即可：
+
+```python
+class DegradationDetector:
+    """模块自行实现，不是共享库。
+    参考路径：各模块 entry.py 或独立的 degradation.py"""
+
+    def __init__(self, capability: str, threshold: int = 3, window: float = 60.0):
+        self.capability = capability
+        self.threshold = threshold
+        self.window = window
+        self.failures = []        # [(timestamp, reason)]
+        self.is_degraded = False
+
+    def record_failure(self, reason: str) -> bool:
+        """记录失败。返回 True 表示刚触发降级（需要发布事件）。"""
+        now = time.time()
+        cutoff = now - self.window
+        self.failures = [(t, r) for t, r in self.failures if t > cutoff]
+        self.failures.append((now, reason))
+
+        if len(self.failures) >= self.threshold and not self.is_degraded:
+            self.is_degraded = True
+            return True  # → 调用方发布 module.degraded
+        return False
+
+    def record_success(self) -> bool:
+        """记录成功。返回 True 表示刚恢复（需要发布事件）。"""
+        if self.is_degraded:
+            self.is_degraded = False
+            self.failures.clear()
+            return True  # → 调用方发布 module.recovered
+        return False
+```
+
+---
+
+## 7. 恢复判定标准
+
+### 7.1 核心原则
+
+降级不是终态。模块必须定期探测，确认能力恢复后发布 `module.recovered`。
+
+### 7.2 探测机制
+
+```
+降级状态
+  │
+  ├── 有 Retry-After → 等待 Retry-After 到期后探测
+  │
+  └── 无 Retry-After → 每 30s 探测一次
+        │
+        ├── 探测成功 → 发布 module.recovered
+        │
+        └── 探测失败 → 继续降级，30s 后再探测
+```
+
+### 7.3 恢复参数推荐值
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| 默认探测间隔 | 30s | 无 Retry-After 时使用 |
+| 探测成功阈值 | 1 次 | 首次成功即恢复 |
+| Retry-After 优先 | 是 | 上游返回 Retry-After 时优先使用 |
+| 最大降级时长 | 无限制 | 直到探测成功为止 |
+
+### 7.4 探测方式
+
+每个模块根据自身情况选择探测方式：
+
+| 模块 | 探测方式 | 判断成功 |
+|------|---------|---------|
+| Model Service | 发送轻量级 API 请求（如 models.list） | 返回 200 |
+| Channel（TTS） | 合成一段短文本 | 返回音频数据 |
+| 依赖内部模块 | 调用目标模块 health RPC | 返回正常 |
+
+---
+
+## 8. 各角色职责
+
+### 8.1 职责分配表
+
+| 角色 | 职责 | 不做什么 |
+|------|------|---------|
+| **Kernel** | 广播 `module.degraded`/`module.recovered` 系统事件；维护 Registry 中的 degraded 状态；RPC Router 根据 affected 列表决定转发还是拒绝 | 不判断降级，不决定恢复 |
+| **发布模块**（如 Model Service） | 检测自身能力受损 → 发布 `module.degraded`；定期探测 → 恢复后发布 `module.recovered` | 不关心谁收到了事件 |
+| **消费模块**（如 Agent、Channel） | 收到 `module.degraded` → 自行决定降级行为（切换策略、返回预设回复等） | 不判断别的模块是否真的降级了 |
+| **Watchdog** | 资源类降级的代发者（CPU/内存告警）；记录所有模块的降级状态；对 degraded 模块不触发重启 | 不判断业务降级，不替模块做决策 |
+| **kite_console** | 展示降级状态；提供手动降级/恢复操作（未来） | 不做自动降级判断 |
+
+### 8.2 Watchdog 的特殊定位
+
+Watchdog 在降级体系中有两个辅助角色：
+
+**角色 1：资源降级代发**
+
+模块自身可能感知不到"我变慢了"（CPU 高导致响应变慢，但模块代码没有直接检测到超时）。Watchdog 通过资源指标检测到异常后，代模块发布降级事件：
+
+```json
+{
+  "event": "module.degraded",
+  "source": "watchdog",
+  "data": {
+    "module_id": "model_service",
+    "level": "slow",
+    "reason": "resource_pressure",
+    "detail": "CPU 使用率连续 3 次超过 80%"
+  }
+}
+```
+
+注意 `source` 是 `watchdog` 而不是 `model_service`——表明这是代发的。
+
+对应的恢复事件同理：资源指标回到 normal 后，Watchdog 代发 `module.recovered`。
+
+**角色 2：降级保护**
+
+Watchdog 收到 `module.degraded` 后，标记该模块状态。降级模块：
+- 不触发重启（降级 ≠ 崩溃）
+- 提高监控频率（类似 warning 级别）
+- 超长降级告警（降级超过 5 分钟 → 发布 `watchdog.module.degraded_timeout`）
+
+---
+
+## 9. 改动清单
+
+### 9.1 改动总览
+
+| 优先级 | 改动项 | 涉及模块 | 性质 | 状态 |
+|:------:|--------|---------|------|:----:|
+| P0 | Kernel RPC 错误响应增强（`data` 字段） | Kernel | 框架核心 | ✅ 已实现 |
+| P0 | 新增 `module.degraded`/`module.recovered` 系统事件 | Kernel | 框架核心 | ✅ 已实现 |
+| P0 | Registry 状态扩展（degraded 状态 + degraded_info） | Kernel | 框架核心 | ✅ 已实现 |
+| P0 | 新增 `kernel.report_degraded`/`kernel.report_recovered` RPC | Kernel | 框架核心 | ✅ 已实现 |
+| P0 | 系统事件安全加固（禁止模块直接发布系统事件） | Kernel | 框架核心 | ✅ 已实现 |
+| P1 | Watchdog 降级感知 + 资源代发 + 超长降级检测 | Watchdog | 核心模块 | ✅ 已实现 |
+| P1 | Watchdog 健康事件持久化 + `health_events` RPC | Watchdog | 核心模块 | ✅ 已实现 |
+| P1 | 审计模块补充降级/恢复/就绪等事件 | Audit | 核心模块 | ✅ 已实现 |
+| P2 | kite_console 健康检查面板（三区结构） | kite_console | 前端 | ✅ 已实现 |
+| P2 | Model Service 外部调用保护 | Model Service | 业务模块 | 待实施 |
+| P2 | Channel 消息降级 | Channel | 业务模块 | 待实施 |
+| P3 | 模块开发指南更新 | 文档 | 文档 | 待实施 |
+
+### 9.2 Phase 1：框架基础设施（P0，Kernel 改动）✅ 已完成
+
+| 文件 | 改动点 | 说明 |
+|------|--------|------|
+| `kernel/event_hub.py` | `SYSTEM_EVENTS` 增加 `"module.degraded"`, `"module.recovered"` | 自动广播，无需订阅 |
+| `kernel/event_hub.py` | `publish_event()` 增加系统事件拦截 | 禁止模块直接发布系统事件 |
+| `kernel/registry_store.py` | 新增 `set_degraded()` / `clear_degraded()` / `get_degraded_info()` | degraded 状态管理 |
+| `kernel/registry_store.py` | `is_ready()` 兼容 degraded 状态 | degraded 模块仍可接收 RPC（非 affected 方法） |
+| `kernel/rpc_router.py` | 新增 `-32006 MODULE_DEGRADED` 错误码 | `-32005` 已被 `DUPLICATE_EVENT` 占用 |
+| `kernel/rpc_router.py` | 新增 `kernel.report_degraded` / `kernel.report_recovered` RPC | Kernel 中转模式：验证 → 更新 Registry → 广播 |
+| `kernel/rpc_router.py` | `_forward()` 增加降级拦截 | affected 方法返回 `-32006`，其余正常转发 |
+| `kernel/rpc_router.py` | 所有错误响应增加 `data` 字段 | 附带 `module_status`、`retry_after_ms` 等 |
+| `kernel/server.py` | 事件忽略列表增加 `module.degraded` / `module.recovered` | 避免 Kernel 收到自己广播的事件时打 warning |
+
+### 9.3 Phase 2：核心模块适配（P1）✅ 已完成
+
+| 文件 | 改动点 | 说明 |
+|------|--------|------|
+| `watchdog/monitor.py` | 新增 `_degraded_modules` 状态表 | 跟踪降级模块，降级模块不触发重启 |
+| `watchdog/monitor.py` | 处理 `module.degraded` / `module.recovered` 事件 | 维护降级状态 + 持久化健康事件 |
+| `watchdog/monitor.py` | 资源告警时调用 `kernel.report_degraded` 代发 | CPU/内存进入 warning → `level: slow` |
+| `watchdog/monitor.py` | 资源恢复时调用 `kernel.report_recovered` 代发 | 仅恢复 Watchdog 代发的降级 |
+| `watchdog/monitor.py` | 超长降级检测（5 分钟） | 发布 `watchdog.module.degraded_timeout` 告警 |
+| `watchdog/monitor.py` | 健康事件持久化到 `{KITE_INSTANCE_DIR}/health/events.jsonl` | 按天归档到 `health/{YYYY-MM}/{YYYY-MM-DD}.jsonl` |
+| `watchdog/monitor.py` | 新增 `get_health_events()` 查询方法 | 支持 limit + since 参数 |
+| `watchdog/entry.py` | 新增 `health_events` RPC handler | 对外暴露健康事件查询 |
+| `watchdog/entry.py` | 事件订阅增加 `module.degraded` / `module.recovered` | 接收降级/恢复广播 |
+| `watchdog/entry.py` | 设置 `rpc_call_kernel` 回调 | 用于代发降级/恢复 |
+| `audit/collector.py` | `AUDIT_EVENTS` 增加 6 个事件类型 | `module.ready/degraded/recovered` + `watchdog.module.*` |
+| `audit/schemas/audit_event.py` | 结果判定增加 `degraded/warning/timeout` 关键词 | 标记为 failure |
+
+### 9.4 Phase 3：用户体验（P2）✅ 部分完成
+
+| 文件 | 改动点 | 说明 |
+|------|--------|------|
+| `kite_console/static/index.html` | 新增 `page-health` 页面（三区结构） | 系统概览条 + 模块卡片 + 事件时间线 |
+| `kite_console/static/index.html` | 审计筛选器补充新事件类型 | 7 个新选项 |
+| `kite_console/static/js/evol-app.js` | 新增 `initHealthPage()` 及相关方法 | 数据加载、卡片渲染、时间线、自定义指标渲染 |
+| Channel 模块 | 收到 `-32001` / `-32006` 时返回用户友好消息 | **待实施** |
+
+### 9.5 Phase 4：规范化（P3）待实施
+
+| 文件 | 改动点 | 说明 |
+|------|--------|------|
+| `docs/模块开发指南.md` | 新增「降级规范」章节 | 事件格式、推荐参数、参考实现 |
+
+---
+
+## 10. 完整交互时序
+
+### 10.1 Model Service API 限流 → 降级 → 恢复
+
+```mermaid
+sequenceDiagram
+    participant MS as Model Service
+    participant K as Kernel
+    participant WD as Watchdog
+    participant AG as Agent 模块
+    participant CH as Channel 模块
+    participant KC as kite_console
+
+    Note over MS: 调用 OpenAI API → 429 (第1次)
+    Note over MS: 调用 OpenAI API → 429 (第2次)
+    Note over MS: 调用 OpenAI API → 429 (第3次，触发降级)
+
+    MS->>K: kernel.report_degraded({level:"partial", affected:["chat_completion"], reason:"upstream_rate_limit"})
+    K->>K: registry.set_degraded("model_service", info)
+    K->>K: publish_internal("module.degraded")
+
+    par 系统事件广播
+        K->>WD: module.degraded (auto-broadcast)
+        K->>AG: module.degraded (auto-broadcast)
+        K->>CH: module.degraded (auto-broadcast)
+        K->>KC: module.degraded (auto-broadcast)
+    end
+
+    WD->>WD: 标记降级，提高监控频率<br/>不触发重启
+    AG->>AG: 标记 chat_completion 不可用
+    KC->>KC: 前端显示降级图标
+
+    Note over MS,CH: ── 降级期间 ──
+
+    CH->>K: RPC: model_service.chat_completion(...)
+    K->>K: 检查 affected → chat_completion 在列表中
+    K->>CH: error {code:-32006, data:{module_status:"degraded", retry_after_ms:30000}}
+    CH->>CH: 返回用户："AI 服务繁忙，请稍后再试"
+
+    Note over MS: 30s 后探测：调用 OpenAI models.list → 200 成功！
+
+    MS->>K: kernel.report_recovered({})
+    K->>K: registry.clear_degraded("model_service")
+    K->>K: publish_internal("module.recovered")
+
+    par 系统事件广播
+        K->>WD: module.recovered (auto-broadcast)
+        K->>AG: module.recovered (auto-broadcast)
+        K->>CH: module.recovered (auto-broadcast)
+        K->>KC: module.recovered (auto-broadcast)
+    end
+
+    WD->>WD: 清除降级标记
+    AG->>AG: 恢复正常调用
+    KC->>KC: 移除降级图标
+```
+
+### 10.2 资源压力 → Watchdog 代发降级
+
+```mermaid
+sequenceDiagram
+    participant WD as Watchdog
+    participant K as Kernel
+    participant MS as Model Service
+
+    WD->>MS: health check → CPU 82% (连续第2次超80%)
+    WD->>MS: health check → CPU 85% (连续第3次)
+
+    WD->>K: kernel.report_degraded({module_id:"model_service",<br/>level:"slow", reason:"resource_pressure"})
+    K->>K: registry.set_degraded("model_service", info)
+    K->>K: publish_internal("module.degraded")
+    K-->>K: 广播给所有模块
+
+    Note over WD,MS: Model Service 负载下降
+
+    WD->>MS: health check → CPU 45% (恢复正常)
+    WD->>K: kernel.report_recovered({module_id:"model_service"})
+    K->>K: registry.clear_degraded("model_service")
+    K->>K: publish_internal("module.recovered")
+    K-->>K: 广播给所有模块
+```
+
+---
+
+## 11. 向后兼容性
+
+| 变更点 | 旧模块行为 | 兼容性 |
+|--------|-----------|--------|
+| RPC 错误响应增加 `data` 字段 | 旧模块不解析 `data`，忽略 | ✅ 完全兼容 |
+| 新增 `-32006` 错误码 | 旧模块当作未知错误处理 | ✅ 兼容（等同于现有错误处理） |
+| `module.degraded` 系统事件 | 旧模块收到未知事件，忽略 | ✅ 完全兼容 |
+| Registry 增加 `degraded` 状态 | 旧模块不感知此状态 | ✅ 兼容（Kernel 行为不变） |
+| RPC Router 拒绝 affected 方法 | 旧模块收到 `-32006` 而不是正常响应 | ⚠️ 行为变化，但旧模块本来也会收到错误（只是错误码不同） |
+| `event.publish` 拒绝系统事件 | 旧模块如果直接发布系统事件会收到错误 | ⚠️ 安全加固，正常模块不应直接发布系统事件 |
+
+---
+
+## 12. 与现有机制的关系
+
+| 现有机制 | 降级策略的关系 |
+|---------|--------------|
+| `module.offline` 事件 | 互补。offline = 进程级故障；degraded = 能力级故障 |
+| Watchdog 自动重启 | 互斥。降级模块不应被重启（进程还活着） |
+| `watchdog.module.resource_warning` | 包含。资源告警可触发 `module.degraded(level: slow)` |
+| `watchdog.module.recovered`（已有） | 独立。已有的是资源恢复事件；新增的 `module.recovered` 是业务恢复事件 |
+| 三档重连策略（never/standard/cooldown） | 独立。重连策略处理连接层故障；降级策略处理业务层故障 |
+| 队列压力强断（4011） | 独立。队列压力是系统级保护；降级是模块级状态 |
+
+---
+
+## 13. 未来扩展
+
+1. **手动降级开关** — kite_console 提供 UI 让管理员手动将模块设为降级状态（reason: `manual`）
+2. **降级策略配置** — 在 module.md 中声明降级策略（如 fallback provider 列表）
+3. **级联降级** — 模块 A 依赖模块 B，B 降级时 A 自动降级相关能力
+4. **降级审计** — Audit 模块记录所有降级/恢复事件
+5. **降级统计** — 统计各模块的降级频率、平均持续时长、恢复率