MinecraftBot

Автономный игрок Minecraft Java Edition на основе Mineflayer, MCP и проверяемого конечного автомата Skill. Он заходит на сервер как самостоятельный игровой персонаж и воспринимает мир главным образом через структурированные данные на уровне протокола. Он умеет перемещаться, добывать, собирать, создавать, сражаться, строить и непрерывно выполнять длительные задачи.

Рекомендуется использовать вместе с отдельным десктопным агентом Demiurge: Demiurge предоставляет персонажа, текущую LLM, долговременную память, диалог с изображениями на рабочем столе и принятие решений высокого уровня; MinecraftBot отвечает за подключение к серверу, структурное восприятие и надёжное выполнение. Оба проекта независимы друг от друга, и для Minecraft-клиента установка модов не требуется.

Два режима работы

Проект не коммитит .env, API-ключи, журналы выполнения, базу памяти SQLite или локальные данные Minecraft.

Related MCP server: Minecraft Dedalus MCP

Реализованные возможности

• Подключение с офлайн- или Microsoft-идентификацией, автоматическое переподключение, фиксированное имя персонажа.

• Восприятие игроков, инвентаря, экипировки, сущностей, блоков, времени, погоды и событий.

• Сводка сцен, память о пространственном положении, сохранение задач и восстановление после обрыва соединения.

• Планирование через внешний LLM API, восстановление после сбоев и строгая проверка JSON.

• Точная база предметов, блоков, существ и рецептов, рекурсивный расчёт материалов.

• Локальный RAG по гайдам, импорт текстовых гайдов из Markdown/TXT.

• Блокировки ресурсов Skill, приоритетное вытеснение, таймауты, отмена, прогресс, повторные попытки и проверка результатов.

• Навигация, следование, копание, сбор, размещение, создание, выплавка, бой, побег, приём пищи, доставка, операции с сундуками, строительство и исследование.

• Мониторинг побега при низком здоровье, зависаний, полного инвентаря и низкой прочности инструментов.

• Память SQLite, JSON-интерфейс состояния здоровья, структурированные журналы.

• Геометрическая перепроекция буфера глубины, кластеризация остаточных областей, маски известных изменений и опциональный интерфейс анализа VLM.

• Mock LLM и Mock Executor для тестирования основной системы без MC-сервера или API-ключа.

• MCP stdio-инструменты/ресурсы, уведомления об игровых событиях, а также замкнутый цикл с персонажем Demiurge, сессиями и долговременной памятью.

Структура выполнения

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

Требования к окружению

• Сервер Minecraft Java Edition.

• Node.js 22.13 или выше.

• pnpm 10 или выше; можно активировать через Corepack.

• Для режима MCP требуется Demiurge с настроенной LLM; OpenAI-совместимый 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

Для сборки Demiurge на Windows также нужны Rust stable (MSVC), компонент «Разработка классических приложений на C++» из Visual Studio 2022 Build Tools и Windows SDK. Если появляется ошибка о том, что link.exe не найден, сначала установите эти компоненты.

В «Настройках → Minecraft» в Demiurge выберите каталог этого проекта и исполняемый файл Node.js, укажите публичный адрес сервера Tencent Cloud, имя AI-игры AI_Player и имя основного пользователя FuQiang, затем включите «Включить». После сохранения настроек Demiurge автоматически запустит дочерний процесс MCP; при выходе, отключении или изменении конфигурации он остановит/перезапустит его.

Режим MCP принудительно использует MCP_STDIO=true, LLM_MODE=mock, но здесь mock лишь означает, что Mineflayer запрещено использовать внутреннюю модель планирования. Всё планирование, идентичность и диалоги по-прежнему выполняются реальной LLM текущей конфигурации Demiurge. Публичные сообщения и личные сообщения содержат реальное имя отправителя, канал, отметку основного игрока и сцену. Игрок может написать AI_Player，跟着我, чтобы напрямую повернуться к боту; если публичное сообщение не адресовано явно, модель сама решает, обратились ли к ней, исходя из диалогового набора контекста. Диалоги и ключевые события записываются в то же пространство памяти memory текущего персонажа; автоматическая долговременная память и код принудительно фиксируют сцену, текст, имя канала, имя игрока и отметку основного игрока, не полагаясь на модель извлечения памяти для сохранения этой информации.

Область ввода на рабочем столе поддерживает нативные мультимодальные изображения JPEG, PNG, GIF, WebP (до 10 МБ за одно, до 20 МБ суммарно); изображения отправлены только текущей модели 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

В офлайн-режиме нет надёжной проверки подлинности учётных записей. В группе безопасности Tencent Cloud нужно разрешить доступ к TCP:25565 только с вашего публичного IP или подключаться через 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-игрока, которое задано в настройках; личные сообщения по умолчанию считаются обращением к боту, а неадресованные публичные сообщения модель решает по контексту.

База знаний по гайдам

Точные рецепты и реестровые данные берутся из minecraft-data текущей версии сервера и проходят без векторного поиска. Гайды на естественном языке можно массово импортировать:

pnpm knowledge:index ./my-guides

Поддерживается рекурсивное чтение .md и .txt. По умолчанию используются локальные хэш-векторы, что не создаёт дополнительных затрат на embedding API; в дальнейшем векторную реализацию GuideRag можно заменить.

Проверка работоспособности

По умолчанию проверка слушает только локально на Tencent Cloud:

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-буферов и буфера глубины, поэтому при включённом зрении нужен offscreen-рендер или клиент-мод, поставляющий кадры. В проекте уже есть 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-ключи считываются только из переменных окружения, в журналах поля маскируются.

• Экстренное бегство имеет приоритет над обычными задачами и может прерывать перемещение и обзор камеры.

Более подробные шаги по развёртыванию Tencent Cloud см. в docs/DEPLOY_TENCENT.md, интерфейс Skill — в docs/SKILLS.md, соглашения по визуальному подключению — в docs/VISION.md.

Границы проекта

• Сейчас ориентирован на Minecraft Java Edition; соединение по протоколу осуществляет Mineflayer.

• Структурное восприятие — основной путь по умолчанию; локальное зрение и VLM требуют дополнительного источника кадров.

• Детали движения и боя на микросекундном/миллисекундном уровне обрабатываются исполнителем и Skill, LLM не пользуется контролем каждой каждый.

• Офлайн-сервер не может надёжно подтвердить принадлежность имени пользователя; нужно ограничить доступ к порту сервера или использовать частную сеть.

• В режиме MCP любого публичного чата может включать контекстную оценку Demiurge, при оценке затрат на API следует учитывать количество игроков на сервере.

Разработка и проверка

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Тесты не требуют реального Minecraft-сервера или настоящего ключа LLM; Mock Executor и Mock LLM покрывают основную цепочку планирования, Skill, памяти, уведомлений MCP и визуальных остатков.