Zum Hauptinhalt springen

CLI und Konfigurationsbereitstellung

Die veröffentlichten CLI/Config-Artefakte der Version 0.3.1 implementieren den Konfigurations-/Backend-Vertrag 0.3.0 und lehnen unbekannte Schlüssel lokal und im Backend gleichermaßen ab.

Die CLI erstellt, validiert und stellt unveränderliche ChattyBox-Konfigurationsversionen bereit, befördert sie und führt Rollbacks durch. Jedes Deployment-Token ist auf genau ein bestehendes Projekt und ausgewählte Umgebungen beschränkt. Betrachten Sie eine Konfigurationsdatei und ein projektbezogenes Token als ein verwaltetes ChattyBox-Projekt.

Veröffentlichungs- und Laufzeitstatus​

Im öffentlichen Registry sind @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 und das separate JavaScript-SDK @openstaticfish/chattybox@0.1.4 veröffentlicht. Die CLI/config-Artefakte unterstützen die erweiterten Felder (Projekt, Ermittlung/Planung, erweiterte Locale-Steuerung, widget.icon, widget.showBranding) zusammen mit dem Backend-Vertrag 0.3.0. status zeigt die Umgebungsversion, während runtimeConfigVersionId die zuletzt auf die gemeinsame Runtime angewandte Konfiguration benennt und abweichen kann. Ohne mode wird crawl gewählt und ein explizites maxDepth: 0 erhalten. Die ESM-CLI verlangt Node 20+; wählen Sie Bun bei Bedarf ausdrücklich mit bunx --bun.

Paketversionen und schemaVersion: "1" sind getrennte Versionssysteme. bunx beachtet standardmäßig den Node-Shebang: Installieren Sie Node oder wählen Sie Bun ausdrücklich. Die Tests für veröffentlichte Pakete decken Node 20, 22 und 24 unter Linux ab, keine allgemeine Betriebssystem- oder Browser-Kompatibilität. Fixieren Sie in Produktionsautomatisierung eine getestete Paketversion; Beispiele ohne Versionsangabe verwenden das installierte, zwischengespeicherte oder Registry-Paket, nicht den Quellcode dieses Repositorys.

Umfang der Konfiguration als Code​

Die Konfiguration steuert Projektname und -beschreibung, Persona und Fallback des Assistenten, Website-Ermittlung und Aktualisierung, Spracheinstellungen und Darstellung des gehosteten Widgets. Eine Bereitstellung nach preview oder production übernimmt diese Werte und stellt eine Aktualisierung des bestehenden Korpus in die Warteschlange. Mit Config-as-code lock werden konfigurierte Einstellungen über versionierte Deployments statt Dashboard-Formulare geändert; die tarifabhängige Branding-Einstellung ist eine Ausnahme.

Das Projekt muss zunächst einmalig im Dashboard erstellt werden. Öffentliche Widget-Schlüssel samt optionalen Origin-Beschränkungen, Verwaltung der Deployment-Tokens, Analysen, Konversationen, Inhaltslücken, Löschaktionen und hochgeladene Icon-Dateien sind keine Konfigurationsfelder. Verwenden Sie für ein deklaratives Icon eine URL oder ein Emoji. Die Konfiguration enthält bewusst keine Projekt-ID: Das geheime Deployment-Token bestimmt das Zielprojekt.

Ein öffentlicher Widget-API-Schlüssel ist für Chat und Widget-Konfiguration im Browser verwendbar. Ohne Beschränkung gilt er für verschiedene Browser-Origins; ein für eine Website vorbereiteter Schlüssel kann bereits beschränkt sein. Origin-Beschränkungen sind optional und ersetzen keine Besucherauthentifizierung. Ein Deployment-Token für Deploy, Promote, Rollback und Status ist dagegen geheim und gehört nur in lokale oder CI-Secrets.

Konfiguration erstellen​

bunx @openstaticfish/chattybox-cli init

Dadurch wird chattybox.config.json erstellt:

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

