Skip to content

README.md

Latest commit

 

History

History
288 lines (234 loc) · 11.1 KB

README.md

File metadata and controls

288 lines (234 loc) · 11.1 KB
Raw

PenguinServer-Fabric

HuHoBot Penguin 的 Fabric 服务端模组，直连 QQ 官方机器人网关，实现 QQ 群与 Minecraft Java 版服务器的双向消息桥接。

功能特性

✅ 0封号风险 - 使用QQ官方Bot接口
✅ 双向消息转发 - 游戏聊天转发到 QQ 群，QQ 群消息广播到游戏内
✅ 进退服通知 - 玩家进服/退服自动推送到 QQ 群
✅ 40+ 内置群命令 - 查在线、白名单管理、管理员管理、MOTD查询、群管理、面板同步等
✅ MOTD 查询 - /motd <IP:端口> 查询任意服务器状态，支持图片展示
✅ 全量模式优化 - 自动识别图片、语音、表情、视频等多媒体内容
✅ 白名单自助绑定 - QQ 用户自助绑定游戏名并自动加入白名单
✅ 管理员系统 - 支持 QQ 群管理员 / 手动管理员 / 双重模式
✅ 敏感词过滤 - 正则过滤 + 词库过滤，可选 OpenAI 兼容二审
✅ 自定义命令 - 支持参数占位符的自定义群命令
✅ QQ 指令面板 - 自动同步命令到QQ官方指令面板，支持命令补全
✅ 全量转发 - 可按群开启非命令消息广播到游戏
✅ 中文域名支持 - server-ip 支持中文域名，自动转换为 ASCII
✅ 直接执行 MC 命令 - /执行命令 管理员可直接执行任意服务器命令
✅ QQ 群管理 - 禁言、踢人、黑名单、入群审批等 13 个管理接口
✅ 群成员事件 - 进群/退群/入群申请实时通知
✅ 互动事件 - Markdown 消息按钮，5 秒内响应回执
✅ 附属插件 - 往 config/penguin-addons/ 丢 jar 即可扩展，支持热重载
✅ 扫码绑定 - 终端二维码完成凭据绑定，无需手改配置文件

环境要求

支持以下 Minecraft 版本：

Minecraft 版本 JAR 文件
1.20.1 ~ 1.21.10 penguin-server-fabric-*-mc1.20.1.jar（需 Java 21+）
1.21.11 penguin-server-fabric-*-mc1.21.11.jar（需 Java 21+）
26.1+ penguin-server-fabric-*-mc26.2.jar（需 Java 25+）
  • Fabric Loader: 0.16.0+
  • Fabric API: 对应 MC 版本的最新版
  • Fabric Language Kotlin: 1.13.0+
  • QQ 开放平台机器人（需提审上线后才能收到群事件）

安装方法

  1. 确保已安装 Fabric Loader
  2. 下载并安装以下依赖模组（对应你的 MC 版本）：
  3. 将对应版本的 jar 放入服务器 mods/ 目录
  4. 启动服务器，生成配置文件后关闭
  5. 编辑 config/penguin-server.json，填入机器人凭据
  6. 重新启动服务器

配置文件

首次启动后自动生成 config/penguin-server.json：

{
  "bot": {
    "app-id": "你的 AppID",
    "secret": "你的 Secret",
    "name": "HuHoBot",
    "groups": ["群的 group_openid"]
  },
  "serverName": "我的服务器",
  "chat-format": {
    "from-game": "[游戏] {name}: {message}",
    "from-group": "[QQ] {name}: {message}",
    "post-chat": true,
    "start-with": ""
  },
  "whitelist": {
    "add-command": "whitelist add {name}",
    "del-command": "whitelist remove {name}"
  },
  "join-leave": {
    "enabled": true,
    "join-format": "[{server}] 🟢{name}进入服务器",
    "leave-format": "[{server}] 🔴{name}退出服务器"
  },
  "motd": {
    "server-ip": "你的服务器 IP 或域名",
    "server-port": 25565,
    "api": "https://motd.txssb.cn/api/status_img?theme=simple&ip={ip}&port={port}&dark=true&lang=zh-CN",
    "text": "[{server}] 在线玩家：{online}\n{players}",
    "post-img": false,
    "use-markdown": false
  },
  "admin": {
    "mode": "both",
    "openids": []
  },
  "audit": {
    "base-url": "",
    "api-key": "",
    "model": "gpt-4o-mini"
  }
}

主要配置项

配置项 说明
bot.app-id QQ 开放平台机器人 AppID
bot.secret QQ 开放平台机器人 Secret
bot.groups 监听的 QQ 群 group_openid 列表（空 = 所有群）
serverName 服务器名称（用于进退服消息）
chat-format.start-with 游戏消息转发到 QQ 所需的前缀（空 = 全部转发）
motd.server-ip 服务器 IP 或域名，支持中文域名
motd.post-img /查在线 是否发送 MOTD 图片（true/false）
motd.api MOTD 图片 API 地址，支持 {ip} {port} 占位符
motd.use-markdown /查在线 是否使用 Markdown 格式（true/false）
admin.mode 管理员模式：qq/manual/both
audit.base-url OpenAI 兼容接口地址（留空则不启用 AI 二审）
qq.intents QQ 网关订阅位。0 = 按 intents-auto 自动决定；填具体数字则原样使用
qq.intents-auto true（默认）= 自动订阅群消息 + 群成员事件 + 互动事件；false = 只订阅群消息
group-event.to-game 群成员进退群事件是否转发到游戏内
group-event.join-request-to-game 入群申请事件是否转发到游戏内
group-api.admin-only 群管理命令是否仅限管理员（默认 true）

