# `<pleiades-chat>` виджеті

Фреймворкке тәуелсіз жалғыз веб-компонент. Ол беттің бұрышында іске қосу батырмасын көрсетеді және чаты бар бүйір панелін ашады. Ол shadow root ішінде жұмыс істейді, сондықтан хост беттің CSS-і оны бұза алмайды. Қарапайым HTML-де, React, Vue, Svelte немесе Angular-да бірдей жұмыс істейді.

## Орнату

<Tabs activeName="unpkg">
<TabPanel name="unpkg">

```html
<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>
```

</TabPanel>
<TabPanel name="jsDelivr">

```html
<script src="https://cdn.jsdelivr.net/npm/@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>
```

</TabPanel>
<TabPanel name="npm">

```sh
npm install @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
<TabPanel name="pnpm">

```sh
pnpm add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
<TabPanel name="bun">

```sh
bun add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
<TabPanel name="npm:jsr">

```sh
npx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
<TabPanel name="pnpm:jsr">

```sh
pnpm dlx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
<TabPanel name="bun:jsr">

```sh
bunx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

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

</TabPanel>
</Tabs>

Тек [WebMCP polyfill](/kk/docs/polyfill/) керек, чатсыз ба? Бұл сол пакеттің жеке кіру нүктесі (виджет оны өзі орнатады):

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

installWebMcpPolyfill();
```

`agent-url` және `publishable-key` мәндері әкімші панеліндегі арнаңыздан алынады. Виджет сондай-ақ нативті қолдауы жоқ беттерде [WebMCP polyfill](/kk/docs/polyfill/) орнатады, сондықтан [құралдарыңыз](/kk/docs/tools/) кез келген браузерде жұмыс істейді.

Конфигурация қате болса, элемент ештеңе көрсетпейді және консольге бір `[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-дер еленбейді. [Құралдар](/kk/docs/tools/#Басқа-терезелердегі-құралдар) бөлімін қараңыз. |
| `examples` | кірістірілген үшеуі | Бірінші хабарламаға дейін көрсетілетін үш ұсынысқа дейін: жолдардың JSON-массиві, `'["Find a jacket","Where is my order?"]'`. `'[]'` оларды жасырады. Талданбайтын мән кірістірілгендерді сақтайды. |
| `open` | жоқ | Булев атрибут. Панель ашық күйде басталады. Сондай-ақ `open` property. |
| `test-api` | жоқ | Булев атрибут. Браузерді автоматтандыру үшін `window.pleiadesChat.send(text)` функциясын да ашады. Әдепкіде өшірулі: өндірістік беттерде глобалды айнымалы жоқ. |

Диктовка бар жерде браузердің Web Speech API-ін пайдаланады. Ол жоқ жерде микрофон батырмасы бұғатталған болып көрінеді.

## Элемент әдістері мен property-лері

```js
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`](/kk/docs/api/server/#Келушіні-идентификациялау) үшін беріңіз. |
| `chat.agentUrl`, `publishableKey`, `position`, `heading`, `greeting`, `placeholder`, `lang`, `customerContext`, `examples`, `hotkey`, `micHotkey`, `exposeToolsTo` | Атрибуттарды көрсететін property-лер (жолдар). `null` немесе `undefined` орнату атрибутты жояды. |

### `send()`

```js
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()`

Оркестратор әр сөйлесу бойынша фактілерді сақтайды (қай дүкен ашық, соңғы табылған тауар). Бір қосымшаны екіншісіне ауыстыратын бет әр ауыстыру сайын сброс жасауы керек:

```js
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 негіз береді. |

```css
pleiades-chat {
  --pleiades-accent: #0b6e4f;
  --pleiades-accent-fg: #fff;
  --pleiades-font-family: "Inter", sans-serif;
}
```

Токендерден тыс кез келген нәрсе үшін CSS Shadow Parts қолданыңыз:

```css
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-ды бір рет импорттаңыз:

```ts
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 статусынан](/kk/docs/api/widget/#Қате-статустары) алынады: жауаптың болмауы — желі қатесі және composer-ді бұғаттайды, `403` — тыйым салынған, `413` — «тым ұзын», `429` — жылдамдық шектелген, `code: "task_failed"` бар терминал ағын `error`-ы сайттың кеңесін көрсетеді және composer-ді ешқашан бұғаттамайды. Арна рұқсат етпейтін origin браузерде желі қатесі сияқты көрінеді: сервер CORS тақырыптарынсыз `403` жауап береді, сондықтан браузер себебін жасырады.

## Қауіпсіздік

- **Тек `pk_` кілттері.** Виджет `sk_` кілтімен іске қосудан бас тартады. Құпия кілт [`identify`](/kk/docs/api/server/#Келушіні-идентификациялау) үшін серверіңізде тұруы керек.
- `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 арқылы бекітіңіз.
