Разметка элементов сайта

Коротко

Размечайте только те элементы, про которые пользователь реально может спросить: кнопки, поля, карточки, пункты меню, шаги формы и важные состояния. Не нужно покрывать каждый декоративный контейнер.

Минимальный хороший набор для элемента: data-ai-context-id для стабильной связи, data-ai-label для понятного названия и data-ai-kb-query как поисковый fallback. Для повторяющихся карточек добавляйте общий context_id и отдельные data-ai-entity-type / data-ai-entity-id.

У повторяющихся строк и карточек data-ai-entity-type и data-ai-entity-id всегда задаются парой. Общий data-ai-context-id описывает вид элемента, например строку лида, а пара сущности указывает на конкретного лида. Когда на экране несколько элементов с одним контекстным ключом, действие без этой пары считается неоднозначным и не выполняется; передача только одного из двух атрибутов тоже недопустима.

Что дает разметка

Разметка data-ai-* помогает связать вопрос вида "что это за кнопка?", "как заполнить это поле?", "почему этот тариф недоступен?" с конкретным элементом страницы. Посетитель выбирает элемент на сайте через виджет, а виджет прикладывает к сообщению контекст выбранного элемента.

Разметка отвечает именно за элементы страницы. Контекст текущей страницы, открытой карточки, проекта, заказа или другой бизнес-сущности передается отдельно через Public API виджета: contextProvider, SenlerWidget.setPageContext(items) и одноразовый contextItems для следующего сообщения. В диалоге все это выглядит как плашки контекста рядом с сообщением.

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

Без разметки виджет тоже пытается собрать контекст по обычному HTML: текст, aria-label, label, placeholder, ближайшие aside, nav, main, header, footer, form, dialog, table. Но data-ai-* дает стабильные ключи и лучше связывает вопрос с базой знаний.

Как включить

Подключить канал Widget и вставить код виджета на сайт.
В настройках виджета включить функцию "Выбор элемента" (features.element_selection: true).
Добавить на сайт data-ai-* атрибуты для важных элементов.
В Markdown-документации обернуть фразу, которая описывает элемент, в span data-ai-context-id с таким же ключом.

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

Как это выглядит в работе

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

Какие элементы можно выбирать

Выбираемыми считаются:

элементы с data-ai-context-id, data-ai-label, data-ai-kind, data-ai-action, data-ai-kb-doc-id, data-ai-kb-query;
стандартные элементы button, a, input, textarea, select, label, summary;
текстовые и структурные элементы article, section, li, p, h1-h6;
элементы с ролями button, link, menuitem, tab, checkbox, radio, option;
элементы с aria-label или aria-labelledby.

data-ai-section сам по себе только описывает секцию. Если нужно выбрать весь блок, добавьте на него data-ai-label, data-ai-kind или data-ai-context-id.

Атрибуты

data-ai-area - крупная область страницы: header, navigation, sidebar, content, main, form, modal, footer.
data-ai-section - смысловой раздел: catalog, checkout-payment, pricing, profile-settings.
data-ai-label - понятное человеку название элемента.
data-ai-kind - тип элемента: primary-action, form-field, product-card, plan-card, menu-item, status-badge.
data-ai-action - смысловое действие: cart.add, checkout.pay, plan.choose, support.open.
data-ai-context-id - стабильный ключ для связи с базой знаний. Для сайта клиента используйте lowercase slug через точки, например checkout.payment.submit; для кабинета Senler AI используется формат cabinet.<section>.<screen>.<element>, для iframe диалогов - dialog.<section>.<screen>.<element>.
data-ai-kb-doc-id - прямой ID документа базы знаний, если он известен и стабилен. Для загружаемой MD-документации Senler AI не используйте его как основную связь.
data-ai-kb-query - поисковая подсказка для базы знаний, например "как оплатить заказ".
data-ai-entity-type - тип бизнес-сущности: product, plan, order, article.
data-ai-entity-id - ID бизнес-сущности, например SKU или публичный ID тарифа.

Не помещайте в атрибуты пароли, токены, email, телефон, персональные данные или секретные служебные ID.

Мини-чеклист качества

Ключ стабилен и не зависит от текста кнопки, языка интерфейса или ID конкретного пользователя.
Видимый текст статьи описывает действие по-человечески, а не повторяет контекстный ключ.
Элемент можно найти в текущей разметке страницы без перехода на другую страницу.
Для кнопки или поля есть label, role или понятный data-ai-label.
У каждой повторяющейся карточки есть одинаковый смысловой data-ai-context-id и своя полная пара data-ai-entity-type / data-ai-entity-id.
Для опасных действий вроде удаления или оплаты есть отдельная статья с ограничениями.

