Dice!Next

主题

适配器配置 ​

Dice!Next 采用插件式适配器架构。请在 管理面板 → 适配器管理 里添加和管理适配器；配置会保存到 config/adapters.json，并在下次启动时直接加载。

OneBot v11 适配器 ​

支持两种传输模式，对应配置里的 connection_mode：

模式connection_mode含义端点填法
正向 WebSocketforward_wsDice!Next 主动连接 OneBot 客户端完整 WS 地址，如 ws://127.0.0.1:3001/
反向 WebSocketreverse_wsOneBot 客户端反连 Dice!Next一个端口号（如 6700），Dice!Next 在该端口监听

反向模式下，在 OneBot 客户端把反向 WS 上报地址指向 ws://<Dice!Next 所在 IP>:<端口>/；该端口只接受一个 OneBot 连接，多余连接会被直接关闭。

断线重连（正向 WS）

断线后自动重连采用退避策略：前 10 次每 5 秒、第 11~20 次每 60 秒；连续 20 次失败后暂停自动重连，状态显示「连接超时」，在面板点手动重连即可恢复（连接稳定 30 秒后失败计数自动清零）。

配置文件字段 ​

适配器数组写在 config/adapters.json：

json
{
  "adapters": [
    {
      "name": "MyQQBot",
      "type": "onebot_v11",
      "connection_mode": "forward_ws",
      "endpoint": "ws://127.0.0.1:3001/",
      "access_token": "",
      "enabled": true
    }
  ]
}
字段说明
name适配器显示名
type协议类型；OneBot v11 使用 onebot_v11
connection_modeforward_ws / reverse_ws
endpoint正向：OneBot 端的 WS 地址；反向：监听端口号
access_token连接令牌，留空则不携带（正向连接时以 Authorization: Bearer 头发送，与 OneBot 端保持一致）
enabled是否启用

通过管理面板配置 ​

进入 管理面板 → 适配器管理，新建连接并按平台填写连接信息，保存并启用即可。面板修改即时生效，无需重启。

多适配器 ​

可以添加多个适配器，连接不同账号或作为备用连接。

Milky 适配器 ​

平台连接中选择 Milky。API 通过 HTTP 调用，事件通过 WebSocket 接收；当前仅支持 forward_ws，不支持 Webhook 入站。

字段说明
API 地址（endpoint）Milky 服务的 HTTP / HTTPS 基址，例如 http://127.0.0.1:3000；不是 OneBot WS 地址
事件地址（eventEndpoint）WebSocket 地址，例如 ws://127.0.0.1:3000/event；留空时由 API 地址推导
连接模式（connectionMode）forward_ws，由 Dice!Next 主动连接事件服务
Access Token（accessToken）与 Milky 服务端一致的认证令牌，不是 BDC 骰娘密钥

支持群聊 / 私聊、群成员与名片、群文件及相关管理能力，具体操作仍取决于协议端实现与骰娘权限。临时私聊保留来源群信息，但不会把群号当成私聊目标。群历史单次读取按协议限制为 1–30 条。

连接服务不要直接无认证暴露到公网。API 连通不代表事件已连接；没有消息响应时同时检查 API 地址、事件地址、认证和服务端日志。

QQ 官方机器人能力边界 ​

  • 群聊、C2C 与频道的能力并不相同。群聊 / C2C 的 Markdown 需要相应平台权限；频道按自身支持的消息格式发送，不应默认视为同样支持 Markdown。
  • 已补齐群信息、成员、管理、撤回、菜单及频道等官方接口，插件可通过适配器的 qq_* 动作调用；接口可能要求内邀或白名单，未获权限时仍会返回平台错误。
  • .log export 已接入富媒体文件通道（file_type=4）。文件上传有 200MB 预检限制，最终是否可发送仍取决于平台与账号权限；收不到文件时可改用日志站链接或 WebUI 下载。
  • 当前接口接入和离线测试不等于所有真实账号场景已验收。排查时保留错误码与时间，不要公开 AppSecret、Token 或玩家敏感数据。

回复文案与视觉方案 ​

在 系统设置 → 基础设置 → 回复与显示 → 回复文案与视觉方案 选择传统、标准或高级视觉文案。设置可分别作用于全局、适配器类型和单个账号，优先级为账号 > 适配器类型 > 全局；局部覆盖可以独立选择任意方案，不再受旧版二元“全局主开关”限制。

平台富文本表现说明
OneBot v11传统文本OneBot 标准没有统一的跨实现卡片协议。
Milky传统文本与协议消息段不套用 QQ 官方机器人的 Markdown 能力。
DiscordEmbed超过 Embed 长度限制的消息自动保持传统文本。
KOOKCardMessage使用官方卡片消息格式；过长内容自动保持传统文本。
QQ 官方机器人 2.0Markdown平台需要为机器人开通 Markdown 能力；若接口连续拒绝，Dice!Next 会暂时熔断并直接发送传统文本。

Markdown 模板只保留一份可编辑原稿。Dice!Next 会在内置文案加载、自定义文案保存或人格载入时自动生成纯文字版本；发送时先根据来源适配器和作用域设置选好版本，再代入昵称、骰式等动态变量。传统文案使用历史措辞覆盖层，标准文案使用当前默认文案，高级视觉文案在同一份语义数据上增加状态条与操作提示，不要求骰主维护三份容易不一致的内容。QQ 官方启用交互后，用法行与 [[action:说明|.指令]] 会成为待填充按钮；其他适配器继续收到完整文字，不会混入 QQ 专属标签。

