nonebot-plugin-minecraft-tools 是一个仅通过 Minecraft RCON 与服务端通信的
NoneBot2 插件。插件定时执行 list，根据前后两次完整玩家名单的差集判断玩家
上线和下线，并向唯一配置的 QQ 群发送通知；目标群中的普通消息也会通过固定的
tellraw 广播到 Minecraft。
插件只使用 RCON，不接收服务端事件，也不提供命令翻译功能。目标群中的 NoneBot 超级用户可以通过受控入口执行任意 Minecraft 服务端命令。
- 默认每 5 秒通过 RCON 执行一次
list。 - 根据完整玩家名单变化推送加入和退出通知。
- RCON 连接失效和恢复时各通知一次。
- 使用
/MC状态立即查询最新在线人数和玩家名单。 - 使用
/本次MC时长、/今日MC时长、/本周MC时长、/本月MC时长、/总MC时长查询对应周期的游玩时长。 - 使用
/MC时长查询完整时长统计，使用/MC时长 玩家名称查询指定玩家。 - QQ 用户可绑定多个 MC 账号名称；同一 MC 账号只能绑定给一个 QQ 用户。
- 使用
/MC绑定、/MC解绑与/MC绑定列表管理自己的账号绑定。 - 使用
/MC帮助查看全部指令；优先发送帮助卡片，渲染失败时回退为文字。 - 目标群中的 NoneBot 超级用户可用 @成员 持久化授权 OP，并配置死亡不掉落和防爆保护。
- 目标群中的 NoneBot 超级用户可使用
/MC代绑与/MC代解绑为群成员维护绑定。 - 时长排行榜最多展示当前周期前 10 名；图片渲染繁忙时自动回退为文字，避免请求堆积。
- 目标群中的 NoneBot 超级用户可使用
/MC指令 <具体命令>执行服务端管理员命令。 - 默认每天 23:59:59 按机器人所在系统本地时区向目标群发送时长日报。
- QQ 消息发送失败时进入单群可靠队列，按顺序重试。
- 将目标 QQ 群的非插件命令消息安全转发到 Minecraft 聊天栏。
只有同时满足以下条件的消息才会执行：
- 消息来自
MINECRAFT_GROUP_ID配置的唯一目标群； - 发送者属于 NoneBot 配置中的
SUPERUSERS。
使用示例：
/MC指令 time set day
/MC指令 whitelist add Steve
/MC指令 stop
该入口允许执行全部 Minecraft 服务端命令，不设置黑名单，包括 stop、op、
deop、ban 和 whitelist 等高风险命令。非超级用户发送 /MC指令 时不会执行、
不会回复，也不会作为普通聊天转发到 Minecraft。
服务端返回非空结果时，机器人会附带原命令将结果发送到群内；长结果自动分段并保持 顺序。服务端返回空字符串或纯空白内容时不发送任何回复。
管理员命令采用最多执行一次的策略。命令发送后如果连接中断、超时或响应异常，机器人
不会自动重发，以免 /give、summon 等有副作用的命令执行两次。此时会提示执行结果
未知、命令可能已经生效，管理员应先检查服务端状态再决定是否手动重试。
绑定关系保存在游玩时长数据库中。一个 QQ 用户可以绑定多个 MC 账号；每个 MC 账号只能归属一个 QQ 用户，名称不区分大小写。普通成员只能管理自己的绑定：
/MC绑定 Steve
/MC解绑 Steve
/MC绑定列表
目标群中的 NoneBot 超级用户可使用 QQ 号为群成员手动维护绑定：
/MC代绑 123456789 Steve
/MC代解绑 123456789 Steve
MC 名称必须是 3 至 16 位英文、数字或下划线。已绑定到其他 QQ 用户的账号不会被 覆盖；重复绑定同一用户的账号保持幂等。
策略配置保存在游玩时长数据库中，默认均为“未配置”，插件不会主动修改服务器规则。 超级用户可以在目标群中执行：
/MC设置OP @成员
/MC取消OP @成员
/MC设置 死亡不掉落 开
/MC设置 防爆保护 开
/MC设置 死亡不掉落 关
/MC配置
OP 授权按 QQ 用户保存，会覆盖该用户当前和未来绑定的全部 MC 账号；目标账号加入 服务器时若未拥有 OP，插件会自动执行 op。取消授权会立即尝试对在线绑定账号执行 deop。
死亡不掉落对应 gamerule keepInventory true，防爆保护对应 gamerule mobGriefing false。关闭死亡不掉落会持续校正 keepInventory false；关闭防爆保护 会持续校正 mobGriefing true。防爆保护不阻止玩家放置的 TNT 破坏方块。服务器首次连通 或重连恢复时，已配置的规则和在线授权账号会自动再次校正。RCON 暂时不可用时配置仍会 保存，待服务器恢复后自动同步。
在 server.properties 中启用 RCON：
enable-rcon=true
rcon.port=25575
rcon.password=请设置高强度密码RCON 通信本身不提供加密。不要将 RCON 端口直接暴露到公网，应通过防火墙只允许 机器人所在主机访问。
在机器人项目的 .env 中配置唯一的服务端和 QQ 群：
MINECRAFT_RCON_HOST=127.0.0.1
MINECRAFT_RCON_PORT=25575
MINECRAFT_RCON_PASSWORD=your-password
MINECRAFT_GROUP_ID=965502761以上四项均为必填项：
MINECRAFT_RCON_HOST：Minecraft 服务端可访问地址。MINECRAFT_RCON_PORT：RCON 端口，必须为1到65535的整数。MINECRAFT_RCON_PASSWORD：server.properties中配置的 RCON 密码。MINECRAFT_GROUP_ID：接收通知并允许查询的唯一 QQ 群号。
可选配置：
MINECRAFT_MONITOR_ENABLED=true
MINECRAFT_POLL_INTERVAL=5
MINECRAFT_DAILY_REPORT_TIME=23:59:59
MINECRAFT_QQ_CHAT_PREFIX=QQMINECRAFT_DAILY_REPORT_TIME 必须使用严格的 HH:MM:SS 24 小时格式；未配置
或配置无效时使用默认值 23:59:59。轮询间隔最小为 1 秒。修改配置后需要重启
机器人。
MINECRAFT_QQ_CHAT_PREFIX 控制 Minecraft 聊天中方括号内的前缀，未配置、为空或
仅包含空白字符时使用默认值 QQ。
目标群中的普通消息使用以下格式广播到全部在线玩家：
[QQ]张三: 大家好 😀 [图片]
[QQ]李四: @张三 收到
- 发送者、
@对象和回复对象都优先使用群名片，其次 QQ 昵称，最后回退为 QQ 号。 /MC帮助、/MC状态、能够匹配现有规则的/MC时长系列命令、/MC指令、MC 账号绑定和服务器策略命令不会转发；其他消息即使以/开头也会正常转发。- 图片、音频、视频、文件和卡片分别显示为
[图片]、[音频]、[视频]、[文件]和[卡片]。 - Unicode Emoji 会作为文本原样发送；QQ 原生表情在没有可读名称时显示为
[表情]。 - 回复消息只显示
@回复对象和当前消息正文，不附带被引用的原文。 - Minecraft 客户端能否显示特定 Unicode Emoji 取决于客户端使用的字体。
- 用户文本通过 JSON 文本组件传给固定的
tellraw @a，不能控制选择器或执行其他命令。 - 转发失败只记录日志，不向 QQ 群发送失败提示。
- 第一次轮询时建立 TCP 连接并完成鉴权，后续
list复用同一连接。 - 连接中断、超时或协议异常时会关闭失效连接，立即重连并重试一次；重试仍失败 才将服务标记为失效。
- 机器人正常关闭时会主动关闭持久 RCON 连接。
- 首次成功轮询只建立基线，不会把已经在线的玩家误报为刚刚上线。
- 只有在线人数与解析出的玩家数量完全一致时，结果才会用于更新玩家状态。
- 名单不完整、响应无法解析、鉴权失败、连接失败或超时时，本轮视为失败；上一次 成功名单不会被覆盖，也不会产生虚假的玩家退出通知。
- 连续失败只发送一次连接失效通知；后续成功时发送一次恢复通知。
/MC状态会立即执行一次list，不会只返回旧缓存。
游玩会话完全由 RCON 轮询到的名单变化驱动：
- 玩家第一次出现在完整名单中时开始会话。
- 玩家从完整名单中消失时结束会话。
- 服务首次失联时，所有活动会话按最后一次成功观测时间结束。
- 服务失联期间不推测玩家的真实上下线时间，也不会继续累计时长。
- 服务恢复后，仍在线的玩家从恢复时刻开始新的会话。
数据保存在机器人项目根目录的 data/minecraft_tools/playtime.db。今日、本周和本月
均使用机器人所在系统的本地时区，本周从周一开始。
📈 Steve 加入了服务器
👥 当前在线：2 人
🎲 玩家：Alex, Steve
📉 Steve 离开了服务器
👥 当前在线：1 人
🎲 玩家：Alex
本次游玩时长：1小时23分0秒
🔴 Minecraft 服务连接失效
🟢 Minecraft 服务已恢复
👥 当前在线：1 人
🎲 玩家：Steve