> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置

> kazzle.config.ts 完整參考 — 應用清單。

# 配置

每個 Kazzle 應用在專案根目錄都有一個 `kazzle.config.ts`。此檔案定義應用包含的內容 — 元件、技能和中繼資料。

## 快速開始

```typescript theme={"theme":"material-theme-darker"}
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

```typescript theme={"theme":"material-theme-darker"}
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

```typescript theme={"theme":"material-theme-darker"}
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

```typescript theme={"theme":"material-theme-darker"}
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' },
  ],
});
```