CLI a gosod ffurfweddiad

Mae arteffactau CLI/config cyhoeddedig fersiwn 0.3.1 yn gweithredu contract ffurfweddiad/backend 0.3.0 ac yn gwrthod allweddi anhysbys yn lleol ac yn y backend.

Mae'r CLI yn creu, yn dilysu, yn gosod, yn hyrwyddo ac yn dychwelyd fersiynau digyfnewid o ffurfweddiad ChattyBox. Mae pob tocyn gosod wedi'i gyfyngu i un prosiect sy'n bodoli eisoes ac amgylcheddau dethol. Triniwch un ffeil ffurfweddu ac un tocyn wedi'i gyfyngu i brosiect fel un prosiect ChattyBox a reolir.

Statws rhyddhau a runtime

Mae @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1, a'r SDK JavaScript ar wahân @openstaticfish/chattybox@0.1.4 ar gael yn y gofrestrfa gyhoeddus. Mae'r arteffactau CLI/config yn cefnogi'r contract estynedig a'r backend 0.3.0. Mae fersiynau pecyn a schemaVersion: "1" yn systemau fersiynu ar wahân.

Mae'r gorchmynion sylfaenol isod yn bodoli yn y CLI cyhoeddedig. Mae'r CLI/config 0.3.1 yn rhannu'r rheolau dilysu â'r backend 0.3.0 ac yn cefnogi'r contract estynedig. Mae status yn dangos fersiwn yr amgylchedd, tra mai runtimeConfigVersionId yw'r ffurfweddiad olaf a gymhwyswyd i'r runtime a rennir a gall fod yn wahanol. Mae hepgor mode yn dewis crawl heb newid maxDepth: 0 penodol.

Creu ffurfweddiad

bunx @openstaticfish/chattybox-cli init

Mae hyn yn creu chattybox.config.json:

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

Defnyddiwch lwybr personol pan fo'r ffurfweddiad yn perthyn mewn isgyfeiriadur:

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

Dilysu'n lleol neu mewn CI

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

Mae dilysiad ffynhonnell gyfredol yn gwirio siapiau gwrthrychau, enw gofynnol y cynorthwyydd, enums, URLau HTTP(S), terfynau cyfanrif, cyfuniadau locale a lliwiau hex chwe digid. Gall knowledge gael ei hepgor wrth ddilysu lleol, ond pan fo'n bresennol mae angen union un ffynhonnell gwefan; mae preview a production yn ei gwneud yn ofynnol. Mae dilysiad yn darllen JSON yn unig, nid yw'n gwneud cais rhwydwaith, yn gwirio tocyn/entitlement, nac yn cymhwyso defaults. Nid gwarant gosod yw llwyddiant lleol.

Creu tocyn gosod

Agorwch dab Settings y prosiect, dewch o hyd i Config deployment tokens, ac yna crëwch docyn ar gyfer yr amgylcheddau y gall eich llif gwaith eu newid. Copïwch ef ar unwaith; dim ond ei hash y mae ChattyBox yn ei storio ac ni all ei ddangos eto.

Gosodwch y tocyn ac URL API y widget o dab Embed y prosiect:

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

Peidiwch byth â chyflwyno'r tocyn. Storiwch ef yn storfa gyfrinachau wedi'i hamgryptio gan eich darparwr CI.

Ar ôl gwirio'r llif gwaith gosod, galluogwch Config-as-code lock yn yr un adran gosodiadau. Mae'r clo'n analluogi newidiadau i ffurfweddiad a chorffws o'r dangosfwrdd, felly dim ond tocynnau gosod sydd â'r cwmpas priodol all newid y runtime. Mae creu a dirymu tocynnau yn parhau ar gael os bydd angen cylchdroi manylyn adnabod CI.

Gosod ffurfweddiad

Mae gosod yn creu fersiwn ddigynewid ac yn ei hyrwyddo i'r amgylchedd dethol:

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

Mae development yn cofnodi pwyntydd fersiwn yn unig (applied: false, indexingStatus: "not_required"). Mae preview a production yn trosysgrifo'r un gosodiadau runtime, corpus ac allweddi cyhoeddus: y dyrchafiad runtime diweddaraf sy'n ennill. Mae'r naill na'r llall yn cymhwyso ffurfweddiad yn atomig ac yn ciwio scrape (applied: true, indexingStatus: "pending"), ond nid ydynt yn aros am sgrapio nac embeddings. Mae adnewyddiadau'n diweddaru tudalennau yn eu lle ac nid ydynt yn dileu URLau hŷn dim ond am fod ffynhonnell neu hidlydd newydd yn eu hepgor; nid snapshot fersiwnedig yw'r corpus.

