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

Эта страница фиксирует пользовательские 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`;
- создать папку;
- найти файл или папку;
- проверить, есть ли файл или папка;
- показать карточку файла: размер, тип, даты изменения, публичная ссылка;
- прочитать небольшой текстовый файл;
- сохранить текстовый результат;
- создать или снять публичную ссылку;
- создать QR-код для публичной ссылки и сохранить его на Диск;
- отправить публичную ссылку и QR-код по Яндекс Почте email-адресу или контакту;
- загрузить или скачать файл;
- переместить, скопировать или переименовать файл/папку;
- удалить файл/папку в корзину;
- показать корзину, восстановить объект из корзины или очистить корзину.

Примеры:

- `сколько места на Яндекс Диске`;
- `покажи файлы на Яндекс Диске`;
- `найди на Диске договор`;
- `прочитай файл /IOLA/notes/todo.txt`;
- `создай папку фото на Яндекс Диске`;
- `сделай публичную ссылку на /IOLA/report.pdf`;
- `сделай публичную ссылку и QR-код на /IOLA/report.pdf`;
- `отправь ссылку и QR-код на /IOLA/report.pdf по почте user@example.com`;
- `отправь Петрову ссылку и QR-код на папку /IOLA/reports`;
- `создай папку /IOLA/share, перенеси файлы из папки /IOLA/inbox, сделай ссылку и QR-код и отправь по почте user@example.com`;
- `сними публичную ссылку с /IOLA/report.pdf`;
- `переименуй /IOLA/a.txt в b.txt`;
- `перемести /IOLA/a.txt в /IOLA/archive/a.txt`;
- `скопируй /IOLA/a.txt в /IOLA/copy/a.txt`;
- `удали /IOLA/tmp.txt`;
- `покажи корзину Яндекс Диска`;
- `восстанови /IOLA/tmp.txt из корзины`.

### yandex-mail

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

- проверить доступ к почте;
- показать последние или непрочитанные письма;
- показать папки почты: входящие, отправленные, черновики, спам, корзина и пользовательские папки;
- показать письма из конкретной папки, например из спама, черновиков или отправленных;
- найти письмо;
- прочитать письмо по UID или номеру из последнего списка;
- при чтении по просьбе пользователя пометить письмо прочитанным;
- пометить письмо прочитанным или непрочитанным;
- отправить письмо только после явного запроса;
- ответить на письмо по UID или номеру из последнего списка;
- переслать письмо другому получателю;
- удалить письмо безопасно: переместить его в корзину, а не стирать безвозвратно.
- включить автоопрос новых писем, например каждые 5 минут;
- выключить автоопрос новых писем;
- вручную проверить новые письма через mail-watch tick;
- сохранить письмо на Яндекс Диск в Markdown;
- создать событие календаря из письма;
- добавить отправителя письма в контакты;
- найти в письме школу, детский сад или ИНН и подтянуть карточку из открытых городских слоев;
- найти адреса в письме и дать ссылки на Яндекс.Карты;
- создать локальную задачу по письму;
- отправить письмо по имени контакта из Яндекс Контактов;
- если найдено несколько однофамильцев, попросить уточнить получателя;
- если контакт найден, но email не указан, прямо сообщить об этом;
- добавить email в существующий контакт по явной просьбе пользователя.

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

Автоопрос почты использует локальный cron CLI. Он не передает письма на сервер IOLA: токены, состояние последнего UID и расписание хранятся на компьютере пользователя.

### yandex-calendar

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

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

Примеры:

- `покажи яндекс календарь`;
- `найди событие собрание в яндекс календаре`;
- `создай событие название: прием врача завтра в 10:00`;
- `перенеси встречу прием врача на послезавтра в 11:00`;
- `добавь напоминание 20 минут к событию прием врача`;
- `удали событие прием врача`.

### yandex-docs

Работать с документами Яндекс 360 через Яндекс Диск:

- показать документы в папке `/IOLA/docs`;
- найти документ по названию;
- создать текстовый, Markdown или HTML-документ;
- прочитать небольшой текстовый документ;
- создать публичную ссылку и QR-код на документ;
- переименовать документ;
- удалить документ по явной просьбе.

Важно: CLI работает с документами как с файлами на Яндекс Диске. Он не подменяет веб-редактор Яндекс Документов и не обещает создание "нативного" документа, если Яндекс не дает стабильный API для этого действия.

Примеры:

- `покажи документы на Яндекс Диске`;
- `найди документ справка на Яндекс Диске`;
- `создай документ яндекс 360 название: заметка текст: купить лекарства`;
- `прочитай документ /IOLA/docs/заметка.md`;
- `сделай ссылку на документ /IOLA/docs/заметка.md`;
- `переименуй документ /IOLA/docs/заметка.md в лекарства.md`;
- `удали документ /IOLA/docs/лекарства.md`.

### yandex-contacts

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

- проверить доступ к адресной книге;
- показать контакты;
- найти контакт по имени, email, телефону, организации, адресу или заметке;
- открыть карточку контакта;
- создать контакт с email или телефоном;
- добавить или обновить email, телефон, адрес, заметку, день рождения, организацию и должность;
- удалить email или телефон из карточки;
- удалить контакт по явной просьбе пользователя;
- найти неполные контакты: без email, телефона или адреса;
- найти дубликаты контактов;
- экспортировать контакты в vCard или CSV;
- импортировать контакты из vCard или CSV;
- сохранить резервную копию контактов на Яндекс Диск;
- создать события дней рождения в Яндекс Календаре;
- включить регулярную проверку контактов: дубликаты, неполные карточки и опциональный backup на Диск.

Примеры:

- `найди контакт Петров`;
- `создай контакт Иван Петров email ivan@example.com`;
- `добавь телефон +7 999 123 45 67 к контакту Иван Петров`;
- `добавь заметку к контакту Иван Петров заметка: родительский комитет`;
- `покажи контакты без email`;
- `покажи дубликаты контактов`;
- `экспортируй контакты в csv`;
- `сохрани резервную копию контактов на Яндекс Диск`;
- `импортируй контакты из contacts.csv`;
- `создай события дней рождения из контактов в календаре`.
- `включи регулярную проверку контактов каждые 7 дней`;
- `запусти проверку контактов сейчас`;
- `включи проверку контактов с backup на Диск`.

### yandex-contacts-combined

Комбинированные сценарии с контактами:

- отправить письмо контакту по имени;
- если найдено несколько контактов, попросить уточнить;
- если у контакта нет email, сказать прямо и не отправлять письмо;
- отправить контакту публичную ссылку и QR-код на файл или папку Яндекс Диска;
- создать папку контакта на Яндекс Диске и сохранить туда `contact.vcf` и `README.txt`;
- создать встречу с контактом в Яндекс Календаре;
- создать календарное событие для Телемоста с контактом;
- создать полный пакет контакта: папка на Диске, Markdown-документ, публичная ссылка, QR-код и встреча в календаре;
- создать контакт из открытого городского слоя, если у школы или детского сада есть публичный email или телефон.

Примеры:

- `отправь Петрову письмо текст: встреча завтра в 14:00`;
- `отправь Иванову ссылку и QR-код на /IOLA/report.pdf`;
- `создай папку на Яндекс Диске для контакта Иван Петров`;
- `подготовь полный пакет по контакту Иван Петров завтра в 15:00`;
- `создай встречу с Иваном Петровым завтра в 15:00`;
- `создай контакт из школы № 7`.

### yandex-mail-combined

Комбинированные сценарии по письмам:

- сохранить письмо на Яндекс Диск в Markdown;
- создать публичную ссылку и QR-код на сохраненное письмо;
- создать событие календаря по письму;
- пригласить отправителя письма как участника, если в отправителе есть email;
- при явной просьбе отправить отправителю ссылку и QR-код.

Примеры:

- `по письму #2382 создай пакет: сохрани на диск, сделай ссылку и событие`;
- `по самому свежему письму подготовь встречу завтра в 14:00`;
- `сохрани письмо #2382 на Диск и создай событие`.

