@file-ud.js/core 0.1.0

package/dist/utils/index.d.ts

@@ -0,0 +1,2048 @@
+import PQueue from 'p-queue';
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+declare class EventEmitter {
+    events?: Map<EventName, Set<Function>>;
+    /** 确保 events Map 已初始化（兼容 Object.create 不执行字段初始化器） */
+    private ensureEvents;
+    on<K extends EventName>(eventName: K, callback: EventCallback<K>): this;
+    emit<K extends EventName>(eventName: K, ...args: Parameters<EventCallback<K>>): boolean;
+    once<K extends EventName>(eventName: K, callback: EventCallback<K>): this;
+    off<K extends EventName>(eventName: K, callback?: EventCallback<K>): this;
+    listenerCount(eventName: EventName): number;
+    removeAllListeners(eventName?: EventName): this;
+}
+
+/**
+ * 分片管理器基类
+ *
+ * 提取上传/下载分片管理器的所有公共逻辑：
+ * - 并发分片传输调度
+ * - 暂停/恢复/取消
+ * - 重试机制（含 AbortController + 超时）
+ * - 进度计算 & 速率统计
+ * - 分片完成/失败后的事件触发与状态聚合
+ *
+ * 子类只需实现以下抽象方法：
+ * - {@link getTag}      日志标签
+ * - {@link getTransferFile}  关联的传输文件实例
+ * - {@link doInit}      初始化传输（获取已传分片列表等）
+ * - {@link doChunkTransfer}  执行单个分片的实际传输
+ * - {@link doMergeChunks}    合并所有分片
+ */
+declare abstract class ChunkManager<T extends TransferFile<T> = TransferFile<any, any>> {
+    chunkSize: number;
+    maxConcurrent: number;
+    /** 最大速率限制（bytes/秒），0 = 不限制。下载场景由 maxDownloadSpeed 设置 */
+    maxSpeed: number;
+    chunkIndex: number;
+    retries: number | null;
+    retryDelay: number;
+    timeout: number;
+    chunk: Blob | null;
+    totalChunks: number;
+    chunks: boolean[];
+    chunkEndTime: number;
+    completedChunks: number;
+    totalChunkTime: number;
+    response: any;
+    queue: PQueue | null;
+    chunkStartTime: number;
+    chunkStatsInfos: {
+        totalTime: number;
+        fileSize: number;
+        completedChunks: number | undefined;
+        averageSpeed: number;
+    };
+    totalChunkSize: number;
+    config: ChunkOptions;
+    countedChunks: Set<number>;
+    fileHash: string;
+    failedChunks: number[];
+    retryCountMap: Map<number, number>;
+    isPaused: boolean;
+    isCancelled: boolean;
+    pauseResolves: Array<() => void>;
+    activeUploads: Set<Promise<void>>;
+    abortControllers: AbortController[];
+    lastUpdateTime: number;
+    lastChunkBytes: number;
+    /** 每次 start() 递增的代数计数器，防止旧 run 的异步回调污染新 run 的状态 */
+    private _startGeneration;
+    /** 速率限制：累计已传输字节数（用于限速计算） */
+    private _throttleBytes;
+    /** 速率限制：起始时间戳 */
+    private _throttleStartTime;
+    chunkStats: {
+        averageTime: number;
+        maxTime: number;
+        minTime: number;
+    } | null;
+    /** 是否秒传/秒下（无需实际传输，文件已在目标端） */
+    isInstantTransfer: boolean;
+    /** 关联的传输文件（UploadFile / DownloadFile） */
+    protected transferFile: T;
+    /** 日志标签，如 "uploadChunkManager" / "DownloadChunkManager" */
+    protected abstract getTag(): string;
+    /** 计算文件唯一标识：上传=本地MD5，下载=服务端Hash / 指纹 */
+    protected abstract computeFileIdentifier(): Promise<string>;
+    /** 返回关联的传输文件实例 */
+    protected getTransferFile(): T;
+    /** 初始化传输：检查已上传/已下载分片（断点续传） */
+    protected abstract doInit(): Promise<any>;
+    /** 执行单个分片的实际传输（上传/下载） */
+    protected abstract doChunkTransfer(chunkIndex: number, signal?: AbortSignal): Promise<{
+        data: any;
+        chunkSize: number;
+    }>;
+    /** 合并所有分片 */
+    protected abstract doMergeChunks(): Promise<any>;
+    /** start() 重置后的额外清理，如下载场景清空 downloadedChunks */
+    protected doAfterStartReset(): Promise<void>;
+    /** 分片传输成功后保存结果数据（上传存 response，下载存 blob 到 Map / 流式写入磁盘） */
+    protected doSaveChunkResult(_chunkIndex: number, _data: any): Promise<void>;
+    /** onSuccess 之前的额外操作，如下载场景调用 saveBlob */
+    protected doBeforeOnSuccess(_mergeResult: any): Promise<void>;
+    /** start() 发现所有分片已完成时的处理（上传需区分秒传/断点续传） */
+    protected doOnAllChunksAlreadyDone(_initResult: any): Promise<void>;
+    /**
+     * 标记所有分片为已完成（秒传/秒下、服务端已存在全部分片）
+     */
+    protected applyAllChunksComplete(fileSize: number): void;
+    /**
+     * 断点续传恢复：从 initResult.chunks 标记已完成的分片
+     * @param initResult - 服务端返回的初始化结果，包含 chunks 数组
+     */
+    protected applyBreakpointResume(initResult: {
+        chunks?: number[] | null;
+    }): void;
+    constructor(ChunkOptions: ChunkOptions, file: T);
+    /**
+     * 暂停传输（上传/下载统一实现）
+     */
+    pause(): void;
+    /**
+     * 恢复传输（上传/下载统一实现）
+     */
+    resume(): Promise<void>;
+    /**
+     * 取消传输（上传/下载统一实现）
+     */
+    cancel(): void;
+    /**
+     * 是否处于暂停状态
+     */
+    getPaused(): boolean;
+    /**
+     * 获取失败分片的数量
+     */
+    getFailedChunksCount(): number;
+    /**
+     * 更新传输进度百分比
+     */
+    updateProgress(): void;
+    /**
+     * 计算并触发全局速率更新
+     */
+    protected calculateAndUpdateSpeed(currentTransferredBytes: number): void;
+    /**
+     * 计算传输统计信息
+     */
+    protected calculateStats(): void;
+    /**
+     * 统一的 entry：启动分片传输
+     */
+    start(): Promise<void>;
+    /** 子类覆写以返回不同的开始事件名 */
+    protected getStartEventName(): string;
+    /**
+     * 重试失败的分片
+     */
+    retryFailedChunks(): Promise<void>;
+    /**
+     * 带超时 & 重试机制的单个分片传输
+     */
+    protected chunkWithRetry(chunkIndex: number): Promise<void>;
+    /**
+     * 分片传输成功后的统一处理
+     */
+    protected handleChunkSuccess(chunkIndex: number, result: {
+        data: any;
+        chunkSize: number;
+    }): Promise<void>;
+    /**
+     * 分片传输失败后的统一处理
+     */
+    protected handleChunkError(chunkIndex: number, error: any): void;
+    /**
+     * 并发传输所有分片
+     *
+     * @param startGen - 当前 start() 调用的代数，用于过滤上一轮残留的异步回调
+     */
+    protected transferWithConcurrency(startGen?: number): Promise<void>;
+    /**
+     * 检查统计信息并触发合并或失败处理
+     */
+    protected checkStatistics(): Promise<void>;
+    /**
+     * 处理所有分片成功
+     */
+    protected handleAllChunksSuccess(): Promise<void>;
+    /**
+     * 处理失败分片
+     */
+    protected handleFailedChunks(): Promise<void>;
+    /**
+     * 设置文件状态为失败
+     */
+    protected setFileStatusToFail(): void;
+    /**
+     * 等待恢复（暂停/恢复机制）
+     */
+    protected waitForResume(): Promise<void>;
+    /**
+     * 下载速率限流：在传输每个分片前检查是否需要延迟
+     *
+     * 采用平均速率算法：累计已传输字节数 / 已用时间 必须 ≤ maxSpeed。
+     * 如果当前速率超过限制，sleep 差值后继续。
+     *
+     * @param chunkSize - 待传输分片的预计大小（字节）
+     */
+    protected throttleBeforeChunk(chunkSize: number): Promise<void>;
+    /**
+     * 从活跃控制器列表中移除指定的 AbortController
+     */
+    protected removeAbortController(controller: AbortController): void;
+    /**
+     * 合并完成后的收尾（可分片数量完整时直接走合并流程）
+     */
+    protected completeMerge(): Promise<void>;
+}
+
+declare class TransferFile<T extends TransferFile<T, any>, D = any> {
+    /**
+     * 上传速率统计信息
+     * 包含瞬时速度、平均速度及其格式化字符串
+     * 通过 Proxy 自动触发全局速率聚合
+     */
+    speed: speedInfo;
+    /**
+     * 上传下载时间统计信息
+     * 记录文件从开始到结束的完整耗时
+     * 通过 Proxy 自动触发 UI 更新
+     */
+    transferTime: TimeInfo;
+    /** 文件唯一标识符 */
+    fileId: string;
+    /** Proxy 代理对象,用于实现响应式更新 */
+    proxy: T;
+    /** 文件预览 URL (Object URL) */
+    url: string;
+    /** 文件名称 */
+    fileName: string;
+    /** 原始 File 对象 */
+    File: File;
+    /** 上传进度百分比 (0-100) */
+    percent: number | undefined;
+    /** 所属的 Uploader 实例 */
+    transfer: Transfer;
+    /** 是否正在上传 */
+    loading: boolean;
+    /** 文件传输状态 */
+    status: IFile["status"];
+    isCancel: boolean;
+    /** 文件扩展名 */
+    extension: string | undefined;
+    hashPercent: number;
+    hashLoading: boolean;
+    /** 格式化后的文件大小,如 "5.23 MB" */
+    formatSize: string | undefined;
+    /** 当前文件已上传的大小（格式化字符串），如 "45.23 MB" */
+    transferFormatSize: string;
+    context: any;
+    /** 表单数据对象,用于携带上传参数 */
+    formData: FormData | null;
+    chunkManager: ChunkManager | null;
+    /** 是否处于重试状态 */
+    isRetry?: boolean;
+    size: number;
+    /** Promise resolve 回调引用 */
+    resolve: ((value: any) => void | undefined) | undefined;
+    /** Promise reject 回调引用 */
+    reject: ((reason?: any) => void | undefined) | undefined;
+    /** 文件在队列中的索引 */
+    index?: number;
+    /** 插件可写入的自定义元数据 */
+    metadata?: Record<string, any>;
+    sub: T | null;
+    /** 取消上传的函数 */
+    abort: IFile["abort"];
+    /** 标记是否已计入总字节数（避免重试时重复累加） */
+    __hasCountedTotalBytes__: boolean;
+    /** 当前文件已上传的字节数（用于普通上传计算总进度） */
+    __transferBytes__: number;
+    type: string;
+    /** 上次计算速率的时间戳 (毫秒) */
+    protected lastUpdateTime: number;
+    /** 上次已传输的字节数 */
+    protected lastTransferBytes: number;
+    /** 传输开始的时间戳 (毫秒) */
+    protected transferStartTime: number;
+    constructor(file: IFile, transfer: Transfer);
+    isUploader(): boolean;
+    isDownloader(): boolean;
+    /**
+     * 开始传输
+     *
+     * 统一的传输入口，自动根据配置选择分片传输或普通传输：
+     * - **分片传输**: 调用 chunkManager.start()
+     * - **普通传输**: 由子类实现具体逻辑
+     *
+     * @example
+     * ```typescript
+     * // 手动传输模式
+     * const file = uploader.addFile(fileObject);
+     *
+     * // 用户点击按钮时
+     * button.onclick = () => {
+     *   file.start();
+     * };
+     * ```
+     *
+     * @remarks
+     * - 如果文件已经在传输中，会忽略此次调用
+     * - 如果文件已传输成功，会抛出警告
+     * - 这是异步操作，建议在 UI 上显示加载状态
+     */
+    start(chunkManager: ChunkManager | null): Promise<D>;
+    /**
+     * 取消当前传输
+     */
+    cancel(fn: ((next: () => void) => void) | void): void;
+    /**
+     * 暂停传输（仅分片传输支持）
+     */
+    pause(): void;
+    /**
+     * 恢复传输（仅分片传输支持）
+     */
+    resume(): Promise<void>;
+    /**
+     * 重试传输
+     */
+    retry(): Promise<void>;
+    /**
+     * 执行普通传输的重试（模板方法，由子类覆写）
+     * - UploadFile: 重试上传 → 调用 upload()
+     * - DownloadFile: 重试下载 → 调用 download()
+     */
+    protected doRetryTransfer(): Promise<any>;
+    onSuccess(res: D): void;
+    onError(err: any): void;
+    initInterceptor(): void;
+    /**
+     * 处理传输进度事件（供 XHRInterceptor 回调）
+     *
+     * 统一流程：
+     * 1. 调用子类的 {@link updateLocalProgress} 更新当前文件的本体进度/字节数
+     * 2. 更新格式化后的已传输大小
+     * 3. 调用子类的 {@link calculateGlobalProgress} 计算全局统计
+     * 4. 调用 {@link calculateSpeed} 计算并更新速率
+     * 5. 发射 progress 事件
+     *
+     * @param event - XHR 进度事件对象
+     */
+    handleProgress(event: ProgressEvent): void;
+    /**
+     * 更新当前文件的进度和已传输字节数（模板方法，由子类实现）
+     *
+     * - **普通传输**：从 event.loaded/event.total 直接计算百分比
+     * - **分片传输**：由分片管理器独立维护进度，此处无需额外操作
+     *
+     * @param event - XHR 进度事件对象
+     */
+    protected updateLocalProgress(_event: ProgressEvent): void;
+    /**
+     * 获取文件对应的分片管理器（模板方法，由子类实现）
+     * - UploadFile 返回 uploadChunkManager
+     * - DownloadFile 返回 downloadChunkManager
+     */
+    protected getChunkManager(): ChunkManager | null;
+    /**
+     * 获取文件大小（字节数），兼容上传（有 File 对象）和下载（无 File 对象）场景
+     */
+    getFileSize(): number;
+    /**
+     * 计算全局传输进度（统一实现，子类只需覆写 getChunkManager / getFileSize）
+     *
+     * 汇总所有活动文件的传输进度，更新 transfer 实例上的全局统计
+     *
+     * @param _event - XHR 进度事件对象
+     */
+    protected calculateGlobalProgress(_event: ProgressEvent): void;
+    /**
+     * 计算传输速率（带防抖优化）
+     *
+     * 采用最小时间间隔采样策略，避免高频进度回调导致数值剧烈抖动。
+     * 瞬时速度基于最近两个有效采样点计算，平均速度基于总耗时和总字节数计算。
+     *
+     * @param loadedBytes - 当前已传输的字节数
+     */
+    protected calculateSpeed(loadedBytes: number): void;
+}
+
+declare class Transfer<T extends TransferFile<T> = TransferFile<any>, D = any> extends EventEmitter {
+    /** 当前传输任务的文件列表 */
+    files: T[];
+    /** 当前正在上传或下载任务的文件列表 用来判断当前文件是否全部上传完成 */
+    activeFiles: T[];
+    /** 总字节数 */
+    totalBytes: number;
+    /** 已传输的总字节数 */
+    transferredBytes: number;
+    /** 总的已传输的总字节数 */
+    totalTransferredBytes: number;
+    /** 全局已传输的总大小（格式化字符串），如 "125.50 MB" */
+    transferredFormatSize: string;
+    lastLoadedMap: Map<any, any>;
+    plugins: IUDPlugin<T>[];
+    /** 插件间共享数据（如 MD5 计算结果等），由插件自行存取 */
+    pluginSharedData: Map<string, any>;
+    /** 全局待传输的总大小（格式化字符串），如 "256.80 MB" */
+    totalFormatSize: string;
+    /** 全局传输速率信息 (瞬时速度、平均速度等) */
+    speed: speedInfo;
+    /** 全局传输进度百分比 (0-100) */
+    totalPercent: number;
+    /** 是否处于加载/传输状态 */
+    loading: boolean;
+    /** 传输时间统计信息 (开始时间、结束时间、耗时) */
+    transferTime: TimeInfo;
+    /** 内部定时器 ID，用于防抖更新 */
+    __updateTimer__: number | undefined;
+    updateCallback: UpdateCallBack<T> | null | undefined;
+    onInitChunkCallback: onInitChunkCallback<T> | null;
+    OnMergeChunkCallBack: OnMergeChunkCallBack | null;
+    beforeTransferCallback: beforeTransferCallBack<T> | null | undefined;
+    static onError: ErrorCallBack;
+    successCallback: successCallback<D>;
+    /**
+     * 触发更新回调（requestAnimationFrame 防抖）
+     *
+     * 用 rAF 替代 setTimeout，确保同一帧内多次调用只执行一次，
+     * 多文件并发场景下所有文件的 Proxy set 共享同一个 rAF 调度。
+     * @private
+     */
+    triggerUpdate(): void;
+    /**
+     * 更新全局统计信息（内部方法）
+     * @private
+     */
+    updateGlobalStats(): void;
+    /**
+     * 重置上状态为初始值（统一重置逻辑）
+     * @private
+     */
+    resetState(): void;
+    set onUpdate(callback: UpdateCallBack<T>);
+    set onInitChunk(callback: onInitChunkCallback<T>);
+    set onMergeChunk(callback: OnMergeChunkCallBack);
+    set onSuccess(callback: successCallback<D>);
+    set onbeforeTransfer(callback: beforeTransferCallBack<T>);
+    /**
+     * 注册插件
+     * @param plugin 插件实例
+     * @param options 插件配置
+     */
+    use(plugin: IUDPlugin<T> | IUDPlugin<T>[], options?: any): this;
+    /**
+     * 移除插件
+     * @param name 插件名称
+     */
+    unuse(name: string): this;
+    /**
+     * 获取插件
+     * @param name 插件名称
+     */
+    getPlugin(name?: string): IUDPlugin<T> | IUDPlugin<T>[] | undefined;
+    /**
+     * 执行插件钩子
+     * @param hook 钩子名称
+     * @param args 参数
+     */
+    runHook<K extends keyof IUDPlugin>(hook: K, ...args: any[]): Promise<any[]>;
+    /**
+     * 计算全局上传速率(所有文件的聚合)
+     * @returns 全局速率对象
+     * @private
+     */
+    private calculateGlobalUploadSpeed;
+    /**
+     * 获取文件的已上传字节数（统一获取逻辑）
+     * @param file 文件实例
+     * @returns 已上传字节数
+     * @private
+     */
+    private getFileBytes;
+}
+
+declare class UploadChunkManager extends ChunkManager {
+    uploadFile: UploadFile;
+    uploadErrorFileCallBack: (() => void)[];
+    /**
+     * 初始化上传任务
+     */
+    constructor(ChunkOptions: ChunkOptions, file: UploadFile);
+    protected getTag(): string;
+    protected computeFileIdentifier(): Promise<string>;
+    protected doInit(): Promise<any>;
+    protected doChunkTransfer(chunkIndex: number, signal?: AbortSignal): Promise<{
+        data: any;
+        chunkSize: number;
+    }>;
+    protected doMergeChunks(): Promise<any>;
+    /**
+     * 计算文件MD5哈希值
+     * 优化: 使用与分片上传相同的 chunkSize,减少重复I/O
+     */
+    private computeFileHash;
+    private getFileHash;
+    /**
+     * 初始化上传
+     */
+    private initUpload;
+    /**
+     * 带重试机制的分片上传
+     */
+    private uploadChunkWithRetry;
+    /**
+     * 设置文件状态为失败（统一处理，避免重复代码）
+     */
+    protected setFileStatusToFail(): void;
+    /**
+     * 上传单个分片
+     */
+    private uploadChunk;
+    /**
+     * 合并所有分片
+     */
+    private mergeChunks;
+    /**
+     * 计算上传统计信息（统一处理，避免重复代码）
+     */
+    private calculateUploadStats;
+    /**
+     * 检查统计信息并触发合并
+     */
+    protected checkStatistics(): Promise<void>;
+    /**
+     * 处理所有分片成功的情况
+     */
+    protected handleAllChunksSuccess(): Promise<void>;
+    /**
+     * 处理失败分片的情况（自动重试）
+     */
+    protected handleFailedChunks(): Promise<void>;
+    /**
+     * 处理重试失败的情况（统一错误处理）
+     */
+    private handleRetryFailure;
+    /**
+     * 重试失败的分片
+     */
+    retryFailedChunks(): Promise<void>;
+    /**
+     * 取消上传
+     *
+     * 取消所有正在进行的分片上传任务，并清理相关资源。
+     * 与 pause 不同，cancel 会完全停止上传，无法恢复。
+     *
+     * @example
+     * ```typescript
+     * file.cancel();
+     * console.log(file.status); // "cancelled"
+     * ```
+     */
+    cancelUpload(): void;
+    /**
+     * 暂停上传
+     *
+     * 暂停所有正在进行的分片上传,但保持当前进度。
+     * 会等待当前活跃的分片完成后暂停新分片的启动。
+     *
+     * @example
+     * ```typescript
+     * file.pause();
+     * console.log(file.status); // "paused"
+     * ```
+     */
+    pause(): void;
+    /**
+     * 恢复上传
+     *
+     * 从暂停的位置继续上传分片。
+     *
+     * @example
+     * ```typescript
+     * file.resume();
+     * console.log(file.status); // "UDLoading"
+     * ```
+     */
+    resume(): Promise<void>;
+    /**
+     * 检查是否处于暂停状态
+     * @returns 是否暂停
+     */
+    getPaused(): boolean;
+    /**
+     * 获取失败分片的数量
+     * @returns 失败分片数量
+     */
+    getFailedChunksCount(): number;
+    /**
+     * 等待恢复（用于暂停/恢复机制）
+     * @private
+     */
+    protected waitForResume(): Promise<void>;
+    /**
+     * 更新上传进度
+     *
+     * ✅ 简单直接的进度计算：completedChunks / totalChunks * 100%
+     * completedChunks 只在分片真正上传成功时才累加
+     */
+    updateProgress(): void;
+    /**
+     * 计算并更新单个文件的上传速度
+     *
+     * 🔑 内联实现，每次分片完成时直接写入 proxy.speed，不做首次跳过也不做防抖。
+     *    分片上传本身是低频事件（间隔取决于分片大小/网速），不需要防抖反而会导致
+     *    相邻调用间的 speed 值振荡。（calculateSpeed 的 100ms 防抖适用于 XHR progress
+     *    高频回调场景，但对分片上传反而有害。）
+     *
+     * 💡 瞬时速度在首次调用时为 0（无上次采样可比较），从第二次起有真实值。
+     *    平均速度基于 chunkStartTime，首轮即有效（虽然包含了 hash 开销会偏低，
+     *    但这在几次分片后即趋于稳定，比跳变好得多）。
+     */
+    private updateChunkUploadSpeed;
+    startUpload(): Promise<void>;
+    /**
+     * 使用信号量控制并发上传
+     */
+    protected uploadWithConcurrency(): Promise<void>;
+}
+
+/**
+ * XHR 拦截器配置
+ */
+interface XHRInterceptorConfig<T> {
+    /** 拦截器名称（用于日志） */
+    name: string;
+    /** 获取文件队列的方法 */
+    getFileQueue: () => T[];
+    /** 获取全局 headers 的方法 */
+    getGlobalHeaders: (file: T) => Record<string, string> | undefined;
+    /** 处理进度事件的方法 */
+    onProgress: (file: T, event: ProgressEvent) => void;
+    /** 设置 abort 方法（可选） */
+    setupAbort?: (file: T, xhr: XMLHttpRequest) => void;
+    /** 标记文件已分配（可选） */
+    markFileAsAssigned?: (file: T) => void;
+    /** 从 XHR 获取文件实例的方法 */
+    getFileFromXHR?: (xhr: XMLHttpRequest) => T | null;
+    /** 设置 XHR 与文件的映射 */
+    setFileToXHR?: (xhr: XMLHttpRequest, file: T) => void;
+    /** 设置 abort 方法 */
+    onAbort?: (file: T, xhr: XMLHttpRequest) => void;
+    /** 取消标记文件 */
+    unmarkFileAsAssigned: (file: T) => void;
+}
+/**
+ * 全局 XHR 拦截器管理器
+ */
+declare class XHRInterceptor<T extends TransferFile<T>> {
+    private config;
+    private static instances;
+    private isInstalled;
+    private originalXHR;
+    private xhrToFileMap;
+    private assignedFiles;
+    constructor(config: XHRInterceptorConfig<T>);
+    /**
+     * 获取或创建拦截器实例（单例模式）
+     */
+    static getInstance<T extends TransferFile<T>>(name: string, config: XHRInterceptorConfig<T>): XHRInterceptor<T>;
+    /**
+     * 添加文件到已分配集合
+     */
+    private markAsAssigned;
+    /**
+     * 从 XHR 获取关联的文件
+     */
+    private getFileFromXHR;
+    /**
+     * 设置 XHR 与文件的映射
+     */
+    private setFileToXHR;
+    /**
+     * 安装拦截器（全局只安装一次）
+     */
+    install(): void;
+    /**
+     * 恢复原始 XHR
+     */
+    restore(): void;
+    /**
+     * 清理文件（文件完成时调用）
+     */
+    cleanupFile(file: T): void;
+}
+
+/**
+ * 文件传输实例类
+ * 负责单个文件的上传逻辑、状态管理、速率计算和生命周期控制
+ *
+ * @template T - 上传成功后的响应数据类型
+ */
+declare class UploadFile<T = any> extends TransferFile<UploadFile, T> {
+    up: Uploader<T>;
+    /**
+     * 🔑 文件创建时保存 action 快照，防止切换模式后重试时用到错误的 action
+     */
+    private _action;
+    /**
+     * 分片管理器实例
+     * 每个文件拥有独立的 uploadChunkManager,实现并发控制、断点续传和失败隔离
+     */
+    uploadChunkManager: UploadChunkManager | null;
+    static interceptor: XHRInterceptor<UploadFile>;
+    /**
+     * 全局共享的 WeakMap
+     * 用于存储 XHR 实例与文件上下文的映射关系,支持拦截器透明注入
+     */
+    private static xhrToFileMap;
+    /**
+     * 全局共享的当前上传文件队列
+     * 用于在拦截器中查找匹配的 FormData
+     */
+    private static currentQueue;
+    /**
+     * 跟踪已分配到 XHR 的文件集合
+     * 用于按顺序分配 XHR 实例,避免冲突
+     */
+    private static assignedFiles;
+    constructor(file: IFile, transfer: Transfer);
+    /**
+     * 从回显数据初始化 uploadChunkManager 状态
+     * 用于后端接口返回的文件列表回显场景
+     *
+     * @param file - 包含分片上传信息的文件对象
+     */
+    private initChunkManagerFromRestore;
+    /**
+     * 执行普通上传的重试（模板方法覆写）
+     */
+    protected doRetryTransfer(): Promise<T>;
+    remove(): void;
+    setFile(file: File | Blob, formData: FormData, index?: number): void;
+    /**
+     * 上传文件（支持普通上传和分片上传）
+     *
+     * @param onChunkComplete - 分片上传完成时的回调函数
+     * @param signal - AbortSignal，用于取消请求（超时控制）
+     * @param chunkFormData - 分片上传的 FormData（可选，优先使用此参数而不是 this.formData）
+     * @returns Promise<T>
+     */
+    upload(onChunkComplete?: (res: T) => void, signal?: AbortSignal, chunkFormData?: FormData): Promise<T>;
+    /**
+     * 返回上传的分片管理器
+     */
+    protected getChunkManager(): ChunkManager | null;
+    /**
+     * 获取文件大小（上传场景：直接用 File.size）
+     */
+    getFileSize(): number;
+    /**
+     * 更新当前文件的上传进度和已传输字节数（模板方法）
+     *
+     * 根据上传类型采用不同的进度计算策略：
+     * - 普通上传：从 event.loaded/event.total 直接计算百分比和字节数
+     * - 分片上传：由 uploadChunkManager 独立维护进度，此处无需额外操作
+     */
+    protected updateLocalProgress(event: ProgressEvent): void;
+}
+
+declare class Uploader<T = any> extends Transfer<UploadFile, T> {
+    inputHTML: HTMLInputElement | null;
+    static objectUrls: any[];
+    static baseConfig: UploaderConfig;
+    config: UploaderConfig | null;
+    static instances: Uploader | null;
+    static uploadFile: UploadFile | null;
+    static isInterceptorInstalled: boolean;
+    totalPercent: number;
+    static fileIndex: number;
+    static originalXHR?: typeof XMLHttpRequest | null;
+    static interceptorActive: boolean;
+    private static defaultPlugins;
+    openCallBack: OpenFileCallback;
+    selectCallback: SelectCallBack | null | undefined;
+    clearFiles(): void;
+    /**
+     * 设置全局默认插件（影响之后创建的所有实例）
+     */
+    static setDefaultPlugins(plugins: IUDPlugin<UploadFile>[]): void;
+    /**
+     * 设置文件列表（用于回显已上传的文件）
+     * @param files - 要回显的文件列表，可以是 UploadFile 实例或文件信息对象
+     * @example
+     * ```typescript
+     * //从服务端获取文件列表后回显
+     * const savedFiles = await fetchSavedFiles();
+     * uploader.setFiles(savedFiles.map(fileInfo => ({
+     *   fileId: fileInfo.id,
+     *   fileName: fileInfo.name,
+     *   url: fileInfo.url,
+     *   size: fileInfo.size,
+     *   percent: 100,
+     *   status: 'success',
+     *   formatSize: formatFileSize(fileInfo.size)
+     * })));
+     *
+     */
+    setFiles(files: IFile[]): void;
+    constructor(config?: UploaderConfig);
+    /**
+     * @description: 打开文件
+     * @param {OpenFileCallback} fn
+     * @return {*}
+     */
+    open(fn?: OpenFileCallback): any;
+    private init;
+    private createInput;
+    create(config?: UploaderConfig): this;
+    updateConfig(config: Partial<UploaderConfig>): void;
+    set onbeforeTransfer(callback: beforeTransferCallBack<UploadFile>);
+    set onSelect(callback: SelectCallBack);
+    remObjectUrls(url: string): void;
+    cancelAll(): void;
+    pauseAll(): void;
+    resumeAll(): void;
+    retryAll(): void;
+    /**
+     * @description: 手动提交上传所有文件（当 autoUpload 为 false 时）
+     * @return {Promise<void>}
+     */
+    submit(): Promise<void>;
+    /**
+     * 验证文件是否符合上传条件（统一验证逻辑）
+     * @param file 原始文件对象
+     * @param uploadFileInstance 上传文件实例
+     * @returns 验证结果 { valid: boolean, error?: any }
+     * @private
+     */
+    private validateFile;
+    /**
+     * 处理文件选择（内部方法）
+     */
+    private processSelectedFiles;
+}
+
+/**
+ * 错误码枚举（所有可能的错误）
+ */
+declare enum ErrorCode {
+    /** 未知错误 */
+    UNKNOWN = 1000,
+    /** 操作已中止 */
+    ABORTED = 1001,
+    /** 请求超时 */
+    TIMEOUT = 1002,
+    /** 网络错误 */
+    NETWORK = 1003,
+    /** 文件过大 */
+    FILE_TOO_LARGE = 2000,
+    /** 文件过小 */
+    FILE_TOO_SMALL = 2001,
+    /** 文件类型无效 */
+    INVALID_TYPE = 2002,
+    /** 文件数量超限 */
+    FILE_LIMIT_EXCEEDED = 2003,
+    /** 重复的文件 */
+    DUPLICATE_FILE = 2004,
+    /** 文件为空 */
+    FILE_EMPTY = 2005,
+    /** 文件已损坏 */
+    FILE_CORRUPTED = 2006,
+    /** 文件过于空泛（可能缺少必要内容） */
+    FILE_TOO_EMPTY = 2007,
+    /** 图片宽度不符合要求 */
+    IMAGE_WIDTH_INVALID = 2100,
+    /** 图片高度不符合要求 */
+    IMAGE_HEIGHT_INVALID = 2101,
+    /** 图片宽高比不符合要求 */
+    IMAGE_ASPECT_RATIO_INVALID = 2102,
+    /** 图片分辨率不符合要求 */
+    IMAGE_RESOLUTION_INVALID = 2103,
+    /** 图片不是正方形 */
+    IMAGE_NOT_SQUARE = 2104,
+    /** 不支持动态图片 */
+    IMAGE_ANIMATED = 2105,
+    /** 视频时长不符合要求 */
+    VIDEO_DURATION_INVALID = 2200,
+    /** 视频宽度不符合要求 */
+    VIDEO_WIDTH_INVALID = 2201,
+    /** 视频高度不符合要求 */
+    VIDEO_HEIGHT_INVALID = 2202,
+    /** 视频比特率不符合要求 */
+    VIDEO_BITRATE_INVALID = 2203,
+    /** 视频编码格式不支持 */
+    VIDEO_CODEC_INVALID = 2204,
+    /** 上传失败 */
+    UPLOAD_FAILED = 3000,
+    /** 分片上传失败 */
+    CHUNK_UPLOAD_FAILED = 3001,
+    /** 合并分片失败 */
+    MERGE_FAILED = 3002,
+    /** 服务器错误 */
+    SERVER_ERROR = 3003,
+    /** 未授权访问 */
+    UNAUTHORIZED = 3004,
+    /** 禁止访问 */
+    FORBIDDEN = 3005,
+    /** 资源不存在 */
+    NOT_FOUND = 3006,
+    /** 下载失败 */
+    DOWNLOAD_FAILED = 4000,
+    /** 分片下载失败 */
+    CHUNK_DOWNLOAD_FAILED = 4001,
+    /** 插件错误 */
+    PLUGIN_ERROR = 5000,
+    /** 插件初始化失败 */
+    PLUGIN_INIT_FAILED = 5001,
+    /** 插件执行失败 */
+    PLUGIN_EXECUTION_FAILED = 5002
+}
+/**
+ * 错误级别
+ */
+declare enum ErrorLevel {
+    INFO = "info",// 提示信息，不影响流程
+    WARNING = "warn",// 警告，但继续执行
+    ERROR = "error",// 错误，中断当前操作
+    CRITICAL = "critical"
+}
+/**
+ * 错误上下文（包含现场信息）
+ */
+interface ErrorContext {
+    /** 发生时间 */
+    timestamp?: number;
+    /** 插件名称 */
+    plugin?: string;
+    /** 上传器实例 */
+    uploader?: Uploader;
+    options?: Record<string, any>;
+    /** 文件名 */
+    fileName?: string;
+    /** 文件大小 */
+    fileSize?: number;
+    /** 分片索引 */
+    chunkIndex?: number;
+    /** HTTP 状态码 */
+    httpStatus?: number;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 原始错误 */
+    originalError?: any;
+    /** 自定义字段 */
+    [key: string]: any;
+}
+/**
+ * 错误配置
+ */
+interface ErrorOptions {
+    /** 是否可恢复 */
+    recoverable?: boolean;
+    /** 是否自动重试 */
+    retryable?: boolean;
+    /** 建议操作 */
+    suggestion?: string;
+    /** 是否显示给用户 */
+    userVisible?: boolean;
+    /** 国际化key */
+    i18nKey?: string;
+}
+interface FileUDErrorJSON {
+    name: string;
+    code: ErrorCode;
+    level: ErrorLevel;
+    message: string;
+    context: ErrorContext;
+    options: ErrorOptions;
+    stack?: string;
+}
+
+/**
+ * 文件下载器类 (Downloader)
+ *
+ * 继承自 Transfer，专门处理文件下载相关的业务逻辑。
+ * 回调属性（successCallback / updateCallback / onInitChunkCallback / OnMergeChunkCallBack /
+ * beforeTransferCallback）及其 setter 全部由 Transfer 基类提供，此处不再重复声明。
+ */
+declare class Downloader<T = any> extends Transfer<DownloadFile, T> {
+    /** 全局基础配置 */
+    static baseConfig: DownloaderConfig;
+    /** 当前实例的配置信息 */
+    config: DownloaderConfig | null;
+    static instances: Downloader | null;
+    static fileIndex: number;
+    /** 静态默认插件（影响之后创建的所有实例） */
+    private static defaultPlugins;
+    constructor(config?: DownloaderConfig);
+    /**
+     * 动态更新配置
+     * @param config 部分配置项
+     */
+    updateConfig(config: Partial<DownloaderConfig>): void;
+    /**
+     * 创建下载器实例（多例模式支持）
+     * @param config 下载器配置
+     * @returns Downloader 实例
+     */
+    create(config?: DownloaderConfig): this;
+    /**
+     * 设置全局默认插件（影响之后创建的所有实例）
+     */
+    static setDefaultPlugins(plugins: IUDPlugin<DownloadFile>[]): void;
+    /**
+     * 初始化实例插件列表（继承全局默认插件）
+     */
+    private init;
+    /**
+     * 🔑 文件名 → FileSystemFileHandle 缓存
+     *
+     * 用途：避免重复调用 showSaveFilePicker() 截断已存在的文件。
+     * Chrome 的 showSaveFilePicker() 在用户选择覆盖同名文件时会直接截断文件为 0 字节，
+     * 导致"秒下"检测失败。缓存句柄后，二次下载同一文件直接复用句柄。
+     *
+     * ⚠️ 挂载在 window 上而非 static Map：Vite HMR 会重置模块级静态变量，
+     *    但 window 上的属性不受影响，保证开发模式下缓存不丢失。
+     *    页面全量刷新后缓存自然清空，功能不受影响（回退到正常下载）。
+     */
+    private static get fileHandleCache();
+    /**
+     * 静态方法：打开系统"另存为"对话框，获取流式写入 FileHandle
+     *
+     * 使用 File System Access API（Chrome 86+, Edge 86+）。
+     * 如果 API 不可用，返回 undefined（调用方应回退到 Blob 下载模式）。
+     *
+     * 🔑 如果当前会话中已下载过同名文件，直接复用缓存的 handle，
+     *    避免 showSaveFilePicker() 截断已有文件。
+     *
+     * @param suggestedName 建议的文件名
+     * @returns FileHandle（用户选择后），null（用户取消），undefined（API 不可用）
+     */
+    static pickSaveFile(suggestedName?: string): Promise<FileSystemFileHandle | null | undefined>;
+    /**
+     * 添加下载任务并立即开始下载
+     * @param file 下载文件配置
+     * @param fileHandle 可选，File System Access API 的 FileHandle（流式保存用）
+     * @returns DownloadFile 实例
+     */
+    downloadFile(file: UDFile, fileHandle?: FileSystemFileHandle): DownloadFile<T>;
+    /**
+     * 提交所有待下载文件（自动调用所有文件 start 方法）
+     */
+    submit(): void;
+    /**
+     * 取消所有下载任务
+     */
+    cancelAll(): void;
+    /**
+     * 暂停所有下载任务
+     */
+    pauseAll(): void;
+    /**
+     * 恢复所有下载任务
+     */
+    resumeAll(): Promise<void>;
+    /**
+     * 移除所有下载任务（取消进行中的下载并清空列表）
+     */
+    removeAll(): void;
+    /**
+     * 重试所有失败/取消的下载任务
+     */
+    retryAll(): Promise<void>;
+    /**
+     * 保存 Blob 到本地（触发浏览器下载对话框）
+     * @param fileName 文件名
+     * @param data Blob 数据或可转为 Blob 的数据
+     */
+    static saveBlob(fileName: string, data: any): void;
+    /**
+     * 通过 URL 下载并保存文件到本地（触发浏览器下载对话框）
+     * @param fileName 文件名
+     * @param url 下载链接
+     */
+    static saveFile(fileName: string, url: string): Promise<void>;
+}
+
+/**
+ * 文件传输接受类型定义
+ * 支持常见的 MIME 类型、通配符和文件后缀名
+ */
+type AcceptFileType = "image/*" | "image/jpeg" | "image/png" | "image/gif" | "image/webp" | "image/svg+xml" | "image/bmp" | "image/tiff" | "video/*" | "video/mp4" | "video/webm" | "video/ogg" | "video/quicktime" | "audio/*" | "audio/mp3" | "audio/wav" | "audio/ogg" | "audio/aac" | "audio/flac" | "application/pdf" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/zip" | "application/x-rar-compressed" | "application/x-7z-compressed" | "text/plain" | "text/csv" | "text/html" | "text/css" | "text/javascript" | "application/json" | "application/xml" | "font/woff" | "font/woff2" | "font/ttf" | "font/otf" | ".jpg" | ".jpeg" | ".png" | ".gif" | ".webp" | ".svg" | ".bmp" | ".tiff" | ".ico" | ".heic" | ".heif" | ".raw" | ".psd" | ".ai" | ".eps" | ".mp4" | ".webm" | ".ogg" | ".avi" | ".mov" | ".wmv" | ".flv" | ".mkv" | ".m4v" | ".mpeg" | ".mpg" | ".3gp" | ".rmvb" | ".rm" | ".mp3" | ".wav" | ".flac" | ".aac" | ".wma" | ".m4a" | ".ape" | ".opus" | ".aiff" | ".mid" | ".midi" | ".pdf" | ".doc" | ".docx" | ".xls" | ".xlsx" | ".ppt" | ".pptx" | ".txt" | ".md" | ".csv" | ".rtf" | ".odt" | ".ods" | ".odp" | ".wps" | ".et" | ".dps" | ".json" | ".xml" | ".html" | ".htm" | ".css" | ".scss" | ".sass" | ".less" | ".js" | ".jsx" | ".ts" | ".tsx" | ".vue" | ".py" | ".java" | ".c" | ".cpp" | ".h" | ".hpp" | ".go" | ".rs" | ".php" | ".rb" | ".swift" | ".kt" | ".yaml" | ".yml" | ".toml" | ".ini" | ".sql" | ".sh" | ".bat" | ".ps1" | ".zip" | ".rar" | ".7z" | ".tar" | ".gz" | ".bz2" | ".xz" | ".tgz" | ".iso" | ".ttf" | ".otf" | ".woff" | ".woff2" | ".eot" | ".apk" | ".ipa" | ".exe" | ".msi" | ".dmg" | ".pkg";
+interface ChunkOptions {
+    maxConcurrent?: number;
+    chunkSize?: number;
+    retries?: number | null;
+    retryDelay?: number;
+    timeout?: number;
+    enableFileCache?: boolean;
+    cacheRetentionDays?: number;
+}
+type FileConfig = {
+    data: File | Blob;
+    uploadFile: UploadFile;
+    formData: FormData;
+    chunkIndex?: number;
+};
+interface UDConfig<T = any> {
+    chunkOptions?: ChunkOptions | null;
+    axiosInstance?: AxiosInstance;
+    limit?: number;
+    maxSize?: number;
+    headers?: Record<string, any>;
+    /** 最大同时传输文件数，0 或不设置表示不限制 */
+    maxFileConcurrent?: number;
+}
+interface UploaderConfig extends UDConfig<UploadFile> {
+    multiple?: boolean;
+    accept?: AcceptFileType[] | string[];
+    show?: false;
+    elementId?: string;
+    autoUpload?: boolean;
+    /**
+     * 文件传输下载地址，可以是字符串或者promise函数
+     * @return {Promise}
+     */
+    action: string | ((formData: FormData, transferFile: UploadFile) => string | Promise<any>);
+    file?: string | ((FileConfig: FileConfig) => void);
+}
+/**
+ * 下载器配置
+ */
+interface DownloaderConfig extends UDConfig<DownloadFile> {
+    /** 默认超时时间 */
+    timeout?: number;
+    /**
+     * 文件传输下载地址，可以是字符串或者promise函数
+     * @return {Promise}
+     */
+    action: string | ((transferFile: DownloadFile) => string | Promise<any>);
+    axiosOptions?: AxiosRequestConfig;
+    /** 下载最大速率限制（bytes/秒），0 或不设置表示不限制 */
+    maxDownloadSpeed?: number;
+}
+interface PluginContext<T extends TransferFile<any, any> = TransferFile<any, any>> {
+    /** 传输器实例（Uploader 或 Downloader） */
+    transfer: Transfer<T>;
+    /** 当前文件 */
+    file?: T;
+    /** 表单数据（上传专用） */
+    formData?: FormData;
+    /** 配置信息 */
+    config?: any;
+    /** 插件共享数据 */
+    shared: Map<string, any>;
+    /** 当前操作状态（用于区分MD5计算、上传中等不同阶段） */
+    status?: IFile["status"];
+    /** 状态描述信息（可选，用于显示给用户） */
+    message?: string;
+}
+interface IUDPlugin<T extends TransferFile<any, any> = TransferFile<any, any>> {
+    /** 插件名称 */
+    name: string;
+    /** 插件版本 */
+    version?: string;
+    desc?: string;
+    /** 插件优先级（数字越小越先执行） */
+    priority?: number;
+    /** 插件初始化（注册时调用一次） */
+    install?: (transfer: Transfer<T>, options?: any) => void | Promise<void>;
+    created?: (transfer: Transfer<T>) => void | Promise<void>;
+    /** 文件选择后触发 */
+    onFileSelect?: (file: T, context: PluginContext<T>) => Promise<T | void | false> | T | void;
+    /** 传输前触发 */
+    beforeTransfer?: (file: T, context: PluginContext<T>) => Promise<boolean | void> | boolean | void;
+    /** 传输进度触发 */
+    onProgress?: (percent: number, file: T, context: PluginContext<T>) => void;
+    /** 传输成功触发 */
+    onSuccess?: (response: any, file: T, context: PluginContext<T>) => void;
+    /** 传输失败触发 */
+    onError?: (error: Error, file: T, context: PluginContext<T>) => void;
+    /** 插件销毁时调用 */
+    destroy?: () => void;
+}
+interface UDFile {
+    fileId?: string;
+    url: string;
+    fileName: string;
+    size?: number;
+    fileHandle?: FileSystemFileHandle;
+    status?: "pending" | "UDLoading" | "paused" | "success" | "fail" | "error" | "cancelled" | "merging" | "hashing";
+}
+interface IFile extends UDFile {
+    percent?: number;
+    extension?: string;
+    File?: File;
+    loading?: boolean;
+    hashLoading?: boolean;
+    hashPercent?: number;
+    isCancel?: boolean;
+    formatSize?: string;
+    abort?: () => void;
+    isRetry?: boolean;
+    index?: number;
+    metadata?: Record<string, any>;
+    speed?: speedInfo;
+    totalChunks?: number;
+    completedChunks?: number;
+    chunkIndexes?: number[];
+    fileHash?: string;
+    uploadId?: string;
+}
+/**
+ * 下载文件接口
+ */
+interface IDownloadFile extends Omit<IFile, "transfer"> {
+    saveFileName?: string;
+    useBlob?: boolean;
+    __downloader__?: Downloader;
+}
+type ErrorCallBack = (errors: FileUDErrorJSON) => void;
+type beforeTransferCallBack<T extends TransferFile<any, any>> = (file: T) => boolean | Promise<Boolean> | undefined | null | {
+    [key: string]: any;
+};
+type successCallback<T> = (response: T, file: TransferFile<any, any>) => void;
+type UpdateCallBack<T = any> = (file: T[]) => void;
+type onInitChunkCallback<T> = (file: T, totalChunks: number, fileHash: string) => Promise<{
+    fileHash: string;
+    chunks?: number[] | null | undefined;
+    isInstantUpload?: boolean;
+    isInstantDownload?: boolean;
+    url?: string;
+    shouldRemove?: boolean;
+}> | undefined;
+type OnMergeChunkCallBack = (chunkManager: UploadChunkManager) => Promise<any>;
+type OpenFileCallback = (uploadFile: UploadFile) => void;
+type SelectCallBack = (file: File) => boolean | Promise<Boolean> | undefined | null;
+/**
+ * 分片事件数据辅助类型（上传/下载共用）
+ */
+interface ChunkStartData<T = TransferFile<any, any>> {
+    file: T;
+    totalChunks: number;
+    chunkSize: number;
+}
+interface ChunkSuccessData<T = TransferFile<any, any>> {
+    chunkIndex: number;
+    totalChunks: number;
+    completedChunks: number;
+    percent: number;
+    file: T;
+}
+interface ChunkErrorData<T = TransferFile<any, any>> {
+    chunkIndex: number;
+    totalChunks: number;
+    error: string;
+    file: T;
+}
+/**
+ * 基础传输事件接口（上传/下载共用）
+ *
+ * 注意：error 和 update 未纳入基类，因为上传/下载的签名完全不同：
+ *   - Uploader.error = (errors: FileUDErrorJSON) => void
+ *   - Downloader.error = (error: Error, file: DownloadFile) => void
+ */
+interface BaseTransferEvents<T = TransferFile<any, any>> {
+    change: (file: T) => void;
+    progress: (percent: number) => void;
+    pause: (file: T) => void;
+    resume: (file: T) => void;
+    cancel: (file: T) => void;
+    retry: (file: T) => void;
+    remove: (file: T) => void;
+    "files-start": (files: T[]) => void;
+    "files-complete": (files: TransferFile<any, any>[]) => void;
+    "chunk-success": (data: ChunkSuccessData<T>) => void;
+    "chunk-error": (data: ChunkErrorData<T>) => void;
+    merging: (data: {
+        file: T;
+        completedChunks: number;
+        totalChunks: number;
+    }) => void;
+    "merge-success": (data: {
+        file: T;
+        response?: any;
+    }) => void;
+    "merge-error": (data: {
+        file: T;
+        error: string;
+    }) => void;
+}
+interface UploaderEvents extends BaseTransferEvents<UploadFile> {
+    select: (file: File) => boolean;
+    update: (uploaderFile: UploadFile[]) => void;
+    error: ErrorCallBack;
+    "chunk-upload-start": (data: ChunkStartData<UploadFile>) => void;
+    "instant-upload": (data: {
+        file: UploadFile;
+        reason: string;
+    }) => void;
+}
+type EventName = keyof UploaderEvents;
+type EventCallback<T extends EventName> = UploaderEvents[T];
+/**
+ * 上传速率统计信息接口
+ * 用于描述单个文件或全局的上传速度指标
+ */
+interface speedInfo {
+    /** 当前瞬时速度 (bytes/s) - 基于最近两个采样点计算 */
+    currentSpeed: number;
+    /** 平均速度 (bytes/s) - 基于总耗时和总字节数计算 */
+    averageSpeed: number;
+    /** 格式化后的当前速度,如 "15.23 MB/s"、"256 KB/s" */
+    currentSpeedFormatted: string;
+    /** 格式化后的平均速度,如 "12.45 MB/s"、"128 KB/s" */
+    averageSpeedFormatted: string;
+    /** 预计剩余时间（秒），-1 表示无法计算，0 表示即将完成 */
+    estimatedTimeRemaining: number;
+    /** 格式化后的预计剩余时间，如 "3m 20s"、"12s"、"即将完成" */
+    estimatedTimeFormatted: string;
+}
+/**
+ * 上传时间统计信息接口
+ * 记录文件传输的生命周期时间节点
+ */
+interface TimeInfo {
+    /** 开始时间戳 (毫秒) */
+    startTime: number;
+    /** 结束时间戳 (毫秒) */
+    endTime: number;
+    /** 总耗时 (毫秒) */
+    duration: number;
+    /** 格式化后的耗时,如 "5.23s"、"1m 30s"、"2h 15m" */
+    durationFormatted: string;
+}
+
+declare class DownloadChunkManager extends ChunkManager {
+    private downloadFile;
+    /** 存储每个分片的 Blob 数据（流式写入不可用时的内存兜底） */
+    private chunkBlobs;
+    /** 流式写入的 FileHandle（File System Access API） */
+    private streamFileHandle;
+    /** 流式写入的可写流 */
+    private writable;
+    /** 待完成写入的 Promise 列表（fire-and-forget，不阻塞 PQueue worker） */
+    private pendingWrites;
+    /** 🔑 已确认落盘的分片索引（仅流式模式使用，内存模式不写此 Set） */
+    private _diskWrittenChunks;
+    /** 🔑 doAfterStartReset() 保存 IndexedDB 时的安全快照。
+     *    ensureWritableClosed() 的 pending writes 会追加新分片到 _diskWrittenChunks，
+     *    若 close() 失败 → abort() → 磁盘数据丢失，需要回滚 IndexedDB 到这个安全状态，
+     *    而不是全量删除。已 settle 的 writes 在磁盘上是安全的。 */
+    private _safeDiskChunks;
+    /** 上次写入 IndexedDB 进度的时间戳（节流用） */
+    private _lastProgressSaveTime;
+    constructor(chunkOptions: ChunkOptions, file: TransferFile<any, any>);
+    protected getTag(): string;
+    /**
+     * 计算文件唯一标识
+     *
+     * - 若 this.fileHash 已设置（服务端返回的真实 MD5），直接返回
+     * - 否则兜底用 fileName-fileSize，仅作为 onInitChunk → check-file 的临时传参
+     */
+    protected computeFileIdentifier(): Promise<string>;
+    /**
+     * 初始化下载任务（含断点续传 / 秒下检查）
+     *
+     * 1. 调用 onInitChunkCallback 检查已下载分片（断点续传 / 秒下）
+     * 2. 如果用户提供了 fileHandle 直接使用；否则尝试调用 showSaveFilePicker
+     *    让用户选择保存位置，实现流式写入磁盘（内存峰值 = 并发数 × 分片大小）。
+     * 3. 若 API 不可用或用户取消，回退到内存累积模式。
+     */
+    protected doInit(): Promise<any>;
+    /**
+     * 标记为秒下（instant download），设置所有状态为已完成
+     */
+    private markInstantDownload;
+    /**
+     * 下载单个分片（Range 请求）
+     */
+    protected doChunkTransfer(chunkIndex: number, signal?: AbortSignal): Promise<{
+        data: Blob;
+        chunkSize: number;
+    }>;
+    /**
+     * 合并所有已下载分片
+     *
+     * - 流式模式：等待所有 fire-and-forget 写入完成后关闭 writable
+     * - 内存模式：将 chunkBlobs Map 中的分片按顺序拼接为单一 Blob
+     */
+    protected doMergeChunks(): Promise<Blob | FileSystemFileHandle>;
+    /**
+     * 保存每个分片的 Blob 数据 + 自动缓存下载进度到 IndexedDB
+     *
+     * - 流式模式：fire-and-forget 写入（不 await，PQueue worker 立即继续下载下一个分片）
+     * - 内存模式：存储到 chunkBlobs Map 中，待合并时一次性拼接
+     *
+     * 🔑 IndexedDB 安全性：仅当磁盘写入确认完成后才保存进度。避免 cancel 时
+     *    write 尚未 flush → close() 未保住数据 → abort() 丢弃 → IndexedDB 却标记"已完成"
+     *    → 重试时跳过这些分片 → 文件出现空洞损坏。
+     */
+    protected doSaveChunkResult(chunkIndex: number, data: any): Promise<void>;
+    /**
+     * 将下载进度存入 IndexedDB（节流，最多每 2 秒写一次）
+     *
+     * 🔑 流式模式：仅保存 _diskWrittenChunks 中已确认落盘的分片，防止
+     *    cancel→abort 丢弃数据后 IndexedDB 仍标记"已完成"→重试跳过→文件损坏。
+     *    内存模式：chunkBlobs Map 存于内存，cancel 不丢数据，直接用 this.chunks[]。
+     */
+    private saveProgressToCacheSoft;
+    /**
+     * 合并完成后保存文件
+     *
+     * - 流式模式：文件已在写入流关闭时落盘，无需额外操作
+     * - 内存模式：如果有 fileHandle 则流式写入，否则触发浏览器下载对话框
+     */
+    protected doBeforeOnSuccess(mergeResult: any): Promise<void>;
+    /**
+     * start() 重置后清理之前的 Blob 缓存和流式写入状态
+     *
+     * 🔑 在此处将 _diskWrittenChunks 保存到 IndexedDB，但 NOT clear()。
+     *    clear() 推迟到 ensureWritableClosed() 的最终保存完成后执行：
+     *    - doAfterStartReset() 保存时，_diskWrittenChunks 含已 settle 的分片
+     *    - ensureWritableClosed() 等待 pending writes → 新 settle 的分片被
+     *      .then() 加入 _diskWrittenChunks → 最终保存含完整集合 → 覆盖写入 ✅
+     *    - 如果 doAfterStartReset() 就 clear()，最终保存只剩几个零碎分片 → 覆盖掉
+     *      刚刚保存的完整记录 → 进度倒退 ❌
+     */
+    protected doAfterStartReset(): Promise<void>;
+    /**
+     * 异步清理：关闭上次的 writable，释放文件锁。
+     *
+     * ⚠️ 必须 await 调用，确保 writable 完全关闭、文件锁释放后，
+     *    doInit() 才能安全调用 createWritable()，否则会因锁冲突抛 InvalidStateError。
+     *
+     * 🔑 竞态修复：先置 null this.writable，再异步 close。
+     *    否则旧 PQueue 残留的 doSaveChunkResult 回调会在 close() 进行中
+     *    检查 if (this.writable) → 仍为非 null → writable.write() 写入正在关闭的流
+     *    → 浏览器抛出 "Cannot write to a closing writable stream"。
+     *
+     * 🔑 数据安全：先等待 pendingWrites 全部 settle → write.then() 中会更新
+     *    _diskWrittenChunks → 再 close() flush 缓冲区 → 磁盘数据完整。
+     *    若 close() 失败退化为 abort()，磁盘数据丢失，必须同步清理 IndexedDB。
+     */
+    ensureWritableClosed(): Promise<void>;
+}
+
+/**
+ * 文件下载实例类
+ * 负责单个文件的下载逻辑、状态管理、速率计算和生命周期控制
+ *
+ * @template T - 下载成功后的响应数据类型
+ */
+declare class DownloadFile<T = any> extends TransferFile<DownloadFile, T> {
+    /**
+     * 分片管理器实例
+     * 每个文件拥有独立的 downloadChunkManager,实现并发控制、断点续传和失败隔离
+     */
+    downloadChunkManager: DownloadChunkManager | null;
+    dl: Downloader<T>;
+    /**
+     * 🔑 文件创建时保存 action 快照，防止切换模式后重试时用到错误的 action
+     */
+    private _action;
+    /**
+     * 流式保存的 FileHandle（File System Access API）
+     * 如果设置了 fileHandle，下载完成后通过流式写入文件，不触发浏览器下载对话框
+     */
+    fileHandle: FileSystemFileHandle | null | undefined;
+    /**
+     * 分片下载专用 headers 队列（如 Range）
+     * 并发分片各自 push，拦截器 shift 取走，避免并发覆盖导致 Range 头错乱
+     * 函数 action 下，用户不需要手动处理分片 headers
+     */
+    _chunkHeadersQueue: Record<string, string>[];
+    static interceptor: XHRInterceptor<DownloadFile>;
+    /**
+     * 全局共享的 WeakMap
+     * 用于存储 XHR 实例与文件上下文的映射关系,支持拦截器透明注入
+     */
+    private static xhrToFileMap;
+    /**
+     * 全局共享的当前下载文件队列
+     * 用于在拦截器中查找匹配的 XHR
+     */
+    private static currentQueue;
+    /**
+     * 跟踪已分配到 XHR 的文件集合
+     * 用于按顺序分配 XHR 实例,避免冲突
+     */
+    private static assignedFiles;
+    constructor(file: IDownloadFile, transfer: Transfer);
+    /**
+     * 执行普通下载的重试（模板方法覆写）
+     */
+    protected doRetryTransfer(): Promise<T>;
+    /**
+     * 从回显数据初始化 downloadChunkManager 状态
+     */
+    private initChunkManagerFromRestore;
+    /**
+     * 执行下载
+     */
+    download(): Promise<T>;
+    /**
+     * 更新当前文件的下载进度和已传输字节数（模板方法）
+     *
+     * - 普通下载：从 event.loaded/event.total 直接计算百分比和字节数
+     * - 分片下载：由 downloadChunkManager 独立维护进度，此处无需额外操作
+     *
+     * 当响应没有 Content-Length 头（event.total === 0）时：
+     * - __transferBytes__ 使用 event.loaded 记录实际已下载字节数
+     * - 百分比无法精确计算，使用基于 loaded 的模拟进度（0~99%），完成时跳到 100%
+     */
+    protected updateLocalProgress(event: ProgressEvent): void;
+    /**
+     * 返回下载的分片管理器
+     */
+    protected getChunkManager(): ChunkManager | null;
+    /**
+     * 下载单个分片（Range 请求）
+     *
+     * - 字符串 action：直接走 axios，Range 头在 overrides.headers 中显式传入
+     * - 函数 action：通过 _chunkHeadersQueue 告知拦截器注入 Range 头，
+     *   最终由 cfg.action(this) 调用用户的 axios 函数
+     *
+     * @param start  - 分片起始字节偏移
+     * @param end    - 分片结束字节偏移（含）
+     * @param signal - AbortSignal，用于超时/取消
+     * @returns 分片的 Blob 数据
+     */
+    downloadChunk(start: number, end: number, signal?: AbortSignal): Promise<Blob>;
+    /**
+     * 统一 HTTP 请求方法（download() 和 downloadChunk() 共用）
+     *
+     * action 不区分普通/分片，只按类型分发：
+     *   - 字符串 action → 始终走 axios（分片时 headers 里带 Range，普通时不带）
+     *   - 函数 action → 始终调 cfg.action(this)（分片时 _chunkHeadersQueue 已 push，拦截器自动注入 Range）
+     */
+    private _doHttpRequest;
+    /**
+     * 获取文件大小（下载场景：无 File 对象，fallback 到 size 属性）
+     */
+    getFileSize(): number;
+    /**
+     * 通过 FileHandle 流式写入 Blob 数据到磁盘
+     *
+     * 使用 File System Access API，直接写入用户选择的文件位置。
+     * 绕过浏览器内存限制，适合大文件下载。
+     *
+     * @param fileHandle - 文件句柄
+     * @param data - 要写入的数据（Blob 或可转为 Blob）
+     */
+    /**
+     * 从下载列表中移除当前文件，取消进行中的下载
+     */
+    remove(): void;
+    static writeToFileHandle(fileHandle: FileSystemFileHandle, data: Blob | any): Promise<void>;
+}
+
+/**
+ * 统一日志工具模块
+ *
+ * 提供环境感知的日志输出，支持级别控制和格式化
+ *
+ * @example
+ * ```typescript
+ * import { logger } from './utils/logger';
+ *
+ * logger.info('uploadChunkManager', '开始上传分片');
+ * logger.debug('uploadChunkManager', '分片详情', { index: 0, size: 1024 });
+ * logger.warn('uploadChunkManager', '更新状态失败:', error);
+ * logger.error('uploadChunkManager', '上传失败', error);
+ * ```
+ */
+/**
+ * 日志级别枚举
+ */
+declare enum LogLevel {
+    DEBUG = 0,// 调试信息（仅开发环境）
+    INFO = 1,// 一般信息
+    WARN = 2,// 警告信息
+    ERROR = 3
+}
+/**
+ * 日志配置选项
+ */
+interface LoggerOptions {
+    /** 是否启用日志输出（默认 true） */
+    enabled?: boolean;
+    /** 最低日志级别 */
+    level?: LogLevel;
+    /** 是否显示时间戳 */
+    showTimestamp?: boolean;
+    /** 是否启用颜色输出 */
+    enableColors?: boolean;
+}
+/**
+ * 日志条目接口
+ */
+interface LogEntry {
+    /** 时间戳 */
+    timestamp: number;
+    /** 日志级别 */
+    level: LogLevel;
+    /** 模块名称 */
+    module: string;
+    /** 消息内容 */
+    message: string;
+    /** 额外参数 */
+    args?: any[];
+    /** 错误堆栈（如果是 Error 对象） */
+    stack?: string;
+}
+/**
+ * 日志收集器回调函数类型
+ */
+type LogCollectorCallback = (entry: LogEntry) => void | Promise<void>;
+/**
+ * 初始化日志配置
+ * @param options 日志配置选项
+ */
+declare function initLogger(options?: LoggerOptions): void;
+/**
+ * 动态设置日志级别
+ * @param level 日志级别
+ */
+declare function setLogLevel(level: LogLevel): void;
+/**
+ * 注册日志收集器
+ * @param callback 收集器回调函数
+ * @returns 取消注册的函数
+ *
+ * @example
+ * ```typescript
+ * // 注册收集器
+ * const unsubscribe = addLogCollector((entry) => {
+ *   if (entry.level === LogLevel.ERROR) {
+ *     // 上报到监控平台
+ *     reportToSentry(entry);
+ *   }
+ * });
+ *
+ * // 取消注册
+ * unsubscribe();
+ * ```
+ */
+declare function addLogCollector(callback: LogCollectorCallback): () => void;
+/**
+ * 清除所有日志收集器
+ */
+declare function clearLogCollectors(): void;
+/**
+ * 日志工具对象
+ */
+declare const logger: {
+    /**
+     * 调试日志（仅开发环境）
+     * @param module 模块名称
+     * @param message 消息内容
+     * @param args 额外参数
+     */
+    debug: (module: string, message: string, ...args: any[]) => void;
+    /**
+     * 信息日志
+     * @param module 模块名称
+     * @param message 消息内容
+     * @param args 额外参数
+     */
+    info: (module: string, message: string, ...args: any[]) => void;
+    /**
+     * 警告日志
+     * @param module 模块名称
+     * @param message 消息内容
+     * @param args 额外参数
+     */
+    warn: (module: string, message: string, ...args: any[]) => void;
+    /**
+     * 错误日志
+     * @param module 模块名称
+     * @param message 消息内容
+     * @param args 额外参数
+     */
+    error: (module: string, message: string, ...args: any[]) => void;
+};
+
+/**
+ * 保存 File 对象到 IndexedDB
+ *
+ * @param fileHash - 文件哈希值（作为主键）
+ * @param file - File 对象
+ * @returns Promise<void>
+ */
+declare function saveFileToCache(fileHash: string, file: File): Promise<void>;
+/**
+ * 从 IndexedDB 恢复 File 对象
+ *
+ * @param fileHash - 文件哈希值
+ * @returns Promise<File | null> - 如果找到则返回 File 对象，否则返回 null
+ */
+declare function restoreFileFromCache(fileHash: string): Promise<File | null>;
+/**
+ * 删除指定文件的缓存
+ *
+ * @param fileHash - 文件哈希值
+ * @returns Promise<void>
+ */
+declare function removeFileFromCache(fileHash: string): Promise<void>;
+/**
+ * 清空所有文件缓存
+ *
+ * @returns Promise<void>
+ */
+declare function clearAllFileCache(): Promise<void>;
+/**
+ * 获取缓存统计信息
+ *
+ * @returns Promise<{ count: number; totalSize: number }>
+ */
+declare function getCacheStats(): Promise<{
+    count: number;
+    totalSize: number;
+}>;
+/**
+ * 清理过期缓存（超过指定天数的缓存）
+ *
+ * @param days - 保留天数，默认 7 天
+ * @returns Promise<number> - 删除的记录数
+ */
+declare function cleanExpiredCache(days?: number): Promise<number>;
+/**
+ * 将 FileSystemFileHandle 持久化到 IndexedDB（跨页面刷新复用）
+ *
+ * 关键是避免重复调用 showSaveFilePicker() 导致 Chrome 截断已有文件为 0 字节。
+ */
+declare function saveFileHandle(fileName: string, fileHandle: FileSystemFileHandle): Promise<void>;
+/**
+ * 从 IndexedDB 加载持久化的 FileSystemFileHandle
+ * @returns FileSystemFileHandle（未找到或已失效则返回 null）
+ */
+declare function loadFileHandle(fileName: string): Promise<FileSystemFileHandle | null>;
+/**
+ * 删除指定文件的句柄记录
+ */
+declare function removeFileHandle(fileName: string): Promise<void>;
+
+/**
+ * 上传性能监控模块
+ *
+ * 提供上传成功率、耗时统计、错误分析等监控功能
+ *
+ * @example
+ * ```typescript
+ * import { uploadMonitor } from '@core/utils';
+ *
+ * // 获取实时统计数据
+ * console.log(uploadMonitor.getStats());
+ *
+ * // 重置统计数据
+ * uploadMonitor.reset();
+ * ```
+ */
+/**
+ * 单个文件的上传记录
+ */
+interface UploadRecord {
+    /** 文件唯一标识 */
+    fileId: string;
+    /** 文件名 */
+    fileName: string;
+    /** 文件大小（字节） */
+    fileSize: number;
+    /** 开始时间戳 */
+    startTime: number;
+    /** 结束时间戳 */
+    endTime?: number;
+    /** 是否成功 */
+    success: boolean;
+    /** 失败原因（如果失败） */
+    error?: string;
+    /** 重试次数 */
+    retryCount: number;
+    /** 分片总数（如果是分片上传） */
+    totalChunks?: number;
+    /** 成功分片数 */
+    chunks?: number;
+    /** 失败分片数 */
+    failedChunks?: number;
+    /** ✅ 各模块的错误次数统计 */
+    errorModules?: Map<string, number>;
+}
+/**
+ * 上传统计数据
+ */
+interface UploadStats {
+    /** 总上传数 */
+    totalUploads: number;
+    /** 成功上传数 */
+    successfulUploads: number;
+    /** 失败上传数 */
+    failedUploads: number;
+    /** 成功率（0-100） */
+    successRate: number;
+    /** 平均耗时（毫秒） */
+    averageDuration: number;
+    /** 最短耗时（毫秒） */
+    minDuration: number;
+    /** 最长耗时（毫秒） */
+    maxDuration: number;
+    /** 中位数耗时（毫秒） */
+    medianDuration: number;
+    /** 平均文件大小（字节） */
+    averageFileSize: number;
+    /** 总上传数据量（字节） */
+    totalBytesUploaded: number;
+    /** 平均上传速度（字节/秒） */
+    averageSpeed: number;
+    /** 按错误类型统计 */
+    errorsByType: Map<string, number>;
+    /** 按模块统计错误 */
+    errorsByModule: Map<string, number>;
+    /** 平均重试次数 */
+    averageRetries: number;
+    /** 分片上传统计 */
+    chunkUploadStats?: {
+        /** 总分片数 */
+        totalChunks: number;
+        /** 成功分片数 */
+        successfulChunks: number;
+        /** 失败分片数 */
+        failedChunks: number;
+        /** 分片成功率 */
+        chunkSuccessRate: number;
+    };
+}
+/**
+ * 上传性能监控类
+ */
+declare class UploadMonitor {
+    /** 上传记录列表 */
+    private records;
+    /** 当前活跃的上传任务 */
+    private activeUploads;
+    /** 最大保留记录数 */
+    private readonly MAX_RECORDS;
+    constructor();
+    /**
+     * 初始化日志收集器
+     */
+    private init;
+    /**
+     * 处理日志条目
+     */
+    private processLog;
+    /**
+     * 完成记录并添加到历史
+     */
+    private finalizeRecord;
+    /**
+     * 从日志条目中提取 fileId
+     */
+    private extractFileId;
+    /**
+     * 从日志条目中提取文件名
+     */
+    private extractFileName;
+    /**
+     * 从日志条目中提取文件大小
+     */
+    private extractFileSize;
+    /**
+     * 从日志条目中提取分片总数
+     */
+    private extractTotalChunks;
+    /**
+     * 获取上传统计数据
+     */
+    getStats(): UploadStats;
+    /**
+     * 分类错误类型
+     */
+    private classifyError;
+    /**
+     * 获取最近 N 条上传记录
+     */
+    getRecentRecords(count?: number): UploadRecord[];
+    /**
+     * 获取活跃上传任务
+     */
+    getActiveUploads(): Map<string, UploadRecord>;
+    /**
+     * 重置所有统计数据
+     */
+    reset(): void;
+    /**
+     * 导出统计数据为 JSON
+     */
+    exportToJSON(): string;
+    /**
+     * 打印统计报告到控制台
+     */
+    printReport(): void;
+}
+declare const uploadMonitor: UploadMonitor;
+
+/**
+ * 网络状态检查工具
+ *
+ * 提供上传前的网络状态检查功能
+ */
+/**
+ * 网络检查结果
+ */
+interface NetworkCheckResult {
+    /** 是否在线 */
+    online: boolean;
+    /** 检查时间戳 */
+    timestamp: number;
+    /** 错误信息（如果离线） */
+    error?: string;
+}
+/**
+ * 检查网络连接状态
+ * @returns 网络检查结果
+ */
+declare function checkNetworkStatus(): NetworkCheckResult;
+/**
+ * 异步检查网络连通性（通过实际请求测试）
+ * @param testUrl 测试用的 URL（可选，默认为当前域名）
+ * @param timeout 超时时间（毫秒），默认 5000ms
+ * @returns Promise<NetworkCheckResult>
+ */
+declare function checkNetworkConnectivity(testUrl?: string, timeout?: number): Promise<NetworkCheckResult>;
+/**
+ * 监听网络状态变化
+ * @param callback 网络状态变化回调
+ * @returns 取消监听的函数
+ */
+declare function watchNetworkStatus(callback: (online: boolean) => void): () => void;
+
+/**
+ * Web Worker 内联 MD5 计算 — 将 CPU 密集型哈希计算移出主线程，避免 UI 卡顿。
+ *
+ * 策略：
+ *  - 文件 ≤ 50MB：通过 Blob URL Worker 异步计算，主线程零阻塞
+ *  - 文件 > 50MB 或 Worker 不可用：回退到主线程 SparkMD5 流式计算
+ *  - 小文件 (<5MB)：直接用主线程，省去 Worker 创建开销
+ */
+/**
+ * 使用 Web Worker 异步计算文件 MD5。
+ *
+ * 仅在上传端使用（有 File 对象时）；下载端正用此函数的地方
+ * 传入的是 FileSystemFileHandle.getFile() 返回的 File，同样可用。
+ *
+ * @returns MD5 hex 字符串
+ */
+declare function calculateFileMD5InWorker(file: File, signal?: AbortSignal): Promise<string>;
+/**
+ * 全局清理：释放缓存的 Blob URL（SPA 卸载时调用）
+ */
+declare function disposeMD5Worker(): void;
+
+declare function generateFileId(): string;
+declare function mergeObjects<T extends Record<string, any>>(target: T, source?: Partial<T>): T;
+declare function handleFile(file: File): Promise<string>;
+declare function computeTransferTime(transferTime: TimeInfo): {
+    start(): void;
+    end(): void;
+};
+declare function getFileExtension(filename?: string): string;
+/**
+ * 判断文件是否处于活跃上传状态（统一判断逻辑）
+ * @param file 文件实例
+ * @returns 是否为活跃上传状态
+ * @private
+ */
+declare function isFileActive(file: TransferFile<any>): boolean;
+/**
+ * 将文件大小转换为易读的格式
+ * @param {number} bytes - 文件大小的字节数
+ * @param {number} [decimals=2] - 保留的小数位数，默认为2
+ * @returns {string} 转换后的文件大小字符串
+ */
+declare function formatFileSize(bytes: any, decimals?: number): string;
+declare const validator: {
+    limit(limit: number, length: number): boolean;
+    size(fileSize: number, maxSize: number): boolean;
+    type(accept: string[], file: TransferFile<any>): boolean;
+};
+/**
+ * 创建响应式的 UploadFile 实例
+ * @param uploadFile 原始的 UploadFile 实例
+ * @param uploader Uploader 实例
+ * @returns Proxy 包装后的 UploadFile
+ */
+declare function createReactiveUploadFile(file: UploadFile, uploader: Transfer): UploadFile;
+/**
+ * 创建响应式的 DownloadFile 实例
+ * @param file 原始的 DownloadFile 实例
+ * @param downloader Downloader 实例
+ * @returns Proxy 包装后的 DownloadFile
+ */
+declare function createReactiveDownloadFile(file: DownloadFile, downloader: Transfer): DownloadFile;
+/**
+ * 提取函数中的路径
+ * @param str 函数字符串
+ * @returns 提取到的路径，如果没有找到返回 null
+ */
+declare function extractPathFromFunction(str: string): string | null;
+/** 判断一个值是否为纯对象（非 null、非数组、typeof === "object"） */
+declare function isPlainObject(value: any): value is Record<string, any>;
+/**
+ * 格式化上传/下载速度显示
+ * @param bytesPerSecond 每秒字节数
+ * @returns 格式化后的速度字符串
+ */
+declare function formatSpeed(bytesPerSecond: number): string;
+/**
+ * 格式化时间 duration 显示
+ * @param milliseconds 毫秒数
+ * @returns 格式化后的时间字符串
+ */
+declare function formatDuration(milliseconds: number): string;
+/**
+ * 睡眠工具函数
+ * @param ms 毫秒数
+ * @returns Promise
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * 计算文件的 MD5 哈希值
+ *
+ * 策略（自动选择最优路径）：
+ *  - 文件 > 50MB：Worker 路径（完整读取至 Worker 计算，主线程零阻塞）
+ *  - 文件 5~50MB：Worker 路径，无进度回调时优先
+ *  - 文件 ≤ 5MB 或有 onProgress 回调：主线程 SparkMD5 流式计算
+ *  - Worker 不可用：回退到主线程 SparkMD5
+ *
+ * @param file 文件对象
+ * @param onProgress 可选的进度回调函数，接收当前进度百分比 (0-100)
+ * @returns MD5 哈希字符串
+ */
+declare function calculateFileMD5(file: File, onProgress?: (percent: number) => void, signal?: AbortSignal): Promise<string>;
+
+export { type LogCollectorCallback, type LogEntry, LogLevel, type LoggerOptions, type NetworkCheckResult, type UploadRecord, type UploadStats, addLogCollector, calculateFileMD5, calculateFileMD5InWorker, checkNetworkConnectivity, checkNetworkStatus, cleanExpiredCache, clearAllFileCache, clearLogCollectors, computeTransferTime, createReactiveDownloadFile, createReactiveUploadFile, disposeMD5Worker, extractPathFromFunction, formatDuration, formatFileSize, formatSpeed, generateFileId, getCacheStats, getFileExtension, handleFile, initLogger, isFileActive, isPlainObject, loadFileHandle, logger, mergeObjects, removeFileFromCache, removeFileHandle, restoreFileFromCache, saveFileHandle, saveFileToCache, setLogLevel, sleep, uploadMonitor, validator, watchNetworkStatus };