Виджет

Один веб-компонент, не привязанный к фреймворку. Он показывает кнопку-лаунчер в углу страницы и открывает боковую панель с чатом. Компонент живёт в shadow root, поэтому CSS страницы-хозяина не может его сломать. Он одинаково работает в обычном HTML, React, Vue, Svelte и Angular.

Установка

<script src="https://unpkg.com/@shalotts/pleiades-widget/dist/pleiades-widget.js" defer></script>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
html

Нужен только полифил WebMCP , без чата? Это отдельная точка входа того же пакета (виджет ставит его сам):

import { installWebMcpPolyfill } from "@shalotts/pleiades-widget/webmcp-polyfill";

installWebMcpPolyfill();
js

agent-url и publishable-key берутся из вашего канала в админ-панели. На страницах без нативной поддержки виджет также устанавливает полифил WebMCP , поэтому ваши инструменты работают в любом браузере.

Если конфигурация неверна, элемент ничего не рисует и пишет в консоль одну строку [pleiades-widget] <code>. См. Ошибки .

Атрибуты

Вся настройка выполняется через атрибуты. Изменение любого из них перемонтирует виджет.

АтрибутПо умолчаниюОписание
agent-urlобязателенБазовый URL оркестратора. Только https; обычный http допускается для localhost, 127.0.0.1 и [::1]. Без имени пользователя и пароля в URL.
publishable-keyобязателенПубличный ключ канала. Должен соответствовать pk_ и не менее 8 символов из A-Za-z0-9_- после него.
positionbottom-leftУгол лаунчера: bottom-left, bottom-right, top-left, top-right. Панель выезжает с той же стороны. Неизвестные значения заменяются на bottom-left.
headingлокализуетсяЗаголовок панели.
greetingлокализуетсяПервое сообщение-пузырь.
placeholderлокализуетсяПодсказка в поле сообщения.
lang<html lang>, иначе язык браузераen, ru или kk. Учитываются только первые две буквы (ru-RU работает); всё остальное — английский.
customer-contextнетПлоский JSON-объект с фактами, которые сайт уже знает, например '{"city":"Almaty","tier":"gold"}'. Значения должны быть строками, числами или булевыми; остальные поля отбрасываются с ошибкой в консоли. Отправляется с каждым сообщением.
hotkeymod+jОткрывает и закрывает панель. mod — это Ctrl, а на Mac — Cmd. Другие примеры: ctrl+shift+k, alt+/. Пустое значение отключает.
mic-hotkeymod+shift+spaceЗапускает и останавливает диктовку, пока панель открыта. Тот же формат. Пустое значение отключает.
expose-tools-toнетOrigin'ы через запятую (https://a.example,https://b.example), окна которых могут получать список и запускать инструменты этой страницы через postMessage. * и некорректные origin'ы игнорируются. См. Инструменты .
examplesвстроенные триДо трёх подсказок, которые показываются до первого сообщения: JSON-массив строк, '["Find a jacket","Where is my order?"]'. '[]' скрывает их. Если значение не разбирается, остаются встроенные.
openотсутствуетБулев атрибут. Панель стартует открытой. Также есть свойство open.
test-apiотсутствуетБулев атрибут. Дополнительно открывает window.pleiadesChat.send(text) для автоматизации браузера. По умолчанию выключен: на боевых страницах глобальной переменной нет.

Диктовка использует Web Speech API браузера там, где он есть. Там, где его нет, кнопка микрофона затемнена.

Методы и свойства элемента

const chat = document.querySelector("pleiades-chat");
js
ЧленОписание
chat.openСвойство, отражающее атрибут open. Установите его, чтобы открыть или закрыть панель.
chat.toggle()Переключает open.
chat.send(text)Отправляет text, как будто посетитель набрал его и нажал «Отправить». Открывает панель, выполняет вызовы инструментов страницы и завершается (resolve), когда ход заканчивается. Никогда не отклоняется (reject).
chat.resetSession()Новый разговор для того же посетителя: новый тред, пустая панель, инструменты страницы объявляются заново. Никогда не отклоняется.
chat.getVisitorToken()Возвращает токен посетителя этого браузера (при необходимости создавая сессию) или undefined, пока элемент не настроен. Передайте его на свой сервер для identify .
chat.agentUrl, publishableKey, position, heading, greeting, placeholder, lang, customerContext, examples, hotkey, micHotkey, exposeToolsToСвойства, зеркалирующие атрибуты (строки). Присвоение null или undefined удаляет атрибут.

send()

