CLI i wdrażanie konfiguracji

Opublikowane artefakty CLI/config w wersji 0.3.1 implementują kontrakt konfiguracji/backendu 0.3.0 i odrzucają nieznane klucze zarówno lokalnie, jak i w backendzie.

CLI tworzy, weryfikuje i wdraża niezmienne wersje konfiguracji ChattyBox, a także je promuje i przywraca. Tokeny wdrażania są przypisane do jednego projektu i wybranych środowisk, dzięki czemu ten sam proces sprawdza się w lokalnym środowisku programistycznym i w CI.

Stan wydania i środowiska wykonawczego

Opublikowane są @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 oraz SDK JavaScript @openstaticfish/chattybox@0.1.4. Artefakty te obsługują rozszerzoną konfigurację wraz z kontraktem backendu 0.3.0; schemaVersion: "1" nie jest wersją pakietu. status pokazuje wersję środowiska, natomiast runtimeConfigVersionId oznacza ostatnią konfigurację zastosowaną do współdzielonego runtime i może się różnić. Pominięte mode wybiera crawl, zachowując jawne maxDepth: 0. CLI wymaga Node 20+ (lub jawnego bunx --bun).

Tworzenie konfiguracji

bunx @openstaticfish/chattybox-cli init

To polecenie tworzy plik chattybox.config.json:

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

Użyj niestandardowej ścieżki, gdy konfiguracja ma znajdować się w podkatalogu:

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

Weryfikacja lokalna lub w CI

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

Walidacja czyta tylko JSON i nie wykonuje sieci, nie sprawdza tokenu/planu ani nie stosuje defaults. Lokalny sukces nie gwarantuje wdrożenia, ale zarówno walidator lokalny, jak i backend odrzucają nieznane pola.

Tworzenie tokenu wdrażania

Otwórz kartę Settings projektu, znajdź Config deployment tokens i utwórz token dla środowisk, które może zmieniać Twój proces. Skopiuj go od razu — ChattyBox przechowuje tylko jego skrót i nie może wyświetlić go ponownie.

Ustaw token i adres URL API widżetu z karty Embed projektu:

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

Nigdy nie zatwierdzaj tokenu w repozytorium. Przechowuj go w zaszyfrowanym magazynie sekretów dostawcy CI.

Po zweryfikowaniu procesu można włączyć Config-as-code lock. Jest nieodwracalny w obecnym panelu, CLI i publicznym API; blokuje dashboardowe ustawienia, upload ikon oraz ręczne scrape/usuwanie/rebuild. Tokeny i klucze publiczne pozostają zarządzalne. Wyjątek: planowo dozwolone ustawienie brandingu pozostaje edytowalne w panelu.

Wdrażanie konfiguracji

Wdrożenie tworzy niezmienną wersję i promuje ją do wybranego środowiska:

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

development jedynie zapisuje wskaźnik (applied: false). Preview i production współdzielą ten sam runtime, korpus oraz publiczne klucze; najnowsza promocja wygrywa. Użyj osobnych projektów dla faktycznej izolacji. Preview/production atomowo stosują config i kolejkują scrape, ale nie czekają na indeksowanie, nie usuwają starych URL-i pominiętych w nowym źródle i nie przywracają konfiguracji po błędzie odświeżania.

Użyj --json w automatyzacji, aby otrzymać wersję, środowisko, status aplikacji i identyfikator zadania skanowania w postaci danych strukturalnych.

Status, promocja i 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 przyjmuje nieprzezroczyste version._id, nie numer, SHA ani hash. Rollback używa tej samej promocji, nie musi wskazywać starszej wersji i kolejkuje nowe odświeżenie; nie odtwarza historycznego korpusu ani nie gwarantuje append-only historii promocji.

Limity i pełna konfiguracja

Promuj kompletną konfigurację, nie patch: pominięte pola config-owned są resetowane, poza widget.showBranding, które zachowuje bieżącą preferencję. maxPages zapisuje żądanie bez ograniczania; uruchomienie używa efektywnej pojemności opisanej w zasadach scrapingu. Daily auto-refresh i showBranding:false wymagają Starter+. Token environment scope nie izoluje produkcji od preview.

Przepływy pracy CI/CD

Dodaj CHATTYBOX_DEPLOY_TOKEN jako zaszyfrowany sekret ograniczony do produkcji u dostawcy CI. Dodaj CHATTYBOX_API_URL jako sekret lub zmienną, używając adresu URL API widżetu z karty Embed projektu. Uruchamiaj walidację dla pull requestów, ale ogranicz wdrożenia produkcyjne do chronionej gałęzi domyślnej lub zatwierdzonego środowiska wdrożeniowego.

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

Użyj sekretu produkcyjnego przypisanego do środowiska i wymagaj zatwierdzenia wdrożenia, jeśli Twoje repozytorium to obsługuje. CLI zapisuje typowe zmienne CI dotyczące commita i gałęzi razem z niezmienną wersją.

GitLab CI/CD

Przechowuj obie wartości w Settings → CI/CD → Variables. Chroń token wdrożenia, zamaskuj go i ogranicz go do środowiska 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 automatycznie udostępnia zadaniu CHATTYBOX_DEPLOY_TOKEN i CHATTYBOX_API_URL, używając ich nazw zmiennych. Użyj chronionej gałęzi domyślnej, aby chronione zmienne nie były dostępne dla niezaufanych gałęzi.

Bitbucket Pipelines

Dodaj obie wartości jako zmienne wdrożeniowe w Repository settings → Pipelines → Deployments → Production. Oznacz token wdrożenia jako zabezpieczony.

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

Zastąp main, jeśli Twoja gałąź domyślna ma inną nazwę. Bitbucket wstrzykuje zmienne wdrożeniowe tylko do kroków powiązanych z tym środowiskiem wdrożeniowym.

Sekcje konfiguracji

Sekcja	Przeznaczenie
schemaVersion	Wybiera publiczny kontrakt konfiguracji. Obecnie obsługiwana jest wersja 1.
assistant	Określa nazwę asystenta oraz opcjonalnie jego profil promptu i prompt systemowy.
knowledge.sources	Deklaruje źródła internetowe oraz opcjonalne wzorce uwzględniania i wykluczania.
runtime	Zawiera domyślne ustawienia środowiska wykonawczego, takie jak locale.
widget	Opisuje opcjonalne ustawienia wyglądu hostowanego widżetu.

Typowany pomocnik konfiguracji

Zainstaluj pakiet konfiguracyjny, jeśli tworzysz osobne narzędzia TypeScript korzystające ze schematu:

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

Samo CLI odczytuje pliki JSON. defineConfig() jest przeznaczone dla typowanych aplikacji lub narzędzi kompilacji; nie umożliwia CLI bezpośredniego wczytywania plików TypeScript.

Aby już dziś uzyskać działającą integrację produkcyjną, użyj hostowanego widżetu lub zbuduj własny interfejs za pomocą SDK JavaScript.