触发: 用户通过手机 IM 工具（如 Telegram）发送消息
过程: 平台机器人接收消息 → 转发给 Aion Agent → LLM 处理
结果: 处理完成后通过相同平台推送结果给用户

┌─────────────────────────────────────────────────────────────┐
│                  ChannelManager (单例)                        │
│                  (统一管理所有组件)                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │PluginManager│ │SessionManager│ │PairingService│           │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
│  ┌─────────────┐ ┌─────────────────────────────┐            │
│  │ActionExecutor│ │ChannelMessageService         │            │
│  └─────────────┘ └─────────────────────────────┘            │
└────────────────────┼────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                     Layer 1: Plugin                          │
│                     (平台适配层)                             │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐                                   │
│  │ Telegram │ │  Lark    │  ... (Slack, Discord 待实现)      │
│  │  Plugin  │ │  Plugin  │                                   │
│  └────┬─────┘ └────┬─────┘                                   │
│       └────────────┴────────────┘                           │
│                    │                                         │
│  职责: 接收平台消息/回调 → 转换为统一格式 → 发送响应        │
│  不关心: Agent 类型、业务逻辑                               │
└────────────────────┼────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                     Layer 2: Gateway                         │
│                     (业务逻辑层)                             │
├─────────────────────────────────────────────────────────────┤
│  ActionExecutor: 系统 Action 处理、对话路由                  │
│  SessionManager: 会话管理、用户授权                          │
│  PairingService: 配对码生成和验证                            │
│  ChannelMessageService: 消息流式处理                        │
│                                                              │
│  职责: 系统 Action 处理、对话路由、会话管理、权限控制       │
│  不关心: 平台细节、Agent 实现细节                           │
└────────────────────┼────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                     Layer 3: Agent                           │
│                     (AI 处理层)                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
│  │ Gemini  │  │   ACP   │  │  Codex  │                      │
│  │  Agent  │  │  Agent  │  │  Agent  │                      │
│  └─────────┘  └─────────┘  └─────────┘                      │
│                                                              │
│  职责: 与 AI 服务通信、管理对话上下文、返回统一响应         │
│  不关心: 消息来源平台、系统级操作                           │
└─────────────────────────────────────────────────────────────┘

入站流程:
  平台消息 → Plugin(转换) → ActionExecutor(路由) → Agent(处理)

  详细流程:
  1. Plugin 接收平台消息 → toUnifiedIncomingMessage()
  2. PluginManager 调用 messageHandler → ActionExecutor.handleMessage()
  3. ActionExecutor 根据 Action 类型路由:
     - Platform Action → Plugin 自行处理
     - System Action → SystemActions 处理
     - Chat Action → ChannelMessageService → Agent

出站流程:
  Agent 响应 → ChannelEventBus → ChannelMessageService → ActionExecutor → Plugin(转换) → 平台发送

  详细流程:
  1. Agent Worker 发送消息 → ChannelEventBus.emitAgentMessage()
  2. ChannelMessageService 监听事件 → handleAgentMessage()
  3. transformMessage + composeMessage → StreamCallback
  4. ActionExecutor 调用 context.sendMessage/editMessage()
  5. Plugin 转换消息格式 → sendMessage/editMessage()

created → initializing → ready → starting → running → stopping → stopped
                ↓                    ↓           ↓
              error ←←←←←←←←←←←←←←←←←←←←←←←←←←←←

