Добавлен AGENTS.md.
This commit is contained in:
parent
1c58359e44
commit
d2c10fa0a5
1 changed files with 106 additions and 0 deletions
106
AGENTS.md
Normal file
106
AGENTS.md
Normal file
|
|
@ -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 отсутствуют
|
||||||
|
- Комментарии только для сложных участков
|
||||||
|
|
||||||
|
### Асинхронность
|
||||||
|
Большая часть функций в проекте - асинхронные.
|
||||||
|
|
||||||
|
### Тестирование
|
||||||
|
Тесты отсутствуют. Для тестирования запускается экземпляр бота с тестовой конфигурацией, и вручную проверяется функциональность.
|
||||||
Loading…
Add table
Reference in a new issue