# QQMsgSync

**Repository Path**: minecraft-programming-team/QQMsgSync

## Basic Information

- **Project Name**: QQMsgSync
- **Description**: A lightweight, two-way message synchronization plugin that utilizes the official QQ bot platform.
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QQMsgSync

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

---

## 功能

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

## 环境要求

- Minecraft 1.21+（Spigot / Paper）
- Java 21
- QQ 机器人（[bot-qqpd-java](https://github.com/kloping/bot-qqpd-java) 驱动）

## 快速开始

### 1. 安装

从 [Releases](https://github.com/MinecraftProgrammingTeam/QQMsgSync/releases) 下载最新 JAR，放入服务器的 `plugins/` 目录，启动服务器。

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

```yaml
# 必填：机器人信息
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` 中加一个方法：

```java
// 无参数命令
@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` 接口即可：

```java
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](https://github.com/MinecraftProgrammingTeam/QQMsgSync/actions) 页面下载任意 commit 的构建产物

## 许可证

[Apache License 2.0](LICENSE) · 不得商用