@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/file-transfer/api.ts

@@ -0,0 +1,364 @@
+/**
+ * api.ts — 文件传输专用 API 封装
+ *
+ * 与 iOS LargeAttachmentUploadOperation 对齐的后端接口：
+ *   - initMultipartUpload：初始化分片上传（文档 §八）
+ *   - batchGetChunkPreSignedUrl：刷新过期的分片预签名 URL（文档 §九）
+ *   - batchCompleteChunks：确认所有分片上传完成（文档 §十）
+ *   - resolveShortLink：解析短链接获取实际下载地址（文档 §十三）
+ *   - downloadCallback：下载完成回调（文档 §十二）
+ *
+ * 使用 api-client.ts 的 postJson 和 buildSignature 实现 HMAC-SHA256 签名。
+ * 所有接口 Base URL 为 /api/im/open/bot。
+ */
+
+import { randomUUID } from 'node:crypto';
+import { postJson, buildSignature } from '../api-client.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 服务端响应原始类型（与接口文档对齐）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 服务端 ChunkUrlVO 结构 */
+interface ChunkUrlVO {
+  chunkIndex: number;
+  preSignedUrl: string;
+  expireTime: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 导出响应类型（对调用方友好的归一化结构）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** initMultipartUpload 响应 */
+export interface InitMultipartUploadResult {
+  /** 服务端分配的文件 ID */
+  fileId: string;
+  /** 各分片的预签名上传 URL 列表（按 chunkIndex 顺序） */
+  chunkUrlList: string[];
+  /** 总分片数 */
+  totalChunks: number;
+  /** 上传会话过期时间（毫秒时间戳），用于填充 PbChatFileMeta.expireTime */
+  expireTime: number;
+}
+
+/** batchGetChunkPreSignedUrl 响应 */
+export interface BatchChunkUrlResult {
+  /** 刷新后的分片 URL 列表（按 chunkIndex 对应） */
+  chunkUrlList: { index: number; url: string }[];
+}
+
+/** batchCompleteChunks 响应 */
+export interface BatchCompleteResult {
+  /** 文件访问 URL */
+  fileUrl: string;
+  /** 操作凭证（下载回调用） */
+  opCreds: string;
+}
+
+/** 短链接解析结果 */
+export interface ResolveShortLinkResult {
+  /** 实际下载 URL（302 重定向目标） */
+  downloadUrl: string;
+  /** 文件 ETag（从响应头获取） */
+  etag: string;
+  /** 文件大小（字节，从 Content-Length 响应头获取） */
+  contentLength: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API 路径常量（对齐文档 Base URL: /api/im/open/bot）
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PATH_INIT_MULTIPART = '/api/im/open/bot/initMultipartUpload';
+const PATH_BATCH_CHUNK_URL = '/api/im/open/bot/batchGetChunkPreSignedUrl';
+const PATH_BATCH_COMPLETE = '/api/im/open/bot/batchCompleteChunks';
+const PATH_SHORT_LINK = '/api/im/open/bot/file/shorLink';
+const PATH_DOWNLOAD_CALLBACK = '/api/im/open/bot/downloadCallback';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具：GET 请求（带签名，用于短链接解析）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 发送带签名的 GET 请求，手动跟随 302 重定向以获取 Location 头。
+ * 签名规则与 POST 一致：body 为空时对空字符串 "" 做 SHA-256。
+ */
+async function getWithRedirect(
+  apiBaseUrl: string,
+  path: string,
+  auth: { apiKey: string; apiSecret: string },
+  queryParams?: Record<string, string>,
+): Promise<Response> {
+  const qs = queryParams ? '?' + new URLSearchParams(queryParams).toString() : '';
+  const url = `${apiBaseUrl.replace(/\/$/, '')}${path}${qs}`;
+
+  const emptyBody = new Uint8Array(0);
+  const timestamp = String(Date.now());
+  const signature = buildSignature({
+    apiSecret: auth.apiSecret,
+    method: 'GET',
+    path,
+    timestamp,
+    body: emptyBody,
+  });
+
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'X-Api-Key': auth.apiKey,
+      'X-Timestamp': timestamp,
+      'X-Signature': signature,
+      reqid: randomUUID().replaceAll('-', ''),
+    },
+    redirect: 'manual', // 不自动跟随重定向，手动获取 Location
+  });
+
+  return res;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 公共 API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 初始化分片上传。
+ * POST /api/im/open/bot/initMultipartUpload（文档 §八）
+ *
+ * 服务端返回 chunkUrlList 为 ChunkUrlVO[] 对象数组，
+ * 本函数归一化为按 chunkIndex 排序的 preSignedUrl 字符串数组。
+ */
+export async function initMultipartUpload(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    /** IM 主账号 ID（必填） */
+    imMainAccId: string;
+    fileName: string;
+    fileSize: number;
+    chunkSize: number;
+    totalChunks: number;
+    mimeType: string;
+  },
+): Promise<InitMultipartUploadResult> {
+  const raw = await postJson<{
+    fileId: string;
+    totalChunks: number;
+    chunkSize: number;
+    expireTime: number;
+    chunkUrlList: ChunkUrlVO[];
+  }>(
+    apiBaseUrl,
+    PATH_INIT_MULTIPART,
+    {
+      imMainAccId: params.imMainAccId,
+      fileName: params.fileName,
+      fileSize: params.fileSize,
+      mimeType: params.mimeType,
+      chunkSize: params.chunkSize,
+      totalChunks: params.totalChunks,
+      firstBatchSize: params.totalChunks, // 一次性获取所有分片 URL
+      scene: 'AI_GC',
+    },
+    auth,
+  );
+
+  // 归一化：ChunkUrlVO[] → 按内部 0-based index 排序的 URL 字符串数组
+  // 服务端 chunkIndex 从 1 开始，内部从 0 开始
+  const urlArray = new Array<string>(raw.totalChunks).fill('');
+  for (const item of raw.chunkUrlList ?? []) {
+    urlArray[item.chunkIndex - 1] = item.preSignedUrl;
+  }
+
+  return {
+    fileId: raw.fileId,
+    chunkUrlList: urlArray,
+    totalChunks: raw.totalChunks,
+    expireTime: raw.expireTime,
+  };
+}
+
+/**
+ * 批量刷新分片预签名 URL（URL 过期时调用）。
+ * POST /api/im/open/bot/batchGetChunkPreSignedUrl（文档 §九）
+ */
+export async function batchGetChunkPreSignedUrl(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    /** IM 主账号 ID（必填） */
+    imMainAccId: string;
+    fileId: string;
+    chunkIndices: number[];
+  },
+): Promise<BatchChunkUrlResult> {
+  console.log(
+    `batchCompleteChunks: ${JSON.stringify({
+      imMainAccId: params.imMainAccId,
+      fileId: params.fileId,
+      chunkIndexList: params.chunkIndices.map((i) => i + 1),
+      scene: 'AI_GC',
+    })}`,
+  );
+  const raw = await postJson<{
+    fileId: string;
+    totalChunks: number;
+    chunkUrlList: ChunkUrlVO[];
+  }>(
+    apiBaseUrl,
+    PATH_BATCH_CHUNK_URL,
+    {
+      imMainAccId: params.imMainAccId,
+      fileId: params.fileId,
+      chunkIndexList: params.chunkIndices.map((i) => i + 1), // 内部 0-based → 服务端 1-based
+      scene: 'AI_GC',
+    },
+    auth,
+  );
+
+  // 归一化：ChunkUrlVO[] → { index, url }[]，服务端 1-based → 内部 0-based
+  const chunkUrlList = (raw.chunkUrlList ?? []).map((item) => ({
+    index: item.chunkIndex - 1,
+    url: item.preSignedUrl,
+  }));
+
+  return { chunkUrlList };
+}
+
+/**
+ * 确认所有分片上传完成。
+ * POST /api/im/open/bot/batchCompleteChunks（文档 §十）
+ */
+export async function batchCompleteChunks(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    /** IM 主账号 ID（必填） */
+    imMainAccId: string;
+    fileId: string;
+    completedChunks: { index: number; etag: string }[];
+  },
+): Promise<BatchCompleteResult> {
+  console.log(
+    `batchCompleteChunks: ${JSON.stringify({
+      imMainAccId: params.imMainAccId,
+      fileId: params.fileId,
+      completedChunkList: params.completedChunks.map((c) => ({
+        chunkIndex: c.index + 1,
+        etag: c.etag,
+      })),
+      needOpCreds: true,
+      scene: 'AI_GC',
+    })}`,
+  );
+  const raw = await postJson<{
+    totalCompletedChunks: number;
+    totalChunks: number;
+    fileUrl: string;
+    expireTime: number;
+    opCreds?: string;
+  }>(
+    apiBaseUrl,
+    PATH_BATCH_COMPLETE,
+    {
+      imMainAccId: params.imMainAccId,
+      fileId: params.fileId,
+      // 文档字段名为 completedChunkList，子字段为 chunkIndex / eTag
+      // 内部 0-based → 服务端 1-based
+      completedChunkList: params.completedChunks.map((c) => ({
+        chunkIndex: c.index + 1,
+        etag: c.etag,
+      })),
+      needOpCreds: true,
+      scene: 'AI_GC',
+    },
+    auth,
+  );
+
+  return {
+    fileUrl: raw.fileUrl,
+    opCreds: raw.opCreds ?? '',
+  };
+}
+
+/**
+ * 解析短链接为实际下载地址。
+ * GET /api/im/open/bot/file/shorLink?shortCode=xxx&scene=CHAT_MEDIA（文档 §十三）
+ *
+ * @param queryParams 从短链接 URL 中提取的查询参数，会与 scene 合并后发送
+ *
+ * 服务端返回 302 重定向到签名下载 URL。
+ * 本函数从 Location 头获取实际下载 URL，再 HEAD 请求获取 ETag 和 Content-Length。
+ */
+export async function resolveShortLink(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  queryParams: Record<string, string>,
+): Promise<ResolveShortLinkResult> {
+  const res = await getWithRedirect(apiBaseUrl, PATH_SHORT_LINK, auth, queryParams);
+
+  // 期望 302 重定向
+  if (res.status !== 302 && res.status !== 301) {
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '');
+      throw new Error(`imwe API ${PATH_SHORT_LINK} 返回 ${res.status}: ${errText}`);
+    }
+    // 某些情况服务端可能直接返回 200 + JSON（兼容处理）
+    const json = (await res.json()) as {
+      downloadUrl?: string;
+      url?: string;
+      etag?: string;
+      contentLength?: number;
+    };
+    return {
+      downloadUrl: json.downloadUrl ?? json.url ?? '',
+      etag: json.etag ?? '',
+      contentLength: json.contentLength ?? 0,
+    };
+  }
+
+  // 从 Location 头获取实际下载 URL
+  const downloadUrl = res.headers.get('location') ?? '';
+  if (!downloadUrl) {
+    throw new Error(`imwe API ${PATH_SHORT_LINK} 返回 302 但缺少 Location 头`);
+  }
+
+  // HEAD 请求获取 ETag 和 Content-Length
+  let etag = '';
+  let contentLength = 0;
+  try {
+    const headRes = await fetch(downloadUrl, { method: 'HEAD' });
+    etag = headRes.headers.get('etag') ?? '';
+    contentLength = parseInt(headRes.headers.get('content-length') ?? '0', 10) || 0;
+  } catch {
+    // HEAD 失败时不阻断，调用方可通过实际下载获取大小
+  }
+
+  return { downloadUrl, etag, contentLength };
+}
+
+/**
+ * 下载完成回调（通知服务端可删除临时文件）。
+ * POST /api/im/open/bot/downloadCallback（文档 §十二）
+ */
+export async function downloadCallback(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    /** IM 主账号 ID（必填） */
+    imMainAccId: string;
+    /** 操作凭证 */
+    opCreds: string;
+  },
+): Promise<void> {
+  await postJson<unknown>(
+    apiBaseUrl,
+    PATH_DOWNLOAD_CALLBACK,
+    {
+      imMainAccId: params.imMainAccId,
+      opCredsList: [params.opCreds], // 文档要求数组格式
+      scene: 'AI_GC',
+    },
+    auth,
+  );
+}

