Skip to content
BranchesTags

Repository files navigation

🤖 Telegram Bot for Google Gemini API (Stand & Avatar Engine)

Асинхронный полнофункциональный Telegram-бот на базе Python 3.12+, aiogram 3.15+ (Telegram Bot API 8.0+) и официального Google GenAI SDK (google-genai) с поддержкой актуальных моделей Gemini (3.5 Flash Lite, 3.1 Flash Lite, 3.7 Flash, 3.5 Flash, 2.5 Flash), продвинутой мультимодальности (фото, PDF, документы, голосовые сообщения), генерации речи (TTS), персистентного хранилища SQLite в WAL-режиме, очередей с приоритетами и защиты от спама.

🌟 Два режима работы

Бот спроектирован с разделением на два независимых режима работы с изолированной памятью:

                  ┌──────────────────────────────────────────────┐
                  │              Входящее сообщение              │
                  └──────────────────────┬───────────────────────┘
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 │                                               │
                 ▼                                               ▼
   🥊 Stand-режим (Основной)                       🎭 Режим Аватара (Суфлёр)
   (ИИ-ассистент за спиной)                       (Ghostwriter от 1-го лица)
  ┌───────────────────────────────┐              ┌───────────────────────────────┐
  │ • Роль: ИИ-помощник           │              │ • Роль: Аватар пользователя   │
  │ • Контекст: диалог в чате     │              │ • Контекст: черновик/реплай   │
  │ • Формат: ответ с цитатой     │              │ • Формат: чистое сообщение    │
  │ • Лицо: от лица ИИ            │              │ • Лицо: строго от 1-го лица   │
  │ • Промпт: /prompt / /prompts  │              │ • Промпт: /avatar / /avatars  │
  │ • Память: mode='main'         │              │ • Память: mode='quick'        │
  └───────────────────────────────┘              └───────────────────────────────┘

🥊 1. Stand-режим (Основной режим)

Аналогия со Стендами из аниме/манги JoJo’s Bizarre Adventure:
Стенд — это персонифицированная духовная сила, стоящая за спиной владельца. В этом режиме Gemini выступает вашим верным ИИ-стендом: советником, аналитиком и ассистентом.

  • Как работает: Вы задаёте вопрос боту напрямую текстом, голосом (/voice) или прикрепляете файлы/фото, либо выбираете карточку 🥊 Stand при инлайн-вводе @bot_username.
  • Поведение: Отвечает как экспертный ИИ-помощник, помнит предыдущие реплики беседы, форматирует код, анализирует медиа и цитирует ваш исходный запрос.
  • Настройка личности: Персональный системный промпт стенда настраивается командой /prompt или каталогом /prompts.

🎭 2. Режим Аватара (/avatar / инлайн @bot_username)

Текстовый суфлёр и ghostwriter пользователя:
В этом режиме бот не общается с вами как ассистент, а пишет готовое сообщение за вас от первого лица («я», «мне», «мы»), идеально встраиваясь в контекст переписки.

  • Как работает: Наберите в любом чате @bot_username <ваш черновик> и выберите 🎭 Отправить Avatar, либо отправьте команду /avatar.
  • Поведение:
    • ❌ Никаких вводных слов и вежливостей («Вот вариант:», «Вы можете написать:», «Конечно!»).
    • ❌ Никаких подтверждений выполнения команд («Оки-доки!», «Слушаюсь!»).
    • 🎯 Строго чистый, готовый к отправке текст от вашего имени в заданном стиле.
  • Изолированная память: Имеет собственную независимую историю (mode='quick'), не смешивающуюся с ответами чат-бота.
  • Настройка Личностей: Каталог стилей (Бро, Бизнес, Сарказм, Краткий, Флирт и свои) доступен через /avatars и /avatar edit.

✨ Ключевые возможности

🤖 Модели и генерация

  • Поддержка актуального семейства Gemini:
    • gemini-3.5-flash-lite (быстрая и экономичная модель по умолчанию)
    • gemini-3.1-flash-lite
    • gemini-3.7-flash (флагманская гибридная reasoning-модель)
    • gemini-3.5-flash
    • gemini-2.5-flash
  • Выбор модели в 1 клик через меню /model или главное меню /menu.

