Перейти к содержанию

Структуры

В данном разделе описаны основные компоненты и интерфейсы библиотеки.

Director entities

Director - режиссёр

Director обрабатывает ответы пользователя и возвращает информацию о следующей сцене.

type Director interface {
    PlayScene(command SceneRequest) Result
}
PlayScene

PlayScene принимает запрос от голосового помощника и возвращает информацию о следующей сцене, реплике голосового помощника.

SceneDirector - сценический режиссёр

SceneDirector реализует эту функцию для подхода на основе сценария. В нём есть четыри основных компонента:

  • Обработка начала сценария(команда OnStart от голосового помощника Маруся), который запускает процесс "отыгрывания" начальной сцены
  • Обработка точки выхода (нажатия кнопки выхода или команду OnInterrupt от голосового помощника Маруся), которая вызывает сцена прощания и завещает работу скилла
  • Обработка ошибки при не соответствии команды пользователя набору правил проверки его ввода
  • Обработка обычной сцены при обработанной команде пользователя

Также его работу можно описать в виде 3 этапов: * Вызов у текущей сцены функции реагирования на ввод пользователя * Получения следующей сцены у текущей сцены * Получения информации о новой текущей сцене

В эту цепочку действий может вклиниться сохранения состояния определённой сцены и замены её на другую с помощью команды StashScene и обратный процесс с помощью команды ApplyStashedScene. Подробнее о работе данных команд можно прочитать в разделе "Дополнительно".

SceneRequest

SceneRequest - это запрос, отправленный голосовым помощником скиллуб

type SceneRequest interface {
    Command      string
    FullUserText string
    WasButton    bool
    Payload      json.RawMessage
    Info         UserInfo
}
Command

Очищенный голосовым помощником ввод пользователя.

Важно

Именно на этот ввод пользователя применяются наборы правил проверки пользовательского ввода.

FullUserText

Не очищенный ввод пользователя до 1024 символов.

WasButton

Информирует о том была ли нажата кнопка или пользователь ввёл или сказал ответ.

Payload

Метаданные, которые можно добавлять в описания кнопки и получать в случае нажатия на неё пользователя.

Info

Информация о текущем пользователе. О UserInfo cм. ниже.

UserInfo

Информация о текущем пользователе.

type UserInfo struct {
    UserID   string
    SessionID string
}
UserId

Идентификатор текущего пользователя.

SessionID

Сессия пользователя в голосовом помощнике.

hint

У одного пользователя может быть несколько сессий

Result

Информация о реплике голосового помощника из следующей сцены.

type UserInfo struct {
    Text          Text
    Buttons       []Button
    IsEndOfScript bool
}
Text

Текстовая часть реплики. Text описан ниже.

Buttons

Доступные для пользователя кнопки. Button описан ниже.

IsEndOfScript

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

SceneDirectorConfig

Информация о сценарии.

type SceneDirectorConfig struct {
    StartScene   Scene
    GoodbyeScene Scene
    EndCommand   string
}
StartScene

Стартовая сцена, с которой начинается сценарий. О Scene см. ниже.

GoodbyeScene

Сцена прощания, вызываемая при выходе из скилла. О Scene см. ниже.

EndCommand

Текст кнопки выхода, которая будет показываться в каждой сцене.

Scene entities

Command

Command - это команда, которую должен исполнить director, после обработки реакции ввода пользователя. Поддерживаются следующие команды:

  • NoCommand - ничего не делать
  • ApplyStashedScene - заменить текущую сцену, на сцену из вершины стека сохранённых сцен
  • FinishScene - завершить "отыгрывать" сценарий и отослать команду голосовому помощнику о завершении работы скилла
  • StashScene - сохранить текущую сцену в стэк сохранённых сцен, и перейти на следующую сцену

Button

Button - это описания кнопки, которая показывается голосовым помощником после его реплики и которую пользователь может нажать.

type Button struct {
    Title   string
    URL     string
    Payload interface{}
}
Title

Название кнопки, которое будет отображаться пользователю и которое вернётся при нажатии на кнопку.

URL

Ссылка для перехода при нажатии на кнопку.

Payload

Метаданные, которая будет возвращена, если будет нажата эта кнопка.

Text

Text - это описания реплики голосового помощника в сцене.

type Text struct {
    BaseText     string
    TextToSpeech string
}
BaseText

Текст реплики, который будет выведен на экран.

TextToSpeech

Текст реплики, который будет произнесён голосовым помощником. О формате TTS можно посмотреть на сайте Маруси.

Info

Info - это описание сцены для режиссёра, director.

type Info struct {
    Text             Text
    Buttons          []Button
    ExpectedMessages []MessageMatcher
    Err              Error
}
Text

Текста реплики сцены. О Text см. выше.

Buttons

Кнопки которые надо показать в сцене. О Button см. выше.

ExpectedMessages

Наборы правил проверки пользовательского ввода. О MessageMatcher см. ниже.

Err

Ошибка на подходящий под набор правил сцены ввод пользователя. О Error см. ниже.

MessageMatcher

MessageMatcher - это интерфейс описывающий набор правил для пользовательского ввода.

