@open-dy/vibecoding-sdk-taro 0.1.12 → 0.1.14

package/src/runtime/douyin-container-request.ts

@@ -6,7 +6,8 @@ const ttRuntime: DouyinMiniProgramRuntime | undefined =
   // @ts-ignore
   typeof tt !== "undefined" ? tt : undefined;
 
-let douyinCloud: DouyinCloudInstance | null | undefined;
+let douyinCloud: DouyinMiniProgramCloudInstance | null | undefined;
+let devPreviewUploadCloud: DouyinMiniProgramCloudInstance | null | undefined;
 
 export const isDouyinMiniProgram = (): boolean =>
   Taro.getEnv() === Taro.ENV_TYPE.TT;
@@ -23,6 +24,12 @@ export const isDouyinPreviewEnv = (): boolean => {
   return getDouyinMicroappEnvType() === "preview";
 };
 
+export const isDouyinNativePreviewEnv = (): boolean => {
+  if (!isDouyinMiniProgram() || !isDouyinPreviewEnv()) return false;
+  const platform = ttRuntime?.getSystemInfoSync?.()?.platform;
+  return platform !== "devtools" && platform !== "web-devtools";
+};
+
 export const isDouyinTestEnv = (): boolean => {
   return getDouyinMicroappEnvType() === "development";
 };
@@ -92,23 +99,18 @@ const parseContainerResponseBody = (
   return body;
 };
 
