HuHoBot GameAuthCode

HuHoBot GameAuthCode 是面向 Minecraft 离线模式服务器的独立账号绑定插件。它把 AuthMe 登录状态作为安全边界，让玩家从游戏内获取一次性验证码，再在 QQ 群中完成 Minecraft 角色绑定。

插件通过 HuHoBot API 提供绑定数据，不需要修改 HuHoBot 主体。它面向 HuHoBot-Penguin 官方主分支的 Spigot/Paper 路线；具备兼容绑定服务的其他附属插件（例如 HuHoBot Inventory）可以直接读取已验证的绑定。

• 作者：RiegaLee
• 插件标识：HuHoBotGameAuthCode

当前版本

• GameAuthCode：1.10.4
• 状态：独立加载、双确认绑定、群内绑定查询与官方主分支适配已完成自动测试
• 已验证组合：HuHoBot-Penguin 主分支 bf95dd6（Common 1.5.0）、HuHoBot Inventory 1.24.0、AuthMe 6.x
• Java 字节码兼容：Java 8

正式构建请从仓库的 Releases 页面下载，不要从第三方来源下载来历不明的 JAR。

功能

• AuthMe 登录成功后，玩家可在游戏内获取六位一次性验证码。
• QQ 提交验证码后，必须由对应玩家在游戏内再次确认；其他玩家无法代为确认。
• 确认、拒绝、离线和超时结果都会回执到原 QQ 用户。
• QQ 用户可绑定最多两个 Minecraft 账号。
• 支持绑定列表、主账号切换和指定账号解绑。
• 多账号解绑提供纵向 QQ 按钮，并保留文字命令作为回退。
• 按钮限制发起人、60 秒有效且只能消费一次；点击、新一轮选择或超时后会撤回原按钮消息。
• 新注册玩家会自动收到绑定码，但插件不会删除或撤销 AuthMe 账号。
• 可选强制绑定模式默认关闭；开启后，已通过 AuthMe 但尚未绑定 QQ 的玩家不能移动或执行普通指令，只保留 /authcode 绑定入口。
• 强制绑定模式可监听主分支 QQ 退群事件；启动后还会分页核验群成员，补偿服务器关闭期间遗漏的退群事件。
• 绑定持久化后，服务器重启及玩家离线期间仍可供其他兼容插件查询。
• /查绑 可查询自己或被 @ 群成员的已验证绑定；回复引用原消息并 @ 请求者。
• 管理员可用 /查归属 <游戏ID> 在当前群内反查绑定者，不向普通用户暴露 OpenID。
• 离线服以规范化玩家名作为稳定账号键，不依赖可能变化的离线 UUID。

运行要求

• Paper 或 Spigot 兼容服务端
• HuHoBot Spigot/Paper 主体
• AuthMe 6.x

plugin.yml 只硬依赖 HuHoBotPenguin；不安装 Inventory 也能独立加载并注册全部绑定命令。AuthMe 默认是必需的安全依赖，缺少时插件会停止启用，避免绕过登录验证。

安装

1. 从 Releases 下载 HuHoBot-GameAuthCode-1.10.4.jar。
2. 确认服务器已经安装并能正常启动 HuHoBot 和 AuthMe。
3. 把 JAR 放入服务器的 plugins/ 目录。
4. 完整重启服务器，不建议使用热重载插件。
5. 检查控制台中是否出现 GameAuthCode 成功启用的信息。
6. 首次启动后按需修改 plugins/HuHoBotGameAuthCode/config.yml，修改完成后再次重启。

升级前请备份：

plugins/HuHoBotGameAuthCode/bindings.yml
plugins/HuHoBotGameAuthCode/config.yml

bindings.yml 含有用户绑定标识，不能上传到 GitHub、群文件或公开日志中。

使用方法

第一次绑定

1. 玩家进入服务器并完成 AuthMe 注册或登录。
2. 游戏内会显示验证码；也可以执行 /authcode 重新显示当前验证码。
3. 在 QQ 群发送 /绑定 <验证码>。
4. 对应玩家在游戏内核对 QQ 群昵称，点击“确认绑定”或“拒绝”。
5. QQ 群收到绑定结果回执后，即可使用依赖绑定服务的功能。

游戏内命令

命令	说明
/authcode	获取或重新显示 QQ 绑定验证码

QQ 群命令

