Чат-бот для Twitch с продвинутой модерацией и интерактивными командами

Разработан для cluelesstech98 с учетом особенностей канала

Версия 1.3.0

Содержание

1. Отказ от ответственности
   1. Юридические аспекты
   2. Технические предупреждения
   3. Ответственность пользователя
   4. Лицензирование и использование
2. Особенности
3. Быстрый старт
4. Список команд
5. Разработка
6. Безопасность
7. Вклад в проект
8. Поддержка и обратная связь

---

Отказ от ответственности

⚠️ ВАЖНО: ПРОЧТИТЕ ПЕРЕД ИСПОЛЬЗОВАНИЕМ ⚠️

Юридические аспекты

Это неофициальный проект

Warning

Данный бот НЕ является продуктом или сервисом компании Twitch Interactive, Inc. (Amazon.com, Inc.), это независимый проект с открытым исходным кодом.

Соблюдение правил Twitch

Warning

Вы обязаны соблюдать Условия использования Twitch, Сообществодские правила и все применимые законы вашей страны.

Ответственность за контент

Warning

Пользователь бота несёт полную ответственность за:

• Контент, генерируемый или распространяемый через бота
• Действия бота в чате канала
• Последствия использования команд модерации

Технические предупреждения

Отсутствие гарантий

Warning

Бот предоставляется "как есть", без каких-либо гарантий, но обратная связь присутствует.

Личные файлы намеренно не публикуются в открытом доступе из соображений безопасности.

Авторы не несут ответственности за:

• Потерю/утечку данных
• Блокировку канала Twitch
• Технические сбои и ошибки в работе
• Ущерб, причинённый использованием бота

Безопасность токенов

Caution

⚠️ НИКОГДА НЕ ДЕЛИТЕСЬ СВОИМИ ТОКЕНАМИ Twitch API. Храните ACCESS_TOKEN и CLIENT_ID в секрете, утечка токенов может привести к компрометации вашего аккаунта Twitch ⚠️

Настройка фильтров

Warning

Вы самостоятельно настраиваете фильтры запрещённых слов и правил модерации. Убедитесь, что они соответствуют:

• Правилам Twitch
• Законам вашей страны
• Локальным требованиям платформы

Ответственность пользователя

Тестирование

Warning

Перед использованием на основном канале протестируйте бота:

• На тестовом канале
• В различных сценариях
• С разными типами пользователей

Мониторинг

Warning

Рекомендуется регулярно:

• Проверять логи бота
• Обновлять токены доступа
• Следить за изменениями в Twitch API
• Обновлять список запрещённых слов

Important

Не рекомендуется:

• Использовать не по назначению
• Оставлять без присмотра
• Игнорировать ошибки
• Вписывать неприемлимые слова в текст кода (за исключением /bannedWords.js)
• Напрягать разработчика

Возрастные ограничения

Warning

Использование бота подразумевает, что вы:

• Достигли возраста, разрешённого для использования Twitch (13+ лет) (В тексте кода может присутствовать ненормативная лексика, 18+)
• Имеете право управлять Twitch каналом (от лица владельца или модератора канала)
• Понимаете риски использования сторонних ботов

Лицензирование и использование

Лицензия MIT

Warning

Проект распространяется под лицензией MIT, что означает:

• Вы можете свободно использовать, изменять и распространять код
• Авторы не несут ответственности за последствия использования
• Вы обязаны сохранять уведомление об авторских правах

Используя этот бот, вы подтверждаете, что:

Warning

• Прочитали и однозначно поняли данный отказ от ответственности
• Принимаете на себя все риски, связанные с использованием
• Обязаны соблюдать правила Twitch и местное законодательство
• Несёте полную ответственность за действия бота на канале

Условная рекомендация

Important

Перед публичным использованием проконсультируйтесь с юристом относительно соответствия вашей деятельности местному законодательству и правилам Twitch

---

Особенности

Прямая интеграция с Twitch Helix API

• Команды модерации (!варн, !таймаут, !бан) работают через официальный API Twitch, что гарантирует стабильность и соответствие последним требованиям платформы

Автоматическая модерация

• Фильтр запрещённых слов – прогрессивные наказания: первое нарушение → таймаут, второе → удвоенный таймаут, третье → бан. Список настраивается в src/commands/bannedWords.js
• Капс-детектор – система двух предупреждений, затем таймаут
• Анти-спам – обнаружение и наказание за повторяющиеся сообщения (нормализация текста, учёт пробелов)
• Система предупреждений (!варн) – три предупреждения → автоматический таймаут
• Стример, модераторы и VIP‑пользователи исключены из автомодерации

