302 lines
12 KiB
Markdown
302 lines
12 KiB
Markdown
# 🤖 ChatBot - AI Telegram Bot
|
||
|
||
[](https://dotnet.microsoft.com/)
|
||
[](LICENSE.txt)
|
||
[](https://www.postgresql.org/)
|
||
|
||
[](https://sonarqube.api.home/dashboard?id=ChatBot)
|
||
[](https://sonarqube.api.home/dashboard?id=ChatBot)
|
||
[](https://sonarqube.api.home/dashboard?id=ChatBot)
|
||
[](https://sonarqube.api.home/dashboard?id=ChatBot)
|
||
[](https://sonarqube.api.home/dashboard?id=ChatBot)
|
||
|
||
Интеллектуальный Telegram-бот на базе локальных AI моделей (Ollama), построенный на .NET 9 с использованием Clean Architecture.
|
||
|
||
## ✨ Основные возможности
|
||
|
||
- 🤖 **AI-интеграция** - Использование локальных LLM через Ollama (gemma2, llama3, mistral)
|
||
- 💬 **Telegram Bot** - Полнофункциональный бот с поддержкой команд и групповых чатов
|
||
- 💾 **PostgreSQL** - Надежное хранение истории диалогов и сессий
|
||
- 🗜️ **История сжатия** - Автоматическая оптимизация длинных диалогов
|
||
- 🔄 **Retry механизмы** - Устойчивость к сбоям с экспоненциальным backoff
|
||
- 📊 **Health Checks** - Мониторинг состояния всех сервисов
|
||
- 🧪 **Высокое покрытие тестами** - 50+ тестовых классов
|
||
- 📝 **Serilog** - Структурированное логирование
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Требования
|
||
|
||
- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)
|
||
- [PostgreSQL 14+](https://www.postgresql.org/download/)
|
||
- [Ollama](https://ollama.ai/) с установленной моделью
|
||
- Telegram Bot Token ([создать через @BotFather](https://t.me/botfather))
|
||
|
||
### Установка за 3 шага
|
||
|
||
#### 1. Клонирование и установка зависимостей
|
||
|
||
```bash
|
||
git clone https://github.com/mrleo1nid/ChatBot.git
|
||
cd ChatBot
|
||
dotnet restore
|
||
```
|
||
|
||
#### 2. Настройка окружения
|
||
|
||
Создайте файл `ChatBot/.env`:
|
||
|
||
```env
|
||
# Database Configuration
|
||
DB_HOST=localhost
|
||
DB_PORT=5432
|
||
DB_NAME=chatbot
|
||
DB_USER=postgres
|
||
DB_PASSWORD=your_secure_password
|
||
|
||
# Telegram Bot Configuration
|
||
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
|
||
|
||
# Ollama Configuration
|
||
OLLAMA_URL=http://localhost:11434
|
||
OLLAMA_DEFAULT_MODEL=gemma2:2b
|
||
```
|
||
|
||
#### 3. Запуск
|
||
|
||
```bash
|
||
# Установите AI модель
|
||
ollama pull gemma2:2b
|
||
|
||
# Создайте базу данных
|
||
psql -U postgres -c "CREATE DATABASE chatbot;"
|
||
|
||
# Запустите бота
|
||
cd ChatBot
|
||
dotnet run
|
||
```
|
||
|
||
🎉 **Готово!** Откройте Telegram и найдите вашего бота.
|
||
|
||
## 📚 Документация
|
||
|
||
### 🎯 Начало работы
|
||
- [📋 Обзор проекта](docs/overview.md) - Что такое ChatBot и его возможности
|
||
- [⚡ Быстрый старт](docs/quickstart.md) - Запуск за 5 минут
|
||
- [🛠️ Установка и настройка](docs/installation.md) - Подробная инструкция
|
||
- [⚙️ Конфигурация](docs/configuration.md) - Настройка параметров
|
||
|
||
### 🏗️ Архитектура
|
||
- [📐 Архитектура проекта](docs/architecture/overview.md) - Общая архитектура
|
||
- [🏛️ Слои приложения](docs/architecture/layers.md) - Детальное описание слоев
|
||
- [📊 Модели данных](docs/architecture/data-models.md) - Структура данных
|
||
- [🗄️ База данных](docs/architecture/database.md) - Работа с PostgreSQL
|
||
|
||
### 💻 Разработка
|
||
- [📁 Структура проекта](docs/development/project-structure.md) - Организация кода
|
||
- [🤖 Команды бота](docs/api/bot-commands.md) - Все доступные команды
|
||
|
||
### 📖 Полная документация
|
||
|
||
**👉 [Перейти к полной документации](docs/README.md)**
|
||
|
||
## 🎮 Использование
|
||
|
||
### Команды бота
|
||
|
||
```
|
||
/start - Начать работу с ботом
|
||
/help - Показать справку
|
||
/clear - Очистить историю диалога
|
||
/settings - Показать текущие настройки
|
||
/status - Проверить статус бота
|
||
```
|
||
|
||
### Пример диалога
|
||
|
||
```
|
||
Вы: Привет!
|
||
Бот: Привет! Как дела? 😊
|
||
|
||
Вы: Расскажи анекдот
|
||
Бот: Программист ложится спать...
|
||
Ставит рядом два стакана:
|
||
один с водой — если захочет пить,
|
||
другой пустой — если не захочет 😄
|
||
```
|
||
|
||
## 🏗️ Технологический стек
|
||
|
||
### Backend
|
||
- **Runtime:** .NET 9.0
|
||
- **Language:** C# 13
|
||
- **Architecture:** Clean Architecture, SOLID
|
||
|
||
### Основные библиотеки
|
||
- **Telegram.Bot** 22.7.2 - Telegram Bot API
|
||
- **OllamaSharp** 5.4.7 - Ollama клиент для AI
|
||
- **Entity Framework Core** 9.0.10 - ORM
|
||
- **Npgsql** 9.0.4 - PostgreSQL провайдер
|
||
- **Serilog** 4.3.0 - Логирование
|
||
- **FluentValidation** 12.0.0 - Валидация
|
||
|
||
### Тестирование
|
||
- **xUnit** 2.9.3 - Тестовый фреймворк
|
||
- **Moq** 4.20.72 - Моки и стабы
|
||
- **FluentAssertions** 8.7.1 - Assertions
|
||
- **Coverlet** 6.0.4 - Code coverage
|
||
|
||
## 📊 Архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Telegram Bot Layer │
|
||
│ (Commands, Handlers) │
|
||
├─────────────────────────────────────┤
|
||
│ Service Layer │
|
||
│ (ChatService, AIService) │
|
||
├─────────────────────────────────────┤
|
||
│ Data Access Layer │
|
||
│ (Repositories, DbContext) │
|
||
├─────────────────────────────────────┤
|
||
│ Infrastructure │
|
||
│ (PostgreSQL, Ollama, Telegram) │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
**Принципы:**
|
||
- Clean Architecture
|
||
- SOLID принципы
|
||
- Dependency Injection
|
||
- Repository Pattern
|
||
- Command Pattern для команд бота
|
||
|
||
## 🐳 Docker развертывание
|
||
|
||
```bash
|
||
# Сборка образа
|
||
docker build -t chatbot:latest .
|
||
|
||
# Запуск с docker-compose
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 🧪 Тестирование
|
||
|
||
```bash
|
||
# Запуск всех тестов
|
||
dotnet test
|
||
|
||
# С покрытием кода
|
||
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
|
||
|
||
# Запуск конкретного теста
|
||
dotnet test --filter "FullyQualifiedName~ChatServiceTests"
|
||
```
|
||
|
||
## 📈 CI/CD
|
||
|
||
Проект использует Gitea Actions для автоматизации:
|
||
- ✅ Сборка проекта
|
||
- ✅ Запуск тестов
|
||
- ✅ Анализ кода (SonarQube)
|
||
- ✅ Проверка покрытия
|
||
|
||
Конфигурация: [`.gitea/workflows/build.yml`](.gitea/workflows/build.yml)
|
||
|
||
## 🔧 Конфигурация
|
||
|
||
### Основные параметры
|
||
|
||
| Параметр | Описание | По умолчанию |
|
||
|----------|----------|-------------|
|
||
| `AI.Temperature` | Креативность ответов (0.0-2.0) | 0.9 |
|
||
| `AI.MaxRetryAttempts` | Макс. попыток повтора | 3 |
|
||
| `AI.EnableHistoryCompression` | Сжатие истории | true |
|
||
| `AI.CompressionThreshold` | Порог сжатия (сообщений) | 20 |
|
||
|
||
**Подробнее:** [docs/configuration.md](docs/configuration.md)
|
||
|
||
## 🛠️ Разработка
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
ChatBot/
|
||
├── ChatBot/ # Основной проект
|
||
│ ├── Services/ # Бизнес-логика
|
||
│ ├── Data/ # Доступ к данным
|
||
│ ├── Models/ # Модели и конфигурация
|
||
│ └── Program.cs # Точка входа
|
||
├── ChatBot.Tests/ # Тесты
|
||
└── docs/ # Документация
|
||
```
|
||
|
||
### Добавление новой команды
|
||
|
||
```csharp
|
||
public class MyCommand : TelegramCommandBase
|
||
{
|
||
public override string Command => "mycommand";
|
||
public override string Description => "Описание команды";
|
||
|
||
public override async Task<ReplyInfo> ExecuteAsync(TelegramCommandContext context)
|
||
{
|
||
return new ReplyInfo { Text = "Ответ" };
|
||
}
|
||
}
|
||
```
|
||
|
||
Зарегистрируйте в `Program.cs`:
|
||
```csharp
|
||
builder.Services.AddScoped<ITelegramCommand, MyCommand>();
|
||
```
|
||
|
||
## 🤝 Вклад в проект
|
||
|
||
Мы приветствуем вклад в развитие проекта!
|
||
|
||
### Как внести изменения
|
||
|
||
1. Fork репозитория
|
||
2. Создайте feature branch (`git checkout -b feature/amazing-feature`)
|
||
3. Commit изменения (`git commit -m 'Add amazing feature'`)
|
||
4. Push в branch (`git push origin feature/amazing-feature`)
|
||
5. Откройте Pull Request
|
||
|
||
### Guidelines
|
||
|
||
- Следуйте существующему стилю кода
|
||
- Добавляйте тесты для новой функциональности
|
||
- Обновляйте документацию
|
||
- Убедитесь, что все тесты проходят
|
||
|
||
## 📝 Лицензия
|
||
|
||
Этот проект распространяется под лицензией MIT. См. [LICENSE.txt](LICENSE.txt) для подробностей.
|
||
|
||
## 🙏 Благодарности
|
||
|
||
- [Telegram Bot API](https://core.telegram.org/bots/api) - За отличное API
|
||
- [Ollama](https://ollama.ai/) - За возможность использовать локальные LLM
|
||
- [.NET Community](https://dotnet.microsoft.com/) - За мощный фреймворк
|
||
|
||
## 📞 Контакты и поддержка
|
||
|
||
- 🐛 [Сообщить о проблеме](https://github.com/mrleo1nid/ChatBot/issues)
|
||
- 💡 [Предложить улучшение](https://github.com/mrleo1nid/ChatBot/issues)
|
||
- 📖 [Документация](docs/README.md)
|
||
|
||
## 🌟 Roadmap
|
||
|
||
- [ ] Поддержка мультимодальных моделей (изображения)
|
||
- [ ] Веб-интерфейс для управления ботом
|
||
- [ ] Метрики и аналитика использования
|
||
- [ ] Kubernetes deployment манифесты
|
||
- [ ] Дополнительные команды (история, экспорт)
|
||
- [ ] Плагинная система для расширений
|
||
|
||
---
|
||
|
||
**Сделано с ❤️ используя .NET 9 и Ollama**
|