目录(点击展示)

• GamesAI for MCDReforged
  • 安装
  • 使用
  • 使用 Mineflayer Bot
    • 环境要求
    • 指令
    • 工作原理
    • 支持的操作
    • Bot 控制 AI 工具
    • 配置
  • 配置
    • 1.prefix
    • 2.permission
    • 3.max_history
    • 4.all_ai
    • 5.default_ai
    • 6.mineflayer_bot
  • 工具与Skills
    • 内置工具
    • 在配置文件中自定义工具
    • 在自己的MCDR插件中自定义工具
    • 内置Skills
    • 在配置文件中添加Skills
  • 故障排查
    • !!ask 错误
    • Mineflayer Bot 错误
    • 日志与调试
  • 本次更新
    • Version 0.6.0
      • 🎯 核心亮点
      • 1. Mineflayer Bot 集成
      • 2. 配置系统重制
      • 3. OpenAI 日志桥接
  • 鸣谢与声明
  • 赞助与贡献者名单
  • 许可证

安装

在MCDR控制台中使用如下命令以安装插件

!!MCDR plugin install games_ai

---

或者在MCDR插件仓库中获取并安装到你的插件目录内

如果选择手动安装，请先安装Python包OpenAI、requests和websockets，使用如下命令安装

pip install openai requests websockets

使用

在任何地方输入命令!!gamesai以显示这个插件的所有功能

指令	用途
!!gamesai clear	清除玩家的历史聊天记录，历史聊天记录与公共数据库无关
!!gamesai clearall	清除所有玩家的历史聊天记录，历史聊天记录与公共数据库无关
!!gamesai reload	重新加载插件配置文件
!!gamesai check	检查插件更新
!!gamesai speedtest [model]	测试 API 服务器连接延迟，不指定模型时测试全部
!!gamesai config get <key>	读取一个配置项的值。
!!gamesai config set <key> <value>	修改一个配置项的值（自动适配旧值类型）。

---

你也可以直接输入!!ask向AI提问或者聊天或者帮你做一些事情

指令	用途
!!ask <content>	向AI提问或者聊天或者帮你做一些事情，content为你想让AI做的事情或者你想问AI的问题
!!ask -m <model> <content>	使用指定的模型向AI提问或者聊天或者帮你做一些事情，model为你想使用的模型的AI_ID或昵称，content为你想让AI做的事情或者你想问AI的问题
!!ask -n <content>	向AI提问但不使用历史记录（当前对话仍会被保存）
!!ask -n -m <model> <content>	使用指定的模型且不使用历史记录提问

---

输入!!data获取有关数据库指令的信息

指令	用途
!!data write <key> <value>	在公共数据库内添加一条数据，其中key不能包含空格，value可以是任意字符串
!!data add <key> <value>	将value追加到公共数据库中的key中，不存在时自动创建新key
!!data del <key>	在公共数据库内删除一条数据，无论key是否存在
!!data read <key>	读取公共数据库中key对应的value
!!data list	读取公共数据库中的所有内容
!!data list keys	读取公共数据库中的所有key

---

使用 Mineflayer Bot

GamesAI 0.6.0 引入了基于 Mineflayer 的全自主 Minecraft 机器人。AI 可以直接控制机器人在游戏世界中寻路、挖掘、建造、合成、战斗和交互。

环境要求

• 服务器需安装 Node.js >= 18 和 npm
• 插件首次启动时自动安装 npm 依赖（mineflayer、ws、vec3、mineflayer-pathfinder、mineflayer-mcefly）
• 一个用于 Bot 的 Minecraft 账号（Microsoft/Mojang/离线）

指令

指令	用途
!!aibot join	启用 Bot 并让其加入服务器。
!!aibot leave	让 Bot 离开服务器并禁用。
!!aibot set <key> <value>	配置 Bot 身份（username/password/auth）。

工作原理

玩家 !!ask → GamesAI 插件 → WS 客户端 (Python) → WS 服务器 (Node.js) → Mineflayer Bot
                                                                           ↓
                                                                    Minecraft 服务器

AI（自主控制器）:
  get_state → 分析状态 → bot_call_action(goto/dig/attack/...) → 循环

插件启动一个 Node.js 进程运行 WebSocket 服务器，Python WebSocket 客户端（插件内置）通过本地连接与其通信，形成 MCDR 与 Mineflayer Bot 之间的桥梁。Bot 启动后，自主 AI 控制器会定时读取机器人状态、检查聊天消息，并自主决定执行什么操作。