type MessageMatcher interface {
    Match(message string) (isMatch bool, searchedString string)
    GetMatchedName() string
}
Match

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

  • message - строка с пользовательским вводом
  • isMatch - индикатор соответствия правилам полученной строки.
  • searchedString - вся строка или её часть соответствующая набору правил.
GetMatchedName

Возвращает некоторый уникальный с помощью, которого можно определить этот набор правил.

Библиотека предоставляет следующие стандартные наборы правил:

  • NumberMatcher - получает из ввода пользователя любое целое число
  • PositiveNumberMatcher - получает из ввода пользователя любое положительное целое число
  • AnyMatcher - принимает любой ввод пользователя
  • FirstWordMatcher - получает первое слово из ввода пользователя
  • Agree - проверяет, что пользователь указал команду согласия (Точно, Согласен, Да, Ага)
  • PositiveNumberInWordsMatcher - получает из ввода пользователя любое положительное целое число сказанное словами. Для работы требуется загрузка конфига локализации

hint

Про использование набора правил можно посмотреть в разделе "Дополнительно".

Error

Error - это интерфейс описывающий ошибку при неудовлетворению набору правил.

Поддерживаются два вида правил: * Текстовые - выведется текст вместо текста текущей сцены, но с наборами правил и кнопками текущей сцены. * Сцена - текущая сцена будет застешена, а вместо неё будет вызвана сцена ошибки.

hint

При работе с ошибкой-сценой для возвращения к сцене, на который была вызвана ошибка, надо вернуть команду ApplyStashedScene

type Error interface {
    GetErrorText() string
    GetErrorScene() Scene
    IsErrorScene() bool
}
GetErrorText

Получить текст ошибки.

GetErrorScene

Получить сцену ошибки. О Scene см. ниже.

IsErrorScene

Узнать является ли эта ошибка сценой.

Scene

Scene - это интерфейс описывающий функции работы со сценой. 

type Scene interface {
    GetSceneInfo(ctx *Context) (sceneInfo Info, withReact bool)
    React(ctx *Context) Command
    Next() Scene
}

GetSceneInfo

Возвращает информацию о сцене.

  • ctx - контекст сценария, с текущим запросом от голосового помощника и состоянием сценария. О Context cм. ниже.
  • sceneInfo - информация о сцене.
  • withReact - указывает есть ли у этой сцены реакция. Если значение false значит сценра информационная. См. про информационные сцены в разделе "Дополнительно"
React

Обрабатывает ввод пользователя.

  • ctx - контекст сценария, с текущим запросом от голосового помощника и состоянием сценария. О Context cм. ниже.
  • Command - команда текущей сцены.
Next

Возвращает следующую сцену.

Context

Context - контекст сценария с текущим запросом от голосового помощника. 

type Context struct {
    context.Context
    Request Request
    Info    UserInfo
}

context.Context

Состояние сценария, общее для всех сцен сценария у текущего режиссёра.

Info

Можно передавать через него значения между сценами

Request

Запрос от голосового помощника после проверке ввода на наборе правил. О Request см. ниже.

Info

Информация о текущем пользователе. О UserInfo cм. выше.

Request

Request - контекст сценария с текущим запросом от голосового помощника.

type Request struct {
    SearchedMessage string
    NameMatched     string
    FullMessage     string
    WasButton       bool
    Payload         json.RawMessage
}
SearchedMessage

Текст который соответствовал какому-то из наборов правил.

NameMatched

Идентификатор набора правил.

FullMessage

Не очищенный ввод пользователя до 1024 символов.

WasButton

Информирует о том была ли нажата кнопка или пользователь ввёл или сказал ответ.

Payload

Метаданные, которые можно добавлять в описания кнопки и получать в случае нажатия на неё пользователя.

Marusia entities

ScriptRunner

ScriptRunner - интерфейс описывающий хаб, который должен обеспечивать каждого пользователя своим режиссёром. Является в каком-то смысле "движком" сервера, т.к. он обрабатывает сценарии для каждого пользователя, обеспечивая изоляцию состояний сценария между разными пользователями.

type ScriptRunner interface {
    AttachDirector(sessionIDstring, op Director)
    RunScene(req marusia.Request) (res chan PlayedSceneResult)
}
AttachDirector

Взять в обработку режиссёра для указанного пользователя.

  • sessionId - идентификатор сессии пользователя
  • op - режиссёр, Director
RunScene

Выполнить сцену для указанного запроса.

  • req - запрос от голосового помощника.
  • res - канал куда будет отправлен результат обработки запроса, после выполнения последней. О PlayedSceneResult см. ниже.
ScriptHub

ScriptHub - реализация интерфейса ScriptRunner, предоставленная в данной библиотеке.

PlayedSceneResult

PlayedSceneResult - результат обработки запроса голосового помощника в ScriptRunner.

type PlayedSceneResult struct {
    Result
    WorkedDirector ClosedDirector
}
Result

Результат обработки сцены.

ClosedDirector

Интерфейс для оповещения ScriptRunner о том, что для текущего пользователя следует отозвать режиссёра.

type ClosedDirector interface {
    Close()
}

Комментарии