# Скиллы для жителей

Эта страница фиксирует пользовательские skills, которые реализованы и развиваются в `iola-cli`.

Цель этих skills - помогать жителю города в бытовых вопросах: где находится объект, что рядом, какой объект ближе, как открыть место на карте. Это не административный аудит данных.

## Geo skills

Для geo skills нужен ключ `Yandex Geocoder API`.

Первый рабочий контур подключен к слоям `schools` и `kindergartens`.

Команды:

```bash
iola geo nearby "Йошкар-Ола, улица Петрова, 15" --dataset all --limit 5
iola geo distance --from "Петрова 15" --to "школа 7"
iola geo map-link "школа 7"
iola geo resolve "садик золотой петушок"
iola geo route-context "школа 7"
iola geo services "Йошкар-Ола, улица Петрова, 15"
```

### nearby

Находит городские объекты рядом с адресом пользователя.

Примеры:

- `какие детские сады рядом с Петрова 15`;
- `какие школы ближе к улице Машиностроителей`;
- `что из городских учреждений рядом с домом`.

Сейчас работает по слоям `schools` и `kindergartens`. Позже можно подключить МФЦ, поликлиники, остановки, спортобъекты и учреждения культуры.

### route-context

Объясняет, где находится объект, простым языком: адрес, ориентиры, что рядом, ссылка на карту.

Это не полноценный навигатор и не замена маршрутизатору. Skill дает понятный контекст места для жителя.

### address-to-services

По адресу жителя подбирает релевантные городские объекты.

Примеры:

- ближайшие школы;
- ближайшие детские сады;
- будущие слои муниципальных услуг и учреждений.

### map-link

Добавляет в ответы ссылку на карту.

Примеры:

- открыть школу на Яндекс.Картах;
- открыть детский сад на карте;
- показать точку по координатам.

### place-resolver

Помогает понять криво написанные адреса, названия и ориентиры.

Примеры:

- `семеновка школа`;
- `первомаиская 89`;
- `садик золотой петушок`;
- `рядом с вокзалом`.

Главная задача - не подставлять похожий, но неправильный объект.

### distance

Считает расстояние от адреса пользователя до объекта или между объектами.

Примеры:

- `какой садик ближе к дому`;
- `как далеко школа 7 от Первомайской 89`;
- `что ближе: Пчелка или Улыбка`.

### area-filter

Фильтрует ответы по населенному пункту или району.

Примеры:

- Йошкар-Ола;
- Семеновка;
- другие населенные пункты городского округа, когда они появятся в слоях.

Это важно, чтобы не путать объекты с одинаковыми номерами или похожими названиями.

## Ограничения

- Расстояние считается по прямой между координатами. Это не автомобильный и не пешеходный маршрут.
- CLI не должен подставлять похожий объект из другого населенного пункта. Если слой не содержит нужный объект, ответ должен прямо говорить, что данных недостаточно.
- При первом поиске рядом CLI геокодирует объекты слоя. Повторные запросы в той же сессии работают быстрее за счет памяти процесса.

## Personal docs skills

Эти skills работают с личными документами пользователя в подключенном облаке. Они включаются только при явном облачном намерении: `Яндекс Диск`, `Облако Mail.ru`, `облако`, `сохрани на диск`, `загрузи`, `дай ссылку`, `поделиться`.

Если пользователь говорит только `файл`, `папка` или `документ`, CLI использует `local-files`, а не облако.

### cloud-find-document

Найти документ в подключенном облаке: справку, квитанцию, школьный документ, файл обращения.

### cloud-save-result

Сохранить ответ CLI, отчет, карточку учреждения или список ближайших объектов в `/IOLA`.

### cloud-create-folder

Создать папку на подключенном облачном диске.

Пример:

- `создай у меня на яндекс диске папку фото`;
- `создай папку документы в облаке`.

### cloud-share-link

Создать публичную ссылку на файл. В первом контуре поддерживается для Яндекс Диска.

### cloud-document-pack

Собрать папку с материалами для обращения: текст, найденные данные, ссылки, вложенные документы и скриншоты.

### cloud-inbox

Проверить `/IOLA/inbox`, найти новые документы и предложить их разобрать или проиндексировать.

### cloud-backup-cli

Сохранить резервную копию настроек CLI без секретов, OAuth-токенов и API-ключей.

### cloud-restore-cli

Восстановить CLI из резервной копии, когда пользователь переустановил программу или перешел на другой компьютер.

### cloud-organize

Помочь разобрать личные документы: найти старые отчеты, крупные файлы, дубликаты и предложить структуру папок.

## Yandex services skills

Эти skills работают через Yandex Connector. Пользователь входит в свой Яндекс-аккаунт, а токены хранятся локально на компьютере.

### yandex-identity

Проверить, какой Yandex ID подключен: логин, имя и email.

### yandex-disk

Работать с Яндекс Диском:

- показать файлы и папки в `/IOLA`;
- создать папку;
- найти файл или папку;
- сохранить текстовый результат;
- создать или снять публичную ссылку;
- загрузить или скачать файл.

### yandex-mail

Работать с Яндекс Почтой:

- проверить доступ к почте;
- показать последние или непрочитанные письма;
- показать папки почты: входящие, отправленные, черновики, спам, корзина и пользовательские папки;
- показать письма из конкретной папки, например из спама, черновиков или отправленных;
- найти письмо;
- прочитать письмо по UID или номеру из последнего списка;
- при чтении по просьбе пользователя пометить письмо прочитанным;
- пометить письмо прочитанным или непрочитанным;
- отправить письмо только после явного запроса;
- ответить на письмо по UID или номеру из последнего списка;
- удалить письмо безопасно: переместить его в корзину, а не стирать безвозвратно.

Список писем и поиск не меняют статус письма. Статус меняется только при чтении письма, явной пометке или явном удалении.

### yandex-calendar

Работать с Яндекс Календарем:

- показать ближайшие события;
- создать событие только после явного подтверждения.

### yandex-contacts

Работать с Яндекс Контактами:

- проверить доступ к адресной книге;
- показать контакты;
- найти контакт по имени, email или телефону.

### yandex-telemost

Подготовить встречу через календарное событие. CLI не должен сам нажимать финальные кнопки в интерфейсе Яндекса без явного действия пользователя.

## Yandex Connector backlog

Эти сценарии зафиксированы для следующего этапа. Они не должны оформлять заказ, списывать деньги или нажимать финальную кнопку вместо пользователя.

### taxi-prepare-ride

Подготовить поездку в Яндекс Go:

- уточнить точку отправления и назначения;
- геокодировать адреса;
- сформировать ссылку/deep link в Яндекс Go;
- открыть приложение или страницу;
- пользователь сам проверяет цену и нажимает заказ.

### market-prepare-cart

Подготовить список покупок для Яндекс Маркета:

- разобрать запрос пользователя;
- найти подходящие товары или поисковые ссылки;
- собрать список вариантов;
- сохранить список в CLI или на Диск;
- пользователь сам добавляет товары в корзину и оплачивает.

### delivery-prepare-order

Подготовить доставку:

- уточнить адрес отправления и получения;
- сформировать ссылку или маршрут;
- открыть подходящий сервис Яндекса;
- пользователь сам подтверждает заявку и оплату.
