平台轉接器

源码版本v2026.7.20

職責

每個平台(Telegram、Discord、Slack、Signal、WhatsApp、微信、QQ…)各有一個轉接器,把平台原生事件翻譯成統一的 MessageEvent,並把統一發送動作翻譯回平台 API。轉接器繼承 BasePlatformAdapter,實作少量抽象方法即可。轉接器可來自內建 gateway/platforms/ 或外掛 plugins/platforms/,都經 PlatformRegistry 註冊。

關鍵檔案

• class BasePlatformAdapter(ABC):2317 — 轉接器抽象基類
• 抽象方法 send / send_draft:2983-3015 — 子類必須實作的發送介面
• MessageType / ProcessingOutcome / MessageEvent:1737-1759 — 統一事件模型
• CachedMedia:1638-1737 — 媒體快取(避免重複上傳)
• SendResult / EphemeralReply:1898-2068 — 發送結果與臨時回覆
• 通用發送輔助:3173-3326 — send_slash_confirm / send_clarify / send_typing / send_multiple_images
• gateway/platforms/ 目錄 — signal / whatsapp_cloud / weixin / bluebubbles / yuanbao / qqbot…
• plugins/platforms/ 目錄 — Telegram / Discord / Slack(以外掛形式)
• ADDING_A_PLATFORM.md — 新增平台指南
• PlatformRegistry:162 — 註冊表(register / register_deferred / unregister)

資料流

1. 啟動期 GatewayRunner(gateway/run.py:3029)經 _start_one_profile_adapter:9389 拉起轉接器。
2. 轉接器從 PlatformRegistry(gateway/platform_registry.py:162)按名查詢,支援 deferred 載入(便宜先占位,用到才真匯入)。
3. 轉接器監聽平台事件,翻譯成 MessageEvent:1759 交給 _handle_message:9947。
4. agent 產出串流輸出,轉接器經統一介面(send:3008 / send_draft)把內容投遞回平台;媒體走 CachedMedia:1638 快取。
5. 平台差異(訊息長度、富文字、圖片上限)全由轉接器內部吸收,網關核心不感知。

小結

轉接器 = 「平台方言 ↔ 統一事件」的翻譯器。新增平台只需繼承 BasePlatformAdapter 實作幾個抽象方法並註冊,參考 gateway/platforms/ADDING_A_PLATFORM.md。Telegram/Discord/Slack 走外掛路徑,與內建轉接器同等對待。