d12579b73c
- Заменить 'from discord import commands' на 'from discord.ext import commands' - Исправлена ошибка ImportError, из-за которой не запускались тесты - Обновлена документация AGENTS.md
115 lines
5.8 KiB
Markdown
115 lines
5.8 KiB
Markdown
# 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-коммитов писать на русском языке.**
|
||
- **Думать и размышляй на английском, а отвечать пользователю на русском.**
|
||
|
||
## Команды
|
||
|
||
| Команда | Описание | Формат вывода |
|
||
|---------|----------|---------------|
|
||
| `!pogoda` | Погода в Магнитогорске | Температура, ощущается, описание, влажность, ветер, давление |
|
||
| `!news` | Топ-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 и внешние сервисы
|
||
|
||
### Погода (!pogoda, !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 (!news, !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`) |
|
||
|
||
## Зависимости
|
||
```txt
|
||
discord.py>=2.3.2
|
||
python-dotenv>=1.0.0
|
||
requests>=2.31.0
|
||
```
|
||
|
||
## Структура данных погоды
|
||
Команда `!pogoda` возвращает:
|
||
```
|
||
Температура: X°C (ощущается как Y°C)
|
||
Описание: Z
|
||
Влажность: X%
|
||
Ветер: X м/с
|
||
Давление: X мм рт. ст.
|
||
```
|
||
|
||
## Консольные команды
|
||
Запускаются через терминал при старте бота. Список выводится при запуске.
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `pogoda` | Вывести погоду в Магнитогорск |
|
||
| `news` | Вывести топ-5 статей AI с Habr |
|
||
| `morning` | Вывести погоду, топ-5 статей и котик |
|
||
| `cat` | Заглушка |
|
||
| `stop` | Остановить бота |
|
||
|
||
## Безопасность
|
||
- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий.
|
||
- Используй `.env.example` как шаблон.
|