devzilla/discordBot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: обновить AGENTS.md с описанием архитектуры, API, конвертаций и безопасности

Browse Source
This commit is contained in:
deadzilla 2026-05-25 00:24:56 +05:00
parent 486e3124ed
commit 93f17c74d5
1 changed files with 58 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
AGENTS.md
View File

@ -1,38 +1,83 @@
# AGENTS.md # AGENTS.md
## Проект ## Проект
Discord-бот на Python (discord.py). Команды: `!msg` (повтор текста), `!pogoda` (прогноз погоды для Магнитогорска). Discord-бот на Python (discord.py) для Магнитогорска.
- Команды Discord: `!msg` (повтор текста), `!pogoda` (прогноз погоды)
- Консольные команды: `stop` (остановка бота)
## Запуск ## Запуск
``` ```bash
pip install -r requirements.txt pip install -r requirements.txt
python bot.py python bot.py
``` ```
Введите `stop` в терминал для остановки. Введите `stop` в терминал для остановки бота.
## Токен ## Токен
Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.env.example`. Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.env.example`.
## Конвенции ## Конвенции
Используй TODO-списки для каждого запроса с несколькими шагами. - Используй TODO-списки для каждого запроса с несколькими шагами.
- Пиши комментарии на русском.
- Обработка ошибок: try/except для всех внешних вызовов (API, БД, файловая система).
## Архитектура ## Архитектура
``` ```
commands/ # Discord команды (cogs) bot.py # Точка входа, инициализация бота, console_input()
__init__.py # ALL_COMMANDS — явные импорты commands/ # Discord команды (cogs)
pogoda.py # !pogoda __init__.py # ALL_COMMANDS — явные импорты
console_commands/ # Консольные команды pogoda.py # !pogoda — погода с retry + fallback (wttr.in → Open-Meteo)
__init__.py # ALL_CONSOLE_COMMANDS — явные импорты console_commands/ # Консольные команды
stop.py # stop __init__.py # ALL_CONSOLE_COMMANDS — явные импорты
stop.py # stop — остановка бота
``` ```
**Добавление Discord команды:** ### Добавление Discord команды
1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog` 1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog`
2. Добавить импорт в `commands/__init__.py` 2. Добавить импорт в `commands/__init__.py`
3. Добавить класс в `ALL_COMMANDS` 3. Добавить класс в `ALL_COMMANDS`
**Добавление консольной команды:** ### Добавление консольной команды
1. Создать файл `console_commands/имя.py` с функцией 1. Создать файл `console_commands/имя.py` с функцией `func(stop_event, bot)`
2. Добавить импорт в `console_commands/__init__.py` 2. Добавить импорт в `console_commands/__init__.py`
3. Добавить функцию в `ALL_CONSOLE_COMMANDS` 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` как шаблон.