Przejdź do głównej treści

CLI i wdrażanie konfiguracji

Opublikowane artefakty CLI/config w wersji 0.3.1 implementują kontrakt konfiguracji/backendu 0.3.0 i odrzucają nieznane klucze zarówno lokalnie, jak i w backendzie.

CLI tworzy, weryfikuje i wdraża niezmienne wersje konfiguracji ChattyBox, a także je promuje i przywraca. Tokeny wdrażania są przypisane do jednego projektu i wybranych środowisk, dzięki czemu ten sam proces sprawdza się w lokalnym środowisku programistycznym i w CI.

Stan wydania i środowiska wykonawczego​

Opublikowane są @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 oraz osobny, opublikowany klient JavaScript @openstaticfish/chattybox@0.1.4. Rozszerzoną konfigurację obsługują pakiety CLI i config 0.3.1 wraz z kontraktem konfiguracji/backendu 0.3.0; SDK jest oddzielnym klientem i nie należy do artefaktów obsługujących ten kontrakt. schemaVersion: "1" nie jest wersją pakietu. status pokazuje wersję środowiska, natomiast runtimeConfigVersionId oznacza ostatnią konfigurację zastosowaną do współdzielonego runtime i może się różnić. Pominięte mode wybiera crawl, zachowując jawne maxDepth: 0. CLI jest programem ESM i wymaga Node.js 20 lub nowszego. bunx domyślnie respektuje shebang Node, więc zainstaluj Node albo jawnie wybierz Bun przez bunx --bun @openstaticfish/chattybox-cli ....

W automatyzacji produkcyjnej przypnij przetestowaną wersję pakietu. Niewersjonowane przykłady poleceń korzystają z pakietu już zainstalowanego, dostępnego w pamięci podręcznej albo pobranego z rejestru, a nie z kodu źródłowego tego repozytorium.

CLI nie jest narzędziem przeglądarkowym. Testy CI opublikowanego pakietu obejmują Node 20, 22 i 24 w systemie Linux, a nie pełną macierz systemów i przeglądarek. Walidator obejmuje między innymi ustawienia projektu, wykrywania i harmonogramu, języka, widget.icon oraz widget.showBranding.

Zakres konfiguracji jako kodu​

Konfiguracja steruje nazwą i opisem projektu, personą i odpowiedzią zastępczą asystenta, wykrywaniem i odświeżaniem witryny, językiem oraz wyglądem hostowanego widżetu. Wdrożenie preview lub production stosuje te wartości i kolejkuje odświeżenie istniejącego korpusu. Po włączeniu blokady ustawienia należące do konfiguracji zmienia się przez wersjonowane wdrożenia, z wyjątkiem preferencji brandingu zależnej od planu.

Projekt trzeba najpierw jednorazowo utworzyć w panelu. Klucze publiczne i ich opcjonalne ograniczenia originów, cykl życia tokenów wdrożeniowych, analityka, rozmowy, luki w treści, operacje usuwania i przesłane pliki ikon pozostają poza konfiguracją. Dla deklaratywnej ikony użyj URL-a lub emoji. Plik nie zawiera identyfikatora projektu: wybiera go sekretny token wdrożeniowy, przypisany do jednego istniejącego projektu i wybranych środowisk. Traktuj jeden plik i jeden token projektu jako jeden zarządzany projekt.

Publiczny klucz widżetu można umieścić w kodzie przeglądarki: służy do czatu i konfiguracji widżetu. Klucz bez ograniczeń działa z różnych originów, a przygotowany dla witryny może już być ograniczony. Ograniczenia originów są opcjonalną dodatkową ochroną, nie uwierzytelnianiem odwiedzających. Token wdrożeniowy służy do wdrażania, promocji, rollbacku i sprawdzania statusu konfiguracji; nie wolno umieszczać go w przeglądarce.

Tworzenie konfiguracji​

bunx @openstaticfish/chattybox-cli init

To polecenie tworzy plik chattybox.config.json:

{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}

