🚀 HumanOS - Telegram Bot на aiogram 3.x

Telegram-бот для управления квестами и задачами с интеграцией Windsurf AI.

📋 Описание

HumanOS — это мотивационный Telegram-бот, который помогает превратить ваши цели в увлекательные квесты. Бот поддерживает:

• ✅ Создание квестов разных типов (физические, интеллектуальные, ментальные, произвольные)
• 📈 Отслеживание прогресса с частичным выполнением задач
• 📅 Дедлайны и напоминания для квестов
• 🤖 AI-генерация квестов через Windsurf AI на основе ваших целей
• 💬 Комментарии к квестам для дополнительных заметок
• 📊 Статистика выполнения (в разработке)

🛠️ Технологии

• Python 3.11+
• aiogram 3.13.1 — асинхронный фреймворк для Telegram Bot API
• aiohttp — асинхронные HTTP-запросы для AI интеграции
• aiosqlite — асинхронная работа с SQLite
• python-dotenv — управление переменными окружения
• loguru — продвинутое логирование

📦 Установка

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

git clone <your-repo-url>
cd HumanOS

2. Создание виртуального окружения

Windows:

python -m venv venv
venv\Scripts\activate

Linux/Mac:

python3 -m venv venv
source venv/bin/activate

3. Установка зависимостей

pip install -r requirements.txt

4. Настройка переменных окружения

Скопируйте .env.example в .env:

copy .env.example .env  # Windows
cp .env.example .env    # Linux/Mac

Отредактируйте файл .env и укажите свои данные:

# Токен Telegram-бота (получить у @BotFather)
BOT_TOKEN=your_telegram_bot_token_here

# API ключ для Windsurf AI (опционально)
WINDSURF_API_KEY=your_windsurf_api_key_here

# URL API Windsurf AI
WINDSURF_API_URL=https://api.windsurf.ai/v1/chat/completions

# Путь к базе данных SQLite
DATABASE_PATH=quests.db

# Уровень логирования (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

5. Получение токена бота

1. Откройте Telegram и найдите @BotFather
2. Отправьте команду /newbot
3. Следуйте инструкциям для создания бота
4. Скопируйте полученный токен в файл .env

6. Настройка Windsurf AI (опционально)

Если вы хотите использовать AI-генерацию квестов:

1. Получите API ключ от Windsurf AI
2. Укажите его в .env файле в переменной WINDSURF_API_KEY
3. При необходимости измените WINDSURF_API_URL

Примечание: Бот будет работать и без AI, но функция /quest будет недоступна.

🚀 Запуск

Запуск бота

python main.py

Вы увидите сообщение:

✅ Бот запущен и готов к работе!
📊 База данных: quests.db
🤖 AI: Включен/Выключен

Остановка бота

Нажмите Ctrl+C в терминале.

📖 Использование

Основные команды

• /start — Запуск бота и главное меню
• /help — Справка по командам
• /add_task — Быстрое добавление задачи
• /quest — Создание квеста через AI (требуется API ключ)
• /progress — Просмотр прогресса по всем квестам

Типы квестов

1. 💪 Физические задачи — с количественным значением (например, пробежать 50 км)
2. 📚 Интеллектуальные задачи — с количественным значением (например, прочитать 10 книг)
3. 🧠 Ментальные задачи — с процентом выполнения 0-100% (например, медитация)
4. 🎯 Произвольные задачи — с процентом выполнения 0-100% (любые другие цели)

Пример использования AI

1. Нажмите кнопку "🤖 AI Квест" или используйте команду /quest
2. Опишите свою цель, например: "Хочу похудеть на 5 кг"
3. Бот сгенерирует персональный квест с советами и рекомендациями
4. Квест автоматически добавится в ваш список

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

HumanOS/
├── main.py              # Точка входа приложения
├── config.py            # Конфигурация и переменные окружения
├── database_async.py    # Асинхронная работа с базой данных
├── ai_client.py         # Интеграция с Windsurf AI
├── handlers.py          # Обработчики команд и callback-кнопок
├── requirements.txt     # Зависимости проекта
├── .env.example         # Пример файла с переменными окружения
├── .env                 # Ваши переменные окружения (не в git)
├── README.md            # Документация
├── quests.db            # База данных SQLite (создается автоматически)
└── bot.log              # Лог-файл (создается автоматически)

🔧 Разработка

Добавление новых команд

1. Откройте handlers.py
2. Добавьте новый обработчик с декоратором @router.message(Command("your_command"))
3. Реализуйте логику команды

Добавление новых callback-кнопок

1. Создайте клавиатуру в функции get_*_keyboard()
2. Добавьте обработчик с декоратором @router.callback_query(F.data == "your_callback")

Работа с базой данных

Все методы базы данных асинхронные. Примеры:

# Создание квеста
quest_id, error = await db.create_quest(
    user_id=user_id,
    title="Название",
    quest_type="physical",
    target_value=100
)

# Получение квестов пользователя
quests = await db.get_user_quests(user_id)

# Обновление прогресса
quest = await db.update_quest_progress(user_id, quest_id, new_value)

🐛 Решение проблем

Ошибка: "BOT_TOKEN не установлен"

Решение: Проверьте, что файл .env существует и содержит корректный токен бота.

Ошибка: "AI функция недоступна"

Решение: Убедитесь, что WINDSURF_API_KEY установлен в .env файле. Если не нужен AI, просто не используйте команду /quest.

Бот не отвечает на команды

Решение:

1. Проверьте, что бот запущен (python main.py)
2. Убедитесь, что токен бота корректный
3. Проверьте логи в файле bot.log

Ошибки при установке зависимостей

Решение:

# Обновите pip
python -m pip install --upgrade pip

# Установите зависимости заново
pip install -r requirements.txt --force-reinstall

📝 Логирование

Логи сохраняются в двух местах:

1. Консоль — цветной вывод в реальном времени
2. bot.log — файл с ротацией (максимум 10 MB, хранится 7 дней)

Уровень логирования настраивается в .env через переменную LOG_LEVEL.

🔐 Безопасность

• ✅ Валидация пользовательского ввода на SQL-инъекции
• ✅ Ограничение длины текстовых полей (500 символов)
• ✅ Токены и API ключи хранятся в .env (не в коде)
• ✅ Файл .env добавлен в .gitignore

🤝 Вклад в проект

Если вы хотите улучшить проект:

1. Создайте fork репозитория
2. Создайте ветку для новой функции (git checkout -b feature/amazing-feature)
3. Сделайте commit изменений (git commit -m 'Add amazing feature')
4. Отправьте изменения в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

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

📞 Поддержка

Если у вас возникли вопросы или проблемы:

1. Проверьте раздел "Решение проблем" выше
2. Посмотрите логи в bot.log
3. Создайте Issue в репозитории

---

Сделано с ❤️ для достижения целей и саморазвития