zhamao/go-cqhttp-adapter-plugin

1.1.1 2024-10-01 15:04 UTC

Requires

• php: ~8.0 || ~8.1 || ~8.2 || ~8.3

Requires (Dev)

• zhamao/framework: dev-main

AGPL-3.0

README

炸毛框架用于接入 go-cqhttp（OneBot 11）的适配器插件。

功能

该插件将 gocq 的反向 WebSocket 接入信息全部转换为 OneBot 12 标准，安装该插件后几乎无需修改任何代码即可接入。

如果你想在其他项目上使用，也可以单独使用内部的 Converter 相关类进行转换。

安装

# Composer 安装稳定版
composer require zhamao/go-cqhttp-adapter-plugin

# GitHub 安装 Nightly 版
./zhamao plugin:install https://github.com/zhamao-robot/go-cqhttp-adapter-plugin.git

转换注意事项

由于 OneBot 11 和 OneBot 12 有较多差异，而这些差异也导致两者不能无损相互转换。 例如 OneBot 11 中未规定要求文件分片上传和下载的动作，那么在使用本插件时也无法使用这些动作。

由于 OneBot 11 的实现较多，而且和 OneBot 11 本身相差较大，该插件也时重点针对 go-cqhttp 进行适配转换，这也是插件不叫 onebot-11-adapter 的原因。

本插件下方列举的事件转换规则仅为自身的一些转换细节处理方案，不代表 OneBot 11 和 OneBot 12 的事件定义。 但是本插件的转换规则也是 OneBot 11 和 OneBot 12 事件定义的一个参考，如果你想了解 OneBot 11 和 12 的差异，也可以阅读下方的转换规则。

事件转换规则（11 转 12）

下面是 post_type 转换规则：

• 字段名 post_type 转换为 type。
• 如果 post_type 值为 meta_event，转换为 meta。
• 如果 post_type 值为 message_sent，转换为 message。

下面是 XXX_type 转换规则：

• 如果 post_type 为 message 或 message_sent，将字段名 message_type 转换为 detail_type。
• 如果 post_type 为 meta_event，将字段名 meta_event_type 转换为 detail_type。
• 如果 post_type 为 notice，将字段名 notice_type 转换为 detail_type。
• 如果 post_type 为 request，将字段名 request_type 转换为 detail_type。

下面是 self_id 转换规则：

• 如果存在 self_id 字段，将该字段删除，替换为 "self" => ["user_id" => $user_id, "platform" => "qq"]，其中 $user_id 的值等于 self_id 的字符串值。
• 如果不存在 self_id 字段，将该字段删除，替换为和上方一样的格式，$user_id 的值等于该连接请求握手时 X-Self-ID 的值。

下面是 user_id、group_id、guild_id、channel_id、message_id 转换规则：

• 以上列举的值都取字符串值，即转换为字符串。

下面是其他字段的一些转换规则：

• 如果 post_type 为 message 或 message_sent，则将 raw_message 转换为 alt_message。
• go-cqhttp 的消息事件中默认带有 sender，将其字段名转换为 qq.sender，内部参数不变。
• go-cqhttp 未提供事件的 ID，因此该插件会自动生成一个随机的 UUID 作为事件 ID。

下面是消息事件（message）的一些转换规则：

• message 字段如果为字符串，会先将 CQ 码无损转换为 OneBot 11 的等价消息段，然后再将消息段转换为 OneBot 12 标准的消息段。
• CQ 码的转换基本按照 OneBot 11 的规范进行，但是由于 OneBot 11 的规范不完整，因此可能会有一些不同。例如，CQ 码在解码参数时未考虑参数内带有等号，该适配器仅会获取第一个等号前的参数，后面的等号会被当作值的一部分。
• 转换为 OneBot 12 的消息段时，仅保留 type 和 data，如果存在其他字段，将丢弃。
• at 类型，如果参数 qq 为 all，则类型转换为 mention_all，否则类型转换为 mention 同时 qq 字段名转换为 user_id。
• video、image、record 类型，将参数 file 转换为 file_id。
• record 类型转换为 voice。
• location 类型，将参数 lat 转换为 latitude，将参数 lon 转换为 longitude。
• reply 类型，将 id 转换为 message_id，如果存在参数 qq，将 qq 转换为 user_id。
• 其他类型，类型字段名称统一添加前缀 qq.，例如 forward 转换为 qq.forward。

下面是通知事件（notice）的一些转换规则：

• friend_recall 转换后，仅保留 message_id 和 user_id 字段。
• friend_add 转换后，仅保留 user_id 字段。
• group_increase 转换后，如果 sub_type 值为 approve 或空，则转换为 join；如果为 invite 则不变，如果是其他，则加上前缀 qq.。
• group_increase 转换后，仅保留 sub_type、group_id、user_id``operator_id 且转换为字符串值。
• group_decrease 转换后，如果 sub_type 值为 kick 或 kick_me，则转换为 kick；如果为 leave 则不变，如果是其他，则加上前缀 qq.。如果想判断是否为 kick_me，可以使用判断 user_id 和 operator_id 是否相同。
• group_decrease 转换后，仅保留 sub_type、group_id、user_id``operator_id 且转换为字符串值。
• group_recall 转换后，如果 user_id 与 operator_id 相同，则 sub_type 值设定为 recall，否则为 delete（分别代表自己撤回和被撤回）。
• group_recall 转换后，仅保留 message_id、group_id、user_id、operator_id 且转换为字符串值。
• 其他通知类事件加前缀，其他字段除 post_type、notice_type、sub_type、request_type、meta_event_type、time 和一系列 xxx_id 外，均保留，并加上 qq. 前缀，值不变。

