命令与权限

白名单管理命令 /shitbot whitelist 适用于全部平台，需要 shitbot.admin。使用 /shitbot whitelist add - Steve 添加无 QQ 白名单，使用 /shitbot whitelist add 123456789 Steve 直接添加 QQ 绑定。 删除、分页和 QQ 查询的完整语法见插件 API 与白名单管理。

管理命令

主命令为 /shitbot，别名为 /sbot。

命令	功能	权限
/shitbot status	查看数据库、OneBot 和运行状态	无
/shitbot reload	重载配置、数据库、OneBot、图片和命令服务	shitbot.admin
/shitbot update	下载并安装当前平台的新版本	shitbot.admin
/shitbot image	手动生成在线状态图片	shitbot.admin
/shitbot editor	生成高级图片模板编辑器的短时一次性登录地址	shitbot.admin
/shitbot migrate easybot [EasyBot.db]	导入 EasyBot 绑定数据	shitbot.admin

Spigot 和 Nukkit-MOT 默认仅 OP 拥有 shitbot.admin。BungeeCord 与 Velocity 使用平台权限系统检查同名权限。

/shitbot reload 会先创建新的运行实例；新配置加载失败时保留旧实例。插件 JAR 更新、Java 变更和 TLS 文件变更仍建议正常重启。

QQ 绑定

默认别名：

绑定 <游戏ID> <验证码>
/bind <游戏ID> <验证码>

验证码由未绑定玩家进入服务器时生成。QQ 和游戏 ID 的绑定规则由 binding 配置控制。

在线状态与背包

默认指令：

服务器状态
在线人数
背包
我的背包
背包 <游戏ID>
我的背包 <游戏ID>
个人资料
个人资料 <游戏ID>

指定游戏 ID 查询背包时，ShitBot 会确认该角色已绑定到消息发送者的 QQ，不能查询他人的角色。 个人资料同样只允许查询发送者自己绑定的角色；不带参数时使用最新绑定角色。个人资料图片左侧显示皮肤，右侧内置显示权限组、点券和累计在线时长。权限组和点券通过配置的 PlaceholderAPI 变量获取，变量不可用或为空时会自动隐藏；累计在线时长写入 shitbot_player_stats 表。

TPS 指令

TPS 在 commands.yml 中配置：

tps:
  enabled: true
  permission: ""
  server: ""

别名、成功文本和失败文本在所选语言文件的 console.tps 中配置。

• 单服部署和 Nukkit-MOT 在本服查询。
• 代理部署可以在 server 中设置默认子服。
• 群成员也可以在指令后指定子服，例如 TPS survival。
• permission 为空时不检查游戏权限，但仍受群范围和命令冷却限制。

QQ 快捷命令

每个快捷命令放在 commands.yml 的 shortcuts 下：

shortcuts:
  luckperms-editor:
    enabled: true
    command: "lp editor"
    permission: "shitbot.admin"
    allow-unbound: false
    target: "backend"
    server: ""
    capture-seconds: 5

内置快捷命令的别名和回复模板在语言文件的 console.shortcuts.<名称> 中配置。新增自定义快捷命令时，如果语言文件中没有同名条目，会使用 commands.yml 中的 aliases、message 和 failed 作为后备。

配置	说明
aliases	QQ 群内触发文本
command	去掉前导 / 的控制台命令
permission	绑定角色必须拥有的游戏权限；留空表示跳过游戏权限检查
allow-unbound	是否允许未绑定 QQ 调用；默认关闭
target	backend 在 Bukkit 子服执行，proxy 在 BungeeCord/Velocity 执行
server	默认目标子服；留空时优先使用绑定角色所在子服
capture-seconds	执行后等待并收集新增控制台日志的时间

即使 permission 为空，默认仍要求发送者已经绑定游戏角色。只有明确设置 allow-unbound: true 才允许未绑定群成员执行，该配置会降低权限边界，应谨慎使用。

群成员可以在快捷命令后指定目标子服，例如：

lp编辑 survival

该参数会覆盖命令中的 server。

QQ 高级图片命令

高级图片模板不自行注册命令。每个群入口必须在 commands.yml 的 image-templates.commands 中明确声明：

image-templates:
  commands:
    player-card:
      enabled: true
      aliases:
        - "我的名片"
      template: "player-card"
      player-source: "argument"
      target-server: "survival"
      permission: "shitbot.image.player-card"
      cooldown-seconds: 10
      usage: "%at% 用法：我的名片 <已绑定角色名>"
      failed: "%at% 图片生成失败：%result%"

配置	说明
aliases	群内触发文本；应避免与内置指令、TPS 或快捷命令重复
template	要渲染的已发布模板 ID
player-source	bound 取最新绑定，argument 校验命令参数属于发送者，none 不读取绑定
target-server	代理部署中处理权限与 PAPI 的 Spigot 后端
permission	所选绑定角色必须拥有的游戏权限；留空跳过权限检查
cooldown-seconds	该模板命令独立的群号＋QQ 冷却
usage / failed	参数错误与生成失败回复；支持 %at%、%result%、%command% 和 %server%

权限请求只判断权限，不执行控制台命令。player-source: none 与非空 permission 不能组合成有效授权，因为没有游戏角色可供校验。该功能还要求 config.yml 中 custom-image-templates.enabled: true；完整说明见图片渲染与高级模板。

权限检查顺序

Spigot 后端执行带 permission 的快捷命令时：

1. 角色在线时使用 Bukkit 权限系统；
2. 角色离线时依次尝试 LuckPerms、Vault 和离线 OP 状态。

代理本地命令使用代理权限系统；离线权限可由代理上的 LuckPerms 提供。Nukkit-MOT 在线角色使用 Nukkit 权限系统，离线角色使用 LuckPerms（如已安装）。

命令输出

快捷命令执行前会记录日志位置，等待 capture-seconds 后读取这段时间新增的内容：

• Bukkit 使用 logs/latest.log；
• Nukkit-MOT 使用 logs/server.log；
• 原始日志文件不会被修改；
• 单次回复最多保留 100 行、4000 个字符；
• 玩家聊天、上下线、执行命令等日志会从回复副本中移除；
• 玩家名、UUID、IP、Token、密码和数据库地址会在回复副本中脱敏。

执行成功但没有产生新日志时，机器人会返回明确提示。

修改后生效

保存 commands.yml 或语言文件后执行：

/shitbot reload

如果是代理—后端部署，代理和相关后端的配置都修改完成后再分别重载。通道地址、证书或防火墙发生变化时建议重启。