# Боты в 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)` и отправляет личное сообщение владельцу. Владелец разбирает список: ```bash 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. Словарь маршрутов расширять по мере реальных фраз.