🦊 适用于早柚核心的OneBot适配器 (OneBotUID)

这是一个适用于 早柚核心 (gsuid_core) 的 OneBot v11 适配器插件。它把实现了 OneBot v11 的协议端（NapCat / LLOneBot / Lagrange 等）接进早柚核心，把 QQ 消息转成早柚协议交给核心处理，再把核心下发的消息转成 OneBot 接口调用发出去。

✨ 主要功能

• 🔌 两种连接方式: WS客户端（插件去连协议端的 WS 服务端）与 WS服务器（插件自己开 WS 服务端等协议端连进来）都支持，每条连接单独选。
• 🔀 多协议端: 连接列表 里加几条就是几个协议端，一个插件实例能同时挂多个 QQ 号。
• 📝 连接列表配置: 每条连接独立配置地址、端口、Token、连接标识，可单独启用或禁用。
• ♻️ 热更新: 改完配置不用重启，插件每 2 秒比对一次列表，只重启变更的那一条。
• 🛡️ 双向鉴权: WS客户端 发 Authorization: Bearer；WS服务器 同时认 Bearer 头和 ?access_token= 查询参数。
• 📡 元事件上报: 支持向核心上报进群、退群、戳一戳三类标准 meta 事件。
• ↩️ 撤回回执: 支持 wait_recall 场景，发送后回传 OneBot 消息 ID。
• 🛠️ 控制消息: 支持核心下发主动撤回与群禁言/解禁控制。
• 🖼️ 图片外显: 可配置发图时的 summary，多个文案用英文逗号分隔，发送时随机选一个。
• 🔄 断线重连: 自动检测连接状态并重连，可设间隔与次数上限，也能用指令手动触发。
• 📊 状态监控: 内置状态指令，只看收到指令的那条连接，含连接方式、在线时长与最近错误。
• 🧩 原生下发链路: 复用核心的发送队列、日志回显、撤回回执，插件不重复实现一套。
• 🧪 接口直调: 其他插件 import call_bot_api() 就能调任意 OneBot 接口，走这条已有的 WS 连接，不用另配 HTTP。

🛠️ 安装说明

1. 把插件目录放进早柚核心的 gsuid_core/gsuid_core/plugins/ 下，目录名保持 OneBotUID：

   cd gsuid_core/gsuid_core/plugins

   git clone https://github.com/xiowo/OneBotUID.git OneBotUID

2. 重启核心，插件会在 on_core_start 阶段自动开始连接。

3. 网页控制台 → 插件配置 → OneBotUID，按需填写 连接列表。

📝 配置指南

控制台的插件配置里分两个页签：OneBotUID 放连接相关参数，自定义信息 放只影响消息外观的发送文案。每个页签内部再按分区标题归类。连接列表 里每条记录对应一个协议端，可以随时新增 / 删除 / 单独禁用。

页签：OneBotUID

〔运行控制〕

配置项	说明	默认值
启用适配器	总开关，关掉后所有连接都不启动	true
重连间隔	断线后等几秒重连	5
最大重连次数	最大尝试重连次数，0 为无限重连	0

〔消息处理〕

配置项	说明	默认值
回查引用正文	收到引用回复时调 get_msg 取被引用内容，关掉省一次调用	true

〔WS客户端连接〕

配置项	说明	默认值
连接列表	插件主动去连协议端的 WS 服务端，每条记录对应一个协议端，见下表	一条默认记录

〔WS服务器连接〕

配置项	说明	默认值
连接列表	插件自己开 WS 服务端，等协议端连进来，见下表	空

页签：自定义信息

只影响机器人发出去的消息长什么样，与连接参数无关。三项都留空时使用机器人自身信息与默认文案。

〔图片消息〕

配置项	说明	默认值
图片外显	发图时的外显文案，多个请用英文逗号分隔，发送时随机选择一个	空

〔合并转发〕

配置项	说明	默认值
合并转发 QQ	合并转发节点上显示的发件人 QQ，留空则用机器人自身	空
合并转发昵称	合并转发节点上显示的发件人昵称，留空则用机器人自身	空

连接列表（每条记录）

两种连接方式各自一组列表，加在哪一组就是哪种方式，不再有「连接方式」下拉框；要改方式就删掉一条、在另一组里重新加一条。

WS客户端连接 的每条记录：

配置项	说明	默认值
名称	列表里显示的名字，留空用连接标识	空
启用连接	单独开关，关掉只停这一条	true
协议端地址	插件主动去连的地址，例如 ws://127.0.0.1:3001	ws://127.0.0.1:3001
Access Token	发 Authorization: Bearer 头用，留空不鉴权	空
连接标识	这条连接在核心里的名字（WS_BOT_ID）。默认 OneBot，一般不用改	OneBot
平台标识	上报消息时带的 bot_id，插件与数据库按它区分平台	onebot
忽略自身消息	协议端会上报机器人自己发的消息，开启后不再转发	true

WS服务器连接 的每条记录：