支持的操作

Bot 支持 20+ 种操作，通过 bot_call_action AI 工具调用：

操作	描述
goto	A* 寻路到坐标 {x, y, z, range?}
efly	鞘翅飞行到坐标（需装备鞘翅）
dig	挖掘指定坐标的方块
place	在指定坐标放置方块
attack	按名称攻击附近实体，或攻击最近敌对生物
useOn	右键实体（如村民交易）
equip / unequip	装备/卸下盔甲或手持物品
mount / dismount	骑乘或离开载具和动物
craft	合成物品（背包或工作台）
lookAt	看向坐标或直接设置 yaw/pitch
sleep / wake	在床上睡觉或起床
activateBlock	右键方块（打开箱子、按下按钮）
setControlState	控制载具移动（前进/后退/跳跃）
viewContainer / takeFromContainer / putToContainer	容器管理
openFurnace / furnacePutInput / furnacePutFuel / furnaceTakeOutput	熔炉操作
nearbyEntities / findBlocks / getBlock	世界查询
stop / stopEfly	停止所有移动或鞘翅飞行

Bot 控制 AI 工具

除 bot_call_action 外，还有以下专用 AI 工具：

工具	描述
bot_chat	让 Bot 在公共聊天中发送消息。
bot_whisper	让 Bot 向某个玩家发送私聊消息。
bot_get_state	获取 Bot 完整状态（30+ 字段）。
bot_start / bot_stop	启动或停止 Bot。
delegate_to_bot	将复杂的 Minecraft 任务委派给自主控制器。

配置

完整配置参考见 6.mineflayer_bot。关键要点：

• 将 mineflayer_bot.enabled 设为 true（或使用 !!aibot join）以启动 Bot
• mineflayer_bot.bot.username / password / auth — Bot 的 Minecraft 登录凭据
• mineflayer_bot.cycle_interval — 自主 AI 决策间隔（秒）
• mineflayer_bot.websocket — 内部设置，除非明确知道用途否则不要修改

配置

默认配置文件结构如下:

{
  "prefix": "[GamesAI]",
  "permission": 3,
  "max_history": 10,
  "all_ai": {
      "<Your AI ID>":{
          "prompt": "你是一名成熟、稳重的Minecraft机器人工具，你的名字叫做“GamesAI”",
          "ai_name": "[GamesAI]",
          "base_url": "<Your API Base URL>",
          "ai_model": "<Your AI Model>",
          "api_key": "<Your API Key>",
          "extra_body": {}
      }
    },
  "default_ai": "<Your AI ID>",
  "mineflayer_bot": {
      "enabled": false,
      "cycle_interval": 15.0,
      "websocket": {
          "url": "ws://127.0.0.1:8080",
          "reconnect_interval": 10,
          "timeout": 60
      },
      "bot": {
          "username": "<Your Minecraft Bot Username>",
          "password": "<Your Minecraft Bot Password>",
          "auth": "microsoft"
      }
  }
}

---

以下是每个参数的简介:

1.prefix

值的类型: str

默认值: [GamesAI]

填入插件的名称，以在插件的回复之前加上一个前缀，可以包含Minecraft格式化代码

2.permission

值的类型：int

默认值：3

执行!!data等指令所必须达到的权限，见MCDR权限相关文档

3.max_history

值的类型: int

默认值: 10

填入每个玩家最大可保留的历史记录，与公共数据库无关。设置为 0 时完全禁用历史记录功能

4.all_ai

值的类型: dict

默认值：见文件

填入所有的AI信息，由多个字典组成，每个字典为一个AI模型，字典的键即为插件内部的AI_ID

prompt: 这项配置用于为每个AI编写提示词。使用> xxx.md将提示词指向config/games_ai/prompt/xxx.md文件，不限文件类型

ai_name: 这项配置与prefix功能类似，但是你现在需要单独为每一个模型设置，可以包含Minecraft格式化代码

base_url, ai_model, api_key: 与以前的相关配置功能相同，但是你现在需要单独为每一个模型设置

extra_body：请参考各API提供商对 extra_body 项的说明以编写。对于DeepSeek用户，想要移植原有 thinking 的，直接填写 {"thinking": {"type": "enabled"}}。不填时默认 {}（空）。

5.default_ai

值的类型: str

默认值: <Your AI ID>

