11 - ob11-core-bridge 使用指南¶

ob11-core-bridge 是 aiplugin4 的配套中转后端（位于独立仓库 aiplugin4-backends）。SealDice 以 OB11 正向 WebSocket 客户端身份主动连到中间件，中间件再出站主动连接 OB11 协议端，插件通过 /plugin WebSocket 直连中间件：注入假消息 → 执行核心指令 → 收集 bot 响应，并把结果回传给 AI。扩展指令由插件本地直调扩展 solve 执行（run_ext_command），不经过中间件。

为什么需要它¶

SealDice 的 JS 插件无法直接调用核心指令（.ext、.help 等）——核心指令没有公开的 JS 调用入口；扩展指令则可直接调用 cmdMap[cmd].solve 在插件内本地执行（run_ext_command）。中间件把 SealDice 当成一个普通 OB11 正向 WS 客户端接入，插件端通过 /plugin WebSocket 发起 run_core_command，中间件向核心 WS 注入一条“假消息”（指令前缀 + 指令文本），再监听核心为响应这条消息而发出的 send_*_msg Action 与消息事件，把多消息结果聚合后返回给调用方。

拓扑¶

SealDice（OB11 正向 WS 客户端）  <──>  /core（或 /core/ws）
OB11 协议端 / 模拟器              <──  中间件启动时出站主动连接
aiplugin4 插件                    <──>  /plugin

端点	用途
`/core`、`/core/ws`	SealDice 核心正向 WS，海豹主动连接本端点
协议端（出站）	中间件作为 WS 客户端，启动时主动连接你在配置里填写的协议端地址（带指数退避重连）
`/plugin`	插件控制 WS 端点：aiplugin4 直连并发送 `core_command` 请求（核心指令注入）；扩展指令由插件本地执行
`/healthz`	健康检查

默认监听 0.0.0.0:46880。海豹主动连入 /core；协议端由中间件出站主动连接（不支持反向 WS，协议端无需也无法连入中间件）。

部署¶

方式一：launcher 一键管理（推荐）¶

python launcher.py start ob11-core-bridge

首次启动自动创建依赖并后台运行；也可以在 WebUI（默认 http://127.0.0.1:8910）里安装、启动、改端口与 token。

方式二：手动运行¶

cd ob11-core-bridge   # 后端独立包目录
npm install
npm start

环境变量¶

变量	默认值	说明
`AIPLUGIN4_BACKEND_HOST`	`0.0.0.0`	监听地址
`AIPLUGIN4_BACKEND_PORT`	`46880`	监听端口
`AIPLUGIN4_BRIDGE_CORE_PATH`	`/core`	核心 WS 路径（默认同时接受 `/core/ws`）
`AIPLUGIN4_BRIDGE_CORE_PATHS`	`/core,/core/ws`	核心 WS 路径集合（逗号分隔，覆盖默认）
`AIPLUGIN4_BRIDGE_PROTOCOL_URL`	空	协议端 WS 地址（中间件启动时主动连接；WebUI「⚙ 配置」可填，重启生效）
`AIPLUGIN4_BRIDGE_PLUGIN_PATH`	`/plugin`	插件控制 WS 路径（aiplugin4 直连）
`AIPLUGIN4_BRIDGE_PLUGIN_TOKEN`	空	插件端 WS 鉴权 token（插件以 `access_token` 查询参数传入）
`AIPLUGIN4_BRIDGE_CORE_TOKEN`	空	核心端（SealDice 连接）token
`AIPLUGIN4_BRIDGE_PROTOCOL_TOKEN`	空	协议端 token（可选；同时以 access_token 查询参数与 Bearer 头发送）

注意：这里没有 CORE_URL。旧版“插件连接中间件、中间件反向连海豹”的方案已移除，现在是海豹主动连中间件。

SealDice 侧配置¶

在 SealDice 面板「连接」中新增 OB11 正向 WebSocket，目标地址填：

ws://127.0.0.1:46880/core

若中间件设置了 token，把 access_token 填 AIPLUGIN4_BRIDGE_CORE_TOKEN（未单独设置时用 AIPLUGIN4_BRIDGE_TOKEN）。

协议端侧配置¶

中间件在启动时作为 WS 客户端主动连接 OB11 协议端（NapCat / LLOneBot / 测试模拟器等）的 WS 地址，并在核心与协议端之间原样转发 OB11 JSON。协议端无需配置任何指向中间件的连接（不支持反向 WS）。

在 aiplugin4「后端」页的 ob11-core-bridge 卡片「⚙ 配置」中填写：

