diff --git a/docs/BOTS-ROLES.md b/docs/BOTS-ROLES.md new file mode 100644 index 0000000..ef6f9f2 --- /dev/null +++ b/docs/BOTS-ROLES.md @@ -0,0 +1,49 @@ +# Зоны ответственности ботов и доступ + +Дата: 19.10.2026. + +## Кто за что отвечает + +| Бот | Зона | Источники | Ссылки | +|---|---|---|---| +| `@media` | фильмы, сериалы, музыка: что есть, что качается, что заказать | Jellyfin, Seerr, Sonarr, Radarr, Navidrome | media, ombi, sonarr | +| `@photo` | фотографии и альбомы | Immich | immich | +| `@book` | книги: что есть, что нового, поиск | Calibre | books, каталог | +| `@home` | устройства и датчики дома (Android, Google TV) | Home Assistant | home | +| `@infra` | службы, диски, бэкапы, проблемы, входящие | Prometheus, Kuma, ядро | status, backup | +| `@search` | поиск сразу по всем сервисам, карточки, лента | ядро hub-core | панель | +| `@digest` | сводки за сутки и неделю, карта платформы | ядро | панель | +| `@cam` | видеонаблюдение | Frigate | Frigate (LAN) | + +У каждого бота — **своя полная инструкция**: что умеет, как спросить +по-человечески, полезные ссылки и важные ограничения. Не общая, а именно +по направлению. + +## Как это работает + +1. Человек пишет боту в личку впервые. +2. Бот присылает свою инструкцию (один раз на человека, состояние в + `/var/lib/hub-bots/onboarded.json`). +3. Дальше можно писать обычными словами: «что нового», «найди дюна». +4. «Помощь» в любой момент повторяет инструкцию. + +## Доступ + +Открыт всем участникам (`ALLOWED_USERS` в `/etc/hub-bots/bots.env`): + +* @akadmin (владелец) +* @polina +* @elena +* @nikita +* @sergey +* @alextest + +Каждый получает тот же набор команд — разграничение по ролям будет +следующим шагом (сейчас все в одной роли «свой»). + +## Проверено + +* у всех восьми ботов инструкции различаются (610–1249 символов); +* первое обращение присылает инструкцию, повторное — нет; +* «помощь» отдаёт инструкцию направления; +* `@cam` рассказывает про камеры, `@media` — про медиатеку. diff --git a/ops/bots/hub/guides.py b/ops/bots/hub/guides.py new file mode 100644 index 0000000..a779f1b --- /dev/null +++ b/ops/bots/hub/guides.py @@ -0,0 +1,232 @@ +"""Инструкции ботов: у каждого своя зона ответственности. + +Это то, что бот присылает человеку при первом обращении — подробно +про своё направление, без общей воды. +""" + +GUIDES = { + "media": { + "title": "Медиа", + "zone": "фильмы, сериалы, музыка: что есть, что качается, что заказать", + "about": ( + "Я отвечаю за медиатеку: Jellyfin (что можно смотреть), Seerr " + "(заявки), Sonarr и Radarr (что качается), Navidrome (музыка)." + ), + "commands": [ + ("статистика", "сколько фильмов, сериалов, альбомов в медиатеке"), + ("что нового", "что появилось последним"), + ("найди <название>", "поиск по медиатеке, например «найди дюна»"), + ("сейчас", "кто что смотрит прямо сейчас"), + ("очередь", "что стоит в очереди загрузок"), + ("заявки", "последние заявки и их статус"), + ("место", "сколько свободно на дисках загрузок"), + ("не хватает", "сколько серий и фильмов ещё не найдено"), + ("куда класть", "пути, куда копировать файлы вручную"), + ], + "examples": [ + "что нового за неделю", + "найди все части дюны", + "сколько места осталось", + ], + "links": [ + ("Смотреть", "https://media.buryans.ru"), + ("Заказать фильм или сериал", "https://ombi.buryans.ru"), + ("Что качается", "https://sonarr.buryans.ru"), + ], + "rules": [ + "Заявку я только покажу — одобряет владелец.", + "Если фильма нет и заказать нельзя — скажу причину (нет источника, нет места).", + "Музыку я считаю, но не качаю: это отдельный процесс.", + ], + }, + "photo": { + "title": "Фото", + "zone": "фотографии и альбомы в Immich", + "about": ( + "Я отвечаю за фотографии: сколько снимков, какие альбомы, сколько " + "занимает хранилище. Источник — Immich." + ), + "commands": [ + ("статистика", "сколько снимков, альбомов и людей"), + ("сколько места", "размер базы и хранилища"), + ("альбомы", "список альбомов"), + ], + "examples": ["сколько у нас фотографий", "какие есть альбомы"], + "links": [ + ("Открыть фото", "https://immich.buryans.ru"), + ("Загрузить с телефона", "приложение Immich, автозагрузка"), + ], + "rules": [ + "Я не удаляю и не меняю снимки — только показываю.", + "Если снимков нет — напомню, что нужно приложение на телефоне.", + ], + }, + "book": { + "title": "Книги", + "zone": "библиотека Calibre: что есть, что нового, поиск", + "about": ( + "Я отвечаю за книги: сколько их, что появилось последним, найти " + "по названию или автору. Источник — библиотека Calibre." + ), + "commands": [ + ("статистика", "сколько книг в библиотеке"), + ("новинки", "последние поступления"), + ("найди <название>", "поиск по названию, например «найди стругацкие»"), + ], + "examples": ["что нового в библиотеке", "найди пелевин"], + "links": [ + ("Читать", "https://books.buryans.ru"), + ("Каталог", "https://books.buryans.ru/catalog/"), + ], + "rules": [ + "Я не загружаю книги — это делает человек через сайт.", + "Формат и обложки не правлю.", + ], + }, + "home": { + "title": "Дом", + "zone": "устройства и датчики Home Assistant (Android-телефоны, Google TV)", + "about": ( + "Я отвечаю за умный дом: сколько устройств, какие типы, что " + "происходит. Источник — Home Assistant." + ), + "commands": [ + ("статистика", "сколько устройств и датчиков, по типам"), + ("состояние", "краткое состояние дома"), + ], + "examples": ["сколько датчиков дома", "что с домом сейчас"], + "links": [ + ("Панель дома", "https://home.buryans.ru"), + ], + "rules": [ + "Я показываю состояние, но не управляю устройствами — этим " + "занимается только владелец в приложении.", + "Телефоны на Android и телевизор на Google TV — это тоже " + "устройства дома, я их вижу как сущности.", + ], + }, + "infra": { + "title": "Инфраструктура", + "zone": "службы, диски, резервные копии, проблемы", + "about": ( + "Я отвечаю за то, что вся платформа работает: службы, место на " + "дисках, резервные копии, открытые проблемы и действия сверки." + ), + "commands": [ + ("статус", "какие службы живы, какие нет"), + ("тревоги", "активные тревоги"), + ("место", "свободное место на узлах"), + ("бэкапы", "последние резервные копии"), + ("контент", "что лежит в библиотеках"), + ("пробелы", "чего не хватает, чтобы всё заработало"), + ("службы", "полный список сервисов и адресов"), + ("входящие", "пожелания, которые собрали боты"), + ], + "examples": ["что сломалось", "сколько места", "что у нас не настроено"], + "links": [ + ("Мониторинг", "https://status.buryans.ru"), + ("Резервные копии", "https://backup.buryans.ru"), + ], + "rules": [ + "Останавливать и удалять что-либо я не буду без владельца.", + "Если служба не отвечает, скажу, что именно и с какого времени.", + "По ночам сверка сама поднимает остановленные контейнеры.", + ], + }, + "search": { + "title": "Поиск", + "zone": "поиск по всем сервисам одновременно", + "about": ( + "Я ищу сразу везде: в медиатеке, книгах, документах, закладках. " + "Показываю карточку объекта и историю." + ), + "commands": [ + ("найди <текст>", "поиск по всем сервисам"), + ("карточка <номер>", "подробности объекта и его история"), + ("лента", "последние события системы"), + ("связи <текст>", "где встречается одно и то же название"), + ], + "examples": ["найди дюна", "карточка 1", "что нового в системе"], + "links": [ + ("Единая панель", "http://192.168.1.10:9120/"), + ], + "rules": [ + "Если объекта нет ни в одном сервисе — так и скажу.", + "Номер карточки из поиска нужен для подробностей.", + ], + }, + "digest": { + "title": "Дайджест", + "zone": "сводки: что произошло за сутки и за неделю", + "about": ( + "Я собираю сводку: сколько событий, что скачалось, какие заявки, " + "что сломалось, состояние служб и индекса." + ), + "commands": [ + ("сводка", "итоги за сутки"), + ("карта", "какие сервисы есть и за что отвечают"), + ], + "examples": ["что было за сутки", "покажи карту платформы"], + "links": [ + ("Единая панель", "http://192.168.1.10:9120/"), + ], + "rules": [ + "Сводка приходит сама в 09:00, недельная — по понедельникам 09:30.", + "Я не меняю данные, только рассказываю.", + ], + }, + "cam": { + "title": "Камеры", + "zone": "видеонаблюдение (Frigate)", + "about": ( + "Я отвечаю за камеры: сколько их, что видят, какие события " + "детекции. Сейчас Frigate развёрнут, но камер ещё нет." + ), + "commands": [ + ("статус", "состояние сервера наблюдения и камер"), + ], + "examples": ["камеры работают?", "что видно сейчас"], + "links": [ + ("Frigate (внутренний адрес)", "http://192.168.1.126:5000"), + ], + "rules": [ + "Пока камер нет, я честно об этом говорю.", + "Записи и детекция включаются после добавления RTSP-адресов.", + ], + }, +} + + +def render(bot_name): + """Полная инструкция бота в человеческом виде.""" + g = GUIDES.get(bot_name) + if not g: + return "Инструкция для этого бота пока не написана." + + lines = [f"**{g['title']}** — моя зона ответственности", "", g["zone"], "", g["about"], ""] + + lines.append("**Что я умею**") + for name, desc in g["commands"]: + lines.append(f"• `{name}` — {desc}") + + lines.append("") + lines.append("**Как спросить по-человечески**") + for ex in g["examples"]: + lines.append(f"• «{ex}»") + + if g.get("links"): + lines.append("") + lines.append("**Полезные ссылки**") + for label, url in g["links"]: + lines.append(f"• {label}: {url}") + + if g.get("rules"): + lines.append("") + lines.append("**Важно**") + for r in g["rules"]: + lines.append(f"• {r}") + + lines.append("") + lines.append("Пишите как в обычном чате — команды и восклицательный знак " + "не нужны. Полная инструкция: «помощь».") + return "\n".join(lines) diff --git a/ops/bots/hub/matrix.py b/ops/bots/hub/matrix.py index 19d121c..8ba0f3c 100644 --- a/ops/bots/hub/matrix.py +++ b/ops/bots/hub/matrix.py @@ -208,13 +208,44 @@ class Bot: # не команда — это просьба или вопрос к владельцу return None, "", text + + def _onboard(self, sender): + """Первый раз от этого человека — прислать инструкцию по направлению.""" + try: + import json, os + path = "/var/lib/hub-bots/onboarded.json" + os.makedirs(os.path.dirname(path), exist_ok=True) + try: + data = json.load(open(path, encoding="utf-8")) + except OSError: + data = {} + key = f"{self.name}:{sender}" + if data.get(key): + return None + data[key] = True + json.dump(data, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=1) + from . import guides + return guides.render(self.name) + except Exception: + return None + def dispatch(self, text, in_dm=False): cmd, arg, raw = self._parse(text, in_dm) if cmd is None: if not in_dm: return None + routed = self._llm_route(raw) + if routed: + return routed return self.handle_freeform(raw) if cmd in ("help", "помощь", "?", "start"): + try: + from . import guides + guide = guides.render(self.name) + if guide: + return guide + except Exception: + pass return self.help_text() if cmd not in self.commands: близко = ", ".join(f"`!{c}`" for c in sorted(self.commands)[:6]) @@ -224,6 +255,46 @@ class Bot: except Exception as e: return f"Ошибка при `{cmd}`: {str(e)[:200]}" + + def _llm_route(self, text): + """Свободная фраза: спрашиваем модель, что вызвать.""" + try: + from . import llm + except Exception: + return None + if not llm.enabled(): + return None + res = llm.route(self, text) + if not res: + return None + kind, *rest = res + if kind == "tool": + name, arg = rest[0], rest[1] + try: + return self.commands[name][1](arg) or "Готово." + except Exception as e: + return f"Ошибка при вызове {name}: {str(e)[:150]}" + if kind == "answer": + answer = rest[0] + if not answer: + return None + self._remember(text, answer) + return answer + return None + + def _remember(self, question, answer): + """Пишем диалог в журнал — пригодится для разбора.""" + try: + import json, os, datetime + path = "/var/lib/hub-bots/dialog.jsonl" + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "a", encoding="utf-8") as f: + f.write(json.dumps({"at": datetime.datetime.now().isoformat(timespec="seconds"), + "bot": self.name, "q": question[:500], + "a": answer[:500]}, ensure_ascii=False) + "\n") + except Exception: + pass + def handle_freeform(self, text): """Свободный текст: это просьба. Передаём владельцу и агенту.""" from . import inbox @@ -311,6 +382,9 @@ def poll_loop(bot, stop_event, on_ready=None, allowed=None): "Как только откроют общий доступ — напишу.") continue bot.last_sender = sender + intro = bot._onboard(sender) + if intro: + bot.mx.send_chunked(rid, intro) reply = bot.dispatch(body, in_dm=True) if reply: bot.mx.set_typing(rid, False)