Verwenden Sie einen benutzerdefinierten Pfad, wenn die Konfiguration in ein Unterverzeichnis gehört:

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

Lokal oder in CI validieren​

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

Die Validierung im aktuellen Quellcode prüft Objektstrukturen, den erforderlichen Assistentennamen, Auswahlwerte, HTTP(S)-URLs, Ganzzahl-Limits, Locale-Kombinationen und sechsstellige Hex-Farben. knowledge darf lokal fehlen, muss aber, wenn angegeben, genau eine Website-Quelle enthalten; preview und production erfordern diese Quelle. Ist widget angegeben, ist widget.enabled erforderlich.

Die Validierung liest nur JSON, kein TypeScript, JSONC, YAML oder entferntes Schema. Sie stellt keine Netzwerkanfrage, prüft weder Token noch Tarifberechtigungen und setzt keine Standardwerte. Lokal und im Backend werden unbekannte Felder auf jeder Objektebene abgelehnt; Ein-/Ausschlusswerte müssen nichtleere Zeichenfolgen sein. runtime.locale steht für eine feste Locale ohne Überschreibungen und darf nicht mit localeMode, defaultLocale oder allowLocaleOverride: true kombiniert werden. Ein lokaler Erfolg garantiert keine Bereitstellung: Der Server prüft Tokenberechtigungen und Tarif.

Deployment-Token erstellen​

Öffnen Sie im Projekt Chatbot-Einstellungen → Entwicklerkonfiguration → Tokens für die Konfigurationsbereitstellung und erstellen Sie ein Token für die Umgebungen, die Ihr Workflow ändern darf. Kopieren Sie den vollständigen Tokenwert sofort; er wird nur einmal angezeigt. ChattyBox speichert einen Hash und begrenzte Identifizierungs- und Lebenszyklusmetadaten, kann den vollständigen Wert aber nicht erneut anzeigen.

Das Formular wählt zunächst nur development aus und legt keinen Ablauf fest. Wählen Sie preview oder production bei Bedarf ausdrücklich aus.

Das Dashboard bietet keinen Ablauf oder 7, 30, 90 bzw. 365 Tage; die authentifizierte Erstellungs-API akzeptiert eine Ganzzahl von 1 bis 365 Tagen oder keinen Ablauf. Pro Projekt sind höchstens 20 aktive, nicht abgelaufene Tokens möglich. Erstellen Sie zur Rotation einen Ersatz, aktualisieren Sie CI und widerrufen Sie das alte Token. Die CLI bietet keine Befehle für Login oder das Erstellen, Auflisten und Widerrufen von Tokens.

Setzen Sie das Token und die Widget-API-URL. Verwenden Sie unter Installieren → Installation auf der Website den Wert von data-api-url aus dem Einbettungssnippet, sofern verfügbar; andernfalls verwenden Sie die URL der HTTP-Actions-Bereitstellung aus Ihrer Deployment-Konfiguration. Möglicherweise muss der Installationsablauf zuerst abgeschlossen sein:

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

Verwenden Sie die Basis-URL der HTTP-Actions-Bereitstellung oder die Widget-URL mit dem abschließenden /chat, nicht eine .convex.cloud-Client-URL oder den vollständigen Management-Endpunkt. Außer bei localhost, 127.0.0.1 und [::1] ist HTTPS erforderlich. Die URL darf keine Zugangsdaten, Query-Parameter oder Fragmente enthalten. Prüfen Sie den Zielhost, bevor Sie das Secret übermitteln.

Committen Sie das Token niemals und geben Sie es niemals in browserseitigem Code preis. Bewahren Sie dieses nur serverseitig zu verwendende Geheimnis lokal oder im verschlüsselten Secret-Speicher Ihres CI-Anbieters auf.

