> ## 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' },
  ],
});
```