botuniverse / onebot

OneBot：统一的聊天机器人应用接口标准

OneBot

OneBot 是一个聊天机器人应用接口标准，旨在统一不同聊天平台上的机器人应用开发接口，使开发者只需编写一次业务逻辑代码即可应用到多种机器人平台。

注意，本仓库是 OneBot 标准的最新草案，发布在 https://12.onebot.dev，要查看目前已正式发布的版本，请前往 https://onebot.dev 查找相关链接。

特点

• 简洁：标准所描述的连接规范和接口定义简洁明了，易于理解、实现和接入，同时文档语言清晰易读
• 通用：连接规范适用于几乎所有聊天机器人平台，接口定义抽象了众多聊天机器人 API 的共通部分，保证了通用性
• 可扩展：针对不同聊天机器人平台提供的特色功能，OneBot 实现可根据需要方便地对标准接口进行扩展
• 开放：标准的制定和维护采用开放的运作模式，贡献者提出 RFC 后，由社区评议决定是否接收

本地预览

要在本地预览 OneBot 标准文档，请参考下面命令：

$ pip install -r requirements.txt
$ mkdocs serve

贡献

如果你有兴趣帮助完善 OneBot，可积极参与 discussions 中的讨论、提出 RFC 或帮助更新标准文档，具体贡献方式请参考 贡献指南。

onebot's Issues

kick_group_member 新增 until_time 字段

• 状态：关闭
• 相关 PR：无

摘要

kick_group_member 新增 until_time 字段，以指定在踢出成员后多久时间内不允许其再次入群。

动机

QQ 在踢出时能指定不再接受此人加群申请，Telegram 在踢出时能指定封禁时长。

具体描述

字段名	数据类型	默认值	说明
group_id	string	-	群 ID
user_id	string	-	用户 ID
until_time	int64	-	用户禁止使用的时间，单位秒。在 Telegram，如果用户被禁止使用超过366天或从当前时间起少于 30 秒，则视为永久禁止使用。在 QQ，如果大于 0 秒，则视为永久禁止使用。

局限

替代方案

多机器人账号连接复用

摘要

为 OneBot 标准添加单 OneBot Connect 连接上多机器人账号支持。

动机

以便于实现 OneBot 多账号控制器、单个实现进程登录多个账号等。

具体描述

基本数据类型

• 页面移动到“OneBot Connect - 数据协议”

• 新增 Self 类型，形如：

  {
      "platform": "qq",
      "user_id": "1234567"
  }

OneBot Connect - 通信方式

• HTTP Webhook 和反向 WebSocket 去掉 X-Self-ID 和 X-Platform 头

OneBot Connect - 数据协议 - 事件

• 移除 self_id、platform 字段
• 除元事件外，新增 self 字段，类型 Self

OneBot Connect - 数据协议 - 动作请求

• 除元动作外，新增 self 字段，单 bot 时可选，多 bot 时必须

OneBot Connect - 数据协议 - 动作响应

• 新增返回码 10101 Who Am I：未指定机器人账号，备注“OneBot 实现在单个 OneBot Connect 连接上支持多个机器人账号，但动作请求未指定要使用的账号”

接口定义 - 元接口 - 元动作

• get_status 接口响应修改为：

  {
      "status": "ok",
      "retcode": 0,
      "data": {
          "good": true,
          "bots": [
              {
                  "self": {
                      "platform": "qq",
                      "user_id": "1234567"
                  },
                  "online": true,
                  "qq.status": "信号弱"
              },
              {
                  "self": {
                      "platform": "tg",
                      "user_id": "2345678"
                  },
                  "online": true
              }
          ]
      },
      "message": ""
  }

局限

无

替代方案

下面是一种修改更大的方案：

• 动作请求：

  {
      "id": "...", // 原 echo
      "self": {
          "platform": "qq",
          "user_id": "1234567"
      },
      "name": "get_user_info",
      "params": {
          // ...
      }
  }

• 事件：

  {
      "id": "...",
      "self": {
          "platform": "qq",
          "user_id": "1234567"
      },
      "time": 123.456,
      "name": "message.private",
      "data": {
          // 具体的事件数据
      }
  }

如果如果这个方案以后证明确实好的话，或许可以在下一个 OneBot 大版本引入，OneBot 12 先不引入了。

添加两级群组 (Guild-Channel) 支持

• 状态：候选
• 相关 PR：#160

摘要

添加对于频道的支持

相关链接： 关于频道（Guild）相关事件以及 API #131

动机

目前协议内仅存在单用户接口与单级群组接口，对于频道以及类似的两级群组缺乏必要的支持。

本 RFC 提议向现有协议增加两级群组相关接口，以扩大 OneBot 协议的适用范围。

具体描述

两级群组需要增加以下接口

消息事件

message.channel 频道消息

字段名	数据类型	说明
detail_type	string	必须为 channel
message_id	string	消息唯一 ID
message	message	消息内容
alt_message	string	消息内容的替代表示, 可以为空
guild_id	string	群组 ID
channel_id	string	频道 ID
user_id	string	用户 ID

