# Download SDK

## 概述

Download SDK 是 renderer 创建和管理 Download Center 任务的类型化入口。
它覆盖应用更新、资源预取、插件下载、任务历史、维护操作与进度订阅，
不暴露 raw IPC。

## 运行时契约

- `useDownloadSdk()` 基于 TuffTransport 创建类型化 SDK。
- 主进程 Download Center 负责任务调度和真实状态。
- renderer 只发送命令并订阅推送事件，不维护第二份任务真源。
- `metadata.hidden` 用于标记内部任务，普通下载视图和通知可隐藏这些任务；
  开发者模式仍可展示。

## 可用操作

当前 SDK 包含任务新增/暂停/继续/取消/重试/删除、批量暂停/继续/取消、
任务与历史查询、文件操作、通知设置、维护、统计、迁移状态和任务生命周期
订阅。

## 使用方法

<!-- markdownlint-disable MD003 MD022 MD023 MD034 -->

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { useDownloadSdk } from '@talex-touch/utils/renderer'

  const download = useDownloadSdk()
  const result = await download.addTask({
    url: 'https://example.com/file.zip',
    destination: '/path/to/save',
    filename: 'file.zip',
    priority: 50,
    module: 'resource_download',
    metadata: { hidden: true }
  })

  if (!result.success) {
    throw new Error(result.error || 'Download failed')
  }
---
:::

<!-- markdownlint-enable MD003 MD022 MD023 MD034 -->

订阅方法会返回清理函数。应在所属 Vue 生命周期中注册清理函数，适用时也可
使用 scoped helper。

## 最佳实践

- 设置有意义的 `priority` 和 `module`，便于调度与诊断。
- 合并或节流任务创建，避免短时间向队列写入大量任务。
- 处理操作失败响应，并提供与场景匹配的重试路径。
- 所属视图或 composable 销毁时取消任务事件订阅。
- 发布/下载服务端路由应通过更新服务契约消费，不要从 renderer 绕过
  Download Center。

## 相关文档

- [Download API 索引](./index.zh.mdc)
- [发布与下载路由](../release/index.zh.md)
- [CoreApp Download Center](../../../../../core-app/src/main/modules/download/README.md)
- [Release Assets 核对清单](../../../../../../docs/engineering/nexus-release-assets-checklist.md)
- [English version](./download.en.mdc)