Делаем навык для Алисы. Alice-ktx

Alice-ktx — это библиотека на Kotlin, упрощающая разработку навыков Алисы из Яндекс.Диалогов. В этой статье мы рассмотрим основные возможности библиотеки.

Установка

Для начала, добавьте библиотеку в зависимости вашего проекта

dependencies {     implementation("io.github.danbeldev:alice-ktx:0.0.3") }

Первый навык, Эхо‑бот

fun main() {     skill {         id = "..."         webServer = ktorWebServer {             port = 8080             path = "/alice"         }          dispatch {             message({ message.session.new }) {                 response {                     text = "Привет!"                 }             }              message {                 response {                     text = message.request.command.toString()                 }             }         }     }.run() }

• id — Уникальный идентификатор скилла, читайте здесь.

• webServer — Конфигурация приложение с использованием Ktor.

• port — Порт, на котором будет запущено приложение. В данном случае используется порт 8080.

• path — Путь, по которому приложение будет доступен. В данном случае это /alice.

message({ message.session.new }) {     response {         text = "Привет!"     } }

Этот блок кода обрабатывает новые сессии. Если сессия новая message.session.new, то в ответ отправляется текст «Привет!».

message {     response {         text = message.request.command.toString()     } }

Этот блок кода обрабатывает все остальные сообщения. В ответ отправляется текст запроса пользователя.

Мидлвари

Мидлварь — это код, который активируется при каждом событии, полученном от API Алисы.

Есть два типа Мидлвари

1. Внешняя (outer) область — вызывается перед обработкой фильтров (innerMiddleware).

2. Внутренняя (inner) область — вызывается после обработки фильтров, но перед обработчиком (outerMiddleware).

Мидлварь должен всегда возвращать null чтобы передать событие следующему мидлварю/хэндлеру. Если вы хотите завершить обработку события, вы должны вернуть Response.

Пример

dispatch {   // ...   outerMiddleware {     if(message.session.user?.userId == null)         response { text = "У вас нет аккаунта в Яндексе." }     else         null   }   // ... }

Обработка исключений

responseFailure — это расширение для Dispatcher, которое позволяет обрабатывать ошибки, возникающие при выполнении запросов. Оно предоставляет возможность задать обработчики ошибок для различных типов исключений и условий.

responseFailure должен всегда возвращать null чтобы передать событие следующему хэндлеру. Если вы хотите завершить обработку события, вы должны вернутьResponse.

Пример

• Обработка конкретного исключения.

responseFailure(ArithmeticException::class) {     response {         text = "Произошла арифметическая ошибка"     } }

• Общий обработчик исключений.

responseFailure {     response {         text = "Произошла ошибка"     } }

• Обработка ошибок по условию.

responseFailure({ message.session.new }) {     response {         text = "В начале сессии произошла ошибка"     } }

Dialog API

Чтобы получить, загрузить и удалить загруженные изображения и звуки, надо передать OAuth Token при создании DialogApi.

skill {     // ...     dialogApi = ktorYandexDialogApi {         oauthToken = "..."     }     // ... }.run()

Для каждого аккаунта Яндекса на Диалоги можно загрузить не больше 100 МБ картинок и 1 ГБ аудио. Чтобы узнать, сколько места уже занято, используйте этот метод.

dialogApi.getStatus()

Все доступные методы API.

interface DialogApi {     suspend fun getStatus(): Response<Status>      suspend fun uploadImage(url: String): Response<ImageUpload>     suspend fun uploadImage(file: File): Response<ImageUpload>     suspend fun getAllImages(): Response<Images>     suspend fun deleteImage(id: String): Response<Unit>      suspend fun uploadSound(file: File): Response<SoundUpload>     suspend fun getAllSounds(): Response<Sounds>     suspend fun deleteSound(id: String): Response<Unit> }

Все методы API возвращают обёртку Response<>.

sealed interface Response<T> {     data class Failed<T>(val message: String): Response<T>     data class Success<T>(val data: T): Response<T> }

Машина состояний

Не вся функциональность навыка может быть реализована в одном хэндлере. Если вам нужно получить некоторую информацию от пользователя в несколько шагов или нужно направить его в зависимости от ответа, то вам надо использовать FSM.

Для начала определите возможные состояния в вашем навыке

enum class InfoState {     SET_NAME,     SET_AGE,     SET_INFO }

Начальное Состояние, когда начинается новая сессия, установите начальное состояние

message({ message.session.new }) {     state.setState(InfoState.SET_NAME.name)     response {         text = "Добро пожаловать в навык, как вас зовут?"     } } 

• Условие: Обрабатывается при начале новой сессии.

• Действие: Устанавливает состояние в SET_NAME и запрашивает у пользователя имя.

После получения имени от пользователя, сохраняем его и переходим к следующему состоянию.

message({ state == InfoState.SET_NAME.name }) {     val username = message.request.originalUtterance.toString()     state.updateData("name" to username)     state.setState(InfoState.SET_AGE.name)     response {         text = "Рад познакомиться $username, сколько вам лет?"     } } 

• Условие: Обрабатывается, если текущее состояние SET_NAME.

• Действие: Сохраняет имя в состоянии, устанавливает следующее состояние SET_AGE, и запрашивает возраст.

После получения возраста от пользователя, сохраняем его и переходим к последнему состоянию.

message({ state == InfoState.SET_AGE.name }) {     val age = message.request.originalUtterance.toString()     state.updateData("age" to age)     state.setState(InfoState.SET_INFO.name)     response {         text = "Супер, расскажите о себе"     } } 

• Условие: Обрабатывается, если текущее состояние SET_AGE.

• Действие: Сохраняет возраст в состоянии, устанавливает следующее состояние SET_INFO, и запрашивает дополнительную информацию.

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

message({state == InfoState.SET_INFO.name}) {     val info = message.request.originalUtterance.toString()     val data = state.getData()     state.clear()     response {         text = "Вот что мне удалось узнать\n\nИмя-${data["name"]}\nВозраст-${data["age"]}\nИнформация-$info"         endSession = true     } } 

• Условие: Обрабатывается, если текущее состояние SET_INFO.

• Действие: Формирует текст ответа на основе собранной информации, очищает состояние и завершает сессию.

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

  Кнопки и альбомы

  Для того чтобы добавить кнопку используйте метод button.

response {     text = "Выберите тип"     SchedulesType.entries.forEach {         button {             text = it.name             payload = mapOf("schedule_type" to it.name)         }     } }

Существует три типа альбомов

• Card Items List.

response {     text = "CARD ITEMS LIST"     cardItemsList {         header = "HEADER"         repeat(10) { index ->             item {                 imageId = IMAGE_ID                 title = "#${index + 1}"             }         }         footer {             text = "Footer text"             mediaButton {                 text = "Click"             }         }     } }

• Card Big Image.

response {     cardBigImage {         imageId = IMAGE_ID         title = "CARD BIG IMAGE"         mediaButton {             text = "Open url"             url = "https://ya.ru"         }     } }

• Card Image Gallery.

response {     cardImageGallery {         repeat(10) { index ->             item {                 imageId = IMAGE_ID                 title = "#${index + 1}"             }         }     } }

Полезные ссылки

• Alice-ktx

• Документация

• Примеры