Текстовые документы и контекстные ключи

Как создать текстовый документ

В левом меню откройте «Настройки» и перейдите в базу знаний.
Нажмите «Добавить».
Выберите «Текстовый документ».
Заполните название и содержимое.
Нажмите «Создать».

Так создаётся обычный текстовый документ без ручных контекстных ключей. Чтобы добавить ключи или воспользоваться полным редактором, откройте созданный документ. Другой способ — открыть его меню и выбрать «Редактировать».

Поля формы

В форме текстового файла есть:

заголовок;
контекстные ключи для элементов;
контент;
кнопка создания или сохранения и отмена;
удаление при редактировании с отдельным подтверждением.

Заголовок и контент обязательны. Заголовок должен быть понятным для поиска: например, "Правила возврата", "FAQ по тарифам", "Инструкция по кнопке Добавить канал".

Контент

Контент можно писать как структурированный Markdown: заголовки, списки, таблицы, примеры вопросов и ответов. Для поддержки полезнее документы, где есть:

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

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

Markdown-ссылки и картинки можно писать обычным синтаксисом: ![Скриншот](assets/screen.png) или [регламент](docs/rules.pdf). Если целевой файл загружен в базу знаний, кабинет сможет показать его в предпросмотре или связать с документом для ответа.

Режимы редактора

«Визуальный редактор» подходит для обычного форматирования: можно работать с текстом, заголовками, списками, цитатами, ссылками и блоками кода, не редактируя знаки Markdown вручную.

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

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

Правка выделенного текста с AI

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

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

Если документ не сохраняется

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

Если во время редактирования на сервере появилась новая версия того же файла, кабинет показывает предупреждение о более свежей версии и блокирует сохранение. Скопируйте свой текст, перезагрузите страницу, сравните новую версию со своими изменениями и внесите их повторно. Так правки другого пользователя или процесса не будут затёрты.

Контекстные ключи

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

Если файл пришел из загрузки MD/ZIP, проверьте это поле после импорта. Импорт извлекает ключи из inline data-ai-context-id в теле Markdown. Когда пользователь выбирает элемент на странице, документы с таким же ключом получают приоритет.

Поле «Контекстные ключи для элементов» связывает с ключом весь документ. Указывайте по одному ручному ключу на строку или разделяйте их запятыми.

Метки внутри текста

Если с элементом интерфейса связан только определённый фрагмент документа, добавьте метку прямо в Markdown:

Нажмите <span data-ai-context-id="channels.add">кнопку «Добавить канал»</span>.

Ключ должен состоять как минимум из двух сегментов через точку, например channels.add или widget.custom-action.create. Допустимы латинские буквы, цифры, дефисы и подчёркивания; общая длина — не более 120 символов. Пробелы, кириллица и пустые сегменты не поддерживаются.

Чтобы добавить метку, откройте режим Markdown и оберните нужный текст в span, как в примере. Затем можно вернуться в визуальный режим: помеченный фрагмент будет выделен. Нажмите его, чтобы открыть панель контекстной метки.

В панели можно изменить контекстный ключ и применить его кнопкой «Сохранить». Кнопка «Убрать метку» удаляет только привязку: сам текст остаётся в документе. Закрытие панели не применяет несохранённое изменение ключа.

Ключи из таких меток кабинет добавляет к документу автоматически и не дублирует в поле ручных ключей. Если разметка метки написана с ошибкой, исправьте её в Markdown; до исправления визуальное редактирование может быть недоступно.

Пример:

billing.plan
sidebar.settings
channels.add

И соответствующая разметка:

<button data-ai-context-id="channels.add" data-ai-kb-query="как добавить канал">
  Добавить канал
</button>

Если документ не находится по выбранному элементу

Проверьте:

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