CLI ja määritysten käyttöönotto

CLI luo, validoi, ottaa käyttöön, promotoi ja palauttaa muuttumattomia ChattyBox-määritysversioita. Käyttöönotto-tokenit rajataan yhteen projektiin ja valittuihin ympäristöihin, joten sama työnkulku sopii paikalliseen kehitykseen ja CI:hin.

Määrityksen luominen

bunx @openstaticfish/chattybox-cli init

Tämä luo tiedoston chattybox.config.json:

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

Käytä mukautettua polkua, kun määritys kuuluu alihakemistoon:

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

Validointi paikallisesti tai CI:ssä

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

Validointi tarkistaa skeeman, pakollisen avustajan nimen, tuetut lähdetyypit, HTTP-lähteiden URL-osoitteet, positiiviset sivurajat ja widgetin värit. Onnistunut validointi ei ota mitään käyttöön eikä muuta etätilaa.

Käyttöönotto-tokenin luominen

Avaa projektin Settings-välilehti, etsi Config deployment tokens ja luo token niille ympäristöille, joita työnkulkusi voi muuttaa. Kopioi token heti; ChattyBox tallentaa vain sen hashin eikä voi näyttää sitä uudelleen.

Aseta token ja widgetin API-URL projektin Embed-välilehdeltä:

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

Älä koskaan commitoi tokenia. Tallenna se CI-palveluntarjoajan salattuun salaisuussäilöön.

Kun olet varmistanut käyttöönottotyönkulun, ota Config-as-code lock käyttöön samassa asetusten osiossa. Lukitus estää määrityksen ja korpuksen muutokset hallintapaneelissa, joten vain rajatut käyttöönotto-tokenit voivat muuttaa runtimea. Tokeneita voi edelleen luoda ja peruuttaa, jos CI-tunnistetieto täytyy kierrättää.

Määrityksen käyttöönotto

Käyttöönotto luo muuttumattoman version ja promotoi sen valittuun ympäristöön:

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

Kehitys- ja esikatseluympäristöihin tehdyt promootiot kirjataan tarkistettaviksi. Tuotantopromootiot ottavat avustajan kehotteen, varavastauksen, widget-asetukset, kielialueen ja verkkosivustolähteen käyttöön atomisesti aktiivisessa projektissa. Tuotantomäärityksen on sisällettävä täsmälleen yksi verkkosivustolähde. Käyttöönotto lisää jonoon versioon sidotun kaavintatyön, joka suoritetaan aiempien töiden valmistuttua. Sen jälkeen käyttöönotto korvaa vanhan korpuksen ja generoi embeddingit uudelleen. Nykyinen runtime hylkää useita lähteitä sisältävät määritykset.

Käytä --json-valitsinta automaatiossa saadaksesi version, ympäristön, sovelluksen tilan ja kaavintatyön tunnuksen jäsenneltynä tulosteena.

Tila, promootio ja palautus

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

Palautus promotoi vanhemman muuttumattoman version ja ottaa sen uudelleen käyttöön; se ei koskaan kirjoita käyttöönottohistoriaa uudelleen. Määritys palautetaan heti, mutta tarvittava sisällön päivitys jatkuu asynkronisesti.

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

Käytä ympäristöön rajattua tuotannon salaisuutta ja vaadi käyttöönotolle hyväksyntä, jos repositoriosi tukee sitä. CLI tallentaa yleiset CI:n commit- ja branch-muuttujat muuttumattoman version yhteyteen.

Määrityksen osiot

Osio	Tarkoitus
schemaVersion	Valitsee julkisen määrityssopimuksen. Tällä hetkellä tuetaan versiota 1.
assistant	Nimeää avustajan ja määrittää valinnaisesti sen kehoteprofiilin ja järjestelmäkehotteen.
knowledge.sources	Määrittää verkkosivustolähteet sekä valinnaiset sisällytys- ja poissulkemismallit.
runtime	Sisältää suoritusajan oletukset, kuten maa-asetuksen.
widget	Kuvaa hostatun widgetin valinnaiset esitysasetukset.

Tyypitetyn määrityksen apufunktio

Asenna määrityspaketti, kun rakennat skeeman ympärille erillisiä TypeScript-työkaluja:

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 lukee itse JSON-tiedostoja. defineConfig() on tarkoitettu tyypitettyihin sovellus- tai koontityökaluihin; se ei tee TypeScript-tiedostoista suoraan CLI:n ladattavia.

Käytä tällä hetkellä toimivaan tuotantointegraatioon hostattua widgetiä tai rakenna mukautettu käyttöliittymä JavaScript SDK:lla.