通知事件

notice.guild_member_increase 群组成员增加

字段名	数据类型	说明
detail_type	string	必须为 guild_member_increase
sub_type	string	必须为 join、invite、空字符串或扩展的子类型
guild_id	string	群组 ID
user_id	string	用户 ID
operator_id	string	操作者 ID

notice.guild_member_decrease 群组成员减少

字段名	数据类型	说明
detail_type	string	必须为 guild_member_decrease
sub_type	string	必须为 leave、kick、空字符串或扩展的子类型
guild_id	string	群组 ID
user_id	string	用户 ID
operator_id	string	操作者 ID

notice.channel_message_delete 频道消息删除

字段名	数据类型	说明
detail_type	string	必须为 channel_message_delete
sub_type	string	必须为 recall、delete、空字符串或扩展的子类型
guild_id	string	群组 ID
channel_id	string	频道 ID
message_id	string	消息 ID
user_id	string	消息发送者 ID
operator_id	string	操作者 ID

notice.channel_create 新建频道

字段名	数据类型	说明
detail_type	string	必须为 channel_create
guild_id	string	群组 ID
channel_id	string	频道 ID
operator_id	string	操作者 ID

notice.channel_delete 删除频道

字段名	数据类型	说明
detail_type	string	必须为 channel_delete
guild_id	string	群组 ID
channel_id	string	频道 ID
operator_id	string	操作者 ID

动作

消息动作 send_message 发送消息需要增加 detail_type: "channel"，以及 guild_id 和 channel_id 字段

get_guild_info 获取群组信息

请求参数

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID

响应数据

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID
guild_name	string	-	群组名称

get_guild_list 获取群组列表

无请求参数，响应数据参见 get_guild_info

get_channel_info 获取频道信息

请求参数

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID
channel_id	string	-	频道 ID

响应数据

字段名	数据类型	默认值	说明
channel_id	string	-	频道 ID
channel_name	string	-	频道名称

get_channel_list 获取频道列表

请求参数

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID

响应数据参见 get_channel_info

get_guild_member_info 获取群组成员信息

请求参数

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID
user_id	string	-	用户 ID

响应数据

字段名	数据类型	默认值	说明
user_id	string	-	用户 ID
nickname	string	-	用户名称/昵称

get_guild_member_list 获取群组成员列表

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID

响应数据参见 get_guild_member_info

set_guild_name 设置群组名称

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID
guild_name	string	-	新群组名称

无响应数据

set_channel_name 设置频道名称

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID
channel_id	string	-	频道 ID
channel_name	string	-	新频道名称

无响应数据

leave_guild 退出群组

字段名	数据类型	默认值	说明
guild_id	string	-	群组 ID

无响应数据

局限

• 目前两级群组没有可参考的成熟用例
• 各 IM Guild API 未完全确定，本 RFC 所建议增加的接口是参考目前各家 API 选取尽可能的交集提出
• 对于 Role 等未提供很好的支持，需要后续其他 RFC 继续完善。

替代方案

可以将两级群组减并为单级群组接口的扩展实现:

使用单级群组增加 guild.id 的形式代替 guild_id， 原 group_id 记录 channel_id。

但是该方案缺少直接的 Guild 相关接口，亦无法体现 Guild-Channel 的从属关系。

明确动作请求 `self` 字段要求

具体描述

• 新增 10102 Unknown Self 响应码，表示“不存在的机器人账号”，备注“动作请求指定的机器人账号不存在”
• 当元动作的请求传入了 self，实现可直接忽略，也可按下面逻辑处理
• 当多机器人账号复用 OBC 时
  • 若非元动作请求没有传入 self，行为由 OneBot 实现定义，可以返回 10101 Who Am I
  • 若动作请求传入的 self 不存在，返回 10102 Unknown Self
• 当 OBC 不复用时
  • 若动作请求传入的 self 不存在，返回 10102 Unknown Self

局限

无

替代方案

无

ban_group_member 新增 until_time 字段

• 状态：关闭
• 相关 PR：无

摘要

ban_group_member 新增 until_time 字段，以指定在禁言成员后多久时间内不允许其再次发言。

动机

QQ 最长能指定禁言 30 天，Telegram 最长能指定禁言永久。

具体描述

字段名	数据类型	默认值	说明
group_id	string	-	群 ID
user_id	string	-	用户 ID
until_time	int64	-	用户禁止发言的时间，单位秒。在 Telegram，如果用户被禁止发言超过366天或从当前时间起少于 30 秒，则视为永久禁止发言。在 QQ，最长可禁止发言 30 天。

局限

替代方案

正向 WebSocket 支持使用 `Sec-WebSocket-Protocol` 头传递鉴权 token

• 状态：关闭
• 相关 PR：无

摘要

修改原有鉴权方式。

动机

在浏览器端发起 WebSocket 连接时无法操作 Header。

具体描述

var aWebSocket = new WebSocket(url [, protocols]);
以上为 WebSocket 标准语法，参见 MDN。
建议通过 protocols 参数（Sec-WebSocket-Protocol 头）传输 access_token。