Живые сценарии

Интернет-магазин: пользователь спрашивает "как оплатить заказ?", находится статья про оплату и показывается кнопка с data-ai-context-id="checkout.payment.submit".
SaaS-форма: пользователь не понимает, куда вставить токен, а data-ai-context-id поля токена из документации помогает подсветить нужный input.
Личный кабинет: пользователь спрашивает про настройку уведомлений, сначала показывается пункт меню на текущей странице, а затем объясняется, что делать после перехода.

Во всех сценариях текст статьи остается человеческим: "нажмите кнопку оплаты", "введите токен", "откройте уведомления". Контекстный ключ находится в атрибуте span и не мешает читать инструкцию.

Пример: карточка товара

<main data-ai-area="content" data-ai-section="catalog">
  <article
    data-ai-label="Товар: Кроссовки Alpha"
    data-ai-kind="product-card"
    data-ai-context-id="catalog.product-card"
    data-ai-kb-query="как выбрать товар и размер"
    data-ai-entity-type="product"
    data-ai-entity-id="sku-alpha-42"
  >
    <h2>Кроссовки Alpha</h2>
    <p>Размеры 39-44</p>
    <button
      data-ai-label="Добавить Кроссовки Alpha в корзину"
      data-ai-kind="primary-action"
      data-ai-action="cart.add"
      data-ai-context-id="cart.add"
      data-ai-kb-query="как добавить товар в корзину"
    >
      В корзину
    </button>
  </article>
</main>

Пример: тарифы и оплата

<section data-ai-area="content" data-ai-section="pricing">
  <div
    data-ai-label="Тариф Pro"
    data-ai-kind="plan-card"
    data-ai-context-id="pricing.plan.pro"
    data-ai-kb-query="чем отличается тариф Pro"
    data-ai-entity-type="plan"
    data-ai-entity-id="pro"
  >
    <h3>Pro</h3>
    <button
      data-ai-label="Выбрать тариф Pro"
      data-ai-kind="primary-action"
      data-ai-action="plan.choose"
      data-ai-context-id="pricing.plan.choose"
      data-ai-kb-query="как выбрать и оплатить тариф"
    >
      Выбрать
    </button>
  </div>
</section>

Пример: форма

<form data-ai-area="form" data-ai-section="checkout-delivery">
  <label for="delivery-city">Город доставки</label>
  <input
    id="delivery-city"
    name="city"
    data-ai-label="Город доставки"
    data-ai-kind="form-field"
    data-ai-context-id="checkout.delivery.city"
    data-ai-kb-query="как указать город доставки"
  />
  <button
    data-ai-label="Продолжить оформление заказа"
    data-ai-kind="primary-action"
    data-ai-action="checkout.continue"
    data-ai-context-id="checkout.continue"
    data-ai-kb-query="как продолжить оформление заказа"
  >
    Продолжить
  </button>
</form>

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

Если на сайте есть data-ai-context-id="checkout.delivery.city", добавьте такой же ключ в текст файла базы знаний:

<span data-ai-context-id="checkout.delivery.city">Укажите город доставки</span>.

Когда пользователь выберет поле и задаст вопрос, Senler AI использует context_id для поиска по базе знаний. Документы с совпадающими контекстными ключами получают сильный приоритет.

Если точного ключа нет, помогает data-ai-kb-query: он добавляется к поисковому запросу вместе с label, text и section.

Если документация загружается папкой Markdown или ZIP-архивом, не полагайтесь только на видимый текст без разметки. При загрузке inline data-ai-context-id сохраняются как "Контекстные ключи для элементов". Подробности: документ site-actions.md-folder-context-id-ingestion.

Как выполняется действие на странице

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

Диагностика

Если элемент не выбирается:

проверьте, включена ли функция "Выбор элемента" в настройках виджета;
проверьте, что пользователь нажал "Выбрать элемент" в виджете;
добавьте на элемент data-ai-label или data-ai-context-id;
не размечайте только родительский контейнер через data-ai-section, если нужно выбрать сам контейнер.

Если нужная инструкция не найдена:

проверьте, что data-ai-context-id совпадает с контекстным ключом файла базы знаний;
добавьте data-ai-kb-query с естественной фразой;
проверьте, что документ активен и подключен к нужному агенту;
убедитесь, что вопрос отправлен с выбранной плашкой элемента в виджете.

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

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

страница базы знаний