填入当用户直接使用!!ask时使用的模型，应该填入all_ai字典中的某一个键(即为插件内部的AI_ID)，如果错填，会导致无法正常使用!!ask指令

6.mineflayer_bot

值的类型: dict

默认值: 见上方

Mineflayer 自主 Bot 代理的配置项。

enabled: 是否在启动时拉起 Bot。需要 Node.js >= 18。

cycle_interval: 自主 AI 决策循环间隔秒数（默认: 15.0）。

websocket: 内部 WebSocket 连接参数 — url、reconnect_interval、timeout。

bot: Minecraft 账号凭据 — username、password、auth（microsoft/mojang/offline）。服务器地址自动从 server.properties 中检测。

工具与Skills

内置工具

GamesAI插件提供了很多内置的工具，见下表。如果你想要更多的工具，可以选择向作者投稿、在配置文件中自定义工具、或在自己的MCDR插件中注册工具。

点击查看所有的内置工具

工具ID	传入参数	用途
get_online_players	无	获取服务器内在线的玩家列表。依赖于online_player_api插件，不存在时自动关闭此工具
get_whitelist_name	无	获取服务器完整的白名单列表。依赖于whitelist_api插件，不存在时自动关闭此工具
add_to_whitelist	name	将某个玩家添加到白名单中。依赖于whitelist_api插件，不存在时自动关闭此工具
remove_from_whitelist	name	将某个玩家从白名单删除。依赖于whitelist_api插件，不存在时自动关闭此工具
search_minecraft_wiki	query	让AI搜索Minecraft Wiki，以确保回答更准确
calculator	expression	简单的数学表达式计算器
item_caculator	expression,single_limit	数学表达式计算器，并将最终结果转换为物品计数法，即 盒、组、个，自动适应物品的堆叠数，不存在时默认使用64
add_pos_pos	name,pos,dimension	在指定位置添加一个坐标点。依赖于where2go或location_marker插件，两者都存在时，优先使用where2go，均不存在时，自动关闭此工具
add_pos_here	name	在玩家的位置添加一个坐标点，控制台执行时自动关闭此工具。依赖于where2go或location_marker插件，两者都存在时，优先使用where2go，均不存在时，自动关闭此工具
remove_pos	name	删除一个坐标点，where2go版本会自动将name转换为id。依赖于where2go或location_marker插件，两者都存在时，优先使用where2go，均不存在时，自动关闭此工具
search_pos	name	搜索一个坐标点。依赖于where2go或location_marker插件，两者都存在时，优先使用where2go，均不存在时，自动关闭此工具
get_all_pos	无	获取所有的坐标点列表.依赖于where2go或location_marker插件，两者都存在时，优先使用where2go，均不存在时，自动关闭此工具
ai_read_data	key	读取一条数据库内容
ai_read_all_keys	无	获取数据库中所有的键
ai_read_all_data	无	一次性读取数据库中所有键值对
ai_write_data	key,value	向数据库中写入一条数据(覆写模式)
ai_add_data	key,value	向数据库中写入一条数据(追加模式)
read_skills	skills	读取已注册的技能指导文件，引导 AI 执行特定任务
write_skills	skills、summary、content	创建或覆写一个技能文件并注册到技能索引中
modify_skills	skills、summary、content	修改已有技能文件并更新索引中的简介
delete_skills	skills	删除一个技能文件并从技能索引中移除
read_custom_tools	无	读取当前自定义 tools.py 文件的内容
modify_custom_tools	tools	用新代码替换整个自定义 tools.py 文件
append_custom_tools	tools	向自定义 tools.py 文件末尾追加新工具代码
setting_timer	duration	暂停执行指定秒数后再继续下一步操作
reload_plugin	无	热重载插件以应用配置、技能和自定义工具的更改，不会丢失聊天记录
ai_del_data	key	删除数据库中的一条数据
bot_chat	message	让 Mineflayer 机器人在 Minecraft 聊天中发送消息。
bot_whisper	username, message	让机器人私聊某个玩家。
bot_get_state	无	获取机器人完整状态（30+ 字段）。
bot_call_action	action, params	向机器人发送任意指令（goto，dig，place，attack 等）。
bot_start	无	启动 Mineflayer 机器人（如果未运行）。
bot_stop	无	停止 Mineflayer 机器人。
delegate_to_bot	task	将复杂的 Minecraft 任务委派给自主 Bot 控制器。

