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

Julkaistut CLI/config-artefaktit versiolla 0.3.1 toteuttavat määritys-/backend-sopimuksen 0.3.0 ja hylkäävät tuntemattomat avaimet sekä paikallisesti että taustajärjestelmässä.

CLI luo, validoi, ottaa käyttöön, promotoi ja palauttaa muuttumattomia ChattyBox-määritysversioita. Käyttöönotto-tokenit rajataan täsmälleen yhteen olemassa olevaan projektiin ja valittuihin ympäristötunnuksiin, joten yksi asetustiedosto ja projektikohtainen token hallitsevat yhtä ChattyBox-projektia.

Julkaisu- ja runtime-tila

Julkisessa rekisterissä ovat @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 ja erillinen JavaScript SDK @openstaticfish/chattybox@0.1.4. Paketit tukevat laajennettuja määrityskenttiä yhdessä backend-sopimuksen 0.3.0 kanssa. Pakettiversio ja schemaVersion: "1" ovat eri versiomekanismeja.

Peruskomennot ja aloitusmääritys ovat julkaistussa CLI:ssä. Julkaistu 0.3.1 tukee laajennettuja määrityskenttiä ja jakaa validointisäännöt backend-sopimuksen 0.3.0 kanssa. status näyttää ympäristöversion, kun taas runtimeConfigVersionId on jaettuun runtimeen viimeksi sovellettu määritys ja voi poiketa siitä. Jos mode jätetään pois, valitaan crawl ja eksplisiittinen maxDepth: 0 säilyy.

CLI on ESM-komentoriviohjelma, joka edellyttää Node.js 20:tä tai uudempaa. bunx noudattaa oletuksena sen Node-shebangia; asenna Node tai valitse Bun nimenomaisesti komennolla bunx --bun @openstaticfish/chattybox-cli .... Kiinnitä tuotantoautomaatiossa testattu pakettiversio.

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

Nykyisen lähteen validointi tarkistaa objektimuodot, pakollisen avustajan nimen, enumit, HTTP(S)-URL-osoitteet, kokonaislukurajat, locale-yhdistelmät ja kuusinumeroiset heksavärit. knowledge voi puuttua paikallisessa validoinnissa tai development-ympäristössä, mutta mukana ollessaan sen on sisällettävä täsmälleen yksi verkkosivustolähde. Preview ja production edellyttävät lähdettä.

Validointi lukee vain JSONia; se ei lataa TypeScriptiä, JSONC:tä, YAML:ia tai etäskeemaa, ei tee verkkopyyntöä eikä tarkista tokenia tai pakettioikeuksia. Se ei ole käyttöönoton takuu.

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, voit ottaa Config-as-code lock -lukituksen käyttöön samassa asetusten osiossa. Lukitusta ei voi perua nykyisessä hallintapaneelissa, CLI:ssä tai julkisessa API:ssa. Se estää hallintapaneelin config-omisteiset asetukset, kuvakkeiden lataukset ja manuaaliset korpusoperaatiot, kuten haravoinnin, sivujen poistamisen, sisällön tyhjennyksen ja embeddingien uudelleenluonnin. Se ei estä ajastettua työtä tai projektin poistoa. Tokeneita ja julkisia avaimia voi silti hallita.

Branding on poikkeus: hallintapaneelin pelkkä branding-asetus pysyy muokattavana lukitussa projektissa paketin sallimissa rajoissa. Free-paketissa branding pakotetaan käyttöön.

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

development tallentaa vain version/osoittimen (applied: false, indexingStatus: "not_required"). preview ja production ylikirjoittavat saman projektin runtime-asetukset ja käyttävät samaa korpusta sekä samoja julkisia widget-avaimia; viimeisin runtime-promootio voittaa. Käytä erillisiä projekteja todelliseen eristykseen. Molemmat ottavat määrityksen käyttöön atomisesti ja lisäävät kaavintatyön jonoon (applied: true, indexingStatus: "pending"), mutta eivät odota kaavintaa tai embeddingien valmistumista. Päivitykset muuttavat sivuja paikallaan eivätkä poista vanhoja URL-osoitteita vain siksi, että uusi lähde tai suodatin jättää ne pois. Korpus ei ole versioitu tilannevedos, eikä epäonnistunut päivitys peru jo käyttöönotettua määritystä.

Ota käyttöön koko haluttu määritys, ei paikkausta. Omittoidut config-omisteiset arvot voivat nollata aiemmat hallintapaneelin arvot: runtime palautuu automaattiseen localeen, oletukseen en ja sallittuihin ohituksiin; widget.icon palautuu oletuskuvakkeeseen (medium-koko, jota hostattu loader ei käytä); lähdetila oletuksena crawl-tilaan ja automaattinen päivitys pois. maxPages tallentaa pyynnön ilman rajausta; ajo käyttää scraping-säännöissä kuvattua tehokasta kapasiteettia.

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

--version käyttää läpinäkymätöntä määritysversiotunnusta, ei näkyvää numeroa. Rollback käyttää samaa taustaoperaatiota kuin promote, sen ei tarvitse kohdistua vanhempaan versioon, ja se ylikirjoittaa valitun ympäristön osoittimen sekä promootiotiedot; append-only-promootiohistoriaa ei ole. Preview- tai production-rollback ottaa määrityksen uudelleen käyttöön nykyisillä käyttöoikeuksilla ja lisää uuden päivityksen jonoon sen sijaan, että se palauttaisi historiallisen korpuksen.

CI/CD-työnkulut

Lisää CHATTYBOX_DEPLOY_TOKEN salattuna tuotantoon rajattuna salaisuutena CI-palveluusi. Lisää CHATTYBOX_API_URL salaisuutena tai muuttujana käyttämällä widgetin API-URL-osoitetta projektin Embed-välilehdeltä. Suorita validointi pull requestien yhteydessä, mutta rajoita tuotantokäyttöönotto suojattuun oletushaaraan tai hyväksyttyyn käyttöönottopaikkaan.

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

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.

GitLab CI/CD

Tallenna molemmat arvot kohtaan Settings → CI/CD → Variables. Suojaa käyttöönottotunnus, peitä se ja rajaa se production-ympäristöön.

.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 tuo CHATTYBOX_DEPLOY_TOKEN- ja CHATTYBOX_API_URL-muuttujat työtehtävään automaattisesti niiden muuttujanimillä. Käytä suojattua oletushaaraa, jotta suojatut muuttujat eivät ole epäluotettavien haarojen käytettävissä.

Bitbucket Pipelines

Lisää molemmat arvot käyttöönottomuuttujina kohtaan Repository settings → Pipelines → Deployments → Production. Merkitse käyttöönottotunnus suojatuksi.

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

Korvaa main, jos oletushaarallasi on toinen nimi. Bitbucket lisää käyttöönottomuuttujat vain vaiheisiin, jotka liittyvät kyseiseen käyttöönottopaikkaan.

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.
project	Valinnainen projektin metatieto, kuten hallintapaneelikuvaus.
knowledge.sources	Valitsee etusivu-, sivukartta-, manuaali- tai crawl-löytämisen sekä rajat, suodattimet ja päivitysaikataulun.
runtime	Hallitsee automaattista/kiinteää localea, oletuslocalea ja sivukohtaisia locale-ohituksia.
widget	Hallitsee käyttöä, sijoittelua, tekstiä, värejä ja oletus-/emoji-/URL-kuvaketta.

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.