jeyroik/extas-alice

# Extas-alice

Библиотека для создания навыков для голосового помощника Алисы от компании Яндекс.

Данная библиотека поддерживает сценарии (см. руководство ниже).

# Установка

`composer require jeyroik/extas-alice:1.*`

# Использование

Пример использования библиотеки смотрите в репозитории [alice-extas-example](https://github.com/jeyroik/alice-extas-example "Перейти к alice-extas-example")

## Реализация навыка

- Регистрируем навык в Яндекс.Диалогах (https://dialogs.yandex.ru/developer/).
- Получаем идентификатор навыка (skill_id).
- Добавялем запись о навыке в extas.json в секцию skills:
```json
"skills": [
  {
    "id": "идентификатор навыка, полученный в Яндекс.Диалогах",
    "name": "алиас навыка, по нему будет организовываться связка со сценариями",
    "description": "описание навыка, нигде не используется, заполняется только для понимания"
  }
]
```
- Добавляем в extas.json шаги, которые потребуются для навыка:
```json
"steps": [
  {
    "name": "Имя шага, по нему будут запускаться плагины (см. ниже)",
    "title": "Название шага, используется только для понимания",
    "description": "Описание шага, используется для понимания"
  }
]
```
- Добавляем в extas.json сценарии навыка:
```json
"scenarios": [
  {
    "name": "Имя сценария, используется для запуска плагинов",
    "title": "Название сценария, используется для понимания",
    "description": "Описание сценария, используется для понимания",
    "skill_name": "алиас навыка - см. skills:name",
    "schema": {
      "message_1": [{
        "condition": "имя класса для проверки условия, оставить пустым для обязателнього запуска данной реакции",
        "step": "имя шага, см. steps:name"
      }],
      "message_x": [{
        "condition": "",
        "step": "demo.help"
      }, {
        "condition": "extas\\components\\yandex\\skills\\conditions\\ConditionTest",
        "step": "demo.test"
      }]
    }
  }
]
```
    - В схеме доступны два варианта идентификаторов сообщения: 
        - N, где N - целое число, идентификатор сообщения (см. детали https://yandex.ru/dev/dialogs/alice/doc/protocol-docpage/ описание по message_id)
            - Пример: message_1, message_2
        - x - для реакции на все сообщения пользователя;
            - Пример: message_x
-  При необходимости можно также заранее прописать карточки и кнопки (см. extas.json для примера).
- Устанавливаем навык: `alice-extas# vendor/bin/extas i`
- Запускаем навык: `alice-extas# php -S 0.0.0.0:8080 -t resources `
    - См. `resources/index.php` для примера запуска. 

## Использование сценария

- Сценарий состоит из реакций.
- Реакция состоит из проверки условий и имени шага.
- Шаг состоит из имени и описания.

Шаги можно установить предварительно.

### Установка шагов

```json
{
    "steps": [
        {
          "name": "demo.help",
          "title": "Помощь",
          "description": "Пользователь запросил помощь"
        },
        {
          "name": "demo.start",
          "title": "Начало использования",
          "description": "На этом шаге приветствуем пользователя"
        }
      ]
}
```

Как видно, шаги не зависят от сценария и могут переиспользоваться.
По каждому шагу запускается следующие стадии (события):
- step.<name шага>
- <name сценария>.step.<name шага>
- <name навыка>.<name сценария>.step.<name шага>

Таким образом возможно реализовать как общую логику (и ограничения), так и персонально для каждого сценария и навыка.

### Установка сценария

```json
"scenarios": [
    {
      "name": "demo",
      "title": "Демонстрационный сценарий",
      "description": "Это демонстрационный сценарий",
      "skill_name": "test",
      "schema": {
        "message_1": [{
          "condition": "",
          "step": "demo.start"
        }],
        "message_x": [{
          "condition": "",
          "step": "demo.help"
        }]
      }
    }
  ]
```

Схема сценария может содержать следующие секции:

- `message_N`, где `N` - любое целое число, представляющее идентификатор сообщения (см. документацию по навыкам). Данная секция содержит реакции на конкретное по порядку сообщение.
- `message_x` - данная секция содержит реакции для вариативных по порядку сообщений.

Каждая реакция состоит из
- `condition` - проверка условия. Если данная реакция должна применяться всегда, поле оставляется пустым, в противном случае здесь указывается имя класса. Класс реакции должен реализовывать метод `__invoke(IAliceCall $call)` и возвращать `bool` (`true` или `false`). Если `true`, то будет запущен соответствующий реакции шаг.
- `step` - имя шага, который нужно запустить, если условия подходят.