在配置文件中自定义工具

通过修改config/games_ai/tools/tools.py文件来实现自定义修改工具。

先来看看默认值如何：

from mcdreforged.command.command_source import CommandSource
from games_ai.games_ai_tool import register_tool

@register_tool(description="My Custom Tool")
def my_custom_tool(source: CommandSource, ai_prefix: str):
    return "Tool execution completed"

description 是必填项，告诉 AI 此工具的用途。parameters 字典（可选）定义了 AI 应传入的参数，遵循 OpenAI function calling 格式。函数签名必须包含 source: CommandSource 和 ai_prefix: str 作为前两个参数，其后跟随 parameters 中定义的参数。

在自己的MCDR插件中自定义工具

如果你在开发独立的 MCDR 插件，可以直接在插件代码中注册工具，无需修改 tools.py：

from games_ai.games_ai_tool import register_tool, register_bot_tool

@register_tool(
    description="你的自定义工具的描述",
    parameters={...}  # 可选
)
@register_bot_tool()  # 可选 — 让该工具可被 Mineflayer Bot 控制器使用
def my_plugin_tool(source: CommandSource, ai_prefix: str, ...):
    source.reply(f'{ai_prefix}正在执行我的工具...')
    return "工具执行结果"

你的插件需要在 mcdreforged.plugin.json 中将 games_ai 列为依赖，以确保 GamesAI 先加载：

{
    "id": "my_plugin",
    "dependencies": {
        "mcdreforged": ">=2.15.0",
        "games_ai": ">=0.4.1"
    }
}

以此方式注册的工具与内置工具完全相同——AI 可以直接调用，如果需要也可以使用 @register_bot_tool() 标记为 Bot 可用工具。

内置Skills

GamesAI 内置了以下技能文件，AI 在执行相关操作前会自动读取：

技能文件	描述
skills_management.md	指导 AI 如何正确读取、写入、修改和删除技能文件。
custom_tools_management.md	指导 AI 如何安全地读取、修改和追加自定义工具代码。
mineflayer_bot_guide.md	指导 AI 如何操控 Mineflayer 机器人（仅在 Bot 运行时可用）。

在配置文件中添加Skills

Skills 技能系统让你可以编写指导文件来规范 AI 处理特定任务的方式——例如白名单管理、假人控制等。

技能文件存放在 config/games_ai/skills/ 目录下，格式为 Markdown（.md）。要注册一项技能，编辑 config/games_ai/skills/skills.json。以下是一个示例配置（whitelist.md 和 player.md 仅为示例文件名，并非插件内置文件）：

[
    {
        "file": "whitelist.md",
        "description": "添加/删除/查询白名单时都应读取此技能文件"
    },
    {
        "file": "player.md",
        "description": "创建/控制/删除假人时必须读取此技能文件"
    }
]

• file — 技能文件名（相对于 skills 文件夹）。
• description — 展示给 AI 的简短提示，说明何时应当读取此技能。

技能注册后会出现在 AI 的系统提示中。AI 可以使用 read_skills 工具在执行相关任务前读取技能文件的完整内容。

故障排查

!!ask 错误

症状	可能原因	解决方法
HTTP 400	请求体格式错误	检查 extra_body 格式是否与 API 提供商的要求一致。
HTTP 401	API Key 无效	检查 AI 配置中的 api_key。
HTTP 404	模型不存在	检查 ai_model 名称是否正确。
HTTP 429	请求频率过高	稍后重试，或升级 API 套餐。
超时/无响应	网络问题或 API 响应慢	使用 !!gamesai speedtest 检查延迟。尝试更换模型。
「未知函数」回复	AI 调用了不存在的工具	通常无害——AI 会重试其他方法。

Mineflayer Bot 错误