Użyj niestandardowej ścieżki, gdy konfiguracja ma znajdować się w podkatalogu:

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Weryfikacja lokalna lub w CI​

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

Walidacja bieżącego kodu sprawdza strukturę obiektów, wymaganą nazwę asystenta, wartości wyliczeniowe, adresy HTTP(S), limity liczb całkowitych, kombinacje języków i sześciocyfrowe kolory hex. knowledge można pominąć podczas lokalnej walidacji lub w środowisku development, ale jeśli występuje, musi zawierać dokładnie jedno źródło witryny. preview i production wymagają tego źródła. Jeśli występuje widget, pole widget.enabled jest wymagane.

Walidacja czyta tylko JSON, nie TypeScript, JSONC, YAML ani zdalny schemat. Nie wykonuje żądań sieciowych, nie sprawdza tokenu ani uprawnień planu i nie stosuje wartości domyślnych. Lokalny sukces nie gwarantuje wdrożenia. Zarówno walidator lokalny, jak i backend odrzucają nieznane pola na każdym poziomie obiektu. Wpisy include/exclude muszą być niepustymi ciągami. Skrót runtime.locale wybiera stały język bez nadpisywania i nie może być łączony z localeMode, defaultLocale ani allowLocaleOverride: true. Zakres tokenu i uprawnienia planu sprawdza serwer.

Tworzenie tokenu wdrażania​

Otwórz Ustawienia chatbota → Konfiguracja deweloperska, a następnie Tokeny wdrożeń konfiguracji. Utwórz token dla środowisk, które może zmieniać Twój proces. Skopiuj od razu pełny token — ChattyBox przechowuje jego skrót oraz ograniczone metadane identyfikacyjne i dotyczące cyklu życia; pełnego tokenu nie da się ponownie wyświetlić.

Formularz domyślnie zaznacza tylko development (etykieta w panelu: „Deweloperskie”) i „Nigdy nie wygasa”. Zaznacz jawnie preview lub production, jeśli proces ma zmieniać te środowiska.

Panel oferuje brak wygaśnięcia albo 7, 30, 90 lub 365 dni; uwierzytelnione API tworzenia przyjmuje liczbę całkowitą od 1 do 365 dni albo pominięcie pola, aby token nie wygasał. Projekt może mieć najwyżej 20 aktywnych, niewygasłych tokenów. Aby wykonać rotację, utwórz nowy token, zaktualizuj CI i unieważnij stary. CLI nie ma poleceń logowania ani tworzenia, listowania lub unieważniania tokenów.

Ustaw token i adres URL API widżetu. W Instalacja → Instalacja na stronie użyj data-api-url ze snippetu, jeśli jest dostępny; w przeciwnym razie pobierz adres URL wdrożenia HTTP actions z konfiguracji wdrożenia. Konfiguracja instalacji może wymagać wcześniejszego ukończenia przygotowania:

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Nigdy nie umieszczaj tokenu w kodzie przeglądarkowym ani nie zatwierdzaj go w repozytorium. Przechowuj go w zaszyfrowanym magazynie sekretów dostawcy CI. Token wdrożeniowy jest sekretem serwerowym używanym jako Authorization: Bearer ...; ograniczenia origin widżetu go nie chronią. Trasy zarządzania nie stosują ograniczeń origin widżetu, nie wymagają nagłówka Origin i nie udostępniają dostępu przez browser CORS. Token nie jest związany z originem — każdy, kto go posiada, może wywoływać API z serwera. Publiczne klucze widżetu nie zastępują tego tokenu.

Brakujący, niepoprawny, wygasły, unieważniony lub niedozwolony dla środowiska token zwraca HTTP 401 INVALID_TOKEN. Token przestaje działać także wtedy, gdy jego projekt lub właściciel nie istnieje albo jest usuwany.

