CLI och konfigurationsdistribution

De publicerade CLI/config-artefakterna i version 0.3.1 implementerar konfigurations-/backendkontraktet 0.3.0 och avvisar okända nycklar både lokalt och i backend.

CLI:t skapar, validerar, distribuerar, promoterar och återställer oföränderliga ChattyBox-konfigurationsversioner. Varje distributionstoken är begränsad till ett befintligt projekt och valda miljöetiketter. @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 och JavaScript-SDK:t @openstaticfish/chattybox@0.1.4 är publicerade och stöder konfigurations-/backendkontraktet 0.3.0. status visar miljöversionen, medan runtimeConfigVersionId är senast tillämpade gemensamma runtime-versionen och kan skilja sig. När mode utelämnas väljs crawl utan att ett uttryckligt maxDepth: 0 ändras.

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 läser endast JSON och ändrar inte fjärrtillståndet. Den publicerade 0.3.1-validatorn stöder fälten för discovery, locale, ikon och branding. En lokal godkänd validering kontrollerar inte token, planbehörighet, nätverk eller backendens extra fält och är därför ingen distributionsgaranti.

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 kan du aktivera Config-as-code lock i samma inställningssektion. Låset kan inte ångras via nuvarande instrumentpanel, CLI eller publika API. Det blockerar konfigurations- och manuella korpusändringar från kontrollpanelen, men tokenhantering, publika nycklar och den planstyrda branding-inställningen förblir separata. Ha ett testat tokenflöde innan du låser.

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

development registrerar endast en version/pekare (applied: false, indexingStatus: "not_required"). preview och production skriver över samma projekts runtime-inställningar och använder samma korpus och publika widgetnycklar; den senaste runtime-promoteringen vinner. Använd separata projekt för verklig isolering. Båda tillämpar konfigurationen atomiskt och köar ett skrapningsjobb (applied: true, indexingStatus: "pending"), men väntar inte på skrapning eller embeddings. Korpusen är ingen versionshanterad ögonblicksbild, och en misslyckad uppdatering återställer inte den tillämpade konfigurationen.

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

--version använder det ogenomskinliga konfigurationsversions-ID:t, inte det synliga numret. Återställning använder samma backendåtgärd som promotion, behöver inte rikta in sig på en äldre version och skriver över den valda miljöns pekare och promotionsmetadata; någon append-only-promotionshistorik finns inte. För preview eller production tillämpar den konfigurationen på nytt med aktuella behörigheter och köar en ny uppdatering i stället för att återställa historiskt korpusinnehåll.

CI/CD-arbetsflöden

Lägg till CHATTYBOX_DEPLOY_TOKEN som en krypterad produktionsbegränsad hemlighet hos din CI-leverantör. Lägg till CHATTYBOX_API_URL som en hemlighet eller variabel med widgetens API-URL från projektets Embed-flik. Kör validering på pull requests, men begränsa produktionsdistribution till din skyddade standardgren eller en godkänd distributionsmiljö.

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

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.

GitLab CI/CD

Lagra båda värdena under Settings → CI/CD → Variables. Skydda distributionstoken, maskera den och begränsa den till miljön 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 exponerar automatiskt CHATTYBOX_DEPLOY_TOKEN och CHATTYBOX_API_URL för jobbet med deras variabelnamn. Använd en skyddad standardgren så att skyddade variabler inte är tillgängliga för opålitliga grenar.

Bitbucket Pipelines

Lägg till båda värdena som distributionsvariabler under Repository settings → Pipelines → Deployments → Production. Markera distributionstoken som säkrad.

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

Ersätt main om din standardgren har ett annat namn. Bitbucket injicerar distributionsvariabler endast i steg som är kopplade till den distributionsmiljön.

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	Styr Auto/Fixed-locale, standardspråk och sidans locale-overrides.
widget	Styr aktivering, placering, text, färger och presentation med standard-, emoji- eller URL-ikon i den utökade konfigurationen.

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.

development är endast en pekare och preview/production delar samma runtime, korpus och publika nycklar; använd separata projekt för isolering. Rollback/promote återställer inte historiskt korpusinnehåll eller en append-only promotionshistorik och köar arbete enligt aktuella planregler.