const r = await chat.send("book a double room for two nights from Friday");
// { requestId?, reply, steps: [{ text, phase }], status: "done" | "failed" | "error", error? }
js
ПолеЗначение
status: "done"Цель достигнута.
status: "failed"Сервер отработал, но сайт не смог выполнить задачу. В error лежит последний ответ самого сайта, если он есть.
status: "error"Занято, не настроено, сообщение слишком длинное, сбой сервера или остановка. error говорит, что именно произошло.
replyИтоговый текст ассистента за этот ход.
stepsСтроки прогресса, показанные за ход; phase — running, done или failed.
requestIdId первого tool_call хода (открывает запуск в админ-панели /flow/<id>). Отсутствует, если в ходе не было вызова инструмента на стороне браузера.

resetSession()

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

picker.addEventListener("change", () => chat.resetSession());
js

Разным сайтам следует использовать отдельные каналы (по одному publishable-key на каждый); при смене ключа у каждого свой разговор, который сохраняется между перезагрузками.

Темизация

Задайте CSS-переменные на элементе:

ПеременнаяНазначение
--pleiades-accent, --pleiades-accent-fgАкцентный цвет и цвет текста на нём.
--pleiades-bg, --pleiades-fgФон панели и текст.
--pleiades-muted, --pleiades-muted-fgВторостепенные поверхности и текст.
--pleiades-borderГраницы.
--pleiades-destructive, --pleiades-destructive-fgЦвет ошибки и цвет текста на нём.
--pleiades-font-familyШрифт.
--pleiades-font-scaleМножитель всех размеров текста; по умолчанию 1.5. Значение 1 даёт компактную базу 14 px.
pleiades-chat {
  --pleiades-accent: #0b6e4f;
  --pleiades-accent-fg: #fff;
  --pleiades-font-family: "Inter", sans-serif;
}
css

Для всего, что выходит за рамки токенов, используйте CSS Shadow Parts:

pleiades-chat::part(panel) { border-radius: 0; }
pleiades-chat::part(send)  { text-transform: uppercase; }
css

Части (parts) в шаблонах: launcher, panel, header, close, messages, error, mode, hint, tooltip, composer, input, send, mic, link.

@shalotts/pleiades-widget/style.css — это точная таблица стилей, которую виджет внедряет в свой shadow root. Используйте её как справочник по именам классов; подключение её к странице ничего не даёт, потому что shadow DOM не применяет её там.

Типы

Пакет поставляется с объявлениями TypeScript, включая запись HTMLElementTagNameMap, поэтому document.querySelector("pleiades-chat") типизирован. Для React JSX один раз импортируйте расширение типов:

import type {} from "@shalotts/pleiades-widget/react";
ts

Ошибки

Ошибки конфигурации один раз пишутся в консоль как [pleiades-widget] <code>: <advice>, и ничего не рисуется.

КодПричина
missing_agent_urlagent-url пуст.
invalid_agent_urlЭто не http(s) URL либо в нём есть имя пользователя или пароль.
insecure_agent_urlhttp к хосту, отличному от localhost.
missing_keypublishable-key пуст.
secret_keyКлюч начинается с sk_. Считайте его скомпрометированным и замените.
invalid_keyЭто не ключ pk_ ожидаемого вида.

Некорректный customer-context пишет invalid_customer_context и отбрасывается; виджет продолжает работать.

Ошибки времени выполнения отображаются в панели. Они сопоставляются со статусами API : отсутствие ответа — сетевая ошибка, и поле ввода блокируется; 403 — запрещено; 413 — «слишком длинно»; 429 — превышен лимит запросов; завершающая error потока с code: "task_failed" показывает совет сайта и никогда не блокирует поле ввода. Origin, который канал не разрешает, выглядит в браузере как сетевая ошибка: сервер отвечает 403 без заголовков CORS, поэтому браузер скрывает причину.

Безопасность

  • Только ключи pk_. Виджет отказывается запускаться с ключом sk_. Секретный ключ должен храниться на вашем сервере, для identify .
  • Только https для agent-url, кроме localhost, чтобы токен посетителя никогда не передавался открытым текстом.
  • Разрешённые origin'ы. Канал перечисляет origin'ы, которым разрешено его использовать; сервер проверяет заголовок Origin, который браузер подделать не может. Скопированный ключ на другом сайте бесполезен.
  • Никаких секретов на странице. Ключ отправляется один раз, чтобы получить токен посетителя. Все последующие запросы несут только токен.
  • Запросы используют credentials: "omit" и cache: "no-store": без cookie и без кеширования.
  • Токен и id треда хранятся в localStorage под именем, производным от URL агента и ключа, поэтому два сайта никогда не делят сессию. Если хранилище заблокировано, виджет переключается на память.
  • Текст сообщений отображается через textContent, а не как HTML.
  • Не помещайте чувствительные данные в customer-context. Ограничьтесь несколькими короткими фактами (страна, город, метка тарифа), но не именами, адресами электронной почты или номерами телефонов.
  • Инструменты, зарегистрированные на странице, для оркестратора — недоверенные данные, а без expose-tools-to никакое другое окно не может до них добраться.

Если вы размещаете скрипт самостоятельно, закрепите его с помощью Subresource Integrity.