功能详解¶

本文档详细介绍 GUGUBot 的所有功能及其使用方法。

命令前缀¶

所有命令默认使用 # 作为前缀，可在配置文件中修改：

GUGUBot:
  command_prefix: "#"

通用命令¶

帮助系统¶

获取命令帮助信息。

#帮助

普通用户：显示可用的基础功能
管理员：显示所有管理功能

聊天转发系统¶

功能介绍¶

聊天转发是 GUGUBot 的核心功能，实现游戏内外的消息互通。

消息转发方向¶

QQ → MC：

[QQ] 张三: 有人在线吗？

MC → QQ：

[服务器名] Steve: 我在！

支持的消息类型¶

文本消息¶

普通文本会直接转发，支持： - 中英文 - 表情符号 - 特殊字符

图片消息¶

QQ 发送的图片会以链接形式显示在游戏内：

[QQ] 张三: [图片: https://...]

如果安装了以下插件，可以在游戏内预览图片： - ChatImage - 配置 chat_image: true - ImagePreview - 配置 image_previewer: true

QQ 表情¶

QQ 表情会转换为对应的文字描述：

[QQ] 张三: [呲牙]

游戏事件转发¶

以下游戏事件会自动转发到 QQ：

✅ 玩家加入/离开
✅ 玩家死亡消息
✅ 玩家获得成就
✅ 服务器启动/停止

可在配置文件中单独控制每种事件：

connector:
  minecraft:
    mc_achievement: true
    mc_death: true
    player_join_notice: true
    player_left_notice: true
    server_start_notice: true
    server_stop_notice: true

消息过滤¶

可以过滤不需要转发的消息：

connector:
  minecraft:
    ignore_mc_command_patterns:
      - "!!.*"                    # 忽略 MCDR 指令
      - ".*?\\[Command: /.*\\]"   # 忽略 Carpet 指令记录

启用/禁用转发¶

管理员可以临时关闭转发：

#转发 关闭   # 关闭转发
#转发 开启   # 开启转发

玩家绑定系统¶

绑定账号¶

绑定 Java 版¶

#绑定 Steve

绑定基岩版¶

gugubot 会尝试调用 Floodgate 来添加白名单（如启动绑定时添加白名单）

#绑定 Steve1234 基岩

或使用其他关键词： - 基岩 / bedrock / be - true / 1

管理员为他人绑定¶

#绑定 @某人 PlayerName

或使用 QQ 号：

#绑定 @1234567890 PlayerName 基岩

解绑账号¶

解绑自己的账号¶

#解绑              # 解绑所有 Java 版账号
#解绑 基岩         # 解绑所有基岩版账号
#解绑 Steve        # 解绑指定玩家
#解绑 Steve 基岩   # 解绑指定基岩版玩家

管理员解绑他人¶

#解绑 @某人
#解绑 @某人 PlayerName

查看绑定信息¶

查看自己的绑定¶

#绑定 列表

回复示例：

您的绑定列表:
Java版:
  - Steve
基岩版:
  - Steve1234

查询他人的绑定¶

#绑定 查询 @某人
#绑定 查询 Steve
#绑定 查询 1234567890

绑定限制¶

可在配置文件中设置每个账号最多可绑定的数量：

system:
  bound:
    max_java_bound: 1    # 最多绑定 1 个 Java 版账号
    max_bedrock_bound: 1 # 最多绑定 1 个基岩版账号

自动白名单¶

启用后，绑定账号时自动添加到服务器白名单：

system:
  bound:
    whitelist_add_with_bound: true

退群解绑¶

启用后，玩家退群时自动解除绑定和白名单：

system:
  bound:
    whitelist_remove_with_leave: true

系统管理¶

#绑定 开启   # 启用绑定系统
#绑定 关闭   # 禁用绑定系统

白名单管理¶

添加白名单¶

Java 版（在线模式）¶

#白名单 添加 Steve online

或使用别名：正版 / 在线

Java 版（离线模式）¶

#白名单 添加 Steve offline

或使用别名：离线

基岩版¶

#白名单 添加 Steve1234 bedrock

或使用别名：基岩 / be

默认模式¶

如果不指定模式，使用服务器目前的模式（正版验证开/关）：

#白名单 添加 Steve

删除白名单¶

#白名单 删除 Steve

查看白名单¶

#白名单 列表

启用/禁用白名单¶

#白名单 开启   # 启用服务器白名单
#白名单 关闭   # 禁用服务器白名单

关键词回复¶

添加关键词¶

添加文本回复¶

#添加 你好

机器人回复：请发送您想要添加的关键词/图片

然后发送回复内容：

你好呀！欢迎来到服务器~

添加图片回复¶

#添加 服务器地图

然后发送一张图片。

删除关键词¶

#删除 你好

查看关键词列表¶

#关键词 列表

取消添加¶

如果在添加过程中想取消：

#取消

超时设置¶

关键词添加有时间限制（默认 30 秒），可在配置文件中修改：

system:
  key_words:
    max_add_time: 30

系统管理¶

#关键词 开启   # 启用关键词系统
#关键词 关闭   # 禁用关键词系统

违禁词管理¶

添加违禁词¶

#违禁词 添加 不良词汇 理由说明

删除违禁词¶

#违禁词 删除 不良词汇

查看违禁词列表¶

#违禁词 列表

违禁词触发¶

当消息包含违禁词时：

消息不会转发
发送者收到提示（含违禁理由）
管理员收到通知（可选）

系统管理¶

#违禁词 开启   # 启用违禁词系统
#违禁词 关闭   # 禁用违禁词系统

命令执行系统¶

执行 MC 命令¶

#执行 say 大家好！
#执行 give @a diamond 1

执行 MCDR 命令¶

#mcdr plugin list
#mcdr backup make

跨服执行（多服互联）¶

#执行@服务器1 say 来自主服的消息
#mcdr@服务器2 backup make

命令过滤¶

出于安全考虑，可以配置忽略某些命令：

system:
  execute:
    ignore_execute_command_patterns:
      - ".*?give.*?"    # 忽略 give 指令
      - ".*?op.*?"      # 忽略 op 指令

系统管理¶

#执行 开启   # 启用命令执行
#执行 关闭   # 禁用命令执行

安全提示： - 命令执行功能仅管理员可用 - 建议谨慎配置管理员权限 - 建议启用命令过滤

风格系统¶

查看可用风格¶

#风格 列表

切换风格¶

#风格 可爱
#风格 正经
#风格 沙雕

重载风格¶

添加新风格文件后，需要重载：

#风格 重载

自定义风格¶

在 config/GUGUbot/style/ 目录下创建 .yml 文件：

示例 config/GUGUbot/style/可爱.yml：

gugubot:
  system:
    bound:
      bind_success: "绑定成功啦~ ✨"
      unbind_success: "已经解绑啦~ 👋"
    key_words:
      name: "喵" # 默认: "关键词"
      add: "喵" # 默认: "添加"

命令也可以更改，如上述关键词添加指令会从 #关键词添加 <关键词> 变成 #喵喵 <关键词>

风格切换冷却¶

防止频繁切换，可设置冷却时间：

style:
  style_cooldown: 60  # 60 秒冷却

待办管理¶

添加待办¶

#待办 添加 周末组织活动

完成待办¶

#待办 完成 1

（1 是待办的 ID）

撤回完成¶

#待办 撤回 1

删除待办¶

#待办 删除 1

查看待办列表¶

#待办 列表

回复示例：

未完成待办:
[1] 周末组织活动
    创建者: 张三 (123456)
    时间: 2024-01-01 10:00:00

已完成待办:
[2] 修复服务器BUG
    创建者: 李四 (654321)
    时间: 2024-01-01 09:00:00
    完成时间: 2024-01-01 11:00:00

玩家列表查询¶

查询在线玩家¶

#玩家
#在线
#player
#online

回复示例：

在线玩家(3): Steve, Alex, Notch

多服查询¶

如果启用了多服互联，会同时查询所有服务器的在线玩家：

[主服] 在线玩家(3): Steve, Alex, Notch
[生存服] 在线玩家(2): Mike, John
[创造服] 在线玩家(1): Admin

系统要求¶

开启 RCON 连接

开启步骤如下: 1. 修改 服务器根目录/config.yml - rcon - enable -> false - 记录 rcon - password 和 rcon - port 2. 修改 服务器根目录/server/server.properties - enable-rcon -> true - rcon.password -> 记录的 password - rcon.port -> 记录的 port

RCON 的端口不要跟游戏端口冲突

启动指令¶

添加启动指令¶

#启动指令 添加 gamerule keepInventory true

删除启动指令¶

#启动指令 删除 gamerule keepInventory true

查看启动指令¶

#启动指令 列表

手动执行启动指令¶

#启动指令 执行

自动执行¶

服务器启动时，会自动执行所有启动指令。

不活跃玩家检查¶

手动检查¶

#不活跃检查 检查

查看下次检查时间¶

#不活跃检查 下次检查

检查规则¶

系统会检查以下两类玩家：

不活跃玩家：曾经进入过游戏，但超过指定天数未登录
从未游玩：绑定后超过指定天数仍未进入游戏

通知配置¶

system:
  inactive_check:
    inactive_days: 30       # 不活跃天数阈值
    never_played_days: 7    # 从未进入游戏的天数阈值
    notify_targets:
      admin_private: true   # 私聊管理员
      admin_groups: true    # 发送到管理群
      origin_group: false   # 发送到原群

系统管理¶

#不活跃检查 开启
#不活跃检查 关闭

未绑定用户检查¶

手动检查¶

#未绑定检查 检查

查看下次检查时间¶

#未绑定检查 下次检查

检查规则¶

检查入群后超过指定天数仍未绑定游戏账号的用户。

通知配置¶

system:
  unbound_check:
    timeout_days: 7         # 入群后未绑定的超时天数
    notify_targets:
      admin_private: true   # 私聊管理员
      admin_groups: true    # 发送到管理群
      origin_group: false   # 发送到原群

系统管理¶

#未绑定检查 开启
#未绑定检查 关闭

绑定提醒¶

功能介绍¶

当未绑定的用户在群内发言时，自动发送绑定提醒。

系统管理¶

#绑定提醒 开启
#绑定提醒 关闭

权限系统¶

权限等级¶

GUGUBot 有以下权限等级：

普通用户 - 群成员
管理员 - 配置中指定的管理员

管理员配置¶

通过 QQ 号指定¶

connector:
  QQ:
    permissions:
      admin_ids:
        - 1234567890
        - 9876543210

通过管理群指定¶

管理群内所有成员自动拥有管理权限：

connector:
  QQ:
    permissions:
      admin_group_ids:
        - 111111111

好友自动管理¶

机器人的所有好友自动拥有管理权限：

connector:
  QQ:
    permissions:
      friend_is_admin: true

管理员专用功能¶

以下功能仅管理员可用：

✅ 命令执行
✅ 违禁词管理
✅ 为他人绑定/解绑
✅ 白名单管理
✅ 启动指令管理
✅ 不活跃/未绑定检查
✅ 系统开关控制

群管理模式¶

启用后，所有群指令都需要管理员权限：

GUGUBot:
  group_admin: true

命令速查表¶

通用命令¶

命令	说明	权限
`#帮助`	显示帮助信息	所有人

绑定相关¶

命令	说明	权限
`#绑定 <玩家名> [基岩]`	绑定账号	所有人
`#绑定 @用户 <玩家名> [基岩]`	为他人绑定	管理员
`#解绑 [玩家名] [基岩]`	解绑账号	所有人
`#绑定列表`	查看绑定列表	所有人
`#绑定查询 <玩家名/QQ>`	查询绑定信息	所有人

白名单相关¶

命令	说明	权限
`#白名单添加 <玩家> [模式]`	添加白名单	管理员
`#白名单删除 <玩家>`	删除白名单	管理员
`#白名单列表`	查看白名单	管理员
`#白名单开启/关闭`	启用/禁用白名单	管理员

关键词相关¶

命令	说明	权限
`#添加 <关键词>`	添加关键词	所有人
`#删除 <关键词>`	删除关键词	所有人
`#关键词列表`	查看关键词列表	所有人
`#取消`	取消添加关键词	所有人

命令执行¶

命令	说明	权限
`#执行 <命令>`	执行 MC 命令	管理员
`#mcdr <命令>`	执行 MCDR 命令	管理员
`#执行@<服务器> <命令>`	跨服执行	管理员

风格系统¶

命令	说明	权限
`#风格列表`	查看可用风格	所有人
`#风格 <风格名>`	切换风格	所有人
`#风格重载`	重载风格	管理员

待办管理¶

命令	说明	权限
`#待办添加 <内容>`	添加待办	所有人
`#待办完成 <ID>`	完成待办	所有人
`#待办撤回 <ID>`	撤回完成	所有人
`#待办删除 <ID>`	删除待办	所有人
`#待办列表`	查看待办列表	所有人

查询功能¶

命令	说明	权限
`#玩家` / `#在线`	查询在线玩家	所有人

使用技巧¶

自定义消息模板¶

在配置中设置多个消息模板，系统会随机使用：

connector:
  QQ:
    chat_templates:
      - "({display_name}) {sender}: "
      - "[{display_name}] {sender}: "
      - "{display_name} | {sender} 说："

正则表达式过滤¶

使用正则表达式精确控制消息过滤：

ignore_mc_command_patterns:
  - "^!!.*"           # 以 !! 开头
  - ".*\\[Command.*"  # 包含 [Command
  - "^/.+"            # 以 / 开头的命令

下一步¶

配置说明 - 了解详细配置选项
API 文档 - 开发自定义功能
疑难解答 - 解决使用问题