QQBot QQ 群服互联

模块简介

QQBot 是 Suite 的 QQ 群服互联模块，通过 OneBot 11 WebSocket 协议 连接 QQ 机器人实现端（SnowLuma / NapCat / Lagrange 等），打通 QQ 群与 Minecraft 服务器之间的消息通道。模块提供双向消息同步、QQ-游戏账号绑定、群内指令查询、签到积分系统、服务器监控告警、群管理 moderation 等全方位功能，并可与其他模块通过 Capability 和 EventBus 深度联动。

属性	值
模块 ID	`qqbot`
版本	1.4.4
主类	`xuanmo.arcartxsuite.qqbot.QQBotModule`
配置文件	`config.yml`
消息文件	`messages.yml`
外部依赖	PlaceholderAPI（必需，`external-depends` 硬依赖，未安装时模块不加载）
软依赖模块	`chat`
配置版本	4
数据库表前缀	`axs_qqbot_`（共享模式）或自定义

功能特性

特性	说明
OneBot 11 WebSocket	正向 WebSocket 连接，支持 SnowLuma / NapCat / Lagrange 等实现端，自动重连与端口探测
双向消息同步	QQ 群 ↔ 游戏内消息双向同步，支持 `both` / `game-to-qq` / `qq-to-game` / `none` 四种模式
QQ-游戏账号绑定	验证码绑定方式，群内发起 → 游戏内确认，支持多 QQ 绑定限制
白名单管理	绑定后自动加白名单，解绑后自动移除，支持群内管理指令
自定义群指令	内置指令（查在线/查服务器/积分榜）+ 服务器命令执行 + PAPI 占位符查询
管理员远程控制	配置的 QQ 号可在群内执行控制台命令，支持命令白名单防 RCE
签到积分系统	每日签到获得积分，连续签到加成，积分兑换奖品（通过邮件发放）
积分红包	群内拼手气红包，支持发红包/抢红包/过期退款
积分转账	群成员之间积分转账
群活跃度排行	按发言次数统计本周/本月活跃度排行
服务器监控告警	TPS 过低或内存过高时自动推送告警到群，带冷却防刷屏
定时消息	固定间隔（interval）或每日定时（daily）推送消息到群
击杀/死亡播报	游戏内击杀事件推送到 QQ 群，支持 Boss-only / PvP-only 过滤
大额交易播报	订阅 Market 模块 EventBus 事件，拍卖成交价超阈值时推送
入群欢迎	新成员加群自动 @ 并发送欢迎消息
关键词自动回复	FAQ 关键词匹配自动回复，支持精确/包含匹配
群公告广播	管理员群内发布公告同步到游戏内（聊天栏 + 标题）
群管理 moderation	群内踢出/封禁玩家，QQ 禁言同步游戏封禁
@ 提示	群内 @ 某 QQ 号，绑定玩家在线时游戏内收到 Title 提示
黑名单	禁止指定 QQ 使用机器人所有功能，支持配置静态 + 数据库动态黑名单
SnowLuma 进程管理	支持 native（本地子进程）和 docker 两种模式自动管理 SnowLuma
UI 面板	绑定中心、消息通知 HUD、管理后台三个 UI 界面
周结算排行榜	每周日 23:59 自动推送积分 Top10 到所有群

依赖

依赖类型	名称	说明
外部依赖	PlaceholderAPI	`external-depends` 硬依赖（未安装时模块不加载），提供 PAPI 占位符查询能力（群指令 `papi-query` 类型）
软依赖模块	`chat`	聊天模块，提供消息事件增强
Capability 依赖	`MailDispatchable`	签到积分兑换奖品时通过邮件系统发放奖励
Capability 依赖	`EssentialsQueryable`	查在线指令中显示 AFK / 隐身 / 无敌状态标签
Capability 依赖	`EventBusCapability`	订阅 Market 模块拍卖成交事件实现大额交易播报
Capability 依赖	`QqBindCapable`	向 loginview 等模块暴露 QQ 绑定状态查询

机器人架构详解

QQBot 模块采用分层架构，核心组件如下：

┌─────────────────────────────────────────────────────────┐
│                    QQBotModule                          │
│              (模块生命周期 / 配置 / 命令注册)              │
├─────────────────────────────────────────────────────────┤
│  OneBotClient          QQBotService         SnowLuma    │
│  (WebSocket 客户端)    (事件处理 + Bukkit   ProcessManager│
│   ↕ OneBot 11 WS        监听器)             (进程管理)    │
│   ↕ 自动重连/端口探测                                    │
├─────────────────────────────────────────────────────────┤
│  QQBotCommandRouter   QQBotBindService   QQBotSignInService│
│  (群指令路由)         (绑定服务)         (签到积分服务)    │
├─────────────────────────────────────────────────────────┤
│  QQBotUiService      QQBotMonitorService  QQBotScheduled  │
│  (UI 通讯)          (监控告警)          MessageService   │
│                                          (定时消息)       │
├─────────────────────────────────────────────────────────┤
│  QQBotWeeklyRankService  QQBotLoginGateListener          │
│  (周结算排行)             (登录审计日志)                  │
├─────────────────────────────────────────────────────────┤
│              JdbcQQBotRepository                         │
│        (SQLite / MySQL 数据存储层)                        │
└─────────────────────────────────────────────────────────┘

