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

package/dist/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/dist/adapters/interest-card/runtime/microapp.d.ts

@@ -4,4 +4,4 @@
  * 此适配层只提供稳定的兴趣卡导入路径；请求、登录和传输能力仍由通用
  * microapp Runtime 实现，避免在业务域内复制基础逻辑。
  */
-export { clearDouyinLoginAuth, createMicroappClient, type CreateMicroappClientOptions, } from '../../../runtime/index.js';
+export { clearDouyinLoginAuth, createMicroappClient, prepareImageForUpload, type CreateMicroappClientOptions, type PreparedImageForUpload, } from '../../../runtime/index.js';

package/dist/adapters/interest-card/runtime/microapp.js

@@ -4,5 +4,5 @@
  * 此适配层只提供稳定的兴趣卡导入路径；请求、登录和传输能力仍由通用
  * microapp Runtime 实现，避免在业务域内复制基础逻辑。
  */
-export { clearDouyinLoginAuth, createMicroappClient, } from '../../../runtime/index.js';
+export { clearDouyinLoginAuth, createMicroappClient, prepareImageForUpload, } from '../../../runtime/index.js';
 //# sourceMappingURL=microapp.js.map

package/dist/adapters/interest-card/runtime/microapp.js.map

@@ -1 +1 @@
-{"version":3,"file":"microapp.js","sourceRoot":"","sources":["../../../../src/adapters/interest-card/runtime/microapp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,2BAA2B,CAAA"}
+{"version":3,"file":"microapp.js","sourceRoot":"","sources":["../../../../src/adapters/interest-card/runtime/microapp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,GAGtB,MAAM,2BAA2B,CAAA"}

package/dist/eslint/card-profile.mjs

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * @desc 校验卡片形态；缺少字段保留历史兴趣卡语义，不写回配置。
+ * @params {object} config 已解析的工程配置。
+ * @params {string} [source] 错误信息中的配置来源。
+ * @return {'interest'|'post'} 卡片形态。
+ * @example parseCardType({ cardType: 'post' })
+ */
+export function parseCardType(config, source = 'card-routing.json') {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`${source} must contain an object`)
+  }
+  if (!Object.hasOwn(config, 'cardType')) return 'interest'
+  if (config.cardType !== 'interest' && config.cardType !== 'post') {
+    throw new Error(`${source}: cardType must be interest or post; got ${JSON.stringify(config.cardType)}`)
+  }
+  return config.cardType
+}
+
+/**
+ * @desc 从明确的宿主工程目录读取形态，供 CLI 与两端 SDK 共用。
+ * @params {{projectRoot: string}} options 宿主工程绝对路径；OpenCard 配置也传宿主目录。
+ * @return {{cardType: 'interest'|'post', configPath: string}} 形态及配置来源。
+ * @example readCardProfile({ projectRoot: '/workspace/project/card-app' })
+ */
+export function readCardProfile({ projectRoot }) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+    throw new Error('readCardProfile requires an absolute projectRoot')
+  }
+  const configPath = path.join(projectRoot, 'config/card-routing.json')
+  let raw
+  try {
+    raw = readFileSync(configPath, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { cardType: 'interest', configPath }
+    throw error
+  }
+  let config
+  try {
+    config = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${configPath} must contain valid JSON: ${error.message}`)
+  }
+  return { cardType: parseCardType(config, configPath), configPath }
+}
+
+function findEslintHost(filename, target) {
+  let directory = path.dirname(filename)
+  while (true) {
+    // Stop at the owning package/config instead of inheriting another project's
+    // routing. An OpenCard package belongs to its immediate host directory.
+    if (existsSync(path.join(directory, 'package.json')) ||
+        existsSync(path.join(directory, 'eslint.config.mjs')) ||
+        existsSync(path.join(directory, 'project.card.json'))) {
+      return target === 'opencard' ? path.dirname(directory) : directory
+    }
+    if (existsSync(path.join(directory, '.git'))) return undefined
+    const parent = path.dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/**
+ * @desc 创建作品卡文件匹配器；CLI 传入形态，直接 ESLint 从待检查文件定位工程。
+ * @params {{cardType?: 'interest'|'post', target: 'taro'|'opencard'}} options SDK 配置及目标端。
+ * @params {object} [environment] CLI 子进程环境。
+ * @return {(filename: string) => boolean} 是否启用作品卡配置。
+ * @example createPostCardMatcher({ target: 'taro' })('/workspace/app/src/index.ts')
+ */
+export function createPostCardMatcher(options, environment = process.env) {
+  const configured = options.cardType ?? environment.VIBECODING_CARD_TYPE
+  // An explicitly supplied null must not silently fall back to legacy rules.
+  const explicit = options.cardType !== undefined
+  if (explicit || configured !== undefined) {
+    const cardType = parseCardType({ cardType: explicit ? options.cardType : configured }, 'ESLint cardType')
+    return () => cardType === 'post'
+  }
+  return filename => {
+    const projectRoot = findEslintHost(filename, options.target)
+    return projectRoot ? readCardProfile({ projectRoot }).cardType === 'post' : false
+  }
+}
+
+// The legacy shell entry uses the same parser as the SDK-owned ESLint configs.
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    console.log(readCardProfile({ projectRoot: path.resolve(process.argv[2]) }).cardType)
+  } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}

package/dist/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/dist/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/dist/reference/llms.txt

@@ -14,7 +14,9 @@ Companion libraries are separate project dependencies, imported from their own p
 ## APIs
 
 - [createMicroappClient](./sdk-api/runtime/createMicroappClient.md): 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
-- [CreateMicroappClientOptions](./sdk-api/runtime/CreateMicroappClientOptions.md): 配置普通小程序 Network 的平台渠道。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
+- [CreateMicroappClientOptions](./sdk-api/runtime/CreateMicroappClientOptions.md): 配置普通小程序 Network 的平台渠道和真机预览上传环境。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
+- [prepareImageForUpload](./sdk-api/runtime/prepareImageForUpload.md): 显式预处理本地 JPEG，返回上传路径和诊断信息。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
+- [PreparedImageForUpload](./sdk-api/runtime/PreparedImageForUpload.md): 图片上传应使用的本地路径，以及可取得的压缩诊断信息。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
 - [MiniappOpenCard](./sdk-api/components/miniapp-open-card/MiniappOpenCard.md): 承载同一 OpenCard；SDK 选择环境版本并为空初始化参数提供对象，错误类型直接报错。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
 - [MiniappOpenCardProps](./sdk-api/components/miniapp-open-card/MiniappOpenCardProps.md): 普通 Taro 宿主的内嵌卡属性；沿用 StandardProps，但不接受 children 或 envVersion。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
 - [MiniappOpenCardErrorDetail](./sdk-api/components/miniapp-open-card/MiniappOpenCardErrorDetail.md): 内嵌卡加载错误的事件 detail；可选错误字段由平台提供。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.

package/dist/reference/sdk-api/runtime/CreateMicroappClientOptions.md

@@ -7,7 +7,7 @@
 
 #### 说明
 
-配置普通小程序 Network 的平台渠道。
+配置普通小程序 Network 的平台渠道和真机预览上传环境。
 
 示例：
 
@@ -34,6 +34,7 @@ const options = { platformChannel: 'ext' as const }
 ```ts
 export interface CreateMicroappClientOptions {
     platformChannel?: '' | 'ext';
+    previewUploadEnvType?: 'development';
 }
 ```
 
@@ -50,3 +51,4 @@ CreateMicroappClientOptions
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | platformChannel? | `"" \| "ext" \| undefined` | 平台渠道：空字符串为内场，ext 为外场；默认空字符串。 |
+| previewUploadEnvType? | `"development" \| undefined` | 设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。 |

package/dist/reference/sdk-api/runtime/PreparedImageForUpload.md

@@ -0,0 +1,52 @@
+# PreparedImageForUpload
+
+<!-- Generated by packages/sdk-tooling/src/reference/skill-reference.ts. Do not edit. -->
+
+导入路径：`@open-dy/vibecoding-sdk-taro/runtime`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/runtime/image-upload-preparation.ts`（仅补缺或排错时读取）。
+
+#### 说明
+
+图片上传应使用的本地路径，以及可取得的压缩诊断信息。
+
+示例：
+
+```ts
+const { filePath, reason } = await prepareImageForUpload(tempFilePath)
+```
+
+#### AI 使用约束
+
+| 规则 | 内容 |
+| --- | --- |
+| 意图 | 读取静默压缩选出的路径和诊断信息。 |
+| 适用时机 | 既有调用方需要读取显式预处理的结果时。 |
+| 避免 | 不要把压缩诊断用作上传错误或用户提示。 |
+
+#### 声明
+
+```ts
+export interface PreparedImageForUpload {
+    filePath: string;
+    originalBytes?: number;
+    bytes?: number;
+    reason: 'compressed' | 'below-target' | 'unsupported' | 'not-jpeg' | 'input-budget' | 'busy' | 'invalid-image' | 'no-benefit' | 'timeout' | 'failed';
+}
+```
+
+### PreparedImageForUpload 的类型契约
+
+#### 类型
+
+```ts
+PreparedImageForUpload
+```
+
+#### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath | `string` | 最终上传使用的本地文件路径。 |
+| originalBytes? | `number \| undefined` | 原文件实际大小，单位字节。未取得时为 undefined。 |
+| bytes? | `number \| undefined` | 最终文件实际大小，单位字节。未取得时为 undefined。 |
+| reason | `"timeout" \| "compressed" \| "below-target" \| "unsupported" \| "not-jpeg" \| "input-budget" \| "busy" \| "invalid-image" \| "no-benefit" \| "failed"` | 压缩采用或使用原文件的原因。 |

package/dist/reference/sdk-api/runtime/createMicroappClient.md

@@ -13,11 +13,11 @@
 
 | 名称 | 说明 |
 | --- | --- |
-| `options` | 平台渠道配置；默认使用内场渠道。 |
+| `options` | 平台渠道和真机预览上传环境配置。默认使用内场渠道。 |
 
 返回：仅提供普通小程序的 request、uploadFile、downloadFile 和 streamSse。
 
-备注：业务优先从模板的 @/network 导入 Network；HTTP(S) 绝对地址直接交给 Taro。宿主需要封闭域功能时通过 MiniappOpenCard 承载，请求与数据处理仅在卡内完成。streamSse 返回的是流句柄，Promise resolve 不代表生成完成。正常关闭仅调用一次 onComplete；流错误仅调用一次 onError(Error)，随后释放任务；close() 主动取消仅调用一次可选的 onCancel，不调用 onComplete/onError。业务须在对应终态回调中清理 loading，不能把 onComplete 当通用 finally；终态后的消息与重复事件会被忽略。创建任务前的失败仍通过 Promise rejection 交付。
+备注：业务优先从模板的 @/network 导入 Network。uploadFile 在支持原生图片处理的抖音小程序中自动尝试压缩符合条件的本地 JPEG，各上传路由均适用。业务直接传入原始 filePath。HTTP(S) 绝对地址仍由 Taro 传输。宿主需要封闭域功能时通过 MiniappOpenCard 承载，请求与数据处理仅在卡内完成。streamSse 返回的是流句柄，Promise resolve 不代表生成完成。正常关闭仅调用一次 onComplete；流错误仅调用一次 onError(Error)，随后释放任务；close() 主动取消仅调用一次可选的 onCancel，不调用 onComplete/onError。业务须在对应终态回调中清理 loading，不能把 onComplete 当通用 finally；终态后的消息与重复事件会被忽略。创建任务前的失败仍通过 Promise rejection 交付。
 
 示例：
 
@@ -61,13 +61,14 @@ function createMicroappClient(options?: CreateMicroappClientOptions);
 
 | 参数 | 类型 | 说明 |
 | --- | --- | --- |
-| options? | `CreateMicroappClientOptions` | 平台渠道配置；默认使用内场渠道。 |
+| options? | `CreateMicroappClientOptions` | 平台渠道和真机预览上传环境配置。默认使用内场渠道。 |
 
 ##### options 字段
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | platformChannel? | `"" \| "ext" \| undefined` | 平台渠道：空字符串为内场，ext 为外场；默认空字符串。 |
+| previewUploadEnvType? | `"development" \| undefined` | 设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。 |
 
 #### 返回值
 

package/dist/reference/sdk-api/runtime/index.md

@@ -7,4 +7,6 @@
 | API | 说明 | 文档 |
 | --- | --- | --- |
 | `createMicroappClient` | 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。 | [查看](./createMicroappClient.md) |
-| `CreateMicroappClientOptions` | 配置普通小程序 Network 的平台渠道。 | [查看](./CreateMicroappClientOptions.md) |
+| `CreateMicroappClientOptions` | 配置普通小程序 Network 的平台渠道和真机预览上传环境。 | [查看](./CreateMicroappClientOptions.md) |
+| `prepareImageForUpload` | 显式预处理本地 JPEG，返回上传路径和诊断信息。 | [查看](./prepareImageForUpload.md) |
+| `PreparedImageForUpload` | 图片上传应使用的本地路径，以及可取得的压缩诊断信息。 | [查看](./PreparedImageForUpload.md) |

package/dist/reference/sdk-api/runtime/prepareImageForUpload.md

@@ -0,0 +1,69 @@
+# prepareImageForUpload
+
+<!-- Generated by packages/sdk-tooling/src/reference/skill-reference.ts. Do not edit. -->
+
+导入路径：`@open-dy/vibecoding-sdk-taro/runtime`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/runtime/image-upload-preparation.ts`（仅补缺或排错时读取）。
+
+#### 说明
+
+显式预处理本地 JPEG，返回上传路径和诊断信息。
+
+返回：上传路径及诊断信息，降级时返回原路径。
+
+备注：Network.uploadFile 会自动预处理符合条件的 JPEG。此方法兼容已有显式调用。压缩结果由宿主临时保存，能力缺失或超时时沿用原路径或已验证的候选。
+
+示例：
+
+```ts
+const prepared = await prepareImageForUpload(tempFilePath)
+console.log(prepared.bytes, prepared.reason)
+```
+
+#### AI 使用约束
+
+| 规则 | 内容 |
+| --- | --- |
+| 意图 | 兼容已有的本地 JPEG 显式预处理。 |
+| 适用时机 | 维护已使用显式预处理或需要其诊断信息的调用方时。 |
+| 避免 | 不要为使用新版 Network.uploadFile 的新业务再接一层手动预处理。 |
+
+示例：
+
+```ts
+const prepared = await prepareImageForUpload(tempFilePath)
+```
+
+#### 声明
+
+```ts
+function prepareImageForUpload(filePath: string): Promise<PreparedImageForUpload>;
+```
+
+### prepareImageForUpload 的类型契约
+
+#### 工厂签名
+
+```ts
+(filePath: string): Promise<PreparedImageForUpload>
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath | `string` | 选图或拍摄获得的本地文件路径。 |
+
+#### 返回值
+
+- 类型：`Promise<PreparedImageForUpload>`
+- Promise resolve 类型：`PreparedImageForUpload`
+
+##### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath | `string` | 最终上传使用的本地文件路径。 |
+| originalBytes? | `number \| undefined` | 原文件实际大小，单位字节。未取得时为 undefined。 |
+| bytes? | `number \| undefined` | 最终文件实际大小，单位字节。未取得时为 undefined。 |
+| reason | `"timeout" \| "compressed" \| "below-target" \| "unsupported" \| "not-jpeg" \| "input-budget" \| "busy" \| "invalid-image" \| "no-benefit" \| "failed"` | 压缩采用或使用原文件的原因。 |

package/dist/reference/sdk-api.json

@@ -99,12 +99,12 @@
         "parameters": [
           {
             "name": "options",
-            "description": "平台渠道配置；默认使用内场渠道。"
+            "description": "平台渠道和真机预览上传环境配置。默认使用内场渠道。"
           }
         ],
         "returns": "仅提供普通小程序的 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 交付。"
+          "业务优先从模板的 @/network 导入 Network。uploadFile 在支持原生图片处理的抖音小程序中自动尝试压缩符合条件的本地 JPEG，各上传路由均适用。业务直接传入原始 filePath。HTTP(S) 绝对地址仍由 Taro 传输。宿主需要封闭域功能时通过 MiniappOpenCard 承载，请求与数据处理仅在卡内完成。streamSse 返回的是流句柄，Promise resolve 不代表生成完成。正常关闭仅调用一次 onComplete；流错误仅调用一次 onError(Error)，随后释放任务；close() 主动取消仅调用一次可选的 onCancel，不调用 onComplete/onError。业务须在对应终态回调中清理 loading，不能把 onComplete 当通用 finally；终态后的消息与重复事件会被忽略。创建任务前的失败仍通过 Promise rejection 交付。"
         ],
         "examples": [
           {
@@ -128,13 +128,19 @@
             "name": "options",
             "optional": true,
             "type": "CreateMicroappClientOptions",
-            "description": "平台渠道配置；默认使用内场渠道。",
+            "description": "平台渠道和真机预览上传环境配置。默认使用内场渠道。",
             "fields": [
               {
                 "name": "platformChannel",
                 "optional": true,
                 "type": "\"\" | \"ext\" | undefined",
                 "description": "平台渠道：空字符串为内场，ext 为外场；默认空字符串。"
+              },
+              {
+                "name": "previewUploadEnvType",
+                "optional": true,
+                "type": "\"development\" | undefined",
+                "description": "设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。"
               }
             ]
           }
@@ -734,9 +740,9 @@
       "importPath": "@open-dy/vibecoding-sdk-taro/runtime",
       "source": "src/runtime/client.ts",
       "docPath": "sdk-api/runtime/CreateMicroappClientOptions.md",
-      "summary": "配置普通小程序 Network 的平台渠道。",
+      "summary": "配置普通小程序 Network 的平台渠道和真机预览上传环境。",
       "documentation": {
-        "summary": "配置普通小程序 Network 的平台渠道。",
+        "summary": "配置普通小程序 Network 的平台渠道和真机预览上传环境。",
         "examples": [
           {
             "language": "ts",
@@ -750,7 +756,7 @@
         "avoid": "不要在业务页面直接拼接渠道请求头。",
         "example": "{ platformChannel: 'ext' }"
       },
-      "signature": "export interface CreateMicroappClientOptions {\n    platformChannel?: '' | 'ext';\n}",
+      "signature": "export interface CreateMicroappClientOptions {\n    platformChannel?: '' | 'ext';\n    previewUploadEnvType?: 'development';\n}",
       "contract": {
         "kind": "type",
         "type": "CreateMicroappClientOptions",
@@ -760,6 +766,138 @@
             "optional": true,
             "type": "\"\" | \"ext\" | undefined",
             "description": "平台渠道：空字符串为内场，ext 为外场；默认空字符串。"
+          },
+          {
+            "name": "previewUploadEnvType",
+            "optional": true,
+            "type": "\"development\" | undefined",
+            "description": "设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。"
+          }
+        ]
+      }
+    },
+    {
+      "id": "runtime.prepareImageForUpload",
+      "name": "prepareImageForUpload",
+      "importPath": "@open-dy/vibecoding-sdk-taro/runtime",
+      "source": "src/runtime/image-upload-preparation.ts",
+      "docPath": "sdk-api/runtime/prepareImageForUpload.md",
+      "summary": "显式预处理本地 JPEG，返回上传路径和诊断信息。",
+      "documentation": {
+        "summary": "显式预处理本地 JPEG，返回上传路径和诊断信息。",
+        "returns": "上传路径及诊断信息，降级时返回原路径。",
+        "remarks": [
+          "Network.uploadFile 会自动预处理符合条件的 JPEG。此方法兼容已有显式调用。压缩结果由宿主临时保存，能力缺失或超时时沿用原路径或已验证的候选。"
+        ],
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const prepared = await prepareImageForUpload(tempFilePath)\nconsole.log(prepared.bytes, prepared.reason)"
+          }
+        ]
+      },
+      "ai": {
+        "intent": "兼容已有的本地 JPEG 显式预处理。",
+        "when": "维护已使用显式预处理或需要其诊断信息的调用方时。",
+        "avoid": "不要为使用新版 Network.uploadFile 的新业务再接一层手动预处理。",
+        "example": "const prepared = await prepareImageForUpload(tempFilePath)"
+      },
+      "signature": "function prepareImageForUpload(filePath: string): Promise<PreparedImageForUpload>;",
+      "contract": {
+        "kind": "callable",
+        "signature": "(filePath: string): Promise<PreparedImageForUpload>",
+        "parameters": [
+          {
+            "name": "filePath",
+            "optional": false,
+            "type": "string",
+            "description": "选图或拍摄获得的本地文件路径。"
+          }
+        ],
+        "returns": {
+          "type": "Promise<PreparedImageForUpload>",
+          "promise": true,
+          "resolvesTo": "PreparedImageForUpload",
+          "fields": [
+            {
+              "name": "filePath",
+              "optional": false,
+              "type": "string",
+              "description": "最终上传使用的本地文件路径。"
+            },
+            {
+              "name": "originalBytes",
+              "optional": true,
+              "type": "number | undefined",
+              "description": "原文件实际大小，单位字节。未取得时为 undefined。"
+            },
+            {
+              "name": "bytes",
+              "optional": true,
+              "type": "number | undefined",
+              "description": "最终文件实际大小，单位字节。未取得时为 undefined。"
+            },
+            {
+              "name": "reason",
+              "optional": false,
+              "type": "\"timeout\" | \"compressed\" | \"below-target\" | \"unsupported\" | \"not-jpeg\" | \"input-budget\" | \"busy\" | \"invalid-image\" | \"no-benefit\" | \"failed\"",
+              "description": "压缩采用或使用原文件的原因。"
+            }
+          ]
+        },
+        "methods": []
+      }
+    },
+    {
+      "id": "runtime.PreparedImageForUpload",
+      "name": "PreparedImageForUpload",
+      "importPath": "@open-dy/vibecoding-sdk-taro/runtime",
+      "source": "src/runtime/image-upload-preparation.ts",
+      "docPath": "sdk-api/runtime/PreparedImageForUpload.md",
+      "summary": "图片上传应使用的本地路径，以及可取得的压缩诊断信息。",
+      "documentation": {
+        "summary": "图片上传应使用的本地路径，以及可取得的压缩诊断信息。",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const { filePath, reason } = await prepareImageForUpload(tempFilePath)"
+          }
+        ]
+      },
+      "ai": {
+        "intent": "读取静默压缩选出的路径和诊断信息。",
+        "when": "既有调用方需要读取显式预处理的结果时。",
+        "avoid": "不要把压缩诊断用作上传错误或用户提示。",
+        "example": "const { filePath, reason } = await prepareImageForUpload(tempFilePath)"
+      },
+      "signature": "export interface PreparedImageForUpload {\n    filePath: string;\n    originalBytes?: number;\n    bytes?: number;\n    reason: 'compressed' | 'below-target' | 'unsupported' | 'not-jpeg' | 'input-budget' | 'busy' | 'invalid-image' | 'no-benefit' | 'timeout' | 'failed';\n}",
+      "contract": {
+        "kind": "type",
+        "type": "PreparedImageForUpload",
+        "fields": [
+          {
+            "name": "filePath",
+            "optional": false,
+            "type": "string",
+            "description": "最终上传使用的本地文件路径。"
+          },
+          {
+            "name": "originalBytes",
+            "optional": true,
+            "type": "number | undefined",
+            "description": "原文件实际大小，单位字节。未取得时为 undefined。"
+          },
+          {
+            "name": "bytes",
+            "optional": true,
+            "type": "number | undefined",
+            "description": "最终文件实际大小，单位字节。未取得时为 undefined。"
+          },
+          {
+            "name": "reason",
+            "optional": false,
+            "type": "\"timeout\" | \"compressed\" | \"below-target\" | \"unsupported\" | \"not-jpeg\" | \"input-budget\" | \"busy\" | \"invalid-image\" | \"no-benefit\" | \"failed\"",
+            "description": "压缩采用或使用原文件的原因。"
           }
         ]
       }

package/dist/reference/sdk-api.md

@@ -44,6 +44,8 @@
 - [runtime](sdk-api/runtime/index.md)
   - `createMicroappClient`
   - `CreateMicroappClientOptions`
+  - `prepareImageForUpload`
+  - `PreparedImageForUpload`
 - [components/miniapp-open-card](sdk-api/components/miniapp-open-card/index.md)
   - `MiniappOpenCard`
   - `MiniappOpenCardProps`

package/dist/runtime/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * @desc 配置普通小程序 Network 的平台渠道。
+ * @desc 配置普通小程序 Network 的平台渠道和真机预览上传环境。
  * @example
  * ```ts
  * const options = { platformChannel: 'ext' as const }
@@ -12,6 +12,8 @@
 export interface CreateMicroappClientOptions {
     /** @desc 平台渠道：空字符串为内场，ext 为外场；默认空字符串。 */
     platformChannel?: '' | 'ext';
+    /** @desc 设置为 development 时，真机扫码预览的托管上传使用抖音云开发环境。 */
+    previewUploadEnvType?: 'development';
 }
 /**
  * 网络请求模块