🎙 Синтез речи (TTS) и голосовой интерфейс

  • Синтез речи On-Demand: При вызове /voice или включённом voice_mode: ON бот автоматически генерирует аудио через Gemini TTS.
  • Выбор TTS-модели: gemini-3.1-flash-tts-preview, gemini-2.5-flash-preview-tts и др.
  • Выбор голоса: Aoede, Kore, Puck, Fenrir, Charon.
  • Прямая озвучка текста: Команда /tts <текст> для мгновенной генерации голосового сообщения.

🖼 Мультимодальность и Telegram Replies 2.0 (Bot API 8+)

  • Умное чтение цитат и контекста:
    • message.quote.text: точное извлечение выделенных цитат (Telegram 10.2+).
    • message.reply_to_message: полное считывание ответов на сообщения, подписи, фото, документы и голосовые.
    • message.external_reply: поддержка цитат из других каналов и топиков.
  • Анализ изображений: Отправка фото или ссылок на картинки с вопросом.
  • Анализ документов: Поддержка PDF, текстовых файлов и исходного кода.
  • Голосовые сообщения: Распознавание входящих голосовых и аудиозаметок.

⚡️ Инлайн-режим (Inline Mode)

  • Обращение к боту из любого чата:
    • При вводе @bot_username ваш вопрос Telegram мгновенно предлагает 2 варианта на выбор:
      1. 🥊 Отправить Stand — ответ ИИ-ассистента с цитированием вашего вопроса.
      2. 🎭 Отправить Avatar — чистый ответ от вашего лица без цитат и вводных слов.
    • @bot_username /tts текст — мгновенная отправка голосового сообщения из кэша.

💾 Персистентная архитектура и хранилище

  • SQLite + aiosqlite в WAL-режиме:
    • Автоматические миграции схемы БД без потери данных.
    • Высокая параллельная производительность без блокировок чтения/записи.
    • Сохранение истории диалогов, токенов и пользовательских настроек в ./data.
  • Управление историей: Выборочная очистка истории по конкретным чатам или во всех чатах сразу (/clear).

🛡 Безопасность и контроль ресурсов

  • Очередь с приоритетами: Суперадмины и администраторы обслуживаются вне очереди.
  • Рейт-лимитер: Скользящее окно лимитов запросов (в минуту и в сутки) с командой /limits.
  • Управление доступом: Встроенная админ-панель (/admin) с белым списком (ALLOWED_USER_IDS), добавлением/удалением пользователей в реальном времени.

🛠 Полный список команд

Команда Описание
/menu 📱 Главное интерактивное меню (все настройки, выбор моделей и параметров)
/start 🚀 Запустить бота и открыть главное меню
/help ℹ️ Справка и краткое руководство по всем возможностям и режимам
/avatar [имя/текст] 🎭 Режим Аватара: выбрать, создать или изменить личность: /avatar edit Имя = Текст
/avatars 🎭 Личности Аватара: каталог стилей (Бро, Бизнес, Сарказм, Краткий, Флирт и свои)
/prompt [текст] 🥊 Настроить/изменить Stand-промпт: /prompt edit Имя = Текст
/prompts 🥊 Промпты Stand: каталог ролей (Кодер, Сисадмин, Переводчик, Аналитик и свои)
/voice [вопрос] 🎙 Stand-режим: принудительный ответ голосовым сообщением
/text [вопрос] 💬 Stand-режим: принудительный ответ текстовым сообщением
/model 🤖 Выбор основной модели Gemini
/settings ⚙️ Параметры чата (rich-режим, голосовые ответы, очистка истории)
/tts <текст> 🎧 Озвучить произвольный текст выбранным голосом
/limits 📊 Проверить остаток лимитов запросов и статистику токенов
/clear 🗑 Очистить историю диалога (выбор конкретного чата или всех сразу)
/business 💼 Secretary Mode: Telegram Business бот, управление фактами, авто-ответами и черновиками
/admin 👑 Панель администратора (белый список, управление доступом)

🚀 Быстрый старт

1. Клонирование репозитория

git clone https://github.com/vlv-code/tg-bot-gemini-api.git
cd tg-bot-gemini-api
cp .env.example .env

2. Настройка конфигурации (.env)

Откройте файл .env и укажите ваши ключи:

# Токен бота от @BotFather
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ

# Ключ Google Gemini API от Google AI Studio (https://aistudio.google.com/)
GEMINI_API_KEY=AIzaSy...

# ID суперадминистратора (узнать у @userinfobot)
ADMIN_IDS=123456789

