平台适配器

源码版本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 走插件路径,与内置适配器同等对待。