Виджет
Бұл бет машиналық аудармамен жасалған және тексерілуде. Қателер болуы мүмкін - ағылшын нұсқасын қараңыз.
Фреймворкке тәуелсіз жалғыз веб-компонент. Ол беттің бұрышында іске қосу батырмасын көрсетеді және чаты бар бүйір панелін ашады. Ол 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 polyfill керек, чатсыз ба? Бұл сол пакеттің жеке кіру нүктесі (виджет оны өзі орнатады):
import { installWebMcpPolyfill } from "@shalotts/pleiades-widget/webmcp-polyfill";
installWebMcpPolyfill(); agent-url және publishable-key мәндері әкімші панеліндегі арнаңыздан алынады. Виджет сондай-ақ нативті қолдауы жоқ беттерде WebMCP polyfill орнатады, сондықтан құралдарыңыз кез келген браузерде жұмыс істейді.
Конфигурация қате болса, элемент ештеңе көрсетпейді және консольге бір [pleiades-widget] <code> жолын жазады. Қателер бөлімін қараңыз.
Атрибуттар
Барлық баптау атрибуттар арқылы жасалады. Біреуін өзгерту виджетті қайта монтаждайды.
| Атрибут | Әдепкі | Сипаттамасы |
|---|---|---|
agent-url | міндетті | Оркестратордың базалық URL-ы. Тек https; localhost, 127.0.0.1 және [::1] үшін қарапайым http қабылданады. URL ішінде пайдаланушы аты мен құпиясөз болмауы керек. |
publishable-key | міндетті | Арнаның ашық кілті. pk_ және одан кейін A-Za-z0-9_- таңбаларынан кемінде 8 таңба болуы керек. |
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 | жоқ | Терезелері осы беттің құралдарын postMessage арқылы тізімдей және іске қоса алатын origin-дердің үтірмен бөлінген тізімі (https://a.example,https://b.example). * және жарамсыз origin-дер еленбейді. Құралдар бөлімін қараңыз. |
examples | кірістірілген үшеуі | Бірінші хабарламаға дейін көрсетілетін үш ұсынысқа дейін: жолдардың JSON-массиві, '["Find a jacket","Where is my order?"]'. '[]' оларды жасырады. Талданбайтын мән кірістірілгендерді сақтайды. |
open | жоқ | Булев атрибут. Панель ашық күйде басталады. Сондай-ақ open property. |
test-api | жоқ | Булев атрибут. Браузерді автоматтандыру үшін window.pleiadesChat.send(text) функциясын да ашады. Әдепкіде өшірулі: өндірістік беттерде глобалды айнымалы жоқ. |
Диктовка бар жерде браузердің Web Speech API-ін пайдаланады. Ол жоқ жерде микрофон батырмасы бұғатталған болып көрінеді.
Элемент әдістері мен property-лері
const chat = document.querySelector("pleiades-chat"); | Мүше | Сипаттамасы |
|---|---|
chat.open | open атрибутын көрсететін property. Панельді ашу немесе жабу үшін оны орнатыңыз. |
chat.toggle() | open мәнін ауыстырады. |
chat.send(text) | text мәтінін келуші теріп, «Жіберу» түймесін басқандай жібереді. Панельді ашады, беттің құрал шақыруларын орындайды және кезек аяқталғанда resolve болады. Ешқашан reject болмайды. |
chat.resetSession() | Сол келуші үшін жаңа сөйлесу: жаңа тред, бос панель, беттің құралдары қайта жарияланады. Ешқашан reject болмайды. |
chat.getVisitorToken() | Осы браузердің келуші токенімен resolve болады (қажет болса сессияны құрады), ал элемент бапталмаған кезде undefined қайтарады. Оны серверіңізге identify үшін беріңіз. |
chat.agentUrl, publishableKey, position, heading, greeting, placeholder, lang, customerContext, examples, hotkey, micHotkey, exposeToolsTo | Атрибуттарды көрсететін property-лер (жолдар). 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 | Кезектің бірінші 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; } Үлгілерде бар part-тар: launcher, panel, header, close, messages, error, mode, hint, tooltip, composer, input, send, mic, link.
@shalotts/pleiades-widget/style.css — виджет өзінің shadow root ішіне енгізетін дәл сол stylesheet. Оны класс атаулары үшін анықтама ретінде қолданыңыз; оны бетке қосу ештеңе істемейді, өйткені shadow DOM оны ол жерде қолданбайды.
Типтер
Пакет TypeScript декларацияларымен, соның ішінде HTMLElementTagNameMap жазбасымен жеткізіледі, сондықтан document.querySelector("pleiades-chat") типтелген. React JSX үшін augmentation-ды бір рет импорттаңыз:
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 | localhost емес хостқа http. |
missing_key | publishable-key бос. |
secret_key | Кілт sk_ деп басталады. Оны ашылып қалған деп санап, ауыстырыңыз. |
invalid_key | Күтілген пішіндегі pk_ кілті емес. |
Қате customer-context invalid_customer_context жазады және алынып тасталады; виджет жұмысын жалғастырады.
Орындалу уақытындағы ақаулар панельде көрсетіледі. Олар API статусынан алынады: жауаптың болмауы — желі қатесі және composer-ді бұғаттайды, 403 — тыйым салынған, 413 — «тым ұзын», 429 — жылдамдық шектелген, code: "task_failed" бар терминал ағын error-ы сайттың кеңесін көрсетеді және composer-ді ешқашан бұғаттамайды. Арна рұқсат етпейтін origin браузерде желі қатесі сияқты көрінеді: сервер CORS тақырыптарынсыз 403 жауап береді, сондықтан браузер себебін жасырады.
Қауіпсіздік
- Тек
pk_кілттері. Виджетsk_кілтімен іске қосудан бас тартады. Құпия кілтidentifyүшін серверіңізде тұруы керек. agent-urlүшін тек https (localhost-тан басқа), сондықтан келуші токені ашық мәтінмен ешқашан жіберілмейді.- Рұқсат етілген origin-дер. Арна оны қолдана алатын origin-дерді тізімдейді; сервер
Originтақырыбын тексереді, оны браузер жасанды түрде жасай алмайды. Көшірілген кілт басқа сайтта пайдасыз. - Бетте құпия жоқ. Кілт келуші токенін алу үшін бір рет жіберіледі. Кейінгі әр сұраныста тек токен болады.
- Сұраныстар
credentials: "omit"жәнеcache: "no-store"қолданады: cookie жоқ, ештеңе кэшталмайды. - Токен мен тред идентификаторы
localStorageішінде agent URL мен кілттен алынған атаумен сақталады, сондықтан екі сайт сессияны ешқашан бөліспейді. Сақтау бұғатталса, виджет жадыға көшеді. - Хабарлама мәтіні
textContentарқылы көрсетіледі, ешқашан HTML ретінде емес. customer-contextішіне құпия деректерді салмаңыз. Оны бірнеше қысқа фактімен (ел, қала, тариф белгісі) шектеңіз, есімдерді, email-дерді немесе телефон нөмірлерін ешқашан салмаңыз.- Бетте тіркелген құралдар оркестратор үшін сенімсіз деректер, ал
expose-tools-toболмаса, басқа терезе оларға қол жеткізе алмайды.
Скриптті өзіңіз хостласаңыз, оны Subresource Integrity арқылы бекітіңіз.