# Разрешённые пользователи (оставьте пустым для свободного доступа)
ALLOWED_USER_IDS=123456789

3. Запуск через Docker Compose (рекомендуется)

docker compose up -d --build

Просмотр логов в реальном времени:

docker compose logs -f

Перезапуск:

docker compose restart

4. Локальный запуск (без Docker)

Требуется Python 3.12+.

python -m venv .venv

# Linux / macOS:
source .venv/bin/activate

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

pip install -r requirements.txt
python bot.py

⚙️ Настройка в Telegram (@BotFather)

Для полноценной работы всех возможностей бота рекомендуется включить следующие опции в @BotFather:

  1. /setcommands — меню команд регистрируется автоматически при старте бота.
  2. /setinline — включите инлайн-режим, чтобы бот работал через @bot_username во всех чатах.
  3. /setinlinefeedback — включите Enabled (100%), чтобы бот получал события выбора инлайн-результатов.
  4. /setprivacy — для работы в группах:
    • Disabled — бот видит все сообщения в группах и может отвечать на реплаи.
    • Enabled — бот видит только явные вызовы через / и реплаи на свои сообщения (или требуется дать боту права администратора).

📂 Структура проекта

tg-bot-gemini-api/
├── audio.py            # Обработка и конвертация аудио в формат Telegram Voice (OGG/Opus)
├── bot.py              # Точка входа, регистрация команд и запуск aiogram polling
├── config.py           # Валидация и загрузка настроек из .env
├── formatting.py       # Rich Markdown парсер и безопасное разбиение по UTF-16 code units
├── gemini_client.py    # Асинхронный клиент Google GenAI SDK (текст, vision, audio, TTS, таймауты)
├── handlers/           # Модульная маршрутизация событий
│   ├── __init__.py     # Сборка роутеров
│   ├── common.py       # Общие состояния, кэш инлайн-сессий и рендеринг
│   ├── menu.py         # Главное меню, модели, TTS и настройки
│   ├── prompts.py      # Управление пресетами Stand и личностями Аватара
│   ├── admin.py        # Панель администратора и управление белым списком
│   ├── business.py     # Secretary Mode: Telegram Business боты, черновики и авто-ответы
│   ├── chat.py         # Обработка текстовых, голосовых и мультимодальных сообщений
│   └── inline.py       # Инлайн-режим карточек, интерактивная панель действий
├── keyboards.py        # Интерактивные inline-клавиатуры для навигации
├── locks.py            # Асинхронные блокировки и очередь запросов с приоритетами
├── middlewares.py      # Middleware контроля доступа и белого списка
├── rate_limiter.py     # Рейт-лимитер со скользящим окном (RPM и RPD)
├── storage.py          # Асинхронное хранилище SQLite (aiosqlite WAL) с разделением mode
├── scripts/
│   └── backup_db.py    # Горячий онлайн-бэкап SQLite (VACUUM INTO) с ротацией
├── tests/              # Набор модульных тестов (хэндлеры, безопасность, блокировки, БД)
├── Dockerfile          # Оптимизированный multi-stage Dockerfile
├── docker-compose.yml  # Манифест Docker Compose с пробросом volumes
└── requirements.txt    # Зависимости проекта

💾 Резервное копирование базы данных

Для создания безопасного онлайн-бэкапа SQLite базы данных без остановки бота используется скрипт scripts/backup_db.py (выполняет команду VACUUM INTO, гарантирующую консистентность даже при активных транзакциях в WAL-режиме):

# Ручной запуск бэкапа (сохраняет в data/backups/ с ротацией 30 дней)
python scripts/backup_db.py

# С кастомными параметрами:
python scripts/backup_db.py --db data/bot.db --backup-dir data/backups --keep-days 14

Автоматизация через Cron (Linux):

Добавьте задачу в crontab -e для ежедневного создания бэкапа в 03:00 ночи:

0 3 * * * cd /path/to/tg-bot-gemini-api && .venv/bin/python scripts/backup_db.py >> /var/log/bot_backup.log 2>&1

🧪 Запуск тестов

Проект покрыт автоматическими тестами:

# Запуск через pytest:
pytest -v

# Либо через стандартный модуль unittest:
python -m unittest discover -s tests -p "test_*.py" -v

📄 Лицензия

Проект распространяется под лицензией MIT.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages