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

Обновлено 18 июля 2024

Code

Chat App

Canvas App

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 — вопрос ) после тега записывается паттерн. Это локальный тег, переход по которому возможен из ближайшего родительского, из любого дочернего (в т.ч. из дочерних соседних стейтов) или из соседнего стейта. Подробнее — в разделе Как работают локальные теги.

Тип значения

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. Если в проекте используется множество файлов, для удобства можно:

Создать отдельный файл. Например, с именем files.sc.
В созданном файле задать все необходимые зависимости.
В 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 () { … } )

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

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

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

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

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

Тег q:

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

Тег event:

state: Фрукты
    event: Fruits
    a: Выберите тип фрукта

    state: Розоцветные
        event: Rosales
        a: Выберите фрукт

        state: Яблоко
            event: Apple
            a: Это Яблоко, оно красное

        state: Груша
            event: Pear
            a: Это Груша, она зеленая

    state: Цитрусовые
        event: Citrus
        a: Выберите фрукт

        state: Апельсин
            event: Orange
            a: Это Апельсин, он оранжевый
          
        state: Лимон
            event: Lemon
            a: Это Лимон, он желтый

Тег intent:

state: Фрукты
    intent: /Фрукты
    a: Выберите тип фрукта

    state: Розоцветные
        intent: /Розоцветные
        a: Выберите фрукт

        state: Яблоко
            intent: /Яблоко
            a: Это Яблоко, оно красное

        state: Груша
            intent: /Груша
            a: Это Груша, она зеленая

    state: Цитрусовые
        intent: /Цитрусовые
        a: Выберите фрукт

        state: Апельсин
            intent: /Апельсин
            a: Это Апельсин, он оранжевый
          
        state: Лимон
            intent: /Лимон
            a: Это Лимон, он желтый

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

Теги﻿

theme:﻿

state:﻿

q!:﻿

q:﻿

patterns:﻿

event!:﻿

event:﻿

require:﻿

init:﻿

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

Теги

theme:

state:

q!:

q:

patterns:

event!:

event:

require:

init:

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