CLI dan deployment konfigurasi

CLI membuat, memvalidasi, melakukan deployment, mempromosikan, dan melakukan rollback versi konfigurasi ChattyBox yang immutable. Token deployment dibatasi untuk satu project dan environment yang dipilih, sehingga alur kerja yang sama cocok untuk pengembangan lokal dan CI.

Membuat konfigurasi

bunx @openstaticfish/chattybox-cli init

Perintah ini membuat chattybox.config.json:

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

Gunakan path khusus jika konfigurasi berada dalam subdirektori:

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

Memvalidasi secara lokal atau di CI

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

Validasi memeriksa skema, nama asisten yang wajib, tipe sumber yang didukung, URL sumber HTTP, batas halaman positif, dan warna widget. Validasi yang berhasil tidak melakukan deployment atau mengubah state jarak jauh.

Membuat token deployment

Buka tab Settings project, cari Config deployment tokens, lalu buat token untuk environment yang dapat diubah oleh alur kerja Anda. Segera salin token tersebut; ChattyBox hanya menyimpan hash-nya dan tidak dapat menampilkannya lagi.

Atur token dan URL API widget dari tab Embed project:

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

Jangan pernah commit token. Simpan token di secret store terenkripsi milik penyedia CI Anda.

Setelah memverifikasi alur deployment, aktifkan Config-as-code lock di bagian pengaturan yang sama. Lock ini menonaktifkan perubahan konfigurasi dan corpus dari dashboard, sehingga hanya token deployment dengan cakupan yang sesuai yang dapat mengubah runtime. Pembuatan dan pencabutan token tetap tersedia jika kredensial CI perlu dirotasi.

Deploy konfigurasi

Deployment membuat versi immutable dan mempromosikannya ke environment yang dipilih:

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

Promosi development dan preview dicatat untuk ditinjau. Promosi production menerapkan secara atomik prompt asisten, respons fallback, pengaturan widget, locale, dan sumber situs web ke project live. Konfigurasi production harus berisi tepat satu sumber website. Deployment mengantrekan scraping yang terikat pada versi untuk dijalankan setelah job-job sebelumnya selesai. Setelah itu, deployment mengganti corpus lama dan membuat ulang embedding. Runtime saat ini menolak konfigurasi dengan banyak sumber.

Gunakan --json dalam otomatisasi untuk menerima versi, environment, status aplikasi, dan ID job scraping sebagai output terstruktur.

Status, promosi, dan 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

Rollback mempromosikan dan menerapkan ulang versi immutable yang lebih lama; tindakan ini tidak pernah menulis ulang riwayat deployment. Konfigurasi dipulihkan segera, sementara refresh konten yang diperlukan berlanjut secara asinkron.

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

Gunakan secret production yang dicakup oleh environment dan wajibkan persetujuan deployment jika repositori Anda mendukungnya. CLI mencatat variabel commit dan branch CI umum bersama versi immutable.

Bagian konfigurasi

Bagian	Tujuan
schemaVersion	Memilih kontrak konfigurasi publik. Versi 1 saat ini didukung.
assistant	Memberi nama asisten dan secara opsional menentukan profil prompt serta prompt sistemnya.
knowledge.sources	Mendeklarasikan sumber situs web serta pola penyertaan dan pengecualian opsional.
runtime	Menyimpan nilai default runtime seperti locale.
widget	Menjelaskan pengaturan presentasi opsional untuk widget yang dihosting.

Helper konfigurasi bertipe

Instal paket konfigurasi saat membangun tooling TypeScript terpisah di sekitar skema:

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 itu sendiri membaca file JSON. defineConfig() ditujukan untuk aplikasi bertipe atau tooling build; fungsi ini tidak membuat file TypeScript dapat langsung dimuat oleh CLI.

Untuk integrasi produksi yang berfungsi saat ini, gunakan widget yang dihosting atau bangun antarmuka khusus dengan SDK JavaScript.