AstrBot Adapter

一个用于连接 Minecraft 服务器和 AstrBot 的插件，支持消息互通、服务器状态监测和远程指令执行。

Important

本仓库是 railgun19457/AstrBotAdapter 的 EllanServer 下游维护版，用于保留本服适配、MineSentinel 观察上报和兼容性改动。同步上游时请优先对比上游 main 分支。

特性

• ✅ 消息互通 - 服务器聊天消息转发至 AstrBot，AstrBot 也可以发送消息至服务器，支持发送者信息
• ✅ Token 鉴权 - 安全的 Token 认证机制
• ✅ 服务器状态监控 - 实时监测玩家信息、TPS、内存使用等
• ✅ 远程指令执行 - 通过外部接口执行服务器指令
• ✅ 玩家事件通知 - 玩家加入/离开通知
• ✅ 游戏内AI聊天 - 支持AI聊天，可区分群聊/私聊
• ✅ MineSentinel 观察上报 - 只读采集聊天、玩家事件和服务器指标，批量上报给 AstrBot 侧分析

Note

孪生项目:Minecraft适配器
AstrBot插件，用于对接本插件，实现群服互通等功能

兼容性

支持的平台

平台	版本	下载
Bukkit/Paper/Spigot/Folia	1.20.x - 26.x	AstrbotAdaptor-x.x.x-Backend.jar
Velocity	3.3.x	AstrbotAdaptor-x.x.x-Velocity.jar

• Java 版本: 17+
• 后端包说明: Bukkit/Paper/Spigot/Folia 共用同一个 Backend jar。该 jar 以 Java 17 和 1.20 API 作为兼容基线，运行时自动检测 Folia 并切换到 Folia 调度/监听实现；新版本 Paper/Folia 继续复用同一 jar。
• 依赖说明: Java 插件 jar 是 thin jar，不再 shade/relocate Netty、Gson、SnakeYAML。Bukkit/Spigot 通过 plugin.yml 的 libraries 引用依赖；Paper/Folia 通过 paper-plugin-loader 使用 Paper classpath loader；Velocity 端需要将发布包里的 libs/ 目录和 Velocity jar 保持在同一目录。
• 版本说明: 26.x 是 Minecraft Java Edition 2026 年起使用的新官方版本号，不是 1.26.x。

平台说明

• Bukkit/Paper/Spigot: 适用于大多数传统 Minecraft 服务器
• Folia: 适用于 Paper 的区域化多线程分支，提供更好的多核性能
• Velocity: 适用于 Velocity 代理服务器，完整功能须代理端和后端服一起安装插件

快速开始

独立服务器（非群组服）

1. 安装本插件
2. 从配置文件中获取认证token（或使用指令获取）
3. 在AstrBot插件中添加服务器，并配置服务器地址端口和认证token等信息

Note

独立服务器请不要开启proxyMode！！！

velocity群组服

1. 在vc端 和 需要的后端服务器都安装本插件
2. 启动vc端，获取secret值（可查看启动日志 或从插件配置文件夹中的proxy-secret.txt文件中获取）
3. 在所有的后端服务器的插件配置中，启用proxyMode，并填写secret值，用于插件握手鉴权
4. 从vc端插件配置中，获取认证token，并在AstrBot端插件中添加服务器，填写Velocity地址、端口、token等信息

AI 总结接入

AI 总结由 Java 端 MineSentinel 只读采集 observation，AstrBot 插件侧落盘、去重、聚合并调用 AstrBot 模型生成报告。Java 端不会自行处罚玩家、执行命令或修改配置。

单服实现

1. 后端服安装 AstrbotAdaptor-版本-Backend.jar，保持 proxyMode.enabled: false。
2. 在后端服配置中确认 mine_sentinel.enabled、mine_sentinel.observation.enabled、mine_sentinel.chat.enabled 和 mine_sentinel.metrics.enabled 为 true。
3. 可选：填写稳定的 mine_sentinel.server_id / server_name，例如 survival / 生存服，方便 AstrBot 侧手动生成指定服务器报告。
4. 启动服务器，从配置文件或 /astrbot token show 获取 auth.token。
5. 在 AstrBot 侧的 astrbot_plugin_minecraft_adapter 添加该服务器地址、端口、token，并在服务器 target_sessions 中填入要接收报告的 QQ 群 UMO。
6. 在 AstrBot 侧开启 mine_sentinel.report.enabled，可用 mc report now <服务器ID> 8h 立即测试 8 小时窗口总结；定时总结由 interval_hours 控制。

