84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# AGENTS.md
|
||
|
||
## Проект
|
||
Discord-бот на Python (discord.py) для Магнитогорска.
|
||
- Команды Discord: `!msg` (повтор текста), `!pogoda` (прогноз погоды)
|
||
- Консольные команды: `stop` (остановка бота)
|
||
|
||
## Запуск
|
||
```bash
|
||
pip install -r requirements.txt
|
||
python bot.py
|
||
```
|
||
|
||
Введите `stop` в терминал для остановки бота.
|
||
|
||
## Токен
|
||
Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.env.example`.
|
||
|
||
## Конвенции
|
||
- Используй TODO-списки для каждого запроса с несколькими шагами.
|
||
- Пиши комментарии на русском.
|
||
- Обработка ошибок: try/except для всех внешних вызовов (API, БД, файловая система).
|
||
|
||
## Архитектура
|
||
```
|
||
bot.py # Точка входа, инициализация бота, console_input()
|
||
commands/ # Discord команды (cogs)
|
||
__init__.py # ALL_COMMANDS — явные импорты
|
||
pogoda.py # !pogoda — погода с retry + fallback (wttr.in → Open-Meteo)
|
||
console_commands/ # Консольные команды
|
||
__init__.py # ALL_CONSOLE_COMMANDS — явные импорты
|
||
stop.py # stop — остановка бота
|
||
```
|
||
|
||
### Добавление Discord команды
|
||
1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog`
|
||
2. Добавить импорт в `commands/__init__.py`
|
||
3. Добавить класс в `ALL_COMMANDS`
|
||
|
||
### Добавление консольной команды
|
||
1. Создать файл `console_commands/имя.py` с функцией `func(stop_event, bot)`
|
||
2. Добавить импорт в `console_commands/__init__.py`
|
||
3. Добавить функцию в `ALL_CONSOLE_COMMANDS`
|
||
|
||
## API и внешние сервисы
|
||
|
||
### Погода (!pogoda)
|
||
- **Основной**: `wttr.in` (бесплатный, без ключа)
|
||
- **Fallback**: `api.open-meteo.com` (бесплатный, без ключа)
|
||
- Retry: 3 попытки с экспоненциальной задержкой при SSL/Connection/Timeout ошибках
|
||
- Fallback срабатывает автоматически при неуспешных попытках
|
||
- WMO weather codes → русский перевод в `_wmo_to_russian()`
|
||
|
||
### Конвертации
|
||
- Давление: hPa → мм рт. ст. (`* 0.750062`)
|
||
- Ветер: км/ч → м/с (`/ 3.6`)
|
||
- Погодные описания: английский → русский (`_translate_weather()`)
|
||
|
||
## Конфигурация
|
||
| Переменная | Описание | Где взять |
|
||
|------------|----------|-----------|
|
||
| `DISCORD_TOKEN` | Токен бота | Discord Developer Portal |
|
||
|
||
## Зависимости
|
||
```txt
|
||
discord.py>=2.3.2
|
||
python-dotenv>=1.0.0
|
||
requests>=2.31.0
|
||
```
|
||
|
||
## Структура данных погоды
|
||
Команда `!pogoda` возвращает:
|
||
```
|
||
[TEMP] Температура: X°C (ощущается как Y°C)
|
||
[DESC] Описание: Z
|
||
[HUMID] Влажность: X%
|
||
[WIND] Ветер: X м/с
|
||
[PRESS] Давление: X мм рт. ст.
|
||
```
|
||
|
||
## Безопасность
|
||
- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий.
|
||
- Используй `.env.example` как шаблон.
|