跳转到主要内容

​
配置

每个 Kazzle 应用在项目根目录都有一个 kazzle.config.ts 文件。此文件定义应用包含的内容 — 组件、技能和元数据。

​
快速开始

import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
defineConfig 辅助函数提供 TypeScript 自动完成和验证。类型来自 kazzle.types.ts，它是自动生成的，包含在每个模板中。

​
顶级字段

字段类型必需描述
iconstring否应用图标文件的路径，相对于仓库根目录（png、jpg、svg、webp、ico）。发布时上传到 CDN。
componentsobject[]否可执行组件 — UI 前端或后台进程
skillsobject[]否AI 技能定义 — AI 读取的 markdown 文件，用于领域知识
capabilitiesobject否可选的桌面集成功能，如快捷键、通知和状态栏显示

​
组件字段

components[] 中的每个条目：
字段类型必需描述
namestring是应用内唯一的组件名称
type"ui" | "process"是组件类型 — ui（最多 1 个）或 process
pathstring是应用目录内的入口路径
runtimeobject否命令：{ dev?, build?, run? }
runtime.devstring否启动开发服务器的命令（例如 "bun run dev"）
runtime.buildstring否为生产环境构建的命令（例如 "vite build"）
runtime.runstring否在生产环境中启动的命令（例如 "bun run start"）
schedulestring否进程组件的 Cron 计划（例如 "*/5 * * * *"）
trigger"webhook" | "event"否进程组件的触发模式
envobject否密钥集合 + 环境变量注入的环境
env.collectionstring是（如果有 env）密钥集合 slug
env.environmentstring是（如果有 env）环境 slug
env.includestring[]否仅注入这些环境变量名称。如果省略，注入集合+环境中的所有变量。

​
技能字段

skills[] 中的每个条目：
字段类型必需描述
namestring是技能名称
pathstring是SKILL.md 文件的路径，相对于应用根目录

​
约束

  • 每个应用最多 1 个 UI 组件
  • 组件 name 值在应用内必须唯一

​
模板示例

​
ui 应用

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 应用图标的路径，相对于仓库根目录。发布时上传到 CDN。 */
  icon: 'components/ui/public/favicon.svg',
  /** 应用组件 — 每个条目定义一个可部署单元。最多 1 个 UI 组件。 */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});

​
process 应用

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 应用图标的路径，相对于仓库根目录。发布时上传到 CDN。 */
  icon: 'icon.svg',
  /** 应用组件 — 每个条目定义一个可部署单元。 */
  components: [
    {
      name: 'My App',
      type: 'process',
      path: './components/process/index.ts',
      runtime: { dev: 'bun run dev', run: 'bun run start' },
      // 持久进程是长时间运行的服务器。平台在每个触发器的 `path` 处
      // 向运行中的服务器发送触发器，使用
      // `Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`。客户代码
      // 在执行工作前验证标头。
      processMode: 'persistent',
      triggers: [
        // 示例 cron — 取消注释并调整。5 字段，分钟精度。
        // { name: 'hourly-sync', kind: 'schedule', schedule: '0 * * * *', path: '/cron/hourly-sync' },
        // 示例 webhook — POST 到 /webhooks/{spaceId}/{appId}/My App/incoming
        // { name: 'incoming', kind: 'webhook', path: '/webhook/incoming' },
      ],
    },
  ],
});

​
空应用

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 应用图标的路径，相对于仓库根目录。发布时上传到 CDN。 */
  icon: 'icon.svg',
  /** 应用组件 — 每个条目定义一个可部署单元。 */
  components: [],
});