Velocity 群组服实现

1. Velocity 代理端安装 AstrbotAdaptor-版本-Velocity.jar，所有需要统计的后端服安装 AstrbotAdaptor-版本-Backend.jar。
2. 先启动 Velocity 端，记录代理端生成的 proxy-secret.txt 或启动日志中的 secret。
3. 每个后端服开启 proxyMode.enabled: true 并填写同一个 proxyMode.secret。后端服不再直接连接 AstrBot，而是通过 Plugin Messaging Channel 把聊天、事件、指标和 MineSentinel observation 转交给 Velocity 端。
4. 每个后端服建议填写不同且稳定的 mine_sentinel.server_id / server_name，例如 lobby、survival、resource。这样 AstrBot 侧报告能按后端来源聚合问题。
5. Velocity 端保持 mine_sentinel.enabled: true 和 mine_sentinel.observation.enabled: true。Velocity 自身 mine_sentinel.chat.enabled 默认可保持 false，玩家聊天主要由后端服采集。
6. 在 AstrBot 侧只添加 Velocity 端的地址、端口、token；报告会通过 Velocity 连接接收各后端上报的数据。
7. 在 AstrBot 侧配置接收 QQ 群：常规用服务器 target_sessions，需要额外群或私聊可用 mine_sentinel.report.delivery_targets。测试命令仍是 mc report now <服务器ID> 8h。

推荐窗口

• 普通巡检：interval_hours: 8，default_window_minutes: 480。
• 高频测试：先把 AstrBot 侧 default_window_minutes 调到 30 或 60，确认 QQ 群能收到图片报告和 JSONL 附件后再改回 8 小时。
• 聊天量很大时优先在 AstrBot 侧调 max_records_in_memory、max_ai_records 和 max_ai_prompt_chars，Java 端仍只保留瞬时队列并批量上报。

AI 一键部署 Prompt

把下面这段发给具备本机文件读写和联网能力的 AI 助手，让它代为下载、安装和配置：

你是 Minecraft + AstrBot 部署助手。请按下面要求帮我部署 MineSentinel AI 总结，不要跳过备份和验证。

项目链接：
- MC Java 插件仓库：https://github.com/EllanServer/AstrBotAdapter
- MC Java 插件 Actions：https://github.com/EllanServer/AstrBotAdapter/actions
- AstrBot 插件仓库：https://github.com/EllanServer/astrbot_plugin_minecraft_adapter
- AstrBot 插件 Actions：https://github.com/EllanServer/astrbot_plugin_minecraft_adapter/actions
- NapCatQQ 仓库：https://github.com/NapNeko/NapCatQQ
- NapCatQQ Releases：https://github.com/NapNeko/NapCatQQ/releases
- NapCat Shell 安装文档：https://napneko.github.io/guide/boot/Shell

开始前先向我索取这些信息，不要自行猜路径：
1. 部署模式：单服 / Velocity 群组服。
2. Minecraft 服务器根目录。单服给一个根目录；Velocity 群组服请给 Velocity 根目录和每个后端服根目录。
3. AstrBot 根目录。
4. 要接收 AI 总结的 QQ 群或 UMO，例如 group:123456789 或 aiocqhttp:GroupMessage:123456789。
5. NapCat 安装目录如果已知可一并提供；不知道就留空，由你先自动检测。
6. 是否现在重启 MC 服务端、AstrBot 和 NapCat。

拿到路径后执行：
1. 检查所有目录是否存在，识别 plugins 目录、AstrBot 插件目录和现有配置文件。
2. 先检测 NapCat/OneBot 是否已经安装和运行，不要一上来重装：
   - Windows：检查进程 NapCat/NapCatQQ/QQ/NapCatWinBootMain，检查服务、计划任务、常见目录、AstrBot 同级目录和用户给出的 NapCat 目录。
   - Linux：检查 ps、systemctl、pm2、docker ps、which napcat、sudo napcat、常见安装目录和 AstrBot 同级目录。
   - 同时检查 AstrBot 现有 aiocqhttp/OneBot v11/QQ 适配器配置，确认是否已经能连接到 NapCat。
   - 如果 NapCat 已安装且可用，只记录安装位置和连接方式，不覆盖现有配置。