下面是请求事件（request）的一些转换规则：

• 由于 OneBot 12 标准未规定任何 request 事件，故所有 request 事件均将 request_type 加上 qq. 前缀，并转换名称为 detail_type。
• 其他字段除 post_type、notice_type、sub_type、request_type、meta_event_type、time 和一系列 xxx_id 外，均保留，并加上 qq. 前缀，值不变。

下面是元事件（meta）的一些转换规则：

• meta_event_type 转换为 detail_type。
• 目前 go-cqhttp 仅有两种元事件，其中 meta_event_type 分别为 lifecycle 和 heartbeat。
• 如果 meta_event_type 为 lifecycle，sub_type 为 connect，则将 detail_type 转换为 connect。
• 如果按照上面的规则转换为 connect，其中 OneBot 12 转换后的 version 内容为：['impl' => 'go-cqhttp', 'version' => $user_agent, 'onebot_version' => '12']。其中 $user_agent 为与 gocq 建立连接时对端发送过来的 User-Agent 值。
• 如果 meta_event_type 为 heartbeat，则参数仅保留 interval，类型名称不变。
• 其他 meta_evet_type，不添加前缀，假设实现端有一个 xxx 元事件，则此处转换为 detail_type 依旧是 xxx。
• 其他元事件的其他字段，除 post_type、notice_type、sub_type、request_type、meta_event_type、time 和一系列 xxx_id 外，均保留，并加上 qq. 前缀，值不变。

动作转换规则（12 转 11）

• send_message 动作根据参数 detail_type 的值，转换为对应的 send_xxx_msg 动作，但目前仅支持私聊和群组类型。
• 如果 detail_type 为 group，将保留 group_id 参数，并将 OneBot 12 消息段转换为 OneBot 11 消息段发送。
• 如果 detail_type 为 private，将保留 user_id 参数，如果传入的 Action 对象存在 group_id 参数也将会保留，然后将 OneBot 12 消息段转换为 OneBot 11 消息段发送。
• delete_message 动作名称变更为 delete_msg，保留 message_id 参数。
• get_self_info 动作名称变更为 get_login_info。
• get_user_info 动作名称变更为 get_stranger_info，保留 user_id 字段。
• get_friend_list、get_group_info、get_group_list、get_group_member_info、get_group_member_list、set_group_name 动作名称和参数均不变。
• leave_group 动作名称变更为 set_group_leave，参数不变。
• upload_file 动作名称变更为 download_file，并且仅支持 URL 方式上传文件。
• get_status 名称和参数（好像也没有请求参数，不管了）均保持不变。
• get_version 动作名称变更为 get_version_info。
• 其他动作如果开头使用 qq. 前缀，则将其前缀去除，参数保持不变。
• echo 回响字段保持不变。

动作响应转换规则（11 转 12）

动作响应的转换在插件内部对动作请求做了缓存，通过 echo 字段进行匹配，从而确定响应对应的动作请求。

• status、retcode、echo 字段保持不变。
• msg 字段如果存在则转换为 message 字段。
• 如果请求的动作是 send_xxx_msg，则响应中的 message_id 字段保持不变。
• 如果请求动作是 get_stranger_info，响应中的 user_id 保持不变，nickname 转换为 user_name，同时也将 user_displayname 设置为 user_name 相同的值，user_remark 设置为空。
• 如果请求动作是 get_login_info，响应中的 user_id 保持不变，nickname 转换为 user_name，同时也将 user_displayname 设置为 user_name 相同的值。
• 如果请求动作是 get_friend_list，每个用户元素的 user_id 保持不变，nickname 转换为 user_name，同时也将 user_displayname 设置为 user_name 相同的值，user_remark 设置为空。
• 如果请求动作是 get_group_info 或 get_group_list，参数保持不变。
• 如果请求动作是 get_group_member_info，现有参数转换规则同 get_stranger_info 的参数转换规则，其他参数的参数名添加前缀 qq.，值保持不变。
• 如果请求动作是 get_group_member_list，每个用户元素的参数转换规则同 get_group_member_info。
• 如果请求动作是 download_file，响应中的 file 字段转换为 file_id。
• 如果请求动作是 set_group_name、set_group_leave，参数保持不变。
• 如果请求动作是 get_status，仅保留 good 字段，OB12 的 bots 字段值为 [['impl' => 'go-cqhttp', 'version' => $user_agent, 'onebot_version' => '12']]。
• 如果请求动作是 get_version_info，app_name 转换为 impl，且 impl 值后附加 (go-cqhttp-adapter converted)，app_version 转换为 version，onebot_version 设置为 12，其他值丢弃。

其他不兼容项

转换器不支持转换以下 OneBot 12 动作到 OneBot 11 API：

• get_latest_events
• get_supported_actions
• 所有二级群组动作，例如 get_guild_info 等
• upload_file_fragmented
• get_file
• get_file_fragmented