鉴权

如果配置了 access_token 且不为空字符串，OneBot 实现必须在连接建立前（协议 upgrade 前）检查请求头中的 Sec-WebSocket-Protocol 头是否等于 <access_token>（<access_token> 不需要对两边的空白字符进行裁剪），若等于则认为鉴权成功，否则鉴权失败。

局限

这并不是 protocols 参数应该做的事。

替代方案

可以在 WebSocket 消息中包含 access_token 字段。

请提供一个方便JSON类型鉴别器识别的字段，并保持字段第一位，并且合并类型

说明

首先说明我使用的语言为 .NET 8.0，我使用 System.Text.Json 的类型鉴别器发现一个问题。

type 字段它必须保证为第一位，否则它无法正常工作抛出异常，我查阅了C#运行时仓库的相关反馈

dotnet/runtime/issues/72604 ，确实是不支持，不过在.NET9后开始支持，它会给我们提供个AllowOutOfOrderMetadataProperties属性用于控制读取无序的JSON，但这样需要预先读取所有内容进行缓存所以出现了性能效率问题（变慢）。

当然还有一个问题，不支持子类型嵌套的类型鉴别器，也就是子类型无效，这样导致后果只能进行手动进行序列化和反序列化，我个人觉得在一个同级类型中就不要搞什么主类型和子类型了，只弄一个Type类型字段，可以采用 message.private/ message.group / xxx.xxx.xxx.xxx.... 进行表示

简述

1.调整type字段为第一位（另一个解决方案增加一个新的 $type 字段到第一位）
2.同级类不单独再设置一个子类型字段，应与type进行合并，使用 xxx.xxx.xxx.xxx.... 进行表示，使用 . 分割代表有子类型，示例：message.private 、 message.group 以便多态序列化和反序列化，目前我看见的OneBot都是通过手动序列化/反序列化 提取type 和 detail_type, 然后根据多态类类型字典进行查找然后再次序列化到目标的类

最后

我个人觉得消息段中使用Data套了一层，我觉得是没有必要的

取消各接口扩展规则中对前缀的强制性要求

• 状态：接收
• 相关 PR：#157

摘要

在事件、动作、消息段的扩展规则中，取消对 <platform>. 或 <impl>. 前缀的强制性要求。

相关链接：

• specs/interface/index.md#扩展
• specs/interface/event/extended.md
• specs/interface/action/extended.md
• specs/interface/segment/extended.md

动机

此前强制要求所有扩展的名字都需要加聊天平台或 OneBot 实现专属的前缀，以防止不同平台、不同实现之间发生命名冲突的情况，但实际上这造成了 OneBot 实现的编写不便、用户使用也不便。

目前看来，相比潜在的不同平台、不同实现之前同一个命名含义不同的冲突，OneBot 实现的编写和使用的便捷性更为重要，在标准层面进行强制的前缀约束可能弊大于利。

具体描述

本 RFC 提议删掉标准中对扩展规则的描述中，强制要求前缀的部分，改为建议使用前缀但不强制。也就是说，OneBot 实现者可以根据接口的实际情况，包括是不是潜在地适用于不同平台、是否加了前缀会不够直观等因素，来决定要不要加前缀。

相关页面中 JSON 形式的事件、动作、消息段的实例不需要调整，以体现对使用前缀的建议。

对前缀的格式要求不变，如果实现决定添加前缀，仍然应该使用 <impl>. 或 <platform>.。

局限

取消了强制前缀约束后，不同平台、实现可能会发生同一个名字的事件、动作、消息段、字段，具有不同的数据类型或含义的情况。但并不意味着我们任由命名冲突发生，而是应由人们根据情况进行冲突避免和解决。具体来说，解决命名冲突有很多办法：

1. 在命名之前进行沟通，需要时提前标准化
2. 发生冲突后沟通，需要时进行标准化，各实现修改为标准含义
3. 发生冲突后在使用时（SDK 或用户代码中）根据 impl 和 platform 辨别含义

替代方案

一个替代方案是在 LibOneBot 和 OneBotSDK 中为前缀提供更为便捷的写法，但这种方案仍然会为 OneBot 实现的编写者和用户带来心智负担，举例来说，人们仍然需要区分：

# OneBot 实现
ob.add_action("send_message", ...)  # 实现 send_message 动作
ob.add_extended_action("get_something", ...)  # 实现 tg.get_something 动作

# OneBot 用户
ob.send_message(...)  # 调用 send_message 动作
ob.tg.send_message(...)  # 调用 tg.get_something 动作

实际上，LibOneBot 和 OneBotSDK 仍然可以提供这样的区分方式，这和解除强制性前缀约束不冲突。

修改事件时间格式为 `float64` 类型

• 状态：接收
• 相关 PR：#156

摘要

将事件的 time 字段类型修改为 float64，单位为秒。

动机

在一些情况下，事件提供的时间精度不够准确。特别是在高并发环境下，一秒钟内有多条消息时间并发的可能性非常高。在这种情况下，就需要使用精确度更高的时间戳进行描述。