3. 如果检测不到 NapCat，先询问并确认 NapCat 安装目录、运行方式（Windows Shell 一键包 / Linux Shell / Docker）和机器人 QQ 号，然后按官方 NapCatQQ Releases 与 Shell 安装文档安装：
   - Windows AMD64 优先下载 NapCat.Shell.Windows.OneKey.zip，解压到无中文和空格的目录，运行安装器或 napcat.bat。
   - Linux 优先按官方 Shell 文档/installer 安装；如果用户要求 Docker，再使用 Docker 方式。
   - 不要让 AI 输入 QQ 密码；启动 NapCat 后让用户扫码/手动登录。
   - 配置 OneBot v11 WebSocket 或 HTTP，使 AstrBot 能连接 NapCat；若已有可用连接，保持原配置。
4. 从 GitHub Actions 下载两个仓库最新 successful workflow 的构建产物和源码。优先使用 gh：
   - gh run list -R EllanServer/AstrBotAdapter --branch main --status success --limit 1
   - gh run download -R EllanServer/AstrBotAdapter <run-id> --dir ./downloads/AstrBotAdapter
   - gh run list -R EllanServer/astrbot_plugin_minecraft_adapter --branch master --status success --limit 1
   - gh run download -R EllanServer/astrbot_plugin_minecraft_adapter <run-id> --dir ./downloads/astrbot_plugin_minecraft_adapter
   如果没有 gh，就打开上面的 Actions 链接下载最新成功运行的 artifacts。若 Actions 没有源码 artifact，则同时下载源码 ZIP：
   - https://github.com/EllanServer/AstrBotAdapter/archive/refs/heads/main.zip
   - https://github.com/EllanServer/astrbot_plugin_minecraft_adapter/archive/refs/heads/master.zip
5. 安装 Java 插件：
   - 单服：把最新 Backend jar 放进该服务器根目录的 plugins/。
   - Velocity 群组服：把 Velocity jar 放进 Velocity 的 plugins/，把 Backend jar 放进每个后端服的 plugins/；如果产物包含 libs/，按 README 保持 libs/ 与 Velocity jar 同级。
6. 安装 AstrBot 插件：把 astrbot_plugin_minecraft_adapter 最新源码放进 AstrBot 的插件目录，目录名保持 astrbot_plugin_minecraft_adapter；如已有旧目录，先备份再覆盖。
7. 配置 Java 插件：
   - 单服保持 proxyMode.enabled=false。
   - Velocity 群组服先启动/读取 Velocity 端 secret，再给每个后端服写入 proxyMode.enabled=true 和 proxyMode.secret。
   - 确认 mine_sentinel.enabled、observation.enabled、chat.enabled、metrics.enabled 为 true。
8. 配置 AstrBot 插件：
   - 单服在 mc_servers 中添加后端服 host/port/token。
   - 群组服只添加 Velocity 端 host/port/token。
   - 把 QQ 群写入 message.target_sessions，必要时写入 mine_sentinel.report.delivery_targets。
   - 开启 mine_sentinel.enabled、storage.enabled、report.enabled、send_as_image、send_full_log_file。
   - 确认 AstrBot 已连接 NapCat/OneBot，且目标 QQ 群可以收发消息。
9. 做备份：覆盖任何 jar、插件目录或配置文件前，先复制到带时间戳的 backup 目录。
10. 验证：
   - 启动或重启服务后检查 Java 插件、AstrBot 和 NapCat 日志。
   - 在 QQ/AstrBot 会话执行 mc monitor status，确认收到 observation。
   - 执行 mc report now <服务器ID> 30m 测试图片报告和 JSONL 附件发送。
11. 最后给我汇总：安装了哪些文件、备份位置、NapCat 是否复用或新装、配置了哪些服务器 ID、测试命令结果、还需要我手动确认的事项。

插件配置

配置文件：

• 后端服（Bukkit/Paper/Folia）：src/main/resources/config-backend.yml
• 代理端（Velocity）：src/main/resources/config-velocity.yml

说明：以下为完整字段说明；未特别标注的平台表示两端通用。

通用配置说明