入群申请事件需要机器人在群里也是管理员，否则 QQ 不会下发 GROUP_JOIN_REQUEST，即使 intents 开了也收不到。

附属插件配置

插件目录固定为 config/penguin-addons/，不支持自定义路径。无额外配置项。

MOTD 图片配置

/查在线 命令支持四种显示模式（优先级从高到低）：

  1. Markdown + 图片模式（use-markdown = true 且 post-img = true）：推荐，Markdown 卡片内嵌 MOTD 图片
  2. 纯图片模式（use-markdown = false 且 post-img = true）：文本 + MOTD 图片
  3. 纯 Markdown 模式（use-markdown = true 且 post-img = false）：仅 Markdown 格式
  4. 纯文本模式（两者都为 false）：显示原始 list 命令输出

推荐 API（默认）：

https://motd.txssb.cn/api/status_img?theme=simple&ip={ip}&port={port}&dark=true&lang=zh-CN

注意：简幻欢（Simpfun）服务器可能无法使用 MOTD 图片查询。

内置群命令

@机器人 发送以下命令：

命令 权限 说明
查在线 所有人 查看在线玩家列表
MOTD 所有人 查看指定服务器的MOTD
在线服务器 所有人 查看服务器是否在线
查信息 所有人 查看自己的 OpenID 和认证状态
发消息 <内容> 所有人 广播消息到游戏
绑定白名单 <游戏名> 所有人 自助绑定并加入白名单
解除绑定 所有人 解除绑定并移出白名单
认证 所有人 查看/申请认证状态
添加白名单 <玩家名> 管理员 直接添加白名单
删除白名单 <玩家名> 管理员 移除白名单
查白名单 管理员 查看白名单列表
解绑白名单 <玩家名> 管理员 解绑指定玩家并移出白名单
加管理 <OpenID> 管理员 添加手动管理员
删管理 <OpenID> 管理员 删除手动管理员
查管理 管理员 查看管理员列表
管理方式 <QQ/手动/双重> 管理员 设置管理员认定方式
全量 <开/关> 管理员 开关全量消息转发到游戏
同步面板 管理员 手动同步QQ指令面板
刷新 管理员 手动同步QQ指令面板
重载 管理员 重载配置并重启网关
执行命令 <MC命令> 管理员 直接执行任意服务器命令（如 执行命令 list）
认证 <OpenID> 管理员 认证指定用户
解除认证 所有人 解除自己的认证

群管理命令

需要群管理员身份（且机器人本身得有管理权限）。

命令 说明
群信息 查看本群名称、成员数、机器人入群与闭麦状态
群成员 查看群成员列表
查成员 <OpenID> 查询指定成员的入群时间、消息数
禁言 <分钟> 全群禁言，0 为解除。上限 30 天
踢人 <OpenID> 把成员移出本群
入群申请 列出待处理的入群申请
同意入群 <OpenID> 同意入群
拒绝入群 <OpenID> 拒绝入群
群黑名单 查看本群黑名单
拉黑 <OpenID> 加入黑名单
移出黑名单 <OpenID> 移出黑名单
撤回 撤回触发该条命令的消息（受 QQ 的 2 分钟窗口限制）
扫码绑定 终端显示二维码，扫码完成凭据绑定

附属插件命令

命令 权限 说明
附属插件 所有人 列出已加载的附属插件及其命令
重载插件 管理员 重新加载 config/penguin-addons/ 下的所有 jar

附属插件

往 config/penguin-addons/ 丢一个 jar 就能扩展功能，不需要放进 mods/。

仓库里的 sample-addon/ 是完整可构建的示例工程（cd sample-addon && ./gradlew jar）， 开发文档见 ADDON-DEV-GUIDE.md。

最小示例：

class MyAddon : AddonProvider {
    override val meta = Addon(name = "myaddon", version = "1.0.0")

    override fun onLoad(api: AddonApi) {
        api.registerCommand("你好", "打招呼") { ctx ->
            ctx.reply("你好，${ctx.displayName}")
        }
    }
}

入口类在 jar 根目录的 penguin-addon.json 里声明：

{ "mainClass": "你的包名.你的类名" }

装好后 QQ 群发 重载插件，或控制台 /penguin addons reload。

几个规则：

  • 内置命令优先，插件不能覆盖已有命令（registerCommand 返回 false）
  • 命令名匹配按长度降序，添加白名单 不会被 添加 抢先
  • 每条插件命令会同步到 QQ 指令面板，但面板上限 20 项，排序是内置优先、插件补足； 插件命令多于剩余槽位时会被挤出面板，但仍能手动发命令调用
  • 1.20.1 与 26.2 两个分支的 API 签名相同，同一份插件代码可以原样跑两边

服务端命令

需要 OP 权限（权限等级 4）：

/penguin reload        重载配置并重启 QQ 网关
/penguin info          查看模组状态
/penguin send <消息>   手动向所有配置的群发送消息
/penguin sync          手动同步QQ指令面板
/penguin addons        列出已加载的附属插件
/penguin addons reload 重载附属插件

/huhobot <子命令>      同 /penguin <子命令>

自定义命令

在配置文件 custom-commands 中配置：

"custom-commands": [
  {
    "key": "天气",
    "command": "weather clear",
    "permission": 0
  },
  {
    "key": "踢人",
    "command": "kick {0}",
    "permission": 1
  }
]

占位符：{params} 全部参数、{0} {1} 第 N 个参数、{group} 群 OpenID、{user} 用户 OpenID

构建

./gradlew build

相关项目

开源许可

AGPL3.0 License