MinecraftBot

基于 Mineflayer、MCP 和可验证 Skill 状态机的 Minecraft Java 版自主玩家。它以独立游戏角色加入服务器，主要依靠协议级结构化数据感知世界，并能够导航、采集、合成、战斗、建造和持续执行长任务。

推荐配合独立的 Demiurge 桌面 Agent 使用：Demiurge 提供人物设定、当前 LLM、长期记忆、桌面图片对话和高层决策；MinecraftBot 负责连接服务器、结构化感知和可靠执行。两个项目相互独立，不要求 Minecraft 客户端安装 Mod。

两种运行模式

模式	规划模型	适合场景
Demiurge MCP（推荐）	使用 Demiurge 当前配置的唯一 LLM	共享人物、长期记忆、多人聊天身份和桌面图片对话
独立模式	MinecraftBot 自己调用 OpenAI-compatible API	不运行 Demiurge 的服务器机器人或开发调试

项目不会提交 .env、API Key、运行日志、SQLite 记忆数据库或本地 Minecraft 数据。

已实现能力

• 离线或微软身份连接、自动重连、固定角色名。
• 玩家、背包、装备、实体、方块、时间、天气和事件感知。
• 场景摘要、空间位置记忆、任务持久化及掉线恢复。
• 外部 LLM API 规划、失败恢复及严格 JSON 校验。
• 精确物品、方块、生物、配方数据库和递归材料计算。
• 本地攻略 RAG，可导入 Markdown/TXT 攻略。
• Skill 资源锁、优先级抢占、超时、取消、进度、重试及结果验证。
• 导航、跟随、挖掘、采集、放置、合成、熔炼、战斗、逃生、进食、交付、箱子存取、建造和探索。
• 低血量逃生、卡死、背包满、工具低耐久监控。
• SQLite 记忆、JSON 健康接口、结构化日志。
• 深度缓冲几何重投影、残差区域聚类、已知变化掩膜和可选 VLM 分析接口。
• Mock LLM 和 Mock Executor，可在没有 MC 服务器或 API Key 时测试主体系统。
• MCP stdio 工具/资源、游戏事件通知，以及 Demiurge 人设、会话和长期记忆闭环。

运行结构

PCL（FuQiang） ───────公网──────> 腾讯云 Minecraft Server
                                      ↑
本机 Demiurge ──MCP stdio──> Mineflayer AI_Player
      │ 当前角色/长期记忆           │ 结构化感知/RAG/Skill Runtime
      └────唯一 LLM 规划与对话──────┘

环境要求

• Minecraft Java 服务端。
• Node.js 22.13 或更高版本。
• pnpm 10 或更高版本，也可以通过 Corepack 启用。
• MCP 模式需要已配置 LLM 的 Demiurge；独立运行模式才需要 OpenAI-compatible API。

本地安装

corepack enable
pnpm install
cp .env.example .env

独立运行时至少修改：

MC_HOST=127.0.0.1
MC_PORT=25565
MC_USERNAME=AI_Player
MC_AUTH=offline
MC_OWNER=FuQiang

LLM_MODE=api
LLM_BASE_URL=https://你的API地址/v1
LLM_API_KEY=你的密钥
LLM_MODEL=你的模型名

先进行离线自检：

pnpm typecheck
pnpm test
pnpm smoke

启动开发模式：

pnpm dev

生产模式：

pnpm build
NODE_ENV=production pnpm start

使用 Demiurge（推荐）

分别构建两个独立项目：

# 本项目
pnpm install --frozen-lockfile
pnpm build

# Demiurge（单独克隆）
git clone https://github.com/Dancncn/Demiurge.git
cd Demiurge
npm install
npm run tauri dev

Windows 构建 Demiurge 还需要 Rust stable（MSVC）、Visual Studio 2022 Build Tools 的“使用 C++ 的桌面开发”以及 Windows SDK；若出现找不到 link.exe，请先补齐这些组件。

在 Demiurge 的“设置 → Minecraft”中选择本项目目录和 Node.js 可执行文件，填写腾讯云服务端公网地址、AI 游戏用户名 AI_Player 与主用户游戏名 FuQiang，最后打开“启用”。保存设置后 Demiurge 会自动启动 MCP 子进程；退出、禁用或修改配置时会停止/重启它。

MCP 模式会强制使用 MCP_STDIO=true、LLM_MODE=mock，但这里的 mock 只表示 Mineflayer 禁止调用内部规划模型。所有规划、人格与对话仍由 Demiurge 当前配置的真实 LLM 完成。公开聊天与私聊都会携带真实发言用户名、频道、主用户标识和场景。玩家输入 AI_Player，跟着我 即可自然点名；未点名的公开消息由模型结合对话语境判断是否在和它说话。对话和关键经历写入当前角色的同一 memory namespace；自动长期记忆由代码强制写入场景、频道、玩家用户名和主用户标识，不依赖记忆提取模型自行保留这些信息。