Интерактивные команды

• !iq / !айкью / !icq – случайный IQ с сохранением истории в базе данных
• !игра – отображение текущей игры (или "Стрим не в эфире")
• !followage / !подписка / !отслеживание – время отслеживания канала (разные форматы для стримера, модераторов, зрителей)
• !чебыло – история категорий текущего стрима с продолжительностью
• !команды – вывод списка доступных команд

Система званий (новая в версии 1.3.0)

• Автоматическое начисление званий за количество сообщений: новокек, кепка, свой, братан, нифтяк, нифига ты баклажан, писатель, летописец, ЛЕГЕНДА
• Звания за победы в дуэлях: воин, мастер, грандмастер, эпик, легенда, миф
• Команда !звание / !ачивка – просмотр своих званий
• Команда !прогресс – отображение прогресса до следующего звания
• Команда !установитьзвание – ручная установка звания (только для модераторов и стримера)
• Топ пользователей по званиям – !топ звания

Экономика и перевод очков

• Очки начисляются за активность (команды, участие в голосовании, выигрыш в рулетке)
• Команда !перевод @ник сумма – перевод очков другому пользователю (с проверкой баланса)
• Команда !+очки @ник сумма – начисление очков модераторами и стримером
• В будущем планируется обмен очков на бонусы канала

Голосование и развлечения

• !предложение [игра] – предложить игру для голосования
• !голос [игра] – проголосовать за игру (один голос за стрим)
• !итоги – статистика текущего стрима (результаты голосования, количество нарушений, банов, таймаутов)
• !пословица [слово] – случайная пословица с подстановкой указанного слова
• !рулетка – игровой автомат 3×3 с выигрышем очков. Кулдаун: 5 минут во время стрима, 30 секунд вне эфира (настраивается в config/cooldowns.js)

Управление через Telegram (новое в версии 1.3.0)

• При запуске бота в указанный Telegram‑чат автоматически отправляется меню с инлайн‑кнопками
• Модераторы могут через Telegram:
  • просматривать жалобы (/reports)
  • банить (/ban @user причина)
  • таймаутить (/timeout @user секунды причина)
  • начислять очки (/points @user количество)
  • выдавать предупреждения (/warn @user [причина])
• Все события (жалобы, баны, таймауты, дуэли, звания) логируются в Telegram‑чат

API‑сервер

• REST API для удалённого управления ботом (порт 3001)
• Эндпоинты для получения топа, статистики пользователя, управления жалобами, модерации

Конфигурация и производительность

• Все настраиваемые параметры вынесены в файлы config/:
  • cooldowns.js – кулдауны для игр
  • moderation.js – пороги автомодерации
  • titles.js – звания и их пороги
• База данных SQLite автоматически создаёт недостающие колонки; при необходимости дубли можно очистить скриптом clean-db.js

Хранение данных

• SQLite база данных – сохраняет IQ пользователей, историю нарушений, категории стримов, предложенные игры, голоса, очки, пословицы, жалобы, дуэли, баны, предсказания, анекдоты и звания
• Кэширование запросов (NodeCache) – оптимизация работы с Twitch API
• Журналирование – детальные логи для отладки

Прямая интеграция с Twitch Helix API

• Команды модерации (!варн, !таймаут, !бан) работают через официальный API Twitch, что гарантирует стабильность и соответствие последним требованиям платформы

Автоматическая модерация

• Фильтр запрещённых слов – мгновенный таймаут за использование запрещённых слов (список настраивается в src/commands/bannedWords.js)
• Капс-детектор – система двух предупреждений, затем таймаут
• Анти-спам – обнаружение и наказание за повторяющиеся сообщения
• Система предупреждений (!варн) – три предупреждения → автоматический таймаут

Интерактивные команды

• !iq – случайный IQ с сохранением истории в базе данных
• !игра – отображение текущей игры (или "Стрим не в эфире")
• !followage – время отслеживания канала (разные форматы для стримера, модераторов, зрителей)
• !чебыло – история категорий текущего стрима с продолжительностью
• !команды – вывод списка доступных команд
• !подарок – случайный подарок с механикой "бан-подарка" (для модераторов и стримера без ограничений)
• !+подарок – добавление нового подарка (только модераторы/стример)
• !-подарок – сброс кэша подарков (только стример)

Новые команды (v1.2.0)

• !предложение [игра] – предложить игру для голосования на следующий стрим
• !голос [игра] – отдать голос за предложенную игру (один голос за стрим)
• !итоги – показать результаты голосования и статистику текущего стрима
• !пословица [слово] – случайная пословица с подстановкой указанного слова
• !рулетка – игровой автомат с тремя эмодзи; при совпадении всех трёх – выигрыш 10 очков бота
• !баллы / !очки – показать текущее количество очков пользователя

