Декларативные теги SmartApp DSL

Обновлено 20 февраля 2024

Code

Chat App

Canvas App

Теги

theme:

theme: — точка входа смартапа, в это состояние переходит система при запуске смартапа.

Тип значения

• string

Параметры

• none

Вложенные данные

• tags

Синтаксис

Объявление темы должно начинаться с символа /:

theme:/Hello

Внутрь тега theme: на первом уровне могут быть вложены только стейты.

Примеры значений

• без значения:

theme: /
    state: start
        q!: *
        a: Начинаем!

• со значением:

theme: /Start
    state: start
        q!: *
        a: Начинаем!

Значение /start — это название theme:. Указание любого значения в theme: после символа / или его отсутствие не оказывает влияния на код.

state:

state — состояние смартапа. Стейты могут иметь вложенную структуру. Название стейта может быть как на русском, так и на английском языках.

Тип значения

• string

Параметры

• noContext (boolean) — по умолчанию false. Используется для регулирования контекста при переходе из одного стейта в другой.
• modal (boolean) — по умолчанию false. Используется, когда от пользователя нужно получить важную информацию, без которой диалог не может продолжаться.

Вложенные данные

• tags

Синтаксис

Объявление стейта происходит следующим образом:

state: Hello
    state: HowAreYou

Стейты могут быть родительскими Hello и дочерними HowAreYou. Дочерним называется стейт, который расположен внутри родительского стейта.

Параметры разделяйте пробелами:

state: MyState name with space || noContext=true

Примеры использования

Простой пример использования стейтов:

state: hello
        q: *
        a: Привет!

Пример использования флага noContext=true.

Если нужно, чтобы система не поменяла контекст при переходе с помощью паттерна или интента в другой стейт, используйте флаг noContext=true.

state: Правила
    q!: $regex</start>
    a: Игра больше-меньше. Загадаю число от 0 до 100, ты будешь отгадывать. Начнем?
    go!: /Правила/Согласен?

        state: Согласен?

            state: Да
                q: * да *
                go!: /Игра

            state: Нет
                q: * нет *
                a: Ну и ладно!

state: CatchAll || noContext=true
    q: *
    a: Я не понял

Если пользователь ввел сообщение отличное от да или нет, то активируется стейт CatchAll.

Теперь поставим в этот стейт флаг noContext=true, чтобы остаться в контексте стейта Правила. Если написать боту нет, то сработает стейт /Согласен?/Нет и появится сообщение Ну и ладно!.

Без флага noContext=true пользователь не сможет перейти из стейта CatchAll в стейт Правила. Тогда если написать боту нет, он ответит Я не понял.

Пример использования флага modal=true.

Флаг modal=true не дает диалогу совершить переход из контекста модального стейта. Флаг активен на стейте, в котором он указан, и на вложенных в него стейтах на первом уровне вложенности. Запрос может попасть только в один из его вложенных стейтов. Если среди вложенных стейтов не предусмотрен ответ и отсутствует локальный CatchAll, то система выдаст ошибку.

    theme: /
        state: FlightNumber || modal = true
            q!: * (когда|прибывает*) * ~рейс *
            a: Здравствуйте! Какой у вас номер рейса?

            state: GetNumber
                q: * $Number *
                a: Ожидается прибытие рейса
                go!: /WhatElse

            state: LocalCatchAll
                event: noMatch
                a: Это не похоже на номер рейса. Попробуйте еще раз.

        state: WhatElse
            a: Чем еще я могу помочь?

        state: City
            q: * $City *
            a: Вас интересуют рейсы из города {{ $parseTree._City }}?

В этом сценарии пользователь хочет уточнить статус своего рейса, для этого от него требуется номер рейса. Флаг modal = true предотвращает выход диалога из контекста вопроса о номере рейса до получения необходимой информации.

Если в запросе пользователя указан город, а в стейте FlightNumber отсутствует флаг modal = true, то сработает стейт City. Таким образом, пользователь выйдет из сценария уточнения рейса и не получит необходимую информацию.

q!:

q!: (от англ. question — вопрос) после тега записывается паттерн. Глобальный тег, который обрабатывает запросы пользователя из любого места сценария. Этот тег работает как с паттернами, так и с примерами фраз.

Тип значения

• multiline string

Параметры

• none

Вложенные данные

• multiline data

Примеры значений

theme: /
    state:
        q!: *
        a: Здравствуй мир!

theme: /
    state: start
        q!: * *start
        a: Привет!

q:

q: — (от англ. question — вопрос ) после тега записывается паттерн. Локальный тег, переход по тегу возможен из ближайшего родительского, из любого дочернего или из соседнего стейтов. Этот тег работает как с паттернами, так и с примерами фраз.

Область срабатывания локального тега

Локальные декларативные теги срабатывают в следующих случаях:

• При переходе между стейтами, которые находятся на одном уровне и внутри одного родительского стейта. Примеры: Из стейта Розоцветные в стейт Цитрусовые и обратно. Из стейта Яблоко в стейт Груша и обратно
• При переходе из родительского стейта в дочерний, но не более чем на один уровень вложенности. Примеры: Из стейта Фрукты в стейт Розоцветные. Из стейта Розоцветные в стейт Яблоко
• При переходе из дочернего стейта в родительский на любое количество уровней. Примеры: Из стейта Яблоко в стейт Розоцветные. Из стейта Яблоко в стейт Фрукты

Локальные декларативные теги НЕ срабатывают в следующих случаях:

• При переходе из дочернего в чужой родительский стейт. Примеры: Из стейта Груша в стейт цитрусовые. Из стейта Лимон в стейт Розоцветные
• При переходе из родительского стейта в чужой дочерний. Примеры: Из стейта Розоцветные в стейт Апельсин. Из стейта Цитрусовые в стейт Груша
• При переходе из родительского стейта в дочерний на 2 и более уровней. Примеры: Из стейта Фрукты в стейт Яблоко. Из стейта Фрукты в стейт Апельсин

state: Фрукты
    q: Фрукты
    a: Выберите тип фрукта
     
    state: Розоцветные
        q: Розоцветные
        a: Выберите фрукт
         
        state: Яблоко
            q: Яблоко
            a: Это Яблоко, оно красное
         
        state: Груша
            q: Груша
            a: Это Груша, она зеленая
     
    state: Цитрусовые
        q: Цитрусовые
        a: Выберите фрукт
         
        state: Апельсин
            q: Апельсин
            a: Это Апельсин, он оранжевый
         
        state: Лимон
            q: Лимон
            a: Это Лимон, он желтый

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

Тип значения

• multiline string

Параметры