Das Deployment-Token authentifiziert sich mit Authorization: Bearer ...; öffentliche Widget-Schlüssel können es nicht ersetzen. Die Management-Routen wenden keine Widget-Origin-Einschränkungen an, erfordern keinen Origin-Header und bieten keinen Browser-CORS-Zugriff. Das Geheimnis ist nicht an eine Origin gebunden: Jeder, der es besitzt, kann die API von einem Server aus aufrufen. Fehlende, ungültige, abgelaufene, widerrufene oder für die falsche Umgebung ausgestellte Tokens liefern HTTP 401 INVALID_TOKEN. Tokens funktionieren auch nicht mehr, wenn ihr Projekt oder Eigentümer fehlt oder gelöscht wird.

Nach Überprüfung des Workflows können Sie Config-as-code lock aktivieren. Die Sperre ist im aktuellen Dashboard, CLI und API irreversibel; es gibt keine unterstützte Entsperrung. Ihre Aktivierung erstellt weder Token noch Konfigurationsversion. Halten Sie vor dem Sperren einen getesteten Token-Workflow bereit. Sie blockiert Dashboard-Konfiguration, Icon-Uploads und manuelle Korpusaktionen (Scraping, Löschen, Rebuild), nicht aber geplante Arbeit, Projektlöschung, öffentliche Schlüssel oder Tokens. Branding ist die Ausnahme: Die Branding-Einstellung bleibt tarifabhängig im Dashboard änderbar. Das Ausblenden der Zuordnung erfordert auch beim Deployment Starter oder höher; Free erzwingt sie weiterhin zur Laufzeit.

Konfiguration bereitstellen​

Das Deployment erstellt eine unveränderliche Version und befördert sie in die ausgewählte Umgebung:

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

development speichert nur Version und Zeiger, ohne Runtime-Anwendung. preview und production teilen dieselbe Runtime, dasselbe Korpus und dieselben öffentlichen Schlüssel: Die letzte Runtime-Promotion gewinnt, ohne Umgebungsisolation. Ein auf preview beschränktes Token kann daher auch die Runtime eines Projekts ändern, das Production-Traffic bedient. Nutzen Sie für echte Trennung separate Projekte mit jeweils eigenen Tokens und öffentlichen Schlüsseln. Runtime-Promotion wendet Konfiguration an und stellt einen Scrape in die Warteschlange, wartet aber nicht auf Scraping oder Embeddings; ausgelassene alte URLs werden nicht entfernt und das Korpus ist kein versionierter Snapshot.

Bei development melden die Ergebnisse applied: false und indexingStatus: "not_required"; preview und production wenden die Konfiguration atomar an und melden für den eingereihten Scrape applied: true und indexingStatus: "pending". Bei fehlgeschlagener Aktualisierung können teilweise Änderungen am Korpus bestehen bleiben; die angewandte Konfiguration wird nicht zurückgesetzt. Jobs speichern eine Konfigurationsversions-ID, lesen aber auch veränderliche Scrape-Einstellungen. Vermeiden Sie überlappende Deployments, wenn konsistente Indexierung wichtig ist.

Verwenden Sie --json in der Automatisierung, um das API-Ergebnis einschließlich version._id, Umgebung, Zeiger, applied, indexingStatus und Scraping-Job-ID (falls ein Job eingereiht wurde) strukturiert zu erhalten. Im JSON-Ergebnis von status lautet das entsprechende ID-Feld activeVersion._id.

Konfigurationsersatz und Seitenlimits​

Deployen Sie die vollständige gewünschte Konfiguration, keinen Patch. Eine Promotion nach preview oder production löscht oder setzt ausgelassene, von der Konfiguration verwaltete Werte zurück, einschließlich vorheriger Dashboard-Einstellungen:

Ausgelassener WertAuswirkung zur Laufzeit
project.description, Assistant-Prompt/-Profil/-FallbackGespeicherte Anpassungen werden gelöscht; das Runtime-Fallback-Verhalten greift.
runtimeSetzt auf automatische Locale, Standard en und erlaubte Locale-Überschreibungen zurück.
widget oder optionale Widget-Texte, Theme oder PositionWenn widget fehlt, wird das Widget aktiviert. Ist das widget-Objekt vorhanden, wird der erforderliche Wert von enabled übernommen. Ausgelassene Darstellungsanpassungen werden gelöscht, sodass Runtime-Standardwerte gelten.
widget.iconSetzt auf Standardsymbol in mittlerer Größe zurück. Die Promotion löscht die Datei eines zuvor hochgeladenen Icons, auch wenn ein deklarativer Ersatz angegeben ist.
Quellenmodus, Filter oder ZeitplanDer Modus wird crawl, ausgelassene Filter werden gelöscht und die automatische Aktualisierung deaktiviert. Modusspezifische Einstellungen gelten nur für den jeweils ausgewählten Modus.
widget.showBrandingAusnahme: Bei Auslassung bleibt die gespeicherte Einstellung erhalten, andernfalls gilt true; ein expliziter Wert überschreibt sie bei der nächsten Runtime-Promotion. false erfordert Starter oder höher.

Die unveränderliche Konfigurationsversion behält den angeforderten Wert von maxPages; die zur Laufzeit angewandte Scrape-Konfiguration ist auf 100.000 begrenzt. Für die Auswahl berücksichtigt der Worker den angeforderten Wert und den höheren Wert aus Anbieter-Kapazität und bereits indexierten Projektseiten; die Aufnahme neuer Seiten wird zusätzlich anhand des kontoweiten Seitenkontingents des Projektinhabers geprüft. Bei der Sitemap-Ermittlung können Sitemap-Dokumente abgerufen und URLs aufgelistet werden, bevor die Auswahl begrenzt wird. Die Kapazität ist daher weder eine Datenschutzgarantie noch eine Grenze für ausgehende Anfragen. Sie garantiert nicht, dass alle angeforderten Seiten indexiert werden. Ohne maxPages entspricht der Standard-Anforderungswert dem im Tarif enthaltenen Seitenkontingent pro Konto: Free 10, Starter 150, Pro 5.000 und Business 25.000. Dadurch entstehen weder ein separates Projektkontingent noch zusätzliche Tarifansprüche; jeder Scrape prüft das aktuelle Seiten-/PAYG-Kontingent und die monatlichen Aktualisierungslimits erneut.

Im Modus sitemap schlägt ein explizites sitemapUrl, das keine URLs liefert, fehl. Ist sitemapUrl nicht angegeben, wird zuerst eine erkannte Sitemap verwendet, danach /sitemap.xml, dann /sitemap_index.xml und schließlich die gespeicherte Website-URL, falls keine davon URLs liefert.

Automatische tägliche Aktualisierung und ausdrücklich gesetztes showBranding: false erfordern Starter oder höher. Free erlaubt wöchentliche oder monatliche automatische Aktualisierung. Diese Berechtigungen werden bei der Promotion nach preview oder production geprüft, auch beim Rollback, nicht bei lokaler Validierung oder development. Nach einem Tarifwechsel kann eine zuvor gültige Version scheitern. Die Promotion verwendet serverseitig zwischengespeicherte Projekt-/Arbeitsbereichsdaten statt einer Live-Abfrage beim Zahlungsanbieter; prüfen Sie bei jüngsten Tarif- oder PAYG-Änderungen Synchronisierung und tatsächliches Scrape-Kontingent getrennt.

Status, Promotion und 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

--version erwartet die undurchsichtige Konfigurationsversions-ID, nicht die sichtbare Nummer: Sie finden sie als version._id im JSON-Ergebnis von deploy, promote oder rollback und als activeVersion._id im JSON-Ergebnis von status. Rollback verwendet dieselbe Backend-Operation wie Promote, muss keine ältere Version wählen und wählt nicht automatisch die vorherige Version aus. Es überschreibt den Zeiger sowie die Promotion-Metadaten der ausgewählten Umgebung; es gibt keine append-only Promotion-Historie. Ein Rollback für preview oder production wendet die Konfiguration mit den aktuellen Entitlements erneut an und reiht eine neue Aktualisierung ein, statt historische Inhalte wiederherzustellen.

