QQMsgSync

Minecraft 服务器 ↔ QQ 群消息 双向同步插件

---

功能

• QQ 群消息实时转发到 Minecraft 服务器聊天栏
• Minecraft 玩家聊天、加入/退出、死亡、成就达成、传送等事件自动同步到 QQ 群
• 基于注解的反射式命令框架，扩展命令只需加一个 @Command 注解
• SQLite 数据库支持（玩家白名单绑定）
• // 前缀在 QQ 群远程执行服务器命令
• 消息同步和白名单可独立开关

环境要求

• Minecraft 1.21+（Spigot / Paper）
• Java 21
• QQ 机器人（bot-qqpd-java 驱动）

快速开始

1. 安装

从 Releases 下载最新 JAR，放入服务器的 plugins/ 目录，启动服务器。

首次启动后会在 plugins/QQMsgSync/ 生成 config.yml：

# 必填：机器人信息
qbot-appid: 12345678
qbot-token: xxxxxx
qbot-secret: xxxxxx

# MessageSync 消息同步
enable-messagesync: false        # 是否开启消息同步
say-prefix: "[Q群消息]"          # MC 聊天栏消息前缀
qbot-qgnumber: ""               # 绑定的群聊 OpenID（自动填写）
admin-openid: ""                # 机器人管理员 OpenID

# Whitelist 白名单
enable-whitelist: false          # 是否开启 QQ 绑定白名单

2. 配置机器人

修改 qbot-appid、qbot-token、qbot-secret 为你的 QQ 机器人信息，然后重启服务器。

3. 绑定群聊

在目标 QQ 群中发送：

/获取ID

将返回的 OpenID 填入 config.yml 的 admin-openid，然后重启服务器。在群内发送：

/绑定群聊

绑定成功后即可开始消息同步。

命令列表

命令	权限	说明
/获取ID	所有人	获取你的 OpenID
/绑定群聊	机器人管理员	将当前群聊绑定为同步目标
/关于	所有人	查看插件信息
/白名单 <玩家名>	所有人	将你的 QQ 与游戏 ID 绑定并添加白名单
//<命令>	所有人	在服务器控制台执行命令（如 //say hello）

事件同步

开启 enable-messagesync 后，以下 MC 事件会自动同步到 QQ 群：

事件	说明
玩家聊天	消息内容
玩家加入/离开	加入/退出提示
玩家死亡	死亡消息
玩家重生	重生坐标
达成成就	成就名称和描述
玩家传送	来源坐标、目标坐标和传送原因

白名单功能

开启 enable-whitelist: true 后，玩家可在 QQ 群发送：

/白名单 Steve

插件会将你的 QQ 与游戏 ID Steve 绑定，并自动将该玩家添加到服务器白名单。每个 QQ 号只能绑定一个游戏 ID。

扩展开发（@Command 注解框架）

命令采用 @Command 注解驱动，添加新命令只需在 CommandHandler 中加一个方法：

// 无参数命令
@Command(value = "help")
public void help(GroupMessageEvent event, QQMsgSync plugin) {
    event.getRawMessage().send("可用命令: /获取ID, /绑定群聊, /关于");
}

// 带参数命令
@Command(value = "say", permissionChecker = GroupAdminPermissionChecker.class,
         denyMessage = "只有群管理员才能使用此命令")
public void say(GroupMessageEvent event, QQMsgSync plugin, String[] args) {
    String msg = String.join(" ", args);
    Bukkit.broadcastMessage("[群公告] " + msg);
}

方法签名支持两种形式：

• void method(GroupMessageEvent event, QQMsgSync plugin) — 无参数
• void method(GroupMessageEvent event, QQMsgSync plugin, String[] args) — 接收空格分隔的参数

内置权限检查器

类	判断逻辑
NoPermissionChecker	始终允许（@Command 默认值）
AdminPermissionChecker	发送者 OpenID == config.yml 中 admin-openid
GroupAdminPermissionChecker	发送者在群内角色为 owner 或 admin

自定义权限检查器

实现 PermissionChecker 接口即可：

public class MyChecker implements PermissionChecker {
    @Override
    public boolean check(GroupMessageEvent event, QQMsgSync plugin) {
        // 自定义逻辑，返回 true 允许执行
        return true;
    }
}

项目结构

src/main/java/com/netessx/qqmsgsync/
├── QQMsgSync.java              # 插件入口，数据库初始化，ListenerHost注册
├── eventHandler.java           # MC 事件监听 → QQ 群转发
└── command/
    ├── Command.java             # @Command 注解定义
    ├── CommandRegistry.java     # 命令注册中心（反射扫描、权限检查、分发）
    ├── CommandHandler.java      # 业务命令实现（添加命令改这里）
    ├── PermissionChecker.java   # 权限检查接口
    ├── NoPermissionChecker.java # 默认：始终允许
    ├── AdminPermissionChecker.java       # 机器人管理员
    └── GroupAdminPermissionChecker.java  # 群管理员

数据存储

插件使用 SQLite 存储玩家白名单绑定数据，数据库文件位于 plugins/QQMsgSync/user.db。

qms_users 表

字段	类型	说明
id	TEXT（PRIMARY KEY）	游戏内玩家名
qid	TEXT	QQ 号 / OpenID
time	TEXT	绑定时间

CI / CD

每次 push 自动构建，打 v* 标签自动发布 Release。

• 构建产物命名：qqmsgsync-{version}-{short-hash}.jar
• 可在 Actions 页面下载任意 commit 的构建产物

许可证

Apache License 2.0 · 不得商用