Files

6.4 KiB
Raw Permalink Blame History

Боты в Matrix: архитектура

Обновлено 23.10.2026.

Принцип: одно входное окно

человек → @secretary → (понимает запрос) → профильный бот → ответ
                            ↓ если не понял
                     поиск по документации (RAG)
                            ↓ если и там нет
                     пожелание владельцу (@akadmin)

Секретарь (@secretary:matrix.buryans.ru) — единственный, кому пишут люди. Он не дублирует функции, а маршрутизирует.

Кто есть

Бот Задача Отвечает
@secretary единое окно, маршрутизация, пожелания всем из allowlist
@media музыка, фильмы, ТВ, колонки медиа-запросы
@book книги, библиотека книжные запросы
@photo фото, альбомы фото-запросы
@home дом, сценарии, свет бытовые команды
@infra бэкапы, сервисы, диски инфраструктура
@search поиск по всему поисковые запросы
@digest что нового за период дайджесты
@cam камеры видео

Маршруты секретаря

Слова Кому
музык, фильм, кино, сериал, тв, колонк, алис, включи MEDIA
книг, чита, библиотек, автор BOOK
фото, снимк, альбом, immich PHOTO
дом, свет, сценар, утро, ночь, ушли HOME
бэкап, сервис, диск, место, статус, логи, агент INFRA
что нового, дайджест, новинк DIGEST
найди, поиск, где лежит SEARCH

История: у каждого своя

/var/lib/hub-bots/secretary.db, таблица history(user, ts, role, text). Ключ — полный Matrix-ID пользователя. Чужие сообщения не попадают в чужой контекст: истории физически разделены.

Проверено: два разных человека пишут секретарю — записи лежат с разными user, бот не смешивает.

Пожелания

Если секретарь не нашёл ответа, он пишет в wishes(user, ts, text, status) и отправляет личное сообщение владельцу. Владелец разбирает список:

sqlite3 /var/lib/hub-bots/secretary.db \
  "select id, user, text, status from wishes where status='new'"

Чего НЕ делаем (и почему)

Не создаём нового бота на каждый запрос. Раньше это приводило к спаму и зоопарку аккаунтов. Все профильные боты — фиксированный набор из 9 аккаунтов, они уже существуют и не пересоздаются.

Не даём профильным ботам инициативу. Они только отвечают на маршрутизированный запрос, не пишут первыми.

Как это устроено в коде

Файл Роль
/opt/hub-bots/hub/secretary.py секретарь: маршруты, история, пожелания
/opt/hub-bots/hub/matrix.py базовый класс Bot, poll_loop
/opt/hub-bots/hub/main.py запуск флота, связывание секретаря с профильными
/etc/hub-bots/bots.env токены, ALLOWED_USERS

Секретарь получает ссылки на профильных ботов (peers) и вызывает их dispatch() напрямую — без пересылки сообщений между комнатами, поэтому в Matrix не появляется лишних сообщений.

Флаг any_room = True: обычные боты слушают только свою личку, секретарь — любую комнату, куда его пригласили (чтобы человек мог написать из своей личной комнаты).

Проверено вживую

Сценарий Результат
«включи музыку на кухне» маршрут MEDIA, ответ пришёл
«хочу учёт семейных расходов» пожелание записано, владельцу ушло сообщение
два пользователя истории раздельные

Распознавание действий (23.10)

Раньше «включи музыку» возвращало справку. Теперь секретарь различает действие и вопрос:

Фраза Что делает
включи музыку на кухне команда музыка у MEDIA (запуск)
включи телевизор в спальне команда тв у MEDIA
покажи что есть в медиатеке справка MEDIA (stats)
найди книгу дюна BOOK
когда последний бэкап INFRA

Проверено юнит-тестом без Matrix: маршрут и выбор команды корректны.

Команды секретаря

!помощь · !хочу <идея> · !история · !кто · !пожелания (только владелец)

Что дальше

  1. !пожелания показывает новые записи; нужны статусы (new → принято → сделано) и ответ «вам пришло пожелание» автору.
  2. Профильные боты всё ещё отвечают только владельцу в своей личке — после маршрута от секретаря это неважно, но стоит унифицировать.
  3. Словарь маршрутов расширять по мере реальных фраз.