Инструкция по сборке

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

1. Базовые принципы проектирования

Точка входа (Entry Point)

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

Исключение: Вспомогательные (модульные) сценарии, которые вызываются исключительно через реакцию «Переход», могут не иметь триггеров на первом шаге.

Обработка ответов и ветвление

Для обработки ответов пользователя и создания ветвлений на любом шаге сценария необходимо добавить соответствующие триггеры.

Всегда предусматривайте Fallback-логику На каждом шаге, где ожидается ввод от пользователя, обязательно добавляйте триггер «Прочее» (Fallback). Он обрабатывает все случаи, которые не соответствуют другим триггерам на этом шаге (нераспознанные фразы, неожиданные интенты). Это гарантирует, что бот не перестанет отвечать и корректно обработает любую ситуацию.

Глобальные переходы (триггер «Выход»)

Триггер «Выход» позволяет перехватить управление и перейти в другой сценарий, даже если текущий сценарий ожидает другого ответа. Это полезно для обработки глобальных команд, таких как «Помощь» или «Спасибо».

Опасность зацикливания: Неправильное использование триггера «Выход» может привести к бесконечным циклам между сценариями. Тщательно тестируйте эту логику.

2. Ключевые архитектурные паттерны

Модульные сценарии

Для повторяющейся логики (например, авторизация, сбор обратной связи, перевод на оператора) создавайте отдельные, модульные сценарии. Вызывайте их из других сценариев с помощью реакции «Переход».

Преимущества модульности:

• DRY (Don't Repeat Yourself): Избегание дублирования кода.

• Централизованное управление: Для изменения логики достаточно отредактировать один сценарий, и изменения применятся везде.

• Читаемость: Основные сценарии не перегружаются вспомогательной логикой.

Безопасный перевод на оператора

Перевод на оператора всегда должен завершаться реакцией «Стоп». Она отправляет команду terminate, которая формально завершает сессию бота и передает управление.

Для стандартизации этого процесса рекомендуется выносить логику перевода (включая сообщение о переводе и саму реакцию «Стоп») в отдельный модульный сценарий.

3. Жизненный цикл сценария

Управление сценариями включает в себя три основных действия:

• Клонирование: Используйте для безопасного тестирования новых гипотез, сниппетов или логики, не затрагивая рабочую версию сценария.

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

• Удаление: Полностью удаляет сценарий. Используйте с осторожностью во время плановых чисток проекта.

Рассинхронизация интента и сценария: Если заархивировать сценарий, но оставить его интент на первом шаге активным, NLU-модель распознает интент, но не найдет сценария для его обработки. Это приведет к тому, что бот не ответит.

4. Стандартные сниппеты проекта

Многие проекты используют стандартный набор сниппетов для решения типовых задач.

• check_if_first_message: Обычно размещается в начале сценария «Старт». Определяет, является ли сообщение первым в диалоге, и отправляет приветствие. Может содержать логику подавления повторных приветствий.

• was_terminated: Проверяет, был ли диалог недавно переведен на оператора. Помогает избежать повторных переводов, если пользователь пишет сразу после завершения разговора со специалистом.

• Distributor: Сниппет для предварительной обработки текста. Может использоваться для очистки сообщения от спецсимволов или для маршрутизации запроса в зависимости от его содержимого.

• snippet_language: Определяет язык сообщения (например, латиницу). Позволяет отфильтровывать сообщения на языках, для которых не настроена логика.

5. Тестирование и отладка

Дебаг-чат — ваш основной инструмент. Перед каждым релизом тщательно проверяйте все изменения в дебаг-чате. Это помогает выявить:

• Конфликты триггеров (один интент используется в нескольких активных сценариях).

• Пропущенные реакции (например, забыли добавить «Стоп»).

• Ошибки в логике сниппетов.

• Некорректную работу заархивированных компонентов.