如果有的聊天平台只实现了秒级别精度的时间戳，应将小数部分设为 0。

局限

无。

替代方案

使用毫秒作为该字段单位。

增加 platform_time 字段

• 状态：关闭
• 相关 PR：无

摘要

为所有事件增加 platform_time 字段，表示 OneBot 实现平台产生事件的时间，在元事件里可以为空。

动机

在例如 Telegram 等聊天平台的 API 提供的时间不一定跟 OneBot 事件产生时间相同，因此增加此字段用以跟 OneBot 事件产生时间区分。

具体描述

字段名	数据类型	说明
id	string	事件唯一标识符
impl	string	OneBot 实现名称，格式 [_a-z]+
platform	string	OneBot 实现平台名称，格式 [_a-z]+
self_id	string	机器人自身 ID
time	float64	OneBot 实现事件发生时间（Unix 时间戳），单位：秒
type	string	事件类型，必须是 meta、message、notice、request 中的一个，分别表示元事件、消息事件、通知事件和请求事件
detail_type	string	事件详细类型
sub_type	string	事件子类型（详细类型的下一级类型）
platform_time	int64	OneBot 实现平台事件发生时间（时间戳）

局限

替代方案

明确 `get_latest_events` 的行为

摘要

明确 get_latest_events 动作在不同通信方式下的响应方式以及规定部分未定义行为。

动机

这个问题是编写 LibOB 时发现的，当 OneBot 产生一个事件时，在开发层面发现 OneBot 12 当前的标准文档中未定义一些边缘行为。

具体描述

OneBot Connect - 通信方式 - HTTP - 事件轮询

补充描述：

不同通信方式之间应该相互隔离，即，无论其它通信方式上是否成功推送事件，get_latest_events 都应该能收到所有事件（在未超出缓冲区的情况下）。OneBot 实现应建议用户不要同时使用 get_latest_events 和其它通信方式来接收事件。

修改描述：

多个并发请求同时调用 get_latest_events 是未定义行为，OneBot 实现可以做任意假设。

为：

多个并发请求同时调用 get_latest_events 的结果由 OneBot 实现定义，实现可以对后来的请求返回错误码、返回空事件列表或是对所有请求返回相同的事件列表。

接口定义 - 元接口 - 元动作 - get_latest_events

修改 timeout 参数说明为：

没有事件时最多等待的秒数，0 表示使用短轮询，不等待

局限

无

替代方案

无

动作请求 `echo` 字段名改为 `id`

摘要

如题。

动机

id 的含义更明确一些，并且和事件对称。

具体描述

如题。

局限

无。

替代方案

无。

`get_latest_events` 元动作不要求包含元事件

• 状态：接收
• 相关 PR：#162

摘要

get_latest_events 元动作是仅 HTTP 通信方式必须实现的元动作，用于轮询获取最新事件列表。本 RFC 在标准中建议该动作返回列表不包含元事件。

动机

元事件的一种——心跳事件，会按固定间隔产生，这类事件放在 get_latest_events 返回结果里没有意义。

具体描述

同摘要。

局限

无。

替代方案

无。

支持使用 URL query 参数传递鉴权 token

摘要

在 Authorization 头之外，允许通过 /?access_token=xxx 来传递 access_token。

动机

部分场景下，应用端或 OneBot 实现无法操作 HTTP 请求头，例如：

• 浏览器和 Deno 发起 WebSocket 连接时
• IFTTT Maker Webhooks

具体描述

通信方式 - HTTP、正向 WebSocket

“鉴权”部分，实现应优先检查 Authorization 头，如果存在，则依照原来的标准鉴权，如果不存在，则尝试获取 access_token URL query 参数，以此鉴权。

通信方式 - HTTP Webhook

“请求头”部分，若无法操作请求头，实现可以通过 access_token URL query 参数来传递 token，应用端应优先检查 Authorization 头，如果存在，则依照原来的标准鉴权，如果不存在，则尝试获取 access_token URL query 参数，以此鉴权。

反向 WebSocket 文档会指向此处，故不用修改。

局限

无。

替代方案

无。

两级群组接口中为频道增加成员增减相关接口

摘要

两级群组接口中，添加频道增加/减少成员事件，添加获取频道成员信息、获取频道成员列表、退出频道动作。

动机

Slack 等平台中，用户加入 guild 后，对 channel 也有加入和退出操作，会在 channel 内显示新成员加入的通知。也就是说两级群组都有“成员管理”这个概念。对于 channel 没有加入和退出概念的平台（如 QQ 频道），这些接口可以不实现。

具体描述

群组通知事件

新增：

• notice.channel_member_increase 频道成员增加
• notice.channel_member_decrease 频道成员减少

字段和 notice.guild_member_increase 等相比多一个 channel_id。

群组动作

新增：

• get_channel_member_info 获取频道成员信息
• get_channel_member_list 获取频道成员列表

参数和 get_guild_member_info 等相比多一个 channel_id，响应数据和 get_guild_member_info 等相同。

