onebots

简体中文

English

简体中文

English

主题

onebots 系统架构 ​

本文档描述了 onebots 系统的整体架构，包括服务端和客户端组件。

整体架构图 ​

建议放大查看

数据流向图 ​

组件说明 ​

服务端组件 ​

1. 应用层 (App Layer) ​

  • BaseApp: 核心应用基类，提供配置管理、日志系统、HTTP/WebSocket 服务器、路由管理等基础功能
  • 配置管理: 基于 YAML 的配置文件，支持全局配置、账号配置、协议配置
  • 路由管理: 基于 Koa 的路由系统，动态注册协议路由

2. 适配器层 (Adapter Layer) ​

  • QQ Adapter: 连接 QQ 官方机器人平台
  • WeChat Adapter: 连接微信公众平台
  • Kook Adapter: 连接 Kook 开放平台
  • Discord Adapter: 连接 Discord API
  • 每个适配器负责：
    • 连接平台 API
    • 提取平台事件并转换为统一格式
    • 执行平台动作（发送消息、管理群组等）

3. 账号层 (Account Layer) ​

  • 管理每个平台账号的实例
  • 维护账号状态（在线/离线）
  • 绑定协议实例
  • 处理账号级别的事件分发

4. 协议层 (Protocol Layer) ​

  • OneBot V11: 提供 OneBot V11 标准协议接口
  • OneBot V12: 提供 OneBot V12 标准协议接口
  • Satori V1: 提供 Satori 协议接口
  • Milky V1: 提供 Milky 协议接口
  • 每个协议负责：
    • 实现协议标准的 HTTP/WebSocket 接口
    • 转换平台事件为协议事件格式
    • 转换协议 API 调用为平台动作

客户端组件 ​

1. imhelper 核心 ​

  • ImHelper: 统一的客户端接口，提供：
    • 消息发送 API
    • 事件监听
    • 账号管理
    • 跨协议的统一抽象

2. 客户端适配器 ​

  • OneBot V11 Adapter: OneBot V11 协议的客户端实现
  • OneBot V12 Adapter: OneBot V12 协议的客户端实现
  • Satori V1 Adapter: Satori 协议的客户端实现
  • Milky V1 Adapter: Milky 协议的客户端实现
  • 每个适配器包含：
    • HTTP 客户端（用于 API 调用）
    • 事件接收器（WebSocket/Webhook/SSE）

3. 接收器 (Receivers) ​

  • WebSocket Receiver: 实时事件接收，支持自动重连
  • WSS Receiver: 安全 WebSocket，TLS 加密
  • Webhook Receiver: HTTP 服务器，接收服务端推送的事件
  • SSE Receiver: Server-Sent Events，长连接事件接收

通信方式 ​

服务端提供的通信方式 ​

  1. HTTP API: RESTful API，用于调用机器人功能
  2. WebSocket: 双向通信，支持实时事件推送和 API 调用
  3. Webhook: 服务端主动推送事件到客户端
  4. SSE: Server-Sent Events，单向事件流

客户端支持的接收方式 ​

  1. WebSocket: 连接到服务端 WebSocket，实时接收事件
  2. WSS: 安全 WebSocket 连接
  3. Webhook: 启动 HTTP 服务器，接收服务端推送
  4. SSE: 通过 Server-Sent Events 接收事件流

扩展性 ​

添加新平台 ​

  1. 创建新的适配器包（如 adapter-telegram）
  2. 实现 Adapter 基类
  3. 注册到 AdapterRegistry
  4. 配置账号信息

添加新协议 ​

  1. 创建新的协议包（如 protocol-telegram-bot-api）
  2. 实现 Protocol 基类
  3. 注册到 ProtocolRegistry
  4. 配置协议选项

自定义客户端 ​

  1. 使用 imhelper 核心
  2. 选择或创建协议适配器
  3. 选择接收方式（WebSocket/Webhook/SSE）
  4. 实现业务逻辑

相关链接 ​