Skip to content

README.ru.md

Latest commit

 

History

History
89 lines (64 loc) · 5.69 KB

README.ru.md

File metadata and controls

89 lines (64 loc) · 5.69 KB
Raw

Telegram Abridger Userbot

English · 中文 · Русский

Юзербот (MTProto, от имени аккаунта), который следит за входящими сообщениями, копит их по отправителю в скользящем окне и — когда отправитель заваливает окно — склеивает накопленные сообщения в одно беззвучное саммари и заглушает уведомления от него. Если ты сам ответил в этом чате, саммари не отправляется: разговор очевидно идёт.

Требования

  • Python 3.11+
  • uv
  • Учётные данные Telegram API (API_ID, API_HASH)

Получение API_ID и API_HASH

  1. Открыть https://my.telegram.org и войти по номеру телефона
  2. Перейти в API development tools
  3. Создать приложение (название и платформа — любые)
  4. Скопировать App api_id → API_ID и App api_hash → API_HASH

Конфигурация (переменные окружения или .env)

Переменная По умолчанию Описание
API_ID — Telegram API ID (обязательно)
API_HASH — Telegram API hash (обязательно)
COOLDOWN_INTERVAL 300 Окно наблюдения в секундах
MESSAGE_FREQUENCY_LIMIT 5 Максимум сообщений за окно до mute
MESSAGE_CONCAT_STRING , Разделитель при склейке сообщений
MUTE_TIMEOUT 3600 Длительность mute в секундах
SUMMARY_PREFIX (нет) Необязательный префикс перед саммари; %d заменяется числом сообщений (например, "Собрано %d сообщений:\n")
SESSION userbot Имя или путь сессии Telethon; авторизация хранится в $SESSION.session

Запуск

cp .env.example .env  # заполни API_ID и API_HASH
uv run bot.py

uv run сам разрешает и устанавливает зависимости из pyproject.toml/uv.lock в изолированное окружение — ручная настройка не нужна.

При первом запуске Telethon запросит номер телефона и код подтверждения, затем создаст файл *.session. Этот файл содержит секрет авторизации — храни его в тайне и никогда не коммить.

Запуск в контейнере

Образ собирает зависимости в стадии uv и поставляется как тонкий non-root рантайм. Сессия хранится на томе /data, поэтому авторизация переживает перезапуски.

# Сборка
docker build --tag telegram-abridger --file Containerfile .

# Первый запуск: интерактивная авторизация с сохранением сессии в именованный том
docker run --interactive --tty \
  --env-file .env \
  --volume abridger-session:/data \
  telegram-abridger

# Последующие запуски (авторизация уже выполнена)
docker run --detach --restart unless-stopped \
  --env-file .env \
  --volume abridger-session:/data \
  telegram-abridger

Образ задаёт SESSION=/data/userbot; не задавай SESSION в своём .env, чтобы сессия попадала на том.

Как это работает

Юзербот отслеживает входящие сообщения из не заглушённых и не архивных чатов (чаты с форумами/топиками исключаются). Для каждого отправителя ведётся скользящее окно COOLDOWN_INTERVAL секунд:

  • Входящие сообщения отмечаются прочитанными и добавляются в буфер по отправителю
  • Если отправитель превышает MESSAGE_FREQUENCY_LIMIT сообщений за окно, он заглушается на MUTE_TIMEOUT секунд через настройки уведомлений Telegram, а его буфер отправляется досрочно
  • Сообщения буфера склеиваются через MESSAGE_CONCAT_STRING и беззвучно отправляются в тот же чат; если задан SUMMARY_PREFIX, он добавляется в начало саммари (%d → число сообщений)
  • Буферы также периодически сбрасываются, когда окно отправителя затихает
  • Если ты отправил любое сообщение в этом же чате за COOLDOWN_INTERVAL, саммари подавляется — разговор уже активен

Разработка

uv sync          # установка runtime- и dev-зависимостей
uv run pytest    # запуск тестов
uv run ruff check . && uv run ruff format --check .
uv run mypy bot.py

Выходные файлы

  • $SESSION.session (по умолчанию userbot.session) — файл сессии Telethon (не коммитить)
  • Логи выводятся в stdout