Użyj głównego adresu wdrożenia HTTP actions albo adresu widżetu kończącego się na /chat, nie adresu klienta .convex.cloud ani pełnego endpointu /v1/config/deployments. CLI usuwa końcowe ukośniki i końcowe /chat, po czym dodaje trasę zarządzania. HTTPS jest wymagany poza localhost, 127.0.0.1 i [::1]; adres API z danymi logowania, query lub fragmentem jest odrzucany. Przed podaniem sekretu sprawdź adres docelowy.

Blokada konfiguracji​

Przed włączeniem blokady przetestuj cały przepływ wdrożenia z tokenem. W Ustawienia chatbota → Konfiguracja deweloperska kliknij Włącz blokadę konfiguracji. Blokada jest nieodwracalna w obecnym panelu, CLI i publicznym API — nie ma obsługiwanej operacji jej wyłączenia. Samo jej włączenie nie tworzy tokenu ani nie wdraża wersji.

Blokada uniemożliwia zapisywanie w panelu ustawień projektu i widżetu należących do konfiguracji, przesyłanie ikon oraz ręczne operacje na korpusie, takie jak skanowanie, usuwanie stron, czyszczenie treści i ponowne generowanie embeddingów. Nie zatrzymuje zaplanowanych zadań ani nie blokuje usunięcia projektu. Nadal można tworzyć i unieważniać tokeny, zarządzać kluczami publicznymi i odczytywać dane operacyjne.

Branding jest wyjątkiem: kontrola dotycząca wyłącznie brandingu pozostaje edytowalna w panelu zablokowanego projektu, o ile pozwala na to plan. Ukrycie oznaczenia ChattyBox wymaga planu Starter lub wyższego, także przy wdrożeniu konfiguracji. Pominięcie widget.showBranding zachowuje zapisaną preferencję (lub domyślne true); jawna wartość nadpisuje ją przy następnej promocji do runtime. Runtime w planie Free nadal wymusza branding.

Wdrażanie konfiguracji​

Wdrożenie tworzy niezmienną wersję i promuje ją do wybranego środowiska:

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

development jedynie zapisuje wersję i wskaźnik (applied: false, indexingStatus: "not_required"). Preview i production współdzielą ten sam runtime, korpus oraz publiczne klucze; najnowsza promocja wygrywa, nawet jeśli status innej etykiety nadal wskazuje starszą wersję. Token z zakresem preview może więc zmienić projekt obsługujący ruch produkcyjny. Użyj osobnych projektów oraz odpowiednich tokenów i kluczy dla faktycznej izolacji.

Preview/production atomowo stosują konfigurację i kolejkują skanowanie (applied: true, indexingStatus: "pending"), ale nie czekają na skanowanie ani embeddingi. Odświeżenie aktualizuje strony w miejscu i zleca embeddingi dla zmienionej treści; nie usuwa starych URL-i pominiętych w nowym źródle lub filtrze. Korpus nie jest wersjonowaną migawką: po błędzie mogą pozostać częściowe aktualizacje, a zastosowana konfiguracja nie jest cofana. Zadania zapisują ID wersji konfiguracji, ale odczytują również zmienne ustawienia skanowania; unikaj nakładających się wdrożeń, gdy spójność indeksowania ma znaczenie.

Użyj --json w automatyzacji, aby otrzymać version._id, wskaźnik środowiska, applied, indexingStatus oraz identyfikator zakolejkowanego zadania skanowania. Zachowaj version._id do późniejszej promocji lub rollbacku; widoczny numer wersji nie jest argumentem --version.

Status, promocja i rollback​

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
--version '<config-version-id>' \
--environment production

bunx @openstaticfish/chattybox-cli rollback \
--version '<known-good-config-version-id>' \
--environment production

