Configurazione

Ogni app Kazzle ha un kazzle.config.ts nella radice del progetto. Il file esporta una definizione di app: lo stesso contratto che Kazzle utilizza per le app pubblicate e i connettori integrati.

Avvio rapido

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 convalida la definizione e fornisce l’autocompletamento di TypeScript. I campi non supportati o scritti male non vengono ignorati, ma causano un errore di convalida.

Campi della definizione

Campo	Tipo	Obbligatorio	Descrizione
`schemaVersion`	`1`	sì	Versione del contratto di definizione.
`name`	`string`	sì	Nome visualizzato nel catalogo e nella pagina dei dettagli.
`subtitle`	`string`	sì	Descrizione del catalogo su una riga.
`description`	`{ type: 'markdown', path: string }`	sì	Markdown incluso nell’app, solitamente `README.md`.
`version`	`string`	no	Versione dell’editore mostrata con l’app installata.
`icon`	`string`	no	Percorso dell’icona relativo alla radice dell’app.
`accentColor`	colore esadecimale	no	Colore di accento del brand.
`maxInstallations`	`number \| null`	sì	Installazioni massime per Space; `null` consente qualsiasi numero.
`setup`	oggetto setup	sì	Come viene configurata un’installazione.
`launch`	oggetto launch	sì	Cosa si apre dopo l’installazione.
`components`	component[]	sì	Componenti UI e di processo.
`tools`	tool source[]	sì	Sorgenti che si compilano in strumenti IA richiamabili.
`skills`	skill[]	sì	Istruzioni caricate quando rilevanti.
`kazzleAuth`	`'optional' \| 'required'`	no	Se la superficie di avvio richiede l’identità Kazzle.
`webhookUrl`	URL	no	Riceve webhook del ciclo di vita dell’installazione.
`appLogin`	`boolean`	no	Abilita il login dell’app per l’utente finale.

Setup

Un’app sceglie esattamente un flusso di setup.

setup: { type: 'none' }

Usa none quando l’installazione non richiede autorizzazione esterna.

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: [],
}

Usa oauth per OAuth 1.0a o OAuth 2.0. Le credenziali del client OAuth vengono configurate privatamente quando l’app viene pubblicata; non compaiono mai nella definizione.

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 },
  ],
}

I campi del modulo supportano text, password, url, hostname, email e select. labelField può fare riferimento a un campo non segreto per distinguere più installazioni.

Launch

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

Una destinazione di componente deve nominare un componente nella stessa definizione. Le destinazioni URL scelgono esplicitamente embedded o external.

Componenti

Ogni componente ha un name univoco, un type di ui o process e un path di origine. Un’app può avere al massimo un componente UI.

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

env può selezionare una raccolta di segreti e un ambiente per un componente. I componenti di processo possono anche dichiarare esecuzione persistente o attivata e trigger di pianificazione o webhook denominati.

Strumenti e skill

Strumenti e skill sono indipendenti. Gli strumenti definiscono operazioni richiamabili; le skill spiegano quando e come utilizzarli.

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.' } },
]

Le azioni di connessione richiedono un’installazione quando vengono richiamate. Vengono emesse dal convertitore di app di sistema di Kazzle; le app pubblicate definiscono strumenti richiamabili nei file. Le skill rimangono separate e possono essere caricate solo quando rilevanti.

Per iniziare

Costruire

Utenti e dati

Pubblicare

Usare Kazzle

Sicurezza

Riferimento

Configurazione

Configurazione

Avvio rapido

Campi della definizione

Setup

Launch

Componenti

Strumenti e skill

​Configurazione

​Avvio rapido

​Campi della definizione

​Setup

​Launch

​Componenti

​Strumenti e skill

Configurazione

Avvio rapido

Campi della definizione

Setup

Launch

Componenti

Strumenti e skill