# 即时消息桥接服务

<cite>
**本文档引用的文件**
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/lib/im/channel-router.ts](file://src/lib/im/channel-router.ts)
- [src/lib/im/commands.ts](file://src/lib/im/commands.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/lib/im/delivery.ts](file://src/lib/im/delivery.ts)
- [src/lib/im/policy.ts](file://src/lib/im/policy.ts)
- [src/lib/im/permission-broker.ts](file://src/lib/im/permission-broker.ts)
- [src/lib/im/types.ts](file://src/lib/im/types.ts)
- [src/lib/im/adapters/base.ts](file://src/lib/im/adapters/base.ts)
- [src/lib/im/adapters/registry.ts](file://src/lib/im/adapters/registry.ts)
- [src/app/api/im-channels/route.ts](file://src/app/api/im-channels/route.ts)
- [src/app/api/im-events/route.ts](file://src/app/api/im-events/route.ts)
- [src/hooks/use-im-channels.ts](file://src/hooks/use-im-channels.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本项目是一个多平台即时消息桥接服务，支持飞书、Telegram、Discord 等平台的消息桥接与转发。系统采用五层架构设计，通过适配器层对接不同平台，桥接管理层统一调度，路由层负责会话绑定，对话引擎调用 AI 能力，投递层负责消息格式化与平台投递。系统提供命令系统、权限控制、频道管理、实时事件同步等功能，并具备完善的错误处理、重连机制与性能优化策略。

## 项目结构
项目采用前后端分离的 Next.js 应用结构，IM 桥接相关逻辑集中在 `src/lib/im` 目录下，API 层位于 `src/app/api`，前端 Hook 位于 `src/hooks`。

```mermaid
graph TB
subgraph "前端"
UI["React 组件<br/>views/im-view.tsx"]
Hooks["React Hooks<br/>use-im-channels.ts"]
end
subgraph "后端 API"
API_Channels["/api/im-channels<br/>route.ts"]
API_Events["/api/im-events<br/>route.ts"]
end
subgraph "IM 核心"
BM["BridgeManager<br/>bridge-manager.ts"]
Router["ChannelRouter<br/>channel-router.ts"]
Engine["ConversationEngine<br/>conversation-engine.ts"]
Delivery["DeliveryLayer<br/>delivery.ts"]
Policy["Policy<br/>policy.ts"]
Perm["PermissionBroker<br/>permission-broker.ts"]
Types["Types<br/>types.ts"]
end
subgraph "适配器层"
Base["ChannelAdapter<br/>adapters/base.ts"]
Registry["Registry<br/>adapters/registry.ts"]
Feishu["Feishu Adapter"]
Telegram["Telegram Adapter"]
Discord["Discord Adapter"]
end
UI --> Hooks
Hooks --> API_Channels
API_Channels --> BM
API_Events --> |Server-Sent Events| UI
BM --> Router
BM --> Engine
BM --> Delivery
BM --> Policy
BM --> Perm
Engine --> Delivery
Delivery --> Base
Base --> Registry
Registry --> Feishu
Registry --> Telegram
Registry --> Discord
```

**图表来源**
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/lib/im/bridge-manager.ts:1-635](file://src/lib/im/bridge-manager.ts#L1-L635)
- [src/lib/im/adapters/base.ts:1-102](file://src/lib/im/adapters/base.ts#L1-L102)
- [src/lib/im/adapters/registry.ts:1-31](file://src/lib/im/adapters/registry.ts#L1-L31)

**章节来源**
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/hooks/use-im-channels.ts:1-77](file://src/hooks/use-im-channels.ts#L1-L77)

## 核心组件
- 桥接管理层（BridgeManager）：负责适配器生命周期、轮询循环、并发控制、重连策略、消息处理流水线。
- 频道路由器（ChannelRouter）：将平台聊天与会话进行绑定，支持自动创建与显式绑定。
- 对话引擎（ConversationEngine）：调用 AI SDK，消费流式响应，生成文本块与附件。
- 投递层（DeliveryLayer）：负责速率限制、消息分片、去重、重试、审计日志与平台特定渲染。
- 权限代理（PermissionBroker）：集中处理工具调用权限请求，支持超时与用户响应。
- 策略模块（Policy）：基于数据库配置的 DM/群组策略与触发模式检查。
- 适配器抽象（ChannelAdapter）：定义平台适配器接口，注册中心负责实例化。
- 类型定义（types.ts）：统一定义消息、权限、命令、状态等类型。

**章节来源**
- [src/lib/im/bridge-manager.ts:1-635](file://src/lib/im/bridge-manager.ts#L1-L635)
- [src/lib/im/channel-router.ts:1-232](file://src/lib/im/channel-router.ts#L1-L232)
- [src/lib/im/conversation-engine.ts:1-459](file://src/lib/im/conversation-engine.ts#L1-L459)
- [src/lib/im/delivery.ts:1-336](file://src/lib/im/delivery.ts#L1-L336)
- [src/lib/im/permission-broker.ts:1-117](file://src/lib/im/permission-broker.ts#L1-L117)
- [src/lib/im/policy.ts:1-89](file://src/lib/im/policy.ts#L1-L89)
- [src/lib/im/adapters/base.ts:1-102](file://src/lib/im/adapters/base.ts#L1-L102)
- [src/lib/im/adapters/registry.ts:1-31](file://src/lib/im/adapters/registry.ts#L1-L31)
- [src/lib/im/types.ts:1-140](file://src/lib/im/types.ts#L1-L140)

## 架构总览
系统采用五层架构，从平台适配器到桥接管理层，再到路由、对话引擎与投递层，形成清晰的职责分离与扩展点。

```mermaid
graph TB
subgraph "平台适配器层(L1)"
A1["ChannelAdapter 接口"]
A2["注册中心"]
A3["飞书/Telegram/Discord 适配器"]
end
subgraph "桥接管理层(L2)"
B1["BridgeManager"]
B2["会话锁管理"]
B3["重连与电路保护"]
end
subgraph "路由层(L3)"
C1["ChannelRouter"]
end
subgraph "对话引擎(L4)"
D1["ConversationEngine"]
end
subgraph "投递层(L5)"
E1["DeliveryLayer"]
end
A1 --> A2 --> A3
A3 --> B1
B1 --> C1
B1 --> D1
D1 --> E1
B1 --> E1
```

**图表来源**
- [src/lib/im/bridge-manager.ts:1-635](file://src/lib/im/bridge-manager.ts#L1-L635)
- [src/lib/im/adapters/base.ts:1-102](file://src/lib/im/adapters/base.ts#L1-L102)
- [src/lib/im/adapters/registry.ts:1-31](file://src/lib/im/adapters/registry.ts#L1-L31)
- [src/lib/im/channel-router.ts:1-232](file://src/lib/im/channel-router.ts#L1-L232)
- [src/lib/im/conversation-engine.ts:1-459](file://src/lib/im/conversation-engine.ts#L1-L459)
- [src/lib/im/delivery.ts:1-336](file://src/lib/im/delivery.ts#L1-L336)

## 详细组件分析

### 桥接管理层（BridgeManager）
- 适配器生命周期：启动/停止适配器、权限回调注册、状态持久化。
- 轮询循环：每通道独立的轮询控制器，阻塞等待消息，异常时触发重连。
- 并发控制：会话级锁确保同一聊天的 SDK 调用串行；SDK 调用背压限制最大并发。
- 消息处理流水线：策略检查 → 命令解析 → 会话解析 → 会话锁 → 对话引擎 → 投递层 → 事件同步。
- 重连机制：指数退避 + 随机抖动，连续失败触发电路保护，5 分钟内不再尝试。
- 去重与清理：按消息 ID 去重，定期清理；速率桶清理与去重表 TTL 清理。

```mermaid
sequenceDiagram
participant PM as "平台适配器"
participant BM as "BridgeManager"
participant Router as "ChannelRouter"
participant Engine as "ConversationEngine"
participant Delivery as "DeliveryLayer"
PM->>BM : "consumeOne() 返回 IncomingMessage"
BM->>BM : "策略检查"
alt 是命令
BM->>BM : "parseImCommand()"
BM->>Delivery : "deliver() 发送命令响应"
else 普通消息
BM->>Router : "resolveSession()"
Router-->>BM : "sessionId, workspace"
BM->>BM : "acquire(sessionKey)"
BM->>Engine : "processMessage() 回调 onTyping/onDraft/onFinal"
Engine-->>BM : "ConversationResult"
BM->>Delivery : "deliver()/deliverImage()/deliverFile()"
BM->>BM : "release(sessionKey)"
end
```

**图表来源**
- [src/lib/im/bridge-manager.ts:337-529](file://src/lib/im/bridge-manager.ts#L337-L529)
- [src/lib/im/channel-router.ts:31-74](file://src/lib/im/channel-router.ts#L31-L74)
- [src/lib/im/conversation-engine.ts:40-231](file://src/lib/im/conversation-engine.ts#L40-L231)
- [src/lib/im/delivery.ts:78-169](file://src/lib/im/delivery.ts#L78-L169)

**章节来源**
- [src/lib/im/bridge-manager.ts:78-328](file://src/lib/im/bridge-manager.ts#L78-L328)
- [src/lib/im/bridge-manager.ts:337-529](file://src/lib/im/bridge-manager.ts#L337-L529)
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)

### 频道路由器（ChannelRouter）
- 会话解析优先级：已绑定会话 → 兼容旧版绑定（仅工作区） → 自动创建新会话并绑定。
- 显式绑定/解绑：支持 /bind 与 /unbind 命令。
- 默认工作区与模型：优先使用桥接默认工作区，否则使用最近打开的工作区；默认模型来自设置。
- 最近会话查询：用于 /sessions 命令展示。

```mermaid
flowchart TD
Start(["收到消息"]) --> CheckBinding["查询 channel_bindings"]
CheckBinding --> HasSession{"存在 session_id ?"}
HasSession --> |是| VerifySession["校验 sessions 是否存在"]
VerifySession --> |存在| ReturnExisting["返回现有会话"]
VerifySession --> |不存在| CreateNew["创建新会话并更新绑定"]
HasSession --> |否| HasLegacy{"存在 workspace ?"}
HasLegacy --> |是| CreateFromLegacy["创建新会话并升级绑定"]
HasLegacy --> |否| AutoCreate["自动创建新会话并插入绑定"]
ReturnExisting --> End(["完成"])
CreateNew --> End
CreateFromLegacy --> End
AutoCreate --> End
```

**图表来源**
- [src/lib/im/channel-router.ts:31-74](file://src/lib/im/channel-router.ts#L31-L74)

**章节来源**
- [src/lib/im/channel-router.ts:19-232](file://src/lib/im/channel-router.ts#L19-L232)

### 对话引擎（ConversationEngine）
- 用户消息持久化：保存带附件块的用户消息，便于桌面视图渲染。
- SDK 查询创建：根据会话是否存在决定续聊或全新会话；支持权限模式（确认/全量）。
- 流式消费：首次事件触发“正在输入”，周期性发送草稿预览，最终文本完成后发送完整内容。
- 附件检测：解析 MEDIA: 协议行与工具使用启发式提取文件路径，去重后交给投递层。
- 内存归档与刷新：定时归档旧记忆，按需提醒 Agent 写入记忆。

```mermaid
sequenceDiagram
participant BM as "BridgeManager"
participant CE as "ConversationEngine"
participant SDK as "Forge SDK"
participant DL as "DeliveryLayer"
BM->>CE : "processMessage(msg, sessionId, workspace, callbacks)"
CE->>CE : "保存用户消息"
CE->>SDK : "createForgeQuery(prompt, attachments, ...)"
SDK-->>CE : "流式事件"
CE->>DL : "onTyping()"
CE->>DL : "onDraft(partialText)"
CE->>DL : "onFinal(text)"
CE->>DL : "onAttachments(attachments)"
CE-->>BM : "ConversationResult"
```

**图表来源**
- [src/lib/im/conversation-engine.ts:40-317](file://src/lib/im/conversation-engine.ts#L40-L317)
- [src/lib/im/delivery.ts:78-169](file://src/lib/im/delivery.ts#L78-L169)

**章节来源**
- [src/lib/im/conversation-engine.ts:30-231](file://src/lib/im/conversation-engine.ts#L30-L231)
- [src/lib/im/conversation-engine.ts:237-354](file://src/lib/im/conversation-engine.ts#L237-L354)

### 投递层（DeliveryLayer）
- 速率限制：令牌桶算法，每通道每分钟最多 20 条消息，突发 5。
- 消息分片：按平台最大长度切分，优先在换行处分割。
- 去重：对相同文本计算哈希，5 分钟内去重；定期清理过期记录。
- 重试：指数退避最多 3 次；编辑失败回退为发送新消息。
- 审计日志：记录发送、编辑、删除、图片/文件发送等操作。
- 平台渲染：将 Markdown 渲染为各平台可识别的格式。

```mermaid
flowchart TD
In(["deliver(adapter, chatId, text, options)"]) --> Typing{"是否为输入指示？"}
Typing --> |是| SendTyping["adapter.sendTypingIndicator()"] --> Done
Typing --> |否| Delete{"是否删除消息？"}
Delete --> |是| DoDelete["adapter.send(deleteMessageId)"] --> Audit["记录审计"] --> Done
Delete --> |否| Rate["令牌桶获取"] --> Render["平台渲染"]
Render --> Edit{"是否编辑已有消息？"}
Edit --> |是| DoEdit["adapter.send(editMessageId)"] --> Audit2["记录审计"] --> Done
Edit --> |否| Chunk["按平台长度分片"]
Chunk --> Dedup{"是否跳过去重？"}
Dedup --> |否| CheckDup["计算哈希并查重"]
CheckDup --> Dup{"重复？"}
Dup --> |是| NextChunk["下一个分片"] --> Chunk
Dup --> |否| Send["retryWithBackoff(adapter.send)"]
Dedup --> |是| Send
Send --> Track["记录出站引用"] --> Audit3["记录审计"] --> NextChunk
NextChunk --> |全部完成| Done(["返回最后消息ID"])
```

**图表来源**
- [src/lib/im/delivery.ts:78-327](file://src/lib/im/delivery.ts#L78-L327)

**章节来源**
- [src/lib/im/delivery.ts:68-336](file://src/lib/im/delivery.ts#L68-L336)

### 权限代理（PermissionBroker）
- 权限请求：向适配器发送权限提示，等待用户响应或超时自动拒绝。
- 超时控制：默认 120 秒自动拒绝。
- 响应解析：支持精确匹配与前缀匹配（兼容飞书短 ID）。
- 清理策略：单通道断开时清理该通道的待决请求；完全关闭时清理全部。

```mermaid
classDiagram
class PermissionBroker {
-pending : Map~string, PendingRequest~
+requestPermission(req, adapter, channelId) Promise~Decision~
+resolvePermission(requestId, decision) void
+cleanupChannel(channelId) void
+cleanup() void
+pendingCount : number
}
class PendingRequest {
+resolve(decision)
+timeout
+channelId
}
PermissionBroker --> PendingRequest : "管理"
```

**图表来源**
- [src/lib/im/permission-broker.ts:25-116](file://src/lib/im/permission-broker.ts#L25-L116)

**章节来源**
- [src/lib/im/permission-broker.ts:1-117](file://src/lib/im/permission-broker.ts#L1-L117)

### 策略模块（Policy）
- DM 策略：禁用、开放、白名单、配对（当前作为白名单处理）。
- 群组策略：禁用、开放、白名单。
- 触发模式：提及才响应（mention）。
- 白名单解析：JSON 数组解析，支持空值安全。

**章节来源**
- [src/lib/im/policy.ts:20-89](file://src/lib/im/policy.ts#L20-L89)

### 适配器接口规范
- 抽象基类定义：生命周期（start/stop/isRunning）、消息消费（consumeOne）、消息发送（send/sendImage/sendFile/sendTypingIndicator）、权限提示（sendPermissionPrompt/onPermissionResponse）、配置验证（validateConfig）。
- 注册中心：按通道类型映射构造函数，统一创建实例。

```mermaid
classDiagram
class ChannelAdapter {
<<abstract>>
+channelType : ChannelType
+start(config) Promise~void~
+stop() Promise~void~
+isRunning() boolean
+consumeOne(signal) Promise~IncomingMessage|null~
+send(msg) Promise~string|undefined~
+sendImage(chatId, buffer, caption) Promise~void~
+sendFile(chatId, buffer, filename, caption) Promise~void~
+sendTypingIndicator(chatId) Promise~void~
+sendPermissionPrompt(req) Promise~void~
+onPermissionResponse(callback) void
+validateConfig(config) {valid, error?}
}
class Registry {
+registerAdapter(type, ctor) void
+createAdapter(type) ChannelAdapter
+getRegisteredTypes() ChannelType[]
}
ChannelAdapter <|-- FeishuAdapter
ChannelAdapter <|-- TelegramAdapter
ChannelAdapter <|-- DiscordAdapter
Registry --> ChannelAdapter : "创建实例"
```

**图表来源**
- [src/lib/im/adapters/base.ts:16-101](file://src/lib/im/adapters/base.ts#L16-L101)
- [src/lib/im/adapters/registry.ts:15-31](file://src/lib/im/adapters/registry.ts#L15-L31)

**章节来源**
- [src/lib/im/adapters/base.ts:1-102](file://src/lib/im/adapters/base.ts#L1-L102)
- [src/lib/im/adapters/registry.ts:1-31](file://src/lib/im/adapters/registry.ts#L1-L31)

### 命令系统设计
- 支持命令：新建会话、绑定/解绑、列出会话、清空、压缩上下文、项目管理、模型切换、权限模式、状态查看、停止任务、帮助。
- 未知命令提示：提供相似命令建议与帮助引导。
- 多语言支持：中英文双语文案，动态读取语言设置。
- 交互事件：命令执行与会话变更通过事件同步到桌面端。

```mermaid
flowchart TD
CmdIn(["/command args"]) --> Parse["parseImCommand()"]
Parse --> Known{"是否已知命令？"}
Known --> |否| Suggest["checkUnknownCommand() 提示建议"] --> Reply["deliver() 返回建议"]
Known --> |是| Exec["executeImCommand()"]
Exec --> Handler{"具体处理器"}
Handler --> Reply2["生成响应文本"]
Reply2 --> Reply
```

**图表来源**
- [src/lib/im/commands.ts:277-373](file://src/lib/im/commands.ts#L277-L373)

**章节来源**
- [src/lib/im/commands.ts:1-964](file://src/lib/im/commands.ts#L1-L964)

### 实时事件与桌面同步
- SSE 端点：/api/im-events 通过 Server-Sent Events 向桌面 UI 推送事件。
- 事件类型：im:message、im:command、im:session-changed 等。
- 心跳机制：30 秒 keepalive，避免代理/浏览器超时。
- 订阅管理：连接建立时订阅，断开时清理。

**章节来源**
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)

### 频道管理与前端集成
- API：/api/im-channels 获取所有频道及其状态。
- 前端 Hook：useIm-channels 封装频道列表、更新、刷新逻辑。
- 数据映射：将数据库 JSON 字段映射为对象数组，支持白名单解析。

**章节来源**
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/hooks/use-im-channels.ts:1-77](file://src/hooks/use-im-channels.ts#L1-L77)

## 依赖关系分析

```mermaid
graph LR
Types["types.ts"] --> Bridge["bridge-manager.ts"]
Types --> Router["channel-router.ts"]
Types --> Engine["conversation-engine.ts"]
Types --> Delivery["delivery.ts"]
Types --> Policy["policy.ts"]
Types --> Perm["permission-broker.ts"]
Base["adapters/base.ts"] --> Registry["adapters/registry.ts"]
Registry --> Feishu["Feishu Adapter"]
Registry --> Telegram["Telegram Adapter"]
Registry --> Discord["Discord Adapter"]
Bridge --> Router
Bridge --> Engine
Bridge --> Delivery
Bridge --> Policy
Bridge --> Perm
Engine --> Delivery
Delivery --> Base
```

**图表来源**
- [src/lib/im/types.ts:1-140](file://src/lib/im/types.ts#L1-L140)
- [src/lib/im/bridge-manager.ts:1-635](file://src/lib/im/bridge-manager.ts#L1-L635)
- [src/lib/im/adapters/base.ts:1-102](file://src/lib/im/adapters/base.ts#L1-L102)
- [src/lib/im/adapters/registry.ts:1-31](file://src/lib/im/adapters/registry.ts#L1-L31)

**章节来源**
- [src/lib/im/bridge-manager.ts:17-35](file://src/lib/im/bridge-manager.ts#L17-L35)
- [src/lib/im/adapters/registry.ts:8-25](file://src/lib/im/adapters/registry.ts#L8-L25)

## 性能考虑
- 并发控制
  - 会话级锁：确保同一聊天的 SDK 调用串行，避免平台限流与状态竞争。
  - SDK 调用背压：全局最多 3 个并发 SDK 调用，等待队列唤醒机制。
- 速率限制
  - 令牌桶：每通道每分钟 20 条消息，突发 5，降低平台封禁风险。
- 消息分片与去重
  - 按平台最大长度切分，减少单次发送失败影响。
  - 基于哈希的去重，5 分钟 TTL，防止重复消息刷屏。
- 缓存与清理
  - 速率桶与去重表定期清理，避免内存膨胀。
- 重连与电路保护
  - 指数退避 + 抖动，连续失败 5 次电路保护 5 分钟，避免雪崩。
- I/O 优化
  - 附件落地一次，同时用于数据库内容与 SDK 附件，避免重复写入。
  - 流式草稿预览 800ms 节流，平衡实时性与平台压力。

[本节为通用性能指导，无需特定文件来源]

## 故障排除指南
- 连接失败与重连
  - 现象：状态变为 error，持续重试。
  - 排查：检查凭证有效性、网络连通性；关注电路保护触发（连续失败超过阈值）。
  - 处理：修复凭证后等待电路保护恢复，或手动重启适配器。
- 会话冲突
  - 现象：SDK 报告会话 ID 已被占用。
  - 处理：自动回退到全新 SDK 会话并重试。
- 权限拒绝
  - 现象：工具调用被拒绝。
  - 处理：检查权限模式（confirm/full），确认用户响应或超时自动拒绝。
- 消息重复
  - 现象：同一条消息多次出现。
  - 处理：检查去重表清理与消息 ID 去重逻辑；确认平台是否重复推送。
- 附件发送失败
  - 现象：图片/文件发送失败或编辑失败回退为新消息。
  - 处理：检查文件大小与类型过滤规则（>20MB、源码/配置等），确认平台支持情况。
- SSE 断连
  - 现象：桌面端无实时更新。
  - 处理：检查 /api/im-events 的 keepalive 与订阅清理逻辑。

**章节来源**
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)
- [src/lib/im/conversation-engine.ts:180-207](file://src/lib/im/conversation-engine.ts#L180-L207)
- [src/lib/im/permission-broker.ts:66-85](file://src/lib/im/permission-broker.ts#L66-L85)
- [src/lib/im/delivery.ts:246-276](file://src/lib/im/delivery.ts#L246-L276)
- [src/app/api/im-events/route.ts:51-54](file://src/app/api/im-events/route.ts#L51-L54)

## 结论
本即时消息桥接服务通过清晰的五层架构实现了多平台适配、命令系统、权限控制与实时同步。桥接管理层承担了核心编排职责，结合路由、对话引擎与投递层，提供了高可靠的消息同步与转发能力。策略模块与权限代理保障了接入安全与可控性。整体设计兼顾扩展性与稳定性，适合在复杂多平台环境中部署与维护。

[本节为总结性内容，无需特定文件来源]

## 附录

### 适配器接口规范要点
- 生命周期必须幂等：重复 start 应当重连。
- 消费模型：阻塞等待直到有消息或信号中断。
- 权限提示：平台原生 UI 或命令交互，支持用户点击允许/拒绝。
- 配置验证：在 start 前进行参数校验，失败即刻返回错误。

**章节来源**
- [src/lib/im/adapters/base.ts:24-101](file://src/lib/im/adapters/base.ts#L24-L101)

### 事件订阅模式
- 事件源：BridgeManager 与命令执行过程中触发事件。
- 订阅方式：EventSource 订阅 /api/im-events，接收类型化事件负载。
- 心跳与清理：30 秒心跳与连接断开清理，保证长连接稳定。

**章节来源**
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)

### 实时通信协议
- 协议：Server-Sent Events（SSE）。
- 内容：事件类型 + JSON 负载，支持 keepalive。
- 兼容性：设置缓存与传输头，避免代理/浏览器误判。

**章节来源**
- [src/app/api/im-events/route.ts:57-65](file://src/app/api/im-events/route.ts#L57-L65)