• leave_channel 退出频道

参数和 leave_guild 相比多一个 channel_id。

变更：

• get_channel_list 动作语义修改为“获取指定群组中机器人可见的频道列表”，同时增加 joined_only 参数，类型为 bool，默认值 false，用于限制只获取机器人账号已加入的频道列表

局限

无。

替代方案

无。

`get_version` 动作响应数据移除 `platform`

摘要

如题。

动机

因为元动作现在的定义只针对实现，不针对机器人平台。

具体描述

get_version 动作响应数据中：

• 移除 platform
• 修改 impl 格式描述指向术语表

局限

无。

替代方案

无。

明确事件 `time` 字段表述

• 状态：接收
• 相关 PR：#184

摘要

明确事件的基本字段 time 的含义为事件在 IM 平台上的发生时间，如果无法得知平台发生时间，才应使用 OneBot 实现中的事件对象产生时间。

动机

根据 #170 的讨论发现此处表述有模糊。

具体描述

修改“OneBotRPC - 数据协议 - 事件”页面的 time 字段说明为“事件发生时间（Unix 时间戳），单位：秒，建议优先采用聊天平台给出的时间，其次采用实现中创建事件对象的时间”。

局限

无。

替代方案

无。

反向 WebSocket 支持使用 `Sec-WebSocket-Protocol` 头传递 `X-OneBot-Version` 和 `X-Impl`

摘要

Sec-WebSocket-Protocol 协议名称为 <onebot_version>.<impl>，<onebot_version> 和 <impl> 的要求同 X-OneBot-Version 和 X-Impl 头，例如：

Sec-WebSocket-Protocol: 12.walle-q

动机

同 #164。Authorization 由 #175 解决。

具体描述

此 RFC 依赖 #181。

通信方式 - 反向 WebSocket

“请求头”部分重写如下：

在请求连接时，应设置以下请求头：

• User-Agent：具体的 UA 值可以由实现自行定义
  • 例如 User-Agent: OneBot/12 (qq) Go-LibOneBot/1.0.0
• Sec-WebSocket-Protocol: <onebot_version>.<impl>：<onebot_version> 应为实现的 OneBot 标准版本（如 12），<impl> 应为实现的名称，格式见术语表

局限

无。

替代方案

无。

关于在写onebot12协议java-sdk的一些想法

Discussed in https://github.com/orgs/botuniverse/discussions/247

^{Originally posted by eiriksgata October 25, 2023}
讨论1： 关于事件的数据拓展字段。

我们都知道在12标准协议中，必填字段有 id、time、type、detail_type、sub_type ，其余如果想要进行拓展，那么其拓展的字段是位于 当前 Event 所在的并级下，我认为这是一种不合理的设计。

如文档中给出的例子：

{
    "id": "b6e65187-5ac0-489c-b431-53078e9d2bbb",
    "self": {
        "platform": "qq",
        "user_id": "123234"
    },
    "time": 1632847927.599013,
    "type": "message",
    "detail_type": "private",
    "sub_type": "",
    "message_id": "6283",
    "message": [
        {
            "type": "text",
            "data": {
                "text": "OneBot is not a bot"
            }
        }
    ],
    "alt_message": "OneBot is not a bot",
    "user_id": "123456788",
    "qq.nickname": "海阔天空"
}

根据例子来看，其事件是往机器人平台发送一条私聊消息，其中包含 message、 user_id 等相关字段，这些字段都是位于 Event 所在的当前层级，对于常规的弱语言（形如脚本语言）来说，json增加字段确实没什么问题，但是对于强语言类型来说，我们必然是要定义一个Class 来 实现实体类，或者是 ts 定义一个 type | interface 来增强语言类型。

想message、user_id 这种拓展字段 ，本身应该是填写在 Event 所在的 某个字段下级，例如下面例子：

{
  "id": "b6e65187-5ac0-489c-b431-53078e9d2bbb",
  "self": {
    "platform": "qq",
    "user_id": "123234"
  },
  "time": 1632847927.599013,
  "type": "message",
  "detail_type": "private",
  "sub_type": "",
  "content": {
    "message_id": "6283",
    "message": [
      {
        "type": "text",
        "data": {
          "text": "OneBot is not a bot"
        }
      }
    ],
    "alt_message": "OneBot is not a bot",
    "user_id": "123456788",
    "qq.nickname": "海阔天空"
  }
}

上述例子中 将 message 、user_id等数据 ，放入 content 中， 随着你 type 不同而 对 content 中的字段而不同。

因此我们在写 实体类时，可以采用 泛型 的形式对 json 进行轻松的反序列化，同时也增强了语言的可读性。

规范化 `get_xxx_info`、`get_xxx_list` 动作的命名

• 状态：关闭
• 相关 PR：无

摘要

把 get_xxx_info 动作改名为 get_xxx、get_xxx_list 改名为 get_xxxs。

动机

get_xxx_info 和 get_xxx_list 是 CoolQ 时代遗留下来的命名方法，已经和新的接口的命名方式不匹配（get_version、get_latest_events 等）。

