Konfiguration

Jede Kazzle-App hat eine kazzle.config.ts im Projektstamm. Die Datei exportiert eine App-Definition: denselben Vertrag, den Kazzle für veröffentlichte Apps und integrierte Konnektoren verwendet.

Schnelleinstieg

import { defineApp } from '@kazzle/app';

export default defineApp({
  schemaVersion: 1,
  name: 'My App',
  subtitle: 'A short catalog description',
  description: { type: 'markdown', path: 'README.md' },
  maxInstallations: 1,
  setup: { type: 'none' },
  launch: { type: 'component', component: 'web' },
  components: [{ name: 'web', type: 'ui', path: '.' }],
  tools: [],
  skills: [],
});

defineApp validiert die Definition und bietet TypeScript-Autovervollständigung. Nicht unterstützte oder falsch geschriebene Felder führen zu Validierungsfehlern, statt ignoriert zu werden.

Definitionsfelder

Feld	Typ	Erforderlich	Beschreibung
`schemaVersion`	`1`	ja	Version des Definitionsvertrags.
`name`	`string`	ja	Anzeigename im Katalog und auf der Detailseite.
`subtitle`	`string`	ja	Einzeilige Katalogbeschreibung.
`description`	`{ type: 'markdown', path: string }`	ja	Markdown gebündelt mit der App, normalerweise `README.md`.
`version`	`string`	nein	Verlegerversion, die mit der installierten App angezeigt wird.
`icon`	`string`	nein	Symbolpfad relativ zum App-Stamm.
`accentColor`	Hex-Farbe	nein	Markenakzentfarbe.
`maxInstallations`	`number \| null`	ja	Maximale Installationen pro Space; `null` erlaubt beliebig viele.
`setup`	Setup-Objekt	ja	Wie eine Installation konfiguriert wird.
`launch`	Launch-Objekt	ja	Was nach der Installation geöffnet wird.
`components`	component[]	ja	UI- und Prozesskomponenten.
`tools`	Tool-Quelle[]	ja	Quellen, die in aufrufbare KI-Tools kompiliert werden.
`skills`	skill[]	ja	Anweisungen, die bei Bedarf geladen werden.
`kazzleAuth`	`'optional' \| 'required'`	nein	Ob die Launch-Oberfläche Kazzle-Identität erfordert.
`webhookUrl`	URL	nein	Empfängt Webhooks zum Installationslebenszyklus.
`appLogin`	`boolean`	nein	Aktiviert die eigene Endbenutzer-Anmeldung der App.

Setup

Eine App wählt genau einen Setup-Flow.

setup: { type: 'none' }

Verwenden Sie none, wenn die Installation keine externe Autorisierung benötigt.

setup: {
  type: 'oauth',
  version: '2.0',
  metadata: {
    type: 'endpoints',
    authorizationUrl: 'https://provider.example.com/oauth/authorize',
    tokenUrl: 'https://provider.example.com/oauth/token',
  },
  scopes: ['account.read'],
  pkce: 'required',
  authorizationParams: {},
  fields: [],
}

Verwenden Sie oauth für OAuth 1.0a oder OAuth 2.0. OAuth-Client-Anmeldedaten werden privat konfiguriert, wenn die App veröffentlicht wird; sie erscheinen niemals in der Definition.

setup: {
  type: 'form',
  labelField: 'accountUrl',
  fields: [
    { key: 'accountUrl', label: 'Account URL', kind: 'url', required: true, secret: false },
    { key: 'apiKey', label: 'API key', kind: 'password', required: true, secret: true },
  ],
}

Formularfelder unterstützen text, password, url, hostname, email und select. labelField kann auf ein nicht-geheimes Feld verweisen, um mehrere Installationen zu unterscheiden.

Launch

launch: { type: 'none' }
launch: { type: 'component', component: 'web' }
launch: { type: 'url', url: 'https://example.com', target: 'external' }

Ein Komponentenziel muss eine Komponente in derselben Definition benennen. URL-Ziele wählen embedded oder external explizit.

Komponenten

Jede Komponente hat einen eindeutigen name, einen type von ui oder process und einen Quell-path. Eine App kann höchstens eine UI-Komponente haben.

components: [{
  name: 'server',
  type: 'process',
  path: './server',
  runtime: {
    dev: { command: 'bun run dev' },
    prod: { command: 'bun run start', build: 'bun run build' },
  },
}]

env kann eine Geheimnissammlung und Umgebung für eine Komponente auswählen. Prozesskomponenten können auch persistente oder ausgelöste Ausführung und benannte Schedule- oder Webhook-Trigger deklarieren.

Tools und Skills

Tools und Skills sind unabhängig. Tools definieren aufrufbare Operationen; Skills erklären, wann und wie sie verwendet werden.

tools: [
  { name: 'app-tools', type: 'file', path: './tools.ts' },
  {
    name: 'stripe',
    type: 'connection_actions',
    actions: ['customers.list', 'invoices.list'],
  },
],
skills: [
  { name: 'billing', source: { type: 'file', path: './skills/billing/SKILL.md' } },
  { name: 'review', source: { type: 'inline', instructions: 'Confirm before write actions.' } },
]

Verbindungsaktionen erfordern eine Installation beim Aufrufen. Sie werden vom System-App-Konverter von Kazzle ausgegeben; veröffentlichte Apps definieren aufrufbare Tools in Dateien. Skills bleiben separat und können nur bei Bedarf geladen werden.

Erste Schritte

Erstellen

Nutzer und Daten

Veröffentlichen

Kazzle verwenden

Sicherheit

Referenz

Konfiguration

Konfiguration

Schnelleinstieg

Definitionsfelder

Setup

Launch

Komponenten

Tools und Skills

​Konfiguration

​Schnelleinstieg

​Definitionsfelder

​Setup

​Launch

​Komponenten

​Tools und Skills

Konfiguration

Schnelleinstieg

Definitionsfelder

Setup

Launch

Komponenten

Tools und Skills