OneBot 连接流程

模块启动时，SnowLumaProcessManager 异步初始化 SnowLuma 进程（若 auto-start: true）
等待 WS 端口就绪（最多 8 秒超时探测）
OneBotClient 发起 WebSocket 连接到 OneBot 实现端
连接成功后，QQBotService.onBotConnected() 标记连接状态
收到 OneBot 事件后，经 OneBotEvent 包装，分发给 QQBotService.handleOneBotEvent()
断线时自动按 reconnect-interval-seconds 间隔重连

消息处理流水线

群消息到达后，QQBotService.handleOneBotEvent() 按以下顺序处理：

黑名单拦截 — 配置静态黑名单 + 数据库动态黑名单双重检查
notice 事件 — 入群欢迎 / 禁言同步
自动 moderation — 关键词拦截（撤回 + 禁言）
指令处理 — QQBotCommandRouter.handleCommand() 尝试匹配群指令
自动回复 — 关键词 FAQ 匹配
@ 提示 — 群内 @ 某 QQ → 游戏内 Title 提示
活跃度记录 — 记录群发言次数
消息同步 — QQ → 游戏内广播（受 sync-mode 控制）

账号绑定机制

QQBot 使用 验证码绑定 方式关联 QQ 号与游戏账号，流程如下：

绑定流程

QQ 群                          Minecraft 服务端
  │                                │
  │  #绑定 <游戏名>                 │
  │ ──────────────────────────────>│
  │  生成 6 位验证码                 │
  │  <── 验证码已生成: {code} ──────│
  │  (验证码有效期 300 秒)           │
  │                                │
  │              /qqbot bind {code}│
  │ <──────────────────────────────│
  │  校验玩家名匹配 → 写入数据库     │
  │  <── 绑定成功! ─────────────────│
  │  自动加白名单（若启用）           │

绑定规则

规则	说明
绑定方式	验证码（code），群内发起 → 游戏内确认
验证码格式	6 位随机数字（100000-999999）
验证码有效期	`binding.code-expire-seconds`（默认 300 秒）
每 QQ 绑定上限	`binding.max-bindings-per-qq`（默认 1）
玩家名唯一	同一玩家名只能被一个 QQ 绑定
验证码防碰撞	生成时检查重复，确保唯一
自动白名单	绑定成功后自动执行 `whitelist add {name}`（若启用）
自动解绑白名单	解绑后自动执行 `whitelist remove {name}`（若启用）

绑定数据存储

绑定记录存储在 axs_qqbot_bindings 表中，包含以下字段：

字段	类型	说明
`id`	INTEGER	自增主键
`qq_id`	BIGINT	QQ 号
`player_uuid`	VARCHAR(36)	玩家 UUID
`player_name`	VARCHAR(64)	玩家名
`bound_at`	BIGINT	绑定时间戳（毫秒）

QqBindCapable Capability

模块注册了 QqBindCapable Capability，供 loginview 等模块查询绑定状态：

方法	说明
`isBound(UUID)`	查询玩家是否已绑定 QQ
`getBoundQqId(UUID)`	获取玩家绑定的 QQ 号
`confirmBind(Player, code)`	确认绑定（含自动加白名单逻辑）

UI 面板

QQBot 模块提供三个 UI 界面，通过 ArcartX UI 框架渲染：

UI	文件	UI ID	说明
绑定中心	`ui/qqbot_bind.yml`	`AXS:qqbot_bind`	玩家查看绑定状态、申请验证码、解绑、查看群消息
消息通知 HUD	`ui/qqbot_notify.yml`	`AXS:qqbot_notify`	屏幕右上角弹出新群消息通知
管理后台	`ui/qqbot_admin.yml`	`AXS:qqbot_admin`	管理员查看机器人状态、绑定列表、执行命令

UI 通讯通过 PacketBridge 实现，绑定中心使用 AXS_qqbot 包 ID，管理后台使用 AXS_qqbot_admin 包 ID。

快速上手

安装 OneBot 实现端（推荐 SnowLuma，模块内置进程管理）
在 config.yml 中配置 onebot.ws-url 指向 OneBot WebSocket 地址
在 groups 列表中添加要监听的 QQ 群号
执行 /axs reload qqbot 重载模块
群内发送 #帮助 查看可用指令
群内发送 #绑定 <游戏名> 开始绑定流程

概览