package/src/file-transfer/concurrency.ts

@@ -0,0 +1,77 @@
+/**
+ * concurrency.ts — 滑动窗口并发任务执行器
+ *
+ * 提供可配置并发数的 Promise 池模式执行器，上传和下载共用。
+ * 与 iOS LargeAttachmentUploadOperation 的并发上传策略对齐。
+ */
+
+/** 任务定义 */
+export interface ConcurrentTask<T> {
+  /** 任务唯一标识（用于日志和状态追踪） */
+  id: string | number;
+  /** 任务执行函数 */
+  execute: () => Promise<T>;
+}
+
+/** 并发执行结果 */
+export interface ConcurrentResult<T> {
+  id: string | number;
+  success: boolean;
+  value?: T;
+  error?: Error;
+}
+
+/**
+ * 滑动窗口并发执行器。
+ *
+ * 同时最多执行 `limit` 个任务，一个完成后立即启动下一个（滑动窗口）。
+ * 与 iOS LargeAttachmentUploadOperation 的并发上传策略对齐。
+ *
+ * @param tasks   任务列表
+ * @param limit   最大并发数
+ * @param onProgress  单个任务完成时的回调（可选，用于更新持久化状态）
+ * @returns 所有任务的执行结果（保持原始顺序）
+ */
+export async function runConcurrent<T>(
+  tasks: ConcurrentTask<T>[],
+  limit: number,
+  onProgress?: (result: ConcurrentResult<T>) => void,
+): Promise<ConcurrentResult<T>[]> {
+  if (tasks.length === 0) return [];
+
+  const results: ConcurrentResult<T>[] = new Array(tasks.length);
+  let nextIndex = 0;
+
+  async function runTask(taskIndex: number): Promise<void> {
+    const task = tasks[taskIndex];
+    try {
+      const value = await task.execute();
+      results[taskIndex] = { id: task.id, success: true, value };
+    } catch (err) {
+      results[taskIndex] = {
+        id: task.id,
+        success: false,
+        error: err instanceof Error ? err : new Error(String(err)),
+      };
+    }
+    onProgress?.(results[taskIndex]);
+  }
+
+  // 启动一个 worker：执行当前任务，完成后从队列取下一个
+  async function worker(): Promise<void> {
+    while (nextIndex < tasks.length) {
+      const idx = nextIndex++;
+      await runTask(idx);
+    }
+  }
+
+  // 启动 min(limit, tasks.length) 个 worker 并行执行
+  const workerCount = Math.min(limit, tasks.length);
+  const workers: Promise<void>[] = [];
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(worker());
+  }
+
+  await Promise.all(workers);
+  return results;
+}

