@open-dy/vibecoding-sdk-taro 0.1.11 → 0.1.13

package/dist/runtime/prepared-upload-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepared-upload-task.js","sourceRoot":"","sources":["../../src/runtime/prepared-upload-task.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-dy/vibecoding-sdk-taro",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Runtime, UI, build and ESLint capabilities for Douyin Taro templates.",
   "type": "module",
   "files": [

package/release-provenance.json

@@ -2,12 +2,12 @@
   "schema": 1,
   "producer": "vibecoding-sdk-taro",
   "packageName": "@open-dy/vibecoding-sdk-taro",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "source": {
-    "digest": "sha256-65487d3df50200d0d27332e26f04e9d3520d3313d31eae611483a3078b0f658c",
-    "files": 159
+    "digest": "sha256-d7a5401f44161aed968a09decead0697bc0ef1f543626208b3ed2eb4e072df74",
+    "files": 164
   },
-  "payload": "sha256-ff279eab5b08f88997926c9180ecd6a50e8d0f724cf81a76f314f477b116cc40",
+  "payload": "sha256-01638ed4e3da5db1f656bcfca5cddb7a1d23fc14176d366adf563406dfde8d48",
   "toolchain": {
     "node": "v22.22.3",
     "runtime": {

package/src/adapters/interest-card/eslint/taro.mjs

@@ -1,3 +1,4 @@
+export { CARD_TYPE_RULES_VERSION } from '../../../eslint/taro.mjs'
 import { createMicroappTaroEslintConfig } from '../../../eslint/taro.mjs'
 
 /**

package/src/adapters/interest-card/runtime/microapp.ts

@@ -7,5 +7,7 @@
 export {
   clearDouyinLoginAuth,
   createMicroappClient,
+  prepareImageForUpload,
   type CreateMicroappClientOptions,
+  type PreparedImageForUpload,
 } from '../../../runtime/index.js'

package/src/eslint/card-profile.mjs

@@ -0,0 +1,2 @@
+// SDK builds embed this shared, dependency-free module beside the ESLint entry.
+export { createPostCardMatcher } from '../../../vibecoding-cli/src/config/card-profile.mjs'

package/src/eslint/eslint-plugin-post-card.mjs

@@ -0,0 +1,82 @@
+const TARO_SOURCES = new Set(['@tarojs/taro'])
+const TAB_APIS = new Set([
+  'switchTab', 'setTabBarItem', 'setTabBarStyle', 'showTabBar', 'hideTabBar',
+  'setTabBarBadge', 'removeTabBarBadge', 'showTabBarRedDot', 'hideTabBarRedDot',
+  'getTabBar', 'onTabItemTap', 'useTabItemTap',
+])
+
+function key(node) {
+  return node?.type === 'Identifier' ? node.name
+    : node?.type === 'Literal' && typeof node.value === 'string' ? node.value : null
+}
+
+function platformObject(node, context, seen = new Set()) {
+  if (!node || seen.has(node)) return false
+  seen.add(node)
+  if (['TSAsExpression', 'TSNonNullExpression', 'ChainExpression'].includes(node.type)) {
+    return platformObject(node.expression, context, seen)
+  }
+  if (node.type === 'CallExpression') {
+    return node.callee.type === 'Identifier' && node.callee.name === 'require'
+      && TARO_SOURCES.has(node.arguments[0]?.value)
+  }
+  if (node.type === 'MemberExpression') {
+    return ['globalThis', 'window'].includes(node.object?.name)
+      && ['tt', 'Taro'].includes(key(node.property))
+  }
+  if (node.type !== 'Identifier') return false
+  let scope = context.sourceCode.getScope(node)
+  let variable
+  while (scope && !variable) { variable = scope.set.get(node.name); scope = scope.upper }
+  if (!variable?.defs.length) return ['tt', 'Taro'].includes(node.name)
+  return variable.defs.some(def => {
+    if (def.type === 'ImportBinding') {
+      return TARO_SOURCES.has(def.parent?.source?.value)
+        && ['ImportDefaultSpecifier', 'ImportNamespaceSpecifier'].includes(def.node.type)
+    }
+    return def.type === 'Variable' && platformObject(def.node.init, context, seen)
+  })
+}
+
+export default {
+  rules: {
+    'no-platform-tabbar': {
+      meta: { type: 'problem', schema: [], messages: {
+        config: '作品卡不支持平台 tabBar（含 custom 模式）。请用普通组件绘制导航并实现页面或状态切换。',
+        api: '作品卡不支持 {{name}}。请使用普通页面路由或组件状态切换，不调用平台 TabBar。',
+      } },
+      create(context) {
+        const filename = context.filename.replaceAll('\\', '/')
+        const isAppConfig = /\/app\.config\.[cm]?[jt]s$/.test(filename)
+        const report = (node, name) => {
+          if (TAB_APIS.has(name)) context.report({ node, messageId: 'api', data: { name } })
+        }
+        return {
+          Property(node) {
+            if (isAppConfig && key(node.key) === 'tabBar') context.report({ node, messageId: 'config' })
+            if (node.parent.type === 'ObjectPattern' && platformObject(node.parent.parent?.init, context)) {
+              report(node, key(node.key))
+            }
+          },
+          ImportSpecifier(node) {
+            if (node.importKind !== 'type' && node.parent.importKind !== 'type'
+              && TARO_SOURCES.has(node.parent.source.value)) report(node, key(node.imported))
+          },
+          ExportSpecifier(node) {
+            if (TARO_SOURCES.has(node.parent.source?.value)) report(node, key(node.local))
+          },
+          MemberExpression(node) {
+            const name = key(node.property)
+            if (platformObject(node.object, context) || (name === 'getTabBar' && node.object.type === 'ThisExpression')) {
+              report(node, name)
+            }
+          },
+          JSXAttribute(node) {
+            const value = node.value?.type === 'JSXExpressionContainer' ? node.value.expression?.value : node.value?.value
+            if (node.name.name === 'openType' && value === 'switchTab') report(node, 'switchTab')
+          },
+        }
+      },
+    },
+  },
+}

package/src/eslint/taro.mjs

@@ -1,3 +1,6 @@
+import postCard from './eslint-plugin-post-card.mjs';
+import { createPostCardMatcher } from './card-profile.mjs';
+export const CARD_TYPE_RULES_VERSION = 1;
 import eslint from '@eslint/js';
 import { fixupPluginRules } from '@eslint/compat';
 import tseslint from 'typescript-eslint';
@@ -381,6 +384,7 @@ const indexPageRestrictedSyntaxRules = [
 ];
 
 export function createMicroappTaroEslintConfig(options = {}) {
+  const matchesPostCard = createPostCardMatcher({ cardType: options.cardType, target: 'taro' });
   const lucideColorCheckPlugin = createLucideColorCheckPlugin(options.lucideImportSources)
   const pageRestrictedSyntaxRules = createPageRestrictedSyntaxRules(
     options.preferredUiImportBase,
@@ -581,6 +585,12 @@ export function createMicroappTaroEslintConfig(options = {}) {
   },
 );
 
+defaults.push({
+  files: [['src/**/*.{js,jsx,ts,tsx}', matchesPostCard]],
+  settings: { cardType: 'post', cardTypeRulesVersion: CARD_TYPE_RULES_VERSION },
+  plugins: { postCard },
+  rules: { 'postCard/no-platform-tabbar': 'error' },
+});
 const overrides = options.overrides
 if (!overrides) return defaults
 if (typeof overrides === 'function') return overrides(defaults) ?? defaults

package/src/runtime/client.ts

@@ -2,6 +2,7 @@ import {
   canUseDouyinContainer,
   downloadByDouyinContainer,
   isDouyinMiniProgram,
+  isDouyinNativePreviewEnv,
   isDouyinPreviewEnv,
   isWebPreviewEnv,
   requestByDouyinContainer,
@@ -18,10 +19,12 @@ import {
   downloadByDouyinLogin,
 } from './douyin-login-request'
 import { mergeIframeIdentityHeaders } from '../internal/runtime/iframe-auth/index'
-import { appendGetQuery, createUrl } from './network-url'
+import { canPrepareImageForUpload, prepareUploadFilePath } from './image-upload-preparation'
+import { appendGetQuery, createUrl, getManagedUploadError } from './network-url'
+import { startPreparedUploadTask } from './prepared-upload-task'
 
 /**
- * @desc 配置普通小程序 Network 的平台渠道。
+ * @desc 配置普通小程序 Network 的平台渠道和真机预览上传环境。
  * @example
  * ```ts
  * const options = { platformChannel: 'ext' as const }
@@ -34,6 +37,8 @@ import { appendGetQuery, createUrl } from './network-url'
 export interface CreateMicroappClientOptions {
   /** @desc 平台渠道：空字符串为内场，ext 为外场；默认空字符串。 */
   platformChannel?: '' | 'ext'
+  /** @desc 设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。 */
+  previewUploadEnvType?: 'development'
 }
 
 /**
@@ -115,7 +120,7 @@ export function createMicroappClient(
     return promise
   }) as typeof Taro.request
 
-  const uploadFile = ((option: Taro.uploadFile.Option) => {
+  const startUpload = (option: Taro.uploadFile.Option) => {
     if (!option.url) {
       option.url = '';
     }
@@ -126,16 +131,31 @@ export function createMicroappClient(
     if (!option.name) {
       option.name = 'file';
     }
+    if (options.previewUploadEnvType === 'development' && isDouyinNativePreviewEnv()) {
+      return uploadByDouyinContainer(option, options.previewUploadEnvType)
+    }
     if (
       isDouyinMiniProgram() &&
       !isWebPreviewEnv() &&
       !isDouyinPreviewEnv() &&
-      canUseDouyinContainer() &&
-      !/^http(s)?:\/\//.test(option.url)
+      canUseDouyinContainer()
     ) {
       return uploadByDouyinContainer(option)
     }
     return uploadByDouyinLogin(option)
+  }
+
+  const uploadFile = ((option: Taro.uploadFile.Option) => {
+    if (getManagedUploadError(option) || !canPrepareImageForUpload(option.filePath)) {
+      return startUpload(option)
+    }
+
+    const uploadOption = { ...option }
+    const preparedPath = prepareUploadFilePath(uploadOption.filePath)
+    if (/^https?:\/\//.test(uploadOption.url ?? '')) {
+      return startPreparedUploadTask(uploadOption, preparedPath, prepared => taro.uploadFile(prepared))
+    }
+    return preparedPath.then(filePath => startUpload({ ...uploadOption, filePath }))
   }) as (
     option: Omit<Taro.uploadFile.Option, 'url' | 'name'> & { url?: string, name?: string },
   ) => ReturnType<typeof Taro.uploadFile>

package/src/runtime/default-client.ts

@@ -6,9 +6,9 @@ import {
 
 /**
  * @desc 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。
- * @params {CreateMicroappClientOptions} [options] 平台渠道配置；默认使用内场渠道。
+ * @params {CreateMicroappClientOptions} [options] 平台渠道和真机预览上传环境配置。默认使用内场渠道。
  * @return {ReturnType<typeof createMicroappClient>} 仅提供普通小程序的 request、uploadFile、downloadFile 和 streamSse。
- * @remarks 业务优先从模板的 @/network 导入 Network；HTTP(S) 绝对地址直接交给 Taro。宿主需要封闭域功能时通过 MiniappOpenCard 承载，请求与数据处理仅在卡内完成。streamSse 返回的是流句柄，Promise resolve 不代表生成完成。正常关闭仅调用一次 onComplete；流错误仅调用一次 onError(Error)，随后释放任务；close() 主动取消仅调用一次可选的 onCancel，不调用 onComplete/onError。业务须在对应终态回调中清理 loading，不能把 onComplete 当通用 finally；终态后的消息与重复事件会被忽略。创建任务前的失败仍通过 Promise rejection 交付。
+ * @remarks 业务优先从模板的 @/network 导入 Network。uploadFile 在支持原生图片处理的抖音小程序中自动尝试压缩符合条件的本地 JPEG，各上传路由均适用。业务直接传入原始 filePath。HTTP(S) 绝对地址仍由 Taro 传输。宿主需要封闭域功能时通过 MiniappOpenCard 承载，请求与数据处理仅在卡内完成。streamSse 返回的是流句柄，Promise resolve 不代表生成完成。正常关闭仅调用一次 onComplete；流错误仅调用一次 onError(Error)，随后释放任务；close() 主动取消仅调用一次可选的 onCancel，不调用 onComplete/onError。业务须在对应终态回调中清理 loading，不能把 onComplete 当通用 finally；终态后的消息与重复事件会被忽略。创建任务前的失败仍通过 Promise rejection 交付。
  * @example
  * ```ts
  * const Network = createMicroappClient({ platformChannel: 'ext' })

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'