Defnyddiwch --json mewn awtomeiddio i gael y fersiwn, yr amgylchedd, statws y rhaglen ac ID y job sgrapio fel allbwn strwythuredig.

Statws, hyrwyddo a dychwelyd

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

Mae --version yn cymryd version._id afloyw, nid rhif, SHA na hash. Mae rollback yn defnyddio'r un hyrwyddo, nid oes rhaid iddi dargedu fersiwn hŷn ac mae'n ciwio adnewyddiad newydd; nid yw'n adfer corpus hanesyddol na gwarantu hanes hyrwyddo append-only.

Disodli a therfynau cynllun

Defnyddiwch ffurfweddiad dymunol cyflawn, nid patch: caiff meysydd config-owned a hepgorir eu clirio neu eu hailosod, heblaw widget.showBranding, sy'n cadw'r dewis cyfredol. Mae maxPages yn storio'r cais heb ei glampio; mae'r rhediad yn defnyddio'r capasiti effeithiol a ddisgrifir yn y rheolau sgrapio. Mae daily auto-refresh a showBranding:false yn gofyn am Starter+; nid yw scope tocyn environment yn ynysu production oddi wrth preview.

Llifau gwaith CI/CD

Ychwanegwch CHATTYBOX_DEPLOY_TOKEN fel cyfrinach wedi'i hamgryptio wedi'i chwmpasu i gynhyrchu yn eich darparwr CI. Ychwanegwch CHATTYBOX_API_URL fel cyfrinach neu newidyn gan ddefnyddio URL API y widget o dab Embed y prosiect. Rhedwch ddilysiad ar pull requests, ond cyfyngwch osod cynhyrchu i'ch cangen ddiofyn warchodedig neu amgylchedd gosod a gymeradwywyd.

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

Defnyddiwch gyfrinach gynhyrchu wedi'i chwmpasu gan amgylchedd a gofynnwch am gymeradwyaeth i'r gosodiad pan fo'ch ystorfa'n ei gefnogi. Mae'r CLI yn cofnodi newidynnau cyffredin commit a changen CI gyda'r fersiwn ddigynewid.

GitLab CI/CD

Storiwch y ddau werth o dan Settings → CI/CD → Variables. Gwarchodwch gyfrinach y gosodiad, ei chuddio, a'i chwmpasu i'r amgylchedd 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

Mae GitLab yn datgelu CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL yn awtomatig i'r swydd gan ddefnyddio eu henwau newidynnau. Defnyddiwch gangen ddiofyn warchodedig fel nad yw newidynnau gwarchodedig ar gael i ganghennau annibynadwy.

Bitbucket Pipelines

Ychwanegwch y ddau werth fel newidynnau gosod o dan Repository settings → Pipelines → Deployments → Production. Marciwch gyfrinach y gosodiad fel un ddiogel.

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

Amnewidiwch main os oes gan eich cangen ddiofyn enw arall. Mae Bitbucket yn mewnosod newidynnau gosod i gamau sy'n gysylltiedig â'r amgylchedd gosod hwnnw yn unig.

Adrannau ffurfweddu

Adran	Diben
schemaVersion	Yn dewis y contract ffurfweddu cyhoeddus. Cefnogir fersiwn 1 ar hyn o bryd.
assistant	Yn enwi'r cynorthwyydd ac, yn ddewisol, yn diffinio ei broffil anogwr a'i anogwr system.
knowledge.sources	Yn datgan ffynonellau gwefannau a phatrymau cynnwys/eithrio dewisol.
runtime	Yn cadw rhagosodiadau amser rhedeg, megis locale.
widget	Yn disgrifio gosodiadau cyflwyno dewisol y widget lletyol.

Cynorthwyydd ffurfweddu wedi'i deipio

Gosodwch y pecyn ffurfweddu wrth adeiladu offer TypeScript ar wahân o amgylch y sgema:

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

Mae'r CLI ei hun yn darllen ffeiliau JSON. Mae defineConfig() ar gyfer offer rhaglen neu adeiladu wedi'u teipio; nid yw'n gwneud ffeiliau TypeScript yn rhai y gall y CLI eu llwytho'n uniongyrchol.

Ar gyfer integreiddiad cynhyrchu sy'n gweithio heddiw, defnyddiwch y widget lletyol neu adeiladwch ryngwyneb personol gyda'r SDK JavaScript.