Download the PHP package jx3dev/onebot-v11 without Composer

jx3dev/onebot-v11

OneBot V11 反向 WebSocket 服务端。多机器人接入、多 Worker 可用。

功能

• 反向 WS 服务端：只处理 Universal 连接，多机器人按 X-Self-ID 区分
• 多 Worker：API 调用/响应靠 echo 编码 workerId 精确回投
• 消息段：Segment / Message 与 CQ 码字符串双向互转；发出去的裸字符串一律当纯文本，用户可控内容拼进 reply() 不会被解析成 @全体成员
• 注解分发：命令 → 四个事件糖（#[BotMessage] / #[BotNotice] / #[BotRequest] / #[BotMetaEvent]）→ 全局 #[BotEvent]，分层执行；#[BotEventBefore] 排在会话拦截之前，是「每条消息都过」的全局闸门
• 命令 #[BotCommand]：前缀 + 别名 / 正则、作用域、toMe、参数切分；runCommand() 可把当前消息转给别的命令，走完整 管线（权限不绕过）
• 权限：内置 super / owner / admin / member + 自定义 PermissionInterface，OR 逻辑
• 钩子：事件 / 命令 / API / 异常 / 连接 / 生命周期各类前后置（API 钩子可 abort() 短路）
• 中间件 #[BotMiddleware]：类级 / 方法级，内置冷却 #[Cooldown] / 互斥 #[Exclusive]
• 上下文 BotContext：reply()、多轮追问 prompt() / 捕获 capture()、临时数据、切换机器人
• 分发控制：stop() 阻断本条事件的剩余分发（任意 handler 可用）；stopTier() 仅在事件分层内、只停当前层；finish() 阻断并回复
• 可扩展：继承 BotContext / Bot + 换工厂即可替换，无需改本包
• 日志：内置结构化，收包 + 完成汇总、按 message_id 对齐、长内容截断

目录

• 安装
• 配置
• 写第一个命令
• 注解总览
• 事件路由与分层
• 命令 #[BotCommand]
• 钩子
• 中间件
• 主动调用 API：call / send / 群发 / 定时任务
• 上下文 BotContext
• 消息段 Segment / Message
• 异常与日志
• 多 Worker 原理与已知限制
• 测试
• 许可

安装

配置

1. 加一个 WebSocket Server

config/autoload/server.php 的 servers 里追加：

需要「同一条连接的帧恒定落在同一个 Worker」——prompt() / capture() 的会话等待，以及冷却 #[Cooldown] / 互斥 #[Exclusive] 的 per-worker static 状态全靠它。

• SWOOLE_BASE：天然满足（谁 accept 谁持有），dispatch_mode 在该模式下不生效。
• SWOOLE_PROCESS：需要有连接亲和性的 dispatch_mode —— 2（按 fd，Swoole 默认，推荐）或 4（按 IP； 注意同一出口 IP 的多个机器人会全挤在同一个 Worker）。

别用 1（轮询）/ 3（抢占）：它们把同一连接的帧打散到多个 Worker。Swoole 不报错也不警告、握手照样成功， 但事件会大面积丢失，上述功能静默失效。（开了 open_http2_protocol 时 Swoole 会在启动期拦下 1/3，但那是 http2 的守卫，不能指望它兜底。）

2. 注册路由

config/routes.php：

对端（go-cqhttp / NapCat / Lagrange / LLOneBot）的反向 WS 地址填 ws://<host>:9502/onebot/v11/ws。本包只处理 Universal 连接，不要用 API / Event 分离的那两个地址。

想在握手阶段就返回真 401（而不是升级后再断开），给路由挂 AccessTokenMiddleware：

挂了它，token 不对的连接在握手时直接收到 401、不会升级；不挂也有鉴权，只是退化成 onOpen 里「升级后关闭」。两者共用 access_token 配置。

3. config/autoload/onebot.php

同时在线机器人的容量写死在 ConnectionRegistry::MAX_BOTS（4096，约 1~2MB 共享内存），运行期不可扩容；真有超过的极端需求，改常量重启即可。

或者：复用已有的 HTTP server

不想多开端口的话，把骨架里现有的 http server 的 type 改成 SERVER_WEBSOCKET，在原有的 ON_REQUEST 之外补上三个 ws 回调，同一个端口就能同时跑 HTTP 和 WS：

这种情况下路由不用 addServer 包一层 —— Router 的默认 server 名就是 http，顶层注册即可：