### yandex-telemost

Подготовить встречу через Телемост:

- проверить режим Телемоста;
- попробовать создать ссылку через прямой API, если он доступен текущему аккаунту;
- если прямой API недоступен, создать календарное событие и честно сообщить, что ссылка Телемоста не была получена через API.

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

### yandex-automation

Регулярные сценарии через локальный cron:

- автоопрос новых писем;
- ежедневный дайджест: непрочитанные письма, события на 24 часа, неполные контакты, сохранение отчета на Диск;
- календарные напоминания: проверка ближайших событий;
- регулярная проверка контактов: неполные карточки, дубликаты, backup;
- аудит Яндекс Диска: место, корзина, документы и публичные ссылки в `/IOLA`.

Команды:

- `iola yandex mail-watch on --minutes 5`;
- `iola yandex daily-digest on --time 09:00`;
- `iola yandex calendar-reminders on --minutes 15`;
- `iola yandex contacts-maintenance on --days 7 --backup`;
- `iola yandex disk-maintenance on --days 7`.

## Yandex Go deeplink

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

### taxi-prepare-ride

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

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

Команды:

```bash
iola yandex go link --from "Медведево, Школьная 15" --to "Медведево, Советская 20"
iola yandex go open --from "Медведево, Школьная 15" --to "Медведево, Советская 20" --tariff econom
```

Если ключ геокодера не подключен, CLI должен объяснить, что нужно открыть `/master` и выбрать `Yandex Cloud Connector (геокодинг и YandexGPT)`, либо запустить `iola yandex cloud setup`.

Цена, повышенный спрос, детское кресло, назначение машины и отмена поездки через API ждут партнерский `clid/apikey` от Яндекса.

## Yandex Connector backlog

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

### market-prepare-cart

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

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

### delivery-prepare-order

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

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