┌─────────────────────────────────────────────────────────────┐
│ Step 1: 创建 Bot                                            │
│   用户在 Telegram 中 @BotFather → /newbot → 获取 Token      │
├─────────────────────────────────────────────────────────────┤
│ Step 2: 配置 Token                                          │
│   AionUi 设置页面 → 粘贴 Token → 验证 → 保存               │
├─────────────────────────────────────────────────────────────┤
│ Step 3: 启动 Bot                                            │
│   开启开关 → Bot 开始监听                                   │
├─────────────────────────────────────────────────────────────┤
│ Step 4: 用户配对（见下方安全机制）                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ ① 用户在 Telegram 中发起                                   │
│    用户 → @YourBot: /start 或任意消息                      │
├─────────────────────────────────────────────────────────────┤
│ ② Bot 返回配对请求                                         │
│    Bot → 用户:                                             │
│    "👋 欢迎使用 Aion 助手！                                │
│     您的配对码: ABC123                                     │
│     请在 AionUi 中批准此配对:                              │
│     设置 → Telegram → 待批准请求 → [批准]"                │
├─────────────────────────────────────────────────────────────┤
│ ③ AionUi 显示待批准请求                                    │
│    设置页面展示: 用户名、配对码、请求时间、[批准]/[拒绝]   │
├─────────────────────────────────────────────────────────────┤
│ ④ 用户在 AionUi 点击 [批准]                                │
├─────────────────────────────────────────────────────────────┤
│ ⑤ Bot 通知配对成功                                         │
│    Bot → 用户: "✅ 配对成功！现在可以开始对话了"           │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Step 1: 创建应用                                            │
│   在飞书开放平台创建企业自建应用 → 获取 App ID 和 App Secret │
├─────────────────────────────────────────────────────────────┤
│ Step 2: 配置权限                                            │
│   应用权限管理 → 开通"获取与发送单聊、群组消息"权限          │
├─────────────────────────────────────────────────────────────┤
│ Step 3: 配置事件订阅                                        │
│   事件订阅 → 订阅"接收消息"事件 → 配置加密密钥（可选）      │
├─────────────────────────────────────────────────────────────┤
│ Step 4: 配置凭证                                            │
│   AionUi 设置页面 → 粘贴 App ID、App Secret → 验证 → 保存   │
├─────────────────────────────────────────────────────────────┤
│ Step 5: 启动 Bot                                            │
│   开启开关 → Bot 通过 WebSocket 连接开始监听               │
├─────────────────────────────────────────────────────────────┤
│ Step 6: 用户配对（见下方安全机制）                          │
└─────────────────────────────────────────────────────────────┘

Bot 消息:
┌─────────────────────────────────────────┐
│ 👋 欢迎使用 Aion 助手！                 │
│                                          │
│ 🔑 配对码: ABC123                       │
│ 请在 AionUi 设置中批准此配对            │
│                                          │
│ [📖 使用指南]  [❓ 获取帮助]            │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ ... 对话内容 ...                        │
├─────────────────────────────────────────┤
│ Reply Keyboard (常驻快捷操作)           │
│ [🆕 新对话] [📊 状态] [❓ 帮助]         │
├─────────────────────────────────────────┤
│ [输入消息...]                   [发送]  │
└─────────────────────────────────────────┘

Bot 消息:
┌─────────────────────────────────────────┐
│ 这是一个快速排序的实现：               │
│                                          │
│ ```python                                │
│ def quicksort(arr):                      │
│     ...                                  │
│ ```                                      │
│                                          │
│ [📋 复制] [🔄 重新生成] [💬 继续]       │
└─────────────────────────────────────────┘

Bot 消息:
┌─────────────────────────────────────────┐
│ ⚙️ 设置                                 │
│                                          │
│ ┌─────────────────────────────────────┐ │
│ │ 🤖 AI 模型                          │ │
│ │ 当前: Gemini 1.5 Pro                │ │
│ └─────────────────────────────────────┘ │
│                                          │
│ ┌─────────────────────────────────────┐ │
│ │ 💬 对话风格                         │ │
│ │ 当前: 专业                          │ │
│ └─────────────────────────────────────┘ │
│                                          │
│ [← 返回]                                │
└─────────────────────────────────────────┘