Очки бота

• Начисляются за активность (команды, участие в голосовании, выигрыш в рулетке)
• В будущем планируется обмен на бонусы канала

Хранение данных

• SQLite база данных – сохраняет IQ пользователей, историю нарушений, категории стримов, предложенные игры, голоса, очки, пословицы
• Кэширование запросов (NodeCache) – оптимизация работы с Twitch API
• Журналирование – детальные логи для отладки

Быстрый старт

Предварительные требования

• Node.js (версия 16 или выше) — официальный сайт
• Git
• Аккаунт на Twitch и доступ к консоли разработчика

Установка и запуск

1. Получите код бота

   • Способ А (через Git): откройте командную строку (терминал) и выполните:

     git clone https://github.com/ваш-логин/twitch-bot.git
     cd twitch-bot

   • Способ Б (без Git): скачайте архив с репозитория (зелёная кнопка «Code» → «Download ZIP»), распакуйте его в удобную папку и откройте терминал в этой папке

2. Установите зависимости
   В терминале выполните команду:

   npm install

3. Переименуйте .env.example -> .env Замените своими данными:

• ACCESS_TOKEN=ваш_токен_бота
• CLIENT_ID=ваш_client_id
• BOT_USERNAME=имя_бота
• CHANNEL_NAME=ваш_канал

4. Запустите бота

• node src/bot.js
• проверьте наличие data/bot_database.db
• выдайте статус модератора через /mod
• протестируйте

Авторская ремарка

Данный проект может быть реализован как бот с ответом от лица стримера или модератора канала. Инструкции по умолчанию подразумевают аккаунт модератора. Для запуска от лица стримера замените BOT_USERNAME на название канала и используйте токен стримера, ВСЕГДА следите за действиями, которые выполняет кусок-какого-то-кода

ВНИМАНИЕ: Для обеспечения безопасности Вашего канала не рекомендуется использование от лица стримера

Список команд

Команды модерации (доступны модераторам и стримеру)

• !варн @ник – система предупреждений (3 предупреждения → таймаут)
• !таймаут @ник секунды [причина] – временный мут
• !бан @ник [причина] – перманентный бан с указанием причины
• !разбан @ник – снятие бана
• !жалобы – просмотр необработанных жалоб
• !+очки @ник сумма – начисление очков пользователю
• !установитьзвание @ник название – установка произвольного звания
• !сбросить_подарки – сброс кэша подарков (только стример)

Интерактивные команды (доступны всем)

Команда	Описание
!iq / !айкью / !icq	Случайный IQ 1–250 с историей
!игра	Текущая игра стрима (или «Стрим не в эфире»)
!followage / !подписка / !отслеживание	Время отслеживания канала
!чебыло	История категорий текущего стрима
!7тв	Ссылки на расширение 7TV
!пинг	Задержка ответа бота
!э	Тестовая команда
!тг	Ссылка на Telegram (из .env)
!правила / !rules	Правила чата
!команды	Список доступных команд
!подарок	Случайный подарок (для модераторов и стримера без ограничений)
!+подарок [название]	Добавление нового подарка (только модераторы/стример)
!сбросить_подарки (алиас !-подарки, !0подарки)	Сброс кэша подарков (только стример)
!предложение [игра]	Предложить игру для голосования
!голос [игра]	Проголосовать за игру (один голос за стрим)
!итоги	Итоги голосования и статистика стрима
!пословица [слово]	Случайная пословица с вашим словом
!рулетка	Игровой автомат 3×3, выигрыш очков (кулдаун зависит от статуса стрима)
!баллы / !очки	Показать свои очки
!перевод @ник сумма	Перевести очки другому пользователю
!звание / !ачивка	Показать свои звания (за сообщения и дуэли)
!прогресс	Прогресс до следующего звания
!топ очки / !топ points	Топ‑10 по очкам
!топ iq / !топ айкью	Топ‑10 по IQ
!топ варн / !топ warns	Топ‑10 по предупреждениям
!топ бан / !топ bans	Топ‑10 по банам
!топ звания	Топ пользователей по званиям
!дуэль @ник [очки]	Вызвать на дуэль
!принять	Принять вызов на дуэль
!отклонить	Отклонить вызов на дуэль
!репорт @ник [причина]	Отправить жалобу на пользователя
!анекдот	Случайный анекдот
!судьба	Предсказание на день (один раз в день)
!тест [сообщение]	Тестовая команда (бот повторяет сообщение)

