Configuración

Cada app de Kazzle tiene un kazzle.config.ts en la raíz del proyecto. El archivo exporta una definición de app: el mismo contrato que Kazzle usa para apps publicadas y conectores integrados.

Inicio rápido

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 valida la definición y proporciona autocompletado de TypeScript. Los campos no soportados o mal escritos fallan en la validación en lugar de ser ignorados.

Campos de definición

Campo	Tipo	Requerido	Descripción
`schemaVersion`	`1`	sí	Versión del contrato de definición.
`name`	`string`	sí	Nombre mostrado en el catálogo y página de detalle.
`subtitle`	`string`	sí	Descripción de catálogo de una línea.
`description`	`{ type: 'markdown', path: string }`	sí	Markdown incluido con la app, generalmente `README.md`.
`version`	`string`	no	Versión del publicador mostrada con la app instalada.
`icon`	`string`	no	Ruta del icono relativa a la raíz de la app.
`accentColor`	color hex	no	Color de acento de marca.
`maxInstallations`	`number \| null`	sí	Instalaciones máximas por espacio; `null` permite cualquier número.
`setup`	objeto setup	sí	Cómo se configura una instalación.
`launch`	objeto launch	sí	Qué se abre después de la instalación.
`components`	component[]	sí	Componentes de UI y proceso.
`tools`	tool source[]	sí	Fuentes que se compilan en herramientas IA llamables.
`skills`	skill[]	sí	Instrucciones cargadas cuando son relevantes.
`kazzleAuth`	`'optional' \| 'required'`	no	Si la superficie de lanzamiento requiere identidad de Kazzle.
`webhookUrl`	URL	no	Recibe webhooks del ciclo de vida de instalación.
`appLogin`	`boolean`	no	Habilita el inicio de sesión de usuario final de la app.

Setup

Una app elige exactamente un flujo de configuración.

setup: { type: 'none' }

Usa none cuando la instalación no necesita autorización externa.

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 para OAuth 1.0a u OAuth 2.0. Las credenciales del cliente OAuth se configuran de forma privada cuando se publica la app; nunca aparecen en la definición.

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

Los campos de formulario soportan text, password, url, hostname, email y select. labelField puede referenciar un campo no secreto para distinguir múltiples instalaciones.

Launch

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

Un objetivo de componente debe nombrar un componente en la misma definición. Los objetivos de URL eligen embedded o external explícitamente.

Componentes

Cada componente tiene un name único, un type de ui o process, y una path de origen. Una app puede tener como máximo un componente de UI.

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

env puede seleccionar una colección de secretos y entorno para un componente. Los componentes de proceso también pueden declarar ejecución persistente o disparada e triggers de horario o webhook nombrados.

Herramientas y habilidades

Las herramientas y habilidades son independientes. Las herramientas definen operaciones llamables; las habilidades explican cuándo y cómo usarlas.

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

Las acciones de conexión requieren una instalación cuando se llaman. Son emitidas por el convertidor de app del sistema de Kazzle; las apps publicadas definen herramientas llamables en archivos. Las habilidades permanecen separadas y solo se pueden cargar cuando son relevantes.

Empezar

Construir

Usuarios y datos

Publicar

Usar Kazzle

Seguridad

Referencia

Configuración

Configuración

Inicio rápido

Campos de definición

Setup

Launch

Componentes

Herramientas y habilidades

​Configuración

​Inicio rápido

​Campos de definición

​Setup

​Launch

​Componentes

​Herramientas y habilidades

Configuración

Inicio rápido

Campos de definición

Setup

Launch

Componentes

Herramientas y habilidades