适配器人格范围 ​

在指令列表 → 人格开放中选择机器人账号后，可以单独设置以下选项；这些设置不再放在平台连接的新增 / 编辑弹窗中：

  • 默认人格：跟随全局，或为这个机器人固定指定人格。
  • 用户人格选择：开放全部人格、只开放勾选的人格，或禁止普通用户通过 .rpmode 切换。

默认人格和开放列表相互独立。骰主始终可以在 WebUI 为适配器或群绑定任意人格；开放列表只约束群管理、邀请人和私聊用户通过聊天指令能够发现和选择的内容。这样多个机器人可以共享同一套人物卡和回复数据，同时保持各自的角色范围，不会互相暴露不合适的人格。

卡片上的可点击按钮需要对应平台的交互事件与具体业务授权。Dice!Next 只会在某个功能确实需要用户选择、且该平台能力可用时提供按钮，不会把管理或敏感操作做成通用按钮。

QQ 官方机器人 2.0 ​

在适配器管理页选择 QQ 官方机器人 2.0。可填写 AppID 与 AppSecret，或使用面板中的扫码绑定完成授权；连接建立后会通过官方 Gateway WebSocket 收发官方群和私聊消息。

自 2026-08-10 的 QQ 机器人 2.0 能力更新起，OpenAPI 请求统一使用 https://api.bot.qq.com。Dice!Next 已统一鉴权、Gateway、资料、分享链接、消息和富媒体等请求域名；旧域名不再用于接口调用。

在“标准文案”或“高级视觉文案”方案下，适配器可发送 Markdown。适配器编辑页可开启 Markdown 图片资源强校验：开启后，如果 QQ 平台无法转存 Markdown 中的图片，整条消息会失败并回退纯文字；默认关闭，以保持平台原有兼容行为。对应 config/adapters.json 字段为 force_verify_image_resource。若同一适配器连续两次收到 Markdown / 卡片 HTTP 拒绝，Dice!Next 会在接下来的 10 分钟直接使用预渲染纯文字；冷却结束后自动再次探测，不需要手动重连。

QQ 官方平台以 OpenID 标识用户和群聊，而不是直接提供真实 QQ 号。Dice!Next 可将已验证的 OneBot QQ 身份与官方 OpenID 关联，使人物卡、群设置和日志沿用同一记录；使用 .info 可查看当前窗口的身份和绑定指引。

群权限说明

QQ 官方 API 仍未向消息事件提供可供 Dice!Next 验证的发言者群角色，因此 .bot on/off 等基础指令在官方群内继续按当前兼容策略处理。新增的禁言、入群审批和自动审批策略接口则要求机器人自身是群管理员；若权限不足，QQ 平台会拒绝请求并在面板显示错误。

官方群管理 ​

在 群组管理 → 选择 QQ 官方机器人账号 → 官方群管 中可使用以下能力：

  • 查询当前全员禁言模式和仍在生效的成员禁言，并按成员 OpenID 设置或解除禁言；
  • 拉取当前群的待处理入群申请，查看验证消息、问答、来源与风险提示，并人工通过或拒绝；
  • 创建、启停、修改备注、执行或删除入群自动审批策略，并批量增删白名单 QQ 号。

Gateway 的 GROUP_JOIN_REQUEST 事件也已接入统一事件管线。它会通知骰主，并复用 .group auto pass 及全局加群申请策略；事件中的 join_request_id 会随审批请求原样回传。官方自动审批策略由 QQ 平台执行，和 Dice!Next 的本地关键词自动审批可以并存。

接口限制

入群申请事件要求机器人为群管理员，并使用 GROUP_AND_C2C_EVENT (1<<25) Intent。接口频率、白名单资格和具体错误码由 QQ 官方平台控制。

Discord ​

在适配器管理页选择 Discord，填入 Discord Developer Portal 创建的 Bot Token 即可。适配器通过 Discord Gateway 接收服务器频道和私聊消息，支持 @机器人 指令、频道消息和私聊消息。

请在 Discord Developer Portal 的 Bot 设置中开启 Message Content Intent，否则 Discord 不会向机器人提供普通消息正文。

KOOK ​

在适配器管理页选择 KOOK，填入机器人 Token。适配器通过 KOOK Gateway 与 REST API 连接，支持服务器频道、私聊、文本与 KMarkdown 消息，以及 @机器人 指令。

适配器开发 ​

适配器按统一接口接入，便于继续扩展其他平台。开发方式详见适配器开发。

常见问题 ​

  • 连接不上：检查端点地址与端口、防火墙、Access Token 是否匹配；在仪表盘日志查看详细错误。
  • 状态「连接超时」：自动重连已暂停（连续 20 次失败），修好 OneBot 端后手动重连。
  • 消息丢失：确认适配器状态为「已连接」，且 OneBot 客户端正常上报消息事件。

更多排查见故障排查。

基于 AGPLv3 协议发布

Copyright © 2025-2026 Dice!Next