用户输入
    │
    ├─→ 平台 Action → Plugin 自行处理（不进入 Gateway）
    │       例: Telegram 配对、Slack OAuth、Discord 邀请
    │
    ├─→ 系统 Action → Gateway ActionHandler → 统一处理
    │       例: 会话管理、设置、帮助
    │
    └─→ 对话 Action → AgentRouter → Gemini/ACP/Codex

UnifiedAction {
  action: string          // Action 类型
  params?: object         // 可选参数
  context: {
    platform: string      // 来源平台
    userId: string        // 用户 ID
    chatId: string        // 聊天 ID
    messageId?: string    // 触发消息 ID
    sessionId?: string    // 当前会话 ID
  }
}

格式: action:param1=value1,param2=value2

示例:
• "session.new"
• "settings.model.select:id=gemini-pro"
• "chat.regenerate:msg=abc123"

ActionResponse {
  text?: string                    // 文本内容
  parseMode?: 'plain' | 'markdown' // 解析模式
  buttons?: ActionButton[][]       // Inline 按钮
  keyboard?: ActionButton[][]      // Reply Keyboard
  behavior: 'send' | 'edit' | 'answer'  // 响应行为
  toast?: string                   // Toast 提示
}

Session {
  id: string              // 会话 ID
  platform: string        // 来源平台
  userId: string          // 用户 ID
  chatId: string          // 聊天 ID

  // Agent 配置
  agentType: string       // gemini / acp / codex
  agentConfig: {
    modelId?: string      // 模型 ID
  }

  // 会话状态
  status: string          // active / idle / error
  context: object         // Agent 会话上下文

  // 元数据
  createdAt: number
  lastActiveAt: number
}

┌─────────────────────────────────────────────────────────────────┐
│                    Agent Worker (Gemini/ACP/Codex)              │
│                    (Agent Worker 进程)                          │
├─────────────────────────────────────────────────────────────────┤
│  发送消息事件到 IPC Bridge                                      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ChannelEventBus                               │
│                    (全局事件总线 - 单例)                         │
├─────────────────────────────────────────────────────────────────┤
│  emitAgentMessage(conversationId, data)                          │
│  onAgentMessage(handler) → () => void (cleanup)                  │
│                                                                  │
│  事件类型: 'channel.agent.message'                               │
│  数据结构: IAgentMessageEvent { ...IResponseMessage, conv_id }   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ChannelMessageService                         │
│                    (消息服务 - 单例)                             │
├─────────────────────────────────────────────────────────────────┤
│  initialize() {                                                  │
│    // 服务初始化时注册全局事件监听                               │
│    channelEventBus.onAgentMessage(this.handleAgentMessage);    │
│  }                                                               │
│                                                                  │
│  handleAgentMessage(event) {                                     │
│    // 处理特殊事件: start, finish, error                         │
│    // 使用 transformMessage + composeMessage 合并消息            │
│    // 回调通知: callback(TMessage, isInsert)                     │
│  }                                                               │
│                                                                  │
│  sendMessage(sessionId, conversationId, text, callback) {        │
│    // 仅发送消息，不处理监听                                     │
│    // 通过 WorkerManage 调用 Agent Task                          │
│  }                                                               │
│                                                                  │
│  内部状态:                                                       │
│    activeStreams: Map<conversationId, IStreamState>              │
│    messageListMap: Map<conversationId, TMessage[]>               │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ActionExecutor                                │
│                    (业务执行器)                                  │
├─────────────────────────────────────────────────────────────────┤
│  handleChatMessage(context, text) {                              │
│    messageService.sendMessage(                                   │
│      sessionId, conversationId, text,                             │
│      (message: TMessage, isInsert: boolean) => {                 │
│        const outgoing = convertTMessageToOutgoing(message, platform); │
│        if (isInsert) context.sendMessage(outgoing);              │
│        else context.editMessage(msgId, outgoing);                │
│      }                                                           │
│    );                                                            │
│  }                                                               │
│                                                                  │
│  convertTMessageToOutgoing(message, platform) {                  │
│    // TMessage → IUnifiedOutgoingMessage                         │
│    // 根据平台格式化文本（HTML/Markdown）                        │
│    // text → 显示内容                                            │
│    // tips → 带图标提示                                          │
│    // tool_group → 工具状态列表                                  │
│  }                                                               │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Plugin (Telegram/Lark)                       │
│                    (平台插件)                                    │
├─────────────────────────────────────────────────────────────────┤
│  sendMessage(chatId, message: IUnifiedOutgoingMessage)           │
│  editMessage(chatId, messageId, message: IUnifiedOutgoingMessage)│
└─────────────────────────────────────────────────────────────────┘

