@onebots/protocol-onebot-v11

OneBots OneBot V11 协议实现 - 支持 OneBot 11 标准的协议插件

简介

@onebots/protocol-onebot-v11 是 OneBots 框架的官方 OneBot V11 协议实现，完全兼容 OneBot 11 标准，提供 HTTP、WebSocket 等多种通信方式。

特性

• ✅ 完整支持 - 实现 OneBot 11 全部标准 API
• 🔌 多通信方式 - HTTP、WebSocket、HTTP Reverse、WebSocket Reverse
• 🔐 安全认证 - 支持 Access Token 和签名验证
• 📨 消息格式 - 支持 CQ 码和数组格式
• 🎯 事件过滤 - 灵活的事件过滤机制
• 🔄 自动转换 - 平台消息与 OneBot 格式自动转换

安装

npm install @onebots/protocol-onebot-v11
# 或
pnpm add @onebots/protocol-onebot-v11

使用方法

重要： 协议必须先注册才能使用。即使在配置文件中配置了 onebot.v11 协议，如果没有注册该协议，配置也不会生效。

1. 命令行注册（推荐）

使用 onebots 命令行工具时，通过 -p 参数注册协议：

# 注册 OneBot V11 协议
onebots -p onebot-v11

# 同时注册多个协议
onebots -p onebot-v11 -p onebot-v12 -p satori-v1

# 注册协议并指定适配器
onebots -r wechat -p onebot-v11 -c config.yaml

协议会自动从以下位置加载：

• @onebots/protocol-onebot-v11 (官方包)
• onebots-protocol-onebot-v11 (社区包)
• onebot-v11 (直接包名)

2. 配置文件方式

accounts:
  - platform: wechat
    account_id: my_account
    protocol: onebot.v11
    
    # OneBot V11 配置
    use_http: true              # 启用 HTTP
    use_ws: true                # 启用 WebSocket
    access_token: your_token    # 访问令牌
    secret: your_secret         # 签名密钥
    heartbeat_interval: 15000   # 心跳间隔(ms)
    
    # HTTP Reverse
    http_reverse:
      - http://localhost:5700/onebot/v11
    
    # WebSocket Reverse
    ws_reverse:
      - ws://localhost:6700/onebot/v11

3. 代码方式

import { App } from 'onebots';
import { OneBotV11Protocol } from '@onebots/protocol-onebot-v11';

// 注册协议
await App.registerProtocol('onebot', OneBotV11Protocol, 'v11');

// 创建应用
const app = new App();
await app.start();

配置参数

通信方式

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | use_http | boolean | true | 启用 HTTP API | | use_ws | boolean | false | 启用 WebSocket | | http_reverse | string[] | [] | HTTP 反向推送地址 | | ws_reverse | string[] | [] | WebSocket 反向连接地址 |

安全配置

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | access_token | string | - | 访问令牌 | | secret | string | - | 签名密钥 | | enable_cors | boolean | false | 启用 CORS |

消息配置

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | post_message_format | "string" | "array" | "array" | 消息格式 | | heartbeat_interval | number | - | 心跳间隔(ms) | | post_timeout | number | 5000 | 推送超时(ms) |

通信方式

HTTP API

访问地址：

http://host:port/{platform}/{account_id}/onebot/v11/{action}

示例：

curl -X POST http://localhost:6727/wechat/my_account/onebot/v11/send_private_msg \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"user_id": 123456, "message": "Hello"}'

WebSocket

连接地址：

ws://host:port/{platform}/{account_id}/onebot/v11

HTTP Reverse

OneBots 主动推送事件到配置的 HTTP 地址。

WebSocket Reverse

OneBots 主动连接到配置的 WebSocket 地址。

API 列表

消息 API

• send_private_msg - 发送私聊消息
• send_group_msg - 发送群消息
• send_msg - 发送消息
• delete_msg - 撤回消息
• get_msg - 获取消息
• get_forward_msg - 获取合并转发消息
• send_like - 发送好友赞
• set_group_kick - 群组踢人
• set_group_ban - 群组单人禁言
• set_group_anonymous_ban - 群组匿名用户禁言
• set_group_whole_ban - 群组全员禁言
• set_group_admin - 群组设置管理员
• set_group_anonymous - 群组匿名
• set_group_card - 设置群名片
• set_group_name - 设置群名
• set_group_leave - 退出群组
• set_group_special_title - 设置群组专属头衔
• set_friend_add_request - 处理加好友请求
• set_group_add_request - 处理加群请求/邀请

获取信息 API

• get_login_info - 获取登录号信息
• get_stranger_info - 获取陌生人信息
• get_friend_list - 获取好友列表
• get_group_info - 获取群信息
• get_group_list - 获取群列表
• get_group_member_info - 获取群成员信息
• get_group_member_list - 获取群成员列表
• get_group_honor_info - 获取群荣誉信息
• get_cookies - 获取 Cookies
• get_csrf_token - 获取 CSRF Token
• get_credentials - 获取 QQ 相关接口凭证
• get_record - 获取语音
• get_image - 获取图片
• can_send_image - 检查是否可以发送图片
• can_send_record - 检查是否可以发送语音
• get_status - 获取运行状态
• get_version_info - 获取版本信息
• set_restart - 重启 OneBot 实现
• clean_cache - 清理缓存

CQ 码支持

完整支持 CQ 码格式：

// 文本
[CQ:text,text=Hello]

// 表情
[CQ:face,id=123]

// 图片
[CQ:image,file=http://example.com/image.jpg]

// 语音
[CQ:record,file=http://example.com/audio.mp3]

// @某人
[CQ:at,qq=123456]

// 回复
[CQ:reply,id=123456]

// 更多 CQ 码...

事件类型

消息事件

• message.private - 私聊消息
• message.group - 群消息

通知事件

• notice.group_upload - 群文件上传
• notice.group_admin - 群管理员变动
• notice.group_decrease - 群成员减少
• notice.group_increase - 群成员增加
• notice.group_ban - 群禁言
• notice.friend_add - 好友添加
• notice.group_recall - 群消息撤回
• notice.friend_recall - 好友消息撤回

请求事件

• request.friend - 加好友请求
• request.group - 加群请求/邀请

元事件

• meta_event.lifecycle - 生命周期
• meta_event.heartbeat - 心跳

开发

# 安装依赖
pnpm install

# 构建
pnpm build

相关链接

• OneBot 11 标准
• OneBot 文档
• OneBots 文档

许可证

MIT License - 查看 LICENSE 文件了解详情

作者

凉菜