Adapter：与 NapCat/WS 的桥接与 BotAPI 协作

Adapter 是 NcatBot 与底层 NapCat WebSocket 的桥梁：

• 管理 WS 连接与收发循环；
• 将 NapCat 的上行事件解析为内部事件对象（BaseEventData 及其子类）；
• 提供线程安全的 API 调用通道，供 BotAPI 统一封装上行接口；
• 把收到的事件分发给由 BotClient 注册的事件回调。

---

与 BotAPI 的协作方式

BotAPI 在构造时被注入了一个异步回调：async_callback = adapter.send。

• 当你调用例如 await bot.api.send_group_msg(...) 时，底层会统一路由到 Adapter.send(path, params)；
• Adapter 会：
  1. 生成 echo 并登记一个 Queue 等待响应；
  2. 通过 WS 发送形如 { action, params, echo } 的 JSON；
  3. 在收到带 echo 的响应后，唤醒对应的等待者并返回结果；
  4. 全程使用线程锁与线程到异步的桥接，保证在任意线程/事件循环下都可安全调用。

因此：所有对外暴露的 API 都集中在 BotAPI 层，Adapter 仅作为「可靠传输层」。这使得 API 的扩展与适配器的替换相互解耦。

---

连接与事件处理

await connect_websocket() 会：

1. 使用配置中的 ws_uri 与 ws_token 建立连接；
2. 进入读取循环 recv()；对于每条消息：
   • 若包含 echo：作为 API 响应交给 _handle_response()，唤醒等待队列；
   • 否则：交给 _handle_event() 解析为 PrivateMessageEvent/GroupMessageEvent/NoticeEvent/RequestEvent/MetaEvent。
3. 根据 post_type 与子类型从 event_callback[event_name] 查找并调用回调（由 BotClient 在启动时注册）。

内置的元事件处理：

• meta_event.lifecycle.connect 会触发 OFFICIAL_STARTUP_EVENT；
• meta_event.heartbeat 会触发 OFFICIAL_HEARTBEAT_EVENT。

异常管理：

• 主动关闭：抛出 NcatBotConnectionError 提示 NapCat 关闭了连接；
• 其他异常：清理连接并抛出 NcatBotError；支持 CancelledError 的优雅收尾。

---

关键 API

• await connect_websocket() -> bool：建立并维护 WS 收包循环。
• await send(path: str, params: dict = None, timeout: float = 300.0) -> dict：上行请求/响应模式，线程安全。
• is_websocket_online() -> bool：状态检查。
• event_callback: Dict[str, Callable[[BaseEventData], None]]：回调注册表，由 BotClient 在启动时填充。

---

使用建议

• 不要绕过 BotAPI 直接调用 Adapter.send，以免破坏抽象层次与未来迁移；
• 回调中避免阻塞（Adapter 的回调在事件循环里），BotClient 内部会将你的处理器分发到线程池执行；
• 若需自定义适配器（对接其他平台），建议保持与 Adapter 同样的回调与 send 协议，以便与 BotAPI 无缝集成。

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)