6.4 KiB
Боты в 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: маршрут и выбор команды корректны.
Команды секретаря
!помощь · !хочу <идея> · !история · !кто · !пожелания (только владелец)
Что дальше
!пожеланияпоказывает новые записи; нужны статусы (new → принято → сделано) и ответ «вам пришло пожелание» автору.- Профильные боты всё ещё отвечают только владельцу в своей личке — после маршрута от секретаря это неважно, но стоит унифицировать.
- Словарь маршрутов расширять по мере реальных фраз.