discordBot/AGENTS.md

AGENTS.md

Проект

Discord-бот на Python (discord.py)

Запуск

pip install -r requirements.txt
python bot.py

Токен

Токен бота хранится в .env (переменная DISCORD_TOKEN). Получи токен на Discord Developer Portal. Шаблон в .env.example.

Конвенции

• Используй TODO-списки для каждого запроса с несколькими шагами.
• Пиши комментарии на русском.
• Обработка ошибок: try/except для всех внешних вызовов (API, БД, файловая система).
• Никогда не используй эмодзи в тексте или выводах.
• До внесения любых изменений в код или файлы предоставь детальное описание всех планируемых изменений и получи явное согласие пользователя. Без согласования изменения не вносить.
• Все git-коммиты согласовывать с пользователем перед созданием.
• Все сообщения git-коммитов писать на русском языке.
• Думать и размышляй на английском, а отвечать пользователю на русском.

Команды

Команда	Описание	Формат вывода
!pg	Погода в Магнитогорске	Температура, ощущается, описание, влажность, ветер, давление
!nw	Топ-5 статей и топ-5 новостей AI с Habr	Два блока: статьи и новости
!morning	Погода + топ-5 статей + топ-5 новостей + котик	Embed: котик thumbnail, погода, статьи, новости
!cat	Случайный котик	Embed с изображением
!msg <текст>	Повторяет текст	Текст

Планировщик

• Ежедневный утренний дайджест (!morning) запускается автоматически в 07:00
• Время задаётся в .env переменной MORNING_TIME (формат ЧЧ:ММ)
• Реализован через discord.ext.tasks.loop
• Отправляет дайджест в первый канал, где бот имеет права
• Код в utils/morning_runner.py

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

Каталог	Назначение
commands/	Discord-команды (Cogs)
utils/	Утилиты (API-клиенты, конвертации)
console_commands/	Консольные команды (для терминала)
bot.py	Точка входа, загрузка Cogs, обработка ошибок

API и внешние сервисы

Погода (!pg, !morning)

• Основной: wttr.in/Magnitogorsk (бесплатный, без ключа)
• Fallback: api.open-meteo.com (бесплатный, без ключа)
• Retry: 3 попытки с экспоненциальной задержкой при SSL/Connection/Timeout ошибках
• Fallback срабатывает автоматически при неуспешных попытках
• WMO weather codes → русский перевод в wmo_to_russian()

Конвертации

• Давление: hPa → мм рт. ст. (* 0.750062)
• Ветер: км/ч → м/с (/ 3.6)
• Погодные описания: английский → русский (translate_weather())

RSS-ленты Habr (!nw, !morning)

Тип	URL
Статьи	https://habr.com/ru/rss/hubs/artificial_intelligence/articles/top/daily/?fl=ru
Новости	https://habr.com/ru/rss/hubs/artificial_intelligence/news/top/daily/?fl=ru

Парсятся RSS 2.0 / Atom, извлекаются title, pubDate, creator, category, guid.

Cat API (!cat, !morning)

• URL: https://api.thecatapi.com/v1/images/search
• Возвращает JSON: [{"url": "..."}]
• Используется для случайных изображений котиков

Конфигурация

Переменная	Описание	Где взять
DISCORD_TOKEN	Токен бота	Discord Developer Portal
MORNING_TIME	Время запуска утреннего дайджеста	.env (формат ЧЧ:ММ, по умолчанию 07:00)
MORNING_CHANNEL_ID	ID канала для утреннего дайджеста	Правый клик по каналу → Копировать ID

Зависимости

discord.py>=2.3.2
python-dotenv>=1.0.0
requests>=2.31.0

Структура данных погоды

Команда !pg возвращает:

Температура: X°C (ощущается как Y°C)
Описание: Z
Влажность: X%
Ветер: X м/с
Давление: X мм рт. ст.

Консольные команды

Запускаются через терминал при старте бота. Список выводится при запуске.

Команда	Описание
pogoda	Вывести погоду в Магнитогорск
news	Вывести топ-5 статей AI с Habr
morning	Вывести погоду, топ-5 статей и котик
cat	Заглушка
stop	Остановить бота

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

• .env в .gitignore — токен никогда не должен попадать в репозиторий.
• Используй .env.example как шаблон.