Зависимости

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

• Благодаря модульной архитектуре проект легче разрабатывать и поддерживать.
• Одну зависимость можно использовать во множестве разных проектов.

Зависимости можно подключить двумя способами:

• Как локальные модули. Код локальных модулей хранится в том же проекте, что и основной сценарий.
• Как внешние зависимости из удаленных репозиториев.

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

Локальные модули

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

Конфигурация

Зависимости указываются в разделе dependencies конфигурационного файла chatbot.yaml. Для локальных модулей должны быть указаны поля:

Структура проекта

Предположим, что имеется существующий проект, состоящий из двух файлов:

• main.sc — основной сценарий.
• offtopic.sc — «болталка» бота: ответы на часто задаваемые вопросы не по теме.

Пример файла offtopic.sc:

patterns:
    $you = (~ты/~вы)

theme: /

    state: WhatCanYouDo
        q!: * {~что * [$you] * (~уметь/научил*/способ*)} *
        q!: * ([~что] $you/что-то) [еще] * (уме*/мож*/научил*/способ*) [делать] *
        q!: * как* * $you * [поставлен*/установлен*] (сервис*/программ*) *
        a: Я умею отвечать на вопросы.

Структура директории проекта имеет следующий вид:

├── chatbot.yaml
├── src
│   ├── main.sc
│   └── offtopic.sc
└── test
    └── test.xml

Если «болталку» планируется расширять новой функциональностью, например специализированной темой о вымышленной биографии бота или своими функциями для обработки данных, целесообразно вынести ее в отдельный модуль, независимый от основного сценария.

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

├── main
│   ├── chatbot.yaml
│   ├── src
│   │   └── main.sc
│   └── test
│       └── test.xml
└── offtopic
    └── src
        └── offtopic.sc

В зависимостях не требуется наличие конфигурационного файла chatbot.yaml и XML-тестов.

Подключение зависимости

1. Перейдите в меню редактирования проекта. На вкладке Размещение смените значение поля Путь на название новой корневой директории проекта — main.

   Если поле Путь не отображается на вкладке, обратитесь к своему аккаунт-менеджеру.

2. Укажите в chatbot.yaml раздел dependencies, если его еще нет. Добавьте зависимость с типом module и именем, соответствующим названию новой директории:

   dependencies:
     - name: offtopic
       type: module

3. В файле main.sc импортируйте нужный файл из зависимости при помощи тега require:

   require: offtopic.sc
       module = offtopic
   
   theme: /
   
       state: You
           q!: * $you *
           a: Я понял, что вы ко мне обратились, но не понял, зачем.
   
       state: CatchAll
           q!: *
           a: Извините, я вас не понял.

Теперь в основном сценарии доступно содержимое подключенного файла: стейт WhatCanYouDo и именованный паттерн $you.

Внешние зависимости

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

Конфигурация

Зависимости указываются в разделе dependencies конфигурационного файла chatbot.yaml. Для внешних зависимостей должны быть указаны поля:

Поля loginSecretKey и tokenSecretKey нужны только в том случае, если зависимость размещена в приватном репозитории. Также учитывайте следующие требования:
1. В качестве значения tokenSecretKey нельзя использовать пароль от учетной записи. Вместо него вам нужно выпустить персональный токен с доступом на чтение нужного репозитория. Подробнее о том, как получить токен в Bitbucket, GitHub и GitLab.
2. Для безопасности ваших данных ни логин, ни токен нельзя записывать непосредственно в chatbot.yaml. Вместо этого их нужно хранить в хранилище токенов JAICP. В качестве значений loginSecretKey и tokenSecretKey используйте названия токенов, где хранятся нужные значения.

Структура проекта

Рассмотрим пример файла offtopic.sc, приведенный выше.

1. Создайте директорию под новый репозиторий.

2. В ней создайте поддиректорию src, в которую поместите offtopic.sc:

   └── src
       └── offtopic.sc

3. Создайте в корневой директории Git-репозиторий и зафиксируйте изменения.

4. Опубликуйте репозиторий на любом внешнем хостинге, например Bitbucket, GitHub или GitLab.

Подключение зависимости

1. Если репозиторий с кодом зависимости приватный, перейдите в раздел Токены и переменные и создайте два токена под логин и персональный токен: например, GITHUB_LOGIN_SECRET и GITHUB_TOKEN_SECRET.

2. Укажите в chatbot.yaml раздел dependencies, если его еще нет. Добавьте зависимость с типом git и параметрами подключения к репозиторию:

   dependencies:
     - name: offtopic
       type: git
       url: https://github.com/example/offtopic
       version: master
       # Если репозиторий приватный:
       loginSecretKey: GITHUB_LOGIN_SECRET
       tokenSecretKey: GITHUB_TOKEN_SECRET

3. В файле main.sc импортируйте нужный файл из зависимости при помощи тега require:

   require: offtopic.sc
       module = offtopic

Теперь в основном сценарии доступно содержимое подключенного файла.

Вы можете просмотреть код подключенных к проекту внешних зависимостей через редактор кода.