yandex-weather/skills/yandex-weather-client/SKILL.md

name, description

name	description
yandex-weather-client	Работа с локальным Python-клиентом Яндекс.Погоды для семейных локаций.

Навык: Яндекс.Погода через локальный Python-клиент

Назначение

Использовать локальный клиент в projects/yandex-weather для получения прогноза напрямую из API Яндекс.Погоды. В рамках этого навыка не подменять источник встроенным погодным сервисом.

Безопасность ключа

• Ключ хранится только в локальном projects/yandex-weather/.env в переменной YANDEX_WEATHER_KEY.
• Никогда не выводить ключ, не добавлять его в сообщения Matrix и не вставлять в команды чата.
• Если ключ попал в переписку, считать его скомпрометированным: отозвать в кабинете Яндекс.Погоды и создать новый.
• Не читать и не цитировать содержимое .env без необходимости; клиент сам загружает его при запуске.

Доступные локации

Перед запуском можно посмотреть реестр:

cd projects/yandex-weather
python3 weather_client.py --list-locations

Поиск выполняется по ключу или сохранённому названию/алиасу:

python3 weather_client.py --location <location>

Для разовой точки допускается запуск по координатам:

python3 weather_client.py --lat <широта> --lon <долгота>

Ограничения бесплатного тарифа «Погода для умного дома»

• Запрашивать максимум два дня: сегодня и завтра.
• Один запуск клиента должен делать один API-запрос.
• Не добавлять лишние повторы или автоматические retry.
• Не использовать extra=true: бесплатный тариф не гарантирует числовые поля осадков и тайлы карты.
• В сообщении можно показывать ссылку на веб-карту осадков Яндекса; это не означает, что тайлы карты получены через API.
• Для личного семейного использования учитывать некоммерческие условия тарифа.

Рабочий порядок

1. Уточнить нужную локацию; если она есть в реестре, использовать --location.
2. Запустить клиент из projects/yandex-weather.
3. Проверить код завершения и не повторять запрос автоматически при сетевой ошибке.
4. Передать пользователю текущую температуру, ощущаемую температуру, ветер, прогноз на сегодня и завтра и ссылку на карту.
5. Не обещать API-данные об осадках сверх того, что вернул бесплатный тариф.
6. Для планового запуска использовать один запуск на одно сообщение.

Пример:

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.
• Ошибка координат: проверить широту и долготу, затем реестр локаций.
• Превышение лимита: остановить повторные запросы и дождаться нового периода лимита.