Files
buryan-infra/docs/HUB-BOTS.md
T
buryan-agent 7b88923550 Личные боты: переписка один на один вместо общей комнаты
Каждый бот теперь личный собеседник: при старте создаёт комнату is_direct
с владельцем и приглашает его. В личке не нужны команды — понимает обычные
слова («статистика», «что нового», «найди дюна»).

Общие комнаты остались, но там бот отвечает только на !команды, чтобы не
встревать в разговор. Уведомления и сводки — туда же.

Боты принимают приглашения: если человек сам начнёт переписку, она станет
личной (признак is_direct в событии приглашения).
2026-10-19 16:53:44 +03:00

195 lines
11 KiB
Markdown
Raw 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.
# Buryan Hub: флот ботов и контентная платформа
Что сделано 19.10.2026: боты в Matrix, пространство с комнатами, единая карта
сервисов, ежедневная сводка, ключи в одном месте.
---
## 1. Важное открытие: библиотеки пусты
Прежде чем строить «контентную архитектуру», проверил, что в сервисах есть:
| Сервис | Содержимое |
|---|---|
| Jellyfin (медиатека) | **0** фильмов, 0 сериалов, 0 серий, 0 альбомов |
| Plex | папка `/opt/plex/media` пуста |
| Navidrome (музыка) | **0** треков, 0 альбомов |
| Immich (фото) | **0** снимков, 0 альбомов |
| Calibre (книги) | **0** книг |
| Home Assistant | **8** сущностей |
| Frigate | **не развёрнут** |
Диск один (NVMe 476 ГБ), внешних хранилищ нет. То есть платформа построена,
но контентом не наполнена — интеграция пока показывает честные нули
и подсказки, как наполнить.
**Что нужно, чтобы ожило:**
1. **Медиа** — положить файлы в `/media/movies`, `/media/series`, `/media/music`
(CT 103) и запустить сканирование. Для автоматических загрузок —
настроить в Sonarr/Radarr клиент загрузки (qBittorrent/ Transmission)
и индексаторы в Prowlarr.
2. **Фото** — поставить приложение Immich на телефоны, включить автозагрузку.
3. **Книги** — загрузить через `books.buryans.ru`.
4. **Дом** — добавить устройства в Home Assistant.
5. **Frigate** — нужны RTSP-адреса камер; без них сервер наблюдения не имеет смысла.
---
## 1. Личные боты — основной способ общения
Каждый бот — **личный собеседник**. С ним одна переписка, только вы и он:
| Бот | Что спрашивать |
|---|---|
| `@media` | «статистика», «что нового», «найди дюна», «очередь», «заявки» |
| `@photo` | «статистика», «сколько места» |
| `@book` | «статистика», «новинки», «найди стругацкие» |
| `@home` | «статистика», «состояние» |
| `@infra` | «статус», «тревоги», «место», «бэкапы», «контент», «пробелы», «службы» |
| `@search` | «найди <текст>», «индекс», «связи дюна» |
| `@digest` | «сводка», «карта» |
| `@cam` | «статус» |
В личной переписке **не нужны команды и восклицательные знаки** — пишите
обычными словами. Бот понимает и `!stats`, и «статистика», и «найди дюна».
Комнаты (Медиа, Фото, Книги…) остались как **общие** — там бот отвечает
только на команды с `!`, чтобы не встревать в разговор. Туда же приходят
уведомления и сводки.
Почему так: личка — это «мой помощник», комната — «общая доска».
Когда появится ролевая модель, роль можно вешать на тип комнаты:
личка — полный доступ, общая — только чтение.
Технически: при старте каждый бот создаёт личную комнату с владельцем
(`is_direct`) и приглашает его; карта комнат хранится в
`/etc/hub-bots/dm.env`. Если человек сам начнёт переписку с ботом,
бот примет приглашение и будет отвечать в ней.
## 2. Пространство и общие комнаты
Пространство **Buryan Hub** в Matrix, внутри 9 комнат:
| Комната | Бот | Что там |
|---|---|---|
| Медиа | `@media` | фильмы, сериалы, очередь загрузок, заявки |
| Фото | `@photo` | Immich: снимки, альбомы |
| Книги | `@book` | библиотека, поиск, новинки |
| Дом | `@home` | Home Assistant: сущности, состояние |
| Инфраструктура | `@infra` | службы, тревоги, диски, резервные копии, состав библиотек |
| Поиск | `@search` | поиск по медиа, книгам и документам сразу |
| Дайджесты | `@digest` | ежедневная сводка в 09:00 и карта платформы |
| Камеры | `@cam` | Frigate (когда появится) |
Люди приглашены: `@akadmin`, `@polina`, `@elena`, `@nikita`, `@sergey`, `@alextest`.
## 3. Команды ботов
У каждого бота `!help` показывает свои команды. Коротко:
| Бот | Команды |
|---|---|
| media | `!stats` `!new` `!find <текст>` `!now` `!queue` `!requests` `!disk` `!wanted` `!paths` |
| photo | `!stats` `!space` |
| book | `!stats` `!new` `!find <текст>` |
| home | `!stats` `!status` |
| infra | `!status` `!alerts` `!disk` `!backups` `!content` `!services` `!gaps` |
| search | `!s <текст>` `!index` `!reindex` `!link <текст>` |
| digest | `!digest` `!map` |
| cam | `!status` |
Отдельно стоит знать:
* **`!gaps`** — честный список того, что мешает системе работать целиком:
пустые библиотеки, не настроенный загрузчик, отсутствие Frigate. Это ответ
на вопрос «что у нас есть и чего не хватает» без прикрас.
* **`!index`** — что попало в общий индекс и когда он обновлялся.
* **`!link`** — кросс-связи: где одно и то же название встречается в разных
видах контента (фильм, книга, закладка).
## 3.1. Общий индекс контента
Все сервисы сведены в одну базу `/var/lib/hub-bots/index.db`:
| Источник | Что забирает |
|---|---|
| Jellyfin | фильмы, сериалы, треки |
| Sonarr / Radarr | сериалы и фильмы (в том числе ещё не скачанные) |
| Navidrome | альбомы и исполнители |
| Calibre | книги и авторов |
| Paperless | документы |
| Linkding | закладки |
Особенности:
* поиск идёт по нормализованному полю — SQLite не умеет `lower()` для
кириллицы, поэтому регистр приводится в Python при сборке;
* выгрузки из баз делают маленькие помощники `hub/helpers/*.py`, они лежат
в контейнерах (`/opt/hub-helpers`);
* пересборка — каждые 3 часа (`/etc/cron.d/hub-index`) и командой `!reindex`;
при недоступности источника в комнату дайджеста уходит предупреждение.
Проверено на тестовых записях: поиск «дюна» находит фильм, книгу и закладку
одной командой, `!link` группирует их по видам.
## 4. Как это устроено
```
/opt/hub-bots/ ← код на узле Proxmox
hub/
matrix.py клиент Matrix: отправка, длинный опрос
sources.py клиенты сервисов (Jellyfin, Sonarr, Radarr, Seerr, Prometheus)
local.py чтение баз через pct (Navidrome, Calibre, Immich, HA)
catalog.py карта сервисов и состав библиотек
bots.py все боты и их команды
main.py запуск флота
digest.py ежедневная сводка (cron 09:00)
/etc/hub-bots/bots.env настройки и ключи (600)
/etc/systemd/system/hub-bots.service
```
Почему на узле, а не в контейнере: боты читают базы сервисов через `pct exec`
(Navidrome, Calibre, Immich, Home Assistant) — из контейнера так нельзя.
Служба: `systemctl status hub-bots`, лог `/var/log/hub-bots.log`.
## 5. Где ключи
* `/etc/hub-bots/bots.env` — рабочие ключи (600).
* `/root/hub-bots/ALL-SECRETS.txt` — **все** ключи одним файлом (600).
* `ops/secrets-enc/hub-bots-secrets.age` — то же, зашифровано age (в репозитории).
Расшифровать: `SOPS_AGE_KEY_FILE=/root/.buryan-age-key sops -d ...`.
## 6. Уведомления из сервисов
Боты принимают вебхуки и публикуют их в комнате «Медиа»:
* приёмник: `http://192.168.1.10:9110/seerr` (внутри службы ботов);
* в Seerr настроено: заявка создана, одобрена, отклонена, стала доступна,
одобрена автоматически (маска событий 206);
* проверено: уведомление «Уже доступно — Дюна: часть вторая (2024),
просил Роман» пришло в комнату.
Чтобы добавить ещё сервис — шлите POST на тот же адрес с полем
`notification_type`, либо на `/other` (придёт как есть).
## 7. Seerr без пароля: Quick Connect
В Seerr включён быстрый вход: `POST /api/v1/auth/jellyfin/quickconnect/initiate`
возвращает код, человек вводит его в Jellyfin (где уже вошёл через Authentik)
и попадает в Seerr без пароля.
Важно: при первом входе Seerr **очистил адрес Jellyfin** в настройках —
из-за этого быстрый вход падал с «Invalid URL». Адрес прописан заново
(`192.168.1.103:8096`), после чего код выдаётся.
## 8. Что дальше (по приоритету)
1. **Наполнить библиотеки** — без контента боты показывают нули.
2. **Уведомления** Seerr/Sonarr → комната «Медиа» (вебхук в n8n или напрямую).
3. **Frigate** — как только будут камеры.
4. **Кросс-связи**: книга → экранизация (Calibre ↔ Jellyfin), фото → место
(Immich ↔ Home Assistant), музыка → исполнитель в медиатеке.
5. **Утренняя сводка уже включена** — посмотрите комнату «Дайджесты».