CLI a nasazování konfigurace

CLI vytváří, ověřuje, nasazuje, propaguje a vrací neměnné verze konfigurace ChattyBoxu. Nasazovací tokeny jsou omezené na jeden projekt a vybraná prostředí, takže stejný postup je vhodný pro místní vývoj i CI.

Vytvoření konfigurace

bunx @openstaticfish/chattybox-cli init

Tím se vytvoří soubor chattybox.config.json:

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

Pokud konfigurace patří do podadresáře, použijte vlastní cestu:

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

Místní ověření nebo ověření v CI

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

Ověření kontroluje schéma, povinný název asistenta, podporované typy zdrojů, adresy URL zdrojů HTTP, kladné limity stránek a barvy widgetu. Úspěšné ověření nic nenasazuje ani nemění vzdálený stav.

Vytvoření nasazovacího tokenu

Otevřete kartu projektu Settings, vyhledejte Config deployment tokens a vytvořte token pro prostředí, která může váš pracovní postup měnit. Ihned ho zkopírujte; ChattyBox ukládá pouze jeho hash a znovu ho nemůže zobrazit.

Nastavte token a URL API widgetu z karty projektu Embed:

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

Token nikdy necommitujte. Uložte ho do šifrovaného úložiště tajných údajů poskytovatele CI.

Po ověření pracovního postupu nasazování povolte ve stejné části nastavení Config-as-code lock. Zámek zakáže změny konfigurace a korpusu z dashboardu, takže běhové prostředí mohou měnit pouze nasazovací tokeny s příslušným rozsahem. Vytváření a odvolávání tokenů zůstane k dispozici, pokud je potřeba obměnit přihlašovací údaj CI.

Nasazení konfigurace

Nasazení vytvoří neměnnou verzi a propaguje ji do vybraného prostředí:

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

Propagace do vývojového a preview prostředí se zaznamenává ke kontrole. Propagace do produkce atomicky aplikuje prompt asistenta, záložní odpověď, nastavení widgetu, jazykové nastavení a zdroj webu na živý projekt. Produkční konfigurace musí obsahovat přesně jeden zdroj webu. Nasazení zařadí do fronty scraping navázaný na verzi, který se spustí po dokončení předchozích úloh. Poté nahradí předchozí korpus a znovu vygeneruje embeddingy. Aktuální runtime odmítá konfigurace s více zdroji.

V automatizaci použijte --json, abyste jako strukturovaný výstup získali verzi, prostředí, stav aplikace a ID úlohy scrapingu.

Stav, propagace a návrat

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

Návrat propaguje a znovu aplikuje starší neměnnou verzi; nikdy nepřepisuje historii nasazení. Konfiguraci obnoví okamžitě, zatímco případná potřebná aktualizace obsahu pokračuje asynchronně.

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

Použijte produkční tajný údaj omezený na prostředí a vyžadujte schválení nasazení, pokud to váš repozitář podporuje. CLI zaznamenává běžné CI proměnné commitu a větve spolu s neměnnou verzí.

Části konfigurace

Část	Účel
schemaVersion	Vybírá veřejný konfigurační kontrakt. V současnosti je podporována verze 1.
assistant	Pojmenovává asistenta a volitelně definuje jeho profil pokynů a systémový pokyn.
knowledge.sources	Deklaruje zdroje webových stránek a volitelné vzory pro zahrnutí či vyloučení.
runtime	Obsahuje výchozí hodnoty běhového prostředí, například locale.
widget	Popisuje volitelná nastavení vzhledu hostovaného widgetu.

Pomocná funkce pro typovanou konfiguraci

Při vytváření samostatných nástrojů TypeScript nad schématem nainstalujte konfigurační balíček:

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

Samotné CLI čte soubory JSON. defineConfig() je určené pro typované aplikační nebo sestavovací nástroje; neumožňuje CLI přímo načítat soubory TypeScript.

Pro funkční produkční integraci dnes použijte hostovaný widget nebo vytvořte vlastní rozhraní pomocí JavaScript SDK.