不破不立，没有必要继续沿用旧的命名方式。新的命名方式会更符合英语表达习惯，且在视觉上更简练。

具体描述

• get_self_info -> get_self
• get_user_info -> get_user
• get_friend_list -> get_friends
• get_group_info -> get_group
• get_group_list -> get_groups
• get_group_member_info -> get_group_member
• get_group_member_list -> get_group_members

局限

旧的代码需要改名。

替代方案

无。

移除事件的 `impl` 字段

摘要

移除事件的 impl 字段。

动机

由于请求头中有 X-Impl，此字段意义不大，并会在 #181 之后造成与动作请求的不对称。

具体描述

数据协议 - 事件

移除 impl 字段。

局限

无。

替代方案

无。

OneBot Web WeChat 端

• 状态：关闭
• 相关 PR：无

摘要

社群曾在 #82 讨论过 WeChat 端的实现，现在已有开源项目绕过 Web WeChat 的账号登录注册时间限制，OneBot WeChat 端已具备技术条件和可行性。

• 实现：wechaty/wechaty
• 原理：wechaty/puppet-wechat#127
  • 摘要：通过伪造 UOS 端微信的 header 进行绕过限制
  • 注意：如需安装 UOS 端微信进行实际测试，请注意其目前仅支持 UOS 专业版，但可通过 wechat-uos-makefile 项目在 Arch 系统上进行安装测试，该实现并不受系统限制。
• 源码：wechaty/puppet-wechat#129

动机

WeChat 是**大陆境内常用的 IM 软件之一，以往因为 WeChat 的风控相较 QQ 更为严格，在 Web WeChat 的账号登录受注册时间限制，开源的 Web WeChat 实现几近报废，导致 WeChat Bot 缺位，仅存在闭源收费的 PC 实现或 hook 注入实现。现已存在可行、持久的实现方式应在 OneBot 各端实现上进行补充。

具体描述

WeChat 与 OneBot 兼容规范进行的修改和描述，其 Web WeChat 端接口参考 wechaty/wechaty 所给文档及 Urinx/WeixinBot 所示接口和示例数据，OneBot 规范依据 V12 草案。

此处将 WeChat Api 中字段与 OneBot 对应，Web WeChat 端中不存在的消息段类型/事件数据字段此处不列，后续可根据其他平台（设备） WeChat 端开源实现进行扩展，而其实际消息段类型/事件数据字段也可能与此不符，因其全凭第三方文档，仍需复核。

消息段类型

消息段类型	WeChat	OneBot	备注
未知	Unknown	❌
文件	Attachment	❌
语音	Audio	record
推荐好友	Contact	contact
QQ 表情	Emoticon	此类型名称应进行去平台中心化更改，并可将 QQ 端与 WeChat 端共存类似或相同表情采用同一 id，拟定类型名「表情」
图片	Image	image
纯文本	Text	text
短视频	Video	video	此类型名称应进行去平台中心化更改，并非所有平台均存在时长限制，拟定类型名「视频」
链接	Url	❌	纯文本链接应作为新的类型，QQ 端纯文本类型可能会被解析成 xml，而 Telegram 端则亦有 Preview 预览实现，拟定类型字段名 preview = bool

图片消息

事件数据字段	WeChat	OneBot	备注
长度	length	❌
高度	hdlength	❌

语音消息

事件数据字段	WeChat	OneBot	备注
结束标记	endflag	❌	功能未知
取消标记	cancelflag	❌	功能未知
转发标记	forwardflag	❌	功能未知
语音格式	voiceformat	❌
语音长度	voicelength	❌
长度	length	❌	功能未知
bufid	bufid	❌	功能未知
客户端消息 id	clientmsgid	❌	功能未知

视频消息

事件数据字段	WeChat	OneBot	备注
长度	length	❌
高度	hdlength	❌

位置消息

WeChat 的位置消息属于纯文本消息，内容即链接 http://weixin.qq.com/cgi-bin/redirectforward?args=xxx

推荐好友

事件数据字段	WeChat	OneBot	备注
被推荐人	UserName	id
省份	Province	❌
城市	City	❌
Scene	Scene	❌	功能未知
QQ 号	QQNum	❌
内容	Content	❌	功能未知
微信号	Alias	❌
OpCode	OpCode	❌	功能未知
签名	Signature	❌
Ticket	Ticket	❌	功能未知
性别	Sex	❌
昵称	NickName	❌
AttrStatus	AttrStatus	❌	功能未知
验证标识	VerifyFlag	❌	功能未知

音乐分享

事件数据字段	WeChat	OneBot	备注
头图	thumburl	❌
音频	lowdataurl/dataurl	audio
链接	url	url
应用 ID	appid	❌

事件数据字段

消息事件

事件数据字段	WeChat	OneBot	备注
时间	CreateTime	time
接收者 ID	FromUserName	self_id
发送者 ID	ToUserName	user_id
类型	MsgType	post_type

局限

Web WeChat 端接口/事件并不完整。

