CLI und Konfigurationsbereitstellung

Die CLI erstellt, validiert und stellt unveränderliche ChattyBox-Konfigurationsversionen bereit, befördert sie und führt Rollbacks durch. Deployment-Tokens sind auf ein Projekt und ausgewählte Umgebungen beschränkt, sodass sich derselbe Workflow für die lokale Entwicklung und CI eignet.

Konfiguration erstellen

bunx @openstaticfish/chattybox-cli init

Dadurch wird chattybox.config.json erstellt:

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

Verwenden Sie einen benutzerdefinierten Pfad, wenn die Konfiguration in ein Unterverzeichnis gehört:

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

Lokal oder in CI validieren

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

Die Validierung prüft das Schema, den erforderlichen Namen des Assistenten, unterstützte Quelltypen, HTTP-Quell-URLs, positive Seitenlimits und Widget-Farben. Eine erfolgreiche Validierung führt keine Bereitstellung durch und ändert keinen entfernten Zustand.

Deployment-Token erstellen

Öffnen Sie im Projekt den Tab Settings, suchen Sie Config deployment tokens und erstellen Sie ein Token für die Umgebungen, die Ihr Workflow ändern darf. Kopieren Sie es sofort; ChattyBox speichert nur dessen Hash und kann es nicht erneut anzeigen.

Setzen Sie das Token und die Widget-API-URL aus dem Tab Embed des Projekts:

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

Committen Sie das Token niemals. Speichern Sie es im verschlüsselten Secret-Speicher Ihres CI-Anbieters.

Nachdem Sie den Deployment-Workflow überprüft haben, aktivieren Sie Config-as-code lock im selben Einstellungsbereich. Die Sperre deaktiviert Konfigurations- und Korpusänderungen über das Dashboard, sodass nur entsprechend begrenzte Deployment-Tokens die Laufzeit ändern können. Das Erstellen und Widerrufen von Tokens bleibt möglich, falls ein CI-Zugangsschlüssel rotiert werden muss.

Konfiguration bereitstellen

Das Deployment erstellt eine unveränderliche Version und befördert sie in die ausgewählte Umgebung:

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

Promotionen nach development und preview werden zur Prüfung protokolliert. Promotionen nach production wenden den Assistant-Prompt, die Fallback-Antwort, Widget-Einstellungen, Locale und Website-Quelle atomar auf das Live-Projekt an. Die Produktionskonfiguration muss genau eine Website-Quelle enthalten. Ein Deployment stellt einen an die Version gebundenen Scraping-Job in die Warteschlange, der nach Abschluss früherer Jobs ausgeführt wird. Anschließend ersetzt es das bisherige Korpus und generiert die Embeddings neu. Die aktuelle Laufzeit lehnt Konfigurationen mit mehreren Quellen ab.

Verwenden Sie --json in der Automatisierung, um Version, Umgebung, Anwendungsstatus und Scraping-Job-ID als strukturierte Ausgabe zu erhalten.

Status, Promotion und 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

Ein Rollback befördert eine ältere unveränderliche Version und wendet sie erneut an; die Deployment-Historie wird dabei nie umgeschrieben. Die Konfiguration wird sofort wiederhergestellt, während eine erforderliche Inhaltsaktualisierung asynchron fortgesetzt wird.

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

Verwenden Sie ein auf die Produktionsumgebung begrenztes Secret und verlangen Sie eine Deployment-Genehmigung, wenn Ihr Repository dies unterstützt. Die CLI zeichnet gängige CI-Commit- und Branch-Variablen zusammen mit der unveränderlichen Version auf.

Konfigurationsabschnitte

Abschnitt	Zweck
schemaVersion	Wählt den öffentlichen Konfigurationsvertrag aus. Derzeit wird Version 1 unterstützt.
assistant	Benennt den Assistenten und definiert optional sein Prompt-Profil und seinen System-Prompt.
knowledge.sources	Deklariert Website-Quellen und optionale Ein- und Ausschlussmuster.
runtime	Enthält Laufzeitvorgaben wie die Locale.
widget	Beschreibt optionale Darstellungseinstellungen für das gehostete Widget.

Typisierter Konfigurationshelfer

Installieren Sie das Konfigurationspaket, wenn Sie separate TypeScript-Werkzeuge rund um das Schema entwickeln:

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 },
});

Die CLI selbst liest JSON-Dateien. defineConfig() ist für typisierte Anwendungen oder Build-Werkzeuge vorgesehen; TypeScript-Dateien werden dadurch nicht direkt von der CLI geladen.

Für eine heute einsatzbereite Produktionsintegration verwenden Sie das gehostete Widget oder erstellen Sie mit dem JavaScript-SDK eine eigene Benutzeroberfläche.