81 lines
5.2 KiB
Markdown
81 lines
5.2 KiB
Markdown
---
|
||
name: "yandex-weather-client"
|
||
description: "Работа с локальным Python-клиентом Яндекс.Погоды для семейных локаций."
|
||
---
|
||
|
||
# Навык: Яндекс.Погода через локальный Python-клиент
|
||
|
||
## Назначение
|
||
|
||
Использовать локальный клиент в `projects/yandex-weather` для получения прогноза напрямую из API Яндекс.Погоды. В рамках этого навыка не подменять источник встроенным погодным сервисом.
|
||
|
||
## Безопасность ключа
|
||
|
||
- Ключ хранится только в локальном `projects/yandex-weather/.env` в переменной `YANDEX_WEATHER_KEY`.
|
||
- Никогда не выводить ключ, не добавлять его в сообщения Matrix и не вставлять в команды чата.
|
||
- Если ключ попал в переписку, считать его скомпрометированным: отозвать в кабинете Яндекс.Погоды и создать новый.
|
||
- Не читать и не цитировать содержимое `.env` без необходимости; клиент сам загружает его при запуске.
|
||
|
||
## Доступные локации
|
||
|
||
Перед запуском можно посмотреть реестр:
|
||
|
||
```bash
|
||
cd projects/yandex-weather
|
||
python3 weather_client.py --list-locations
|
||
```
|
||
|
||
Поиск выполняется по ключу или сохранённому названию/алиасу:
|
||
|
||
```bash
|
||
python3 weather_client.py --location <location>
|
||
```
|
||
|
||
Для разовой точки допускается запуск по координатам:
|
||
|
||
```bash
|
||
python3 weather_client.py --lat <широта> --lon <долгота>
|
||
```
|
||
|
||
## Ограничения бесплатного тарифа «Погода для умного дома»
|
||
|
||
- Запрашивать максимум два дня: сегодня и завтра.
|
||
- Один запуск клиента должен делать один API-запрос.
|
||
- Не добавлять лишние повторы или автоматические retry.
|
||
- Не использовать `extra=true`: бесплатный тариф не гарантирует числовые поля осадков и тайлы карты.
|
||
- В сообщении можно показывать ссылку на веб-карту осадков Яндекса; это не означает, что тайлы карты получены через API.
|
||
- Для личного семейного использования учитывать некоммерческие условия тарифа.
|
||
|
||
## Рабочий порядок
|
||
|
||
1. Уточнить нужную локацию; если она есть в реестре, использовать `--location`.
|
||
2. Запустить клиент из `projects/yandex-weather`.
|
||
3. Проверить код завершения и не повторять запрос автоматически при сетевой ошибке.
|
||
4. Передать пользователю текущую температуру, ощущаемую температуру, ветер, прогноз на сегодня и завтра и ссылку на карту.
|
||
5. Не обещать API-данные об осадках сверх того, что вернул бесплатный тариф.
|
||
6. Для планового запуска использовать один запуск на одно сообщение.
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
cd projects/yandex-weather
|
||
python3 weather_client.py --location <location>
|
||
```
|
||
|
||
Для машинного результата допустим `--json`, но перед отправкой в Matrix нужно отфильтровать технические поля и убедиться, что ключ отсутствует в выводе.
|
||
|
||
## Добавление новой локации
|
||
|
||
- Найти координаты адреса по надёжному картографическому источнику.
|
||
- Добавить ключ, понятное имя, алиасы, `lat` и `lon` в `projects/yandex-weather/locations.json`.
|
||
- Не добавлять секреты в этот файл.
|
||
- Выполнить `--list-locations` и один тестовый запуск для новой точки.
|
||
- Сообщить пользователю, какой источник использован для координат.
|
||
|
||
## Проверка и диагностика
|
||
|
||
- Отсутствующий ключ: проверить наличие локального `.env`, не просить пользователя присылать ключ в Matrix.
|
||
- HTTP 403: проверить, что ключ активирован, тариф действует и используется endpoint `/v2/forecast`.
|
||
- Ошибка координат: проверить широту и долготу, затем реестр локаций.
|
||
- Превышение лимита: остановить повторные запросы и дождаться нового периода лимита.
|