--version przyjmuje nieprzezroczyste ID wersji z JSON: version._id z wyniku deploy/promote/rollback albo activeVersion._id z wyniku status — nie wyświetlany numer, SHA ani hash. Ujmij identyfikatory w cudzysłowy jak w przykładzie i zastąp je rzeczywistymi ID z projektu tokenu. Rollback używa tej samej operacji backendu co promocja, nie musi wskazywać starszej wersji i nie wybiera jej automatycznie. Zachowuje niezmienne rekordy wersji, ale nadpisuje wskaźnik wybranego środowiska i metadane promocji; nie istnieje historia zdarzeń promocji typu append-only. W preview lub production ponownie stosuje konfigurację przy bieżących uprawnieniach i kolejkuje odświeżenie, nie odtwarzając historycznego korpusu. Powtórne wdrożenia tworzą nowe wersje nawet dla tej samej konfiguracji; powtórne promocje mogą zakolejkować nowe zadania.

status pokazuje Environment version i podsumowanie wskaźnika wybranej etykiety, nie efektywną konfigurację runtime, różnice względem panelu ani postęp skanowania lub embeddingów. Dla niewdrożonej etykiety pokazuje Environment version: none oraz zwraca environment: null i activeVersion: null. runtimeConfigVersionId wskazuje ostatnią konfigurację zastosowaną do współdzielonego runtime i może się różnić po promocji innej etykiety. Promocja development go nie zmienia; przy wyłączonej blokadzie późniejsze zmiany w panelu mogą zmienić pola runtime bez zmiany tego ID. Udane sprawdzenie statusu aktualizuje lastUsedAt tokenu i zużywa limit żądań zarządzania. Postęp indeksowania sprawdź osobno w panelu.

Limity i pełna konfiguracja​

Promuj kompletną, docelową konfigurację, a nie patch: pominięte pola należące do konfiguracji są resetowane, także wcześniejsze ustawienia z panelu. Pominięcie całego obiektu widget włącza widżet; jeśli obiekt występuje, jego wymagane pole enabled jest respektowane. Pozostałe pominięte ustawienia wyglądu są czyszczone, aby zastosować wartości domyślne runtime. Pominięcie widget.icon przywraca ikonę domyślną w rozmiarze medium, a promocja do runtime usuwa wcześniej przesłany plik ikony — również wtedy, gdy zastępujesz go ikoną deklaratywną. widget.showBranding jest wyjątkiem: pominięcie zachowuje bieżącą preferencję (lub domyślne true), a jawna wartość nadpisuje ją przy promocji do runtime.

Jeśli podano maxPages, niezmienna wersja konfiguracji zachowuje żądaną wartość, a promocja do runtime ogranicza operacyjną konfigurację skanowania do 100 000. Gdy maxPages pominięto, wartością domyślną jest limit stron uwzględniony w planie konta: Free 10, Starter 150, Pro 5 000, Business 25 000.

W każdym przebiegu efektywny limit wyboru to mniejsza z wartości: żądane maxPages albo większa z bieżącej pojemności dostawcy i liczby istniejących stron projektu. Przyjmowanie nowych stron jest dodatkowo ograniczone osobnym limitem stron dla całego konta właściciela. Nie ma gwarancji, że zostaną zaindeksowane wszystkie żądane strony. Odkrywanie sitemap może pobierać dokumenty sitemap i wyliczać adresy URL przed wyborem stron, więc ani maxPages, ani dostępna pojemność nie stanowią granicy prywatności lub żądań wychodzących.

W trybie sitemap, jeśli pominięto sitemapUrl, system najpierw próbuje wykrytej sitemap, następnie /sitemap.xml i /sitemap_index.xml, a jeśli żadna nie zwróci adresów — zapisany adres strony. Daily auto-refresh i showBranding:false wymagają Starter+. Zakres tokenu preview/production nie izoluje runtime’u.

Pominięte project.description, profil, prompt i odpowiedź zastępcza asystenta usuwają zapisane nadpisania. Pominięte runtime przywraca automatyczny język, domyślny en i możliwość nadpisania. Pominięte filtry są czyszczone, a automatyczne odświeżanie domyślnie wyłączone; ustawienia zależne od trybu są stosowane tylko dla pasującego trybu. Free dopuszcza automatyczne odświeżanie tygodniowe lub miesięczne. Uprawnienia planu są sprawdzane przy promocji preview/production, także przy rollbacku, nie podczas lokalnej walidacji ani zapisu development; zmiana planu może uniemożliwić promocję wcześniej poprawnej wersji. Plan jest ustalany na podstawie danych projektu lub obszaru roboczego zapisanych w pamięci serwera, nie bieżącego zapytania do dostawcy rozliczeń. Po zmianie planu lub PAYG sprawdź osobno synchronizację rozliczeń i faktyczny limit skanowania.