注意这条路径同时也会被 HTTP 路由表命中：不带 Upgrade: websocket 头去访问它会走到 onRequest，把 WebSocketController 当普通控制器调其 __invoke()。控制器已实现该方法，对这类请求抛 HttpException(426, 'Upgrade Required')，由你 app 的异常处理器渲染（需注册 HTTP 异常处理器）。

写第一个命令

任意类的方法挂上 #[Bot*] 注解即可，无需继承、无需注册——启动时自动扫描收集。

注解总览

全部注解在 OneBot\Annotation 命名空间下。带 ★ 的可重复（一个方法可挂多个）。

所有事件类注解都带 priority（大者先执行，只在同层内比较）。

事件路由与分层

一条事件按类别分三层，按先后跑，三层默认都执行（分层只定先后、不互相兜底）：

• 层内：命中的 handler 挨个执行，按 priority 降序（同级按类名 + 行号，稳定可复现）。
• 默认三层全跑：命令命中不会自动挡住下面的 #[BotMessage] / #[BotEvent]；想挡得自己调。
• priority 只在同层内比较，不跨层。
• 中途停两档：$ctx->stopTier() 只结束当前这一层、继续下一层；$ctx->stop() 停全部。
• #[BotEvent] 是最后一层，适合放全局兜底 / 未处理事件日志（但它照样每条都跑，不是「没人接才跑」）。

四个事件糖（#[BotMessage] / #[BotNotice] / #[BotRequest] / #[BotMetaEvent]）：type 是点分二级 二级类型.三级类型 ，留空匹配该类全部：

#[BotEvent(type)]：type 是点分三级 post_type.二级.三级，如 message、message.group、notice.notify.poke ，留空匹配全部事件。#[BotEventBefore] / #[BotEventAfter] 同样按这个三级 type 收窄。

命令 #[BotCommand]

命令是消息事件的细化：先按消息事件筛，再按下面规则命中。可重复（一个方法多条命令，任一命中即以该命令跑）。

name 与 regex 是「或」：任一命中即算命中；都留空则不匹配任何消息（启动时会打一条 warning，多半是漏填命令词）。匹配用消息纯文本（ extractPlainText，已滤掉 at/image 等非文本段）。

name / alias 不能含空白：首尾空白（含全角空格）会自动清掉，内部还含空白（多词）的命令词永远匹配不上、启动时会打一条 warning——多词匹配请用 regex。

命令参数 Args

非命令 handler 参数类型写 BotContext 即可。

权限

permission 是 OR 逻辑，任一通过即命中，不满足则静默不命中。内置名用 Permission::* 常量（super 看 super_users 配置； owner/admin/member 看群消息的 sender.role，admin 含群主），可与自定义 PermissionInterface 类混用：

被拒默认静默。想回一句：注解加 denyReply（检查器里 stop() 了则不发），或方法里用 $ctx->isSuper() / isOwner() / isAdmin() / senderRole() 自行处理。

重定向命令 runCommand() / hasCommand()

让 handler 把当前消息手动转给某条命令执行，走完整命令管线（权限 + 中间件 + 命令前后置）：

• runCommand(string $name, string $args = ''): int —— $name 认命令的 name 或 alias；$args 是原始字符串、内部按空白切成位置参数（不支持具名参数）。
• 同名多条按优先级全跑，返回实际派发的条数；命令不存在返回 0（且打一条 warning——转发基本没人接返回值，静默就成了「消息凭空消失、零线索」）。不想吵 warning 就先 hasCommand() 探。
• 权限不绕过，命令前后置 / 中间件 / stop() 全部照常继承；只绕过 scope / toMe（那是文本匹配期的约束，显式点名就不该再被文本规则拦）。
• 正则命令转不过去（没命令词）。
• 相互转发有深度上限 3，转成环会抛 OneBotException（走 #[BotException]、不致命）。
• 只能在被 dispatch() 分发的上下文里用（手工构造的 BotContext 没绑分发器，调了会抛）。

钩子

事件前后置 #[BotEventBefore] / #[BotEventAfter]

在三层之外：before 在所有主 handler 前、after 在所有之后（after 同 finally，始终执行）。#[BotEventBefore] 排在会话拦截 （prompt() / capture()）之前，是真正「每一条消息都过」的全局闸门——即便某个会话正活着、这条消息将被 prompt / capture 收走，前置也照跑；在前置里 stop() 就彻底拦下：消息既不投给会话、也不进命令层（黑名单 / 全局限流 / 埋点靠的就是这个）。也能 像 BotEvent 一样按三级 type 收窄（#[BotEventBefore('message.group')] 只在群消息前跑）。

