Виджет
Один веб-компонент, не привязанный к фреймворку. Он показывает кнопку-лаунчер в углу страницы и открывает боковую панель с чатом. Компонент живёт в 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> Нужен только полифил WebMCP , без чата? Это отдельная точка входа того же пакета (виджет ставит его сам):
import { installWebMcpPolyfill } from "@shalotts/pleiades-widget/webmcp-polyfill";
installWebMcpPolyfill(); 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_- после него. |
position | bottom-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"}'. Значения должны быть строками, числами или булевыми; остальные поля отбрасываются с ошибкой в консоли. Отправляется с каждым сообщением. |
hotkey | mod+j | Открывает и закрывает панель. mod — это Ctrl, а на Mac — Cmd. Другие примеры: ctrl+shift+k, alt+/. Пустое значение отключает. |
mic-hotkey | mod+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"); | Член | Описание |
|---|---|
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? } | Поле | Значение |
|---|---|
status: "done" | Цель достигнута. |
status: "failed" | Сервер отработал, но сайт не смог выполнить задачу. В error лежит последний ответ самого сайта, если он есть. |
status: "error" | Занято, не настроено, сообщение слишком длинное, сбой сервера или остановка. error говорит, что именно произошло. |
reply | Итоговый текст ассистента за этот ход. |
steps | Строки прогресса, показанные за ход; phase — running, done или failed. |
requestId | Id первого tool_call хода (открывает запуск в админ-панели /flow/<id>). Отсутствует, если в ходе не было вызова инструмента на стороне браузера. |
resetSession()
Оркестратор хранит факты по каждому разговору (какой магазин открыт, последний найденный товар). Страница, которая подменяет одно приложение другим, должна сбрасывать сессию при каждом переключении:
picker.addEventListener("change", () => chat.resetSession()); Разным сайтам следует использовать отдельные каналы (по одному 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 Shadow Parts:
pleiades-chat::part(panel) { border-radius: 0; }
pleiades-chat::part(send) { text-transform: uppercase; } Части (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"; Ошибки
Ошибки конфигурации один раз пишутся в консоль как [pleiades-widget] <code>: <advice>, и ничего не рисуется.
| Код | Причина |
|---|---|
missing_agent_url | agent-url пуст. |
invalid_agent_url | Это не http(s) URL либо в нём есть имя пользователя или пароль. |
insecure_agent_url | http к хосту, отличному от localhost. |
missing_key | publishable-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.