• fromState (string) — определяет стейт, из которого смартап может перейти по заданному паттерну.
• toState (string) — определяет стейт, в который перейдет смартап при определении паттерна. При использовании параметра, паттерн, заданный в теге, будет срабатывать только в контексте текущего стейта. При переходе выполняются все реакции заданного стейта (аналогично тегу go!:.
• onlyThisState (boolean) — при флаге true переход в стейт может быть совершен только из указанного в параметре fromState состояния, но не из его дочерних стейтов. По умолчанию false.

Например:

theme: /Test

    state: Как дела
        q!: как {(твои/у тебя) дел*}
        a: А ты как?

        state: Хорошо || modal = true
            q: хорошо [$andYou]
            q: супер || fromState = /Test, onlyThisState = true
            a: Ты из какого города?

Вложенные данные

• multiline data

Примеры значений

state:
    q: $Yes
    a: Я могу вам помочь?

Синтаксис

• Если тег имеет только один строковый параметр, кавычки можно опустить.

q: * $Yes *

• Параметры отделяются от значения симоволом ||.

q: * $Yes * || fromState=/theme1

• Если параметр содержит пробелы, то он должен быть заключен в кавычки.

q: * $Yes * || toState=/theme1
q: * $Yes * || toState="/theme 1"

patterns:

patterns: — после тега объявляются именованные паттерны в sc-файле, они доступны для использования во всех файлах проекта.

Иногда для удобства все именованные паттерны выносят в отдельный sc-файл.

Тип значения

• none

Параметры

• none

Вложенные данные

• named patterns — особый вид вложенных данных

Синтаксис

• Тег patterns имеет особый вид вложенных данных — список именованных паттернов. Структура тега следующая:

   patterns:
          $<pattern name> = (pattern body | multiline body)
          $<pattern name> = (pattern body) || converter=dateConverter

• Каждый вложенный элемент трактуется как определение нового именованного паттерна.

• После знака = задается значение типа multiline string с опциональным атрибутом converter, имеющим тип string.

• Для объявления и обращения к именованному паттерну используют $

  q!: $<pattern name>
  q: $<pattern name>

Подробнее о паттернах.

Примеры значений

patterns:
    $Start = $regexp</start>
    $CatchAll = *
    $Yes = (да/конечно)
    $No = (нет/не хочу)

patterns:
    $hello = (салют|привет|здравствуй*|здарова|добрый (день|вечер))

Подробнее о базовых и расширенных элементах паттернов.

event!:

event!: — реакция на различные события, происходящие в ассистенте, аккаунте или проекте. Например: начало новой сессии, нажатие на кнопку и другое. Глобальный тег, который может попасть в стейт с event!: из любого места сценария. Родробнее о локальных тегах смотрите в разделе [Как работают локальные теги].

События могут быть разных типов.

Тип значения

• string

Параметры

• fromState (string)
• toState (string)
• onlyThisState (boolean)

Вложенные данные

• none

Примеры значений

• Превышение лимита на время обработки запросов:

    state: TimeLimit
        event!: timeLimit
        a: Извините, у меня что-то сломалось. Попробуйте другой вопрос.

event:

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

События могут быть разных типов.

Тип значения

• string

Параметры

• fromState (string) — определяет стейт, из которого смартап может перейти при получении заданного события.
• toState (string) — определяет стейт, в который перейдет смартап при получении заданного события. При использовании параметра, событие, заданное в теге, будет срабатывать только в контексте текущего стейта. При переходе выполняются все реакции заданного стейта аналогично тегу go!:.
• onlyThisState (boolean) — при флаге true переход в стейт может быть совершен только из указанного в параметре fromState состояния, но не из его дочерних стейтов. По умолчанию false.

Вложенные данные

• none

Примеры значений

    state:
       event: sendFile
       a: Спасибо!

require:

require: — тег служит для загрузки зависимых файлов и, по сути, является альтернативой указанию всех зависимых файлов в chatbot.yaml.

Объявлять зависимые файлы через тег require: необходимо в main.sc. Если в проекте используется множество файлов, для удобства можно:

1. Создать отдельный файл. Например, с именем files.sc.
2. В созданном файле задать все необходимые зависимости.
3. В main.sc указать связь с созданным файлом (require: files.sc).

Тип значения

• string — задает имя подключаемого файла

Параметры

• type (string) — опциональный параметр, определяет тип файла; по умолчанию определяется из расширения.
• from (string) — имя модуля, из которого импортируется файл; версия и репозиторий модуля указываются в chatbot.yml.
• rootTheme (string) — базовая тема для всех состояний, определенных в подключаемом файле.
• provide (multiline json) — набор параметров, передаваемый подключаемому модулю.
• name (string) — имя паттерна для справочников сущностей.
• var (string) — определяет имя js-переменной с данными из справочника.
• injector (string) — через объект $injector в скрипт могут передаваться метапараметры.
• module (string) — имя модуля, из которого загружается файл.

Имя модуля задается в секции dependecies конфигурационного файла chatbot.yaml, либо соответствует имени папки в папке системных модулей.

Подробнее о работе с module

Вложенные данные

• named parametrs

Примеры значений

require: catchAll.js
require: /services/api.js

• параметр var;

 require: answers.yml
          var = answers

• параметры from, rootTheme, provide;

require: catchAll.zb
        from = common
        rootTheme = /offtopic/catchAll
        provide = {
            doSwitch: false,
            hintState: “/offtopic/IKnowSomethingElse”
            }

• параметры type, name;

require: cities.csv
         type = namedEntities
         name = $City

• параметр injector;

require: another.sc
injector = { catchAll: { useSwitch2: false } }

• параметр module;

 require: patterns.sc
    module = common

• в значениях параметров возможны подстановки.

require: {{$inject.dictFile}}
        type = namedEntities
        name = $City

init:

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

Тип значения

• multiline string (JavaScript)

Параметры

• none

Вложенные данные

• multiline data

Примеры значений

init:
    state.bind("preProcess", myModule.preProcess)
    state.bind("postProcess", function () { … } )

Как работают локальные теги

Локальные декларативные теги срабатывают в следующих случаях:

• При переходе между стейтами, которые находятся на одном уровне и внутри одного родительского стейта. Например: из стейта Розоцветные в стейт Цитрусовые и обратно; из стейта Яблоко в стейт Груша и обратно
• При переходе из родительского стейта в дочерний, но не более, чем на один уровень вложенности. Например: из стейта Фрукты в стейт Розоцветные; из стейта Розоцветные в стейт Яблоко
• При переходе из дочернего стейта в родительский на любое количество уровней. Например: из стейта Яблоко в стейт Розоцветные; из стейта Яблоко в стейт Фрукты

Локальные декларативные теги НЕ срабатывают в следующих случаях:

• При переходе из дочернего в чужой родительский стейт. Например: из стейта Груша в стейт цитрусовые; из стейта Лимон в стейт Розоцветные
• При переходе из родительского стейта в чужой дочерний. Например: из стейта Розоцветные в стейт Апельсин; из стейта Цитрусовые в стейт Груша
• При переходе из родительского стейта в дочерний на 2 и более уровней. Например: из стейта Фрукты в стейт Яблоко; из стейта Фрукты в стейт Апельсин

state: Фрукты
    event: Fruits
    a: Выберите тип фрукта
     
    state: Розоцветные
        event: Rosales
        a: Выберите фрукт
         
        state: Яблоко
            event: Apple
            a: Это Яблоко, оно красное
         
        state: Груша
            event: Pear
            a: Это Груша, она зеленая
     
    state: Цитрусовые
        event: Citrus
        event: Выберите фрукт
         
        state: Апельсин
            event: Orange
            a: Это Апельсин, он оранжевый
         
        state: Лимон
            event: Lemon
            a: Это Лимон, он желтый

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