Skip to content

README.md

Latest commit

 

History

History
239 lines (165 loc) · 9.59 KB

README.md

File metadata and controls

239 lines (165 loc) · 9.59 KB

FancyHelper

FancyHelper Logo

FancyHelper 是一款基于 AI 驱动的 Minecraft 服务器管理助手插件。它允许管理员通过简单的自然语言与 AI 对话，自动生成并执行复杂的服务器指令，极大地降低了插件学习成本和管理负担。

有问题？尝试→Ask DeepWiki

✨ 核心特性

  • 💬 CLI 交互模式：通过游戏内聊天框进入沉浸式对话，像和真人管理员交流一样管理服务器。
  • 🧠 强力 AI 驱动：接入 CloudFlare Workers AI，默认使用 @cf/moonshotai/kimi-k2.5 大模型，理解意图更精准。
  • 🔄 多 AI 提供商支持：支持 CloudFlare Workers AI 和 OpenAI 兼容 API（OpenAI 官方、Azure OpenAI、DeepSeek、Ollama 等）。
  • 🛡️ 安全执行机制：AI 生成的指令需要玩家手动确认后才会执行，确保服务器安全。
  • ⚡ YOLO 模式：支持快速执行模式，大部分指令自动执行，高危命令仍需确认。
  • 🎯 状态可视化：使用动作栏实时显示 AI 生成状态（思考中、执行工具、等待确认等）。
  • 🔍 智能文档搜索：内置多种主流插件预设（LuckPerms, EssentialsX, WorldEdit 等），并支持在 Wiki 无结果时自动进行全网搜索。
  • 📊 结果反馈闭环：指令执行后的结果会自动反馈给 AI，使其能根据执行情况进行下一步操作或错误修正。
  • 🔄 配置自愈：支持配置文件版本检测与自动更新，无需担心插件升级导致的配置丢失。
  • 🧹 旧插件清理：自动清理旧版本的 MineAgent 插件文件，防止干扰。
  • 🛡️ 防死循环检测：自动检测 AI 陷入重复操作或过度调用，支持豁免机制。
  • 🐛 云端错误上报：自动收集错误日志和配置文件并上报云端，帮助开发者改进插件（可配置关闭）。
  • 📦 库管理命令：支持通过 /fancy lib install protocollib 命令自动下载安装 ProtocolLib 依赖。

📷 图片展示

点击展开/收起插件预览图 FancyHelper预览图1 FancyHelper预览图2 FancyHelper预览图3 FancyHelper预览图4 FancyHelper预览图5 FancyHelper预览图6

📋 要求

  • Java: 17 或更高版本
  • 服务器版本: Spigot/Paper 1.18+
  • 网络: 服务器需能访问 CloudFlare API 接口
  • 依赖: ProtocolLib 5.4.0+（用于命令输出捕获）

🚀 快速开始

📥 下载插件

下载构建

💡 推荐下载最新版本，包含最新功能和修复。

1. 安装插件

  1. 下载最新的 FancyHelper.jar 并放入服务器的 plugins 文件夹。
  2. 推荐安装 ProtocolLib 插件以获得完整功能。你也可以在安装 FancyHelper 后使用 /fancy lib install protocollib 命令自动下载安装。
  3. 重启服务器以生成默认配置文件。
  4. 插件会自动清理旧版本的 FancyHelper 插件文件（如有），并将移动到 plugins/FancyHelper/old/ 目录。

2. 配置 AI 服务 （可选）

CloudFlare Workers AI（默认）

  1. 前往 CloudFlare 控制台 或Key共享站获取你的 API Key。

  2. 编辑 plugins/FancyHelper/config.yml：

    cloudflare:
  cf_key: 你的_CLOUDFLARE_API_KEY
  model: "@cf/moonshotai/kimi-k2.5"

  3. 在游戏中输入 /fancyhelper reload 重载配置。

OpenAI 兼容 API

插件也支持使用 OpenAI 兼容的 API，包括：

  • OpenAI 官方（gpt-4o, gpt-4o-mini, o1-preview 等）
  • DeepSeek（deepseek-chat, deepseek-reasoner）
  • Ollama（本地模型）
  • Azure OpenAI
  • 其他兼容 OpenAI 格式的 API

在 config.yml 中配置：

openai:
  enabled: true
  api_url: "https://api.openai.com/v1/chat/completions"
  api_key: "your-openai-api-key"
  model: "gpt-4o"

Metaso AI 搜索（可选）

Metaso（秘塔 AI 搜索）是一个强大的 AI 搜索引擎，可以提供更智能的搜索结果。当启用时，搜索功能会优先使用 Metaso API。

在 config.yml 中配置：

metaso:
  enabled: true
  api_token: "your-metaso-api-token"
  model: "fast"  # fast: 快速模型, pro: 专业模型
  concise_snippet: true  # 是否启用简洁摘要模式