替代方案

备注

因我并无对 Web WeChat 的实现进行具体研究，以及对 OneBot 的原理不甚了解。这导致可能出现一些问题，欢迎讨论。

添加 get_group_self_authority 动作

• 状态：关闭
• 相关 PR：无

摘要

此动作用于判断自身在指定群组的权限。

动机

用于判断自身是否为某个群组的管理员。

具体描述

请求参数：

字段名	数据类型	说明
group_id	string	群 ID

响应数据：

字段名	数据类型	说明
has_admin	bool	是否存在“管理员”身份组
is_admin	bool	自身是否为管理员

局限

替代方案

`<impl>` 允许使用短横线并采用点号分割不同部分

摘要

形如 walle-q.v1、go-cqhttp.v2 等。

动机

名字里面应该允许短横线。

点号分割不同部分可以允许实现采用版本号来区分扩展 API 版本，或者方便兼容实现声明自己的兼容性（以它所兼容的 impl 作为前缀如 go-cqhttp.v2.compatible-impl。

具体描述

将 <platform> 和 <impl> 的格式描述移到术语表的“机器人平台”和“OneBot 实现”标题下。

将 <platform> 格式要求改为 [a-z][\-a-z0-9]*，将 <impl> 格式要求改为 [a-z][\-a-z0-9]*(\.[\-a-z0-9]+)*。

去除扩展规则中对字段前缀的建议，改由实现自行规定前缀或不使用前缀。

局限

无。

替代方案

无。

`upload_file_fragmented` 分片上传文件接口传输阶段移除 `size` 参数

摘要

移除 upload_file_fragmented 传输阶段 size 参数。

动机

因为无论是 JSON 还是 MsgPack 编码方式，都能直接从 data 字段获得数据长度。

具体描述

局限

无。

替代方案

无。

将 MessagePack 编码方式改为可选

• 状态：接收
• 相关 PR：#152

摘要

将 MessagePack 编码方式改为可选。

相关讨论：

• #129

动机

MessagePack 编码方式是跟随 upload_file 动作引入的，为了减少 base64 编码文件内容的计算和传输开销，但现在发现两个问题：

• 同时支持 MessagePack 和 JSON 对某些语言的 OneBot 实现（和 LibOneBot）来说可能不太简单
• 实现可能并不打算实现 upload_file 等文件相关动作，而其它动作没有必要使用 MessagePack 编码方式

具体描述

将标准中“OneBotRPC - 通信方式”部分的 MessagePack 编码方式定义为可选支持。

具体来说，

• 对于 HTTP 通信方式，Content-Type 为 application/msgpack 时可以返回 415 Unsupported Media Type
• 对于 HTTP Webhook 通信方式，Content-Type 为 application/msgpack 时可以输出表示不支持的错误日志
• 对于正向 WebSocket 和反向 WebSocket 通信方式，收到 binary 类型的 WebSocket 消息时，以 JSON 和 UTF-8 编码返回 10001 Bad Request 返回码

OneBot SDK 或 OneBot 应用可以通过使用 MessagePack 编码请求 get_status 动作来探测 OneBot 实现是否支持 MessagePack。

局限

无。

替代方案

无。

允许在条件不允许时不完整实现所有 OneBot Connect 通信方式

摘要

允许 OneBot 实现在条件不允许时不完整实现所有 OneBot Connect 通信方式。

动机

在浏览器、Deno、PHP 等场景下，可能无法较为方便地（或甚至完全无法）实现所有 OneBot Connect 的通信方式，即 HTTP、HTTP Webhook、正向 WebSocket、反向 WebSocket。

虽然一般我们希望一个实现支持所有通信方式，但对于确实没有办法的情况，应仍然认可其为一个 OneBot 实现。

具体描述

OneBot Connect - 概述 - 对 OneBot 实现的要求

把对 OneBot 实现的要求改为“除非语言或运行环境不允许，否则应实现所有的通信方式，当确实有客观限制时应实现尽可能多的通信方式”。

局限

无。

替代方案

无。

OneBot Connect Webhook 和反向 WS 在不可控制 Header 的实现端处理方式

摘要

OneBot Connect Webhook 和反向 WS 对于 Header 变更为可选。

动机

在浏览器端发起 WebSocket 目前还无法自定义 Header，所以在开发纯浏览器的实现或者调试端时，无法构建自定义的 Header发起请求。

具体描述

比如将 Header 改为可选、采用 GET 请求参数可选的方式。

局限

如果采用 GET 传参的话，可能实现端需要改动，且在标准中规定 Header 和 GET 参数对应的名称。

新增 `status_update` 元事件

摘要

新增 status_update 状态更新元事件，用于通知应用端机器人账号或 OneBot 实现的状态变化。

初步讨论内容见 #191。

动机

应用端需要一种比较好的方式知道当前机器人账号是否在线，轮询 get_status 接口实时性较弱。

具体描述

元接口 - 元事件

• 移动“建议 HTTP 通信方式忽略该类事件。”到开头，使适用于所有元事件，并明确表述为“get_latest_events 应该忽略所有元事件”

