CLI en configuratiedeployment

De CLI maakt, valideert, deployt, promoot en rolt onveranderlijke ChattyBox-configuratieversies terug. Deploymenttokens zijn beperkt tot één project en geselecteerde omgevingen, waardoor dezelfde workflow geschikt is voor lokale ontwikkeling en CI.

Een configuratie maken

bunx @openstaticfish/chattybox-cli init

Hiermee wordt chattybox.config.json gemaakt:

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

Gebruik een aangepast pad wanneer de configuratie in een submap thuishoort:

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

Lokaal of in CI valideren

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

De validatie controleert het schema, de verplichte assistentnaam, ondersteunde brontypen, HTTP-URL's van bronnen, positieve paginalimieten en widgetkleuren. Een geslaagde validatie voert geen deployment uit en wijzigt geen externe status.

Een deploymenttoken maken

Open in het project het tabblad Settings, zoek Config deployment tokens en maak een token aan voor de omgevingen die je workflow mag wijzigen. Kopieer het meteen; ChattyBox slaat alleen de hash op en kan het niet opnieuw tonen.

Stel het token en de widget-API-URL in vanuit het tabblad Embed van het project:

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

Commit het token nooit. Bewaar het in de versleutelde secretopslag van je CI-provider.

Schakel nadat je de deploymentworkflow hebt gecontroleerd Config-as-code lock in dezelfde instellingensectie in. De vergrendeling schakelt configuratiewijzigingen en corpusmutaties vanuit het dashboard uit, zodat alleen deploymenttokens met de juiste scope de runtime kunnen wijzigen. Het aanmaken en intrekken van tokens blijft mogelijk als een CI-credential moet worden geroteerd.

Configuratie deployen

Een deployment maakt een onveranderlijke versie en promoot deze naar de geselecteerde omgeving:

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

Promoties naar development en preview worden vastgelegd voor beoordeling. Promoties naar production passen de assistentprompt, fallbackreactie, widgetinstellingen, locale en websitebron atomair toe op het liveproject. De productieconfiguratie moet precies één websitebron bevatten. Een deployment zet een aan de versie gekoppelde scrape in de wachtrij, die wordt uitgevoerd nadat eerdere taken zijn afgerond. Daarna wordt het vorige corpus vervangen en worden de embeddings opnieuw gegenereerd. De huidige runtime weigert configuraties met meerdere bronnen.

Gebruik --json in automatisering om de versie, omgeving, applicatiestatus en ID van de scrapetaak als gestructureerde uitvoer te ontvangen.

Status, promotie en 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

Een rollback promoot een oudere onveranderlijke versie en past deze opnieuw toe; de deploymentgeschiedenis wordt nooit herschreven. De configuratie wordt onmiddellijk hersteld, terwijl elke vereiste inhoudsvernieuwing asynchroon doorgaat.

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

Gebruik een productiegeheim dat aan de omgeving is gebonden en vereist deploymentgoedkeuring wanneer je repository dit ondersteunt. De CLI legt veelgebruikte CI-commit- en branchvariabelen vast bij de onveranderlijke versie.

Configuratiesecties

Sectie	Doel
schemaVersion	Selecteert het openbare configuratiecontract. Versie 1 wordt momenteel ondersteund.
assistant	Geeft de assistent een naam en definieert optioneel het instructieprofiel en de systeeminstructie.
knowledge.sources	Declareert websitebronnen en optionele patronen voor opnemen of uitsluiten.
runtime	Bevat standaardwaarden voor de runtime, zoals de locale.
widget	Beschrijft optionele presentatie-instellingen voor de gehoste widget.

Helper voor getypeerde configuratie

Installeer het configuratiepakket wanneer je afzonderlijke TypeScript-tooling rond het schema bouwt:

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

De CLI zelf leest JSON-bestanden. defineConfig() is bedoeld voor getypeerde applicatie- of buildtooling; TypeScript-bestanden worden hierdoor niet rechtstreeks laadbaar voor de CLI.

Gebruik voor een werkende productie-integratie op dit moment de gehoste widget of bouw een aangepaste interface met de JavaScript-SDK.