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 julkaistut CLI- ja config-paketit @openstaticfish/chattybox-cli@0.3.1 ja @openstaticfish/chattybox-config@0.3.1; ne toteuttavat laajennetun määrityksen ja backend-sopimuksen 0.3.0. Erillinen JavaScript SDK @openstaticfish/chattybox@0.1.4 on oma pakettinsa eikä osa config-sopimusta. 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 .... Se ei ole selainkäyttöön tarkoitettu työkalu. Julkaistujen pakettien kuluttajatestit kattavat Node 20:n, 22:n ja 24:n Linuxissa, eivät yleistä käyttöjärjestelmä- tai selainyhteensopivuutta. Kiinnitä tuotantoautomaatiossa testattu pakettiversio; versioimattomat esimerkit käyttävät asennettua, välimuistissa olevaa tai rekisteristä haettua pakettia, eivät tämän repositorion lähdekoodia.
Mitä määritys koodina hallitsee
Määritys hallitsee projektin nimeä ja kuvausta, avustajan persoonaa ja varavastauksia, sivuston lähteiden etsintää ja päivityskäytäntöä, kieliasetuksia sekä hostatun widgetin ulkoasua. Preview- tai production-käyttöönotto soveltaa arvot ja lisää olemassa olevan sisältökokoelman päivityksen jonoon. Kun Config-as-code lock on käytössä, määrityksen hallitsemia asetuksia muutetaan versioiduilla käyttöönotoilla hallintapaneelin lomakkeiden sijaan; käyttöoikeuksista riippuva brändäysasetus on poikkeus.
Projekti luodaan aluksi kerran hallintapaneelissa. Julkiset widget-avaimet ja niiden valinnaiset origin-rajoitukset, deployment-tokenien elinkaari, analytiikka, keskustelut, sisältöaukot, tuhoavat toiminnot ja ladatut kuvaketiedostot eivät ole määrityskenttiä. Käytä deklaratiiviseen omaan kuvakkeeseen URL-osoitetta tai emojia. Määritys ei sisällä projektitunnusta: salainen deployment-token valitsee yhden kohdeprojektin.
Julkista widgetin API-avainta voi käyttää selainkoodissa chattiin ja widgetin määrityksen hakuun. Ilman rajoituksia luotu avain toimii eri selaimen origineista, mutta verkkosivustoa varten valmisteltu avain voi olla valmiiksi rajattu. Tarkat origin-rajoitukset ovat valinnainen lisäsuojaus, eivät kävijän todennus. Määritysten deployment-token taas oikeuttaa yhden projektin ja valittujen ympäristöjen deploy-, promote-, rollback- ja status-toimintoihin; säilytä se paikallisissa tai CI-salaisuuksissa, älä selaimessa.
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ä.
Paikallinen ja backendin määritysvalidointi käyttävät samoja sääntöjä ja hylkäävät tuntemattomat kentät kaikilla objektitasoilla. Validointi lukee vain JSONia; se ei lataa TypeScriptiä, JSONC:tä, YAML:ia tai etäskeemaa, tee verkkopyyntöjä, tarkista tokenia tai paketin käyttöoikeuksia eikä lisää oletusarvoja. Jos widget annetaan, myös widget.enabled on pakollinen. Paikallinen onnistuminen ei takaa käyttöönottoa.
Include- ja exclude-merkintöjen on oltava ei-tyhjiä merkkijonoja. runtime.locale on lyhenne kiinteälle kielelle ilman ohituksia, eikä sitä voi yhdistää arvoihin localeMode, defaultLocale tai allowLocaleOverride: true. Palvelin tarkistaa paketin käyttöoikeudet ja tokenin rajauksen.
Käyttöönotto-tokenin luominen
Avaa Chatbotin asetukset → Kehittäjämääritykset ja luo token niille ympäristöille, joita työnkulkusi voi muuttaa. Kopioi tokenin koko selväkielinen arvo heti; ChattyBox tallentaa siitä hashin sekä vain rajalliset tunnistus- ja elinkaarimetatiedot eikä voi näyttää koko arvoa uudelleen.
Lomake valitsee oletuksena vain development-ympäristön eikä aseta vanhenemisaikaa. Valitse tarvittaessa erikseen preview tai production.
Hallintapaneelissa voit valita, ettei token vanhene, tai asettaa vanhenemisajaksi 7, 30, 90 tai 365 päivää. Todennettu luonti-API hyväksyy kokonaisluvun väliltä 1–365 päivää; jos päivien määrä jätetään pois, token ei vanhene. Projektissa voi olla enintään 20 aktiivista ja vanhentumatonta tokenia. Kierrätä token luomalla korvaava token, päivittämällä CI ja perumalla vasta sitten vanha token. CLI:ssä ei ole kirjautumis- eikä tokenin luonti-, listaus- tai perumiskomentoja.
Aseta token ja widgetin API-URL. Käytä kohdassa Asenna → Verkkosivuston asennus olevan koodikatkelman data-api-url-arvoa, jos se on saatavilla; muussa tapauksessa hae HTTP-actions-julkaisun URL käyttöönottosi määrityksistä. Asennusnäkymän käyttö voi edellyttää, että käyttöönoton valmistelu on ensin tehty:
export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'
Älä koskaan commitoi tokenia äläkä sisällytä sitä selaimessa suoritettavaan koodiin. Tallenna se CI-palveluntarjoajan salattuun salaisuussäilöön. Käyttöönotto-tokenit todennetaan muodossa Authorization: Bearer ...; julkiset widget-avaimet eivät korvaa niitä. Hallintareitit eivät käytä widgetin alkuperärajoituksia, eivät vaadi Origin-otsaketta eivätkä tarjoa selaimen CORS-käyttöä. Tokenia ei ole sidottu alkuperään: sen haltija voi kutsua API:a palvelimelta.
Puuttuva, virheellinen, vanhentunut, peruttu tai väärään ympäristöön rajattu token palauttaa HTTP 401 INVALID_TOKEN. Token lakkaa toimimasta myös, jos sen projekti tai omistaja puuttuu tai on poistumassa.
Käytä HTTP-actions-julkaisun juuriosoitetta tai widgetin /chat-päätteistä URL-osoitetta. Älä käytä .convex.cloud-asiakasosoitetta tai täydellistä /v1/config/deployments-päätepistettä. CLI poistaa lopun kauttaviivat ja mahdollisen viimeisen /chat-osan ja lisää sitten hallintareitin. HTTPS on pakollinen paitsi osoitteille localhost, 127.0.0.1 ja [::1]; API-URL:ssa ei saa olla tunnistetietoja, kyselyosaa tai fragmenttia. Tarkista kohdeosoite ennen kuin annat salaisuuden.
Kun olet varmistanut käyttöönottotyönkulun, voit ottaa Config-as-code lock -lukituksen käyttöön samassa asetusten osiossa. Lukitus on peruuttamaton nykyisessä hallintapaneelissa, CLI:ssä ja julkisessa API:ssa; tuettua lukituksen avaustoimintoa ei ole. Käyttöönotto ei luo tokenia eikä ota versiota käyttöön. Testaa token-työnkulku ennen lukitsemista.
Lukitus estää hallintapaneelin kirjoitukset configin hallitsemiin projekti- ja widget-asetuksiin, kuvakkeiden lataukset ja manuaaliset korpusoperaatiot, kuten skrapauksen, sivujen poistamisen, sisällön tyhjentämisen ja embeddingien uudelleenluonnin. Ajastettu työ ja projektin poistaminen jatkuvat. Tokenien luonti ja peruminen, julkisten avainten hallinta ja operatiiviset lukutoiminnot ovat edelleen käytettävissä. Brändäys on poikkeus: brändäysasetus pysyy muokattavana lukitun projektin hallintapaneelissa paketin käyttöoikeuksien rajoissa. Brändäyksen piilottaminen edellyttää Starter-tilausta tai korkeampaa; widget.showBranding-kentän puuttuminen säilyttää nykyisen valinnan (tai oletusarvon true), ja Free-paketin runtime näyttää brändäyksen aina.
Nimenomaisesti annettu widget.showBranding ylikirjoittaa tallennetun valinnan seuraavassa runtime-promootiossa.
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, vaikka toisen ympäristön osoitin näyttäisi yhä vanhempaa versiota. preview-rajattu token voi siis muuttaa tuotantoliikennettä palvelevaa projektia. Käytä erillisiä projekteja, tokeneita ja avaimia 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ä.
Epäonnistuneesta työstä voi jäädä osittaisia päivityksiä. Työt tallentavat määritysversion tunnuksen mutta lukevat myös muuttuvia haravointiasetuksia; vältä päällekkäisiä käyttöönottoja, kun indeksoinnin johdonmukaisuus on tärkeää.
Ota käyttöön koko haluttu määritys, ei paikkausta. Pois jätetyt config-omisteiset arvot voivat tyhjentää tai palauttaa aiempia hallintapaneelin asetuksia. Jos widget jätetään pois, widget otetaan käyttöön. Jos widget on mukana, sen pakollista enabled-arvoa noudatetaan; pois jätetyt widgetin tekstin, teeman ja sijoittelun ylikirjoitukset tyhjennetään erikseen, jolloin runtimen oletusarvot tulevat käyttöön. Runtime-promootiossa aiemmin ladattu ikonitiedosto poistetaan riippumatta siitä, annetaanko deklaratiivinen korvaava kuvake. Oletuskuvake valitaan vain, kun widget.icon puuttuu; sitä ei valita jokaisessa promootiossa.
Pois jätetty project.description sekä avustajan kehote-, profiili- ja varavastausasetukset tyhjentävät tallennetut ohitukset. Pois jätetty runtime palauttaa automaattisen kielen, oletuskielen en ja sallitun kieliohituksen. Pois jätetty lähdetila on crawl, pois jätetyt suodattimet tyhjennetään ja automaattinen päivitys on oletuksena pois päältä. Tilakohtaisia asetuksia sovelletaan vain vastaavassa tilassa. Pois jätetty widget.icon palauttaa keskikokoisen oletuskuvakkeen; widget.showBranding säilyttää poikkeuksellisesti aiemman valinnan tai oletusarvon true.
Jos mode on sitemap eikä sitemapUrl-osoitetta ole annettu, käytetään ensin havaittua sivustokarttaa. Sen jälkeen kokeillaan osoitteita /sitemap.xml ja /sitemap_index.xml, ja jos niistä ei löydy URL-osoitteita, käytetään tallennettua verkkosivuston osoitetta.
Muuttumaton määritysversio säilyttää pyydetyn maxPages-arvon, mutta runtime-promootio rajoittaa operatiivisen skrapausasetuksen arvoon 100 000. Jos maxPages jätetään pois, pyynnön oletusarvona käytetään pakettiin sisältyvää tilin sivukiintiötä: Free 10, Starter 150, Pro 5 000 ja Business 25 000. Ajokohtainen valintaraja on pienempi seuraavista: pyydetty maxPages-arvo tai palveluntarjoajan kapasiteetin ja projektissa jo olevien sivujen määrän suurempi arvo. Näin jo tallennetut sivut voidaan päivittää, vaikka palveluntarjoajan kapasiteetti olisi pienempi. Uusien sivujen hyväksyntä tarkistetaan erikseen omistajan tilikohtaista sivukiintiötä vasten. Sivustokarttojen etsintä voi hakea karttatiedostoja ja luetella URL-osoitteita ennen valintaa, joten kapasiteettiraja ei ole yksityisyys- eikä ulospäin lähtevien pyyntöjen raja. Arvo ei takaa, että kaikki pyydetyt sivut indeksoidaan.
Oletusarvo ei lisää omistajan yhteistä kiintiötä tai paketin käyttöoikeuksia. Haravointi tarkistaa erikseen nykyisen sivu- ja PAYG-kiintiön sekä kuukausittaiset päivitysrajat. Päivittäinen automaattinen päivitys ja nimenomainen showBranding: false edellyttävät Starter-pakettia tai korkeampaa; Free sallii viikoittaisen tai kuukausittaisen päivityksen. Tarkistukset tehdään preview- ja production-promootiossa, myös rollbackissa, eivät paikallisessa validoinnissa tai development-tallennuksessa. Aiemmin kelvollinen versio voi epäonnistua paketin muututtua. Promootio käyttää palvelimelle välimuistiin tallennettuja projekti- tai työtilatietoja, ei reaaliaikaista laskutuspalvelun kyselyä; tarkista laskutuksen synkronointi ja todellinen haravointikiintiö erikseen.
Käytä --json-valitsinta automaatiossa saadaksesi API-tuloksen, kuten version._id-tunnuksen, ympäristöosoittimen, applied- ja indexingStatus-arvot sekä kaavintatyön tunnuksen. Tallenna deploy-/promote-/rollback-tulosteen version._id tai status-tulosteen activeVersion._id; näkyvä järjestysnumero ei kelpaa --version-arvoksi.
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ää deploy-/promote-/rollback-tulosteen version._id-tunnusta tai status-tulosteen activeVersion._id-tunnusta, 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.
Tunnus ei ole Git SHA tai määrityksen hash. Lainausmerkitä esimerkin paikkamerkit ja korvaa ne tokenin projektin todellisilla tunnuksilla. Rollback ei valitse aiempaa versiota automaattisesti. Toistuva deploy luo uuden version myös samalla määrityksellä, ja toistuvat promootiot voivat lisätä uusia töitä jonoon.
status näyttää valitun ympäristötunnuksen version ja osoittimen, ei käytössä olevaa runtime-määritystä, hallintapaneelin muutosten vertailua tai haravoinnin ja embeddingien edistymistä. Ilman käyttöönottoa se näyttää Environment version: none sekä palauttaa environment: null ja activeVersion: null. runtimeConfigVersionId osoittaa viimeksi jaettuun runtimeen sovellettuun määritykseen ja voi olla eri; development-promootio ei muuta sitä. Lukitsemattomassa projektissa myöhemmät hallintapaneelimuutokset voivat muuttaa runtime-kenttiä muuttamatta tunnusta. Onnistunut status-kutsu päivittää tokenin lastUsedAt-ajan ja kuluttaa hallintarajapinnan pyyntökiintiötä. Tarkista indeksointi erikseen hallintapaneelista.
Komennot, valitsimet ja virheet
init [path] luo tarvittavat ylähakemistot mutta ei ylikirjoita tiedostoa; validate [path] validoi JSONin ilman etäyhteyttä. Molempien oletuspolku on chattybox.config.json. deploy vaatii --environment-valitsimen ja hyväksyy valinnaisen --config <path>-arvon. promote ja rollback vaativat lisäksi --version <opaque-id>, eivätkä ne lue paikallista määritystä; status vaatii ympäristön eikä sekään lue määritystä. Ilman komentoa sekä komennoilla help, --help tai -h näytetään päätason ohje: käytä chattybox --help, älä chattybox deploy --help. Päätason --version ja -v näyttävät CLI-version, eivät promootion version tunnusta.
Kaikki neljä hallintakomentoa hyväksyvät --token, --api-url ja --json. Nimenomaiset valitsimet ohittavat ympäristömuuttujat CHATTYBOX_DEPLOY_TOKEN ja CHATTYBOX_API_URL. Suosi salaisia ympäristömuuttujia komentohistorian tai prosessin argumenttien sijaan. Arvot voi antaa muodossa --flag value tai --flag=value; --json on itsenäinen valitsin. Oletusympäristöä ei ole. Tuntemattomat, toistetut, tyhjät ja komentoon sopimattomat hallintavalitsimet hylätään; paikalliset komennot hyväksyvät vain yhden sijaintiin perustuvan polun, eivät valitsimia tai ylimääräisiä argumentteja.
CLI:ssä ei ole --dry-run, --wait, --force, --project, viesti- tai optimistisen samanaikaisuuden valitsimia. HTTP API tukee odotetun version kenttiä, mutta CLI ei lähetä niitä. Aja samaan projektiin kohdistuvat CI-käyttöönotot peräkkäin.
Onnistunut komento palauttaa poistumiskoodin 0. Tiedosto-, JSON-, validointi-, argumentti-, yhteys-, vastauksen luku- ja HTTP-virheet palauttavat koodin 1 ja ChattyBox: ... -viestin stderr-virtaan. --json muotoilee vain onnistuneet tulokset, ei virheitä. API-virhe sisältää HTTP-tilan ja mahdollisen virhekoodin; onnistunut vastaus, joka ei ole JSONia, hylätään. Automaattista uudelleenyritystä, tilan seurantaa tai määritettyä pyyntöaikakatkaisua ei ole. Tarkista tila yhteysvirheen jälkeen ennen uutta yritystä, sillä palvelin on saattanut jo tehdä käyttöönoton.
Hallintareitit ovat POST /v1/config/deployments (201), POST /v1/config/deployments/promote ja /rollback (200) sekä GET /v1/config/deployments/status?environment=... (200). HTTP-vastauksessa onnistuminen on muodossa { "data": ... }; CLI:n JSON purkaa kääreen. Virheet ovat yleensä muodossa { "error": { "code": ..., "message": ... } }: 401 INVALID_TOKEN, 404 NOT_FOUND puuttuvalle tai toisen projektin versiolle, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG tai 500 INTERNAL_ERROR. Virheellinen tyypitetty tunnus tuottaa 422:n, ei välttämättä 404:ää. Pyynnön sisältöraja on 262 144 tavua. Hallintareiteillä on yhteinen tokenkohtainen 20 pyynnön minuuttiraja; 429-vastaus käyttää yhteistä rajoitusmuotoa ja Retry-After-otsaketta. Kokonaan puuttuva POST-sisältö tuottaa nykyisin 500:n, toisin kuin virheellinen JSON (422).
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ä HTTP-actions-julkaisun URL-osoitetta tai widgetin API-URL-osoitetta kohdasta Asenna → Verkkosivuston asennus, jos se on saatavilla. 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.
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ä. Bun-kontin esimerkit käyttävät nimenomaisesti --bun-valitsinta eivätkä edellytä erillistä Node-asennusta; varmista CI:ssä käyttämäsi Bun- ja konttikuvaversio.
Bitbucket Pipelines
Lisää molemmat arvot käyttöönottomuuttujina kohtaan Repository settings → Pipelines → Deployments → Production. Merkitse käyttöönottotunnus suojatuksi.
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. CLI:llä ei ole erillistä BITBUCKET_*-metatietojen määritystä; se käyttää commitin ja haaran selvittämiseen paikallista Gitiä, jossa irrotetulla HEADilla ei välttämättä ole haaran nimeä.
Määrityksen osiot
| Osio | Tarkoitus |
|---|---|
schemaVersion | Valitsee julkisen määrityssopimuksen. Tällä hetkellä tuetaan versiota 1. |
assistant | Nimeää avustajan ja määrittää valmiin persoonan tai oman järjestelmäkehotteen sekä varavastaustekstin. |
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. |
Persoonat
Valitse promptProfile-arvoksi default, support, sales tai sarcastic, kun käytät ylläpidettyjä persoonaohjeita. Oma persoona määritetään arvolla custom ja systemPrompt-kentällä. Jos sekä valmis profiili että systemPrompt annetaan, nimenomainen kehote voittaa.
Tietopohjan lähteiden etsintä
Tämä esimerkki on yksi knowledge.sources-merkintä, ei täydellinen määritys. Se vaatii julkaistut CLI/config-paketit 0.3.1 ja vastaavan backend-sopimuksen 0.3.0. Päivittäinen päivitys vaatii Starter- tai korkeamman paketin; maxPages: 500 on käytettävissä olevan kapasiteetin rajoittama pyyntö, ei lupaus indeksoinnista.
{
"type": "website",
"url": "https://docs.example.com",
"mode": "sitemap",
"sitemapUrl": "https://docs.example.com/docs-sitemap.xml",
"include": ["/docs/"],
"exclude": ["/private/"],
"maxPages": 500,
"autoRescrape": true,
"rescrapeInterval": "daily"
}
Laajennetut lähdeasetukset vaativat julkaistut 0.3.1-määritystyypit ja vastaavan 0.3.0-backend-sopimuksen. Päivittäinen aikataulu vaatii vähintään Starter-paketin; maxPages: 500 tallentaa pyynnön, jota rajoittaa ajon todellinen kapasiteetti.
homepage: valitse vainurltähän päivitykseen; vanhoja sivuja ei poisteta.sitemap: käytäsitemapUrl-osoitetta; nimenomainen sivustokartta, joka ei palauta URL-osoitteita, aiheuttaa virheen. Ilman sitä kokeillaan havaittua karttaa, sitten/sitemap.xmlja/sitemap_index.xmlsekä lopuksi tallennettua sivuston osoitetta.manual: indeksoi ei-tyhjänmanualUrls-luettelon osoitteet.crawl: kokeile tavanomaisia sivustokarttoja ja seuraa sitten tarvittaessaurl-osoitteen linkkejä enintäänmaxDepth-syvyyteen (oletus3).
include ja exclude vertaavat URL-osoitteiden osajonoja kirjainkoko huomioiden, eivät glob- tai regex-syntaksia. Mikä tahansa include-osuma hyväksyy URL-osoitteen ja mikä tahansa exclude-osuma hylkää sen, vaikka include täsmäisi. Tyhjät luettelot eivät suodata; suodattimet koskevat myös etusivu- ja manuaalivalintaa.
maxPages on positiivinen kokonaisluku; muuttumaton versio säilyttää pyydetyn arvon, mutta runtime-määritystä ja valintaa rajoittavat edellä kuvatut kapasiteettitarkistukset. Sivustokarttojen etsintä voi luetella URL-osoitteita ennen valintaa. maxDepth on kokonaisluku väliltä 0–20 ja rajoittaa linkkivarmistushakua, ei sivustokarttojen luettelointia. Pois jätetty mode valitsee crawl-tilan ja säilyttää nimenomaisen maxDepth-arvon, myös nollan. autoRescrape: true edellyttää rescrapeInterval-arvoa "daily", "weekly" tai "monthly"; pelkkä aikaväli ei käynnistä ajastusta. Kuukausi tarkoittaa 30 päivää, ja ajastin voi suorittaa työn myöhemmin kuin määräaikana.
Kieli- ja widget-määritysten validointi
Tuetut kielikoodit ovat en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy ja id. localeMode on auto tai fixed; fixed vaatii defaultLocale-arvon. allowLocaleOverride on erikseen määritettävissä. Lyhenne runtime.locale valitsee kiinteän tilan ja estää ohitukset; paikallinen validointi hylkää sen yhdistämisen arvoihin localeMode, defaultLocale tai allowLocaleOverride: true.
Widgetin sijainnit ovat bottom-right, bottom-left, top-right ja top-left. Kaikki kolme teemaväriä käyttävät muotoa #RRGGBB, eivät lyhyttä heksamuotoa, värinimeä tai alfakanavaa. Kuvakkeen tyyppi on default, emoji (ei-tyhjä emoji-merkkijono) tai url (HTTP(S)-url), ja valinnainen koko on small, medium tai large. Validointi ei hae kuvakkeen URL-osoitetta, tarkista kuvan MIME-tyyppiä tai vaadi tasan yhtä emojia. Lähde- ja kuvakeosoitteista tarkistetaan syntaksi ja protokolla, ei saavutettavuutta tai indeksointilupaa. Valinnaisen kuvauksen, avustajan kehotteen ja varavastauksen sekä widgetin otsikon ja tervetulotekstin on annettaessa oltava ei-tyhjiä; jätä ne pois ohitusten tyhjentämiseksi.
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.
Sekä defineConfig(config) että validateConfig(config) validoivat synkronisesti, heittävät tavallisen Error-virheen ensimmäisestä virheestä ja palauttavat saman objektin kloonaamatta, jäädyttämättä, tyyppiä muuntamatta tai oletusarvoja lisäämättä. Paketti vie TypeScript-tyypit ja nämä funktiot, ei JSON Schema -dokumenttia tai $schema-URL-osoitetta. Julkaistun 0.3.1-paketin tyypit tukevat yllä kuvattuja laajennettuja kenttiä.
Käytä tällä hetkellä toimivaan tuotantointegraatioon hostattua widgetiä tai rakenna mukautettu käyttöliittymä JavaScript SDK:lla.