# HuHoBot Spigot 适配器
[](https://github.com/HuHoBot/SpigotAdapter/releases)
[](https://github.com/HuHoBot/SpigotAdapter/blob/main/LICENSE)
[](https://github.com/HuHoBot/SpigotAdapter/actions)
**本 Mod/插件仅适用于使用腾讯 QQ 在中国地区的用户的。**
[简体中文](http://huhobot.txssb.cn/Adapter/Spigot/)
一种新一代 Minecraft 服务器管理机器人解决方案，突破了传统机器人框架的局限，提供更安全、更稳定的交互体验。
## 🌟 核心优势
| 特性 | 传统方案 | HuHoBot |
|-----------------------|--------------------------------------|--------------------------------------|
| 账号安全 | ❌ 需要物理 QQ 账号，存在账号被封禁的风险 | ✅ 无需依赖第三方 QQ 客户端，零风险管控问题 |
| 部署复杂度 | ❌ 需要搭建完整的机器人框架 | ✅ 开箱即用，一键绑定 |
| 服务器兼容性 | ❌ 部分面板服务器不支持 | ✅ 跨平台兼容，只要有网络就能运行 |
| 协议更新影响| ❌ 需要频繁适配新的协议 | ✅ 协议无关设计，相对稳定 |
## 🚀 功能特性
### 核心功能
- **无缝绑定**: 通过 WebSocket 实现服务器与控制终端的即时绑定
- **跨平台支持**: 兼容所有 Spigot/Paper 版本 1.8+
- **智能风险管控规避**: 基于事件驱动的非侵入式通信协议
- **Folia 支持**: 支持 Folia 服务器核心
### 功能列表
📜 点击查看
| 指令 | 描述 |
|------------------|----------------------------------------------|
| /添加白名单 | 向服务器添加白名单条目 |
| /删除白名单 | 从服务器删除白名单条目 |
| /绑定 | 绑定到服务器 |
| /设置名称 | 设置跨服-群组显示名称 |
| /发信息 | 从群组向服务器发送消息 |
| /执行命令 | 向服务器发送命令执行请求 |
| /查白名单 | 查询服务器的内置白名单 |
| /查在线 | 查询服务器上的在线玩家列表 |
| /在线服务器 | 查询在线服务器 |
| /执行 | 执行自定义指令 |
| /管理员执行 | 以管理员权限运行自定义内容 |
### 高级功能
- **扩展 API**
- 自定义指令系统 (详情见下)
## 📥 安装指南
### 环境要求
- Java 8+ 运行时环境
- **任何支持的 Spigot/Paper 核心** (包括但不限于版本 1.8+)
### 快速开始
1. **访问 GitHub 发布页面**:
- 打开浏览器，访问 [HuHoBot-SpigotAdapter 发布](https://github.com/HuHoBot/SpigotAdapter/releases)
- 下载最新的 `HuHoBot-vx.x.x-Spigot.jar` 文件
2. **放置插件文件**:
- 将下载的 `HuHoBot-vx.x.x-Spigot.jar` 文件移动到服务器的 `plugins` 目录
3. **重启服务器**:
- 重启你的 Minecraft 服务器以加载新的插件
4. **添加机器人**:
- [加入支持群](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=N6tVRxGR8sDwYHBx9YgAhkqRTp1gseyk&authKey=M7Fd3Op6nHjXjSXefBtHBPqIq2wtX8AfufZor9DrfRrJkhyS2rohkt7iuOSwbtn8&noverify=0&group_code=1005746321), 点击“HuHo_Bot”的头像并将其添加到群聊中
5. **完成绑定**:
- 按照控制台提示完成服务器与机器人的绑定
### 高级配置 (可选)
- 为了自定义功能，请参考下方的 `⚙️ 配置示例` 获取详细设置
---
#### 注意事项:
- 确保服务器正确安装了 Java 8+ 运行时环境
- 插件兼容所有支持的 Spigot/Paper 核心版本; 请参考官方文档获取特定版本详情
## ⚙️ 配置示例
```yaml
# 忽略此字段
serverId: null
# 忽略此字段
hashKey: null
chatFormat:
from_game: "<{name}> {msg}" # 在游戏消息转发到群组的文本格式
from_group: "群:<{nick}> {msg}" # 群消息转发到服务器的文本格式
post_chat: true # 是否将群消息转发到服务器
post_prefix: "" # 群消息转发到服务器的前缀
motd:
server_ip: "play.hypixel.net" # 用于 "/查在线" 的 MOTD 图像 URL (替换为你的服务器地址)
server_port: 25565 # 用于 "/查在线" 的 MOTD 图像端口 (替换为你的服务器端口)
api: "https://motdbe.blackbe.work/status_img/java?host={server_ip}:{server_port}" # 用于 "/查在线" 的 MOTD 图像 API (除非必要，否则不要修改; 必须返回图像)
text: "共{online}人在线" # 用于 "/查在线" 的 MOTD 文本 (支持 PlaceholderAPI; 留空以隐藏)
output_online_list: true # 是否显示在线玩家列表
post_img: true # 是否显示 MOTD 图像
whiteList:
add: "whitelist add {name}" # 添加白名单条目的命令
del: "whitelist remove {name}" # 删除白名单条目的命令
# 自定义执行指令
customCommand:
- key: "加白名" # 触发关键字; 使用 "/执行 关键词 参数1 参数2" 运行自定义指令
command: "whitelist add &1" # &1 是参数占位符 (第 1 个参数 = &1, 第 2 个 = &2, 等等)
permission: 0 # 0 = 普通权限; 值 > 0 = 管理员权限
- key: "管理加白名"
command: "whitelist add &1"
permission: 1
```
## ❓ 常见问题
🤔 我需要准备 QQ 账号吗？
完全不需要！此解决方案采用全新的通信协议，完全消除了对第三方聊天平台的依赖。
🛡️ 支持哪些服务器版本？
✅ 测试版本: 1.8 - 1.21
✅ 理论上支持所有 Spigot 核心
🔧 如何更新配置？
支持配置热重载: /huhobot reload
💬 群组和服务器之间的跨通信
使用 /发信息 时，可以在 5 分钟内回复消息 5 次; 机器人将优先回复最新的消息。
如果没有可回复的消息，则无法发送消息。
🌐 "/查在线" 是否会显示其他服务器的信息？
请修改配置文件中的 motdUrl 字段为你的服务器地址。
示例: motdUrl: "play.yourserver.com:25565"
🔍 使用 "/查在线" 时没有响应？
排查步骤:
1. 检查连接状态并使用 /huhobot reconnect 重新连接
2. 尝试清除 motdUrl 字段: "motdUrl": ""
⌨️ 执行指令时没有响应？
注意指令格式的区别:
- /执行 加白 → 用于自定义指令回调
- /执行命令 list → 向控制台发送命令
👥 允许玩家将自己添加到白名单？
在配置文件中配置 customCommand 字段，如配置示例所示。
用法: /执行 加白 "玩家ID" (带有空格的参数请用引号括起来)
👮 如何设置管理员？
在群组中使用命令:
/管理帮助 → 查看管理员命令列表
🏰 是否支持多服务器？
当前版本仅支持每个群组绑定一个服务器。多服务器绑定正在开发中。
为了管理多个服务器，建议为每个服务器创建单独的群组。
### 配置自定义指令
#### 通过配置文件设置
在 `config.yml` 文件中，您可以通过 `customCommand` 字段定义自定义指令。每个自定义指令包括以下属性：
- **key**: 触发指令的关键字 (字符串)
- **command**: 要执行的实际服务器命令 (字符串)
- **permission**: 权限级别 (整数)
配置示例：
```yaml
customCommand:
- key: "加白名" # 触发关键字; 使用 "/执行 关键词 参数1 参数2" 运行自定义指令
command: "whitelist add &1" # &1 是参数占位符 (第 1 个参数 = &1, 第 2 个 = &2, 等等)
permission: 0 # 0 = 普通权限; 值 > 0 = 管理员权限
- key: "管理加白名"
command: "whitelist add &1"
permission: 1
```
#### 查看开发文档
有关更详细的开发指南和高级功能，请参考 [开发文档](docs/develop.md)。
## 📄 开源协议
[GNU 通用公共许可证 v3.0](LICENSE) - 免费使用、修改和分发，但受以下条款约束：
- **开源义务**: 所有衍生作品必须保持开源
- **相同许可证**: 修改后的版本必须使用相同的许可证
- **版权声明**: 必须保留原始版权声明
有关许可证全文，请参见 [LICENSE](LICENSE) 文件。
## 🤝 贡献
欢迎通过 PR 提交贡献。您也可以通过 [讨论](https://github.com/HuHoBot/SpigotAdapter/discussions) 提出建议。