协议端 WebSocket 地址：如 ws://127.0.0.1:6700（对应环境变量 AIPLUGIN4_BRIDGE_PROTOCOL_URL）
协议端 token（可选）：会同时以 access_token 查询参数和 Authorization: Bearer 头发送（对应 AIPLUGIN4_BRIDGE_PROTOCOL_TOKEN）

配置保存后需重启该后端才生效。协议端未配置或不可达时，中间件会按指数退避（1s 起、上限 30s）持续重试，连上后自动恢复转发；期间核心发来的 API 请求立即返回 status: failed，不会静默等待超时。

协议端不是必需的：仅做“注入指令 + 收集响应”时请显式传 forward=false；默认 forward=true 需要协议端可连接，否则核心发出的 Action 无法继续转发。

插件侧接入（aiplugin4）¶

在 aiplugin4「后端 → 后端配置」的 backends.ob11-core-bridge 中填写（也可直接点 aiplugin4-backends WebUI 的「📋 复制后端配置」整段粘贴）：
url：默认 ws://127.0.0.1:46880/plugin（对应后端 AIPLUGIN4_BRIDGE_PLUGIN_PATH，按实际地址/路径填写）
token（可选）：对应后端 AIPLUGIN4_BRIDGE_PLUGIN_TOKEN，中间件要求鉴权时填写（插件以 access_token 查询参数传入）
按需配置「可调用指令白名单」与「指令前缀」。run_core_command 由插件本地注册为 AI 工具（不再依赖 MCP，也无需打开「是否启用MCP」总开关）；run_ext_command 在插件内本地直接执行扩展指令，无需中间件。

工具与参数¶

run_ext_command 与 run_core_command 均由插件本地注册为 AI 工具（敏感工具，执行会显著记录）。run_ext_command 在插件内直调扩展 solve，不依赖中间件；run_core_command 通过 /plugin WebSocket 直连 ob11-core-bridge 注入假消息执行核心指令，需启动 ob11-core-bridge 并在「后端 → 后端配置」的 backends.ob11-core-bridge 填地址。

run_ext_command — 扩展指令¶

action=list：按 kind（builtin / non_builtin / all）列出可调用扩展指令，并附当前已知扩展名
action=call：执行扩展指令
extension + command：扩展名|指令名；command 也支持直接填 扩展名|指令名
args：指令参数，按顺序
trigger：可选，指定注入消息的发送者/触发对象用户 ID；不填则使用当前对话用户
at：可选，指定注入消息中 @ 的用户 ID 列表（字符串数组）；仅群聊支持

本地执行：直接调用扩展 cmdMap[cmd].solve（构造全新 CmdArgs，不要求会话先出现 .r），并复用多消息收集器收集扩展发出的多条回复。无需 MCP/中间件；核心内置扩展与第三方扩展均可调用，仍受「可调用指令白名单」约束。

扩展分为两类： - builtin：fun / story / coc7 / deck / dnd5e / exp / log / reply —— 已硬编码在插件里，无需在配置中维护内置扩展列表 - non_builtin：第三方扩展及本插件

run_core_command — 核心指令¶

action=list：列出白名单中的核心指令
action=call：执行核心指令（如 ext、help；也支持 core|ext 写法）
结构化模式：传 command 和可选 args，插件会按当前「指令前缀」组装核心原始消息
原始消息模式：传 raw_message，原样注入核心；raw_message 不能与 command 或 args 同时使用

触发对象与 @ 对象：两种工具都支持 trigger / at。前者写入 OB11 user_id / sender.user_id，后者写入消息的 at 段和 [CQ:at,qq=...] 原文；省略前者时沿用当前对话用户。私聊传 at 会返回提示，不会伪造私聊 @。

参数¶

参数	适用	说明
`trigger`	两者	指定指令消息发送者/触发对象用户 ID；默认当前对话用户
`at`	两者	指定消息中 @ 的用户 ID 列表（字符串数组）；仅群聊
`forward`	仅 `run_core_command`	是否把捕获到的核心发送消息继续转发给协议端，默认 `true`（转发）
`captureMode`	仅 `run_core_command`	`reply_only` / `lane`；`forward=true` 且要捕获协议端产生的 bot 回复时建议用 `lane`
`maxMessages`	两者	最多收集消息数（1–50；ext 默认 20，core 默认 50）
`settleMs`	两者	收到消息后空闲多少毫秒无新消息即结束（0–10000；ext 默认 400，core 默认 500）
`timeoutMs`	两者	最长等待毫秒数（100–120000，默认 10000）

run_ext_command 本地执行时直接复用会话监听器的 waitFor(timeoutMs, settleMs, maxMessages) 收集扩展发出的多条消息；run_core_command 则把这些参数传给中间件的 capture 策略。

返回结果¶

