SDK API 概述

概述

Tuff 插件 SDK 提供了一套完整的 API，用于开发 CoreBox 插件。所有 API 都采用函数式设计，通过 use* 钩子函数获取实例。

介绍

SDK 以插件运行时上下文为基础，统一输出窗口控制、剪贴板、搜索、存储等能力，适合快速搭建可交互的 CoreBox 插件。

安装

pnpm add @talex-touch/utils

API 参考

模块	导入方式	说明
Plugin Context	`IPluginContext` / `context.utils`	Canonical lifecycle capability facade
Box SDK	`useBox()`	控制 CoreBox 窗口
Clipboard SDK	`useClipboard()` / `system.captureSelection()`	剪贴板、选中文本和历史
TempFile SDK	`useTempPluginFiles()`	临时文件创建与清理
Storage SDK	`usePluginStorage()`	插件数据持久化
Download SDK	`useDownloadSdk()`	下载任务管理
Platform Capabilities SDK	`usePlatformSdk()`	平台能力目录
Screenshot SDK	`screenshot` / `plugin.screenshot`	权限门禁下的显示器、指针屏幕与区域截图
PowerSDK	`usePowerSDK()`	插件低电量状态能力
RecommendSDK	`recommend`	自定义推荐提供者注册
Account SDK	`accountSDK`	用户信息、订阅、配额
TuffTransport	`useTuffTransport()`	新一代 IPC（推荐）
Feature SDK	`useFeature()`	搜索结果管理
Search / Indexed Source SDK	`@talex-touch/utils/search`	Search provider 与 indexed-source lifecycle 合同
QuickActions SDK	`quickActions` / `plugin.quickActions`	MetaK 全局动作与原生分享
QuickOps SDK	`quickOps` / `plugin.quickOps`	内置本地快捷工具的 bounded、策略感知 host facade
DivisionBox SDK	`useDivisionBox()`	独立窗口管理
Flow SDK	`createFlowSDK()`	插件间数据流转
Intelligence SDK	`useIntelligenceSdk()` / `plugin.intelligence`	AI 能力调用与 Provider 发现
Localization SDK	`usePluginI18n()` / `plugin.i18n`	主机语言、localized text 与隔离 Domain Lexicon

新功能： TuffTransport 是新插件推荐使用的 IPC API。它提供类型安全的事件、自动批量处理和流式传输支持。查看 TuffTransport 技术内幕了解技术细节。

快速开始

import {
useBox,
useClipboard,
usePluginStorage,
usePowerSDK,
useFeature,
useDivisionBox
} from '@talex-touch/utils/plugin/sdk'
import { useTuffTransport } from '@talex-touch/utils/transport'

// 初始化 SDK
const box = useBox()
const clipboard = useClipboard()
const storage = usePluginStorage()
const power = usePowerSDK()
const transport = useTuffTransport()
const feature = useFeature()
const divisionBox = useDivisionBox()

// 使用示例
async function init() {
// 读取配置
const config = await storage.getFile('config.json')

    // 读取低电量状态
    const lowPower = await power.isLowPower({ threshold: 25 })
    if (lowPower) {
      console.log('电池模式下跳过重负载任务')
    }

    // 监听输入变化
    feature.onInputChange(async (input) => {
      const results = await search(input)
      feature.pushItems(results)
    })

    // 监听剪贴板
    await box.allowClipboard(ClipboardType.TEXT)
    clipboard.history.onDidChange((item) => {
      console.log('剪贴板变化:', item)
    })

## }

最佳实践

1. 函数式 API

所有 SDK 都通过 use* 函数获取实例，无需手动传递 context：

// ✅ 正确
const storage = usePluginStorage()
await storage.getFile('config.json')

// ❌ 错误（旧版 API，已废弃）
// const storage = ctx.storage
// await storage.getItem('key')

2. 自动上下文检测

SDK 会自动检测插件上下文，无需手动配置：

const storage = usePluginStorage()
// 自动获取当前插件名称，无需传递

3. 返回 Dispose 函数

所有监听器都返回取消订阅函数：

const unsubscribe = feature.onInputChange((input) => {
// ...
})

// 组件卸载时取消订阅
onUnmounted(() => {
unsubscribe()
})

4. Promise 异步

所有异步操作返回 Promise：

const config = await storage.getFile('config.json')
await clipboard.copyAndPaste({ text: 'Hello' })

技术原理

use* 钩子在运行时自动解析插件上下文，避免手动传递 context。
通信层基于 IPC/Transport 统一封装，监听器返回 dispose 函数用于清理。

类型导入

import type {
TuffItem,
TuffQuery,
ClipboardType,
DivisionBoxConfig,
FlowPayload
} from '@talex-touch/utils/plugin/sdk'