分层放对地方：#[BotEventBefore] 放便宜的全局闸门（查缓存黑名单、敏感词），它对每条消息都跑、包括多轮问答 / 接龙里的 每条答案；贵的富化（查群信息 / 群成员、setTemp() 预备数据）放 #[BotCommandBefore]，只在命令真命中时才跑，别让每条闲聊都付这个代价。

「便宜」还有个时序理由：前置链排在会话投递之前，链里任何一个 await 都会推迟消息送到挂起的 prompt() / capture()、 吃掉它的超时预算——极端情况那句回答会因 prompt 已超时清理而落回常规分发、甚至误触命令。另外，想「无论如何都跑」的收尾 / 埋点别靠调低 priority（高优先级前置 stop() 会让低优先级的整个不跑），放 #[BotEventAfter]，它不受 stop() 影响。

命令前后置 #[BotCommandBefore] / #[BotCommandAfter]

对所有命令统一生效（不用逐个挂中间件）。guarded 决定前置落在权限检查的哪一侧——权限检查正夹在两组前置中间：

• 分发顺序：命中 → guarded=false 前置 → 判 permission → guarded=true 前置 → handler → 后置。
• stop() = 硬拦截：命令 handler 与所有命令后置都不执行。
• #[BotCommandAfter] 默认只对真正执行过的命令触发；guarded=false 则命中即触发，包括权限被拒的。

API 钩子 #[BotActionBefore] / #[BotActionAfter]

包在每次 call() / callRaw() 外：action 留空匹配全部，填具体 action（如 send_group_msg）只匹配该调用。before 能改参数（ setParams()），after 能读响应（getResponse()）。它们挨个执行、无法用 stop 阻断。

before 里可用 abort() 短路这次调用——不碰网络，直接用你给的响应走完 after 和成功校验：

abort() 切断剩余的 before 钩子；after 照常执行（用 $ctx->isAborted() 区分是不是短路来的）。

异常 #[BotException]

按异常类型分派，只兜分发链路内（事件 handler、中间件、事件解析、连接钩子、action 钩子）抛出的异常；分发链路之外自己调 call()（定时任务、控制器里）抛的不归它管，请自行 try/catch。

$exception 指定要接的异常类型（含子类），默认 Throwable 兜底全部。一次异常会通知所有类型匹配的 handler（按 priority 依次执行、互不影响）——全局 logger 与具体处理器可共存。可重复：

#[BotEventAfter] 里可用 $ctx->exceptions() 拿到本次事件被捕获的所有异常（list<Throwable>），做统一成功/失败统计。

连接钩子 #[BotConnect] / #[BotDisconnect]

机器人连接建立 / 断开后触发，handler 收 ConnectionContext。断开时连接已断，勿再发消息。

生命周期 #[BotServerStart] / #[BotWorkerStart]

方法参数按类型注入（声明对应事件就拿事件、声明任意 DI 服务就注入它，顺序随意，不要就空着）：

• #[BotServerStart] —— fork 出 Worker 之前、在主进程只调一次（BeforeMainServerStart）。用于「一次性、且最好在 fork 前」的准备：建共享 Swoole\Table（fork 前建各 Worker 才共享同一块内存），或给命令动态加别名（加一次、各 Worker fork 继承，最省）。
• #[BotWorkerStart] —— 每个 Worker 启动后各调一次（AfterWorkerStart）。用于必须 fork 后、每 Worker 各自 的初始化（协程级 / Worker 本地资源、本地缓存）。

HandlerRegistry::addAlias(string $commandName, array $aliases): int：给已注册命令追加别名，等价于注解里的 alias ，只是启动时动态加（可从配置 / 数据库来）。返回实际新增的别名数（0 = 命令不存在、全重复、或都含空白被跳过）。重复自动去重；别名同样不能含空白（首尾自动清、内部含空白的跳过不计）；正则命令没命令词、无法加别名。

⚠ 两个钩子都每次触发各跑一遍；共享 Swoole\Table 只能在 #[BotServerStart]（fork 前）建；钩子里抛异常只记日志、不影响其余。

中间件

#[BotMiddleware]

给事件 handler 挂中间件，可用在类上（该类所有事件 handler）或方法上（只该方法），可重复。执行顺序：类级先于方法级，同级按书写顺序。 $middleware 是实现 MiddlewareInterface 的类名，$args 作为构造参数经容器 make() 注入。

中间件的 process() 收 BotContext，因此只对「事件类」handler 生效——#[BotMessage] / #[BotNotice] / #[BotRequest] / #[BotMetaEvent] / #[BotEvent] / #[BotCommand]，以及四个事件/命令前后置。挂在连接钩子 / action 钩子上不生效也不报错 ，请勿这么挂。

