CLI a nasazování konfigurace
Publikované CLI/config artefakty verze 0.3.1 implementují konfigurační/backendový kontrakt 0.3.0 a lokálně i na backendu odmítají neznámé klíče.
CLI vytváří, ověřuje, nasazuje, propaguje a vrací neměnné verze konfigurace ChattyBoxu. Nasazovací tokeny jsou omezené na jeden projekt a vybraná prostředí, takže stejný postup je vhodný pro místní vývoj i CI.
Jeden konfigurační soubor a jeden token omezený na projekt berte jako jeden spravovaný projekt ChattyBox. Projekt je nejprve nutné jednorázově vytvořit v dashboardu.
Stav vydání a runtime
Publikované jsou @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 a samostatně publikovaný JavaScriptový klient @openstaticfish/chattybox@0.1.4. Rozšířenou konfiguraci podporují balíčky CLI a config 0.3.1 společně s konfiguračním/backendovým kontraktem 0.3.0; SDK je samostatný klientský balíček a nepatří mezi artefakty podporující tento kontrakt. schemaVersion: "1" není verze balíčku. status ukazuje verzi prostředí, kdežto runtimeConfigVersionId je poslední konfigurace použitá pro sdílený runtime a může se lišit. Vynechané mode zvolí crawl a zachová explicitní maxDepth: 0. CLI je program ESM a vyžaduje Node.js 20 nebo novější. bunx ve výchozím nastavení respektuje Node shebang, proto mějte nainstalovaný Node, nebo výslovně zvolte Bun pomocí bunx --bun @openstaticfish/chattybox-cli ....
V produkční automatizaci připněte otestovanou verzi balíčku. Příklady bez uvedené verze používají balíček z lokální instalace či mezipaměti nebo z registru, nikoli zdrojový kód tohoto repozitáře.
Základní konfigurace a příkazy níže jsou součástí publikovaného CLI. Přibalený validátor pokrývá project, nastavení vyhledávání a plánování, rozšířené nastavení jazyka, widget.icon a widget.showBranding. CLI není nástroj pro prohlížeč; CI pro publikované balíčky ověřuje Node 20, 22 a 24 na Linuxu, nikoli obecnou kompatibilitu operačních systémů nebo prohlížečů.
Co spravuje konfigurace jako kód
Konfigurace řídí název a popis projektu, personu a záložní chování asistenta, vyhledávání a obnovu obsahu webu, jazyk a vzhled hostovaného widgetu. Nasazení do preview nebo production tyto hodnoty použije a zařadí aktualizaci stávajícího korpusu. Při zapnutém zámku konfigurace se spravovaná nastavení mění verzovaným nasazením, s výjimkou předvolby brandingu omezené tarifem.
Veřejné klíče widgetu a jejich volitelná omezení originů, správa nasazovacích tokenů, analytika, konverzace, mezery v obsahu, destruktivní akce ani nahrané soubory ikon nejsou konfigurační pole. Pro deklarativní vlastní ikonu použijte URL nebo emoji. Konfigurace neobsahuje ID projektu: projekt vybírá tajný nasazovací token.
Veřejný klíč widgetu pro chat a jeho konfiguraci smí být v kódu prohlížeče. Klíč bez omezení funguje napříč originy prohlížeče; klíč připravený pro web již může být omezený. Omezení originů je volitelná dodatečná ochrana, nikoli ověřování návštěvníků. Nasazovací token pro deploy, promote, rollback a status jednoho projektu a vybraných prostředí do prohlížeče nepatří; uchovávejte jej jako tajný údaj lokálně nebo v CI.
Vytvoření konfigurace
bunx @openstaticfish/chattybox-cli init
Tím se vytvoří soubor chattybox.config.json:
{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}
Pokud konfigurace patří do podadresáře, použijte vlastní cestu:
bunx @openstaticfish/chattybox-cli init config/chattybox.config.json
Místní ověření nebo ověření v CI
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json
Validace čte jen JSON, nepouští síť, nekontroluje token či tarif a nenastavuje defaults. Lokální úspěch není záruka nasazení; lokální validátor i backend však neznámá pole odmítnou.
Validace aktuálního zdrojového kódu kontroluje strukturu objektů, povinný název asistenta, výčtové hodnoty, HTTP(S) URL, celočíselné limity, kombinace jazyků a šestimístné hexadecimální barvy. knowledge lze pro místní validaci nebo development vynechat; je-li uvedeno, musí obsahovat právě jeden webový zdroj. Preview a production tento zdroj vyžadují. Pokud je uveden widget, je povinné widget.enabled.
Validátor nenačítá TypeScript, JSONC, YAML ani vzdálené schéma. Schéma v1 odmítá neznámá pole na všech úrovních včetně překlepů a libovolných rozšíření. Položky include/exclude musí být neprázdné řetězce. Zkratka runtime.locale nastavuje pevný jazyk bez přepsání a nelze ji kombinovat s localeMode, defaultLocale ani allowLocaleOverride: true. Oprávnění podle tarifu a rozsah tokenu kontroluje server.
Vytvoření nasazovacího tokenu
Otevřete Nastavení chatbota → Vývojářská konfigurace a najděte Tokeny pro nasazení konfigurace. Vytvořte token pro prostředí, která může váš pracovní postup měnit. Ihned zkopírujte celý token — ChattyBox uchovává jeho hash a omezená identifikační metadata a metadata životního cyklu, celý token však znovu nezobrazí.
Formulář ve výchozím nastavení vybírá pouze development (v nástěnce označené „Vývoj“) a „Nikdy nevyprší“. Pokud má pracovní postup měnit také preview nebo production, vyberte tyto rozsahy výslovně.
Dashboard nabízí neomezenou platnost nebo 7, 30, 90 či 365 dní; autentizované API pro vytvoření přijímá celé číslo od 1 do 365 dní nebo vynechání pro neomezenou platnost. Projekt může mít nejvýše 20 aktivních neprošlých tokenů. Při rotaci vytvořte náhradu, aktualizujte CI a starý token odvolejte. CLI nemá příkazy pro přihlášení ani vytvoření, výpis či odvolání tokenů.
Nastavte token a URL API widgetu. V Instalace → Instalace na web použijte data-api-url z instalačního úryvku, pokud je k dispozici; jinak získejte URL nasazení HTTP actions z konfigurace nasazení. Nejdříve může být nutné dokončit přípravu instalace:
export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'
Token nikdy nevkládejte do kódu prohlížeče ani ho necommitujte. Uložte ho do šifrovaného úložiště tajných údajů poskytovatele CI. Nasazovací token je serverové tajemství používané jako Authorization: Bearer ...; omezení originů widgetu ho nechrání. Správcovské routy omezení originů widgetu nepoužívají, nevyžadují hlavičku Origin a neposkytují přístup přes browser CORS. Token není vázaný na origin — kdokoli, kdo ho má, může volat API ze serveru. Veřejné klíče widgetu tento token nenahrazují.
Chybějící, nesprávně utvořené, prošlé, odvolané, pro dané prostředí neplatné i jinak neplatné tokeny vracejí HTTP 401 INVALID_TOKEN. Token přestane fungovat také při chybějícím nebo mazaném projektu či vlastníkovi.
Použijte kořen nasazení HTTP actions nebo URL widgetu končící na /chat, nikoli klientskou URL .convex.cloud ani úplný endpoint /v1/config/deployments. CLI odstraní koncová lomítka a případné /chat a připojí správcovskou cestu. Vyžaduje HTTPS s výjimkou localhost, 127.0.0.1 a [::1]; URL s přihlašovacími údaji, query nebo fragmentem odmítá. Před předáním tajného údaje ověřte cíl.
Před zapnutím zámku otestujte celý nasazovací postup s tokenem. V Nastavení chatbota → Vývojářská konfigurace klikněte na Povolit zámek konfigurace. Zámek je v současném dashboardu, CLI i veřejném API nevratný — neexistuje podporovaný způsob jeho vypnutí. Jeho zapnutí nevytvoří token ani nenasadí verzi.
Zámek blokuje zápisy konfiguračních nastavení projektu a widgetu z dashboardu, nahrávání ikon a ruční operace s korpusem, jako je scraping, mazání stránek, mazání veškerého obsahu a opětovné generování embeddingů. Nezastaví naplánované úlohy ani nebrání smazání projektu. Vytváření a odvolávání tokenů, správa veřejných klíčů a provozní čtení zůstávají dostupné.
Branding je výjimkou: ovládací prvek pouze pro branding zůstává v dashboardu uzamčeného projektu upravitelný, pokud to tarif dovoluje. Skrytí označení ChattyBox vyžaduje tarif Starter nebo vyšší, a to i při nasazení konfigurace. Vynechání widget.showBranding zachová uloženou preferenci (nebo výchozí true); explicitní hodnota ji přepíše při příští propagaci do runtime. Runtime tarifu Free branding stále vynucuje.
Nasazení konfigurace
Nasazení vytvoří neměnnou verzi a propaguje ji do vybraného prostředí:
bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production
development pouze zaznamená verzi a ukazatel (applied: false, indexingStatus: "not_required"). Preview a production sdílejí stejný runtime, korpus i veřejné klíče; vyhraje poslední propagace, i když ukazatel druhého prostředí stále míří na starší verzi. Token s rozsahem preview tak může změnit projekt obsluhující produkční provoz. Pro skutečnou izolaci použijte samostatné projekty a jejich tokeny a klíče.
Preview a production atomicky použijí konfiguraci a zařadí scrape (applied: true, indexingStatus: "pending"), ale nečekají na dokončení scrapování ani embeddingů. Obnova aktualizuje stránky na místě a při změně obsahu zařadí embeddingy; staré URL pouze kvůli vynechání z nového zdroje či filtru nemaže. Korpus není verzovaný snapshot: po chybě mohou zůstat částečné změny a použitá konfigurace se nevrátí. Úlohy zaznamenávají ID verze konfigurace, ale čtou také měnitelné nastavení scrapingu; pokud záleží na konzistenci indexace, nepřekrývejte nasazení.
V automatizaci použijte --json, abyste získali version._id, ukazatel prostředí, applied, indexingStatus a ID případně zařazené úlohy scrapingu. version._id si uchovejte pro propagaci nebo rollback; zobrazované pořadové číslo verze nelze použít jako argument --version.
Stav, propagace a návrat
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 přijímá neprůhledné ID verze z JSON: version._id z výsledku deploy/promote/rollback nebo activeVersion._id z výsledku status — nikoli zobrazené číslo, SHA ani hash. Zástupná ID jako v příkladu uvozujte a nahraďte skutečnými ID projektu daného tokenu. Rollback používá stejnou backendovou operaci jako promote, nemusí mířit na starší verzi a nevybírá ji automaticky. Zachovává neměnné záznamy verzí, ale přepisuje ukazatel vybraného prostředí i metadata propagace; historie událostí propagace se neuchovává jako append-only záznam. Rollback preview/production znovu použije konfiguraci podle aktuálních oprávnění tarifu a zařadí obnovení, nikoli přesnou obnovu historického korpusu. Opakovaný deploy vytvoří novou verzi i pro stejnou konfiguraci; opakovaná propagace může zařadit nové úlohy.
status ukazuje verzi a souhrn ukazatele vybraného prostředí, nikoli účinnou runtime konfiguraci, rozdíly oproti dashboardu ani průběh scrapování či embeddingů. Pro nenasazené prostředí zobrazí Environment version: none a vrátí environment: null a activeVersion: null. runtimeConfigVersionId označuje poslední konfiguraci použitou ve sdíleném runtime a po propagaci jiného prostředí se může lišit. Development tento ukazatel runtime nemění; bez zámku mohou pozdější úpravy v dashboardu změnit runtime i bez změny ID. Úspěšný status také aktualizuje lastUsedAt tokenu a čerpá kapacitu limitu správcovských požadavků. Indexaci kontrolujte zvlášť v dashboardu.
Úplná konfigurace a limity
Propagujte úplnou požadovanou konfiguraci, ne patch: vynechaná pole spravovaná konfigurací se resetují, včetně dřívějších nastavení z dashboardu. Není-li celý objekt widget uveden, widget se zapne; je-li uveden, respektuje se jeho povinná hodnota enabled. Ostatní vynechaná nastavení vzhledu se vymažou, takže se použijí výchozí hodnoty runtime. Vynechání widget.icon obnoví výchozí ikonu střední velikosti a propagace do runtime smaže dříve nahraný soubor ikony — i když ho nahrazujete deklarativní ikonou. widget.showBranding je výjimkou: při vynechání zachová aktuální preferenci (nebo výchozí true); explicitní hodnota ji přepíše při propagaci do runtime.
Pokud je maxPages zadáno, neměnná verze konfigurace uchovává požadovanou hodnotu, ale propagace do runtime omezí provozní konfiguraci scrapingu na 100 000. Při vynechání maxPages se jako výchozí hodnota použije počet stránek zahrnutý v tarifu účtu: Free 10, Starter 150, Pro 5 000, Business 25 000.
Efektivní limit výběru v každém běhu je menší z hodnot: požadované maxPages nebo větší z aktuální kapacity poskytovatele a počtu existujících stránek projektu. Přijetí nových stránek navíc samostatně omezuje limit stránek pro celý účet vlastníka. Není zaručeno, že se zaindexují všechny požadované stránky. Vyhledávání sitemap může před výběrem stahovat dokumenty sitemap a vypisovat URL, takže maxPages ani dostupná kapacita nejsou hranicí ochrany soukromí či odchozích požadavků.
V režimu sitemap, pokud není zadáno sitemapUrl, systém nejprve zkusí nalezenou sitemap, poté /sitemap.xml a /sitemap_index.xml, a pokud žádná nevrátí adresy URL, uloženou adresu webu. Daily auto-refresh a showBranding:false vyžadují Starter+. Rozsah tokenu preview/production runtime neizoluje.
Při vynechání project.description či pokynů, profilu nebo fallbacku asistenta se uložené přepisy vymažou. Vynechaný runtime se vrátí na automatický jazyk, výchozí en a povolené přepsání. Výchozí režim zdroje je crawl, vynechané filtry se vymažou a automatická obnova je ve výchozím stavu vypnutá; nastavení konkrétního režimu se použije pouze pro odpovídající režim.
Požadavek na počet stránek nepřidává oprávnění tarifu ani kapacitu sdílenou vlastníkem; scrape znovu kontroluje aktuální limit stránek/PAYG a měsíční rozpočet obnovy. Free připouští týdenní nebo měsíční automatickou obnovu. Oprávnění tarifu se kontrolují při propagaci preview/production včetně rollbacku, nikoli při místní validaci nebo zaznamenání development; dříve platná verze proto může po změně tarifu při propagaci selhat. Tarif se určuje z dat projektu či pracovního prostoru uložených v serverové cache, nikoli živým dotazem na poskytovatele fakturace. Při nedávné změně tarifu či PAYG ověřte synchronizaci fakturace a skutečný limit scrapingu zvlášť.
Příkazy, volby a chyby
init [path] vytvoří případné nadřazené adresáře a existující soubor nepřepíše; validate [path] lokálně ověřuje JSON. Oba používají výchozí chattybox.config.json. deploy vyžaduje --environment a volitelně přijímá --config <path>; promote a rollback vyžadují --environment a --version <opaque-id>; status vyžaduje --environment. Poslední tři nečtou místní konfiguraci. Nápovědu vyvoláte bez příkazu nebo pomocí help, --help či -h na nejvyšší úrovni, například chattybox --help, nikoli chattybox deploy --help. Nejvyšší --version nebo -v udává verzi CLI, nikoli verzi konfigurace pro propagaci.
Všechny čtyři správcovské příkazy přijímají --token, --api-url a --json; výslovné volby mají přednost před CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL. Upřednostněte tajné proměnné prostředí před tokeny v historii shellu či argumentech procesu. Hodnoty lze zadat jako --flag value nebo --flag=value, --json je samostatný přepínač. Výchozí prostředí neexistuje. Neznámé, duplicitní, prázdné či pro příkaz nepoužitelné správcovské volby se odmítají; místní příkazy přijímají jen jednu poziční cestu a odmítají volby i další argumenty.
CLI nemá --dry-run, --wait, --force, --project, volbu zprávy ani volbu optimistické kontroly souběhu. HTTP API podporuje pole očekávané verze, ale CLI je neposílá; nasazení CI do stejného projektu provádějte sériově. Úspěšné příkazy končí kódem 0; chyby souboru, JSON, validace, argumentů, přenosu, čtení odpovědi a HTTP končí kódem 1 se zprávou ChattyBox: ... na stderr. --json formátuje pouze úspěchy, nikoli chyby. CLI odmítá úspěšné odpovědi, které nejsou JSON; automaticky neopakuje požadavky, nečeká na dokončení a nemá nastavený timeout. Po chybě přenosu před opakováním zkontrolujte stav: server již mohl nasazení potvrdit.
Správcovské routy jsou POST /v1/config/deployments (201), POST /v1/config/deployments/promote a /rollback (200) a GET /v1/config/deployments/status?environment=... (200). Úspěch HTTP je zabalen do { "data": ... }, který CLI v JSON výstupu rozbalí. Chyby obvykle používají { "error": { "code": ..., "message": ... } }: 401 INVALID_TOKEN, 404 NOT_FOUND, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG nebo 500 INTERNAL_ERROR. Nesprávně utvořená typovaná ID vracejí 422, ne nutně 404. Limit těla je 262 144 bajtů; routy sdílejí limit 20 požadavků za minutu na token a při 429 vracejí Retry-After. Úplně chybějící tělo POST nyní vrací 500, na rozdíl od chybného JSON (422).
CI/CD workflow
Přidejte CHATTYBOX_DEPLOY_TOKEN jako šifrovaný tajný údaj s rozsahem na produkci u svého poskytovatele CI. Přidejte CHATTYBOX_API_URL jako tajný údaj nebo proměnnou: použijte data-api-url z Instalace → Instalace na web, pokud je k dispozici, nebo URL nasazení HTTP actions z konfigurace nasazení. Spouštějte validaci v pull requestech, ale nasazení do produkce omezte na chráněnou výchozí větev nebo schválené nasazovací prostředí.
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
Použijte produkční tajný údaj omezený na prostředí a vyžadujte schválení nasazení, pokud to váš repozitář podporuje. CLI zaznamenává běžné CI proměnné commitu a větve spolu s neměnnou verzí.
GitLab CI/CD
Obě hodnoty uložte v Settings → CI/CD → Variables. Token nasazení chraňte, zamaskujte a omezte jeho rozsah na prostředí production.
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 automaticky zpřístupňuje CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL úloze pod jejich názvy proměnných. Použijte chráněnou výchozí větev, aby chráněné proměnné nebyly dostupné nedůvěryhodným větvím.
Příklady v kontejneru Bun výslovně používají --bun, aby nezávisely na samostatné instalaci Node; ověřte připnutou verzi Bun a image ve svém CI.
Bitbucket Pipelines
Přidejte obě hodnoty jako proměnné nasazení v Repository settings → Pipelines → Deployments → Production. Označte token nasazení jako zabezpečený.
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
Nahraďte main, pokud má vaše výchozí větev jiný název. Bitbucket vkládá proměnné nasazení pouze do kroků přidružených k danému nasazovacímu prostředí. CLI nemá zvláštní mapování metadat BITBUCKET_*; commit a větev zjišťuje z místního Gitu, kde při odpojeném checkoutu nemusí být název větve dostupný.
Části konfigurace
| Část | Účel |
|---|---|
schemaVersion | Vybírá veřejný konfigurační kontrakt. V současnosti je podporována verze 1. |
project | Volitelná metadata projektu, například popis v dashboardu. |
assistant | Pojmenovává asistenta a určuje vestavěnou personu nebo vlastní systémový pokyn a text záložní odpovědi. |
knowledge.sources | Vybírá domovskou stránku, sitemapu, ruční URL nebo crawl včetně limitů, filtrů a plánu obnovy. |
runtime | Řídí automatický či pevný jazyk, výchozí jazyk a možnost jeho přepsání na stránce. |
widget | Řídí zapnutí, umístění, texty, barvy a výchozí ikonu, emoji nebo ikonu z URL. |
Persony
Pro udržované pokyny nastavte promptProfile na default, support, sales nebo sarcastic. Pro vlastní personu nastavte custom a zadejte systemPrompt. Pokud zadáte vestavěný profil i systemPrompt, přednost má výslovný pokyn.
Vyhledávání zdrojů
Tento příklad je jedna položka v knowledge.sources, nikoli úplná konfigurace. Vyžaduje vydané balíčky CLI/config 0.3.1 a odpovídající backendový kontrakt 0.3.0. Denní aktualizace vyžaduje plán Starter nebo vyšší; maxPages: 500 je požadavek omezený dostupnou kapacitou, nikoli záruka indexování.
{
"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"
}
Rozšířená nastavení vyžadují publikované typy konfigurace 0.3.1 a odpovídající backendový kontrakt 0.3.0. Denní plán vyžaduje Starter nebo vyšší; požadovaný maxPages nadále podléhá skutečné kapacitě daného běhu.
homepage: vybere pro obnovu jenurl; existující stránky nesmaže.sitemap: použijesitemapUrl; výslovně zadaná sitemap bez URL způsobí chybu. Při vynechání se zkusí nalezená sitemap, pak/sitemap.xmla/sitemap_index.xml, a nakonec uložená URL webu, pokud žádná nevrátí URL.manual: indexuje neprázdný seznammanualUrls.crawl: zkusí obvyklé sitemapy a potom sleduje odkazy odurldo hloubkymaxDepth(výchozí3).
include a exclude porovnávají podřetězce URL s rozlišením velikosti písmen, nikoli globy ani regulární výrazy. Shoda s libovolnou položkou include URL připustí, shoda s exclude ji odmítne i při shodě s include. Prázdné seznamy nefiltrují; filtry platí i pro homepage a ruční výběr.
maxPages musí být kladné celé číslo; neměnná verze zachová požadovanou hodnotu, provozní konfigurace a výběr podléhají výše uvedeným limitům. Vyhledávání v sitemapách může URL zjišťovat před výběrem. maxDepth musí být celé číslo od 0 do 20 a řídí záložní procházení odkazů, nikoli výpis sitemap. Vynechaný mode zvolí crawl a zachová výslovný maxDepth, včetně nuly. autoRescrape: true vyžaduje rescrapeInterval: "daily", "weekly" nebo "monthly"; samotný interval plánování nezapne. Měsíční interval znamená 30 dní a plánovač může úlohu spustit později.
Ověření jazyka a widgetu
Podporované kódy jsou en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy a id. localeMode je auto nebo fixed; pevný režim vyžaduje defaultLocale. allowLocaleOverride lze nastavit nezávisle. Zkratka runtime.locale volí pevný režim a vypíná přepsání; aktuální místní validátor odmítá její kombinaci s localeMode, defaultLocale nebo allowLocaleOverride: true.
Umístění widgetu jsou bottom-right, bottom-left, top-right a top-left. Všechny tři barvy používají #RRGGBB, nikoli zkrácený hex, názvy barev ani alfa kanál. Ikony jsou default, emoji (neprázdný řetězec emoji) nebo url (HTTP(S) url), s volitelnou velikostí small, medium nebo large. Validace nestahuje URL ikon, nekontroluje MIME typ obrázků ani nevyžaduje právě jedno emoji. U URL zdrojů a ikon kontroluje syntaxi a protokol, nikoli dostupnost či oprávnění k procházení. Volitelný popis, pokyn a fallback asistenta, titulek widgetu a uvítací text musí být při zadání neprázdné; přepisy vymažete jejich vynecháním.
Pomocná funkce pro typovanou konfiguraci
Při vytváření samostatných nástrojů TypeScript nad schématem nainstalujte konfigurační balíček:
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 },
});
Samotné CLI čte soubory JSON. defineConfig() je určené pro typované aplikační nebo sestavovací nástroje; neumožňuje CLI přímo načítat soubory TypeScript.
defineConfig(config) i validateConfig(config) ověřují synchronně, při první chybě vyhodí běžnou Error a vracejí stejný objekt bez klonování, zmrazení, převodu hodnot nebo doplnění výchozích hodnot. Balíček exportuje typy TypeScript a tyto funkce, nikoli dokument JSON Schema ani URL $schema. Publikovaný balíček 0.3.1 podporuje výše uvedená rozšířená pole v TypeScriptu.
Pro funkční produkční integraci dnes použijte hostovaný widget nebo vytvořte vlastní rozhraní pomocí JavaScript SDK.