CLI und Konfigurationsbereitstellung

Die veröffentlichten CLI/Config-Artefakte der Version 0.3.1 implementieren den Konfigurations-/Backend-Vertrag 0.3.0 und lehnen unbekannte Schlüssel lokal und im Backend gleichermaßen ab.

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.

Veröffentlichungs- und Laufzeitstatus

Im öffentlichen Registry sind @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 und das separate JavaScript-SDK @openstaticfish/chattybox@0.1.4 veröffentlicht. Die CLI/config-Artefakte unterstützen die erweiterten Felder (Projekt, Ermittlung/Planung, erweiterte Locale-Steuerung, widget.icon, widget.showBranding) zusammen mit dem Backend-Vertrag 0.3.0. status zeigt die Umgebungsversion, während runtimeConfigVersionId die zuletzt auf die gemeinsame Runtime angewandte Konfiguration benennt und abweichen kann. Ohne mode wird crawl gewählt und ein explizites maxDepth: 0 erhalten. Die ESM-CLI verlangt Node 20+; wählen Sie Bun bei Bedarf ausdrücklich mit bunx --bun.

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.

Nach Überprüfung des Workflows können Sie Config-as-code lock aktivieren. Die Sperre ist im aktuellen Dashboard, CLI und API irreversibel. Sie blockiert Dashboard-Konfiguration und manuelle Korpusaktionen (Scraping, Löschen, Rebuild), nicht aber geplante Arbeit, Projektlöschung, öffentliche Schlüssel oder Tokens. Branding ist die Ausnahme: Die Branding-Einstellung bleibt tarifabhängig im Dashboard änderbar.

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

development speichert nur Version und Zeiger, ohne Runtime-Anwendung. preview und production teilen dieselbe Runtime, dasselbe Korpus und dieselben öffentlichen Schlüssel: Die letzte Runtime-Promotion gewinnt, ohne Umgebungsisolation. Nutzen Sie getrennte Projekte und Tokens für echte Trennung. Runtime-Promotion wendet Konfiguration an und stellt einen Scrape in die Warteschlange, wartet aber nicht auf Scraping oder Embeddings; ausgelassene alte URLs werden nicht entfernt und das Korpus ist kein versionierter Snapshot.

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

--version erwartet die undurchsichtige Konfigurationsversions-ID, nicht die sichtbare Nummer. Rollback verwendet dieselbe Backend-Operation wie Promote, muss keine ältere Version wählen und überschreibt den Zeiger sowie die Promotion-Metadaten der ausgewählten Umgebung; es gibt keine append-only Promotion-Historie. Ein Rollback für Preview oder Production wendet die Konfiguration mit den aktuellen Entitlements erneut an und reiht eine neue Aktualisierung ein, statt historische Inhalte wiederherzustellen.

CI/CD-Workflows

Fügen Sie CHATTYBOX_DEPLOY_TOKEN als verschlüsseltes, auf die Produktion beschränktes Secret bei Ihrem CI-Anbieter hinzu. Fügen Sie CHATTYBOX_API_URL als Secret oder Variable hinzu und verwenden Sie die Widget-API-URL aus dem Embed-Tab des Projekts. Führen Sie die Validierung für Pull Requests aus, beschränken Sie Produktionsdeployments jedoch auf Ihren geschützten Standardbranch oder eine genehmigte Deployment-Umgebung.

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

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.

GitLab CI/CD

Speichern Sie beide Werte unter Settings → CI/CD → Variables. Schützen und maskieren Sie das Deployment-Token und beschränken Sie es auf die Umgebung 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 stellt CHATTYBOX_DEPLOY_TOKEN und CHATTYBOX_API_URL dem Job automatisch unter ihren Variablennamen zur Verfügung. Verwenden Sie einen geschützten Standardbranch, damit geschützte Variablen nicht für nicht vertrauenswürdige Branches verfügbar sind.

Bitbucket Pipelines

Fügen Sie beide Werte als Deployment-Variablen unter Repository settings → Pipelines → Deployments → Production hinzu. Markieren Sie das Deployment-Token als geschützt.

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

Ersetzen Sie main, wenn Ihr Standardbranch anders heißt. Bitbucket fügt Deployment-Variablen nur Schritten hinzu, die dieser Deployment-Umgebung zugeordnet sind.

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.