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

Коротко

Не нужно дублировать список ai_context_ids во frontmatter. Пишите обычную инструкцию для человека и оборачивайте важную фразу в span data-ai-context-id. При импорте Senler AI извлечет эти ключи и покажет их в поле "Контекстные ключи для элементов".

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

Как должна работать идеальная связка

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

Как импорт читает Markdown

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

При импорте Senler AI делает четыре вещи:

• извлекает data-ai-context-id из текста статьи и переносит их в поле "Контекстные ключи для элементов";
• сохраняет свойства статьи (doc_id, keywords, route, ui_entities, user_questions) как метаданные файла;
• кладет в видимый content тело документа без frontmatter;
• добавляет метаданные в поисковый слой, чтобы база знаний находила документ по ключам и синонимам, но пользователь не видел YAML-шапку как текст страницы.

После загрузки ZIP все равно полезно открыть несколько файлов выборочно и проверить поле "Контекстные ключи для элементов": так можно быстро поймать ошибки в YAML или опечатки в context id.

Рекомендуемый формат MD

Frontmatter нужен как приватная шапка для свойств статьи. Связь с элементом интерфейса живет не во 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>

Что выбирать: context_id, kb_query или kb_doc_id

• data-ai-context-id - основной вариант. Он стабильный, человекочитаемый и сохраняется в поле "Контекстные ключи для элементов".
• data-ai-kb-query - fallback для поиска естественным языком. Полезен, если ключ еще не проставлен в файле БЗ.
• data-ai-kb-doc-id - прямой ID документа БЗ. Используйте осторожно: UUID документа может измениться после переимпорта или в другом проекте.

Как проверять после загрузки папки MD

1. Открыть "Настройки" -> "База знаний".
2. Найти загруженный документ.
3. Открыть редактирование.
4. Проверить поле "Контекстные ключи для элементов".
5. Убедиться, что там есть значения из data-ai-context-id.
6. Если поле пустое, проверить, что в теле Markdown есть inline data-ai-context-id.
7. Проверить, что файл активен и привязан к агенту.

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

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

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

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

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

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

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