原创 开源 聊天 工具 EightBot - 群服互通机器人 超轻量 0.52MiB！ Mohist 1.12+ 专用适配版

[MD] # EightBot EightBot 是面向 Paper 服务器（purpur，leaves，bukkit均可使用）、Mohist服务器的 QQ 群互通插件，通过 OneBot v11 WebSocket 连接机器人，有着超高性能的实现，在实际游戏中插件几乎不消耗占用任何资源，全部原生实现的协议解析识别和发送，只为给您最佳性能优化！ ## 实现功能 - QQ 账号与游戏 ID 绑定、 - 登录限制、 - 双向消息转发、 - 服务器状态查询 - 远程管理。 插件默认关闭绑定限制和两个方向的消息转发。默认配置中的群号与管理员 QQ 都是示例值 `123456789`，使用前必须替换。 [ATTACH type="full"]142723[/ATTACH] ## 运行要求 - Paper 1.21+ 服务端 - Java 21 - 可供服务器连接的 OneBot v11 正向 WebSocket 地址，例如 `ws://127.0.0.1:3001`（建议与`Luckylillia`搭配使用 ⚠ 禁止在`Luckylillia`中讨论该插件的问题） - 机器人账号已加入需要管理的 QQ 群，并具有所用操作需要的群权限 EightBot 作为 WebSocket 客户端连接配置的地址。当前配置不提供访问令牌或自定义请求头；如果 OneBot 服务启用了鉴权，请在 OneBot 端为该连接妥善配置访问方式。 ## 安装 1. 停止 Minecraft 服务器。 2. 将 EightBot 的 JAR 放入服务器的 `plugins` 目录， 启动服务器，让插件生成 `plugins/EightBot/config.yml` 和 `allowlist.csv`。 3. 停止服务器，按下方说明修改配置，尤其是 QQ 群号和管理员 QQ。 4. 启动服务器，并确认控制台出现 `已连接机器人 | Bot Connected`。 ## 完整配置 ```yaml # OneBot v11 正向 WebSocket 地址；EightBot 会作为客户端连接 websocket: url: "ws://127.0.0.1:3001" qq: # 示例群号，必须替换为机器人所在的目标群号 group-id: "123456789" # EightBot 管理员 QQ；可按相同格式添加多行，示例值必须替换 admins: - "123456789" # - "987654321" binding: # 绑定总开关：同时控制群内绑定命令和未绑定玩家的登录限制 enabled: false # 拒绝登录提示；\n 表示换行，{group} 会替换为上方群号，支持 § 颜色代码 reject-message: "§b您尚未绑定QQ，无法进入服务器\n§7请先在QQ群 §e{group} §7完成绑定" forwarding: # 游戏聊天转发到 QQ 群，输出格式为 [MC] 玩家名: 内容 game-to-group: # 该方向的总开关 enabled: false # true：只有带 prefix 的消息才转发；false：所有非空消息均可转发 require-prefix: true # 只从发往 QQ 的内容中移除，不改变游戏内原聊天 prefix: "#qq " # QQ 群消息转发到游戏，仅处理上方配置的目标群 group-to-game: # 该方向的总开关 enabled: false # true：只有带 prefix 的消息才转发；false：所有非空消息均可转发 require-prefix: true # 转发时会移除此触发前缀；末尾空格属于前缀的一部分 prefix: "#mc " # 所有触发词均可修改；设为空字符串会停用对应命令 commands: # 群内绑定游戏 ID：所有群成员可用，但 binding.enabled 必须开启 bind: "绑定" # 群内确认换绑：仅当前发起换绑的 QQ 使用 bind-confirm: "是" # 查询在线玩家、TPS、MSPT 和内存：所有群成员可用 server-status: "查服" # 服务器图片：当前不可用，触发后只回复功能不可用 server-picture: "cf" # 查询绑定账号保存的等级与总经验：所有群成员可用 balance: "查账" # 执行服务器控制台命令：仅 qq.admins；命令内容紧跟触发词 console: "c/" # 开启 QQ 群全体禁言：仅 qq.admins mute-all: "停一下" # 解除 QQ 群全体禁言：仅 qq.admins unmute-all: "好" # 私聊机器人封禁可疑登录 IP：已绑定 QQ，且登录发生后 5 分钟内可用 private-ban: "BAN" ``` ### 基础连接与群设置 - `websocket.url`：OneBot v11 WebSocket 地址，只接受有效的 `ws://` 或 `wss://` 地址。地址无效时，仅停用机器人连接，不会停用整个插件。 - `qq.group-id`：唯一生效的 QQ 群号。群命令、群消息转发和退群解绑只处理这个群的事件。 - `qq.admins`：允许执行控制台、全体禁言和解除禁言的 QQ 列表。群号与 QQ 都应使用引号包裹的纯数字。 ### 绑定设置 - `binding.enabled`：绑定总开关，默认 `false`。开启后才接受群内绑定/确认命令，并限制未绑定玩家登录；关闭时不会执行这两项功能。 - `binding.reject-message`：玩家因未绑定而被拒绝登录时看到的文字。支持 `\n` 换行、`§` 颜色代码和 `{group}` 群号占位符。 如果绑定文件加载失败，且绑定总开关已开启，插件会拒绝所有玩家登录，避免绑定检查意外放行。请先修复控制台报告的文件问题再重启。 ### 转发设置 两个转发方向均默认关闭： - `enabled`：是否启用该方向。 - `require-prefix`：为 `true` 时，只有以 `prefix` 开头的消息才转发；为 `false` 时，所有非空消息都可转发。 - `prefix`：触发前缀。即使 `require-prefix` 为 `false`，消息若主动带有此前缀，转发内容仍会去掉前缀。 当 `require-prefix: true` 且 `prefix` 为空时，该方向会被自动停用并在控制台给出警告。前缀末尾的空格有意义，请保留 YAML 引号。 ### 命令触发词 `commands` 下的值均可自定义。某项设为空字符串时，对应命令会被停用。触发词重复时，插件会警告，并按内部处理顺序优先执行先匹配的命令。 ## 首次配置建议 1. 将 `qq.group-id` 换成目标群号，将 `qq.admins` 换成真实管理员 QQ；不要保留示例值。 2. 确认 OneBot 的 WebSocket 地址可从 Minecraft 服务器访问。 3. 先保持三个功能开关为 `false`，启动并确认机器人连接成功。 4. 按需开启双向转发并验证前缀。 5. 确认 QQ 绑定流程正常后，再开启 `binding.enabled`，避免玩家因配置错误被集体拒绝登录。 所有配置只在插件启动时读取。修改 `config.yml` 后必须完整重启服务器，插件不支持热重载。 ## QQ 绑定与登录限制 绑定只在配置的 QQ 群内进行，默认命令如下： ```text 绑定 游戏ID ``` 游戏 ID 必须是 3–16 位字母、数字或下划线。绑定关系严格一对一：一个 QQ 只能绑定一个游戏 ID，同一个游戏 ID 也不能被其他 QQ 绑定；游戏 ID 比较不区分大小写。 - 未绑定 QQ 发送 `绑定 Steve`：立即建立绑定。 - 已绑定 QQ 发送另一个游戏 ID：插件提示换绑，再发送 `是` 确认。 - 目标游戏 ID 已被其他 QQ 使用：绑定或换绑会被拒绝。 - 已绑定成员退出目标 QQ 群：绑定总开关开启时，插件自动删除该 QQ 的绑定。 开启 `binding.enabled` 后，未绑定玩家会在预登录阶段被拒绝。绑定玩家首次登录时，插件会记录或更新 UUID；退出服务器时会保存等级和总经验，并在下次进入时恢复。 ## 消息转发 ### 游戏到 QQ 群 默认要求玩家发送： ```text #qq 大家好 ``` QQ群收到： ```text [MC] 玩家名: 大家好 ``` 前缀只从发往 QQ 的内容中去除，玩家在游戏内原本发送的聊天不会被取消或改写。 ### QQ 群到游戏 默认要求群成员发送： ```text #mc 大家好 ``` 游戏内收到： ```text §7[QQ群] §e群名片或昵称§f: 大家好 ``` 群命令会先于消息转发识别；已识别的命令会被消费，不会再广播进游戏。QQ 消息中的格式代码会被清理，避免改变游戏聊天格式。 ## 群命令与权限 EightBot 没有游戏内命令，也不使用 Bukkit 权限节点。QQ 管理权限仅由 `qq.admins` 判断。 | 默认触发词 | 使用位置 | 权限 | 行为 | | --- | --- | --- | --- | | `绑定 游戏ID` | 指定 QQ 群 | 所有群成员；需开启绑定 | 新建绑定或发起换绑 | | `是` | 指定 QQ 群 | 发起换绑的 QQ；需开启绑定 | 确认换绑 | | `查服` | 指定 QQ 群 | 所有群成员 | 返回在线玩家、TPS、MSPT 和内存状态 | | `cf` | 指定 QQ 群 | 所有群成员 | 当前不可用，机器人会明确回复“此功能当前不可用” | | `查账` | 指定 QQ 群 | 所有群成员 | 查询绑定账号保存的游戏等级与“福禄”（总经验）；没有记录时提示尚未玩过 | | `c/命令` | 指定 QQ 群 | 仅 `qq.admins` | 以服务器控制台身份执行命令，例如 `c/say hello` | | `停一下` | 指定 QQ 群 | 仅 `qq.admins` | 请求 OneBot 开启全体禁言 | | `好` | 指定 QQ 群 | 仅 `qq.admins` | 请求 OneBot 解除全体禁言 | | `BAN` | 与机器人的私聊 | 已绑定 QQ，且有待确认登录 | 封禁最近 5 分钟内该绑定账号登录所用的 IP | 控制台、禁言和解除禁言命令即使由非管理员发送也会被消费，并回复无权限，不会作为普通聊天转发。 ### 私聊 BAN 的实际行为 已绑定玩家上线时，机器人会私聊对应 QQ，并给出 5 分钟确认窗口。如果不是本人登录，QQ 用户可在与机器人的私聊中发送 `BAN`： - 插件立即踢出当前使用该 IP 的在线玩家； - 此 IP 在本次服务器运行期间无法再次登录； - IP 封禁只保存在内存中，服务器重启后清除； - 超过 5 分钟或没有待确认登录时，命令不会封禁 IP。 ## allowlist.csv 文件位于： ```text plugins/EightBot/allowlist.csv ``` 插件会自动创建此 UTF-8、无表头 CSV。它兼容原有四列格式： ```text null,PlayerName,123456789,null ``` 四列依次为 UUID、游戏 ID、QQ、等级。新绑定最初使用 `null` 占位；玩家登录和退出后会更新 UUID、等级，并可能追加第五列“总经验”。请不要添加表头，也不要在字段中使用逗号。 插件会跳过格式错误的行。QQ 或游戏 ID 重复时，保留文件中第一条有效记录并在控制台警告。文件写入采用安全替换方式；如需手工编辑，请先停止服务器，以免修改被运行中的插件覆盖。 ## 常见问题 ### 机器人无法连接 - 检查 OneBot 服务是否正在监听 `websocket.url`。 - 确认使用的是正向 WebSocket 地址，协议为 `ws://` 或 `wss://`。 - 查看控制台的“配置错误”或 WebSocket 重连日志。断线后插件会每 5 秒尝试重连。 - 当前版本没有令牌配置项；若 OneBot 端要求额外鉴权，需要先调整 OneBot 端的连接策略。 ### 群里发送消息没有反应 - 确认 `qq.group-id` 已替换为真实群号，且机器人确实在该群。 - 确认 OneBot 上报的是 OneBot v11 群消息事件。 - 绑定命令需要 `binding.enabled: true`。 - 转发需要对应方向 `enabled: true`；要求前缀时还必须完整输入前缀及其尾部空格。 - 命令触发词为空会停用该命令。 ### 管理命令提示没有权限 将发送者 QQ 以带引号的纯数字加入 `qq.admins`，然后重启服务器。群主或 QQ 群管理员身份不会自动获得 EightBot 管理权限。 ### 开启绑定后所有玩家都无法登录 先查看控制台是否报告 `allowlist.csv` 无法读取。加载失败时插件会安全地拒绝登录。确认数据目录可写、CSV 至少有四列且绑定记录有效；也可暂时关闭 `binding.enabled`，重启后再修复绑定数据。 ### 图片命令为什么没有截图 `commands.server-picture` 目前仅保留可配置触发词，截图功能尚未实现，触发后只会回复当前不可用。 ### 修改配置后为什么没有变化 EightBot 不会在运行中重新读取配置。请停止并完整重启服务器，不建议使用插件热重载工具。 [/MD]