# AGENTS.md

## Проект
Discord-бот на Python (discord.py)

## Запуск
```bash
pip install -r requirements.txt
python bot.py
```
## Токен
Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.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 |

## Зависимости
```txt
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` как шаблон.