package/src/file-transfer/download.ts

@@ -0,0 +1,261 @@
+/**
+ * download.ts — 分片下载 + 解密服务
+ *
+ * 与 iOS 对齐的分片下载流程：
+ *   1. 解析短链接获取实际下载 URL + ETag + contentLength
+ *   2. 加载/创建 .partial.meta 断点状态
+ *   3. ETag 不匹配时丢弃旧数据重新下载
+ *   4. 并发 Range GET 下载缺失分片（滑动窗口）
+ *   5. 每个分片下载后即时 AES-CTR 解密并写入 .partial 文件对应 offset
+ *   6. SHA256 完整性校验
+ *   7. rename .partial → 最终文件
+ *   8. downloadCallback 通知服务端
+ */
+
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { DownloadAndDecryptParams, DownloadResult, DownloadState } from './types.js';
+import { aesCtrXor } from './file-crypto.js';
+import { runConcurrent, ConcurrentTask } from './concurrency.js';
+import { resolveShortLink, downloadCallback } from './api.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 断点续传状态管理
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 加载下载断点状态。
+ * @param savePath 最终文件保存路径（.partial.meta 与之同目录）
+ * @returns 已有的 DownloadState 或 null
+ */
+export function loadDownloadState(savePath: string): DownloadState | null {
+  const metaPath = `${savePath}.partial.meta`;
+  try {
+    const raw = fs.readFileSync(metaPath, 'utf-8');
+    return JSON.parse(raw) as DownloadState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 持久化下载断点状态（原子写入）。
+ */
+export function saveDownloadState(savePath: string, state: DownloadState): void {
+  const metaPath = `${savePath}.partial.meta`;
+  const tmpPath = `${metaPath}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+  fs.renameSync(tmpPath, metaPath);
+}
+
+/**
+ * 清理下载临时文件（.partial + .partial.meta）。
+ */
+export function clearDownloadState(savePath: string): void {
+  const partialPath = `${savePath}.partial`;
+  const metaPath = `${savePath}.partial.meta`;
+  try {
+    fs.unlinkSync(partialPath);
+  } catch {
+    // 文件不存在时忽略
+  }
+  try {
+    fs.unlinkSync(metaPath);
+  } catch {
+    // 文件不存在时忽略
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 计算分片计划 */
+function computeChunkPlan(fileSize: number, chunkSize: number) {
+  const totalChunks = Math.ceil(fileSize / chunkSize);
+  return { totalChunks, chunkSize, fileSize };
+}
+
+/** 下载单个分片（HTTP Range GET） */
+async function downloadChunk(
+  url: string,
+  chunkIndex: number,
+  chunkSize: number,
+  fileSize: number,
+): Promise<Uint8Array> {
+  const start = chunkIndex * chunkSize;
+  const end = Math.min(start + chunkSize - 1, fileSize - 1);
+
+  const res = await fetch(url, {
+    headers: { Range: `bytes=${start}-${end}` },
+  });
+
+  if (!res.ok && res.status !== 206) {
+    throw new Error(`下载分片 ${chunkIndex} 失败: HTTP ${res.status}`);
+  }
+
+  const buf = await res.arrayBuffer();
+  return new Uint8Array(buf);
+}
+
+/** 确保目录存在 */
+function ensureDir(filePath: string): void {
+  const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+  if (dir && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 主入口
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 下载加密文件、分片解密、SHA256 完整性校验。
+ *
+ * @throws 完整性校验失败时抛出 Error（.partial 文件保留以供重试）
+ */
+export async function downloadAndDecryptFile(
+  params: DownloadAndDecryptParams,
+  auth: { apiKey: string; apiSecret: string },
+  apiBaseUrl: string,
+): Promise<DownloadResult> {
+  const { savePath, key, iv, digest, plaintextLength, opCreds, concurrency = 3 } = params;
+
+  // 幂等：文件已存在且大小匹配时直接返回
+  try {
+    const stat = fs.statSync(savePath);
+    if (stat.isFile() && stat.size === plaintextLength) {
+      return { localPath: savePath, digest };
+    }
+  } catch {
+    // 文件不存在，继续下载
+  }
+
+  // 1. 解析短链接获取实际下载 URL + ETag + contentLength
+  const urlObj = new URL(params.url);
+  const queryParams: Record<string, string> = {};
+  urlObj.searchParams.forEach((value, key) => {
+    queryParams[key] = value;
+  });
+  const resolved = await resolveShortLink(apiBaseUrl, auth, queryParams);
+  const { downloadUrl, etag, contentLength } = resolved;
+
+  // 使用 plaintextLength 作为文件大小（CTR 模式密文长度 === 明文长度）
+  // 注意：优先使用 proto 中的 plaintextLength 作为权威值，
+  // contentLength 仅作为辅助验证（HEAD 请求可能失败或返回不准确）
+  const fileSize = plaintextLength;
+  const chunkSize = 2 * 1024 * 1024; // 2MB，与 iOS 对齐
+  const plan = computeChunkPlan(fileSize, chunkSize);
+
+  // 2. 加载/创建断点状态
+  const partialPath = `${savePath}.partial`;
+  let state = loadDownloadState(savePath);
+
+  if (state) {
+    // 3. ETag 不匹配时丢弃旧数据重新下载
+    if (state.etag !== etag) {
+      clearDownloadState(savePath);
+      state = null;
+    }
+  }
+
+  if (!state) {
+    // 创建新的下载状态
+    state = {
+      etag,
+      chunkSize: plan.chunkSize,
+      totalChunks: plan.totalChunks,
+      fileSize: plan.fileSize,
+      downloadedChunks: [],
+      messageContext: params.messageContext,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    ensureDir(partialPath);
+    // 创建 .partial 文件（预分配大小）
+    const fd = fs.openSync(partialPath, 'w');
+    if (fileSize > 0) {
+      // 稀疏文件：写入最后一个字节以设置文件大小
+      const buf = Buffer.alloc(1);
+      fs.writeSync(fd, buf, 0, 1, fileSize - 1);
+    }
+    fs.closeSync(fd);
+    saveDownloadState(savePath, state);
+  }
+
+  // 4. 计算缺失的分片
+  const downloadedSet = new Set(state.downloadedChunks);
+  const missingChunks: number[] = [];
+  for (let i = 0; i < plan.totalChunks; i++) {
+    if (!downloadedSet.has(i)) {
+      missingChunks.push(i);
+    }
+  }
+
+  // 5. 并发下载缺失分片
+  if (missingChunks.length > 0) {
+    const tasks: ConcurrentTask<number>[] = missingChunks.map((chunkIndex) => ({
+      id: chunkIndex,
+      execute: async () => {
+        // 下载密文分片
+        const ciphertext = await downloadChunk(downloadUrl, chunkIndex, chunkSize, fileSize);
+
+        // 即时解密
+        const offset = chunkIndex * chunkSize;
+        const plaintext = aesCtrXor(ciphertext, key, iv, offset);
+
+        // 写入 .partial 文件对应 offset
+        const fd = fs.openSync(partialPath, 'r+');
+        try {
+          fs.writeSync(fd, plaintext, 0, plaintext.length, offset);
+        } finally {
+          fs.closeSync(fd);
+        }
+
+        return chunkIndex;
+      },
+    }));
+
+    await runConcurrent(tasks, concurrency, (result) => {
+      // 6. 每个分片完成后更新 .partial.meta
+      if (result.success && result.value !== undefined) {
+        state!.downloadedChunks.push(result.value);
+        state!.updatedAt = Date.now();
+        saveDownloadState(savePath, state!);
+      }
+    });
+  }
+
+  // 7. SHA256 完整性校验
+  const fileData = fs.readFileSync(partialPath);
+  const hash = crypto.createHash('sha256').update(fileData).digest('hex');
+
+  if (hash !== digest) {
+    // 校验失败：抛出错误，.partial 保留以供重试
+    throw new Error(`完整性校验失败: 期望 ${digest}, 实际 ${hash}`);
+  }
+
+  // 8. rename .partial → 最终文件
+  ensureDir(savePath);
+  fs.renameSync(partialPath, savePath);
+
+  // 9. 删除 .partial.meta
+  const metaPath = `${savePath}.partial.meta`;
+  try {
+    fs.unlinkSync(metaPath);
+  } catch {
+    // 忽略
+  }
+
+  // 10. downloadCallback 通知服务端（失败时静默忽略）
+  if (opCreds) {
+    try {
+      await downloadCallback(apiBaseUrl, auth, { imMainAccId: params.imMainAccId ?? '', opCreds });
+    } catch {
+      // 静默忽略，不影响本地文件使用
+    }
+  }
+
+  return { localPath: savePath, digest };
+}