• 新增“meta.status_update 状态更新”事件，事件字段同 #181 定义的 get_status 响应数据：

  {
      "good": true,
      "bots": [
          {
              "self": {
                  "platform": "qq",
                  "user_id": "1234567"
              },
              "online": true,
              "qq.status": "信号弱"
          },
          {
              "self": {
                  "platform": "tg",
                  "user_id": "2345678"
              },
              "online": true
          }
      ]
  }

  • 正向和反向 WebSocket 通信方式，连接建立后应在适当时机（如所有机器人账号登录完成后）尽快发送所有机器人账号的状态，之后只在有变化时发送有变化的机器人状态，如果是 good 或其它根级别扩展字段变化，bots 字段可为空
  • HTTP Webhook 通信方式应在实现启动后的适当时机尽快发送，当推送失败时，实现可以选择重试直到成功

• meta.heartbeat 事件移除 status 字段

局限

无

替代方案

无

修改 OneBotRPC 名称为 OneBot Connect

• 状态：接收
• 相关 PR：#185

摘要

修改 OneBotRPC 名称为 OneBot Connect。

动机

有人指出 HTTP webhook 通信方式不应称做“RPC”。之所以把 webhook 归为 OneBotRPC 是为了统一规范四种通信方式上传输的数据协议。为了不必要的误会，可以把“OneBotRPC”改名为“OneBot Connect”，可简称为“OBC”。

具体描述

把标准文档中的“OneBotRPC”字样替换为“OneBot Connect”，并在术语表中声明其官方简称为“OBC”。

局限

无。

替代方案

无。

移除单级群组接口中的 kick、ban、admin 相关接口

摘要

移除单级群组接口中的 kick、ban、admin 相关接口。

动机

这些接口属于权限组相关功能，在不同 IM 平台可能有非常不同的管理方式，因此目前计划不在 OneBot 12 引入权限组相关接口，待经过一段时间发展，再总结这部分接口。

具体描述

删除“接口定义 - 单级群组接口 - 群动作”中的 kick_group_member ban_group_member unban_group_member set_group_admin unset_group_admin 和“接口定义 - 单级群组接口 - 群通知事件”中的 notice.group_member_ban notice.group_member_unban notice.group_admin_set notice.group_admin_unset。

局限

暂时缺少权限组管理相关的标准接口定义。

替代方案

无。

添加 `get_message` 动作

• 状态：草稿
• 相关 PR：#167

摘要

添加消息动作 get_message 接受 message_id: String 参数，若存在返回对应的 MessageEvent

动机

缺少该动作将无法根据 MessageSegment 中的 reply 回复中的 message_id 获得对应 MessageEvent

具体描述

请求参数：

字段名	数据类型	说明
message_id	string	消息 ID

响应数据：同 MessageEvent

局限

无

替代方案

无

重命名用户类的 `nickname` 字段为 `user_name`，并新增 `user_displayname`、`user_remark`

摘要

重命名用户类的 nickname 字段为 user_name，并新增 user_displayname 和 user_remark 字段。

user_name 表示用户名/姓名/昵称；user_displayname 表示用户自己设置的“显示名称”（Slack 等平台）或用户在群里设置的“我在本群的昵称”（微信、QQ 等）；user_remark 表示机器人账号对该用户的备注名称。

动机

目前 nickname 字段仍保留了浓浓的 QQ 味，命名也和 group_name 等不一致。

具体描述

具体地，给 get_user_info get_group_member_info get_guild_member_info 动作的响应删除 nickname 字段，新增 user_name user_displayname user_remark 字段，描述如下：

• user_name：用户名称/姓名/昵称
• user_displayname：用户设置的显示名称，单用户动作应返回账号的显示名，群组动作应优先返回用户在群组内的显示名，若没有/不支持则返回账号的显示名
• user_remark：机器人账号对该用户的备注名称

局限

无。

替代方案

采用扩展字段。

增加用于定时任务的元事件

• 状态：关闭
• 相关 PR：无

摘要

可以使得在每一天的某个时刻，向 OneBot 应用端派发指定任务。

动机

让 OneBot 实现端定时派发任务成为可能。

具体描述

事件字段

字段名	数据类型	说明
task	string	任务名称

可以要求 OneBot 实现端不一定实现此事件

局限

替代方案

分片上传文件 sha256 请求字段移至结束阶段

• 状态：接收
• 相关 PR：#183

摘要

文件动作 upload_file_fragmented 分片上传文件的 sha256 请求字段从 prepare 准备阶段移动到 finish 结束阶段更为合理。

动机

sha256 需要完整的文件数据才可以计算得出，如果在结束阶段再提供，可以在一次读取中完成计算、发送，如果在准备阶段提供会造成应用端需要完整读取两次文件。

该改动对实现端的验证 sha256 无影响。

具体描述

在 upload_file_fragmented 动作中，移除准备阶段请求参数的 sha256 字段，给结束阶段请求参数新增 sha256 字段，字段含义不变。

局限

无。

替代方案

无。