配置
每个 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（传递安装密钥）。 |
appLogin | boolean | 否 | 此应用的最终用户登录（通过 @kazzle/app/auth — 目前支持 Google）。不同于 kazzleAuth（启动界面的 Kazzle 账户门控）；appLogin 是应用自身的用户，存储在其自己的数据库中。需要流程和数据库。 |
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' } } },
],
});
login app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** 单行目录标语。发布时必需。 */
subtitle: 'My App',
icon: 'components/ui/public/favicon.svg',
/** 最终用户登录（通过 Kazzle 的 Google）。用户存储在此应用自己的数据库中。 */
appLogin: true,
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' } } },
],
});