CLI e distribuzione della configurazione
Gli artefatti CLI/config pubblicati nella versione 0.3.1 implementano il contratto di configurazione/backend 0.3.0 e rifiutano le chiavi sconosciute sia in locale sia nel backend.
La CLI crea, convalida, distribuisce, promuove ed esegue il rollback di versioni immutabili della configurazione ChattyBox. Ogni token di deployment è limitato a un solo progetto esistente e agli ambienti selezionati. Considera un file di configurazione e un token limitato al progetto come un unico progetto ChattyBox gestito.
Stato di release e runtime
Il registro pubblico offre @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 e l’SDK JavaScript separato @openstaticfish/chattybox@0.1.4. Questi artefatti supportano i campi ampliati insieme al contratto backend 0.3.0; status mostra la versione dell’ambiente, mentre runtimeConfigVersionId identifica l’ultima configurazione applicata al runtime condiviso e può essere diverso. Se mode è omesso, viene scelto crawl e un maxDepth: 0 esplicito resta invariato. schemaVersion: "1" appartiene a un sistema di versionamento distinto.
La configurazione iniziale e i comandi di base qui sotto sono disponibili nella CLI pubblicata. Anche il riferimento esteso alla configurazione è supportato dai pacchetti CLI/config 0.3.1 e dal corrispondente contratto backend 0.3.0. Il validatore incluso copre project, i campi di rilevamento e pianificazione, i controlli estesi della lingua, widget.icon e widget.showBranding.
La CLI è un programma ESM da riga di comando e richiede Node.js 20 o versioni successive. Per impostazione predefinita bunx rispetta lo shebang Node: installa Node oppure seleziona esplicitamente Bun con bunx --bun @openstaticfish/chattybox-cli .... La CLI non è uno strumento per browser. La CI per i pacchetti pubblicati copre Node 20, 22 e 24 su Linux, non una matrice generale di compatibilità con sistemi operativi o browser. Nelle automazioni di produzione blocca una versione del pacchetto già testata; gli esempi senza versione usano il pacchetto installato, presente nella cache o nel registro, non il codice sorgente di questo repository.
Cosa gestisce la configurazione come codice
La configurazione controlla nome e descrizione del progetto, Persona e fallback dell'assistente, rilevamento e aggiornamento del sito, lingua e presentazione del widget ospitato. Un deployment in preview o production applica questi valori e accoda un aggiornamento del corpus in loco. Con il blocco della configurazione attivo, le impostazioni gestite dalla configurazione vengono modificate tramite deployment versionati invece che nei moduli della dashboard, con l'eccezione della preferenza di branding soggetta ai diritti del piano.
La creazione iniziale del progetto richiede attualmente un'operazione una tantum nella dashboard. Credenziali e dati operativi restano fuori dalla configurazione: chiavi pubbliche del widget e restrizioni facoltative delle origini, gestione dei token di deployment, analisi, conversazioni e lacune nei contenuti, azioni distruttive e file di icone caricati non sono campi di configurazione. Per un'icona personalizzata dichiarativa usa un URL o un'emoji. La configurazione non contiene volutamente un ID di progetto: il token di deployment segreto seleziona l'unico progetto destinatario.
| Credenziale | Ambito | Sicura nel codice del browser? |
|---|---|---|
| Chiave API pubblica del widget | Chat e configurazione del widget | Sì; una chiave creata senza restrizioni funziona tra origini del browser, mentre una preparata per un sito può essere già limitata. Le restrizioni esatte delle origini sono una difesa facoltativa aggiuntiva, non un'autenticazione dei visitatori. |
| Token di deployment della configurazione | Deploy/promote/rollback/status della configurazione per un progetto e le etichette di ambiente selezionate | No; conservalo tra i secret locali o della CI. |
Creare una configurazione
bunx @openstaticfish/chattybox-cli init
Questo comando crea chattybox.config.json:
{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}
Utilizza un percorso personalizzato quando la configurazione deve trovarsi in una sottodirectory:
bunx @openstaticfish/chattybox-cli init config/chattybox.config.json
Convalidare in locale o nella CI
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json
La convalida del codice sorgente corrente verifica la struttura degli oggetti, il nome obbligatorio dell'assistente, i valori enumerati, gli URL HTTP(S), i limiti interi, le combinazioni di lingue e i colori esadecimali a sei cifre. Una convalida riuscita non esegue il deployment e non modifica lo stato remoto.
La convalida legge solo JSON: non carica TypeScript, JSONC, YAML o uno schema remoto. Non effettua richieste di rete, non verifica token o diritti del piano e non applica valori predefiniti. La configurazione knowledge può essere omessa per la convalida locale o lo sviluppo, ma, se presente, deve contenere esattamente una fonte di tipo sito web; preview e production richiedono tale fonte. Se widget è presente, widget.enabled è obbligatorio. Il successo in locale non garantisce il deployment.
Lo schema v1 rifiuta campi sconosciuti a ogni livello. Le voci di inclusione ed esclusione devono essere stringhe non vuote. runtime.locale imposta una lingua fissa senza override e non può essere combinato con localeMode, defaultLocale o allowLocaleOverride: true. I diritti del piano e l'ambito del token sono verificati dal server.
Creare un token di deployment
Apri Impostazioni del chatbot → Configurazione per sviluppatori e cerca Token di deployment della configurazione. Crea un token per gli ambienti che il flusso di lavoro deve poter modificare. Copia subito il token completo: ChattyBox ne conserva un hash e solo metadati identificativi e relativi al ciclo di vita limitati, quindi non può mostrare di nuovo il token completo.
Il modulo seleziona inizialmente solo development e non imposta una scadenza. Se necessario, seleziona esplicitamente preview o production. Nel dashboard puoi scegliere nessuna scadenza oppure 7, 30, 90 o 365 giorni; l’API autenticata accetta un numero intero da 1 a 365 giorni o nessuna scadenza. Ogni progetto può avere al massimo 20 token attivi e non scaduti. Per ruotare un token, creane uno nuovo, aggiorna la CI e revoca quello precedente. Non esistono comandi CLI per accedere o creare, elencare o revocare token.
Imposta il token e l’URL API del widget. In Installa → Installazione sul sito web, usa data-api-url dello snippet, se disponibile; altrimenti recupera l’URL di deployment HTTP actions dalla configurazione di deployment. Potrebbe essere necessario completare prima la configurazione dell’installazione:
export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'
Non eseguire mai il commit del token. È una credenziale segreta Bearer da usare solo lato server: conservala nei secret crittografati del provider CI e non inserirla nel codice del browser. Gli endpoint di gestione non usano le restrizioni di origine del widget, non richiedono un header Origin e non consentono l’accesso CORS dal browser. Il token non è vincolato all’origine: chiunque ne entri in possesso può chiamare l’API da un server. Le chiavi pubbliche del widget non possono sostituirlo. I token mancanti, malformati, scaduti, revocati, non autorizzati per l’ambiente o altrimenti non validi restituiscono HTTP 401 INVALID_TOKEN; smettono inoltre di funzionare se il progetto o il proprietario non esistono più o sono in fase di eliminazione.
Usa la radice di deployment HTTP actions o l’URL del widget che termina con /chat, non un URL client .convex.cloud né un endpoint completo /v1/config/deployments. La CLI rimuove le barre finali e l’eventuale /chat, poi aggiunge l’endpoint di gestione. È richiesto HTTPS, tranne per localhost, 127.0.0.1 o [::1]; nell’URL API non sono ammesse credenziali, query o frammenti. Verifica la destinazione prima di fornire un secret.
Blocco della configurazione
Dopo aver verificato il flusso di deployment, puoi attivare Blocco della configurazione nella stessa sezione. È irreversibile nel dashboard, nella CLI e nell’API pubblica attuali: non esiste un’operazione di sblocco supportata. L’attivazione non crea un token né distribuisce una versione. Prima di bloccare il progetto, verifica un flusso funzionante con token e configurazione.
Il blocco impedisce le modifiche dal dashboard alle impostazioni di progetto e widget gestite dalla configurazione, il caricamento di icone e le operazioni manuali sul corpus, come avviare scansioni, eliminare pagine, svuotare i contenuti o rigenerare gli embedding. Non interrompe le attività pianificate né l’eliminazione del progetto. Restano disponibili la creazione e la revoca dei token, la gestione delle chiavi pubbliche e le letture operative.
La preferenza di branding è l’eccezione: il relativo controllo nel dashboard resta modificabile anche nei progetti bloccati. Nascondere l’attribuzione richiede il piano Starter o superiore, anche tramite deployment della configurazione. Se ometti widget.showBranding, viene mantenuta la preferenza memorizzata (oppure si usa true se non ne esiste una); un valore esplicito la sovrascrive alla successiva promozione del runtime. Il runtime del piano Free continua a mostrare il branding.
Distribuire la configurazione
Il deployment crea una versione immutabile e la promuove nell’ambiente selezionato. Distribuisci la configurazione desiderata completa, non una patch: durante la promozione del runtime, i valori omessi possono azzerare o ripristinare impostazioni precedenti del dashboard.
bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production
Le etichette di ambiente non isolano i runtime. development registra solo una versione e un puntatore (applied: false, indexingStatus: "not_required"). preview e production sovrascrivono le impostazioni dello stesso runtime di progetto e usano lo stesso corpus e le stesse chiavi pubbliche del widget. Prevale la promozione del runtime più recente, anche se lo stato dell’altra etichetta punta ancora a una versione precedente: un token con ambito preview può quindi modificare un progetto che serve traffico di produzione. Per un isolamento reale, usa progetti distinti con i rispettivi token e le rispettive chiavi.
Le promozioni preview e production applicano atomicamente la configurazione e accodano un job di scansione (applied: true, indexingStatus: "pending"), senza attendere il completamento della scansione o degli embedding. Il corpus non è uno snapshot versionato e un aggiornamento non riuscito non annulla la configurazione applicata.
Gli aggiornamenti modificano le pagine esistenti e richiedono nuovi embedding quando i contenuti cambiano; non eliminano automaticamente i vecchi URL solo perché una nuova fonte o un filtro li omette. In caso di errore possono restare aggiornamenti parziali. I job registrano l'ID della versione di configurazione ma leggono anche impostazioni di scansione modificabili: evita deployment sovrapposti quando la coerenza dell'indicizzazione è importante.
Usa --json nelle automazioni per ricevere il risultato API, inclusi version._id, il puntatore dell’ambiente, applied, indexingStatus e l’ID del job di scansione, se ne viene accodato uno. Conserva version._id per le promozioni o i rollback successivi: il numero sequenziale leggibile non è un valore valido per --version.
Sostituzione e limiti del piano
La promozione del runtime cancella o ripristina i valori gestiti dalla configurazione che sono stati omessi, incluse le precedenti impostazioni del dashboard:
| Valore omesso | Effetto sul runtime |
|---|---|
project.description, prompt/profilo/fallback dell’assistente | Cancella le personalizzazioni memorizzate; si applica il comportamento di fallback del runtime. |
runtime | Ripristina la lingua automatica, en come valore predefinito e le sostituzioni di lingua consentite. |
widget o testi/tema/posizione facoltativi del widget | Se si omette l’intero oggetto widget, il widget viene abilitato; se l’oggetto è presente, viene rispettato il valore obbligatorio di enabled. Le personalizzazioni di presentazione omesse vengono cancellate separatamente, applicando i valori predefiniti del runtime. |
widget.icon | Ripristina l’icona predefinita di dimensione media. La promozione del runtime elimina il file dell’icona caricato in precedenza, anche se viene fornita un’icona dichiarativa sostitutiva. |
| Modalità, filtri o pianificazione della fonte | La modalità predefinita è crawl; i filtri omessi vengono cancellati e l’aggiornamento automatico è disattivato. Le impostazioni specifiche valgono solo per la modalità corrispondente. |
widget.showBranding | Eccezione: mantiene la preferenza memorizzata, oppure usa true se non ne esiste una. |
La versione di configurazione immutabile conserva il maxPages richiesto, mentre la promozione limita a 100.000 il valore operativo nella configurazione di scansione. A ogni esecuzione il worker limita la selezione al minore tra il maxPages richiesto e il maggiore tra la capacità del provider e il numero di pagine già esistenti nel progetto; l’ammissione di nuove pagine viene verificata separatamente rispetto alla quota di pagine dell’account. Se maxPages è omesso, come valore predefinito della richiesta si usa la quota di pagine dell’account inclusa nel piano: Free 10, Starter 150, Pro 5.000 e Business 25.000. È solo un valore predefinito per la richiesta, non una quota aggiuntiva; ogni scansione verifica nuovamente la quota di pagine/PAYG attuale e i limiti mensili di aggiornamento. La rilevazione delle sitemap può recuperare i relativi documenti ed enumerare gli URL prima della selezione: la capacità non è quindi un limite di privacy né una garanzia contro richieste in uscita. Non è garantito che tutte le pagine richieste vengano indicizzate.
L'aggiornamento automatico giornaliero e showBranding: false richiedono Starter o superiore. Free accetta aggiornamenti automatici settimanali o mensili. Questi diritti vengono verificati alla promozione preview o production, anche durante il rollback, non durante la convalida locale o la registrazione in development. Una versione prima valida può non essere più promuovibile dopo un cambio di piano. La promozione usa i dati del piano memorizzati sul server, non una richiesta in tempo reale al fornitore di fatturazione: verifica separatamente la sincronizzazione e la quota effettiva di scansione dopo modifiche recenti al piano o al PAYG.
In modalità sitemap, se sitemapUrl non è specificato, la scansione prova prima la sitemap rilevata, poi /sitemap.xml e /sitemap_index.xml; se nessuna restituisce URL, usa l’URL del sito salvato.
Stato, promozione e 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 richiede l’ID opaco della versione: usa version._id nell’output JSON di deploy/promote/rollback o activeVersion._id nell’output JSON di status, non il numero visualizzato, uno SHA Git o l’hash della configurazione. Mantieni le virgolette intorno ai segnaposto come nell'esempio, poi sostituiscili con ID effettivi appartenenti al progetto del token. Il rollback riapplica la configurazione con i diritti del piano attuali e non ripristina esattamente il contenuto storico.
Il rollback usa la stessa operazione di backend della promozione: non deve necessariamente puntare a una versione precedente e non seleziona automaticamente la versione precedente. Sovrascrive il puntatore dell'ambiente selezionato e i relativi metadati; non esiste una cronologia append-only delle promozioni. In preview o production accoda un nuovo aggiornamento. I deployment ripetuti creano nuove versioni anche con configurazioni identiche e le promozioni ripetute possono accodare nuovi job.
status mostra la versione e il riepilogo del puntatore dell'etichetta selezionata, non la configurazione effettiva del runtime, le differenze rispetto alla dashboard o l'avanzamento della scansione e degli embedding. Se l'etichetta non è stata distribuita, mostra Environment version: none e restituisce environment: null e activeVersion: null. runtimeConfigVersionId identifica l'ultima configurazione applicata al runtime condiviso e può differire dopo la promozione di un'altra etichetta. Una chiamata riuscita aggiorna anche lastUsedAt del token e consuma capacità del limite di frequenza della gestione. Controlla separatamente l'indicizzazione nella dashboard.
Comandi, opzioni ed errori
| Comando | Argomenti ed effetto |
|---|---|
init [path] | Usa chattybox.config.json per impostazione predefinita; crea le directory superiori e non sovrascrive file esistenti. |
validate [path] | Usa lo stesso percorso predefinito; legge e convalida JSON senza accesso remoto. |
deploy | Richiede --environment; accetta --config <path> facoltativo; convalida, crea e promuove una versione. |
promote, rollback | Richiedono --environment e --version <opaque-id>; non leggono una configurazione locale. |
status | Richiede --environment; non legge una configurazione locale. |
Nessun comando, help, --help, -h | Mostra la guida generale. Usa chattybox --help, non chattybox deploy --help. |
--version, -v | Versione generale della CLI; distinta dall'opzione --version per la promozione. |
Tutti e quattro i comandi di gestione accettano --token, --api-url e --json. Le credenziali e l'URL espliciti prevalgono su CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL. Preferisci variabili d'ambiente segrete ai token nella cronologia della shell o negli argomenti del processo. Le opzioni con valore accettano --flag value o --flag=value; --json è un'opzione senza valore. Non esiste un ambiente predefinito. Le opzioni di gestione sconosciute, duplicate, vuote o non applicabili al comando vengono rifiutate. I comandi locali accettano solo un percorso posizionale e rifiutano opzioni e argomenti aggiuntivi.
Non esistono opzioni --dry-run, --wait, --force, --project, per messaggi o per il controllo ottimistico della concorrenza. L'API HTTP supporta campi per la versione attesa, ma la CLI non li invia. Serializza i deployment CI verso lo stesso progetto.
I comandi eseguibili riusciti terminano con codice 0. Errori di file/JSON/convalida, argomenti, trasporto, lettura della risposta e HTTP terminano con codice 1 e un messaggio ChattyBox: ... su stderr. --json formatta solo i risultati riusciti, non gli errori. Gli errori API includono stato HTTP e codice quando forniti; le risposte riuscite non JSON vengono rifiutate. La CLI non ha retry, polling o timeout della richiesta configurato. Dopo un errore di trasporto, controlla lo stato prima di riprovare: il server potrebbe aver già registrato il deployment.
Le route di gestione sono POST /v1/config/deployments (201), POST /v1/config/deployments/promote e /rollback (200), e GET /v1/config/deployments/status?environment=... (200). Via HTTP i risultati riusciti sono racchiusi in { "data": ... }; il JSON della CLI rimuove questo involucro. Gli errori usano normalmente { "error": { "code": ..., "message": ... } }: 401 INVALID_TOKEN, 404 NOT_FOUND per una versione mancante o di un altro progetto, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG o 500 INTERNAL_ERROR. Gli ID tipizzati malformati danno 422, non necessariamente 404. Il limite del corpo della richiesta è 262.144 byte. Tutte le route di gestione condividono un limite di 20 richieste al minuto per token; le risposte 429 usano il formato condiviso e l'header Retry-After. Un corpo POST completamente assente produce attualmente 500, a differenza di JSON malformato (422).
activeVersion nello stato è l'ultima versione promossa per l'etichetta selezionata; runtimeConfigVersionId identifica invece l'ultima configurazione applicata al runtime condiviso e può differire dopo una promozione su un'altra etichetta. Una promozione in development non cambia tale puntatore. Se la configurazione non è bloccata, modifiche successive nella dashboard possono cambiare i campi del runtime senza modificare l'ID dell'ultima configurazione applicata.
Workflow CI/CD
Aggiungi CHATTYBOX_DEPLOY_TOKEN come secret crittografato con ambito production nel provider CI. Aggiungi CHATTYBOX_API_URL come secret o variabile usando l’URL di deployment HTTP actions oppure, quando disponibile, l’URL API del widget in Installa → Installazione sul sito web. Esegui la validazione sulle pull request, ma limita il deployment in produzione al branch predefinito protetto o a un ambiente di deployment approvato.
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
Usa un secret di produzione con ambito limitato all'ambiente e richiedi l'approvazione del deployment quando il tuo repository lo supporta. La CLI registra le variabili CI comuni relative al commit e al branch insieme alla versione immutabile.
GitLab CI/CD
Archivia entrambi i valori in Settings → CI/CD → Variables. Proteggi il token di deployment, mascheralo e limita il suo ambito all'ambiente 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 espone automaticamente al job CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL usando i rispettivi nomi di variabile. Usa un branch predefinito protetto, in modo che le variabili protette non siano disponibili per branch non attendibili. Gli esempi con il container Bun usano esplicitamente --bun, senza dipendere da un'installazione separata di Node; verifica in CI la versione di Bun e dell'immagine bloccata.
Bitbucket Pipelines
Aggiungi entrambi i valori come variabili di deployment in Repository settings → Pipelines → Deployments → Production. Contrassegna il token di deployment come protetto.
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
Sostituisci main se il tuo branch predefinito ha un altro nome. Bitbucket inserisce le variabili di deployment solo nei passaggi associati a quell'ambiente di deployment. La CLI non ha una mappatura specifica dei metadati BITBUCKET_*: usa Git locale per commit e branch, che può non avere un nome di branch in un checkout detached.
Sezioni di configurazione
| Sezione | Scopo |
|---|---|
schemaVersion | Seleziona il contratto pubblico di configurazione. Attualmente è supportata la versione 1. |
project | Metadati facoltativi del progetto, come la descrizione nella dashboard. |
assistant | Assegna un nome all'assistente e definisce una Persona integrata o un prompt di sistema personalizzato, oltre al testo di fallback. |
knowledge.sources | Seleziona homepage, sitemap, URL manuali o rilevamento tramite crawl, con limiti, filtri e pianificazione. |
runtime | Controlla lingua automatica/fissa, lingua predefinita e override della lingua a livello di pagina. |
widget | Controlla attivazione, posizione, testi, colori e presentazione dell'icona predefinita, emoji o URL. |
Persona
Imposta promptProfile su default, support, sales o sarcastic per usare le istruzioni Persona mantenute dal prodotto. Impostalo su custom e fornisci systemPrompt per una Persona personalizzata. Se sono forniti sia un profilo integrato sia systemPrompt, prevale il prompt esplicito.
Rilevamento delle fonti
Questo frammento di configurazione estesa richiede i tipi config pubblicati 0.3.1 e il corrispondente contratto backend 0.3.0. La pianificazione giornaliera richiede Starter o superiore; maxPages: 500 memorizza una richiesta comunque soggetta alla capacità effettiva dell'esecuzione.
{
"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"
}
Modalità supportate:
homepage: seleziona solourlper questo aggiornamento, senza eliminare le pagine esistenti.sitemap: usasitemapUrl; una sitemap esplicita che non restituisce URL fa fallire il job. Se omessa, prova la sitemap rilevata, poi/sitemap.xmle/sitemap_index.xml, infine l'URL salvato del sito se nessuna restituisce URL.manual: indicizza l'elenco non vuotomanualUrls.crawl: prova le sitemap convenzionali, poi segue i link daurlfino amaxDepth(predefinito3).
include ed exclude confrontano sottostringhe degli URL rispettando maiuscole e minuscole, non usano glob o espressioni regolari. Qualsiasi corrispondenza include ammette un URL; qualsiasi corrispondenza exclude lo rifiuta, anche se incluso. Gli elenchi vuoti non filtrano. I filtri si applicano anche alla homepage e alla selezione manuale.
maxPages deve essere un intero positivo; la versione immutabile conserva il valore richiesto, mentre la configurazione di runtime è limitata e la selezione è soggetta ai controlli di capacità descritti sopra. La discovery delle sitemap può enumerare URL prima della selezione. maxDepth deve essere un intero da 0 a 20 e controlla il fallback di scansione dei link, non l'enumerazione delle sitemap. Omettere mode seleziona crawl e conserva un maxDepth esplicito, anche zero. autoRescrape: true richiede rescrapeInterval: "daily", "weekly" o "monthly"; l'intervallo da solo non attiva la pianificazione. Mensile significa 30 giorni e lo scheduler può eseguire il job dopo la scadenza.
Convalida della lingua e del widget
I codici lingua supportati sono en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy e id. localeMode è auto o fixed; fixed richiede defaultLocale. allowLocaleOverride è configurabile indipendentemente. La forma abbreviata runtime.locale seleziona la modalità fissa e disattiva gli override; l'attuale convalida locale rifiuta la combinazione con localeMode, defaultLocale o allowLocaleOverride: true.
Le posizioni del widget sono bottom-right, bottom-left, top-right e top-left. Tutti e tre i colori del tema usano #RRGGBB, non esadecimali brevi, nomi di colori o alpha. Le icone usano default, emoji (stringa emoji non vuota) o url (url HTTP(S)), con dimensione facoltativa small, medium o large. La convalida non recupera gli URL delle icone, non verifica i tipi MIME delle immagini e non richiede che la stringa contenga esattamente un'emoji. La convalida degli URL delle fonti e delle icone controlla sintassi e protocollo, non la raggiungibilità o l'autorizzazione alla scansione. Descrizione, prompt/fallback dell'assistente, titolo e messaggio di benvenuto del widget, se forniti, devono essere non vuoti; omettili per cancellare le personalizzazioni.
Funzione di supporto per la configurazione tipizzata
Installa il pacchetto di configurazione se crei strumenti TypeScript separati basati sullo schema:
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 },
});
La CLI legge direttamente file JSON. defineConfig() è destinata ad applicazioni tipizzate o strumenti di build; non rende i file TypeScript direttamente caricabili dalla CLI. Sia defineConfig(config) sia validateConfig(config) convalidano in modo sincrono, generano un normale Error al primo errore e restituiscono lo stesso oggetto senza clonarlo, congelarlo, convertirlo o inserirvi valori predefiniti. Il pacchetto esporta tipi TypeScript e queste funzioni, non un documento JSON Schema né un URL $schema. Il pacchetto pubblicato 0.3.1 fornisce supporto TypeScript per i campi estesi descritti sopra.
Per un'integrazione funzionante in produzione oggi, utilizza il widget ospitato oppure crea un'interfaccia personalizzata con l'SDK JavaScript.