vk_chat_bot/AGENTS.md

Чат-бот для VK/Telegram с функциями ИИ

Описание проекта

Это движок чат-бота для мессенджеров VK и Telegram, написанный на Python 3. Движок поддерживает некоторые полезные функции для групповых чатов (правила, приветствие новичков, статистика сообщений, вычисление молчунов и др.). В движок интегрирован модуль ИИ: пользователи могут общаться с ботом в личных сообщениях, а также в групповых чатах, если упомянут его. Модуль ИИ использует API OpenRouter для генерации ответов, а также API fal.ai и Replicate для генерации изображений.

Архитектура проекта

vk_chat_bot/
├── database.py                # Базовый класс работы с базой данных
├── messages.py                # Константы сообщений
├── utils.py                   # Общие утилиты
├── tg.json                    # Тестовая конфигурация для Telegram
├── vk.json                    # Тестовая конфигурация для VK
│
├── ai/                        # Модуль ИИ
│   ├── agent.py               # Основной агент
│   ├── tool.py                # Базовый класс инструментов
│   ├── utils.py               # Утилиты модуля ИИ
│   │
│   ├── prompts/               # Системные запросы для модуля ИИ
│   │   ├── group_chat.md      # Промпт для групповых чатов
│   │   └── private_chat.md    # Промпт для личных чатов
│   │
│   └── tools/                 # Инструменты
│       └── <toolset1>/        # Набор инструментов 1
│           ├── __init__.py    # Реализация набора инструментов 1
│           ├── <function1>.py # Реализация функции 1
│           ├── <function2>.py # Реализация функции 2
│           └── prompt.py      # Системный запрос с описанием набора инструментов
│
├── tg/                        # Telegram интеграция (aiogram)
│   ├── __main__.py            # Точка входа для Telegram
│   ├── tasks.py               # Фоновые задачи
│   ├── handlers/              # Обработчики сообщений и событий
│   └── tg_database.py         # Класс БД для Telegram (содержит только схему)
│
└── vk/                        # VK интеграция (vkbottle)
    ├── __main__.py            # Точка входа для VK
    ├── tasks.py               # Фоновые задачи
    ├── handlers/              # Обработчики сообщений и событий
    └── vk_database.py         # Класс БД для VK (содержит только схему)

Основные технологии

• Асинхронность: asyncio
• ИИ: OpenRouter (Grok 4.1 Fast), fal.ai (Seedream 4.5) для обычных изображений, Replicate (Nova Anime XL) для генерации изображений в стиле аниме.
• Telegram: aiogram 3.x
• VK: vkbottle
• СУБД: MariaDB (через pyodbc)
• Обработка изображений: PIL/Pillow

Запуск

Telegram бот

python -m tg -c tg.json

VK бот

python -m vk -c vk.json

Описание компонентов

BasicDatabase (database.py)

Класс BasicDatabase реализует все функции по чтению, изменению и удалению сущностей из БД, которая состоит из трех таблиц:

• bots - учетные записи ботов (пока добавляются в БД вручную)
• chats - параметры чатов, в которых работают боты (активация, правила, доп. инструкции для системного запроса)
• contexts - контексты чатов для модуля ИИ (история сообщений)

AiAgent (ai/agent.py)

Основной класс, обрабатывающий:

• get_group_chat_reply() - генерация ответа в групповом чате
• get_private_chat_reply() - генерация ответа в личном чате
• _generate_reply() - вызов LLM через OpenRouter
• _process_tool_calls() - обработка вызова функций

Обработчики сообщений и событий мессенджера (handlers)

• user.py - команды для всех участников групповых чатов
• admin.py - команды для администраторов групповых чатов
• action.py - служебные события групповых чатов (вступление/исключение участника, миграция чата)
• default.py - сообщения групповых чатов, адресованные боту (режим ИИ-ассистента)
• private.py - команды и сообщения в личных чатах

Фоновые задачи (tasks.py)

• startup_task() - действия, выполняемые однократно после авторизации в мессенджере
• daily_maintenance_task() - ежедневные служебные задачи (сброс счетчиков, чистка БД, поздравление именинников)

Особенности разработки

Стиль кода

• Стандарт PEP8
• Docstrings отсутствуют
• Комментарии только для сложных участков

Асинхронность

Большая часть функций в проекте - асинхронные.

Тестирование

Тесты отсутствуют. Для тестирования запускается экземпляр бота с тестовой конфигурацией, и вручную проверяется функциональность.