桌面输入区支持 JPEG、PNG、GIF、WebP 原生多模态图片（单张 10 MB、合计 20 MB），图片只发给 Demiurge 当前模型，不经过游戏聊天。

完整配置与联机验收见 Demiurge 集成指南。

Minecraft 服务端配置

server.properties：

online-mode=false
server-port=25565
server-ip=
white-list=true

重启服务端后，在服务端控制台执行：

whitelist on
whitelist add FuQiang
whitelist add AI_Player

离线模式没有可靠的账号身份验证。腾讯云安全组应只允许你的公网 IP 访问 TCP:25565，或通过 Tailscale/WireGuard 连接，不能依赖白名单防止同名冒充。

游戏内命令

MC_OWNER 指定主用户，用户名比较不区分大小写，但事件和记忆会保留玩家实际显示的精确用户名。模型会把主用户和其他玩家的关系、权限及记忆分开。其他玩家仍可以公开聊天、私聊和请求普通帮助。MCP 模式下自然语言消息统一交给 Demiurge 当前角色判断和处理；独立模式只执行主用户明确叫出 AI 游戏用户名的任务。

AI_Player，帮助
AI_Player，状态
AI_Player，停止
AI_Player，跟着我
AI_Player，去 120 64 -30
AI_Player，收集16个橡木
AI_Player，制作一把石镐并交给我
AI_Player，探索周围区域

固定 @AI 前缀已取消。直接使用设置中的 AI 游戏用户名称呼它；私聊天然视为对 AI 说话，未点名的公开聊天则由模型判断是否需要加入对话。

攻略知识库

精确配方和注册表由当前服务端版本的 minecraft-data 提供，不经过向量检索。自然语言攻略可以批量导入：

pnpm knowledge:index ./my-guides

支持递归读取 .md 和 .txt。默认使用本地哈希向量，不会额外产生 embedding API 成本；后续可以替换 GuideRag 的向量实现。

健康检查

默认只监听腾讯云本机：

GET http://127.0.0.1:3008/health
GET http://127.0.0.1:3008/metrics

将 HEALTH_PORT=0 可关闭。不要把健康端口直接暴露到公网。

视觉模块

主体系统不依赖截图。src/vision 已实现：

• 基于上一帧深度和相机矩阵的几何重投影。
• 实际帧与预测帧的 RGB 残差。
• 已知动作区域掩膜。
• 连通区域聚类和阈值过滤。
• 异常事件及可选 VLM 调用。

Mineflayer 本身不提供原生 RGB 与深度缓冲，因此启用视觉时需要离屏渲染器或客户端 Mod 提供帧。项目已提供 HttpFrameSource，设置 VISION_ENABLED=true 和 VISION_FRAME_URL=http://127.0.0.1:端口/frame 即可接入。没有外部帧源时保持 VISION_ENABLED=false，所有游戏能力继续使用结构化感知。

安全边界

• 默认关闭 PVP：ALLOW_PVP=false。
• 可关闭丢弃物品：ALLOW_DROP_ITEMS=false。
• 单次计划最多 MAX_PLAN_STEPS 步。
• 单次目标距离受 MAX_ACTION_DISTANCE 限制。
• 独立模式只接受主用户明确叫出 AI 游戏用户名的任务；MCP 模式由 Demiurge 判断未点名公开聊天是否需要回应。
• LLM 只能选择注册 Skill；参数经过 Zod 校验。
• API Key 只从环境变量读取，日志会进行字段脱敏。
• 紧急逃生优先级高于普通任务，可以抢占移动和视角。

更具体的腾讯云部署步骤见 docs/DEPLOY_TENCENT.md，Skill 接口见 docs/SKILLS.md，视觉接入约定见 docs/VISION.md。

项目边界

• 当前面向 Minecraft Java 版，协议连接由 Mineflayer 提供。
• 结构化感知是默认主路径；局部视觉和 VLM 需要额外帧源。
• 微秒/毫秒级移动与战斗细节由执行器和 Skill 处理，LLM 不参与每一帧控制。
• 离线服务器无法可靠验证用户名归属，应限制服务器端口来源或使用私有网络。
• MCP 模式下所有公开聊天都可能触发 Demiurge 的语境判断，应结合服务器人数评估 API 成本。

开发与验证

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

测试不要求真实 Minecraft 服务器或真实 LLM Key；Mock Executor 和 Mock LLM 会覆盖规划、Skill、记忆、MCP 通知与视觉残差的主体链路。