type StreamCallback = (chunk: TMessage, isInsert: boolean) => void;

// isInsert = true:  新消息，调用 sendMessage 发送新消息
// isInsert = false: 更新消息，调用 editMessage 编辑现有消息

AgentResponse {
  type: 'text' | 'stream_start' | 'stream_chunk' | 'stream_end' | 'error'
  text?: string
  chunk?: string
  error?: { code: string, message: string }
  metadata?: {
    model?: string
    tokensUsed?: number
    duration?: number
  }
  suggestedActions?: ActionButton[]
}

src/channels/
├── core/                          # 核心模块
│   ├── ChannelManager.ts          # 统一管理器（单例）
│   └── SessionManager.ts          # 会话管理
│
├── gateway/                       # 网关层
│   ├── PluginManager.ts           # 插件生命周期管理
│   └── ActionExecutor.ts          # Action 执行器（路由、消息处理）
│
├── actions/                       # Action 处理（平台无关）
│   ├── types.ts                   # Action/Response 类型定义
│   ├── SystemActions.ts          # 系统 Action（会话、设置、帮助）
│   ├── ChatActions.ts            # 对话 Action（发送、重新生成等）
│   └── PlatformActions.ts        # 平台 Action（配对等）
│
├── agent/                         # Agent 集成
│   ├── ChannelEventBus.ts        # 全局事件总线
│   └── ChannelMessageService.ts  # 消息流式处理服务
│
├── pairing/                       # 配对服务
│   └── PairingService.ts         # 配对码生成和验证（平台无关）
│
├── plugins/                       # 插件目录
│   ├── BasePlugin.ts              # 插件抽象基类
│   ├── telegram/
│   │   ├── TelegramPlugin.ts      # Telegram 插件
│   │   ├── TelegramAdapter.ts     # 消息适配器
│   │   └── TelegramKeyboards.ts   # 键盘组件
│   └── lark/
│       ├── LarkPlugin.ts          # Lark 插件
│       ├── LarkAdapter.ts         # 消息适配器
│       └── LarkCards.ts           # Card 组件
│
├── utils/                         # 工具函数
│   └── credentialCrypto.ts        # 凭证加密
│
└── types.ts                       # 类型定义

1. ChannelManager.getInstance().initialize()
   ├─ 初始化 PluginManager
   ├─ 初始化 SessionManager
   ├─ 初始化 PairingService
   ├─ 初始化 ActionExecutor
   └─ 初始化 ChannelMessageService

2. 加载数据库中的插件配置
3. 为每个启用的插件调用 initialize() 和 start()

1. Plugin 接收平台消息
   └─ toUnifiedIncomingMessage() 转换

2. PluginManager 调用 messageHandler
   └─ ActionExecutor.handleMessage()

3. ActionExecutor 路由 Action
   ├─ Platform Action → PlatformActions
   ├─ System Action → SystemActions
   └─ Chat Action → ChannelMessageService

4. ChannelMessageService.sendMessage()
   └─ 通过 WorkerManage 调用 Agent Task

5. Agent 响应 → ChannelEventBus
   └─ ChannelMessageService.handleAgentMessage()
      └─ StreamCallback → ActionExecutor
         └─ Plugin.sendMessage/editMessage()