Files
buryan-infra/ops/bots/MATRIX-BOTS.md

123 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Боты в 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. Словарь маршрутов расширять по мере реальных фраз.