字段	说明
`ok`	是否成功
`messages`	收集到的消息：`messageId` / `action` / `segments` / `text` / `source`（action/event）/ `forwarded` / `intercepted`
`completedBy`	结束方式：`idle`（空闲窗口）/ `max_messages`（达到上限）/ `timeout` / `disconnect`
`ambiguous`	是否因无法区分并发消息而标记歧义
`forwardedCount` / `interceptedCount`	转发 / 拦截计数
`error`	失败原因（如核心未连接、target 缺少群/私聊 id）

上表是 run_core_command 经核心桥 WebSocket 返回的结果结构；run_ext_command 不经过核心桥，本地执行直接返回收集到的消息文本，异常时返回错误说明。

指令白名单¶

「可调用指令白名单」每框一条，格式 扩展名|指令名/别名1/别名2，同一元素内的别名用 / 分隔：

内置扩展已硬编码，无需填写扩展列表；第三方扩展写实际扩展名
核心指令的扩展名统一写 core（如 core|help）
core|ext 是扩展发现入口，无需加入白名单：run_core_command 执行 command=ext（即核心 .ext）即可查看核心当前全部扩展名称
开启「是否允许调用所有指令」后忽略扩展指令白名单（核心指令仍受 run_core_command 白名单约束）
插件默认值已按当前 SealDice 源码同步全部核心命令、内置扩展命令及别名；核心/扩展指令的调用帮助由默认知识库提供（「知识库」页签：核心指令、扩展指令；OB11 依赖说明见 ob11-api 知识库，仅 QQ 平台可见）。若升级 SealDice 后新增命令，请手动补充白名单或等待插件默认值更新。

指令前缀¶

「工具 → 指令前缀」配置，默认 .。海豹核心通常用 . 作为指令前缀；如果核心改成其他前缀（如 /），请同步修改该配置，否则注入的假消息不会被核心识别为指令。

捕获与转发语义¶

forward=false：捕获核心发出的 send_*_msg Action / 消息事件后拦截，不送到协议端；仍向核心返回 Action 成功响应，避免核心重试或阻塞。适合“AI 内部执行指令、不打扰群聊”的场景。
forward=true：捕获后继续转发到协议端，并把协议端 API 响应按 echo 路由回核心；如需收集协议端产生的 bot 消息，captureMode 用 lane。
reply_only：只收集带 reply 引用（指向注入消息的虚拟 message_id）的响应，最精准；协议端不生成 reply 引用时可能收集不到，此时标记 ambiguous=true。
lane：按 self_id + 群/私聊 + 对方 id 捕获该会话内的 bot 消息，适合没有 reply 引用的场景。
收到第一条消息后进入 settleMs 空闲窗口；达到 maxMessages 或 timeoutMs 结束。

并发与消息混淆¶

同一 lane 的调用串行执行（队列），不同 lane 并行，避免同一群同时注入多条指令时响应混在一起。
纯 OB11 没有标准 trace_id，中间件无法从 Action 本身区分“本次命令的响应”与“外部并发发送”，极端并发下可能返回 ambiguous=true。业务侧建议：短 settleMs + lane 串行 + 唯一目标（selfId / messageType / groupId / userId）来降低混淆。

多核心¶

核心桥收到 trigger 后会同时写入假消息的 user_id 与 sender.user_id；at 会写入 OB11 at 消息段及 raw_message。多个海豹核心可同时连接中间件：核心连接后上报的 self_id 用于路由，run_core_command 的调用与事件按 self_id 区分，插件端从当前消息上下文自动取 selfId 填入 target。run_ext_command 在插件内本地直调当前实例的扩展 solve，不涉及多核心路由。

排障¶

现象	检查
`run_core_command` 不可用 / 报核心桥未连接	「后端 → 后端配置」的 `backends.ob11-core-bridge.url` 是否正确（默认 `ws://127.0.0.1:46880/plugin`）、`ob11-core-bridge` 是否已启动、核心是否已连上 `/core`
`run_ext_command` 执行失败 / 无响应	扩展是否已安装、指令名是否正确（`扩展名\|指令名`）、是否在白名单、指令本身是否抛异常；与中间件无关
执行无响应 / 超时	SealDice 是否已连上 `/core`（看中间件日志）、指令前缀是否正确、目标群/私聊 id 是否正确、指令是否在白名单
返回 `ambiguous=true`	同 lane 并发或缺少 reply 引用；调整 `captureMode` / `settleMs`
鉴权失败	核对 core token / protocol token / plugin token 与中间件 token 一致
提示核心 WS 未连接	检查 SealDice「连接」里的 OB11 正向 WS 是否指向 `/core` 且未报错