内置：冷却 #[Cooldown] / 互斥 #[Exclusive]

两个开箱即用的命令中间件，都是 #[BotMiddleware] 的类型化子类注解，挂命令上即用。

冷却 #[Cooldown]：

• seconds：数字 = 固定滑动窗口；数组 int[] = 递增各级。
• parallel：固定窗口内允许次数（默认 1；递增模式忽略）。

互斥 #[Exclusive]（同 key 的命令不并发、一次一个，后到的排队）：

• 用于「读共享状态 →（reply / prompt / 查 API）→ 写回」这种临界区跨了 await 的场景（否则并发会丢更新 / 超额）；纯同步的读改写协程不抢占、本就安全，不必上锁。⚠ 要互斥的命令必须给同一个 key。
• wait：锁被占时最多等几秒（锁一空就立刻拿到，等满没拿到才拒；默认 10；0 = 不等直接拒）；reply：等超时回一句。

两维分桶（共用 ScopedBucket）：scope 定「谁和谁共享」、key 定「哪些命令共享」。

• scope（用 Cooldown::SCOPE_* / Exclusive::SCOPE_* 常量）：GLOBAL 全局 / GROUP 群（私聊退化为该用户）/ GROUP_USER 群+个人 / USER 个人（跨群）。Cooldown 默认 GROUP_USER，Exclusive 默认 GROUP。
• key：留空 = 分发器给的默认桶——命令层是命令名（别名归一到一桶），其余 handler（糖层 / 事件层 / 各类钩子）是 类::方法、各自独立。要多个共用一桶，给它们同一个 key。

⚠ 于是类级 #[Cooldown] / #[Exclusive] 挂在有多个方法的类上，是每个方法各自一桶、不是全类共享（默认桶按 类::方法 区分）。想全类共享，显式给同一个 key。

状态存 static、per-worker（同一条连接恒定落同一 Worker，无需 Table，见 配置）。想自扩展（令牌桶限流、递增冷却的变体…），照这俩： class X extends BotMiddleware implements MiddlewareInterface { use ScopedBucket; ... }，process() 里 $this->bucket($ctx, $this->scope, $this->key) 拿桶键写自己的逻辑（extends BotMiddleware 后靠 IS_INSTANCEOF 自动被收）。

主动调用 API：call / send / 群发 / 定时任务

从任意 DI 服务里注入 BotManager 取 bot：

call() / callRaw()（要等响应）

API 一律不做封装，只有 call() / callRaw()；协议里的 action 也可通过 __call() 用驼峰直接调（转成 snake_case），Bot 类顶部的方法注解仅供 IDE 补全。

call() 返回响应里的 data，callRaw() 返回完整响应体。两者都要等对端响应，只能在 Worker / Task Worker 里调用。

send()（即发即忘）

不关心返回、或要在自定义进程里调，用 send()——即发即忘、返回 bool、任意进程可用：

群发

send() 任意进程可用，天然适合群发。给所有在线 bot 的某个目标发：

要发到某个 bot 的所有群，先取群列表（call()，需在 Worker / Task Worker 里）再逐个 send()：

定时任务

本包不含定时器；在 Hyperf 里用 hyperf/crontab（或自定义进程 AbstractProcess ）驱动，任务体里推送用 send()——最稳、任意进程可用：

• 推送用 send()（即发即忘）最省心。Hyperf 默认的 crontab 策略会把任务派到 Worker 执行，那种情况下需要响应的 call() 也能用；不确定就只用 send()。
• 定时任务里的异常不归 #[BotException]（那只兜分发链路内的），请自行 try/catch。

上下文 BotContext

事件 handler 收到的 $ctx。命令 handler 收 CommandContext（BotContext 子类，多一个 args()）。

身份与消息查询

回复

⚠ 裸字符串一律当纯文本发：reply() / finish() / prompt() 收到 string 时，里面的 CQ 码（[CQ:at,qq=all]、 [CQ:image,...]）不解析——所以把用户可控文本（群名片、echo 参数…）直接 reply() 是安全的，不会被诱导 @全体 / 发任意卡片。真要发 at / 图片，用段构造器（Segment::at(...)）或 Message；真要按 CQ 串解析（罕见），显式 Message::fromCQ($s)。入站消息不受影响，仍按 CQ 解析成 at / image 等段。

会话：多轮追问 prompt() / 捕获 capture()

同一个人 / 群的后续消息，不用再靠命令绕：

