AIPlayer — LLM 驱动的 Minecraft AI 玩家

一个基于 LLM（默认 DeepSeek，兼容任意 OpenAI 格式接口）的 Minecraft 自主决策机器人。玩家在游戏里对 Bot 说话，Bot 自主规划并执行动作。

架构总览

游戏内 @bot1 发消息
        │
        ▼
Control/（Node.js 游戏交互）── FastAPI HTTP :8000 ──► Decision/（Python AI 决策）──► LLM API
  Mineflayer + pathfinder         POST /plan/{bot_id}         OpenAI SDK + 结构化输出

• Control/：Node.js 层，负责与 Minecraft 交互（Mineflayer）、执行动作、维护聊天历史
• Decision/：Python 层，负责调用 LLM 做规划 / 反思 / 生成技能，通过 FastAPI 提供 HTTP 接口
• 两层通过 FastAPI HTTP 通信，端口 8000

目录结构

mc/
├── Control/                  # Node.js 游戏交互层
│   ├── launcher.js           # 多 Bot 启动器（node launcher.js 3）
│   ├── bot/index.js          # Bot 核心：监听聊天、规划-执行-续行主循环、敌怪监控
│   ├── bot/history.js        # 聊天历史（进程内内存，最多 50 条）
│   ├── core/registry.js      # 工具注册中心（自动扫描 / 热更新 / 同步 tools.json）
│   ├── tools/                # 22 个原子工具，一个工具一个文件
│   ├── actions/index.js      # 动作执行入口 / 任务状态收束 / 保存技能
│   ├── python/client.js      # FastAPI 客户端（状态采集 + 请求规划 + 执行动作）
│   ├── commands/quick.js     # 终端快捷指令（!背包 等）
│   ├── utils/                # 日志、规划响应解析
│   ├── config.json           # Minecraft 服务器地址、fastapi_url 等
│   └── package.json          # 依赖：mineflayer、mineflayer-pathfinder
├── Decision/                 # Python AI 决策层
│   ├── main.py               # FastAPI 入口（/plan /reflect /saveSkill /health）
│   ├── server.py             # 规划 / 反思 / 技能保存逻辑
│   ├── LLMAgent.py           # LLM 客户端（AsyncOpenAI，重试与错误分类）
│   ├── LLMData.py            # pydantic 结构化输出模型
│   ├── skill_manager.py      # 技能加载 / 查询 / 保存
│   ├── prompts/              # decide / reflect / generateSkill 提示词（YAML + Jinja2）
│   ├── skills/               # 已保存的技能（每技能一个目录）
│   ├── config.py             # 配置读取（根目录 .env）
│   └── requirements.txt      # Python 依赖
├── docker-compose.yml        # 一键 Docker 启动（control + decision）
├── Control/Dockerfile        # Node 镜像
├── Decision/Dockerfile       # Python 镜像
└── .env.example              # 环境变量示例（复制为 .env 后填写）

快速开始（本地运行）

前置：Node.js 18+（推荐 24）、Python 3.10+、一个 Minecraft 服务器（默认离线模式连接）。

1. 安装依赖

cd Control
npm install
cd ..

pip install -r Decision/requirements.txt

2. 配置

复制 .env.example 为 .env 并填写：

OpenAI_API_KEY=你的APIKey
LLM_MODEL=deepseek-v4-flash        # 模型名，可按需修改
MODEL_BASE_URL=https://api.deepseek.com   # OpenAI 兼容接口地址

编辑 Control/config.json：

• host：Minecraft 服务器地址（本地服务器填 127.0.0.1，局域网填对应 IP；Docker 运行时保持默认 host.docker.internal）
• 若服务器端口不是 25565、或需要指定协议版本，可在 Control/bot/index.js 的 mineflayer.createBot 中取消注释 port / version

Bot 默认以离线模式登录，用户名固定为 AIPlayer1（多 Bot 时依次为 AIPlayer2…）。

3. 启动

终端 1 —— 启动 Python 决策服务（项目根目录）：

$env:PYTHONPATH = "$PWD\Decision"
uvicorn Decision.main:app --port 8000

（cmd 对应：set PYTHONPATH=%CD%\Decision，再运行同一条 uvicorn 命令；开发时可加 --reload）

终端 2 —— 启动 Bot：

node Control/launcher.js 1

不带参数直接 node Control/launcher.js 会交互式询问启动几个 Bot；node Control/launcher.js 3 启动 3 个。

4. 使用

游戏内对 Bot 说话，消息以 @bot1 开头（多 Bot 时用 @bot2、@bot3…）：

@bot1 帮我挖点钻石
@bot1 我背包里有什么？
@bot1 跟着我

也可以在运行启动器的终端里输入快捷指令（不经过 LLM，直达动作执行）。不带 @botN 会分发到所有 Bot，带 @botN 只发给指定 Bot：

!背包      !物品      !状态      !坐标
!附近实体
!保存技能 转圈
!注册工具 {"name":"Xxx","args":["a"],"class":"DynamicTool","description":"...","code":"..."}

Docker 运行

# 先配置根目录 .env（同上）
docker compose up --build

docker-compose.yml 会启动 decision（自动加载根目录 .env）和 control 两个容器，控制层通过 http://decision:8000 访问决策层。

核心特性

• 全量工具一次决策：22 个原子工具全部加载，LLM 一次输出动作序列，无需分轮查询
• N 步折中规划：LLM 通过 continue 字段自主决定何时续行，兼顾实时性与多步任务
• 工具文件化：一个工具 = tools/ 目录下一个文件，注册中心自动扫描、目录监听热更新，变更自动同步 tools.json 供 Python 端热重载
• 环境状态自动注入：每轮规划前自动执行 GetState / GetAroundBlocks，把最新状态注入 prompt
• 技能系统：LLM 从历史中生成技能（子动作序列），通过 skillProgress 逐段续行推进
• 敌怪监控：发现敌对生物自动中断任务并逃离，安全后恢复
• 多 Bot：launcher.js N 一键启动多个独立 Bot 进程，注册 / 注销自动上报

技术栈

Node.js（mineflayer 4.x + mineflayer-pathfinder）、Python 3.10（FastAPI、OpenAI SDK、pydantic）、任意 OpenAI 兼容 LLM API（默认 DeepSeek）。

项目状态

核心功能已完成：Docker 化、工具热更新、环境状态注入、敌怪监控均已就绪。更详细的技术说明见 DEVELOPER.md。