MCDR-BotKikai（Bot機械）

一个基于 MCDR 的 Minecraft 假人管理插件，专注于简化 Carpet 假人的管理和操作。

君は道具ではなく、その名が似合う人になろんだ

📝 简介

本插件旨在解决以下问题：

记不住每个机器的假人名字？
不习惯输入英文指令？
想在家里快速开关远处、其他维度的机器？

只需为每个假人设置中文别名，就能通过简单的中文名字来操控它们。比如，对于一个叫 SandBot 的假人，你可以给它起个别名叫"刷沙机"，这样 !!bk SandBot spawn 和 !!bk 刷沙机 spawn 的效果是完全一样的！也就是说你不需要记住哪个假人控制哪个机器，只需要确认你想开关哪个机器。

你可以在世界的任意位置输入指令 !!bk 刷沙机 use 即可让假人 SandBot 自动在刷沙机处上线，并右键开关来开启刷沙机（顺便挂机）。

上古版本的介绍视频 By: Nachuan川川

🚀 特性

支持假人别名系统（中文、拼音等都可以）
方便的假人位置和朝向记录
交互式的操作界面
支持假人前后缀
支持权限管理
配置文件热重载
配置校验、原子保存和加载失败保护
在线状态同步及后台任务取消

⚙️ 依赖

Python >= 3.10
MCDReforged >= 2.12.0
MinecraftDataAPI >= 1.6.2
Minecraft 服务端需要安装 Carpet 模组

推荐使用 MCDR 2.16.2 和 MinecraftDataAPI 1.6.2；旧环境升级时请先更新上述依赖。插件不要求开启 RCON。

📖 命令说明

基础命令（可于配置文件中自定义）：

!!bk

所有可用命令：

命令	说明	权限等级
!!bk	显示帮助信息	所有人
!!bk list [online	offline]	显示假人列表，可筛选在线或离线
!!bk reload	重载插件配置	admin
!!bk add <name> <kikai>	使用当前玩家位置添加假人	admin
!!bk add <name> <kikai> [dim] [pos] [facing]	使用自定义参数添加假人	admin
!!bk del <kikai>	删除指定假人的记录，不会让已在线假人下线	admin
!!bk <kikai>	显示假人详细信息和操作界面	user

假人操作命令：

命令	说明	权限等级
!!bk <kikai> spawn	在对应位置生成假人	user
!!bk <kikai> kill	移除假人	user
!!bk <kikai> where	显示记录的假人位置，并请求让假人发光2分钟	user
!!bk <kikai> use	假人右键一次	user
!!bk <kikai> huse [<interval>]	假人持续右键，可选间隔时间（gt）	user
!!bk <kikai> atk	假人左键一次	user
!!bk <kikai> hatk [<interval>]	假人持续左键，可选间隔时间（gt）	user
!!bk <kikai> stop	停止假人的所有动作	user

⚡ 快速上手

为刷沙机添加一个假人并设置位置：
```
!!bk add SandBot 刷沙机
```
玩家站在期望的位置和朝向执行此命令，假人的位置和朝向会被自动记录。

假人基础名称只能包含英文字母、数字和下划线；加上前后缀后的游戏名长度须为 3–16。名称和别名不区分大小写，不能与其他假人的名称、游戏名或别名重复。别名不能包含空白，也不能使用管理命令 add、del、list、reload。

你也可以手动指定位置（不建议，挺麻烦的）：
```
!!bk add SandBot 刷沙机 minecraft:overworld 0 64 0 -154.43 3.90
```

使用假人：

!!bk 刷沙机           # 显示假人信息和操作界面
!!bk 刷沙机 spawn     # 召唤假人到记录的位置
!!bk 刷沙机 use       # 让假人右键一次
!!bk 刷沙机 hatk 12   # 让假人每 12gt 左键一次
!!bk 刷沙机 stop      # 让假人停止动作
!!bk 刷沙机 kill      # 让假人下线

⚙️ 配置文件

插件会在 MCDR/config/bot_kikai 目录下创建两个配置文件：

config.json - 插件基础配置：
```
{
    "prefix_short": "!!bk",
    "spawn_max_wait_time": 10.0,
    "spawn_check_interval": 0.5,
    "bot_name_prefix": "",
    "bot_name_suffix": "",
    "permission": {
        "bot": 1,
        "list": 3
    }
}
```
配置项说明：
- prefix_short: 命令前缀
- spawn_max_wait_time: 等待假人生成的最大时间（秒）
- spawn_check_interval: 等待期间检查服务器状态的最大间隔（秒），加入事件会立即唤醒等待
- bot_name_prefix: 在 Carpet 中设置的假人前缀
- bot_name_suffix: 在 Carpet 中设置的假人后缀
- permission.bot: 操作假人的最低权限等级
- permission.list: 管理假人的最低权限等级
两个时间值必须是大于 0 的有限数值，权限值必须是 0–4 的整数。前后缀仅支持英文字母、数字和下划线，总长度不能超过 15。省略的配置项使用默认值，permission 也会逐项补默认值。未知配置项、无效坐标、名称冲突等会导致加载被拒绝，而不是静默重置。

