# Плейбуки Shopping Assistant

Плейбук — сценарий консультации для типовой задачи покупателя. Он задаёт условия применения, уточнения, правила выбора товаров, структуру ответа и направления поиска.

Чтобы перевести ожидания от ассистента в настройки, пройдите [гайд по настройке плейбука](playbook_guide.md): от выбора задачи и написания инструкций до проверки ответов и исправления ошибок.

!!!warning Доступность
Раздел «Плейбуки» отображается только в секциях, где включено управление плейбуками.
!!!

## Найдите плейбук

![Каталог плейбуков демонстрационного магазина электроники](../personal_account/assets/playbooks-catalog.png)

_Названия, версии и пользователи на скриншоте демонстрационные._

В каталоге показаны название и ID, статус, текущая версия, дата и автор последнего изменения.

- Используйте строку поиска для поиска по названию или ID.
- Выберите статус **Активные** или **Выключенные**, чтобы сузить список.
- Нажмите кнопку обновления, чтобы повторно загрузить данные.
- Нажмите на строку, чтобы открыть опубликованную версию.

## Создайте плейбук

1. Нажмите **Новый плейбук**.
2. Заполните название. Кабинет автоматически предложит ID.
3. Опишите, когда применять сценарий.
4. Добавьте примеры формулировок покупателя.
5. Заполните **Как планировать**, **Как выбирать товары** и **Как отвечать покупателю**.
6. Настройте **Поиск для сценария**, доступные правила количества и разрешённые изменения оформления.
7. Нажмите **Опубликовать и включить**.

![Редактор нового плейбука для подбора рабочего места](../personal_account/assets/playbook-editor.png)

_Сценарий и товарные группы на скриншоте демонстрационные._

### Поля плейбука

| Поле | Назначение |
| :--- | :--- |
| Название | Понятное команде название сценария. |
| ID | Стабильный технический идентификатор. |
| Описание сценария | Условия и покупательская задача, для которых нужен плейбук. |
| Примеры запросов | Реальные формулировки, по которым система распознаёт сценарий. |
| Как планировать | Что выяснить до поиска, когда искать, какие источники использовать и какие допущения разрешены. |
| Как выбирать товары | Какие товары подходят, что исключить и как упорядочить подборку. |
| Как отвечать покупателю | Что сказать и в какой последовательности, как объяснить выбор и продолжить разговор. |
| Поиск для сценария | Группы запросов в каталог или доступную базу знаний. Пустой список допустим, если поиск не нужен. |
| Правила количества | Доступные ориентиры подбора с единицей и областью действия. |
| Порядок блоков, завершающий вопрос, быстрые ответы | Разрешённые для секции изменения оформления ответа с товарами. |

ID должен содержать от 3 до 64 строчных латинских букв, цифр или дефисов и начинаться с буквы или цифры. До первой публикации его можно изменить. После публикации ID фиксируется.

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

Название — до 120 символов, описание — до 1000. Добавьте от 1 до 20 примеров, каждый до 500 символов. Для планирования нужна хотя бы одна инструкция; каждый из трёх списков инструкций содержит до 20 правил по 1000 символов. Поисковых групп может быть до 30.

## Наследование правил

Плейбук работает внутри общих [настроек магазина](settings.md). Он не включает новый источник данных и не отменяет ограничения платформы. Изменять количество и оформление можно только там, где это разрешено конфигурацией секции.

Правило количества различает товары, модели и категории, а также весь ответ и отдельную группу. Не заменяйте эти настройки повторением чисел в тексте инструкций. Если подходящих товаров мало, ассистенту не следует добавлять неподходящие позиции ради заданного ориентира.

Пишите требования к консультации: «До выбора выясни бюджет», а не команды внутренним инструментам. Если требование меняет поиск или порядок уточнений, запишите его в «Как планировать»; если определяет допустимые товары — в «Как выбирать товары».

Старые версии могут содержать один общий список правил ответа. Редактор показывает его в «Как отвечать покупателю» и предупреждает о старом формате. Перед новой публикацией перенесите правила отбора в «Как выбирать товары», а правила уточнений и поиска — в «Как планировать».

## Обновите опубликованный сценарий

Опубликованные поля доступны только для чтения. Чтобы внести изменения:

1. Откройте плейбук.
2. Нажмите **Редактировать**.
3. Измените нужные поля.
4. Нажмите **Опубликовать изменения**.

Изменения становятся новой активной версией. Предыдущая версия остаётся в истории и продолжает быть доступной для просмотра.

Если уйти со страницы с неопубликованными изменениями, кабинет попросит подтвердить действие.

## Проверьте срабатывание

Проверка срабатывания доступна для активной опубликованной версии.

1. Откройте активный плейбук без режима редактирования.
2. В блоке «Проверка срабатывания» оставьте примеры из плейбука или добавьте новые запросы — по одному на строку.
3. Нажмите **Проверить запросы**.
4. Проверьте место плейбука и соседние сценарии для каждого запроса.

![Результаты проверки срабатывания плейбука на запросах покупателей](../personal_account/assets/playbook-retrieval-test.png)

_Запросы и результаты ранжирования на скриншоте демонстрационные._

Результат «Сработал первым» означает первое место. «В числе первых» — попадание в первые три результата. Если сценарий оказался ниже или не сработал, уточните описание и примеры в новой версии, опубликуйте её и повторите тест.

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

Первое место в этом тесте не подтверждает выбор сценария в каждом реальном диалоге и не оценивает ответ. После него обязательно проверьте консультацию в [«Превью»](preview.md).

## Используйте историю версий

В панели «История» отображаются все версии сценария и их состояние. Нажмите на версию, чтобы просмотреть её без редактирования.

Кнопка **Использовать как основу** копирует содержимое выбранной версии в новую редактируемую версию. Рабочий сценарий не изменится до публикации.

## Выключите плейбук

1. Откройте активную опубликованную версию.
2. В блоке «Выключение» нажмите **Выключить плейбук**.
3. Подтвердите действие.

Плейбук перестанет участвовать в подборе, но история версий сохранится. Чтобы вернуть сценарий в работу, создайте и опубликуйте новую версию.