123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# Боты в 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. Словарь маршрутов расширять по мере реальных фраз.
|