CLI och konfigurationsdistribution

CLI:t skapar, validerar, distribuerar, promoterar och återställer oföränderliga ChattyBox-konfigurationsversioner. Distributionstoken begränsas till ett projekt och valda miljöer, vilket gör samma arbetsflöde lämpligt för lokal utveckling och CI.

Skapa en konfiguration

bunx @openstaticfish/chattybox-cli init

Detta skapar chattybox.config.json:

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

Använd en anpassad sökväg när konfigurationen hör hemma i en underkatalog:

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

Validera lokalt eller i CI

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

Valideringen kontrollerar schemat, det obligatoriska assistentnamnet, stödda källtyper, HTTP-URL:er för källor, positiva sidgränser och widgetfärger. En godkänd validering distribuerar eller ändrar inte fjärrtillståndet.

Skapa en distributionstoken

Öppna projektets flik Settings, leta reda på Config deployment tokens och skapa en token för de miljöer som arbetsflödet kan ändra. Kopiera den direkt; ChattyBox lagrar bara dess hash och kan inte visa den igen.

Ange token och widgetens API-URL från projektets flik Embed:

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

Checka aldrig in token. Lagra den i CI-leverantörens krypterade hemlighetslager.

När du har verifierat distributionsarbetsflödet aktiverar du Config-as-code lock i samma inställningssektion. Låset inaktiverar konfigurations- och korpusändringar från kontrollpanelen, så att endast distributionstoken med rätt begränsning kan ändra runtime-miljön. Det går fortfarande att skapa och återkalla token om en CI-autentiseringsuppgift behöver roteras.

Distribuera konfigurationen

En distribution skapar en oföränderlig version och promoterar den till den valda miljön:

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

Promoteringar till utvecklings- och förhandsgranskningsmiljöer registreras för granskning. Produktionspromoteringar tillämpar atomiskt assistentens prompt, reservsvaret, widgetinställningarna, lokalinställningen och webbplatskällan på det aktiva projektet. Produktionskonfigurationen måste innehålla exakt en webbplatskälla. En distribution lägger ett versionsbundet skrapningsjobb i kö som körs efter att tidigare jobb har slutförts. Därefter ersätter distributionen den tidigare korpusen och genererar embeddingar på nytt. Den aktuella runtime-miljön avvisar konfigurationer med flera källor.

Använd --json i automatisering för att få versionen, miljön, applikationsstatusen och ID:t för skrapningsjobbet som strukturerad utdata.

Status, promotering och återställning

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

En återställning promoterar och tillämpar en äldre oföränderlig version på nytt; den skriver aldrig om distributionshistoriken. Den återställer konfigurationen omedelbart, medan eventuell nödvändig innehållsuppdatering fortsätter asynkront.

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

Använd en produktionshemlighet som är begränsad till miljön och kräv godkännande av distributionen när ditt arkiv stöder det. CLI:t registrerar vanliga CI-variabler för commit och branch tillsammans med den oföränderliga versionen.

Konfigurationsavsnitt

Avsnitt	Syfte
schemaVersion	Väljer det offentliga konfigurationskontraktet. Version 1 stöds för närvarande.
assistant	Namnger assistenten och definierar valfritt dess promptprofil och systemprompt.
knowledge.sources	Deklarerar webbplatskällor och valfria mönster för inkludering och exkludering.
runtime	Innehåller standardvärden för körning, till exempel språkversion.
widget	Beskriver valfria presentationsinställningar för den hostade widgeten.

Typad konfigurationshjälp

Installera konfigurationspaketet när du bygger separata TypeScript-verktyg kring schemat:

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

CLI:n läser själv JSON-filer. defineConfig() är avsedd för typade program eller byggverktyg; den gör inte TypeScript-filer direkt läsbara för CLI:n.

För en fungerande produktionsintegration i dag kan du använda den hostade widgeten eller bygga ett anpassat gränssnitt med JavaScript SDK.