Wiederholte Deployments erstellen auch bei identischer Konfiguration neue Versionen; wiederholte Promotions können neue Jobs einreihen. status zeigt die Umgebungsversion und den Zeiger des gewählten Labels, nicht die effektive Runtime-Konfiguration, Dashboard-Abweichungen oder den Scrape-/Embedding-Fortschritt. Ein nicht bereitgestelltes Label liefert environment: null und activeVersion: null. runtimeConfigVersionId kann nach einer Promotion eines anderen Labels abweichen; development ändert diesen Runtime-Zeiger nicht. Ohne Sperre können spätere Dashboard-Änderungen Runtime-Felder ändern, ohne diese ID zu ändern. Erfolgreiche Statusabfragen aktualisieren lastUsedAt des Tokens und verbrauchen Management-Ratenlimit. Prüfen Sie die Indexierung separat im Dashboard.

Befehle, Optionen und Fehler​

BefehlArgumente und Wirkung
init [path]Standard ist chattybox.config.json; erstellt übergeordnete Verzeichnisse und überschreibt keine vorhandene Datei.
validate [path]Derselbe Standardpfad; liest und validiert JSON ohne Fernzugriff.
deployBenötigt --environment, optional --config <path>; validiert, erstellt und befördert eine Version.
promote, rollbackBenötigen --environment und --version <opaque-id>; lesen keine lokale Konfiguration.
statusBenötigt --environment; liest keine lokale Konfiguration.
Kein Befehl, help, --help, -hAllgemeine Hilfe; verwenden Sie chattybox --help, nicht chattybox deploy --help.
--version, -vCLI-Version auf oberster Ebene, nicht die Versionsoption einer Promotion.

Alle vier Management-Befehle akzeptieren --token, --api-url und --json. Explizite Optionen haben Vorrang vor CHATTYBOX_DEPLOY_TOKEN und CHATTYBOX_API_URL; bevorzugen Sie geheime Umgebungsvariablen gegenüber Tokens in Shell-Historie oder Prozessargumenten. Wertoptionen akzeptieren --flag value oder --flag=value, --json ist ein Schalter. Es gibt keine Standardumgebung. Unbekannte, doppelte, leere oder für den Befehl unzulässige Management-Optionen werden abgelehnt; lokale Befehle akzeptieren nur einen Positionspfad und keine zusätzlichen Argumente oder Flags.

Es gibt keine Optionen --dry-run, --wait, --force, --project, für eine Nachricht oder für optimistische Nebenläufigkeit. Die HTTP-API unterstützt erwartete Versionsfelder, die CLI sendet sie aber nicht. Serialisieren Sie CI-Deployments für dasselbe Projekt.

Erfolgreiche Befehle enden mit 0; Datei-, JSON-, Validierungs-, Argument-, Transport-, Antwortlese- und HTTP-Fehler mit 1 und einer ChattyBox: ...-Meldung auf stderr. --json formatiert nur erfolgreiche Ergebnisse. Die CLI wiederholt Anfragen nicht automatisch und bietet weder Polling noch einen konfigurierten Anfrage-Timeout. Prüfen Sie nach einem Transportfehler vor einem erneuten Versuch den Status: Der Server könnte das Deployment bereits übernommen haben.

Die Management-Routen sind POST /v1/config/deployments, POST /v1/config/deployments/promote, POST /v1/config/deployments/rollback und GET /v1/config/deployments/status?environment=.... Typische Fehler sind 401 INVALID_TOKEN, 404 NOT_FOUND, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG und 500 INTERNAL_ERROR; fehlerhafte typisierte IDs liefern 422, nicht unbedingt 404. Der Request-Body ist auf 262.144 Bytes begrenzt; alle Management-Routen teilen ein Limit von 20 Anfragen pro Minute und Token. Bei 429 wird Retry-After ausgegeben. Ein vollständig fehlender POST-Body führt derzeit zu 500, fehlerhaftes JSON dagegen zu 422.

CI/CD-Workflows​

