ИИ-помощник сайта

Сайт может отвечать посетителям на вопросы по собственной базе знаний. Для этого нужны две вещи: каталог assistant/ в проекте и элемент `Assistant` на странице.

Помощник — возможность REEEL-сайта: вопрос уходит на адрес самого сайта, и отвечает сервер, который раздаёт сайт. У экспортированного в статику сайта и в превью редактора отвечать некому.

Каталог assistant/

assistant/
  assistant.json            темы, лимиты, следующие шаги, запасной путь
  prompt.md                 кто такой помощник, словами владельца
  knowledge/<язык>/**.md    по чему он отвечает

Сайт этот каталог не раздаёт : с адреса сайта наружу идут только data/** и страницы.

Но тайником он от этого не становится. assistant/ — такие же файлы проекта, как остальные: они синхронизируются на платформу, и её адрес выдачи содержимого ( /content/{projectId}/… ) отдаёт любой синхронизированный файл тому, кто знает идентификатор проекта и прошёл выдачу доступа, — а она рассчитана на установленные приложения, не на проверку личности. Секретов сюда не кладите : ни в prompt.md , ни в assistant.json , ни в каталог.

Обязательна только база. Каталог с одним knowledge/ — рабочий помощник.

База знаний

Обычные markdown-файлы.

• По каталогу на язык ( knowledge/ru/ , knowledge/en/ ): посетителю отвечают по базе языка, на котором он спросил; если такой базы нет — по базе языка сайта по умолчанию.
• Файлы прямо в knowledge/ : одна база на всех.

Помощник отвечает только тем, что написано в базе . Каждое утверждение опирается на дословную цитату из прочитанного раздела; чего в базе нет, того он не скажет.

Документ и страница

Документ считается страницей по своему же пути:

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

Те же файлы могут быть страницами: страница, которая рисует текст через `Markdown src:` из assistant/knowledge/ , — одновременно и страница, и запись в базе.

Markdown src:$"assistant/knowledge/${strings.effectiveLocale}/project/domains.md"

assistant.json

Все поля необязательны.

{
  "topics": "Тарифы, оплата и публикация Acme.",
  "limits": {
    "questionChars": 400,
    "claims": 5,
    "perVisitorPerDay": 30,
    "offTopicBeforePause": 3,
    "pauseMinutes": 30
  },
  "actions": [
    {
      "id": "support",
      "title": { "ru": "Написать в поддержку", "en": "Write to support" },
      "url": "/help",
      "when": "документация не решает вопрос посетителя"
    }
  ],
  "fallback": {
    "text": { "ru": "Спросите нас напрямую.", "en": "Ask us directly." },
    "action": "support"
  },
  "messages": { "paused": { "ru": "На сегодня всё — позвоните нам." } },
  "links": { "pricing.md": "tiers" },
  "transcripts": true
}

Текст можно задать одной строкой на все языки или объектом по языкам.

Лимиты владелец только ужесточает. Потолки платформы — предел; число больше потолка читается как потолок.

Следующие шаги

Помощник не только отвечает, но и подводит к действию: записаться, скачать, написать в поддержку. when — единственное, что читает модель; она называет id , а подпись и адрес посетителю показываются из этого файла . Ссылок модель не пишет, и шага, которого нет в списке, предложить не может.

Сценарии и каталог: карточки в ответе

Часть ответов лучше показать, чем пересказать: тариф, услугу, товар, раздел сайта. Для этого у помощника есть сценарии — в assistant.json :

"scenarios": [
  { "id": "tiers", "when": "посетитель выбирает тариф", "catalog": "tiers" }
]

и каталог записей рядом с базой знаний — assistant/catalog/tiers.json :

[
  {
    "id": "studio",
    "about": "для команд от пяти человек, с общим доступом",
    "title": { "ru": "Студия", "en": "Studio" },
    "text": { "ru": "Для команд от пяти человек.", "en": "For teams of five or more." },
    "price": 4900,
    "image": "data/images/studio.png",
    "url": "/tier#studio"
  }
]

Как это работает:

• Модель видит список: сценарий, его when и по строке на запись — идентификатор и about . Больше ничего: ни цен, ни картинок, ни адресов.
• В ответе она называет идентификаторы записей. Сервер сверяет их со списком и подставляет поля из каталога на языке посетителя. Идентификатор, которого в каталоге нет, отбрасывается.
• В одном ответе не больше шести карточек. Карточки могут идти вместе с утверждениями или сами по себе.
• Список записей уходит модели перед каждым вопросом, поэтому каталог держите небольшим: до 12 сценариев, до 60 записей в каждом.
• Картинки кладите в data/** : каталог assistant/ наружу не раздаётся.
• Сценарий с ошибкой (нет файла каталога, файл не разбирается, вид text ) пропускается, а помощник продолжает работать без него.

Как нарисовать карточку на странице — в описании элемента `Assistant` .

prompt.md

Инструкция владельца: кто такой помощник и как он говорит. Секретов сюда не кладите — модель можно уговорить пересказать сказанное ей.

Что помощник делает сам

• Отвечает только по темам сайта. Вопрос не по теме получает мягкий отказ; после нескольких таких посетитель ставится на паузу, и ему предлагают fallback .
• Требует согласия. Без него вопрос не уходит со страницы.
• Проверяет незнакомца. После первого вопроса — невидимая проверка «я не бот»; посетителя, который её прошёл, больше не спрашивают.
• Помнит посетителя по cookie , которую сам выставляет. Скрипт страницы её не видит, чужой сайт предъявить не может.

Включение

Каталог assistant/ — заявка, а не разрешение: помощник появляется у сайта, когда платформа включила его для проекта.

Разговоры

Если владелец не запретил ( transcripts: false ), вопросы и ответы сохраняются для улучшения базы: видно, о чём спрашивают и чего в базе не хватает. Об этом посетителю нужно сказать рядом с полем вопроса и в политике сайта.