将 QQ 群机器人接入 Minecraft 1.21.1 NeoForge 服务器：游戏聊天与 QQ 群双向转发、白名单管理、在线查询、命令执行、敏感词审核、AI Agent 智能管理与 WebUI 图形化配置。
基于 HuHoBotPenguin 的 NeoForge 平台移植版。
| 平台 | 状态 | JDK 要求 | 产物 |
|---|---|---|---|
| NeoForge 1.21.1 | 本分支 | JDK 21+ | HuHoBot-Penguin_NeoForge-<版本>.jar |
| Spigot / Paper（api-version 1.18+） | 上游 | JDK 8+ | HuHoBot-Penguin_Spigot-<版本>.jar |
| Nukkit / PMMP | 待适配 | — | — |
| Velocity / BungeeCord | 待适配 | — | — |
| 功能 | 说明 |
|---|---|
| 双向聊天转发 | 游戏 ↔ QQ 群消息实时互通，支持格式模板与前缀过滤 |
| QQ 群指令系统 | 30+ 条内置命令，支持权限分级、命令开关与动态帮助 |
| 白名单管理 | 映射到服务器原生命令，支持自定义模板 |
| 敏感词审核 | 本地正则词库 + 可选 OpenAI 兼容接口 AI 二审 |
| MOTD 服务器状态 | /motd 查询服务器状态，返回图片 + Markdown 卡片 |
| 自定义命令 | 占位符替换，支持权限分级（普通/管理员） |
| 多群支持 | 每群独立的管理员名单与配置 |
| AI Agent | @机器人 /agent 任务描述 —— AI 自动执行服务器管理任务 |
| WebUI 图形化配置 | 浏览器访问 http://127.0.0.1:5678 管理所有配置项 |
| 群服互通 @提及 | 游戏内 /at 命令发送 QQ @消息，QQ→游戏蓝色高亮+叮音效 |
| QQ 群管理 | AI Agent 集成禁言、入群审批、自动审批策略等群管理工具 |
| 指令面板自动同步 | 启动时自动同步命令面板到 QQ 群（上限 20 条） |
- 到 q.qq.com 申请机器人，获得 AppID 和 Secret
- 准备运行环境：JDK 21+
- 准备 Minecraft 服务器：NeoForge 1.21.1（推荐 21.1.217）
将 HuHoBot-Penguin_NeoForge-1.4.0-beta.1.jar 放入服务器 mods/ 目录，重启服务器。
首次启动后会在服务器根目录生成 config.yml，也可通过 WebUI 进行图形化配置。
# QQ 机器人凭据
bot:
app-id: "你的AppID"
secret: "你的Secret"
name: "机器人昵称"
groups: [] # 群 OpenID 列表，留空则不限制
# 聊天格式
chat-format:
from-game: "[游戏] {message}" # 游戏→群 格式
from-group: "[QQ] {name}: {message}" # 群→游戏 格式
post-chat: true # 是否转发游戏聊天
start-with: "" # 触发前缀（留空转发全部）
# AI Agent
agent:
enabled: false
base-url: "" # OpenAI 兼容接口地址
api-key: "" # AI 接口密钥
model: "gpt-4o-mini"
command-mode: "manual" # manual=手动审批 / auto=自动执行完整配置说明请参考 WebUI 或 config.yml 中的注释。
在 QQ 群中 @机器人 /agent <任务描述>，AI 会自动执行服务器管理任务。
示例：
@HuHoBot /agent 查看服务器插件列表
@HuHoBot /agent 给玩家 Steve 添加白名单
@HuHoBot /agent 禁言玩家 BadBoy 10分钟
| 模式 | 说明 |
|---|---|
| 手动审批（manual） | AI 执行危险操作时发送审批卡片，管理员/群主点击同意/拒绝 |
| 自动执行（auto） | AI 直接执行所有操作，无需审批 |
⚠️ 不建议开 auto！ 有用户反馈使用 auto 后 AI 幻觉导致误刷神装给玩家。数据无价，谨慎操作。
| QQ 群命令 | 说明 |
|---|---|
agent <任务描述> |
触发 AI Agent 执行任务 |
newsession |
清除当前用户的 AI 会话上下文 |
stop |
紧急停止所有 AI 任务 |
启动后在服务器控制台查看密码，浏览器访问 http://127.0.0.1:5678。
| 命令 | 说明 |
|---|---|
/hb reload |
重载配置文件 |
/hb info |
查看适配器信息 |
/hb webui |
查看 WebUI 地址 |
/hb password <新密码> |
修改 WebUI 登录密码 |
在 Minecraft 聊天中输入 @玩家名 消息，消息会以 QQ @消息格式发送到群。
QQ 群中的 @消息会自动解析为 §9@玩家名§r（蓝色高亮），被 @ 的在线玩家会收到叮音效提醒。
/at <群成员昵称> <消息内容>
向 QQ 群发送 @消息，支持 Tab 补全昵称。
| 命令 | 说明 |
|---|---|
查信息 [OpenId] |
查询自己的或指定用户的 OpenId 和认证状态 |
发信息 <内容> |
将消息转发到游戏内聊天 |
查在线 |
查询在线玩家列表 |
帮助 |
查看所有可用命令 |
| 命令 | 说明 |
|---|---|
添加白名单 <玩家名> |
添加玩家白名单 |
删除白名单 <玩家名> |
删除玩家白名单 |
查白名单 |
查看白名单列表 |
执行命令 <命令> |
执行服务器原生命令 |
全量 |
切换全量聊天转发开关 |
完整命令列表请查看 /帮助 或上游文档。
- JDK 21+
- Gradle 9.6.1+
git clone https://github.com/Shabby-666/PenguinAgent-NeoForged.git
cd PenguinAgent-NeoForged
# 构建 NeoForge 模块
gradle :server-NeoForge:build --no-configuration-cache
# 产物位于
ls build/gather-jar/注意：由于 Shadow 插件与 Gradle Configuration Cache 不兼容，构建时需加
--no-configuration-cache。
PenguinAgent-NeoForged/
├── build.gradle.kts # 根构建文件
├── settings.gradle.kts # 模块配置
├── deps/qqpd-bot-java/ # QQ Bot SDK（git submodule）
├── common/Bot/ # 平台无关核心模块
├── server/Spigot/ # Spigot/Paper 平台适配
├── server/NeoForge/ # NeoForge 1.21.1 平台适配 ← 本分支
│ └── src/main/kotlin/cn/huohuas001/huhobotpenguin/neoforge/
│ ├── HuHoBotNeoForge.kt # @Mod 入口，HuHoBot 实现
│ ├── events/ # 游戏事件监听
│ ├── commands/ # Brigadier 命令注册
│ ├── compat/ # QQ SDK 兼容层
│ └── manager/ # 配置管理
└── server/AdapterCommon/ # 适配器公共层
| 项目 | 说明 |
|---|---|
| NeoForge 版本 | 21.1.217 |
| ModDevGradle | 2.0.107 |
| Kotlin | 2.2.20 |
| Shadow | 8.3.11 |
| 产物大小 | ~14 MB（已剔除 Minecraft 运行时） |
NeoForge 适配要点：
- 使用
ServerLifecycleHooks.getCurrentServer()替代 Spigot 的Bukkit.getServer() CommandSource.sendMessage()改为sendSystemMessage()（1.21.1 mojmap）- 命令注册使用 Brigadier（
LiteralArgumentBuilder） - QQ SDK 的
PackageScannerImpl不支持 NeoForge 的union:协议，通过预填充类加载器缓存解决 - SDK HTTP 反序列化依赖线程上下文类加载器，需要在调度任务中切换到 Mod 类加载器
本项目采用 GNU Affero General Public License v3.0 许可证。