Polecenia i błędy​

init [path] tworzy katalogi nadrzędne, ale nie nadpisuje istniejącego pliku; validate [path] tylko lokalnie weryfikuje JSON. Oba domyślnie używają chattybox.config.json i przyjmują co najwyżej jedną ścieżkę bez flag. deploy wymaga --environment i opcjonalnie przyjmuje --config <path>; promote i rollback wymagają --environment oraz --version <opaque-id>, a status wymaga --environment. Te trzy ostatnie nie odczytują lokalnej konfiguracji. Pomoc to help, --help lub -h na poziomie głównym, np. chattybox --help, nie chattybox deploy --help. Główne --version / -v oznacza wersję CLI, nie argument promocji.

Cztery polecenia zarządzania obsługują --token, --api-url i --json; jawne flagi mają pierwszeństwo przed CHATTYBOX_DEPLOY_TOKEN i CHATTYBOX_API_URL. Preferuj sekretne zmienne środowiskowe zamiast tokenów w historii powłoki lub argumentach procesu. Flagi z wartością przyjmują --flag value albo --flag=value; --json jest przełącznikiem bez wartości. Nie ma domyślnego środowiska. Nieznane, powtórzone, puste lub niepasujące do polecenia opcje są odrzucane.

Nie ma flag --dry-run, --wait, --force, --project, wiadomości ani kontroli współbieżności. HTTP API obsługuje pola oczekiwanej wersji, ale CLI ich nie wysyła; serializuj wdrożenia CI do tego samego projektu. Sukces kończy się kodem 0, a błędy pliku, JSON, walidacji, argumentów, transportu, odczytu odpowiedzi i HTTP — kodem 1 oraz komunikatem ChattyBox: ... na stderr. --json formatuje tylko udane wyniki, nie błędy. CLI nie ponawia żądań, nie odpytuje o postęp i nie ma skonfigurowanego limitu czasu żądania. Po błędzie transportu sprawdź status przed ponowieniem, bo serwer mógł już zatwierdzić wdrożenie.

Trasy zarządzania współdzielą limit 20 żądań na minutę na token; odpowiedź 429 zawiera Retry-After. Błędy obejmują m.in. 401 INVALID_TOKEN, 404 NOT_FOUND, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG i 500 INTERNAL_ERROR. Nieprawidłowy format typowanego ID daje 422, niekoniecznie 404. Limit treści żądania wynosi 262 144 bajty. Całkowicie brakująca treść POST obecnie prowadzi do 500, w przeciwieństwie do niepoprawnego JSON (422).

Przepływy pracy CI/CD​

Dodaj CHATTYBOX_DEPLOY_TOKEN jako zaszyfrowany sekret ograniczony do produkcji u dostawcy CI. Dodaj CHATTYBOX_API_URL jako sekret lub zmienną: użyj data-api-url z Instalacja → Instalacja na stronie, jeśli jest dostępny, albo adresu URL wdrożenia HTTP actions z konfiguracji wdrożenia. Uruchamiaj walidację dla pull requestów, ale ogranicz wdrożenia produkcyjne do chronionej gałęzi domyślnej lub zatwierdzonego środowiska wdrożeniowego.

GitHub Actions​

name: Deploy ChattyBox configuration

on:
pull_request:
push:
branches: [main]

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- uses: actions/setup-node@v6
with:
node-version: 24
- run: bunx @openstaticfish/chattybox-cli validate

deploy:
if: github.event_name == 'push'
needs: validate
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- uses: actions/setup-node@v6
with:
node-version: 24
- name: Validate and deploy
env:
CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
run: |
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli deploy --environment production --json