命令	说明
/绑定 <验证码>	绑定验证码对应的 Minecraft 账号
/绑定列表	查看当前绑定的账号与主账号
/我的绑定	查看自己的账号绑定
/查绑	查看自己的账号绑定
/查绑 @群成员	查看该群成员的账号绑定
/设置主账号 <序号或游戏ID>	切换默认查询账号
/解绑	单账号直接解绑；多账号时显示选择按钮
/解绑 <序号或游戏ID>	不使用按钮，直接指定要解绑的账号
/查归属 <游戏ID>	管理员在当前群内反查该玩家的绑定者

安全行为

• 验证码有有效期、创建冷却和最大错误尝试次数。
• 同一验证码只能成功使用一次。
• 解绑按钮绑定群、发起用户、随机 nonce 和具体绑定记录。
• 超时按钮、其他用户点击和重复点击都会被拒绝。
• 真正删除前会再次核对稳定 binding ID，避免旧按钮误删后来复用槽位的新绑定。

配置

默认配置位于 src/main/resources/config.yml。常用选项：

配置项	默认值	说明
challenge-expire-seconds	300	验证码有效时间
challenge-create-cooldown-seconds	10	验证码创建冷却
challenge-max-attempts	3	最大错误尝试次数
confirmation-expire-seconds	120	游戏内双确认有效时间
max-accounts-per-user	2	每位 QQ 用户最多绑定账号数
authme.required	true	是否强制要求 AuthMe 集成
force-binding.enabled	false	是否在 AuthMe 登录后强制完成 QQ 绑定才能继续游戏
force-binding.unbind-on-group-leave	true	强制绑定模式下，是否在收到 QQ 退群事件时解除该群绑定
force-binding.startup-membership-reconciliation.enabled	true	启动后分页核验绑定成员，补偿停服期间遗漏的退群事件
force-binding.startup-membership-reconciliation.request-interval-millis	2100	群成员分页请求间隔，默认遵守 30 QPM 级别频控
force-binding.startup-membership-reconciliation.confirm-missing-after-seconds	60	首次完整列表缺失后，等待多久再次完整核验
force-binding.allowed-commands	/authcode 及别名	未绑定期间仍允许执行的命令
force-binding.bypass-permission	huhobot.binding.bypass	绕过限制的权限，默认无人拥有，需由权限插件显式授予

默认行为不会限制玩家，也不会注销或删除任何 AuthMe 账号。若要开启强制绑定，将配置改为：

force-binding:
  enabled: true

开启后，限制只在玩家已经通过 AuthMe 身份验证、但还没有任何有效 QQ 绑定时生效。完成游戏内双确认后会立即解除；退出 QQ 群后，主分支的 GROUP_MEMBER_REMOVE 事件会删除该成员在对应群内的绑定，在线玩家随即重新进入限制状态。

启动补偿不会按绑定逐个查询。插件按群使用 next_cursor 分页，每页最多请求 100 名成员，并在已经找到全部绑定成员时提前停止。只有两次完整分页都确认某个 OpenID 不在群内才会解绑；超时、限流、分页中断或接口无权限都会保留全部绑定。群成员接口目前属于 QQ 官方内邀能力，未开通时控制台会提示错误码 11253，此时只能依赖实时退群事件，或把机器人迁移为独立常驻进程。

所有用户可见提示均可在 messages 节点中修改。

从源码构建

仓库不会打包 HuHoBot 主体或 QQ SDK。编译前需准备兼容版本的以下两个 JAR：

• huhobot-api-*.jar
• common-Bot-*.jar

复制 gradle.properties.example 为 gradle.properties，填写两个 JAR 的路径，然后执行：

.\gradlew.bat clean build

也可以直接传入路径：

.\gradlew.bat clean build `
  -PhuhobotApiJar="D:/path/to/huhobot-api.jar" `
  -PhuhobotQqSdkJar="D:/path/to/common-Bot.jar"

构建产物位于：

build/libs/HuHoBot-GameAuthCode-1.10.4.jar

build 任务同时运行测试和附属插件边界检查。最终 JAR 内置稳定 HuHoBot API，以便在没有 Inventory 时独立加载，但不包含 HuHoBot Core、QQ SDK 或运行期绑定数据。

致谢

• HuHoBot
• AuthMeReloaded
• HuHoSTDWhiteList，为离线服验证流程提供了设计参考

许可证

本项目采用 GNU Affero General Public License v3.0，与 HuHoBot-Penguin 主项目保持一致。