Ключевые концепции

Здесь простыми словами объяснено из чего состоит MXUserBot. Без кода, для понимания общей картины.

Команды

Что это? Это то что ты пишешь с точкой. Например:

.ping    → бот отвечает "Pong!"
.help    → показывает список команд
.mdl     → управляет модулями

Как работает? Бот смотрит на каждое сообщение. Если оно начинается с . — ищет соответствующую команду.

Watcher — "наблюдатель"

Что это? Команды которые реагируют на ЛЮБОЕ сообщение, а не только на те что начинаются с точки.

Пример: - Ты пишешь в чат: "спасибо!" - Бот автоматически ставит реакцию ❤️ - Или автоматически конвертирует валюту если видишь $100 в сообщении

Где используется? Авто-реакции, авто-конвертация, фильтрация спама — всё что должно работать на каждое сообщение.

FSM — диалоги шаг за шагом

Что это? Машина состояний. Позволяет боту вести диалог с пользователем по шагам.

Пример:

Ты:   .feedback
Бот:  "Как тебя зовут?"
Ты:   "Миша"
Бот:  "Приятно познакомиться, Миша! Сколько тебе лет?"
Ты:   "25"
Бот:  "Спасибо! Твой отзыв сохранён."

Почему это нужно? Без FSM пришлось бы писать всё одной командой:

.feedback Миша 25 "Мне всё нравится!"

С FSM — бот сам спрашивает по очереди.

Cron — задачи по расписанию

Что это? Что-то что выполняется автоматически через определённые интервалы времени.

Примеры: - Каждые 30 минут: проверить статус сервера - Каждый час: отправить статистику - Раз в день: бэкап базы

Форматы: - 30m — каждые 30 минут - 2h — каждые 2 часа - */5 * * * * — каждые 5 минут (cron-выражение)

Эмодзи-коллбеки — реакции как кнопки

Что это? В Matrix нет инлайн-кнопок как в Telegram. Но есть реакции (эмодзи). И их можно использовать как кнопки.

Пример:

Бот:  "Подтвердить действие?"
      (бот ставит реакции ✅ и ❌)

Ты:  ставишь реакцию ✅ на сообщение бота
Бот:  "✅ Ок, сделано!" и убирает реакции

Как это работает под капотом? Бот отслеживает кто поставил какую реакцию и вызывает соответствующую функцию.

Rate Limiter — защита от бана

Что это? Матрикс-серверы могут банить за слишком частые запросы (ошибка 429). Rate Limiter автоматически замедляет бота если сервер просит.

Как работает? - Всё нормально → запросы идут с минимальной задержкой - Получили 429 → автоматически увеличиваем задержку - Всё снова ок → постепенно ускоряемся обратно

Для тебя это значит: Ты можешь не волноваться что бот наспамит реакций и тебя забанит. Лимиттер всё сделает сам.

Безопасность — песочница для модулей

Что это? Community модули (не встроенные) работают в ограниченной среде. Они не могут навредить.

Что запрещено: - Читать/писать файлы там где не положено - Импортировать опасные модули (subprocess, socket, ctypes...) - Использовать eval(), exec() - Получать доступ к чувствительным данным бота

Как это работает? 1. AST-анализ кода перед загрузкой 2. Audit hook на все опасные операции во время выполнения 3. Замороженные core-модули — их нельзя изменить из community кода 4. ScopedDatabase — каждый модуль видит только свои данные в БД

Это значит: Ты можешь ставить модули из сомнительных репозиториев с гораздо меньшим риском. Но всё равно думай головой.

Event Handler — обработчик событий

Что это? Команды реагируют только на сообщения. Event Handler'ы реагируют на ЛЮБЫЕ события Matrix: - Кто-то вошёл в комнату - Кто-то вышел из комнаты - Изменилось название комнаты - Кого-то пригласили - и т.д.

Пример: Когда кто-то заходит в комнату — бот автоматически приветствует.

Коротко и ясно

Концепция	Что делает
Команда	Реагирует на `.команда`
Watcher	Реагирует на ЛЮБОЕ сообщение по шаблону
FSM	Диалог шаг за шагом
Cron	Автоматически по расписанию
Эмодзи-коллбеки	Реакции как кнопки
Rate Limiter	Защита от 429
Безопасность	Песочница для чужого кода
Event Handler	Любые события Matrix

Для разработчиков: Если ты хочешь писать модули — смотри раздел Разработка модулей. Там всё это уже с примерами кода и техническими деталями.