原创 开源 工具 ✨ Agent4Mc✨ | 原生 AI Agent 驱动 | 直连服务器插件配置 提升玩家问答检索相关性 | 企业级多路向量检索系统 | 可选高性能 Reranker 重排增强 v1.0

[MD] # 🎮 Agent4Minecraft：让玩家在游戏里询问当前服务器的插件和配置 > 🤖 面向 Minecraft 服主和管理团队的 AI 问答插件套件。 > 玩家在游戏内使用 `/askmc` 提问，后端会结合插件文档、当前服务器已安装插件、已同步配置和服主自定义 Skill 来生成回答。     ## ✨ 资源摘要 **简介：** Agent4Minecraft 让玩家在游戏内询问当前服务器的插件、权限和配置问题，AI 会结合插件文档、已安装插件和同步后的服务器配置回答。 面向 Minecraft 服主的 AI 问答插件套件。玩家用 `/askmc` 在游戏内提问， 后端结合插件文档、已安装插件和已同步配置回答。支持配置脱敏同步、 管理员状态查询和本服 Skill 管理。 玩家经常会问这些问题： ```text /askmc 普通玩家不能用 /spawn，应该检查哪个权限节点？ /askmc Residence 怎么设置玩家最多拥有 3 个领地？ /askmc eco 插件的金币倍率在哪里配置？ ``` 如果只是把问题转发给大模型，它只能给出通用答案。Agent4Minecraft 的目标是让 AI 尽量理解“你的这台服务器”：装了哪些插件、同步过哪些配置、服主希望它按什么规则回答。 ## 🎯 适合谁 - 插件多、配置分散，玩家经常问“怎么用”“权限怎么给”“功能在哪里配置”的服务器。 - 有多名管理员，希望新管理员能快速理解当前服务器规则和插件体系。 - 想把 AI 接入 Minecraft，但不希望玩家跳出游戏去网页聊天。 - 希望 AI 只做问答和配置理解，不直接接管服务器命令权限的服主。 ## 🧩 核心能力 - **游戏内 AI 问答：** 玩家直接使用 `/askmc <问题>` 提问，不需要离开游戏。 - **当前服务器上下文：** 问答会携带 `server.id`、玩家身份和已安装插件列表。 - **配置同步：** 管理员用 `/a4m sync` 同步允许范围内的文本配置。 - **插件文档 RAG：** 后端基于插件文档向量库、BM25 和语义检索组织回答。 - **服务器配置记忆：** 后端会把同步后的配置抽取成可检索的语义记忆。 - **Skill 管理：** 服主可用 `/a4m skill` 查看、创建、确认和删除本服 Skill。 - **上传前脱敏：** 插件上传的是脱敏副本，本地原配置不会被修改。 - **独立后端：** LLM、向量库、检索和可选 reranker 都在后端运行， 不塞进 Minecraft 主线程。 ## 🏗️ 系统由什么组成 - **Agent4Minecraft：** 必需。Minecraft 插件端，提供 `/askmc`、 `/a4m sync`、`/a4m status`、`/a4m skill`。 - **AgentForMc：** 必需。AI 后端，负责 gRPC 服务、RAG 检索、 配置语义记忆和回答生成。 - **AgentForMc-Reranker：** 可选。独立重排服务，需要更高检索质量时再启用。 普通服主优先使用 GitHub Release 里的成品包：插件是 jar， 后端是 Windows / Linux x64 压缩包。正常使用不需要自己构建 jar， 也不需要安装 Python。 ## 📦 下载地址 - Agent4Minecraft 插件： [Agent4Minecraft Releases](https://github.com/EternalmBlue/Agent4Minecraft/releases/latest) - AgentForMc 后端： [AgentForMc Releases](https://github.com/EternalmBlue/AgentForMc/releases/latest) - AgentForMc-Reranker 可选重排服务： [AgentForMc-Reranker Releases](https://github.com/EternalmBlue/AgentForMc-Reranker/releases/latest) - 使用文档： [Agent4Minecraft Wiki](https://github.com/EternalmBlue/Agent4Minecraft/wiki) 建议插件、后端和 reranker 使用同一版本的 Release。升级插件时，也请同步检查后端版本是否匹配。 ## 🚀 快速安装 ### 1. 准备后端 下载 AgentForMc Release 包，例如： ```text AgentForMc-v1.2.1-windows-x64.zip ``` 解压后应能看到： ```text AgentForMc.exe config.toml .env.example data ``` 推荐准备插件文档向量库，并放到： ```text data/plugin_docs_vector_db ``` 这不是基础问答的必需项。没有这份数据时，后端仍可按大模型自有知识回答；准备好之后，插件文档检索、配置项定位和引用准确性会更好。 ### 2. 填写后端密钥 把 `.env.example` 复制为 `.env`，填写： ```dotenv RAG_ZHIPU_API_KEY=你的智谱APIKey RAG_LLM_API_KEY=你的LLM APIKey RAG_GRPC_AUTH_TOKEN=a4m_请改成你自己的长token RAG_RERANKER_GRPC_AUTH_TOKEN= ``` 说明： - `RAG_LLM_API_KEY` 默认用于 DeepSeek 这类 OpenAI-compatible LLM Chat 接口。 - 旧部署里的 `RAG_DEEPSEEK_API_KEY` 仍兼容，新部署建议使用 `RAG_LLM_API_KEY`。 - `RAG_GRPC_AUTH_TOKEN` 必须和插件配置里的 `backend.authToken` 完全一致。 - 不启用 reranker 时，`RAG_RERANKER_GRPC_AUTH_TOKEN` 可以留空。 启动后端： ```text AgentForMc.exe ``` 窗口保持运行即可，不要关闭。 ### 3. 安装插件 下载 Agent4Minecraft Release jar，放进 Minecraft 服务端的 `plugins` 文件夹。 不要使用名字里带 `plain` 的 jar。 首次启动服务端后，插件会生成： ```text plugins/Agent4Minecraft/config.yml plugins/Agent4Minecraft/server-instance-id.txt plugins/Agent4Minecraft/lang/zh_CN.yml plugins/Agent4Minecraft/lang/en_US.yml ``` 停止服务端，打开 `plugins/Agent4Minecraft/config.yml`，至少修改： ```yaml backend: authToken: "a4m_请改成你自己的长token" ``` 这个 token 要和后端 `.env` 的 `RAG_GRPC_AUTH_TOKEN` 一致。 如果后端和 Minecraft 服务端不在同一台机器，再配置： ```yaml backend: authToken: "a4m_请改成你自己的长token" host: "后端机器IP" port: 50051 ``` 跨机器部署时，请用防火墙限制 `50051` 端口来源。 ### 4. 游戏内验证 确认 AgentForMc 后端窗口正在运行，然后启动 Minecraft 服务端。进入游戏后用 OP 或管理员账号执行： ```text /a4m sync /a4m status /a4m skill list /askmc eco 插件的金币倍率在哪里配置？ ``` 成功标准： - `/a4m sync` 能返回同步结果。 - `/a4m status` 能看到本地同步和后端刷新状态。 - `/a4m skill list` 能列出官方、全局或本服 Skill。 - `/askmc` 能返回 AI 回答。 ## ⌨️ 游戏内命令 - `/askmc <问题>`：所有人默认可用，向后端 AI 提问。 - `/a4m sync`：OP 默认可用，同步允许范围内的服务器和插件配置。 - `/a4m status`：OP 默认可用，查看本地同步、远程上传和后端索引状态。 - `/a4m skill list`：OP 默认可用，查看官方、全局和本服 Skill。 - `/a4m skill view <name>`：OP 默认可用，查看某个 Skill 的摘要和内容。 - `/a4m skill create <需求>`：OP 默认可用，通过私有聊天流程创建本服 Skill。 - `/a4m skill confirm`：OP 默认可用，确认安装当前 Skill 草稿。 - `/a4m skill cancel`：OP 默认可用，取消当前 Skill 草稿。 - `/a4m skill status`：OP 默认可用，查看当前 Skill 创建会话状态。 - `/a4m skill delete <name>`：OP 默认可用，删除本服 Skill。 权限节点： - `agent4minecraft.ask`：默认所有人。 - `agent4minecraft.admin`：默认 OP。 建议只给可信管理员 `agent4minecraft.admin`。 ## 🧠 Skill 是什么 Skill 可以理解为“服主给 AI 的本服回答规则”。例如你可以创建一个经济插件排查 Skill，让 AI 回答经济相关问题时优先检查 Vault、EssentialsX、商店插件和你指定的配置习惯。 示例： ```text /a4m skill create 帮我回答经济插件相关问题。优先检查 Vault、EssentialsX 和商店插件配置；回答时先给排查顺序，再给具体配置路径。 ``` 执行后，插件会让该管理员进入私有 Skill 创建模式。管理员后续直接在聊天栏回复后端追问，消息不会广播给其他玩家。草稿准备好后，用： ```text /a4m skill confirm ``` 确认安装到本服。 ## 🔄 配置同步范围 插件不会上传整个服务器目录，只会上传允许范围内的文本配置。 根目录允许： ```text server.properties bukkit.yml spigot.yml paper*.yml ``` `plugins` 文件夹下允许： ```text .yml .yaml .json .properties .txt .md ``` 不会上传： - 世界存档 - jar 文件 - 数据库文件 - 日志文件 - 图片、压缩包、二进制文件 - 不在允许范围内的文件 同步时插件会先生成 manifest 和 SHA-256，后端只要求上传缺失或变更文件，避免重复传输。 ## 🛡️ 安全边界 - AI 不会获得 OP 权限。 - 普通玩家默认只能使用 `/askmc` 问答。 - 配置同步和 Skill 管理需要 `agent4minecraft.admin`。 - 插件不会上传整个服务器目录。 - 上传前会对常见敏感配置值做脱敏。 - 本地原配置不会被脱敏流程修改。 - 后端通过 `server.id` 和 `server-instance-id` 绑定服务器，避免多个服务器误用同一身份。 - 大模型、向量库、检索和 reranker 运行在独立后端，不在 Minecraft 主线程里执行。 ## 🧰 环境要求 - Minecraft 服务端：Paper 1.20.4+ 或兼容核心。 - 插件端：Java 服务端可加载 Paper / Spigot 兼容插件。 - 后端：Windows x64 或 Linux x64 Release 包。 - LLM：OpenAI-compatible Chat API，默认配置面向 DeepSeek。 - Embedding：智谱 embedding API Key。 - 数据：推荐准备 AgentForMc 插件文档向量库 `data/plugin_docs_vector_db`， 用于增强插件文档检索。 ## ⚠️ 不适合哪些场景 - 完全不希望接入外部 AI API 的服务器。 - 只想要一个纯聊天机器人，不关心插件资料、权限节点和服务器配置检索。 - 希望 AI 自动执行高危管理命令、直接接管服务器的场景。 ## ❓ 常见问题 ### 会卡服吗？ 核心 AI、检索、向量库和可选 reranker 都在独立后端中运行。 插件端只做命令入口、上下文收集、配置扫描、脱敏和 gRPC 通信。 网络请求和同步流程也不会塞进 Minecraft 主线程。 ### 玩家能让 AI 执行危险命令吗？ 当前定位是问答和配置理解，不是让 AI 直接接管服务器。普通玩家默认只有 `agent4minecraft.ask`，配置同步和 Skill 管理需要管理员权限。 ### 为什么要同步配置？ 不同服务器的插件配置差异很大。同步配置后，后端才能参考当前服务器真实配置回答，而不是只给通用答案。 ### 为什么建议准备插件文档向量库？ `data/plugin_docs_vector_db` 相当于插件资料的检索数据库。没有它时，AI 仍可按大模型自有知识回答；有它时，后端可以检索具体插件文档，对权限节点、配置路径、版本差异等问题的回答会更稳。 ### 必须安装 Reranker 吗？ 不必须。建议先跑通 Agent4Minecraft 插件和 AgentForMc 后端。只有在觉得检索排序不够准时，再启用 AgentForMc-Reranker。 ### 可以跨机器部署吗？ 可以。后端 `config.toml` 中把 gRPC 监听改为 `0.0.0.0:50051`，插件 `config.yml` 中配置后端 IP 和端口即可。跨机器部署时请限制端口来源，不建议裸露到公网。 ### 插件启动后提示后端不可用怎么办？ 优先检查： - AgentForMc 后端是否已经启动。 - `backend.host` / `backend.port` 是否配置正确。 - 插件 `backend.authToken` 是否和后端 `RAG_GRPC_AUTH_TOKEN` 一致。 - 插件和后端是否使用了匹配版本。 - 当前 `server.id` 是否已经被另一个服务器实例绑定。 ## 📚 文档与反馈 - Wiki 文档：[Agent4Minecraft Wiki](https://github.com/EternalmBlue/Agent4Minecraft/wiki) - 快速开始：[Quick Start](https://github.com/EternalmBlue/Agent4Minecraft/wiki/Quick-Start) - 安装部署：[Install and Deploy](https://github.com/EternalmBlue/Agent4Minecraft/wiki/Install-and-Deploy) - 常见问题：[FAQ](https://github.com/EternalmBlue/Agent4Minecraft/wiki/FAQ) - 问题反馈：建议通过 GitHub Issues 或本帖评论区反馈。 ## ✅ 当前状态 当前体系已包含： - Agent4Minecraft 插件端 - AgentForMc AI 后端 - AgentForMc-Reranker 可选重排服务 - gRPC 通信与 Bearer token 认证 - 游戏内问答 - 配置同步与增量上传 - 上传前脱敏 - 后端语义配置记忆刷新 - `/a4m status` 同步状态查询 - `/a4m skill` 服务器级 Skill 管理 - 简体中文 / 英文插件消息 - Release 成品包交付 建议服主先在测试服体验 `/a4m sync`、`/a4m status`、`/a4m skill list` 和 `/askmc`，确认上传范围、回答质量和后端部署方式都符合自己的服务器场景后，再部署到正式服。 [/MD]