Связь Markdown-документации с элементами сайта

Какой результат нужен

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

Нажмите <span data-ai-context-id="checkout.payment.submit">кнопку оплаты</span>,
чтобы перейти к оплате заказа.

После загрузки Senler AI извлечёт ключ из текста и покажет его у документа в поле «Контекстные ключи для элементов». Отдельный список ai_context_ids во frontmatter для этого не нужен и не заменяет inline-разметку.

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

Последовательность настройки

Владелец сайта размечает кнопку, поле или карточку атрибутом data-ai-context-id.
В Markdown-документе для этой функции указан такой же ключ.
Документ загружается в базу знаний.
Ключ сохраняется как контекстный ключ документа.
Посетитель выбирает элемент в виджете и задает вопрос.
Senler AI получает выбранный элемент как плашку рядом с сообщением. Рядом могут находиться плашки страницы или другой бизнес-сущности.
Поиск по базе знаний отдает приоритет документам, где поле "Контекстные ключи для элементов" содержит этот ключ.

Напишите человеческую инструкцию

Не выносите ключи отдельным техническим списком в видимый текст. Обрамляйте точным ключом конкретные слова: «поле токена», «кнопку оплаты», «настройки уведомлений». Один span должен быть корректно закрыт и находиться в обычном тексте статьи.

Ключ должен содержать как минимум две непустые части через точку, например checkout.payment.submit, начинаться с буквы или цифры и быть не длиннее 120 символов. В частях используйте латинские буквы, цифры, _ и -; для единообразия рекомендуются строчные ключи. Значение без точки, с пустой частью вроде checkout..submit или с пробелом импорт пропустит.

Поставьте тот же ключ на сайте

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

Загрузите Markdown

Добавьте подготовленный файл .md, .mdc или .markdown в базу знаний. Если документов много, загрузите ZIP-архив с той же структурой папок. Выбор файлов, режим распознавания изображений, конфликты имён и ход фоновой обработки описаны в инструкции «Загрузка файлов и архивов».

Импорт MD/ZIP для файлов .md, .mdc, .markdown читает начальный frontmatter и inline-разметку data-ai-context-id в теле статьи. Frontmatter должен находиться в самом начале файла между одинаковыми маркерами --- или +++; внутри распознаются простые поля и списки.

При импорте Senler AI:

отделяет начальный блок frontmatter от видимого текста;
сохраняет распознанные свойства frontmatter как метаданные файла;
извлекает корректно закрытые span data-ai-context-id из тела статьи;
добавляет извлечённые значения в контекстные ключи документа.

Разметка внутри fenced- или inline-кода, отступного блока кода, экранированного фрагмента либо HTML-комментария не считается ключом. Это позволяет показывать примеры без ложной связи с интерфейсом.

Пример Markdown-файла

Frontmatter может хранить свойства статьи. Связь с элементом интерфейса находится прямо в человеческой фразе тела документа.

---
doc_id: "site.checkout.payment"
title: "Оплата заказа"
keywords:
  - "оплата"
  - "карта"
  - "заказ"
search_queries:
  - "как оплатить заказ"
  - "почему оплата не проходит"
---

В тексте документа привяжите фразу к элементу:

<span data-ai-context-id="checkout.payment.submit">Нажмите кнопку оплаты</span>,
чтобы перейти к оплате заказа.

Пример соответствующей разметки сайта

<form data-ai-area="form" data-ai-section="checkout-payment">
  <button
    data-ai-label="Оплатить заказ"
    data-ai-kind="primary-action"
    data-ai-action="checkout.payment.submit"
    data-ai-context-id="checkout.payment.submit"
    data-ai-kb-query="как оплатить заказ"
  >
    Оплатить
  </button>
</form>

Проверьте документ после загрузки

Нажмите шестерёнку «Настройки» справа от названия проекта, в группе «Данные проекта» откройте «База знаний», затем найдите загруженный документ и откройте его редактирование. Проверьте поле «Контекстные ключи для элементов» и убедитесь, что файл или его папка подключены к нужному агенту с правом чтения.

На снимке цифрой 1 отмечена открытая форма документа, 2 — заголовок, 3 — контекстные ключи, 4 — содержимое, 5 — кнопка создания или сохранения. Ключи, извлечённые из inline-разметки, отображаются в поле 3 вместе с ключами, добавленными вручную.

Поле контекстных ключей в документе базы знаний

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

Когда нужны kb_query и kb_doc_id

data-ai-context-id — основной вариант: стабильная связь элемента с конкретным местом инструкции.
data-ai-kb-query — запасная поисковая фраза естественным языком, если точной связи ещё нет.
data-ai-kb-doc-id — прямой ID документа БЗ. Используйте осторожно: UUID документа может измениться после переимпорта или в другом проекте.

Если связь не работает

Если после загрузки папки с MD выбранная кнопка не находит нужную инструкцию:

Проверьте, какой data-ai-context-id стоит на кнопке.
Откройте соответствующий файл в базе знаний.
Проверьте, что такой же ключ есть в inline data-ai-context-id внутри документа или уже отображается в поле "Контекстные ключи для элементов".
Убедитесь, что span находится в обычном тексте, правильно закрыт, а ключ соответствует формату.
Добавьте data-ai-kb-query на кнопку как текстовую поисковую подсказку.
Убедитесь, что агенту подключена папка или файл базы знаний с правом чтения.

Если статья предназначена для публичного чтения, контекстные ключи не должны мешать тексту. Видимая часть span должна оставаться человеческой фразой: «Введите токен Telegram», «Нажмите Подключить», «Откройте настройки уведомлений».

Что проверять дальше

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