跳转至

概述

OneBot 接口定义描述了一组标准事件、动作、消息段和它们的扩展规则。

如果将 OneBotRPC 类比于 C 语言的语法,规定了用户可以怎么用,则接口定义对应 C 语言标准库和标准库扩展的命名规则,描述了用户能用什么,以及实现可以如何扩展标准库。

对 OneBot 实现的要求

事件

必须实现所有标准元事件。

如果实现了一个标准事件,则必须实现这个事件的所有标准定义字段。

如果确实有字段在机器人平台没有对应值,应该使用对应类型的空值。

动作

必须实现所有标准元动作。

如果实现了一个标准动作,则建议支持标准定义的所有参数,必须支持标准定义的所有响应字段。

既然能实现一个标准动作,说明这个动作的大部分语义是可以实现的,对于实在无法实现的参数,建议返回 10004 Unsupported Param 返回码,如果参数不重要,也可以忽略。

如果没有实现某个动作,应该返回 10002 Unsupported Action 返回码。

除了 get_latest_events 外,实现了的其它所有动作必须在 get_supported_actions 元动作的响应数据中列出。

消息段

如果实现了一个标准消息段,则建议支持标准定义的所有参数。

与动作类似,对于实在无法实现的参数,建议返回 10007 Unsupported Segment Data 返回码,如果参数不重要,也可以忽略。

如果没有实现某个要发送的消息段,应该返回 10005 Unsupported Segment 返回码。

如果由于机器人平台的限制,导致某个消息段无法发送成功,建议返回表示“部分消息发送失败”的 34xxx 返回码,如果实在难以检测到失败,也可以忽略。

如果整条消息都无法发送成功,建议返回表示“消息发送失败”的 34xxx 返回码,如果实在难以检测到失败,也可以忽略。

扩展

OneBot 实现可以对事件、动作、消息段进行扩展,一条基本的规则是必须对扩展的字段、类型、名称使用 <platform>.<impl>. 前缀(注意点号),其中 <platform> 为 OneBot 实现针对的机器人平台名称、<impl> 为 OneBot 实现名称,格式都必须是 [_a-z]+

对于元事件和元动作,建议只使用 <impl>. 前缀进行扩展;对于其它情况,建议尽可能使用 <platform>. 前缀,并与该机器人平台的其它 OneBot 实现保持语义一致。

此后具体的扩展规则中不再对前缀的表示和格式进行赘述,只称其为前缀