botuniverse / onebot Goto Github PK
View Code? Open in Web Editor NEWOneBot:统一的聊天机器人应用接口标准
Home Page: https://onebot.dev
License: MIT License
OneBot:统一的聊天机器人应用接口标准
Home Page: https://onebot.dev
License: MIT License
明确 get_latest_events
动作在不同通信方式下的响应方式以及规定部分未定义行为。
这个问题是编写 LibOB 时发现的,当 OneBot 产生一个事件时,在开发层面发现 OneBot 12 当前的标准文档中未定义一些边缘行为。
补充描述:
不同通信方式之间应该相互隔离,即,无论其它通信方式上是否成功推送事件,
get_latest_events
都应该能收到所有事件(在未超出缓冲区的情况下)。OneBot 实现应建议用户不要同时使用get_latest_events
和其它通信方式来接收事件。
修改描述:
多个并发请求同时调用
get_latest_events
是未定义行为,OneBot 实现可以做任意假设。
为:
多个并发请求同时调用
get_latest_events
的结果由 OneBot 实现定义,实现可以对后来的请求返回错误码、返回空事件列表或是对所有请求返回相同的事件列表。
get_latest_events
修改 timeout
参数说明为:
没有事件时最多等待的秒数,0 表示使用短轮询,不等待
无
无
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"
}
X-Self-ID
和 X-Platform
头self_id
、platform
字段self
字段,类型 Self
self
字段,单 bot 时可选,多 bot 时必须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 先不引入了。
首先说明我使用的语言为 .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套了一层,我觉得是没有必要的
get_latest_events
元动作是仅 HTTP 通信方式必须实现的元动作,用于轮询获取最新事件列表。本 RFC 在标准中建议该动作返回列表不包含元事件。
元事件的一种——心跳事件,会按固定间隔产生,这类事件放在 get_latest_events
返回结果里没有意义。
同摘要。
无。
无。
移除单级群组接口中的 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
。
暂时缺少权限组管理相关的标准接口定义。
无。
重命名用户类的 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
:机器人账号对该用户的备注名称无。
采用扩展字段。
如题。
id
的含义更明确一些,并且和事件对称。
如题。
无。
无。
社群曾在 #82 讨论过 WeChat 端的实现,现在已有开源项目绕过 Web WeChat 的账号登录注册时间限制,OneBot WeChat 端已具备技术条件和可行性。
header
进行绕过限制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 端开源实现进行扩展,而其实际消息段类型/事件数据字段也可能与此不符,因其全凭第三方文档,仍需复核。
消息段类型 | 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 |
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
长度 | length | ❌ | |
高度 | hdlength | ❌ |
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
结束标记 | endflag | ❌ | 功能未知 |
取消标记 | cancelflag | ❌ | 功能未知 |
转发标记 | forwardflag | ❌ | 功能未知 |
语音格式 | voiceformat | ❌ | |
语音长度 | voicelength | ❌ | |
长度 | length | ❌ | 功能未知 |
bufid | bufid | ❌ | 功能未知 |
客户端消息 id | clientmsgid | ❌ | 功能未知 |
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
长度 | length | ❌ | |
高度 | hdlength | ❌ |
WeChat 的位置消息属于纯文本消息,内容即链接 http://weixin.qq.com/cgi-bin/redirectforward?args=xxx
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
被推荐人 | UserName | id | |
省份 | Province | ❌ | |
城市 | City | ❌ | |
Scene | Scene | ❌ | 功能未知 |
QQ 号 | QQNum | ❌ | |
内容 | Content | ❌ | 功能未知 |
微信号 | Alias | ❌ | |
OpCode | OpCode | ❌ | 功能未知 |
签名 | Signature | ❌ | |
Ticket | Ticket | ❌ | 功能未知 |
性别 | Sex | ❌ | |
昵称 | NickName | ❌ | |
AttrStatus | AttrStatus | ❌ | 功能未知 |
验证标识 | VerifyFlag | ❌ | 功能未知 |
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
头图 | thumburl | ❌ | |
音频 | lowdataurl/dataurl | audio | |
链接 | url | url | |
应用 ID | appid | ❌ |
事件数据字段 | OneBot | 备注 | |
---|---|---|---|
时间 | CreateTime | time | |
接收者 ID | FromUserName | self_id | |
发送者 ID | ToUserName | user_id | |
类型 | MsgType | post_type |
Web WeChat 端接口/事件并不完整。
因我并无对 Web WeChat 的实现进行具体研究,以及对 OneBot 的原理不甚了解。这导致可能出现一些问题,欢迎讨论。
在事件、动作、消息段的扩展规则中,取消对 <platform>.
或 <impl>.
前缀的强制性要求。
相关链接:
此前强制要求所有扩展的名字都需要加聊天平台或 OneBot 实现专属的前缀,以防止不同平台、不同实现之间发生命名冲突的情况,但实际上这造成了 OneBot 实现的编写不便、用户使用也不便。
目前看来,相比潜在的不同平台、不同实现之前同一个命名含义不同的冲突,OneBot 实现的编写和使用的便捷性更为重要,在标准层面进行强制的前缀约束可能弊大于利。
本 RFC 提议删掉标准中对扩展规则的描述中,强制要求前缀的部分,改为建议使用前缀但不强制。也就是说,OneBot 实现者可以根据接口的实际情况,包括是不是潜在地适用于不同平台、是否加了前缀会不够直观等因素,来决定要不要加前缀。
相关页面中 JSON 形式的事件、动作、消息段的实例不需要调整,以体现对使用前缀的建议。
对前缀的格式要求不变,如果实现决定添加前缀,仍然应该使用 <impl>.
或 <platform>.
。
取消了强制前缀约束后,不同平台、实现可能会发生同一个名字的事件、动作、消息段、字段,具有不同的数据类型或含义的情况。但并不意味着我们任由命名冲突发生,而是应由人们根据情况进行冲突避免和解决。具体来说,解决命名冲突有很多办法:
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 仍然可以提供这样的区分方式,这和解除强制性前缀约束不冲突。
为所有事件增加 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 实现平台事件发生时间(时间戳) |
添加对于频道的支持
相关链接: 关于频道(Guild)相关事件以及 API #131
目前协议内仅存在单用户接口与单级群组接口,对于频道以及类似的两级群组缺乏必要的支持。
本 RFC 提议向现有协议增加两级群组相关接口,以扩大 OneBot 协议的适用范围。
两级群组需要增加以下接口
字段名 | 数据类型 | 说明 |
---|---|---|
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 |
字段名 | 数据类型 | 说明 |
---|---|---|
detail_type | string | 必须为 guild_member_increase |
sub_type | string | 必须为 join、invite、空字符串或扩展的子类型 |
guild_id | string | 群组 ID |
user_id | string | 用户 ID |
operator_id | string | 操作者 ID |
字段名 | 数据类型 | 说明 |
---|---|---|
detail_type | string | 必须为 guild_member_decrease |
sub_type | string | 必须为 leave、kick、空字符串或扩展的子类型 |
guild_id | string | 群组 ID |
user_id | string | 用户 ID |
operator_id | string | 操作者 ID |
字段名 | 数据类型 | 说明 |
---|---|---|
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 |
字段名 | 数据类型 | 说明 |
---|---|---|
detail_type | string | 必须为 channel_create |
guild_id | string | 群组 ID |
channel_id | string | 频道 ID |
operator_id | string | 操作者 ID |
字段名 | 数据类型 | 说明 |
---|---|---|
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 字段
请求参数
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
响应数据
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
guild_name | string | - | 群组名称 |
无请求参数,响应数据参见 get_guild_info
请求参数
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
channel_id | string | - | 频道 ID |
响应数据
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
channel_id | string | - | 频道 ID |
channel_name | string | - | 频道名称 |
请求参数
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
响应数据参见 get_channel_info
请求参数
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
user_id | string | - | 用户 ID |
响应数据
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
user_id | string | - | 用户 ID |
nickname | string | - | 用户名称/昵称 |
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
响应数据参见 get_guild_member_info
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
guild_name | string | - | 新群组名称 |
无响应数据
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
channel_id | string | - | 频道 ID |
channel_name | string | - | 新频道名称 |
无响应数据
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
guild_id | string | - | 群组 ID |
无响应数据
可以将两级群组减并为单级群组接口的扩展实现:
使用单级群组增加 guild.id 的形式代替 guild_id, 原 group_id 记录 channel_id。
但是该方案缺少直接的 Guild 相关接口,亦无法体现 Guild-Channel 的从属关系。
形如 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]+)*
。
去除扩展规则中对字段前缀的建议,改由实现自行规定前缀或不使用前缀。
无。
无。
移除事件的 impl
字段。
由于请求头中有 X-Impl
,此字段意义不大,并会在 #181 之后造成与动作请求的不对称。
移除 impl
字段。
无。
无。
把 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
旧的代码需要改名。
无。
将事件的 time
字段类型修改为 float64
,单位为秒。
在一些情况下,事件提供的时间精度不够准确。特别是在高并发环境下,一秒钟内有多条消息时间并发的可能性非常高。在这种情况下,就需要使用精确度更高的时间戳进行描述。
如果有的聊天平台只实现了秒级别精度的时间戳,应将小数部分设为 0。
无。
使用毫秒作为该字段单位。
文件动作 upload_file_fragmented 分片上传文件的 sha256 请求字段从 prepare 准备阶段移动到 finish 结束阶段更为合理。
sha256 需要完整的文件数据才可以计算得出,如果在结束阶段再提供,可以在一次读取中完成计算、发送,如果在准备阶段提供会造成应用端需要完整读取两次文件。
该改动对实现端的验证 sha256 无影响。
在 upload_file_fragmented
动作中,移除准备阶段请求参数的 sha256
字段,给结束阶段请求参数新增 sha256
字段,字段含义不变。
无。
无。
将 MessagePack 编码方式改为可选。
相关讨论:
MessagePack 编码方式是跟随 upload_file
动作引入的,为了减少 base64 编码文件内容的计算和传输开销,但现在发现两个问题:
upload_file
等文件相关动作,而其它动作没有必要使用 MessagePack 编码方式将标准中“OneBotRPC - 通信方式”部分的 MessagePack 编码方式定义为可选支持。
具体来说,
Content-Type
为 application/msgpack
时可以返回 415 Unsupported Media Type
Content-Type
为 application/msgpack
时可以输出表示不支持的错误日志10001 Bad Request
返回码OneBot SDK 或 OneBot 应用可以通过使用 MessagePack 编码请求 get_status
动作来探测 OneBot 实现是否支持 MessagePack。
无。
无。
两级群组接口中,添加频道增加/减少成员事件,添加获取频道成员信息、获取频道成员列表、退出频道动作。
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
,用于限制只获取机器人账号已加入的频道列表无。
无。
新增 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
}
]
}
good
或其它根级别扩展字段变化,bots
字段可为空meta.heartbeat
事件移除 status
字段
无
无
10102 Unknown Self
响应码,表示“不存在的机器人账号”,备注“动作请求指定的机器人账号不存在”self
,实现可直接忽略,也可按下面逻辑处理self
,行为由 OneBot 实现定义,可以返回 10101 Who Am I
self
不存在,返回 10102 Unknown Self
self
不存在,返回 10102 Unknown Self
无
无
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 进行轻松的反序列化,同时也增强了语言的可读性。
修改原有鉴权方式。
在浏览器端发起 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 字段。
ban_group_member 新增 until_time 字段,以指定在禁言成员后多久时间内不允许其再次发言。
QQ 最长能指定禁言 30 天,Telegram 最长能指定禁言永久。
字段名 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
group_id |
string | - | 群 ID |
user_id |
string | - | 用户 ID |
until_time |
int64 | - | 用户禁止发言的时间,单位秒。在 Telegram,如果用户被禁止发言超过366天或从当前时间起少于 30 秒,则视为永久禁止发言。在 QQ,最长可禁止发言 30 天。 |
此动作用于判断自身在指定群组的权限。
用于判断自身是否为某个群组的管理员。
请求参数:
字段名 | 数据类型 | 说明 |
---|---|---|
group_id | string | 群 ID |
响应数据:
字段名 | 数据类型 | 说明 |
---|---|---|
has_admin | bool | 是否存在“管理员”身份组 |
is_admin | bool | 自身是否为管理员 |
如题。
因为元动作现在的定义只针对实现,不针对机器人平台。
get_version
动作响应数据中:
platform
impl
格式描述指向术语表无。
无。
添加消息动作 get_message 接受 message_id: String 参数,若存在返回对应的 MessageEvent
缺少该动作将无法根据 MessageSegment 中的 reply 回复中的 message_id 获得对应 MessageEvent
请求参数:
字段名 | 数据类型 | 说明 |
---|---|---|
message_id | string | 消息 ID |
响应数据:同 MessageEvent
无
无
OneBot Connect Webhook 和反向 WS 对于 Header 变更为可选。
在浏览器端发起 WebSocket 目前还无法自定义 Header,所以在开发纯浏览器的实现或者调试端时,无法构建自定义的 Header发起请求。
比如将 Header 改为可选、采用 GET 请求参数可选的方式。
如果采用 GET 传参的话,可能实现端需要改动,且在标准中规定 Header 和 GET 参数对应的名称。
允许 OneBot 实现在条件不允许时不完整实现所有 OneBot Connect 通信方式。
在浏览器、Deno、PHP 等场景下,可能无法较为方便地(或甚至完全无法)实现所有 OneBot Connect 的通信方式,即 HTTP、HTTP Webhook、正向 WebSocket、反向 WebSocket。
虽然一般我们希望一个实现支持所有通信方式,但对于确实没有办法的情况,应仍然认可其为一个 OneBot 实现。
把对 OneBot 实现的要求改为“除非语言或运行环境不允许,否则应实现所有的通信方式,当确实有客观限制时应实现尽可能多的通信方式”。
无。
无。
可以使得在每一天的某个时刻,向 OneBot 应用端派发指定任务。
让 OneBot 实现端定时派发任务成为可能。
字段名 | 数据类型 | 说明 |
---|---|---|
task | string | 任务名称 |
可以要求 OneBot 实现端不一定实现此事件
在 Authorization
头之外,允许通过 /?access_token=xxx
来传递 access_token
。
部分场景下,应用端或 OneBot 实现无法操作 HTTP 请求头,例如:
“鉴权”部分,实现应优先检查 Authorization
头,如果存在,则依照原来的标准鉴权,如果不存在,则尝试获取 access_token
URL query 参数,以此鉴权。
“请求头”部分,若无法操作请求头,实现可以通过 access_token
URL query 参数来传递 token,应用端应优先检查 Authorization
头,如果存在,则依照原来的标准鉴权,如果不存在,则尝试获取 access_token
URL query 参数,以此鉴权。
反向 WebSocket 文档会指向此处,故不用修改。
无。
无。
修改 OneBotRPC 名称为 OneBot Connect。
有人指出 HTTP webhook 通信方式不应称做“RPC”。之所以把 webhook 归为 OneBotRPC 是为了统一规范四种通信方式上传输的数据协议。为了不必要的误会,可以把“OneBotRPC”改名为“OneBot Connect”,可简称为“OBC”。
把标准文档中的“OneBotRPC”字样替换为“OneBot Connect”,并在术语表中声明其官方简称为“OBC”。
无。
无。
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。
“请求头”部分重写如下:
在请求连接时,应设置以下请求头:
User-Agent
:具体的 UA 值可以由实现自行定义
- 例如
User-Agent: OneBot/12 (qq) Go-LibOneBot/1.0.0
Sec-WebSocket-Protocol: <onebot_version>.<impl>
:<onebot_version>
应为实现的 OneBot 标准版本(如12
),<impl>
应为实现的名称,格式见术语表
无。
无。
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.