参考
SDK API 参考
@kunkunsh/sdk 暴露的每个主机 API，按模块划分，包括子路径导出。
@kunkunsh/sdk 包是您与主机的接口。友好的包装器（Clipboard、fs、db……）通过 kkrpc 调用底层的 getHostAPI() 代理。每个方法都是异步的，并在主机端进行权限检查。
子路径导出
| 导入路径 | 提供内容 |
|---|---|
@kunkunsh/sdk | 主要 API：Clipboard、LocalStorage、fs、shell、path、db、showToast、spawnBackend…… |
@kunkunsh/sdk/ui | Worker/节点视图 UI 原语（Button、List、Form……） |
@kunkunsh/sdk/runtime | 引导程序 + getHostAPI、服务客户端、startKunkunHeadlessPlugin |
@kunkunsh/sdk/contract | defineServiceContract、method、InferService |
@kunkunsh/sdk/backend | exposeBackend（后端进程侧） |
@kunkunsh/sdk/manifest | 清单模式 + 验证器 |
@kunkunsh/sdk/events | 事件类型 + EventMap |
@kunkunsh/sdk/utils | React 钩子：useQuery、useRecord、useForm、useCachedState…… |
@kunkunsh/sdk/build | 构建辅助：kunkunCommandPlugin、dedupeReact |
Clipboard
Clipboard.readText(): Promise<string>
Clipboard.copy(content: string, options?: { transient?: boolean }): Promise<void>
Clipboard.paste(content: string): Promise<void>
Clipboard.clear(): Promise<void>
clipboard.hasImage(): Promise<boolean>
clipboard.getImageBase64(): Promise<string>Storage
键值存储（LocalStorage）。对于列表和查询，请使用记录存储。
LocalStorage.getItem(key: string): Promise<string | undefined>
LocalStorage.setItem(key: string, value: string): Promise<void>
LocalStorage.removeItem(key: string): Promise<void>
LocalStorage.allItems(): Promise<Record<string, string>>
LocalStorage.clear(): Promise<void>需要 storage 权限。
UI（toast、HUD、弹窗、导航）
showToast(options: { title: string; message?: string; style?: Toast.Style }): Promise<void>
showHUD(title: string): Promise<void>
confirmAlert(options: { title: string; message?: string; primaryAction?: { title: string } }): Promise<boolean>
popToRoot(options?: { clearSearchBar?: boolean }): Promise<void>
closeMainWindow(options?: { clearRootSearch?: boolean }): Promise<void>fs
fs.readTextFile(path): Promise<string>
fs.readFile(path): Promise<Uint8Array>
fs.writeTextFile(path, content, options?): Promise<void>
fs.writeFile(path, data, options?): Promise<void>
fs.readDir(path, options?): Promise<DirEntry[]>
fs.stat(path) / fs.lstat(path): Promise<FileInfo>
fs.exists(path): Promise<boolean>
fs.mkdir(path, options?) / fs.remove(path, options?) / fs.rename(old, new) / fs.copyFile(src, dst): Promise<void>需要作用域 fs-read / fs-write。
shell
shell.execute(program, args?, options?): Promise<ChildProcess>
shell.spawn(program, args?, options?): AsyncIterable<SpawnEvent>
shell.hasCommand(command): Promise<boolean>
shell.whereIsCommand(command): Promise<string | null>
shell.executeBashScript / executeZshScript / executeAppleScript / executePowershellScript / executePythonScript / executeNodeScript(script, options?): Promise<ChildProcess>需要作用域 shell。
path
path.join(...parts) / resolve(...parts) / normalize(p) / dirname(p) / basename(p, ext?) / extname(p): Promise<string>
path.homeDir() / desktopDir() / downloadDir() / documentDir() / appDataDir() / tempDir(): Promise<string>
path.extensionDir() / extensionSupportDir(): Promise<string>dialog
openFileDialog(options?): Promise<string[] | null>
saveFileDialog(options?): Promise<string | null>
showMessageDialog(options): Promise<number>open
openUrl(url) / openFile(path) / openFolder(path): Promise<void>由 open-url / open-file / open-folder 限定作用域。
system
showInFinder(path): Promise<void>
trash(path: string | string[]): Promise<void>
getApplications(): Promise<Array<{ name; path; bundleId? }>>
getFrontmostApplication(): Promise<{ name; path; bundleId? }>
getSelectedText(): Promise<string>Window
windowControl.setSize(size) / setPosition(pos) / setTitle(title): Promise<void>
windowControl.minimize() / toggleMaximize() / center() / hide() / show() / close(): Promise<void>
windowControl.setFullscreen(bool) / setAlwaysOnTop(bool) / setVibrancy(type | null) / setOpacity(n): Promise<void>
windowControl.isMaximized() / isMinimized() / isFullscreen(): Promise<boolean>需要 window-control。
permissions
requestPermission(type: string, scope: string, reason?: string): Promise<boolean>
checkPermission(type: string, scope: string): Promise<boolean>
listGrants(): Promise<Array<{ permissionType; scopePattern; duration; grantedAt }>>network
network.fetch(opts: FetchOptions): Promise<FetchResponse> // 绕过 CORS 的 fetch需要包含 domains 的 network 权限。
db（记录存储）
db.collection<T>(name): DbCollection<T> // add/set/update/get/query/watch/…
db.watch(cb) / db.listCollections() / db.deleteCollection(name)完整指南 + 查询构建器 + 实时查询：记录存储。
Events
import { subscribeToHostEvent } from "@kunkunsh/sdk/runtime";
const unsub = subscribeToHostEvent("clipboard:change", (payload) => { /* … */ });EventMap（来自 @kunkunsh/sdk/events）包括 keyboard:*、mouse:*、clipboard:change、app:*、plugin:* 和 db:changed。键盘/鼠标订阅需要 input-monitor。
logger、env 和 preferences
logger.debug/info/warn/error(message, options?): Promise<void>
logger.captureException(error, attributes?): Promise<void>
getEnvironment(): Promise<{ extensionName; commandName; theme; isDevelopment; supportPath; … }>
getPreferenceValues(): Promise<Record<string, PreferenceValue>>
getPlatform() / getUserLanguage(): Promise<…>Runtime 和后端
import { getHostAPI, startKunkunHeadlessPlugin } from "@kunkunsh/sdk/runtime";
import { createServiceClient, createValidatedServiceClient } from "@kunkunsh/sdk/runtime";
import { spawnBackend } from "@kunkunsh/sdk";
import { exposeBackend } from "@kunkunsh/sdk/backend";getHostAPI()— 类型化的主机代理（很少直接使用）。startKunkunHeadlessPlugin({ init, onTrigger, destroy })— 无头入口。- 服务客户端 — 服务。
spawnBackend/exposeBackend— 后端进程。
React 钩子（@kunkunsh/sdk/utils）
useQuery<T>(collection, options?) // 实时记录查询
useRecord<T>(collection, id) // 实时单条记录
useForm<T>({ onSubmit, validation })
useCachedState / useCachedPromise / useFetch / useAI