QK 应用开发指南

快速开始

# 创建项目
npx create-qk-app my-app
cd my-app

# 安装依赖
npm install

# 启动开发服务器（浏览器模式，使用 mock API）
npm run dev

# 构建生产版本
npm run build

# 打包为 npm 包
npm run pack

# 发布到 npm
npm run publish

项目结构

my-app/
├── src/
│   ├── App.vue          # 主组件
│   ├── main.ts          # 入口
│   └── vite-env.d.ts    # 类型声明
├── public/
├── index.html
├── icon.png             # 应用图标
├── package.json         # 含 qk 配置字段
├── tsconfig.json
└── vite.config.ts

package.json qk 字段

{
  "qk": {
    "entry": "dist/index.html",
    "icon": "icon.png",
    "singleton": false,
    "permissions": {
      "clipboard": true
    },
    "window": {
      "width": 800,
      "height": 600,
      "resizable": true,
      "center": true
    }
  }
}

| 字段 | 类型 | 说明 | |------|------|------| | entry | string | 入口 HTML 文件（相对于包根目录） | | icon | string | 应用图标文件路径 | | singleton | boolean | 是否单例窗口（true 时重复打开会聚焦已有窗口） | | permissions | object | 权限声明，见下方权限系统章节 | | window | object | 窗口配置：width、height、resizable、center、alwaysOnTop 等 |

@qian-kun/api 使用

安装依赖：

npm install @qian-kun/api

开发时自动使用 mock 实现（通过 vite.config.ts 的 alias 配置），无需 QK Shell 即可运行。

import { clipboard, ai, store } from '@qian-kun/api'

clipboard — 剪贴板

权限声明: "clipboard": true

import { clipboard } from '@qian-kun/api'

// 读取剪贴板文本
const text = await clipboard.readText()

// 写入剪贴板
await clipboard.writeText('Hello QK!')

fs — 文件系统

权限声明: "fs": true 或 "fs": { "sandbox": true }

沙盒模式下，文件操作限定在应用专属目录内。

import { fs } from '@qian-kun/api'

// 读写沙盒文件
const content = await fs.readFile('data.json')
await fs.writeFile('data.json', JSON.stringify({ key: 'value' }))

// 列出目录内容
const files = await fs.readDir('.')

// 读写系统路径（hosts、ssh、desktop、documents、downloads）
const hosts = await fs.readSystemPath('hosts')

store — 持久化键值存储

权限声明: "store": true

import { store } from '@qian-kun/api'

await store.set('theme', 'dark')
const theme = await store.get('theme') // 'dark'
await store.remove('theme')

crypto — 加密哈希

权限声明: "crypto": true

import { crypto } from '@qian-kun/api'

const hash = await crypto.hash('sha256', 'hello world')
// 返回十六进制哈希值

支持算法：sha256、sha512

dialog — 文件对话框

权限声明: "dialog": true

import { dialog } from '@qian-kun/api'

// 打开文件
const file = await dialog.openFile()
if (file) {
  console.log(file.path, file.content)
}

// 保存文件
const savedPath = await dialog.saveFile('内容', { defaultName: 'output.txt' })

shell — 命令执行

权限声明: "shell": true

首次调用时会弹窗确认。可选择"始终允许"跳过后续确认。

import { shell } from '@qian-kun/api'

const result = await shell.execute('echo hello')
console.log(result.stdout) // "hello\n"
console.log(result.exitCode) // 0

communications — 应用间通信

权限声明: "communications": ["other-app-id"]（数组内填可通信的目标应用 ID）

import { communication } from '@qian-kun/api'

// 发送消息给指定应用
await communication.sendMessage('target-app-id', { action: 'refresh' })

// 接收消息
communication.onMessage((from, data) => {
  console.log(`收到来自 ${from} 的消息:`, data)
})

// 打开另一个应用并传参
const windowLabel = await communication.openApp('other-app', { key: 'value' })

// 广播消息给所有应用
await communication.broadcast({ event: 'update' })

ai — 大语言模型

权限声明: "ai": true

使用前需要在 QK Shell 的"AI 设置"中配置 LLM Provider（OpenAI 兼容 / Anthropic Claude）。

import { ai } from '@qian-kun/api'

// 非流式调用
const result = await ai.chat({
  messages: [
    { role: 'user', content: '把"用户年龄"翻译成驼峰变量名' }
  ],
  system: '你是一个变量命名专家，只返回变量名',
})
console.log(result.text)    // "userAge"
console.log(result.usage)   // { input_tokens: 28, output_tokens: 3 }

// 流式调用
const stream = ai.chatStream({
  messages: [{ role: 'user', content: '写一个快速排序' }],
  system: '你是一个代码助手',
  temperature: 0.7,
  onChunk: (text) => {
    outputElement.textContent += text
  },
  onDone: ({ usage, model }) => {
    console.log(`完成，模型: ${model}，用量:`, usage)
  },
  onError: (error) => {
    console.error('AI 错误:', error)
  },
})

// 取消流式请求
stream.stop()

请求参数:

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | messages | Array<{ role, content }> | 是 | 对话消息列表 | | system | string | 否 | 系统提示词 | | temperature | number | 否 | 采样温度（0-2） | | max_tokens | number | 否 | 最大生成 token 数 | | stop | string[] | 否 | 停止序列 |

权限系统

权限在 package.json 的 qk.permissions 中声明。分为三个风险等级：

| 等级 | 权限 | 说明 | |------|------|------| | 🟢 低风险（安装时自动授予） | clipboard、store、crypto、dialog | 无安全风险 | | 🟡 中风险（安装时需确认） | fs、ai | 文件访问 / AI 调用可能产生费用 | | 🔴 高风险（运行时首次弹窗确认） | shell | 可执行任意命令 |

声明格式：

{
  "permissions": {
    "clipboard": true,
    "fs": { "sandbox": true },
    "ai": true,
    "shell": true
  }
}

或使用数组格式：

{
  "permissions": ["clipboard", "store", "crypto"]
}

开发调试

Mock 模式

vite.config.ts 中自动配置了 alias：

resolve: {
  alias: {
    '@qian-kun/api': '@qian-kun/api/src/mock',
  },
}

npm run dev 时使用 mock 实现，所有 API 调用返回模拟数据并输出 console.warn，无需 QK Shell 环境。

在 QK Shell 中测试

1. 构建应用：npm run build
2. 将构建产物（dist/ + icon.png + 含 qk 字段的 package.json）放入 QK 的 apps/<app-id>/ 目录
3. 在 QK Shell 中点击应用图标启动

发布流程

# 1. 构建
npm run build

# 2. 打包（自动校验 qk 字段、entry 文件、图标）
npm run pack

# 3. 发布到 npm（需要 npm 账号且登录）
npm run publish

要求：

• 包名必须以 @qian-kun/ 开头
• qk.entry 指向的文件必须存在（先 build 再 pack）
• 图标文件必须存在

发布后用户即可在 QK Shell 的应用商店中搜索安装你的应用。