• prompt(string|Message $prompt = '', float $timeout = 60.0, bool $at = false, bool $quote = false, ?callable $match = null): ?Message —— 先把 $prompt 回出去（非空时），再挂起等下一条消息，返回它的 Message；超时返回 null。同一会话再发起 prompt 会顶掉前一个。 $match（收 BotContext）过滤答案：不过的消息不算答案、照常走常规分发、prompt 继续等下一条（于是放行 /命令 就等于允许追问中途插别的命令）。prompt 超时是一次性的（不因收到不匹配消息而重置），capture 才是滑动超时。

• capture(string $scope = 'user', ?callable $match = null, float $timeout = 60.0, ?float $deadline = null, bool $consume = true): Capture —— 连续收一串消息（foreach 迭代 Capture），scope 定按人还是按群、match 过滤、timeout 是滑动超时、deadline 是总时长上限、 consume 决定收到的消息是否还继续走常规分发。

会话等待是纯本地的（本地 Channel），依赖「同一条连接恒定落同一 Worker」。反向 WS 每端一条连接， SWOOLE_BASE 天然满足、SWOOLE_PROCESS 在 dispatch_mode 为 2/4 时满足；换成打散分派的 1/3， prompt/capture 会静默等不到。见 配置。

临时数据

事件内跨 handler / 中间件共享（区别于 field() 读的原始 payload）：

停止分发 / 切换机器人

替换上下文 / 机器人对象

想给上下文加方法、或给 call()/send() 包一层限速/重试/日志：继承 → 写工厂 → dependencies.php 重绑，无需改本包。

之后 $bots->get() / $ctx->bot() / handler 里的 $ctx 都是你的子类（类型标注仍写 BotContext / Bot，子类满足）。

消息段 Segment / Message

reply() / call() 的 message 字段收 string（走 CQ 码解析）、Segment、Message 或段数组，都会归一。构造段：

异常与日志

异常

都在 OneBot\Exception 下，共同基类 OneBotException。注意 status=async（_async 后缀调用返回的 retcode=1）是「已受理」， 不会抛异常。分发链路里的异常交给 #[BotException]（见上）。

日志

内置三类，走 onebot channel（正文前缀 [onebot]），格式 / 级别 / 去向在 config/autoload/logger.php 调：

• 收包 + 完成走 INFO，行首带 message_id，grep 10050 能捞一条消息全程；完成结果 = sent / done / denied / blocked / captured / handled / unhandled。
• 逐 handler 细节走 DEBUG（把 onebot channel 调到 DEBUG 才出）。
• 元事件（心跳）压到 DEBUG、不刷 INFO；长内容（base64 大图、长 URL）自动截断。
• 开关：onebot.php 的 log.events（收包）/ log.commands（完成），默认开。

多 Worker 原理与已知限制

不用 Redis，靠两样东西：

1. 连接注册表建在 Swoole\Table（共享内存）上，由 CreateRegistryListener 在 Master fork 之前创建，每个 Worker 看到同一份 self_id -> fd 映射。
2. 下行推送直接用 Hyperf 的 Sender（自带跨 Worker 的 fd 代理）；上行响应把 workerId 编进 echo（ php.{workerId}.{随机串}），响应帧落在连接所属 Worker，解出前缀后用 sendMessage 回投给真正挂起的那个 Worker。

已知限制

• call()（要等响应）只能在 Worker / Task Worker 进程内调用；自定义进程 / 定时任务里用即发即忘的 send()。
• 不挂 AccessTokenMiddleware 时，鉴权在 onOpen 里做，非法连接看到的是「101 之后立刻被断开」而不是 401。
• 同时在线机器人容量写死为 ConnectionRegistry::MAX_BOTS（4096），运行期不可调整。
• 同一个 self_id 重连时，新连接顶掉旧连接；被顶替的旧连接在它自己的 onClose 到来前推来的事件推送会被丢弃（在途的 API 响应仍放行——那可能是顶替前发起的调用的回包）。
• 依赖「同一条连接的帧恒定落在同一个 Worker」（SWOOLE_BASE 天然满足；SWOOLE_PROCESS 需 dispatch_mode 为 2 （默认）或 4，见 配置）：prompt() / capture() 与冷却 / 互斥中间件的 per-worker 状态都靠它；换成 1/3 这类打散分派，这些会静默失效。

测试

协程相关用例需要 ext-swoole（没装则自动跳过）。覆盖消息段与 CQ 码互转、命令匹配（前缀 / 别名 / 正则 / 作用域 / 权限）、冷却与互斥中间件（含高并发下的原子性与上限不超卖）、call / send 与成功判定、会话 prompt / capture、上下文与分发管线。

许可

MIT