Перейти к содержимому

Чат-бот для каждого сервера Minecraft

← Назад к оглавлению документации

Панель предлагает настраиваемый администратором чат-бот для каждого управляемого сервера Minecraft, который настраивается на вкладке сервера Настройки → Чат-бот. Он подключается к конечной точке совместимого с OpenAI чат-запроса, включая Ollama на другом хосте в локальной сети. Каждый сервер имеет свою собственную конечную точку, модель, имя вызова, персону, политику транскрипции, сообщения для привлечения внимания и политику полномочий. По умолчанию используется вызов @wizard, а стандартная персона представляет собой древнего, игривого внутриигрового волшебника; оба настраиваются.

Настройки чат-бота

  • Любой игрок может использовать @wizard <сообщение> (или настроенное имя вызова) для общения и получения детерминированной помощи по рецептам ванильной игры с учетом версии Minecraft.
  • Приветствия при входе и настраиваемое одноразовое напоминание о сеансе игры информируют игроков о доступности чат-бота. @wizard chat открывает короткое окно для подтверждения участия в диалоге; @wizard bye закрывает его.
  • Базовые пользователи могут использовать включенные полномочия для себя/мира. Контроллеры полномочий могут выполнять отдельно проверенные действия, влияющие на другого онлайн-игрока. Игроки, не входящие ни в одну из этих групп, могут только общаться.
  • Самостоятельные подарки базовых пользователей используют разрешенный список предметов. Контроллеры могут дарить другому игроку любой допустимый предмет ванильной игры или из модов с пространством имен, в пределах лимита количества и других мер предосторожности.

Транскрипты чат-бота

Конфигурация и транскрипты доступны только администратору. Модель никогда не получает необработанные RCON-запросы или произвольное выполнение команд. Сообщение раскрывает только один фиксированный инструмент, соответствующий его явному намерению; код сервера проверяет авторизацию, аргументы, флаги, количества, задержки и точные имена онлайн-игроков перед выполнением существующей операции службы. Селекторы Minecraft отклоняются, действия между игроками не могут быть нацелены на вызывающего абонента, полномочия начинаются в режиме симуляции (dry-run), и каждое предпринятое действие регистрируется. Неподдерживаемые модели вызова инструментов возвращаются к обычному общению.

Ответы ограничены для чата Minecraft. Известные рецепты ванильной игры берутся из встроенных данных рецептов с учетом версий и отображаются в виде стабильных строк 2x2/3x3; LLM не доверяют создание макетов рецептов. Неизвестные или модовые рецепты направляют игрока к JEI/REI вместо того, чтобы выдумывать ответ.

  • src/services/wizard.js: конфигурация для каждого сервера, запросы, совместимые с OpenAI, обработка чата, привлечение внимания, хранение транскриптов и ограничения ответов.
  • src/services/wizardPowers.js: проверки ролей, схемы инструментов для конкретных намерений, валидация, выполнение, задержки и аудит полномочий.
  • src/services/wizardRecipes.js: детерминированный поиск рецептов с учетом версий и форматирование сетки. Данные рецептов и предметов поступают из пакета minecraft-data. (Более ранний черновик этого документа указывал на папку src/data/recipes/, которая так и не была закоммичена; такой папки нет, и данные находятся в пакете. См. “Размер зависимостей”.)
  • src/analytics/ingest.js: пересылает разобранные события входа, выхода и чата игроков чат-боту.
  • src/web/routes/wizard.js, public/js/pages/integrations.js и views/partials/server/integrations.hbs (через chatbot.hbs): API администратора и вкладка настроек сервера “Настройки → Чат-бот”.
  • src/db/migrations/011_wizard_chat.js, 013_wizard_invocation_name.js, 015_wizard_powers.js, 017_wizard_outreach.js и 019_wizard_power_controllers.js: постоянная схема.
  • test/wizard.test.js: тесты авторизации, границ инструментов, хранения, привлечения внимания и поведения чата.

Внутренние имена маршрутов/модулей/таблиц wizard сохраняются для совместимости обновлений и API; “chatbot” — это общедоступный термин продукта. Аналогично, сохраненное поле power_testers_json соответствует группе Базовые пользователи в пользовательском интерфейсе.

Помощь по рецептам использует пакет minecraft-data. Он занимает много места на диске (около 429 МБ в установленном виде) и поставляется внутри производственного образа, поскольку является зависимостью во время выполнения, а не для разработки. Мы намеренно сохраняем его, чтобы помощь по рецептам работала в автономном режиме для каждого выпуска Minecraft без сетевых вызовов.

Примечания для того, кто будет смотреть это дальше (человек или ИИ), чтобы размер не стал сюрпризом:

  • В настоящее время используются только данные для Java (pc). wizardRecipes.js читает minecraftData.versions.pc и таблицы recipes, items и blocks для каждой версии. Файлы, которые он фактически затрагивает, составляют примерно 15 МБ для всех версий pc.
  • Около 330 МБ пакета приходится на data/bedrock, и здесь пока ничего его не читает. Мы намеренно оставляем его на месте. Если панель когда-либо добавит поддержку Bedrock Minecraft, данные рецептов и предметов для Bedrock уже будут здесь, поэтому функция рецептов сможет охватить серверы Bedrock без добавления новой зависимости. Начните с minecraftData.versions.bedrock и следуйте той же структуре, что и путь pc.
  • Если размер когда-либо придется уменьшить до добавления поддержки Bedrock, в этом репозитории уже есть шаблон для этого. src/services/itemRegistry.js извлекает файлы minecraft-data из CDN jsDelivr, когда они ему нужны, и кэширует их в api_cache. Либо этот подход, либо небольшой тщательно отобранный поднабор src/data/recipes/, охватывающий несколько распространенных версий, значительно уменьшит размер образа.

Все настройки и сохраненные транскрипты хранятся в базе данных SQLite панели по пути /data/panel.db внутри контейнера панели. При стандартном монтировании Compose путь на хосте будет ${DATA_DIR_HOST}/panel.db (например, /opt/msm/data/panel.db). Соответствующие таблицы: wizard_configs, wizard_transcripts и wizard_outreach; аудиты полномочий — это строки в таблице events с типом wizard-power. Необязательный ключ API LLM зашифрован AES-256-GCM с ключом панели в состоянии покоя, .secret-key в папке данных (отдельно от SESSION_SECRET).

Сделайте резервную копию базы данных и остановите панель перед прямым редактированием SQLite, чтобы ее WAL обрабатывался безопасно. Использование UI/API администратора предпочтительнее, поскольку оно применяет валидацию и шифрование. Сохраняйте файлы panel.db, panel.db-wal и panel.db-shm вместе при копировании активной базы данных.