症状	相关日志	解决方法
Bot 未启动（完全没有 [Mineflayer] 日志）	Mineflayer bot is enabled but Node.js was not found	安装 Node.js >= 18。运行 node --version 验证。
Bot 在启动时被禁用	Mineflayer requires Node.js >= 18, but found v{X}	将 Node.js 升级到 18 或更高版本。
Bot 在启动时被禁用	WebSocket port {X} is already in use!	在配置文件中修改 websocket.url 为不同端口，然后 !!gamesai reload。
[Bot] Kicked from server 伴随认证原因	[Bot] Kicked from server. Reason: 后跟认证错误	通过 !!aibot set 检查 username/password/auth。Microsoft 认证需确保账号已迁移。
Bot 卡住不动	goto 操作返回 "No path found" 错误	goto 操作现在会在无路径时返回错误。尝试不同的坐标。
[Bot] Disconnected 后自动重连	[Bot] Disconnected. Reason: ... 后跟 Reconnecting in 5 seconds...	服务器重启或短暂断网后的正常行为。Bot 会在 5 秒后自动重连。
[Bot] Died, respawning...	[Bot] Died, respawning...	正常——Bot 死亡后会自动重生，无需干预。
Bot 不响应指令	日志中无 [WS] 活动	使用 !!aibot leave 然后 !!aibot join 重启。若持续存在，检查 websocket.url 端口是否可访问。
日志中出现 npm install failed	npm install failed (exit {X}) 或 npm is not installed or not in PATH	确保 npm 已安装且在 PATH 中。检查日志中的详细错误信息定位具体包问题。

日志与调试

• 启用调试模式：!!gamesai debug — 显示完整 AI 提示词和工具调用结果。
• Mineflayer Bot 日志在 MCDR 控制台以 [Mineflayer] 前缀显示。
• OpenAI SDK HTTP 日志自动路由至 MCDR 控制台（详见 OpenAI 日志桥接）。
• 如果以上方法均无效，请检查 config/games_ai/config.json 是否存在配置错误。

本次更新

Version 0.6.0

🎯 核心亮点

• 🤖 Mineflayer Bot — 由 AI 通过 WebSocket 全自主控制的 Minecraft 机器人
• ⚙️ 配置系统重制 — 类型自适应配置、!!aibot 管理命令、输入验证
• 📋 日志桥接 — OpenAI/httpx SDK 日志无缝路由至 MCDR 日志系统

1. Mineflayer Bot 集成

0.6.0 最大的新特性：基于 Mineflayer 的全自主 Minecraft 机器人，通过 WebSocket 命令接口由 AI 控制。

支持的操作（20+）：goto（A* 寻路）、efly（鞘翅飞行）、dig、place、attack、useOn、equip/unequip（装备/卸下盔甲）、mount/dismount（骑乘/离开）、craft（合成）、容器与熔炉管理、lookAt、setControlState 等。

扩展 get_state：30+ 字段 — 位置、视角 (yaw/pitch)、速度、盔甲 (head/chest/legs/feet)、氧气、经验、世界时间、天气、维度、睡眠状态等。

自定义物理引擎：击退响应（通过 entity_velocity 数据包）和实体碰撞/挤压。寻路时自动暂停物理以避免干扰。

Bot 管理：

• !!aibot join / !!aibot leave — 生命周期控制
• !!aibot set username/password/auth — 配置 Bot 身份，含输入验证
• bot_start / bot_stop 工具 — AI 自主控制
• delegate_to_bot — 将复杂任务移交给自主控制器

其他改进：死亡自动重生、默认启用物理引擎、path_update noPath 检测（无法到达时立即返回错误）、聊天消息自动去除 § 字符。

2. 配置系统重制

• 类型自适应 set_config：!!gamesai config set 现在读取旧值的类型并自动将新值转换为匹配类型。设置 float 为 "20" 仍保持 float，bool 保持 bool 等。类型不匹配错误会被捕获并报告。
• !!aibot set 命令：无需手动编辑 JSON 即可管理 Bot 的用户名、密码和认证方式。用户名/密码验证为 [a-zA-Z0-9_]，auth 限制为 microsoft/mojang/offline。

3. OpenAI 日志桥接

openai 和 httpx Python 日志现已完全重定向至 MCDR Logger：

• 所有 HTTP 请求/响应日志出现在 MCDR 控制台
• 原始 handler 已清除、propagation 已禁用 — 无重复 stderr 输出

鸣谢与声明

特别感谢 WangHai Server 为此插件的测试提供了基础

特别感谢 william-song-shy (William Song) 为 !!ask 无历史模式提供的建议。

特别感谢 ZhangZuoqian (张作乾) 为测速指令提供的建议。

AI(LLM)模型生成的一切内容与此插件无关

自定义工具造成的一切后果与本插件无关

赞助与贡献者名单

赞助地址：爱发电

为GamesAI赞助的将会出现在下列的赞助者名单中（当前没有赞助者）：

#	赞助者	金额	日期
-	-	-	-

许可证

MIT License, Copyright (c) 2026 yello