botml
3.0.1
Botml — это декларативный и мощный язык разметки для разработки современных чат-ботов (также известных как диалоговые боты).
Любой (разработчик и неразработчик) может использовать его для создания ботов и обучения их поведению . Определите поведение вашего чат-бота, используя правильное форматирование, и мгновенно вступите в разговор. Смотрите сами: бот-калькулятор, написанный всего в две строки.
В этом проекте используются node и npm. Проверьте их, если они у вас не установлены локально.
$ npm i -g botml При этом будут установлены как пакет узла botml , так и клиент bot .
При желании, если вы используете Atom в качестве редактора, вы можете установить подсветку синтаксиса с помощью пакета language-botml .
Либо запустите командную строку:
$ botили используйте его в своем коде:
const Botml = require ( 'botml/lib/botml' )
const bot = new Botml ( 'alice.bot' )
bot . start ( )или даже загрузите его статически в браузере:
< script src =' https://unpkg.com/botml ' > </ script >
< script >
const bot = new Botml ( )
// either load an URI:
// bot.load('https://raw.githubusercontent.com/codename-co/botml/master/examples/hello.bot')
// or load the script directly:
bot . parse ( '> *n< yes?n' )
bot . start ( )
bot . send ( 'hey' )
</ script > Существующие функции делятся на два типа: базовые функции, которые удовлетворяют основные потребности бота, и расширенные функции, которые обеспечивают более широкие возможности общения.
Основные возможности:
Расширенные возможности:
Целью формата является достижение максимального результата при минимальном использовании. При правильном и минимальном наборе соглашений это может быть очень мощно.
Общий синтаксис следует трем важным соглашениям :
Самый простой файл .bot будет:
! BOTML 1
> Hello
< Hello human!
Строка спецификации необходима, чтобы сообщить Botml, что он может загрузить файл.
Это должна быть первая строка любого файла .bot .
! BOTML 1
1 означает текущую версию формата.
Комментарии могут помочь сделать ваш .bot файл более понятным.
Их можно использовать как отдельные блоки или вставлять в блоки с активными действиями.
Их нельзя использовать встроенно.
# COMMENT
Диалоги — это основная концепция любого бота. Он определяет, как могут взаимодействовать человек и бот.
Диалог должен начинаться со строки > , которая определяет, какие предложения могут активировать бота для ответа.
После этого должна быть одна или несколько строк < , определяющих ответ(ы) бота.
Эту последовательность можно повторять несколько раз вперед и назад в одном и том же блоке.
> MESSAGE
< MESSAGE
Пример:
> Hi
< Hello there. Who are you?
> *
< Nice to meet you.
Случайные ответы в диалогах заставляют бота чувствовать себя менее жестким. Отвечая человеку, бот случайным образом выбирает кандидатов для ответа. Бот может выбрать только одного из нескольких кандидатов на ответ.
> MESSAGE
< REPLY CANDIDATE #1
< REPLY CANDIDATE #2
Пример:
> Hello
< Hi there
< Howdy?
Списки полезны для объединения схожих понятий или альтернатив.
Список должен начинаться со строки = , которая определяет имя списка.
В нем должен быть хотя бы один элемент списка, но может быть и больше. Каждый элемент списка начинается с символа - .
= LIST_NAME
- LIST_ITEM
- LIST_ITEM
Элемент списка может ссылаться на другой список.
= LIST_NAME
- LIST_ITEM
- [ANOTHER_LIST]
На него можно ссылаться в строке > для ссылки на несколько вариантов входного шаблона.
На него можно ссылаться в строке < для случайной ссылки на один из элементов списка в качестве ответа.
На него можно ссылаться в ? строка (приглашение) для ссылки на несколько предопределенных вариантов.
Ссылка на список осуществляется путем заключения имени списка в скобки: [LIST_NAME] .
Пример:
= citrus
- oranges
- lemons
- grapefruits
= random_fruit
- apples
- apricots
- bananas
- [citrus]
> I like [random_fruit]
< Oh. I prefer [random_fruit].
# which is the equivalent to:
# > I like apples
# > I like apricots
# > I like bananas
# > I like oranges
# > I like lemons
# > I like grapefruits
# < Oh. I prefer apples
# < Oh. I prefer apricots
# < Oh. I prefer bananas
# < Oh. I prefer oranges
# < Oh. I prefer lemons
# < Oh. I prefer grapefruits
#
# > I like [random_fruit]
# < Oh. I prefer [random_fruit].
Списки также можно использовать в подсказках.
Подсказки — это заранее определенные быстрые ответы в ответ на конкретную ситуацию.
Их необходимо размещать после строки < в конце диалога.
Им необходимо обратиться к списку, чтобы получить доступ ко всем быстрым ответам.
Количество быстрых ответов должно быть минимальным.
= LIST_NAME
- LIST_ITEM
- LIST_ITEM
? [LIST_NAME]
Пример:
= pizza_types
- Peperroni
- Margherita
- Hawaiian
> I need a pizza
< What kind of pizza?
? [pizza_types]
Службы могут использовать конечные точки внешних API.
Сервис должен быть объявлен в отдельном блоке, начинающемся со знака @ . Он состоит из имени и конечной точки API в формате JSON (через http или https).
Он может (и в большинстве случаев должен ) принимать параметр, используя знак $ внутри своей конечной точки.
@ SERVICE_NAME ENDPOINT
Его можно использовать в ходе диалога.
Если ENDPOINT имеет знак $ , он должен принять параметр, значение которого заменит знак $ .
Результат вызова службы можно отфильтровать с помощью дополнительного ВЫХОДА. Это селектор формата /(.w)+/ .
@ SERVICE_NAME( PARAMETER )[ OUTPUT ]
Пример:
@ geo_domain http://freegeoip.net/json/$
> Where is *{domain}
@ geo_domain($domain).city
< It is running from $.
Скрипты можно использовать для оценки кода.
Язык кода зависит от языка используемого синтаксического анализатора. Парсер botml выполнен на языке Javascript, поэтому можно использовать код Javascript.
Он должен быть встроенным в диалоги, заключенные в ```.
Он может получить доступ к именованным переменным:
context.variables.get('price')$priceПример:
> It will cost you #{price} USD
< `$price / 1000`k USD is a lot!
Переменные — это способ обнаружения, форматирования, хранения и повторного использования значимой информации.
Переменную можно зафиксировать в строке > (диалоге).
Он должен быть текстовым ( $ ), числовым ( # ) или буквенно-цифровым ( * ).
Его можно использовать в < строках.
> My name is *{name}
< Nice to meet you, $name
> I am #{age} years old
< Seems that you are $age
Формат переменной: ${VARIABLE_NAME} (с ее числовыми и буквенно-цифровыми эквивалентами). Но для удобства использования формат $VARIABLE_NAME можно использовать и для текстовых, и для числовых переменных.
Специальная переменная $ всегда относится к последнему совпадающему значению диалога или результату предыдущей строки (например, результату использования службы).
Регулярные выражения можно использовать в строках > , чтобы лучше контролировать то, что обнаруживать.
Регулярное выражение должно быть заключено в / и его нельзя смешивать с базовыми выражениями.
> /^I (?:.+s)?(w+) (?:.+s)?(it|this)/
< Cool bro.
Фактически, библиотека XRegExp используется под капотом, предоставляя вам доступ к ведущим именованным захватам, встроенным комментариям и модификаторам режима.
Рабочие процессы диалогов представляют собой расширенную версию классических диалогов.
Рабочий процесс можно использовать для определения точного хода разговора.
Он должен начинаться со строки ~ , определяющей имя списка.
Только один рабочий процесс может начинаться с диалога < . Такой рабочий процесс будет активирован и использован по умолчанию, когда пользователь подключится к боту.
# grocery shopping
> I want to buy *{items}
< How many $items?
> #{count} $items
> #{count}
< There you go.
Условные ветки — это инструкции, которые направляют бота к другой части диалога на основе условий тестирования.
Условные ветки начинаются с --- и прослушивают всю введенную информацию, а затем проверяют ее во всех случаях. Каждый случай разделяется --- :
---
> first input case
< first reply
---
> second input case
< second reply
---
> last input case
< last reply
Условные переходы отлично работают с еще одной функцией, называемой контрольной точкой .
Контрольная точка — это маркер ~ CHECKPOINT_NAME в рабочем процессе, что позволяет легко вернуться к ней на более позднем этапе текущего диалога. На него можно ссылаться с помощью ~ [CHECKPOINT_NAME] , который перенаправляет поток к отметке контрольной точки:
~ ask_howdy
< Hello stranger.
~ checkpoint_name
< How are you?
> meh
< So you feel bad huh
~ [checkpoint_name]
# Example of workflow working:
# < Hello stranger.
# < How are you?
# > meh
# < So you feel bad huh
# < How are you?
# > ...
И контрольные точки , и списки делают работу с условными ветвями действительно интересной:
= mood
- good
- meh
- great
- ok
= exceptions
- fantastic
- better than ever
~ ask_howdy
< hello stranger.
~ listen_howdy
< how are you?
? [mood]
---
> meh
< So you feel bad huh
~ [listen_howdy]
---
> good
< Oh, it is not bad ;)
~ [rechecker]
---
> [exceptions]
< Seems you really cool guy!
---
> ok
< Hmm, just ok? Okay then...
---
> great
< Nice! Let's continue then...
~ rechecker
< Maybe it is more than good?
> excellent
< Much better!
Также возможно использование знака «не равно» ! в условном ветвлении :
= mood
- [bad_mood]
- [good_mood]
= bad_mood
- meh
- bad
= good_mood
- great
- ok
~ ask_howdy
< hello stranger.
~ listen_howdy
< how are you?
? [mood]
---
> ![mood]
< I asked you how you are ; please let's start over with another answer?
~ [listen_howdy]
---
> [good_mood]
< Oh, it is awesome ;)
---
> [bad_mood]
< Hmm... bye then...
Условное ветвление также хорошо работает со сценариями, если возвращается значение. Если скрипт вернет значение true , соответствующая ветка будет активирована. Если все тесты являются false условное ветвление пропустит все ветки и продолжит текущий рабочий процесс:
~ ask_for_email
> start email workflow
~ listen_email
< Your email please?
> *{email}
---
` !/^.+@.+..+/.test('$email')
< This email $email seems not legit!
~ [listen_email]
---
< Cool. We'll reach you over at $email
Триггеры — это способ интеграции бота с другой программой.
Существует два типа событий: стандартные события и пользовательские события.
Стандартные события следующие:
'start''patterns:set' с двумя строковыми параметрами: именем и значением шаблона.'match' с двумя строковыми параметрами: метка, шаблон'current-dialogue-start' с одним строковым параметром: диалогLabel'reply' с одним строковым параметром: сообщение'smart-replies' с одним параметром массива: ответы'current-dialogue-end' с одним строковым параметром: DialogueLabel'variable:set' с двумя строковыми параметрами: именем и значением переменной.'quit''*' перехватывает все стандартные и пользовательские события.Пользовательские события могут запускаться в диалогах.
Пользовательское событие должно иметь имя.
Он может иметь параметры. Параметры могут зависеть от именованных переменных.
@ trigger( 'EVENT_NAME' [, PARAMETER] )
Пример:
> hello
< hi
@ trigger('said_hi')
Затем обработайте событие «said_hi» в своем коде в соответствии с вашими потребностями:
bot . on ( 'said_hi' , ( ) => console . log ( 'The bot said hi' ) ) ; TokensRegex — это платформа для определения расширенных шаблонов, основанных на априорной обработке естественного языка, такой как именованные объекты и тегирование частей речи.
> ([ner: PERSON]+) /was|is/ /an?/ []{0,3} /painter|artist/
< An accomplished artist you say.
Эта функция активируется посредством интеграции кода. См. пример.
НЛП можно включить посредством интеграции кода. См. пример.
См. каталог examples/ .
Запустите модульные тесты с помощью:
npm test
npm run autotest # this is for continuous testingИспользуйте CLI для запуска скриптов botml из консоли:
node lib/cli.js
node lib/cli.js examples/echo.bot # load script from a local file
debug=true node lib/cli.js # add logging verbosityВ режиме CLI несколько специальных команд также могут помочь в отладке:
Смело ныряйте! Откройте проблему или отправьте PR.
Botml имеет лицензию MIT.