bots.json - 假人数据：

{
    "SandBot": {
        "nicknames": ["SandBot", "刷沙机", "shuashaji"],
        "dimension": "minecraft:overworld",
        "position": [-2.44, 7.0, -5.05],
        "facing": [180.59, 29.55]
    }
}

配置项说明：

nicknames: 假人的所有别名列表
dimension: 假人所在维度
position: 假人的位置坐标 [x, y, z]
facing: 假人的朝向角度 [水平角, 垂直角]

重载与数据保护

修改配置或假人数据后执行 !!bk reload。两个文件全部验证通过后才应用；从 bots.json 删除的记录会同步移除，游戏名未改变的在线状态会保留，并异步查询实际在线玩家列表。
修改 prefix_short 后需要执行 !!MCDR plugin reload bot_kikai。 普通配置重载会明确拒绝此次变更并保留原配置，避免出现按钮前缀和已注册命令不一致。
文件无效时不会覆盖原文件；如果 bots.json 无法加载，添加、修改、删除及保存会暂停，修复文件并成功重载后恢复。已有有效内存状态仍可用于操作假人。
文件使用临时文件加原子替换保存，并串行提交修改。旧格式迁移会先备份，且不会覆盖内容不同的现有 bots.json。
重载、卸载、删除记录或服务器停止时，会取消对应的未完成动作，避免旧任务稍后继续执行。后台并发限制为 4 个任务，运行及排队任务合计最多 32 个，队列满时会提示重试。
召唤需要收到上线事件或在线列表确认才算成功；超时不会继续发送后续动作。右键、攻击、下线等只能确认请求已发送，实际结果请结合游戏和 Carpet 日志判断。

🔒 权限系统

插件使用 MCDR 的权限系统，默认配置：

假人操作权限（spawn、use、kill 等）：需要 user 及以上权限
假人管理权限（add、remove 等）：需要 admin 及以上权限

权限等级对应关系：

guest = 0
user = 1
helper = 2
admin = 3
owner = 4

📝 注意事项

关于前后缀配置：
- 如果服务器开启了假人前后缀，请务必在本插件配置文件中配置相同的前后缀，以防止预期之外的情况发生；
- 如果服务器没有开启假人前后缀，您依然可以配置本插件的前后缀，这样由本插件创建的假人都会带有配置的前后缀。
关于命令点击执行：
- 自 Minecraft 1.19.1-rc1 起，由于游戏安全性更新，点击聊天框中的命令按钮将无法直接执行非 / 开头的命令
- 这影响了 MCDR 插件的交互体验，包括本插件在内的绝大部分插件都改用了 suggest_command（命令建议）模式
- 点击命令按钮后，命令会被填充到聊天框中，需要玩家手动按回车执行
- 这也带来了一个好处：对于类似 !!bk <kikai> huse [间隔gt] 这样需要自定义参数的命令，玩家可以在发送前修改参数
- 具体详见 MCDReforged #203
对于某些版本的 Carpet 模组，假人可能无法操作拉杆，建议替换成音符盒式开关或其他支持假人右键的方式。
如果旧数据存在重复别名、非标准游戏名或无效字段，请先调整数据再升级；校验失败时原文件会保留。位置显示的是登记位置，不会实时跟踪假人被移动后的坐标。

🧪 开发与测试

python -m pip install -r requirements-dev.txt
python -m pytest -q
python -m mcdreforged pack

回归测试覆盖配置保护、并发保存、在线状态同步、召唤超时、生命周期取消及命令解析。CI 矩阵覆盖最低支持的 MCDR 2.12.0 和 MCDR 2.16.2，并在发布打包前运行测试；它们不替代实际 Minecraft/Carpet 环境中的验证。

⚠️ 声明

本插件实现的功能只要是装了 Carpet Mod 能召唤假人的服务端都可以实现，即便是这样也仍有可能引发不香草争议。烦请想装本插件的腐竹实装前务必了解下成员们的意愿。

🤝 致谢

感谢 Fallen_Breath 开发的 MCDR 框架
感谢 Carpet 模组提供的假人功能
感谢 AnzhiZhang 的 Bot 插件提供的灵感

📄 开源协议

GPL-3.0 License