Чат-бот для каждого сервера 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)
Заголовок раздела «Размер зависимостей (minecraft-data)»Помощь по рецептам использует пакет 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 вместе при копировании активной базы данных.