# SDK API 概述

## 概述

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

## 介绍

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

## 安装

:::TuffCodeBlock{lang="bash"}
---
code: |
  pnpm add @talex-touch/utils
---
:::

## API 参考
<!-- markdownlint-disable MD060 -->
| 模块                                                          | 导入方式                                           | 说明                                            |
| ----------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| [Plugin Context](./plugin-context.zh.mdc)                   | `IPluginContext` / `context.utils`             | Canonical lifecycle capability facade         |
| [Box SDK](./box.zh.mdc)                                     | `useBox()`                                     | 控制 CoreBox 窗口                                 |
| [Clipboard SDK](./clipboard.zh.mdc)                         | `useClipboard()` / `system.captureSelection()` | 剪贴板、选中文本和历史                                   |
| [TempFile SDK](./temp-file.zh.mdc)                          | `useTempPluginFiles()`                         | 临时文件创建与清理                                     |
| [Storage SDK](./storage.zh.mdc)                             | `usePluginStorage()`                           | 插件数据持久化                                       |
| [Download SDK](./download.zh.mdc)                           | `useDownloadSdk()`                             | 下载任务管理                                        |
| [Platform Capabilities SDK](./platform-capabilities.zh.mdc) | `usePlatformSdk()`                             | 平台能力目录                                        |
| [Screenshot SDK](./screenshot.zh.mdc)                       | `screenshot` / `plugin.screenshot`             | 权限门禁下的显示器、指针屏幕与区域截图                           |
| [PowerSDK](./power.zh.mdc)                                  | `usePowerSDK()`                                | 插件低电量状态能力                                     |
| [RecommendSDK](./recommend.zh.mdc)                          | `recommend`                                    | 自定义推荐提供者注册                                    |
| [**Account SDK**](./account.zh.mdc)                         | `accountSDK`                                   | **用户信息、订阅、配额**                                |
| [**TuffTransport**](./transport.zh.mdc)                     | `useTuffTransport()`                           | **新一代 IPC（推荐）**                               |
| [Feature SDK](./feature.zh.mdc)                             | `useFeature()`                                 | 搜索结果管理                                        |
| [Search / Indexed Source SDK](./search.zh.mdc)              | `@talex-touch/utils/search`                    | Search provider 与 indexed-source lifecycle 合同 |
| [QuickActions SDK](./quick-actions.zh.mdc)                  | `quickActions` / `plugin.quickActions`         | MetaK 全局动作与原生分享                               |
| [QuickOps SDK](./quickops.zh.mdc)                           | `quickOps` / `plugin.quickOps`                 | 内置本地快捷工具的 bounded、策略感知 host facade            |
| [DivisionBox SDK](./division-box.zh.mdc)                    | `useDivisionBox()`                             | 独立窗口管理                                        |
| [Flow SDK](./flow-transfer.zh.mdc)                          | `createFlowSDK()`                              | 插件间数据流转                                       |
| [Intelligence SDK](./intelligence.zh.mdc)                   | `useIntelligenceSdk()` / `plugin.intelligence` | AI 能力调用与 Provider 发现                          |
| [Localization SDK](./i18n.zh.mdc)                           | `usePluginI18n()` / `plugin.i18n`              | 主机语言、localized text 与隔离 Domain Lexicon        |
<!-- markdownlint-enable MD060 -->
::alert{type="info"}
**新功能：** [TuffTransport](./transport.zh.mdc) 是新插件推荐使用的 IPC API。它提供类型安全的事件、自动批量处理和流式传输支持。查看 [TuffTransport 技术内幕](./transport-internals.zh.mdc) 了解技术细节。
::

---

## 快速开始

:::TuffCodeBlock{lang="typescript"}
---
code: |
  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：

:::TuffCodeBlock{lang="typescript"}
---
code: |
  // ✅ 正确
  const storage = usePluginStorage()
  await storage.getFile('config.json')

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

**2. 自动上下文检测**

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

:::TuffCodeBlock{lang="typescript"}
---
code: |
  const storage = usePluginStorage()
  // 自动获取当前插件名称，无需传递
---
:::

**3. 返回 Dispose 函数**

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

:::TuffCodeBlock{lang="typescript"}
---
code: |
  const unsubscribe = feature.onInputChange((input) => {
  // ...
  })

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

**4. Promise 异步**

所有异步操作返回 Promise：

:::TuffCodeBlock{lang="typescript"}
---
code: |
  const config = await storage.getFile('config.json')
  await clipboard.copyAndPaste({ text: 'Hello' })
---
:::

---

## 技术原理

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

## 类型导入

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import type {
  TuffItem,
  TuffQuery,
  ClipboardType,
  DivisionBoxConfig,
  FlowPayload
  } from '@talex-touch/utils/plugin/sdk'
---
:::

---

## 相关文档

- [插件开发快速开始](../getting-started/quickstart.zh.mdc)
- [Manifest 配置](../reference/manifest.zh.mdc)
- [构建工具 Unplugin](../extensions/unplugin-export-plugin.zh.mdc)