配置

每個 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`	設置對象	是	如何配置安裝。
`launch`	啟動對象	是	安裝後打開的內容。
`components`	component[]	是	UI 和流程組件。
`tools`	工具源[]	是	編譯成可調用 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

安全性

參考

配置

配置

快速開始

定義字段

設置

啟動

組件

工具和技能

​配置

​快速開始

​定義字段

​設置

​啟動

​組件

​工具和技能

配置

快速開始

定義字段

設置

啟動

組件

工具和技能