Użyj sekretu produkcyjnego przypisanego do środowiska i wymagaj zatwierdzenia wdrożenia, jeśli Twoje repozytorium to obsługuje. CLI zapisuje typowe zmienne CI dotyczące commita i gałęzi razem z niezmienną wersją.

GitLab CI/CD​

Przechowuj obie wartości w Settings → CI/CD → Variables. Chroń token wdrożenia, zamaskuj go i ogranicz go do środowiska production.

.gitlab-ci.yml
image: oven/bun:1

validate_chattybox:
stage: test
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
- bunx --bun @openstaticfish/chattybox-cli validate

deploy_chattybox:
stage: deploy
environment: production
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- bunx --bun @openstaticfish/chattybox-cli validate
- bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

GitLab automatycznie udostępnia zadaniu CHATTYBOX_DEPLOY_TOKEN i CHATTYBOX_API_URL, używając ich nazw zmiennych. Użyj chronionej gałęzi domyślnej, aby chronione zmienne nie były dostępne dla niezaufanych gałęzi.

Przykłady z kontenerem Bun jawnie używają --bun, więc nie wymagają osobnej instalacji Node. Sprawdź przypiętą wersję Bun i obrazu w swoim CI.

Bitbucket Pipelines​

Dodaj obie wartości jako zmienne wdrożeniowe w Repository settings → Pipelines → Deployments → Production. Oznacz token wdrożenia jako zabezpieczony.

bitbucket-pipelines.yml
image: oven/bun:1

pipelines:
pull-requests:
'**':
- step:
name: Validate ChattyBox configuration
script:
- bunx --bun @openstaticfish/chattybox-cli validate
branches:
main:
- step:
name: Deploy ChattyBox configuration
deployment: Production
script:
- bunx --bun @openstaticfish/chattybox-cli validate
- bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

Zastąp main, jeśli Twoja gałąź domyślna ma inną nazwę. Bitbucket wstrzykuje zmienne wdrożeniowe tylko do kroków powiązanych z tym środowiskiem wdrożeniowym. CLI nie ma osobnego mapowania metadanych BITBUCKET_*; korzysta z lokalnego Git, który w trybie detached checkout może nie podać nazwy gałęzi.

Sekcje konfiguracji​

SekcjaPrzeznaczenie
schemaVersionWybiera publiczny kontrakt konfiguracji. Obecnie obsługiwana jest wersja 1.
projectOpcjonalne metadane projektu, np. opis w panelu.
assistantOkreśla nazwę asystenta, wbudowaną personę lub własny prompt systemowy oraz odpowiedź zastępczą.
knowledge.sourcesWybiera tryb strony głównej, mapy witryny, ręcznych adresów lub crawlowania oraz limity, filtry i harmonogram.
runtimeSteruje automatycznym lub stałym językiem, językiem domyślnym i nadpisywaniem języka na stronie.
widgetSteruje włączeniem, pozycją, tekstem, kolorami i ikoną domyślną, emoji lub pod adresem URL.

Persony​

Ustaw promptProfile na default, support, sales lub sarcastic, aby użyć utrzymywanych instrukcji persony. Dla własnej persony ustaw custom i podaj systemPrompt. Jeśli podano zarówno wbudowany profil, jak i systemPrompt, pierwszeństwo ma jawny prompt.

Wykrywanie treści​

Ten przykład to wpis w knowledge.sources, a nie pełna konfiguracja. Wymaga opublikowanych pakietów CLI/config 0.3.1 i zgodnego kontraktu backendu 0.3.0. Codzienne odświeżanie wymaga planu Starter lub wyższego; maxPages: 500 jest żądaniem zależnym od dostępnej pojemności, a nie gwarancją indeksacji.

{
"type": "website",
"url": "https://docs.example.com",
"mode": "sitemap",
"sitemapUrl": "https://docs.example.com/docs-sitemap.xml",
"include": ["/docs/"],
"exclude": ["/private/"],
"maxPages": 500,
"autoRescrape": true,
"rescrapeInterval": "daily"
}

