PHPackages                             zhamao/go-cqhttp-adapter-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. zhamao/go-cqhttp-adapter-plugin

ActiveLibrary

zhamao/go-cqhttp-adapter-plugin
===============================

1.1.1(1y ago)10291AGPL-3.0PHPPHP ~8.0 || ~8.1 || ~8.2 || ~8.3

Since Mar 11Pushed 1y ago3 watchersCompare

[ Source](https://github.com/zhamao-robot/go-cqhttp-adapter-plugin)[ Packagist](https://packagist.org/packages/zhamao/go-cqhttp-adapter-plugin)[ RSS](/packages/zhamao-go-cqhttp-adapter-plugin/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (3)Used By (0)

go-cqhttp-adapter-plugin
========================

[](#go-cqhttp-adapter-plugin)

炸毛框架用于接入 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）
---------------

[](#事件转换规则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`）的一些转换规则：

go-cqhttp 的 `notice_type`OneBot 12 的 `detail_type`描述`friend_recall``private_message_delete`撤回一条私聊消息`friend_add``friend_increase`添加好友的通知事件`group_increase``group_member_increase`群成员增加`group_decrease``group_member_decrease`群成员减少`group_recall``group_message_delete`群消息撤回除上述外的其他通知事件`qq.` 前缀加上原名称- `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）
---------------

[](#动作转换规则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）
-----------------

[](#动作响应转换规则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`

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 91.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~570 days

Total

2

Last Release

585d ago

PHP version history (2 changes)1.1.0PHP ~8.0 || ~8.1 || ~8.2

1.1.1PHP ~8.0 || ~8.1 || ~8.2 || ~8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/8bbf5705e9f35b31cbba478f9fbae0b6da2211348ecd41689cd2e4230c77a3e1?d=identicon)[crazywhalecc](/maintainers/crazywhalecc)

---

Top Contributors

[![crazywhalecc](https://avatars.githubusercontent.com/u/20330940?v=4)](https://github.com/crazywhalecc "crazywhalecc (11 commits)")[![DreamMiu](https://avatars.githubusercontent.com/u/30835281?v=4)](https://github.com/DreamMiu "DreamMiu (1 commits)")

### Embed Badge

![Health badge](/badges/zhamao-go-cqhttp-adapter-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/zhamao-go-cqhttp-adapter-plugin/health.svg)](https://phpackages.com/packages/zhamao-go-cqhttp-adapter-plugin)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)