参考
清单参考
Kunkun 清单的每个字段，以及交互式验证器。
您的扩展清单是 package.json 中的 kunkun 字段。它由 @kunkunsh/sdk/manifest 中提供的 Valibot 模式验证——下面的验证器也使用相同的模式。
交互式验证器
粘贴或编辑 package.json，它将根据实际模式实时检查：
Manifest validator● valid
这会验证整个 package.json（顶层字段加上 kunkun）。错误会显示字段路径和消息。
顶层 package.json
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | npm 包名称（必填） |
version | string | semver 版本（必填） |
license | string | 必填 |
$schema | string | https://schema.kunkun.sh/ 用于编辑器提示 |
author, contributors, repository, description | — | 标准 npm 字段 |
files | string[] | tarball 中包含的文件（例如 ["dist"]） |
kunkun | object | 清单（见下方） |
kunkun 清单
| 字段 | 类型 | 说明 |
|---|---|---|
identifier | string | 必填。 稳定的唯一 ID（例如 com.you.tool）。影响安装、存储、授权——切勿更改。 |
name | string | 显示名称（回退到包名称） |
shortDescription / longDescription | string | 商店列表 |
icon | Icon | 见下方 |
commands | Command[] | 必填。 每个命令一个条目 |
permissions | Permission[] | 见权限 |
preferences | Preference[] | 扩展级偏好设置 |
demoImages | string[] | 商店截图 |
categories | Category[] | 商店分类 |
platforms | ("linux"|"macos"|"windows")[] | 限制平台 |
services | Service[] | 暴露的服务 |
serviceDependencies | ServiceDependency[] | 您消费的服务 |
bindings | object | 主机 LLM/资源绑定 |
binaryDependencies | BinaryDependency[] | 主机托管的三进制依赖 |
图标
{ "type": "iconify", "value": "mdi:puzzle", "invert": true }type: "iconify" 使用 Iconify ID；invert 为深色模式反转颜色。
命令
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 内部命令 ID |
title | string | 在命令面板中显示 |
description | string | — |
mode | CommandMode | 见下方 |
main | string | 入口：路由（/）、dist/App.js 或 dist/node/App.js |
dist | string | 构建输出目录（自定义视图） |
devMain | string | 开发服务器 URL（HMR） |
icon | Icon | 每个命令的图标 |
window | WindowConfig | 自定义/节点视图窗口选项 |
runtime | "auto"|"deno"|"node" | 节点模式运行时覆盖 |
interval | number | "5m" | 计划任务（无头模式） |
cron | string | cron 计划（无头模式） |
arguments | Argument[] | 用户输入参数 |
preferences | Preference[] | 每个命令的偏好设置 |
keywords | string[] | 额外搜索词 |
platforms | OSPlatform[] | 限制此命令的平台 |
mode — 取以下之一：
| 值 | 运行时 | 说明 |
|---|---|---|
custom-view | BrowserWindow | 您自己的 SPA |
worker-view | Web Worker | 通过 Uniview 使用 React |
node-view | Node/Deno | React + 系统访问 |
worker-headless | Web Worker | 无 UI |
node-headless | Node/Deno | 无 UI + 系统访问 |
menu-bar | Tray | 菜单栏命令 |
quicklink | — | 导航到 link |
view / no-view | — | Raycast 别名 → node-view / node-headless |
窗口配置（自定义/节点视图）
{ "titleBarStyle": "overlay", "transparent": true, "vibrancy": "sidebar", "width": 700, "height": 550 }服务
{
"name": "math",
"description": "数学运算",
"main": "dist/node/MathService.js",
"serviceMode": "node-headless",
"methods": [
{ "name": "add", "description": "加法", "inputSchema": { /* JSON Schema */ }, "outputSchema": { /* JSON Schema */ } }
]
}完整模式见服务。
权限
简单字符串或作用域对象——完整目录和作用域形状见权限。快速形状提醒：
{
"permissions": [
"clipboard-read",
{ "permission": "fs-read", "allow": ["$EXTENSION_SUPPORT/**"] },
{ "permission": "network", "domains": ["*.github.com"] },
{ "permission": "shell", "commands": [{ "program": "git", "args": ["status"] }] },
{ "permission": "backend", "allow": [{ "script": "$EXTENSION/dist/backend.js", "runtime": "node" }] }
]
}最小有效清单
{
"name": "hello",
"version": "0.1.0",
"license": "MIT",
"kunkun": {
"identifier": "com.you.hello",
"commands": [{ "name": "main", "title": "Hello", "mode": "worker-view", "main": "dist/App.js" }]
}
}