配置
每個 Kazzle 應用在專案根目錄都有一個kazzle.config.ts。此檔案定義應用包含的內容 — 元件、技能和中繼資料。
快速開始
import { defineConfig } from '@kazzle/app';
export default defineConfig({
components: [
{ name: 'My App', type: 'ui', path: '.' }
]
});
defineConfig 輔助函式提供 TypeScript 自動完成和驗證。型別來自每個範本都包含的 @kazzle/app 套件。
頂層欄位
| 欄位 | 型別 | 必需 | 說明 |
|---|---|---|---|
name | string | 否 | 應用目錄中顯示的行銷名稱。省略時回退到 slug。 |
subtitle | string | 否 | 目錄中應用名稱下方顯示的簡短單行標語（例如「從 Kazzle 控制 Mac 應用」）。發佈時必需 — 省略會導致發佈失敗。 |
version | string | 否 | 作者設定的版本標籤（例如「1.2.0」）。僅供顯示；發佈時快照，複製時顯示為分支來源版本。 |
icon | string | 否 | 相對於儲存庫根目錄的應用圖示檔案路徑（png、jpg、svg、webp、ico）。發佈時上傳至 CDN。 |
accentColor | string | 否 | 選用的品牌強調色，十六進位字串格式（例如「#3b82f6」）。為應用圖示晶片和詳細頁面英雄著色。省略時，強調色自動從圖示取樣。 |
kazzleAuth | "optional" | "required" | 否 | 應用啟動介面的身分驗證 — 「optional」（如果有 Kazzle 使用者則提供身分）或「required」（必須是已登入的 Kazzle 使用者才能檢視）。 |
launchUrl | string | 否 | 點擊應用時在 Kazzle 內開啟的絕對 URL，按字面使用。省略時，啟動介面是 UI 元件的已部署預覽 URL。 |
webhookUrl | string | 否 | 發佈者端點，Kazzle 在 app.installed / app.uninstalled 時 POST（傳遞安裝金鑰）。 |
components | object[] | 否 | 可執行元件 — UI 前端或背景程序 |
skills | object[] | 否 | AI 技能定義 — AI 讀取的 markdown 檔案以獲取領域知識 |
capabilities | object | 否 | 選用的桌面整合功能，例如快捷鍵、通知和狀態列顯示 |
元件欄位
components[] 中的每個項目：
| 欄位 | 型別 | 必需 | 說明 |
|---|---|---|---|
name | string | 是 | 應用內唯一的元件名稱 |
type | "ui" | "process" | 是 | 元件型別 — ui（最多 1 個）或 process |
path | string | 是 | 應用目錄內的進入路徑 |
runtime | object | 否 | 命令和選用的環境覆蓋：{ dev?, prod? } |
runtime.dev.command | string | 否 | 啟動開發伺服器的命令（例如 "bun run dev"） |
runtime.dev.env | object | 否 | 僅開發環境覆蓋。回退到元件 env。 |
runtime.prod.command | string | 否 | 生產環境中啟動的命令（例如 "bun run start"） |
runtime.prod.build | string | 否 | 為生產環境構建的命令（例如 "vite build"） |
runtime.prod.env | object | 否 | 僅生產環境覆蓋。回退到元件 env。 |
schedule | string | 否 | 程序元件的 Cron 排程（例如 "*/5 * * * *"） |
trigger | "webhook" | "event" | 否 | 程序元件的觸發模式 |
env | object | 否 | 秘密集合 + 環境用於環境變數注入 |
env.collection | string | 是（如果有 env） | 秘密集合 slug |
env.environment | string | 是（如果有 env） | 環境 slug |
env.include | string[] | 否 | 僅注入這些環境變數名稱。省略時，注入集合+環境中的全部。 |
技能欄位
skills[] 中的每個項目：
| 欄位 | 型別 | 必需 | 說明 |
|---|---|---|---|
name | string | 是 | 技能名稱 |
path | string | 是 | 相對於應用根目錄的 SKILL.md 檔案路徑 |
限制
- 每個應用最多 1 個 UI 元件
- 元件
name值在應用內必須唯一
範本示例
ai app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** 單行目錄標語。發佈時必需。 */
subtitle: 'My App',
icon: 'components/ui/public/favicon.svg',
components: [
{ name: 'ui', type: 'ui', path: './components/ui' },
{ name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
],
});
ui db app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** 單行目錄標語。發佈時必需。 */
subtitle: 'My App',
icon: 'components/ui/public/favicon.svg',
components: [
{ name: 'ui', type: 'ui', path: './components/ui' },
{ name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
],
});
ui app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** 單行目錄標語。發佈時必需。 */
subtitle: 'My App',
/** 相對於儲存庫根目錄的應用圖示路徑。發佈時上傳至 CDN。 */
icon: 'components/ui/public/favicon.svg',
/** 應用元件 — 每個項目定義一個可部署單位。最多 1 個 UI 元件。 */
components: [
{ name: 'My App', type: 'ui', path: './components/ui' },
],
});