配置路径	默认值	类型	说明
general.language	zh_CN	string	插件语言，支持 zh_CN / en_US
general.debug	false	boolean	调试模式，开启后输出详细日志
auth.token	""	string	认证 Token，留空启动时自动生成 32 位随机 Token
server.host	0.0.0.0	string	WS/REST 监听地址
server.port	8765	int	WS/REST 监听端口
server.websocket.enabled	true	boolean	是否启用 WebSocket 服务
server.websocket.heartbeatInterval	30	int(秒)	心跳间隔
server.websocket.heartbeatTimeout	90	int(秒)	心跳超时阈值
server.restapi.enabled	true	boolean	是否启用 REST API
server.restapi.rateLimit	100	int(次/分钟)	REST 频率限制，0 为不限流
messageForward.enabled	true	boolean	是否启用聊天消息转发
messageForward.prefix	*	string	转发触发前缀（留空表示转发所有消息）
messageForward.stripPrefix	true	boolean	转发时是否移除前缀
messageForward.incomingFormat	§7[§b{platform}§7] §f{username}§7: §f{content}	string	外来消息显示格式，支持 {platform} {username} {content}
aiChat.group.enabled	true	boolean	是否启用群聊 AI
aiChat.group.prefix	@	string	群聊 AI 触发前缀
aiChat.private.enabled	true	boolean	是否启用私聊 AI
aiChat.private.prefix	#	string	私聊 AI 触发前缀
aiChat.private.echoFormat	<{player}> {message}	string	私聊回显格式，支持 {player} {message}
aiChat.responseFormat	§7[§dAI§7] §f{content}	string	AI 回复格式，支持 {content}
aiChat.thinkingMessage	§7[§dAI§7] §e思考中...	string	AI 思考中提示文案
aiChat.showThinking	true	boolean	是否显示思考中提示
aiChat.timeout	60	int(秒)	AI 请求超时时间
playerNotification.join.enabled	true	boolean	是否通知玩家加入
playerNotification.quit.enabled	true	boolean	是否通知玩家离开
commandExecution.enabled	true	boolean	是否允许远程执行指令
commandExecution.filterType	BLACKLIST	enum	NONE / BLACKLIST / WHITELIST
commandExecution.commandList	见下方	list[string]	指令过滤列表，支持 * 通配符
logQuery.enabled	true	boolean	是否启用日志查询
logQuery.maxLines	1000	int	最大返回行数
logQuery.logFile	""	string	日志路径（相对服务器根目录），留空默认 logs/latest.log
mine_sentinel.enabled	true	boolean	是否启用 MineSentinel 只读观察上报
mine_sentinel.server_id	""	string	观察数据中的服务器 ID，留空时使用平台服务器名
mine_sentinel.server_name	""	string	观察数据中的展示名，留空时使用平台服务器名
mine_sentinel.observation.enabled	true	boolean	是否启用观察队列和批量发送
mine_sentinel.observation.flush_interval_seconds	10	int(秒)	观察批次发送间隔
mine_sentinel.observation.max_queue_size	5000	int	Java 端瞬时观察队列上限，不保存 8 小时历史
mine_sentinel.observation.max_queue_bytes	8388608	long	Java 端瞬时观察队列估算字节上限，和 max_queue_size 同时生效
mine_sentinel.observation.max_batch_size	200	int	单个 OBSERVATION_BATCH 最大事件数
mine_sentinel.observation.drop_policy	drop_oldest	string	缓存满时丢弃策略，支持 drop_oldest / drop_newest
mine_sentinel.observation.include_context	true	boolean	是否上报轻量上下文，例如来源、消息类型、世界/维度、后端服
mine_sentinel.observation.include_position	false	boolean	是否上报方块坐标；privacy.mask_location=true 时坐标仍会被禁止
mine_sentinel.chat.enabled	true	boolean	是否采集玩家聊天观察；Velocity 代理端默认关闭
mine_sentinel.chat.include_raw_message	true	boolean	是否在脱敏/截断后包含聊天正文
mine_sentinel.chat.max_message_length	300	int	聊天观察正文最大长度
mine_sentinel.metrics.enabled	true	boolean	是否定时采集 TPS/MSPT/在线人数/内存等指标
mine_sentinel.metrics.interval_seconds	30	int(秒)	指标观察采集间隔
mine_sentinel.privacy.hash_player_uuid	true	boolean	是否对玩家 UUID 加盐哈希
mine_sentinel.privacy.mask_ip	true	boolean	是否屏蔽 IP 类内容
mine_sentinel.privacy.mask_location	true	boolean	是否屏蔽坐标类内容
mine_sentinel.privacy.redact_patterns	[]	list[string]	自定义正则脱敏规则
mine_sentinel.debug.log_observation_count	false	boolean	是否记录每次上报的观察数量

