Добавлен AGENTS.md.

2026-04-05 15:44:08 +03:00 · 2026-04-05 15:44:08 +03:00 · d2c10fa0a5
commit d2c10fa0a5
parent 1c58359e44
1 changed files with 106 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,106 @@
+# Чат-бот для 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 бот
+```bash
+python -m tg -c tg.json
+```
+
+### VK бот
+```bash
+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 отсутствуют
+- Комментарии только для сложных участков
+
+### Асинхронность
+Большая часть функций в проекте - асинхронные.
+
+### Тестирование
+Тесты отсутствуют. Для тестирования запускается экземпляр бота с тестовой конфигурацией, и вручную проверяется функциональность.