配置项	说明	默认值
名称	列表里显示的名字，留空用连接标识	空
启用连接	单独开关，关掉只停这一条	true
监听地址	监听哪个网卡，0.0.0.0 表示全部	0.0.0.0
监听端口	协议端连这个端口，一个端口可以同时接多个协议端	3002
Access Token	校验协议端带来的 token，留空不鉴权	空
连接标识	这条连接在核心里的名字（WS_BOT_ID）。默认 OneBot，一般不用改	OneBot
平台标识	上报消息时带的 bot_id，插件与数据库按它区分平台	onebot
忽略自身消息	协议端会上报机器人自己发的消息，开启后不再转发	true

📜 指令列表

命令前缀为 onebot，仅主人可用。

指令	描述	权限要求
onebot状态	查看当前连接的状态、连接方式、连接标识、平台标识、已接入协议端数、在线时长、连续失败次数、最近错误	主人
onebot重连	断开并重连当前连接；WS服务器 为断开协议端、等它重新接入	主人
onebot调接口	手动调一次 OneBot 接口，用来验证连通性，见下	主人

onebot调接口 用法：

onebot调接口 <接口名><JSON参数>
onebot调接口 get_group_member_list{"group_id": 7777}
onebot调接口 get_group_info{"group_id": 7777}
onebot调接口 get_login_info

「当前连接」指指令到达的那条连接，不会影响同核心下的其他连接。

🧪 给其他插件调 OneBot 接口

api.py 对外提供 call_bot_api()：用适配器已建立的 WS 连接去调协议端，再把结果交回来。不用另外配 OneBot 的 HTTP 地址，也不用新开连接。

from gsuid_core.sv import SV
from gsuid_core.bot import Bot
from gsuid_core.models import Event

sv = SV("MyPlugin", pm=0, area="ALL")


@sv.on_command("群成员")
async def group_members(bot: Bot, ev: Event) -> None:
    # 延迟 import：核心启动早期 OneBotUID 可能还没加载完
    from gsuid_core.plugins.OneBotUID.api import OneBotApiError, call_bot_api

    try:
        data = await call_bot_api(
            "get_group_member_list",
            {"group_id": ev.group_id},
            self_id=ev.bot_self_id,
        )
    except OneBotApiError as exc:
        await bot.send(f"没拿到群成员列表：{exc}")
        return
    await bot.send(f"群里有 {data.get('member_count')} 人")

参数	说明
action	OneBot v11 接口名，例如 get_group_info、set_group_card、get_msg
params	接口参数，原样传给协议端
self_id	目标机器人 QQ，一般传 ev.bot_self_id；只有一条连接时可留空
timeout	等协议端响应的秒数，默认 30

调通返回响应里的 data（dict）。以下情况抛 OneBotApiError：

• 按 self_id 找不到对应的连接
• 连接不可用或等满 timeout 没回包
• 协议端返回 retcode 不是 0 / 1
• 响应里没有 data

异常带 action 和 response（完整响应，含 retcode），需要区分「接口报错」和「没连上」时读这两个字段。

🔌 协议端怎么配

以 NapCat 为例，在 WebUI 的「网络配置」里按插件选的连接方式加一条。

WS客户端（插件去连）——协议端加「WebSocket 服务器」

配置项	说明
端口	3001（按需修改，与插件里填的一致）
消息格式	array（必须是 array，CQ 字符串只能降级成纯文本）
Token	可选，填了就要在插件配置里填一样的

插件默认连 ws://127.0.0.1:3001。

WS服务器（插件监听）——协议端加「WebSocket 客户端」

配置项	说明
URL	ws://<核心所在机器IP>:3002（端口对齐 监听端口）
消息格式	同样是 array
Token	填了就在插件里填一样的，协议端会放在 Authorization: Bearer 头里；也有协议端只支持拼查询参数，插件同样认 ?access_token=xxx

⚠️ 注意: 如果协议端运行在 Docker 中，请勿将连接地址设置为 127.0.0.1，请使用宿主机 IP（如 172.17.0.1）或 Docker Network 容器名。核心在 Docker 里时，监听地址 要留 0.0.0.0 并把端口映射出去，否则容器外连不进来。

❓ 常见问题 (FAQ)

Q1: 核心日志一直提示连接失败？

A:

1. 确认协议端的 WebSocket 服务器真的开了、端口对得上。
2. 协议端在 Docker 里时 127.0.0.1 指的是容器自己，换成宿主机 IP 或容器名。
3. 这个阶段插件还没注册到核心，所以核心侧不会出现这条连接；onebot状态 里会显示未连接和最近一次的错误原因。

Q2: WS服务器 模式下协议端连不上来？

A:

1. 确认 连接列表 里的监听地址/端口是 0.0.0.0:3002 这种，协议端连的就是它。
2. 连不上多半是防火墙没放行、Docker 没映射端口。
3. 或者 监听地址 填了 127.0.0.1，那只监听本机，容器外连不进来。

Q3: 能接多个账号吗？

A: 能，连接列表 里加几项就是几条连接，同一个插件实例即可。注意每项的 连接标识 不能重复，WS服务器 模式还要各占一个监听端口。

📄 License

MIT License