Перейти до вмісту

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

← Назад до індексу документації

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

Налаштування чат-бота

  • Будь-який гравець може використовувати @wizard <повідомлення> (або налаштоване ім’я виклику) для спілкування та отримання детермінованої допомоги з рецептами ванільної гри, яка враховує версію Minecraft.
  • Привітання при вході та налаштовувана одноразова перевірка ігрової сесії нагадують гравцям про доступність чат-бота. @wizard chat відкриває коротке вікно для участі в розмові; @wizard bye закриває його.
  • Звичайні користувачі можуть використовувати увімкнені власні/світові можливості. Контролери потужності можуть використовувати окремо перевірені дії, що впливають на іншого онлайн-гравця. Гравці, які не належать до жодної з цих груп, можуть лише спілкуватися.
  • Власні подарунки звичайних користувачів використовують список дозволених предметів. Контролери можуть дарувати іншому гравцеві будь-який дійсний ванільний або модифікований предмет з простором імен, з урахуванням обмеження кількості та інших запобіжних заходів щодо потужності.

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

Конфігурація та транскрипти доступні лише адміністраторам. Модель ніколи не отримує необроблений RCON або довільне виконання команд. Повідомлення розкриває лише один фіксований інструмент, що відповідає його явному наміру; серверний код перевіряє авторизацію, аргументи, прапори, кількості, періоди блокування та точні імена онлайн-гравців перед виконанням існуючої операції служби. Селектори Minecraft відхиляються, міжгравцеві дії не можуть націлюватися на викликаючого, потужності починаються в режимі сухого запуску, і кожна спроба використання потужності реєструється. Непідтримувані моделі виклику інструментів повертаються до звичайного спілкування.

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

Основні файли реалізації

Section titled “Основні файли реалізації”
  • 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)

Section titled “Розмір залежностей (minecraft-data)”

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

Примітки для того, хто переглядатиме це наступним (людина чи ШІ), щоб розмір не був несподіванкою:

  • Зараз використовується лише Java-дані (pc). wizardRecipes.js читає minecraftData.versions.pc та таблиці рецептів, предметів та блоків для кожної версії. Файли, до яких він фактично звертається, сумарно становлять приблизно 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/, що охоплює кілька поширених версій, значно зменшить розмір образу.

Локальне сховище та ручна перевірка

Section titled “Локальне сховище та ручна перевірка”

Усі налаштування та збережені транскрипти зберігаються в базі даних 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 за допомогою ключа панелі для зберігання (окремо від SESSION_SECRET).

Зробіть резервну копію бази даних та зупиніть панель перед прямим редагуванням SQLite, щоб її WAL оброблявся безпечно. Використання інтерфейсу адміністратора/API є кращим, оскільки воно застосовує валідацію та шифрування. Зберігайте файли panel.db, panel.db-wal та panel.db-shm разом при копіюванні живої бази даних.