Команды модерации (доступны модераторам и стримеру)

• !варн @ник – Система предупреждений (3 предупреждения → таймаут)
• !timeout @ник секунды – Временный мут
• !бан @ник [причина] – Перманентный бан с указанием причины

Интерактивные команды (доступны всем)

• !iq / !айкью / !icq – Случайный IQ 1-250 с историей
• !игра – Текущая игра стрима (или "Стрим не в эфире")
• !followage / !подписка / !отслеживание – Время отслеживания канала
• !чебыло – История категорий текущего стрима
• !7тв – Ссылки на расширение 7TV
• !пинг – Задержка ответа бота
• !э – Команда тестирования
• !тг – Ссылка на Telegram (из .env)
• !правила / !rules – Правила чата
• !подарок – Случайный подарок (для модераторов и стримера без ограничений) // в разработке
• !+подарок [название] – Добавить новый подарок (только модераторы/стример) // в разработке
• !-подарок – Сброс кэша подарков (только стример) // в разработке
• !команды – Список доступных команд

Новые интерактивные команды в версии 1.2.0 (доступны всем)

• !предложение [игра] – Предложить игру для голосования
• !голос [игра] – Проголосовать за игру (один голос за стрим)
• !итоги – Итоги голосования и статистика стрима
• !пословица [слово] – Случайная пословица с вашим словом // в разработке
• !рулетка – Игровой автомат (три эмодзи, выигрыш 10 очков)
• !баллы / !очки – Показать свои очки бота // в разработке

Разработка

Установка для разработки

---

git clone https://github.com/ваш-логин/twitch-bot.git cd twitch-bot npm install

Для автоматического перезапуска при изменениях используйте nodemon:

npm install -g nodemon npm run dev

Конфигурационные файлы

---

Все основные настройки вынесены в папку config/:

• cooldowns.js – кулдауны для команд (рулетка, дуэли)
• moderation.js – параметры автомодерации (окно спама, порог капса, список ботов)
• titles.js – пороги и названия званий
• shoutoutChannels.js – список каналов для автоматического /shoutout

База данных

---

Бот использует SQLite для хранения данных. Основные таблицы:

• user_iq – IQ пользователей
• violations – история нарушений (тип, причина, дата)
• spam_tracking – временное хранение сообщений для антиспама
• stream_sessions – сессии стримов
• stream_categories – история категорий стрима
• stream_games – предложенные игры для голосования
• votes – голоса пользователей
• bot_points – очки, победы в дуэлях, количество сообщений, звание (расширена в версии 1.3.0)
• proverbs – шаблоны пословиц
• jokes – анекдоты
• fortunes – предсказания
• bans – история банов с датами окончания
• daily_bonus – получение ежедневного бонуса
• daily_fortune – получение предсказания
• duels – активные дуэли
• reports – жалобы пользователей
• unban_requests – запросы на разбан

Расширение функционала

---

Чтобы добавить новую команду:

1. Добавьте алиас в src/commands/aliases.js
2. Создайте функцию-обработчик в соответствующем файле (interactive.js для пользовательских команд, moderation.js для модераторских)
3. Добавьте вызов в userHandlers или modHandlers в src/bot.js

Безопасность

Важные меры предосторожности

• Никогда не коммитьте файл .env и базу данных *.db – они уже в .gitignore
• Регулярно обновляйте токены (ACCESS_TOKEN)
• Используйте разные токены для разработки и продакшена
• При компрометации токена немедленно отзовите его в консоли разработчика (https://dev.twitch.tv/console/apps)

Содержимое .gitignore

Зависимости

node_modules/

Файлы окружения

config/.env config/.env.* .env

База данных

data/*.db *.db

Логи

.log npm-debug.log

Вклад в проект

Мы приветствуем вклад в развитие бота!

1. Форкните репозиторий
2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
3. Сделайте коммит изменений (git commit -m 'Add amazing feature')
4. Запушьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

Альтернативно можно поддержать проект на канале

Поддержка и обратная связь

Если у вас возникли проблемы:

1. Проверьте, что токены актуальны и имеют нужные scopes (особенно channel:moderate)
2. Убедитесь, что бот добавлен как модератор в канал (команда /mod имя_бота)
3. Проверьте логи в консоли на наличие ошибок
4. Попробуйте перезапустить бота
5. Если ничего не помогает – прокляните разработчика и напишите ему, пусть поможет

Руки разработчика --> Cluelesstech@yandex.ru <-- бить или целовать

Последнее обновление: 18.03.2026