Fügen Sie CHATTYBOX_DEPLOY_TOKEN als verschlüsseltes, auf die Produktion beschränktes Secret bei Ihrem CI-Anbieter hinzu. Fügen Sie CHATTYBOX_API_URL als Secret oder Variable hinzu und verwenden Sie die Widget-API-URL unter Installieren → Installation auf der Website, sofern verfügbar, oder die URL der HTTP-Actions-Bereitstellung. Führen Sie die Validierung für Pull Requests aus, beschränken Sie Produktionsdeployments jedoch auf Ihren geschützten Standardbranch oder eine genehmigte Deployment-Umgebung.

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

Verwenden Sie ein auf die Produktionsumgebung begrenztes Secret und verlangen Sie eine Deployment-Genehmigung, wenn Ihr Repository dies unterstützt. Die CLI zeichnet gängige CI-Commit- und Branch-Variablen zusammen mit der unveränderlichen Version auf.

GitLab CI/CD​

Speichern Sie beide Werte unter Settings → CI/CD → Variables. Schützen und maskieren Sie das Deployment-Token und beschränken Sie es auf die Umgebung 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

GitLab stellt CHATTYBOX_DEPLOY_TOKEN und CHATTYBOX_API_URL dem Job automatisch unter ihren Variablennamen zur Verfügung. Verwenden Sie einen geschützten Standardbranch, damit geschützte Variablen nicht für nicht vertrauenswürdige Branches verfügbar sind. Das Bun-Containerbeispiel verwendet ausdrücklich --bun, um nicht von einer separaten Node-Installation abzuhängen; prüfen Sie die in CI fixierte Bun-/Image-Version.

Bitbucket Pipelines​

Fügen Sie beide Werte als Deployment-Variablen unter Repository settings → Pipelines → Deployments → Production hinzu. Markieren Sie das Deployment-Token als geschützt.

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

Ersetzen Sie main, wenn Ihr Standardbranch anders heißt. Bitbucket fügt Deployment-Variablen nur Schritten hinzu, die dieser Deployment-Umgebung zugeordnet sind. Die CLI hat keine eigene Zuordnung für BITBUCKET_*-Metadaten und greift für Commit und Branch auf lokales Git zurück; bei einem Detached Checkout kann der Branchname fehlen.

Konfigurationsabschnitte​

AbschnittZweck
schemaVersionWählt den öffentlichen Konfigurationsvertrag aus. Derzeit wird Version 1 unterstützt.
projectOptionale Projektmetadaten wie die Dashboard-Beschreibung.
assistantBenennt den Assistenten und definiert eine integrierte Persona oder einen eigenen System-Prompt sowie den Fallback-Text.
knowledge.sourcesWählt Homepage-, Sitemap-, manuelle URL- oder Crawl-Ermittlung samt Limits, Filtern und Aktualisierungsplan.
runtimeSteuert automatische oder feste Locale, Standard-Locale und Überschreibungen auf Seitenebene.
widgetSteuert Aktivierung, Position, Texte, Farben und Standard-, Emoji- oder URL-Icon.

Personas​

Setzen Sie promptProfile auf default, support, sales oder sarcastic, um eine gepflegte Persona zu verwenden. Für eine eigene Persona setzen Sie custom und geben systemPrompt an. Wenn ein integriertes Profil und systemPrompt angegeben sind, hat der explizite Prompt Vorrang.

Quellenermittlung​

Dieses Beispiel ist ein Eintrag in knowledge.sources, keine vollständige Konfiguration. Es erfordert die veröffentlichten CLI-/Config-Pakete 0.3.1 und den passenden Backend-Vertrag 0.3.0. Die tägliche Aktualisierung erfordert Starter oder höher; maxPages: 500 ist eine kapazitätsabhängige Anforderung, keine Garantie für die Indexierung.

{
"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"
}

