CLI e distribuzione della configurazione

La CLI crea, convalida, distribuisce, promuove ed esegue il rollback di versioni immutabili della configurazione ChattyBox. I token di deployment sono limitati a un singolo progetto e agli ambienti selezionati, quindi lo stesso flusso è adatto allo sviluppo locale e alla 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 verifica lo schema, il nome obbligatorio dell'assistente, i tipi di fonti supportati, gli URL HTTP delle fonti, i limiti di pagina positivi e i colori del widget. Una convalida riuscita non esegue il deployment e non modifica lo stato remoto.

Creare un token di deployment

Apri la scheda Settings del progetto, cerca Config deployment tokens e crea un token per gli ambienti che il tuo flusso di lavoro può modificare. Copialo subito: ChattyBox memorizza solo il suo hash e non può mostrarlo nuovamente.

Imposta il token e l'URL API del widget dalla scheda Embed del progetto:

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

Non eseguire mai il commit del token. Conservalo nel gestore di secret crittografati del tuo provider CI.

Dopo aver verificato il flusso di deployment, abilita Config-as-code lock nella stessa sezione delle impostazioni. Il blocco disabilita le modifiche alla configurazione e al corpus dalla dashboard, così solo i token di deployment con l’ambito corretto possono modificare il runtime. La creazione e la revoca dei token restano disponibili se è necessario ruotare una credenziale CI.

Distribuire la configurazione

Il deployment crea una versione immutabile e la promuove nell'ambiente selezionato:

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

Le promozioni a development e preview vengono registrate per la revisione. Le promozioni a production applicano atomicamente al progetto live il prompt dell'assistente, la risposta di fallback, le impostazioni del widget, le impostazioni locali e la fonte del sito web. La configurazione di produzione deve contenere esattamente una fonte del sito web. Un deployment accoda uno scraping associato alla versione, che viene eseguito dopo il completamento dei job precedenti. Poi il deployment sostituisce il corpus precedente e rigenera gli embedding. Il runtime attuale rifiuta le configurazioni con più fonti.

Usa --json nelle automazioni per ricevere versione, ambiente, stato dell'applicazione e ID del job di scraping in un output strutturato.

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

Il rollback promuove e riapplica una versione immutabile precedente; non riscrive mai la cronologia dei deployment. Ripristina immediatamente la configurazione, mentre ogni aggiornamento dei contenuti necessario continua in modo asincrono.

GitHub Actions

- name: Deploy ChattyBox configuration
  env:
    CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
    CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
  run: 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.

Sezioni di configurazione

Sezione	Scopo
schemaVersion	Seleziona il contratto pubblico di configurazione. Attualmente è supportata la versione 1.
assistant	Assegna un nome all'assistente e, facoltativamente, ne definisce il profilo delle istruzioni e l'istruzione di sistema.
knowledge.sources	Dichiara le fonti dei siti web ed eventuali pattern di inclusione o esclusione.
runtime	Contiene i valori predefiniti di runtime, come le impostazioni locali.
widget	Descrive le impostazioni facoltative di presentazione del widget ospitato.

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.

Per un'integrazione funzionante in produzione oggi, utilizza il widget ospitato oppure crea un'interfaccia personalizzata con l'SDK JavaScript.