配置

每个 Kazzle 应用的项目根目录都有一个 kazzle.config.ts 文件。该文件导出一个应用定义：这是 Kazzle 用于已发布应用和内置连接器的同一个契约。

快速开始

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 验证定义并提供 TypeScript 自动补全。不支持或拼写错误的字段会导致验证失败，而不是被忽略。

定义字段

字段	类型	必需	描述
`schemaVersion`	`1`	是	定义契约的版本。
`name`	`string`	是	目录和详情页中的显示名称。
`subtitle`	`string`	是	单行目录描述。
`description`	`{ type: 'markdown', path: string }`	是	与应用一起打包的 Markdown，通常为 `README.md`。
`version`	`string`	否	与已安装应用一起显示的发布者版本。
`icon`	`string`	否	相对于应用根目录的图标路径。
`accentColor`	十六进制颜色	否	品牌强调色。
`maxInstallations`	`number \| null`	是	每个 Space 的最大安装数；`null` 允许任意数量。
`setup`	setup 对象	是	如何配置安装。
`launch`	launch 对象	是	安装后打开的内容。
`components`	component[]	是	UI 和流程组件。
`tools`	tool source[]	是	编译成可调用 AI 工具的源。
`skills`	skill[]	是	在相关时加载的说明。
`kazzleAuth`	`'optional' \| 'required'`	否	启动界面是否需要 Kazzle 身份。
`webhookUrl`	URL	否	接收安装生命周期 webhook。
`appLogin`	`boolean`	否	启用应用自身的最终用户登录。

设置

应用恰好选择一个设置流程。

setup: { type: 'none' }

当安装不需要外部授权时，使用 none。

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

对于 OAuth 1.0a 或 OAuth 2.0，使用 oauth。OAuth 客户端凭证在应用发布时私密配置；它们永远不会出现在定义中。

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

表单字段支持 text、password、url、hostname、email 和 select。labelField 可以引用非机密字段来区分多个安装。

启动

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

组件目标必须命名同一定义中的组件。URL 目标明确选择 embedded 或 external。

组件

每个组件都有唯一的 name、ui 或 process 类型，以及源 path。应用最多可以有一个 UI 组件。

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

env 可以为组件选择机密集合和环境。流程组件还可以声明持久或触发执行以及命名的计划或 webhook 触发器。

工具和技能

工具和技能是独立的。工具定义可调用的操作；技能说明何时以及如何使用它们。

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

连接操作在调用时需要安装。它们由 Kazzle 的系统应用转换器发出；已发布的应用在文件中定义可调用的工具。技能保持独立，只能在相关时加载。

开始使用

构建

用户与数据

发布

使用 Kazzle

安全

参考

配置

配置

快速开始

定义字段

设置

启动

组件

工具和技能

​配置

​快速开始

​定义字段

​设置

​启动

​组件

​工具和技能

配置

快速开始

定义字段

设置

启动

组件

工具和技能