SDK API 概述

概述

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

介绍

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

安装

pnpm add @talex-touch/utils

API 参考

模块	导入方式	说明
Plugin Context	`globalThis`	index.js 全局上下文 API
Box SDK	`useBox()`	控制 CoreBox 窗口
Clipboard SDK	`useClipboard()`	剪贴板读写和历史
TempFile SDK	`useTempPluginFiles()`	临时文件创建与清理
Storage SDK	`usePluginStorage()`	插件数据持久化
Download SDK	`useDownloadSdk()`	下载任务管理
Platform Capabilities SDK	`usePlatformSdk()`	平台能力目录
PowerSDK	`usePowerSDK()`	插件低电量状态能力
RecommendSDK	`recommend`	自定义推荐提供者注册
Account SDK	`accountSDK`	用户信息、订阅、配额
TuffTransport	`useTuffTransport()`	新一代 IPC（推荐）
Feature SDK	`useFeature()`	搜索结果管理
DivisionBox SDK	`useDivisionBox()`	独立窗口管理
Flow SDK	`createFlowSDK()`	插件间数据流转
Intelligence SDK	`useIntelligence()`	AI 能力调用

新功能： 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'