独立服专有配置（Bukkit/Paper/Folia）（Velocity端无以下配置项）

配置路径	默认值	类型	说明
updateCheck.enabled	true	boolean	启动时检查更新
updateCheck.notifyOps	true	boolean	有新版本时通知管理员
proxyMode.enabled	false	boolean	是否启用 Velocity 代理模式
proxyMode.secret	""	string	与 Velocity 通信的鉴权密钥

特殊说明

• 群组服场景下，后端服务器启用proxyMode之后，将不再启动 WebSocket/REST API 服务器，而是通过Plugin Messaging Channel和代理端通信，代理端负责和AstrBot插件通信
• 后端插件启用proxyMode之后，大部分通用配置文件将失效，转为直接继承代理端插件配置
• 由于Plugin Messaging Channel的限制，在后端服务器无玩家的情况下，vc端插件将无法和对应后端服务器插件通信，会出现指令无法执行，无法读取到服务器数据等情况
• MineSentinel 是只读观察系统。Java 端只采集、脱敏、缓存并批量上报 OBSERVATION_BATCH，不会自动处罚玩家、执行 RCON/命令或修改服务器配置

游戏内指令

• /astrbot help - 显示帮助信息
• /astrbot reload - 重载配置文件
• /astrbot status - 显示ws/restapi运行状态
• /astrbot token [show/regen] - 显示/重新生成认证token
• /astrbot connections -显示当前活跃的ws连接

权限：astrbot.admin (默认: OP)

编译

需要 Java 17+ 和 Gradle Wrapper；构建 26.x 版本目标时需要 JDK 25：

./gradlew clean releaseAll

Windows 可运行目录中的 build.bat 脚本，会自动构建 Backend/Velocity 插件和 Velocity 运行时引用库。

编译后的 thin jar 文件位于 releases/ 目录：

• AstrbotAdaptor-x.x.x-Backend.jar
• AstrbotAdaptor-x.x.x-Velocity.jar
• libs/*.jar：Velocity 运行时引用库。使用 Velocity jar 时需要保留这个目录；Backend jar 会由 Bukkit/Paper/Folia 运行时按描述文件加载依赖。

Paper hardfork 之后，Backend jar 仍保留 Bukkit plugin.yml 入口以兼容命令和传统服务端；Paper/Folia 会额外读取 paper-plugin-loader，用 Paper 的依赖加载机制处理外部库。

依赖版本由 GitHub Dependabot 每周自动检查并提交 PR；Gradle 侧版本集中在 gradle.properties，Maven 侧版本集中在 pom.xml。

致谢

特别感谢 Railgun19457 创建 AstrBotAdapter 的原始项目基础，MineSentinel 的 Java 插件能力在此基础上继续演进。

开源协议

本子项目使用 MIT License，详见 LICENSE。

当前仓库是多许可证工作区：根目录文件使用 Apache License 2.0，AstrBotAdapter/ 使用 MIT License，astrbot_plugin_minecraft_adapter/ 使用 GNU AGPL v3.0。完整说明见根目录 README.md 和 THIRD_PARTY_LICENSES.md。

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

• v2.0.5

  • 重构后首个正式版
  • 支持前后端插件协作
  • 对应AstrBot插件版本2.0.1+

• v2.0.1-beta - v2.0.4-beta

  • 具体更新内容见commit记录

• v2.0.0-beta

  • 重构架构，支持多平台（Bukkit/Folia/Velocity）
  • 新增 Folia 区域化多线程支持
  • 新增 Velocity 代理服务器支持
  • 统一抽象层设计，更好的可扩展性
  • 改进的国际化支持

• v1.0.3

  • 支持AI聊天
  • 添加配置自动校验

• v1.0.2

  • 修复重复转发的bug
  • 精简代码，提高性能
  • 修改游戏内提示为中文
  • 为status命令添加详细连接信息

• v1.0.1

  • 修复bug
  • 修改配置文件

• v1.0.0

  • 实现基本功能

支持

• 🐛 报告问题
• 💡 功能建议
• 📧 联系作者：通过 GitHub Issue