Die erweiterten Einstellungen erfordern die veröffentlichten Config-Typen 0.3.1 und den passenden Backend-Vertrag 0.3.0. Tägliche Planung erfordert Starter oder höher; ein angefordertes maxPages: 500 bleibt der tatsächlichen Kapazitätsprüfung des Laufs unterworfen.

  • homepage: nur url für diese Aktualisierung auswählen; vorhandene Seiten werden nicht gelöscht.
  • sitemap: sitemapUrl verwenden; die oben beschriebenen Regeln für leere oder fehlende Sitemaps gelten.
  • manual: die nichtleere Liste manualUrls indexieren.
  • crawl: zuerst die üblichen Sitemaps versuchen, sonst Links ab url bis maxDepth folgen (Standard 3).

include und exclude vergleichen URL-Teilstrings unter Beachtung der Groß- und Kleinschreibung, keine Globs oder regulären Ausdrücke. Ein Treffer in include lässt die URL zu; jeder Treffer in exclude schließt sie aus. Leere Listen filtern nicht. Die Filter gelten auch für Homepage und manuelle Auswahl.

maxPages muss eine positive Ganzzahl sein und bleibt in der unveränderlichen Version erhalten; die Laufzeitkonfiguration und Auswahl unterliegen den oben beschriebenen Grenzen. maxDepth muss eine Ganzzahl von 0 bis 20 sein und steuert den Link-Crawl-Fallback, nicht die Sitemap-Ermittlung. Bei ausgelassenem mode gilt crawl und ein explizites maxDepth bleibt einschließlich null erhalten. autoRescrape: true erfordert rescrapeInterval: "daily", "weekly" oder "monthly"; ein Intervall allein aktiviert keinen Zeitplan. Monatlich bedeutet 30 Tage; der Scheduler kann nach dem Fälligkeitszeitpunkt laufen.

Locale- und Widget-Validierung​

Unterstützte Locale-Codes sind en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy und id. localeMode ist auto oder fixed; fixed erfordert defaultLocale. allowLocaleOverride ist unabhängig konfigurierbar. Die Kurzform runtime.locale wählt den festen Modus ohne Überschreibungen; die lokale Validierung lehnt Kombinationen mit localeMode, defaultLocale oder allowLocaleOverride: true ab.

Widget-Positionen sind bottom-right, bottom-left, top-right und top-left. Alle drei Theme-Farben verwenden #RRGGBB, keine kurzen Hex-Werte, Farbnamen oder Alpha-Werte. Icons verwenden default, emoji mit nichtleerem emoji-String oder url mit HTTP(S)-url, optional in small, medium oder large. Die Validierung ruft Icon-URLs nicht ab, prüft keine Bild-MIME-Typen und verlangt nicht genau ein Emoji. Quellen- und Icon-URLs werden auf Syntax und Protokoll geprüft, nicht auf Erreichbarkeit oder Crawling-Erlaubnis. Optionale Beschreibung, Assistant-Prompt/Fallback, Widget-Titel und Begrüßungstext müssen, wenn angegeben, nicht leer sein; lassen Sie sie weg, um Anpassungen zu entfernen.

Typisierter Konfigurationshelfer​

Installieren Sie das Konfigurationspaket, wenn Sie separate TypeScript-Werkzeuge rund um das Schema entwickeln:

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

Die CLI selbst liest JSON-Dateien. defineConfig() ist für typisierte Anwendungen oder Build-Werkzeuge vorgesehen; TypeScript-Dateien werden dadurch nicht direkt von der CLI geladen. defineConfig(config) und validateConfig(config) validieren synchron, werfen beim ersten Fehler einen gewöhnlichen Error und geben dasselbe Objekt zurück, ohne es zu klonen, einzufrieren, zu konvertieren oder Standardwerte einzufügen. Das Paket exportiert TypeScript-Typen und diese Funktionen, kein JSON-Schema-Dokument und keine $schema-URL. Die veröffentlichten Typen 0.3.1 unterstützen die erweiterten Felder oben.

Für eine heute einsatzbereite Produktionsintegration verwenden Sie das gehostete Widget oder erstellen Sie mit dem JavaScript-SDK eine eigene Benutzeroberfläche.