Как AI показывает элементы на сайте

Коротко

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

Надежная связь строится из трех частей: элемент виден на текущем экране, у него есть понятное название или стабильный data-ai-context-id, а в документации есть человеческая фраза с таким же ключом. Если точной связи нет, путь объясняется словами, без вида, что действие уже выполнено.

Как работает выбранный элемент

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

Для ответа учитываются:

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

Контекст страницы задает сайт: при инициализации виджета и при переходах внутри SPA. В кабинете Senler AI заголовок страницы выставляется по текущему разделу, поэтому подпись открытого места становится понятнее. На внешнем сайте для той же пользы задавайте осмысленный <title> и понятные названия ключевых элементов.

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

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

У повторяющихся строк и карточек выбранный объект должен иметь отдельный идентификатор сущности. Тогда подсветка или действие относится именно к выбранной строке; если на экране несколько одинаково размеченных строк и различить их нельзя, произвольное действие не выполняется.

Ограничения и точный формат контекста для разработчиков описаны в статье site-actions/widget-public-api.md.

Быстро спросить AI об элементе

В интерфейсе диалогов размеченные элементы могут показывать действие "Спросить ИИ". На компьютере оно появляется при наведении, на сенсорном устройстве - при удержании элемента. Действие открывает ассистента и передает выбранный элемент как контекст.

Для пользователя это короткий путь к вопросу "что это за элемент?" или "что с ним делать?". Ответ должен быть именно про выбранное место: с учетом его названия, раздела страницы и связанной статьи, без подмены похожей кнопкой или полем.

Если у элемента есть только data-ai-label без стабильного data-ai-context-id, в сообщении все равно будет понятное название. Этого обычно достаточно для объяснения, но хуже для надежной подсказки на экране, прокрутки или изменения элемента.

Поддерживаемые атрибуты

data-ai-area - крупная область: sidebar, content, header, modal, form, navigation.
data-ai-section - раздел внутри области: project-navigation, dialog-chat, billing-settings.
data-ai-label - человекочитаемое название элемента.
data-ai-kind - тип элемента: button, field, menu-item, dialog-list-item.
data-ai-action - действие: open, save, delete, upload, buy.
data-ai-context-id - стабильный ключ для связи с документом базы знаний.
data-ai-kb-doc-id - прямой ID документа базы знаний, не используйте для этой MD-документации Senler AI: UUID файла создается при загрузке и нестабилен.
data-ai-kb-query - поисковая подсказка для базы знаний.
data-ai-entity-type - тип бизнес-сущности.
data-ai-entity-id - ID бизнес-сущности.
data-ai-reveals-context-id - один или несколько корней контекста, которые становятся доступны после раскрытия элемента; несколько значений разделяются пробелами.
data-ai-reveal-action - способ раскрытия: click, hover или focus; если атрибут не задан, используется click.

Ограничения длины значений:

label - до 180 символов;
kind - до 80;
action - до 120;
url - до 500;
title - до 180;
area - до 80;
section - до 120;
context_id - до 120;
kb_doc_id - до 80;
kb_query - до 240;
entity_type - до 80;
entity_id - до 120;
reveals_context_id - до 2000 символов вместе со всеми корнями.

data-ai-section сам по себе не делает контейнер выбираемым. Чтобы элемент выбирался, добавьте data-ai-label, data-ai-kind, data-ai-action, data-ai-context-id, data-ai-kb-doc-id или data-ai-kb-query.

Пример

<aside data-ai-area="sidebar" data-ai-section="project-navigation">
  <button
    data-ai-label="Добавить канал"
    data-ai-kind="button"
    data-ai-action="open"
    data-ai-context-id="cabinet.channels.list.add"
    data-ai-kb-query="как добавить канал"
  >
    Добавить канал
  </button>
</aside>

Как связать скрытый элемент с кнопкой раскрытия

В документации указывайте смысловую цель, а не разные пути для узкого и широкого экрана. Например: «В меню проекта откройте „Агенты“». Если меню уже видно, AI и генератор скриншотов сразу найдут нужный пункт. Если меню свернуто, сначала будет показана кнопка, которая его раскрывает, а затем сам пункт.

Общие компоненты кабинета для меню, окон, боковых панелей, popover, select, вкладок, accordion, collapsible, menubar, hover-card и tooltip сами связывают переключатель с размеченными целями внутри своего содержимого. Обычные связи aria-controls, popovertarget, commandfor и <details>/<summary> тоже поддерживаются. Если содержимое открывается программно или находится внутри отдельного компонента и его нельзя определить заранее, явно укажите корень раскрываемого контекста:

<button
  data-ai-context-id="cabinet.navigation.sidebar.toggle"
  data-ai-label="Открыть меню"
  data-ai-reveals-context-id="cabinet.navigation.project-sidebar"
  data-ai-reveal-action="click"
>
  Открыть меню
</button>

Такой корень охватывает и дочерние элементы: кнопка из примера раскрывает cabinet.navigation.project-sidebar.agents, cabinet.navigation.project-sidebar.channels и другие пункты этой ветки. Если один элемент раскрывает более узкую ветку, используется самое точное совпадение.

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

Связь с базой знаний

Если в документе базы знаний фраза размечена как <span data-ai-context-id="cabinet.channels.list.add">Добавить канал</span>, а на элементе стоит такой же data-ai-context-id, выбранное место связывается с нужным документом.

data-ai-kb-query полезен, когда прямого документа нет, но есть хорошая поисковая фраза.

data-ai-kb-doc-id не подходит для загружаемой MD-документации Senler AI, потому что ID файла базы знаний создается после импорта. Для этой базы используйте связку inline data-ai-context-id в Markdown + такой же data-ai-context-id на элементе + data-ai-kb-query как текстовый fallback.

Действия с элементом страницы

Для элементов кабинета Senler AI, iframe диалогов и клиентских сайтов автоматическое действие стоит выполнять только по явному запросу пользователя: подсветить, прокрутить, сфокусировать, нажать, заполнить, очистить, выбрать или переключить.

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

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

Например, чтобы создать агента, инструкция содержит только раздел «Агенты» в меню проекта и кнопку создания агента. Кнопка открытия свернутого меню определяется по связи раскрытия и добавляется в фактический путь только тогда, когда она действительно нужна. Если точного элемента или связи раскрытия нет на текущем экране, маршрут объясняется словами.

Карточка действия сайта в диалоге

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

Статусы:

готово - страница подтвердила выполнение;
не найдено - элемент не найден на текущем экране;
заблокировано - действие нельзя выполнить автоматически;
ошибка - действие завершилось ошибкой;
выполняется - результат от страницы еще не пришел.

Если карточка показывает "не найдено", проверьте текущую страницу и наличие нужного data-ai-context-id на элементе. Если долго остается "выполняется", страница могла не вернуть результат вовремя. Не считайте действие выполненным, пока карточка не показывает успешный статус.

Диагностика

Если выбранный элемент не помогает найти ответ:

Проверьте, включен ли выбор элемента в настройках виджета.
Проверьте, что элемент реально выбираемый, а не только контейнер с data-ai-section.
Проверьте наличие data-ai-label или data-ai-context-id.
Проверьте, есть ли документ базы знаний с таким контекстным ключом.
Добавьте data-ai-kb-query, если база знаний плохо находит нужный документ.
Если действие "Спросить ИИ" не появляется, проверьте, что это не поле ввода и у элемента есть понятное название или стабильный ключ.

Где это в интерфейсе

Основные элементы раздела:

кнопка добавления канала
кнопка открытия свернутого меню
пункт «Агенты» в боковом меню
кнопка создания агента
страница базы знаний