diff --git a/skills/yandex-weather-client/SKILL.md b/skills/yandex-weather-client/SKILL.md new file mode 100644 index 0000000..1c50061 --- /dev/null +++ b/skills/yandex-weather-client/SKILL.md @@ -0,0 +1,80 @@ +--- +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 +``` + +Для разовой точки допускается запуск по координатам: + +```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 +``` + +Для машинного результата допустим `--json`, но перед отправкой в Matrix нужно отфильтровать технические поля и убедиться, что ключ отсутствует в выводе. + +## Добавление новой локации + +- Найти координаты адреса по надёжному картографическому источнику. +- Добавить ключ, понятное имя, алиасы, `lat` и `lon` в `projects/yandex-weather/locations.json`. +- Не добавлять секреты в этот файл. +- Выполнить `--list-locations` и один тестовый запуск для новой точки. +- Сообщить пользователю, какой источник использован для координат. + +## Проверка и диагностика + +- Отсутствующий ключ: проверить наличие локального `.env`, не просить пользователя присылать ключ в Matrix. +- HTTP 403: проверить, что ключ активирован, тариф действует и используется endpoint `/v2/forecast`. +- Ошибка координат: проверить широту и долготу, затем реестр локаций. +- Превышение лимита: остановить повторные запросы и дождаться нового периода лимита.