Tryb homepage wybiera tylko url do odświeżenia, nie usuwając istniejących stron. Tryb sitemap używa sitemapUrl; jawna mapa bez adresów powoduje błąd, natomiast po pominięciu adresu stosowana jest kolejność wykrywania opisana wyżej. Tryb manual indeksuje niepustą listę manualUrls. Tryb crawl najpierw próbuje standardowych map, a następnie przechodzi po linkach od url do maxDepth (domyślnie 3).

include i exclude dopasowują fragmenty adresu URL z uwzględnieniem wielkości liter, nie używają glob ani regex. Dowolne dopasowanie include dopuszcza adres, a dowolne dopasowanie exclude go odrzuca, nawet jeśli pasuje do include. Puste listy nie filtrują. Filtry obejmują także stronę główną i ręczny wybór.

maxPages musi być dodatnią liczbą całkowitą; zapisana wersja zachowuje żądanie, ale konfiguracja runtime i wybór podlegają limitom opisanym wyżej. Wykrywanie map może wyliczać adresy przed wyborem. maxDepth musi być liczbą całkowitą od 0 do 20 i steruje awaryjnym przechodzeniem po linkach, nie wyliczaniem map. Pominięte mode wybiera crawl i zachowuje jawne maxDepth, także zero. autoRescrape: true wymaga rescrapeInterval: "daily", "weekly" lub "monthly"; sam interwał nie włącza harmonogramu. Miesiąc oznacza 30 dni, a zadanie może uruchomić się później niż termin.

Walidacja języka i widżetu​

Obsługiwane kody to en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy i id. localeMode to auto albo fixed; tryb stały wymaga defaultLocale. allowLocaleOverride można ustawić niezależnie, z wyjątkiem ograniczeń skrótu runtime.locale opisanych wyżej.

Pozycje widżetu to bottom-right, bottom-left, top-right i top-left. Trzy kolory motywu wymagają formatu #RRGGBB, bez skróconego zapisu, nazw kolorów ani kanału alfa. Ikona ma typ default, emoji z niepustym ciągiem emoji albo url z adresem HTTP(S) url i opcjonalny rozmiar small, medium lub large. Walidacja nie pobiera ikon, nie sprawdza typu MIME i nie wymaga dokładnie jednego emoji. Sprawdza składnię i protokół adresów źródeł i ikon, nie ich dostępność ani uprawnienia do skanowania. Opcjonalny opis, prompt i odpowiedź zastępcza asystenta oraz tytuł i powitanie widżetu muszą być niepuste, jeśli je podano; aby usunąć nadpisanie, pomiń je.

Typowany pomocnik konfiguracji​

Zainstaluj pakiet konfiguracyjny, jeśli tworzysz osobne narzędzia TypeScript korzystające ze schematu:

bun add -d @openstaticfish/chattybox-config
import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
schemaVersion: '1',
assistant: { name: 'Support' },
knowledge: {
sources: [{ type: 'website', url: 'https://docs.example.com' }],
},
widget: { enabled: true },
});

Samo CLI odczytuje pliki JSON. defineConfig() jest przeznaczone dla typowanych aplikacji lub narzędzi kompilacji; nie umożliwia CLI bezpośredniego wczytywania plików TypeScript.

Zarówno defineConfig(config), jak i validateConfig(config) walidują synchronicznie, zgłaszają zwykły Error przy pierwszym błędzie i zwracają ten sam obiekt bez klonowania, zamrażania, przekształcania wartości ani dodawania domyślnych. Pakiet eksportuje typy TypeScript i te funkcje, a nie dokument JSON Schema ani adres $schema. Opublikowany pakiet 0.3.1 udostępnia typy dla rozszerzonych pól opisanych powyżej.

Aby już dziś uzyskać działającą integrację produkcyjną, użyj hostowanego widżetu lub zbuduj własny interfejs za pomocą SDK JavaScript.