-export const getDouyinCloud = (): DouyinCloudInstance | null => {
-  if (douyinCloud !== undefined) {
-    return douyinCloud;
-  }
-
-  const envID = getDouyinCloudEnvID();
-  if (!ttRuntime?.createCloud || !envID) {
-    douyinCloud = null;
-    return douyinCloud;
-  }
-
-  const serviceID = getDouyinCloudServiceID();
-  douyinCloud = ttRuntime.createCloud({
+const createDouyinCloud = (envID: string, serviceID: string): DouyinMiniProgramCloudInstance | null => {
+  if (!ttRuntime?.createCloud || !envID) return null;
+  return ttRuntime.createCloud({
     envID,
     ...(serviceID ? { serviceID } : {}),
   });
+};
 
+export const getDouyinCloud = (): DouyinMiniProgramCloudInstance | null => {
+  if (douyinCloud === undefined) {
+    douyinCloud = createDouyinCloud(getDouyinCloudEnvID(), getDouyinCloudServiceID());
+  }
   return douyinCloud;
 };
 
@@ -257,21 +259,25 @@ export const requestSSEByDouyinContainer = (
   return requestPromise;
 };
 
-export const uploadByDouyinContainer = (option: Taro.uploadFile.Option) => {
+export const uploadByDouyinContainer = (option: Taro.uploadFile.Option, envType?: "development") => {
   const error = getManagedUploadError({ fileName: option.fileName });
   if (error) return rejectManagedUpload(option, error);
-  const cloud = getDouyinCloud();
+  const useDevPreviewCloud = envType === "development";
+  const cloud = useDevPreviewCloud
+    ? (devPreviewUploadCloud ??= createDouyinCloud(DOUYIN_CLOUD_DEV_ENV_ID, DOUYIN_CLOUD_SERVICE_ID))
+    : getDouyinCloud();
   const uploadFile = cloud?.uploadFile;
   if (!uploadFile) {
-    const envID = getDouyinCloudEnvID();
+    const envID = useDevPreviewCloud ? DOUYIN_CLOUD_DEV_ENV_ID : getDouyinCloudEnvID();
+    const envIDName = useDevPreviewCloud ? "douyin_cloud_dev_env_id" : getDouyinCloudEnvIDName();
     const error = {
       errMsg: envID
         ? "request:fail douyin cloud uploadFile is unavailable"
-        : `request:fail ${getDouyinCloudEnvIDName()} is required for createCloud`,
+        : `request:fail ${envIDName} is required for createCloud`,
     };
     option.fail?.(error as never);
     option.complete?.(error as never);
-    return Promise.reject(error) as ReturnType<typeof Taro.request>;
+    return Promise.reject(error);
   }
 
   const requestPromise = (async () => {
@@ -307,7 +313,7 @@ export const uploadByDouyinContainer = (option: Taro.uploadFile.Option) => {
     );
   })();
 
-  return requestPromise as ReturnType<typeof Taro.request>;
+  return requestPromise;
 };
 
 export const downloadByDouyinContainer = (option: Taro.downloadFile.Option) => {

package/src/runtime/globals.d.ts

@@ -42,7 +42,7 @@ type DouyinCallContainerFailResult = {
   errMsg?: string;
 };
 
-type DouyinCloudInstance = {
+type DouyinMiniProgramCloudInstance = {
   callContainer?: <T = unknown>(options: {
     path: string;
     id?: string;
@@ -165,7 +165,7 @@ type DouyinMiniProgramRuntime = {
   createCloud?: (options: {
     envID: string;
     serviceID?: string;
-  }) => DouyinCloudInstance;
+  }) => DouyinMiniProgramCloudInstance;
   login?: (options: {
     success?: (result: { code?: string; errMsg?: string }) => void;
     fail?: (result: { errMsg?: string }) => void;

package/src/runtime/image-upload-preparation.ts

@@ -0,0 +1,225 @@
+import { isDouyinMiniProgram } from './douyin-container-request'
+
+const MIB = 1024 * 1024
+const TARGET_BYTES = 2 * MIB
+const LARGE_IMAGE_BYTES = 10 * MIB
+const MAX_SOURCE_BYTES = 32 * MIB
+const MAX_SOURCE_PIXELS = 24_000_000
+const MAX_LARGE_SOURCE_PIXELS = 40_000_000
+const PREPARATION_BUDGET_MS = 1500
+const MAX_OUTPUT_RATIO = 0.9
+const PREPARED_PATH_TTL_MS = 5000
+
+type NativeCallbacks<T> = {
+  success: (result: T) => void
+  fail: (error: unknown) => void
+}
+
+type NativeImageInfo = {
+  type?: string
+  width?: number
+  height?: number
+  orientation?: string
+}
+
+type NativeFileStat = { size?: number, lastModifiedTime?: number }
+type NativeFileSystem = {
+  stat?: (options: NativeCallbacks<{ stats?: NativeFileStat }> & { path: string }) => void
+}
+
+declare const tt: {
+  getFileSystemManager?: () => NativeFileSystem
+  getImageInfo?: (options: NativeCallbacks<NativeImageInfo> & { src: string }) => void
+  compressImage?: (options: NativeCallbacks<{ tempFilePath?: string }> & { src: string, quality: number }) => void
+} | undefined
+
+/**
+ * @desc 图片上传应使用的本地路径，以及可取得的压缩诊断信息。
+ * @example
+ * ```ts
+ * const { filePath, reason } = await prepareImageForUpload(tempFilePath)
+ * ```
+ * @ai-intent 读取静默压缩选出的路径和诊断信息。
+ * @ai-when 既有调用方需要读取显式预处理的结果时。
+ * @ai-avoid 不要把压缩诊断用作上传错误或用户提示。
+ * @ai-example const { filePath, reason } = await prepareImageForUpload(tempFilePath)
+ */
+export interface PreparedImageForUpload {
+  /** @desc 最终上传使用的本地文件路径。 */
+  filePath: string
+  /** @desc 原文件实际大小，单位字节。未取得时为 undefined。 */
+  originalBytes?: number
+  /** @desc 最终文件实际大小，单位字节。未取得时为 undefined。 */
+  bytes?: number
+  /** @desc 压缩采用或使用原文件的原因。 */
+  reason: 'compressed' | 'below-target' | 'unsupported' | 'not-jpeg' | 'input-budget'
+    | 'busy' | 'invalid-image' | 'no-benefit' | 'timeout' | 'failed'
+}
+
+let preparationInProgress = false
+type PreparedFile = { filePath: string, bytes: number, lastModifiedTime?: number }
+let lastManuallyPrepared: (PreparedFile & { expiresAt: number }) | undefined
+
+function callNative<T>(invoke: (callbacks: NativeCallbacks<T>) => void): Promise<T> {
+  return new Promise((success, fail) => invoke({ success, fail }))
+}
+
+function isJpeg(type: string | undefined): boolean {
+  return /^jpe?g$/i.test(type ?? '')
+}
+
+export function canPrepareImageForUpload(filePath: unknown): filePath is string {
+  // 只检查宿主本地文件，避免 getImageInfo 下载远程路径。
+  if (typeof filePath !== 'string' || !/^ttfile:\/\/(?:temp|user)\//.test(filePath)
+    || typeof tt === 'undefined') return false
+  try {
+    return isDouyinMiniProgram()
+      && typeof tt.getImageInfo === 'function' && typeof tt.compressImage === 'function'
+      && typeof tt.getFileSystemManager === 'function'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @desc 显式预处理本地 JPEG，返回上传路径和诊断信息。
+ * @param {string} filePath 选图或拍摄获得的本地文件路径。
+ * @returns {Promise<PreparedImageForUpload>} 上传路径及诊断信息，降级时返回原路径。
+ * @remarks Network.uploadFile 会自动预处理符合条件的 JPEG。此方法兼容已有显式调用。压缩结果由宿主临时保存，能力缺失或超时时沿用原路径或已验证的候选。
+ * @example
+ * ```ts
+ * const prepared = await prepareImageForUpload(tempFilePath)
+ * console.log(prepared.bytes, prepared.reason)
+ * ```
+ * @ai-intent 兼容已有的本地 JPEG 显式预处理。
+ * @ai-when 维护已使用显式预处理或需要其诊断信息的调用方时。
+ * @ai-avoid 不要为使用新版 Network.uploadFile 的新业务再接一层手动预处理。
+ * @ai-example const prepared = await prepareImageForUpload(tempFilePath)
+ */
+export function prepareImageForUpload(filePath: string): Promise<PreparedImageForUpload> {
+  return prepareImage(filePath, false)
+}
+
+export async function prepareUploadFilePath(filePath: string): Promise<string> {
+  return (await prepareImage(filePath, true)).filePath
+}
+
+async function prepareImage(filePath: string, forUpload: boolean): Promise<PreparedImageForUpload> {
+  let originalBytes: number | undefined
+  let best: PreparedFile | undefined
+  const result = (reason: PreparedImageForUpload['reason']): PreparedImageForUpload =>
+    best ? { filePath: best.filePath, bytes: best.bytes, originalBytes, reason: 'compressed' }
+      : { filePath, originalBytes, bytes: originalBytes, reason }
+
+  if (!canPrepareImageForUpload(filePath) || !tt) return result('unsupported')
+  if (preparationInProgress) return result('busy')
+
+  const deadline = Date.now() + PREPARATION_BUDGET_MS
+  const expired = () => Date.now() >= deadline
+  const runtime = tt
+  let timer: ReturnType<typeof setTimeout> | undefined
+  preparationInProgress = true
+
+  const prepare = async () => {
+    try {
+      const fs = runtime.getFileSystemManager?.()
+      if (!fs?.stat || !runtime.getImageInfo || !runtime.compressImage) return result('unsupported')
+      const stat = fs.stat.bind(fs)
+      const getInfo = runtime.getImageInfo.bind(runtime)
+      const compress = runtime.compressImage.bind(runtime)
+      const readStat = async (path: string) => {
+        const { stats } = await callNative<{ stats?: NativeFileStat }>(callbacks => stat({ ...callbacks, path }))
+        const size = stats?.size
+        return size && Number.isSafeInteger(size) && size > 0
+          ? { bytes: size, lastModifiedTime: stats?.lastModifiedTime }
+          : undefined
+      }
+      const readInfo = (src: string) =>
+        callNative<NativeImageInfo>(callbacks => getInfo({ ...callbacks, src }))
+
+      if (expired()) return result('timeout')
+      const original = await readStat(filePath)
+      originalBytes = original?.bytes
+      if (expired()) return result('timeout')
+      if (originalBytes === undefined) return result('invalid-image')
+      if (forUpload && lastManuallyPrepared?.filePath === filePath) {
+        const prepared = lastManuallyPrepared
+        lastManuallyPrepared = undefined
+        if (Date.now() < prepared.expiresAt && originalBytes === prepared.bytes
+          && original?.lastModifiedTime === prepared.lastModifiedTime) return result('compressed')
+      }
+      if (originalBytes <= TARGET_BYTES) return result('below-target')
+      if (originalBytes > MAX_SOURCE_BYTES) return result('input-budget')
+
+      const source = await readInfo(filePath)
+      if (expired()) return result('timeout')
+      if (!isJpeg(source.type)) return result(source.type ? 'not-jpeg' : 'invalid-image')
+      const { width, height, orientation } = source
+      if (!width || !height || !Number.isSafeInteger(width) || !Number.isSafeInteger(height)
+        || width < 0 || height < 0) return result('invalid-image')
+      const isLargeImage = originalBytes > LARGE_IMAGE_BYTES
+      const maxSourcePixels = isLargeImage ? MAX_LARGE_SOURCE_PIXELS : MAX_SOURCE_PIXELS
+      if (width * height > maxSourcePixels) return result('input-budget')
+      // 大图允许尝试常见的 EXIF 旋转，候选必须保留同样的宽高和方向才能上传。
+      const hasKnownRotation = orientation === 'left' || orientation === 'right' || orientation === 'down'
+      if (orientation !== 'up' && !(isLargeImage && hasKnownRotation)) return result('unsupported')
+
+      const qualities = isLargeImage ? [65, 50] : [85, 75]
+      let completedAttempt = false
+      for (const quality of qualities) {
+        if (expired()) return result('timeout')
+        // 宿主可能复用临时路径。下一次编码返回不同路径前，上一候选不能用于上传。
+        const previousBest = best
+        if (previousBest) completedAttempt = false
+        best = undefined
+        // 宿主可能覆盖此前显式预处理的临时文件，开始编码前使记录失效。
+        lastManuallyPrepared = undefined
+        try {
+          const { tempFilePath } = await callNative<{ tempFilePath?: string }>(callbacks =>
+            compress({ ...callbacks, src: filePath, quality }),
+          )
+          // 宿主临时目录只读。超时晚到的结果不会上传，文件由宿主回收。
+          if (expired()) return result('timeout')
+          if (!tempFilePath || tempFilePath === filePath || !/^ttfile:\/\/temp\//.test(tempFilePath)) continue
+          if (previousBest && tempFilePath !== previousBest.filePath) best = previousBest
+          const output = await readStat(tempFilePath)
+          if (expired()) return result('timeout')
+          if (!output) continue
+          const { bytes } = output
+          if (bytes > originalBytes * MAX_OUTPUT_RATIO || (best && bytes >= best.bytes)) {
+            completedAttempt = true
+            continue
+          }
+          const candidate = await readInfo(tempFilePath)
+          if (expired()) return result('timeout')
+          if (!isJpeg(candidate.type) || candidate.width !== width || candidate.height !== height
+            || candidate.orientation !== orientation) continue
+          completedAttempt = true
+          best = { filePath: tempFilePath, ...output }
+          if (bytes <= TARGET_BYTES) break
+        } catch {
+          // 宿主单次处理失败时，仍可用剩余预算或已验证的候选。
+        }
+      }
+      return result(expired() ? 'timeout' : completedAttempt ? 'no-benefit' : 'failed')
+    } catch {
+      return result(expired() ? 'timeout' : 'failed')
+    } finally {
+      preparationInProgress = false
+    }
+  }
+
+  const timeout = new Promise<PreparedImageForUpload>(resolve => {
+    timer = setTimeout(() => resolve(result('timeout')), PREPARATION_BUDGET_MS)
+  })
+  // 等待预算只影响调用方。宿主仍在处理时继续占用唯一名额。
+  try {
+    const prepared = await Promise.race([prepare(), timeout])
+    if (!forUpload && best) {
+      lastManuallyPrepared = { ...best, expiresAt: Date.now() + PREPARED_PATH_TTL_MS }
+    }
+    return prepared
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/runtime/index.ts

@@ -2,3 +2,4 @@ export { createMicroappClient } from './default-client'
 export { type CreateMicroappClientOptions } from './client'
 export { clearDouyinLoginAuth } from './douyin-login-request'
 export { syncIframeAuth } from './default-iframe-auth'
+export { prepareImageForUpload, type PreparedImageForUpload } from './image-upload-preparation'

package/src/runtime/prepared-upload-task.ts

@@ -0,0 +1,86 @@
+type UploadTask = ReturnType<typeof Taro.uploadFile>
+type ProgressCallback = Parameters<UploadTask['onProgressUpdate']>[0]
+type HeadersCallback = Parameters<UploadTask['onHeadersReceived']>[0]
+
+export function startPreparedUploadTask(
+  option: Taro.uploadFile.Option,
+  preparedPath: Promise<string>,
+  start: (option: Taro.uploadFile.Option) => UploadTask,
+): UploadTask {
+  let nativeTask: UploadTask | undefined
+  let abortBeforeStart: (() => void) | undefined
+  const progressListeners = new Set<ProgressCallback>()
+  const headersListeners = new Set<HeadersCallback>()
+
+  const onProgressUpdate = (callback: ProgressCallback) => {
+    if (nativeTask?.onProgressUpdate) nativeTask.onProgressUpdate(callback)
+    else if (nativeTask) nativeTask.progress?.(callback)
+    else if (abortBeforeStart) progressListeners.add(callback)
+  }
+  const onHeadersReceived = (callback: HeadersCallback) => {
+    if (nativeTask?.onHeadersReceived) nativeTask.onHeadersReceived(callback)
+    else if (nativeTask) nativeTask.headersReceive?.(callback)
+    else if (abortBeforeStart) headersListeners.add(callback)
+  }
+  const clearListeners = () => {
+    progressListeners.clear()
+    headersListeners.clear()
+  }
+
+  const promise = new Promise<Taro.uploadFile.SuccessCallbackResult>((resolve, reject) => {
+    abortBeforeStart = () => {
+      abortBeforeStart = undefined
+      clearListeners()
+      const error = { errMsg: 'uploadFile:fail upload file abort', errNo: 121905 }
+      reject(error)
+      try {
+        option.fail?.(error)
+      } finally {
+        option.complete?.(error)
+      }
+    }
+
+    void preparedPath.catch(() => option.filePath).then(filePath => {
+      if (!abortBeforeStart) return
+      abortBeforeStart = undefined
+      try {
+        nativeTask = start({ ...option, filePath })
+        resolve(nativeTask)
+        progressListeners.forEach(onProgressUpdate)
+        headersListeners.forEach(onHeadersReceived)
+      } finally {
+        clearListeners()
+      }
+    }).catch(reject)
+  })
+
+  const task: UploadTask = Object.assign(promise, {
+    abort(callback?: () => void) {
+      if (nativeTask || abortBeforeStart) callback?.()
+      if (nativeTask) nativeTask.abort?.()
+      else abortBeforeStart?.()
+      return task
+    },
+    onProgressUpdate,
+    offProgressUpdate(callback: ProgressCallback) {
+      if (callback) progressListeners.delete(callback)
+      else progressListeners.clear()
+      nativeTask?.offProgressUpdate?.(callback)
+    },
+    onHeadersReceived,
+    offHeadersReceived(callback: HeadersCallback) {
+      if (callback) headersListeners.delete(callback)
+      else headersListeners.clear()
+      nativeTask?.offHeadersReceived?.(callback)
+    },
+    progress(callback: ProgressCallback) {
+      onProgressUpdate(callback)
+      return task
+    },
+    headersReceive(callback: HeadersCallback) {
+      onHeadersReceived(callback)
+      return task
+    },
+  })
+  return task
+}