搜索优先级：Metaso > Tavily

错误上报配置（可选）

插件内置了云端错误上报功能，帮助开发者改进插件。默认启用，可在配置文件中调整：

settings:
  # 是否启用匿名错误上报，帮助开发者改进插件
  auto_report: true

错误上报会收集以下信息：

  • 最近的服务器控制台日志
  • 当前活跃的会话日志
  • 错误堆栈信息
  • 插件配置文件（不含敏感密钥）

所有上报均为匿名，不会收集玩家数据或服务器敏感信息。

3. 使用方法

  • 在游戏中输入 /cli 或 /fancy 进入 AI 对话模式。
  • 直接输入你的需求，例如："给玩家 YanPl 设置为管理员组" 或 "在当前位置生成一个 10x10 的石头平台"。
  • 预览 AI 生成的指令，确认无误后确认执行。

交互指令：

  • exit - 退出 CLI 模式
  • stop - 打断当前 AI 生成或取消待处理操作
  • y / n - 确认或取消执行命令
  • agree - 同意用户协议或 YOLO 协议
  • /cli retry - 重试上一次 AI 响应
  • /cli exempt_anti_loop - 为当前对话开启防死循环豁免
  • ! 或 ！ 开头的消息 - 忽略 CLI 拦截，正常发送聊天消息

YOLO 模式：

  • 输入 agree 同意 YOLO 协议后，大部分 AI 生成的指令会自动执行
  • 但对于高风险命令（如 op、ban、stop、reload 等），仍需手动确认
  • 风险命令列表可在 config.yml 的 settings.yolo_risk_commands 中配置

库管理命令：

  • /fancy lib install protocollib - 自动下载并安装 ProtocolLib 插件（需要 OP 权限）
  • 如果插件目录已存在 ProtocolLib 文件，会提示重启服务器加载
  • 下载完成后需要重启服务器才能生效

读写文件功能：

  • AI 可以读取服务器上的任意文件，帮助分析配置、日志等
  • AI 可以修改服务器上的配置文件，但需要玩家确认后才会执行
  • 文件操作工具（ls、read、diff）会通过安全验证，确保不会操作敏感路径

⚠️ 常见问题

ProtocolLib 依赖问题

FancyHelper 支持 ProtocolLib 作为依赖，用于以下功能：

  • 命令输出捕获
  • 系统消息拦截

解决方案：安装 ProtocolLib 插件以获得完整体验。你可以使用 /fancy lib install protocollib 命令自动下载安装（需要 OP 权限）。

安全聊天警告

如果服务器日志中出现以下警告：

[WARN]: Failed to update secure chat state for <player>: 'Chat disabled due to missing profile public key. Please try reconnecting.'

原因：这是 Minecraft 服务器的安全聊天功能（enforce-secure-profile）产生的警告，不是 FancyHelper 插件的问题。当服务器启用了安全配置文件验证，但玩家的配置文件缺少公钥时就会出现此警告。

解决方案： FancyHelper 会自动检测此问题并尝试将 server.properties 中的 enforce-secure-profile 设置为 false。如果自动修改成功，只需重启服务器即可。

如果自动修改失败，请手动执行以下步骤：

  1. 打开服务器的 server.properties 文件
  2. 将 enforce-secure-profile 设置为 false
  3. 重启服务器

注意：此警告不影响 FancyHelper 的正常功能，可以安全忽略。

旧插件清理

插件启动时会自动清理旧版本的 FancyHelper（或 MineAgent）插件文件，并将移动到 plugins/FancyHelper/old/ 目录，防止干扰。

注意事项：

  • 不会删除任何文件，只是移动到 old 目录
  • 如果移动失败，会在日志中显示警告

🛠️ 指令与权限

指令 描述 默认权限
/fancyhelper 插件主指令 (别名: /cli, /fancy) fancyhelper.cli
/fancyhelper reload 重载插件配置 fancyhelper.reload
/fancyhelper lib install protocollib 下载并安装 ProtocolLib 依赖 OP
权限 描述 默认
fancyhelper.cli 允许使用 CLI 模式 OP
fancyhelper.reload 允许重载配置 OP
fancyhelper.notice 允许查看插件公告 OP

🛠️ 开发与构建

项目使用 Maven 进行管理。

git clone https://github.com/baicaizhale/FancyHelper.git
cd FancyHelper
mvn clean package

❤ 赞助我们

为铸FancyHelper，吾等焚膏继晷，兀兀穷年，耗尽心血。若此物有幸助君一臂之力，不知可否邀君共饮一杯薄酒，或赐一盏清茶之资？

baicaizhalebaicaizhale

zip8919zip8919

© 2026 baicaizhale 保留所有权利。