@lingjingai/lj-awb-cli-pre 0.4.0 → 0.4.6

package/packages/awb-core/src/services.js

@@ -3,6 +3,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { promisify } from 'node:util';
 import {
   API_ORIGIN,
@@ -22,10 +23,12 @@ import {
   isSuccessTaskStatus,
   isTerminalTaskStatus,
   loadState,
+  maskSecret,
   normalizeFeedTaskType,
   nowIso,
   parseJsonArg,
   parseListArg,
+  resolvePurchaseUrl,
   safeFileName,
   saveState,
   sleep,
@@ -35,10 +38,11 @@ import {
   toBool,
   toInt,
   toNumberOrNull,
+  trimSecret,
   trimToNull,
   uniqueNonEmpty,
 } from './common.js';
-import { loadAuth, resolveAuthContext, summarizeAuth } from './auth.js';
+import { clearAuth, loadAuth, resolveAuthContext, saveAccessKey, summarizeAuth } from './auth.js';
 import * as awbApi from './api.js';
 
 const SITE = 'lj-awb';
@@ -46,6 +50,17 @@ const REQUEST_SOURCE_CLI = 'LINGJING_AWB_CLI';
 const DEFAULT_TASK_RECORD_FILE_ENV = process.env.LINGJING_AWB_TASK_RECORD_FILE || process.env.AWB_TASK_RECORD_FILE;
 const execFileAsync = promisify(execFile);
 const COMMON_IMAGE_FORMATS = new Set(['jpg', 'jpeg', 'jfif', 'png', 'webp']);
+const REMOTE_IMAGE_DOWNLOAD_TIMEOUT_MS = 30_000;
+const REMOTE_IMAGE_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
+const REMOTE_IMAGE_MIME_TYPES = new Set([
+  'image/bmp',
+  'image/gif',
+  'image/jpeg',
+  'image/jpg',
+  'image/png',
+  'image/webp',
+]);
+const REMOTE_IMAGE_EXTENSIONS = new Set(['.bmp', '.gif', '.jfif', '.jpg', '.jpeg', '.png', '.webp']);
 const REMOTE_VOICE_DOWNLOAD_TIMEOUT_MS = 30_000;
 const REMOTE_VOICE_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
 const REMOTE_VOICE_MIME_TYPES = new Set([
@@ -61,6 +76,68 @@ const REMOTE_VOICE_EXTENSIONS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg',
 const ASSET_PLATFORM_CODES = ['JIMENG', 'BYTEPLUS'];
 const ASSET_PLATFORM_CODE_SET = new Set(ASSET_PLATFORM_CODES);
 const ASSET_PLATFORM_HINT = ASSET_PLATFORM_CODES.join('|');
+const ASSET_TYPE_CODES = Object.freeze({
+  Image: 'Image',
+  Video: 'Video',
+  Audio: 'Audio',
+});
+const ASSET_IMAGE_EXTENSIONS = new Set(['.bmp', '.gif', '.heic', '.heif', '.jpg', '.jpeg', '.png', '.tif', '.tiff', '.webp']);
+const ASSET_VIDEO_EXTENSIONS = new Set(['.mp4', '.mov']);
+const ASSET_AUDIO_EXTENSIONS = new Set(['.mp3', '.wav']);
+const ASSET_IMAGE_MAX_BYTES = 30 * 1024 * 1024;
+const ASSET_VIDEO_MAX_BYTES = 50 * 1024 * 1024;
+const ASSET_MEDIA_MIN_ASPECT = 0.4;
+const ASSET_MEDIA_MAX_ASPECT = 2.5;
+const ASSET_MEDIA_MIN_DIMENSION = 300;
+const ASSET_MEDIA_MAX_DIMENSION = 6000;
+const ASSET_VIDEO_MIN_SECONDS = 2;
+const ASSET_VIDEO_MAX_SECONDS = 15;
+const ASSET_VIDEO_MIN_FPS = 24;
+const ASSET_VIDEO_MAX_FPS = 60;
+const ASSET_VIDEO_MIN_PIXELS = 640 * 640;
+const ASSET_VIDEO_MAX_PIXELS = 834 * 1112;
+const ASSET_AUDIO_MIN_SECONDS = 2;
+const ASSET_AUDIO_MAX_SECONDS = 15;
+let ffprobeCommandCache = null;
+let ffmpegCommandCache = null;
+const PLATFORM_BACKEND_PATH_PREFIXES = [
+  'material/',
+  'material-image-draw/',
+  'material-image-edit/',
+  'material-video-create/',
+  'default/workbench/',
+  'asset-review/',
+];
+const CREATE_STANDARD_KWARG_KEYS = new Set([
+  'modelGroupCode',
+  'projectGroupNo',
+  'customBizId',
+  'prompt',
+  'ratio',
+  'quality',
+  'generateNum',
+  'generate_num',
+  'duration',
+  'needAudio',
+  'need_audio',
+  'resource',
+  'resources',
+  'resourcesJson',
+  'resources_json',
+  'modelParam',
+  'model_param',
+  'modelParams',
+  'model_params',
+  'modelParamsJson',
+  'model_params_json',
+  'taskRecordFile',
+  'waitSeconds',
+  'pollIntervalMs',
+  'inputFile',
+  'concurrency',
+  'dryRun',
+  'yes',
+]);
 
 export function normalizeUserInfo(payload) {
   const data = payload && typeof payload === 'object' ? payload : {};
@@ -116,6 +193,139 @@ export function ensureConfirmed(kwargs, message, details = {}) {
   });
 }
 
+const LOGIN_FLOW_STATUS = Object.freeze({ PENDING: 0, SUCCESS: 1, EXPIRED: 2, CANCELED: 3 });
+
+function renderLoginFlowPrompt({ verifyUrl, flowId, resumed }) {
+  const lines = [''];
+  if (resumed) {
+    lines.push(`继续轮询已有登录任务（flow_id=${flowId}）...`);
+  } else {
+    lines.push('在浏览器中打开以下链接完成登录授权：', '', verifyUrl || `（flow_id=${flowId}）`, '');
+    lines.push('[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成登录授权。请确保 runner 的 timeout >= 600s。');
+    lines.push('若当前工具无法实时展示命令输出，请使用 "lj-awb auth login --no-wait --json" 获取 flow_id 和 verify_url。');
+    lines.push('用户完成授权后，再执行 "lj-awb auth login --flow-id <flow_id>" 继续轮询。');
+    lines.push('不要重复执行新的 login 命令，否则会生成新的 flow_id，导致旧授权链接失效。');
+  }
+  lines.push('', '等待用户授权...', '');
+  process.stderr.write(lines.join('\n'));
+}
+
+async function saveVerifiedAccessKey(accessKey, { skipVerify = false, loginMethod } = {}) {
+  let user = null;
+  if (!skipVerify) {
+    process.env.LINGJING_AWB_ACCESS_KEY = accessKey;
+    user = normalizeUserInfo(await awbApi.fetchUserInfo());
+  }
+  const { auth } = await saveAccessKey(accessKey, { verified: !skipVerify });
+  return {
+    loginMethod,
+    status: 'success',
+    saved: true,
+    verified: !skipVerify,
+    auth: summarizeAuth(auth, { accessKey, source: 'saved', sourceName: 'auth' }),
+    accessKey: maskSecret(accessKey),
+    user,
+  };
+}
+
+export async function authLogin(kwargs = {}) {
+  const skipVerify = toBool(kwargs.skipVerify);
+  const directAccessKey = trimSecret(kwargs.accessKey || process.env.LINGJING_AWB_ACCESS_KEY || '');
+
+  // 路径一：显式 --access-key 或环境变量 —— 保持原有「直接校验并保存」逻辑
+  if (directAccessKey) {
+    if (toBool(kwargs.dryRun)) {
+      return { dryRun: true, loginMethod: 'access_key', saved: false, verified: false, accessKey: maskSecret(directAccessKey) };
+    }
+    return await saveVerifiedAccessKey(directAccessKey, { skipVerify, loginMethod: 'access_key' });
+  }
+
+  // 路径二/三：浏览器授权登录流程
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, loginMethod: 'flow', saved: false, verified: false };
+  }
+
+  const explicitFlowId = trimToNull(kwargs.flowId);
+  let flowId = explicitFlowId;
+  let verifyUrl = null;
+  if (!flowId) {
+    const created = await awbApi.createLoginFlow();
+    flowId = trimToNull(created?.flowId);
+    verifyUrl = trimToNull(created?.verifyUrl);
+    if (!flowId) {
+      throw new LingjingAwbCliError('创建登录任务失败：未返回 flowId', {
+        type: 'auth_flow_failed',
+        exitCode: 3,
+        hint: '稍后重试 lj-awb auth login；若持续失败请联系平台。',
+      });
+    }
+  }
+
+  if (toBool(kwargs.noWait)) {
+    return {
+      loginMethod: 'flow',
+      status: 'pending',
+      saved: false,
+      verified: false,
+      flowId,
+      verifyUrl,
+      waited: false,
+      nextCommand: `lj-awb auth login --flow-id ${flowId}`,
+    };
+  }
+
+  const waitSeconds = Math.max(0, toInt(kwargs.waitSeconds, 600));
+  const pollIntervalMs = Math.max(1000, toInt(kwargs.pollIntervalMs, 3000));
+  renderLoginFlowPrompt({ verifyUrl, flowId, resumed: Boolean(explicitFlowId) });
+
+  const deadline = Date.now() + waitSeconds * 1000;
+  while (true) {
+    const statusData = await awbApi.queryLoginFlowStatus(flowId);
+    const status = toInt(statusData?.status, LOGIN_FLOW_STATUS.PENDING);
+    if (status === LOGIN_FLOW_STATUS.SUCCESS) {
+      const accessKey = trimSecret(statusData?.accessKey);
+      if (!accessKey) {
+        throw new LingjingAwbCliError('授权成功但未返回 accessKey', {
+          type: 'auth_flow_failed',
+          exitCode: 3,
+          details: { flowId },
+        });
+      }
+      return { ...(await saveVerifiedAccessKey(accessKey, { skipVerify, loginMethod: 'flow' })), flowId };
+    }
+    if (status === LOGIN_FLOW_STATUS.EXPIRED) {
+      throw new LingjingAwbCliError('登录授权链接已过期', {
+        type: 'auth_flow_expired',
+        exitCode: 3,
+        hint: '重新运行 lj-awb auth login 获取新的授权链接。',
+        details: { flowId },
+      });
+    }
+    if (status === LOGIN_FLOW_STATUS.CANCELED) {
+      throw new LingjingAwbCliError('登录授权已被取消', {
+        type: 'auth_flow_canceled',
+        exitCode: 3,
+        hint: '重新运行 lj-awb auth login 重新发起登录授权。',
+        details: { flowId },
+      });
+    }
+    if (Date.now() >= deadline || waitSeconds === 0) break;
+    await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+  }
+
+  throw new LingjingAwbCliError('等待登录授权超时，本轮等待窗口已结束', {
+    type: 'auth_flow_pending',
+    exitCode: 20,
+    hint: `用户在浏览器完成授权后，运行 lj-awb auth login --flow-id ${flowId} 继续轮询；不要重新发起新的 login。`,
+    details: { flowId, verifyUrl, waitSeconds },
+  });
+}
+
+export async function authLogout() {
+  await clearAuth();
+  return { loggedOut: true, authPath: AUTH_PATH };
+}
+
 function envProjectGroupNo() {
   return trimToNull(
     process.env.LINGJING_AWB_PROJECT_GROUP_NO
@@ -262,6 +472,91 @@ export async function accountInfo() {
   };
 }
 
+const REDEEM_CODE_WAIT_SECONDS_DEFAULT = 600;
+
+// 去掉用户粘贴时可能带上的空格 / 制表符 / 换行，避免污染兑换码。
+function sanitizeRedeemCode(value) {
+  return String(value ?? '').replace(/\s+/g, '');
+}
+
+export async function creditsBuy() {
+  const { purchaseUrl } = resolvePurchaseUrl();
+  return {
+    action: 'credits buy',
+    purchaseUrl,
+  };
+}
+
+async function promptRedeemCode(waitSeconds) {
+  if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+    throw argumentError(
+      '未提供兑换码',
+      '非交互终端不会等待输入，请通过 --code 传入兑换码，例如 lj-awb credits redeem --code <code>。',
+    );
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, waitSeconds) * 1000);
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question('请输入兑换码后回车确认：', { signal: controller.signal });
+    return sanitizeRedeemCode(answer);
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new LingjingAwbCliError('等待输入兑换码超时', {
+        type: 'redeem_timeout',
+        exitCode: 20,
+        hint: '重新运行 lj-awb credits redeem 并在限定时间内输入兑换码，或直接用 --code 传入。',
+      });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+  }
+}
+
+export async function creditsRedeem(kwargs = {}) {
+  const waitSeconds = Math.max(0, toInt(kwargs.waitSeconds, REDEEM_CODE_WAIT_SECONDS_DEFAULT));
+  let code = sanitizeRedeemCode(kwargs.code);
+  if (!code) {
+    code = await promptRedeemCode(waitSeconds);
+  }
+  if (!code) {
+    throw argumentError('兑换码不能为空', '请提供有效兑换码，或通过 --code <code> 传入。');
+  }
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, action: 'credits redeem', redemptionCode: code };
+  }
+
+  try {
+    await awbApi.redeemCode(code);
+  } catch (error) {
+    // apiFetch 在平台返回 code != 200 时抛 api_error，并带上平台 msg；统一转成更友好的兑换失败提示。
+    if (error instanceof LingjingAwbCliError && (error.type === 'api_error' || error.type === 'http_error')) {
+      throw new LingjingAwbCliError(error.message || '兑换失败', {
+        type: 'redeem_failed',
+        exitCode: 1,
+        hint: '兑换处理失败，请确认兑换码是否正确或已被使用；若持续失败请联系平台处理。',
+        details: error.details,
+      });
+    }
+    throw error;
+  }
+
+  // 兑换成功后顺带拉取账号概览，展示最新积分余额（等同于 lj-awb account info）。
+  const account = await accountInfo().catch(() => null);
+  return {
+    redeemed: true,
+    action: 'credits redeem',
+    redemptionCode: code,
+    billingPointBalance: account?.billingPointBalance ?? null,
+    currentProjectGroupNo: account?.currentProjectGroupNo ?? null,
+    currentProjectGroupName: account?.currentProjectGroupName ?? null,
+    projectBudgetBalance: account?.projectBudgetBalance ?? null,
+    projectBudgetMax: account?.projectBudgetMax ?? null,
+  };
+}
+
 async function pathExists(filePath) {
   if (!filePath) return false;
   try {
@@ -1047,6 +1342,8 @@ function sourceAllowedByRule(rule = {}, sourceKind) {
 function resourceFormatForValidation(detail = {}) {
   if (detail.localFile?.format) return String(detail.localFile.format).toLowerCase();
   const value = detail.resource?.source?.value;
+  const transformedFormat = imageTransformFormat(value);
+  if (transformedFormat) return transformedFormat;
   const pathname = (() => {
     try {
       return new URL(String(value)).pathname;
@@ -1058,6 +1355,34 @@ function resourceFormatForValidation(detail = {}) {
   return ext || null;
 }
 
+function imageTransformFormat(value) {
+  const text = String(value || '');
+  if (!text.includes('?') && !text.includes('%2F') && !text.includes('/format/')) return null;
+  const queryText = (() => {
+    try {
+      const url = new URL(text);
+      return url.search || text;
+    } catch {
+      const queryIndex = text.indexOf('?');
+      return queryIndex >= 0 ? text.slice(queryIndex) : text;
+    }
+  })();
+  let decoded = queryText;
+  try {
+    decoded = decodeURIComponent(queryText);
+  } catch {}
+  for (const pattern of [
+    /image(?:mogr2|view2)[^&#?]*?\/format\/([A-Za-z0-9]+)/i,
+    /x-oss-process=image[^&#?]*?format,([A-Za-z0-9]+)/i,
+    /(?:^|[?&#])format=([A-Za-z0-9]+)/i,
+  ]) {
+    const match = decoded.match(pattern);
+    const format = normalizeFileFormat(match?.[1]);
+    if (format) return format;
+  }
+  return null;
+}
+
 function normalizeFileFormat(value) {
   const format = trimToNull(value)?.toLowerCase();
   if (!format) return null;
@@ -1122,6 +1447,15 @@ function isConvertibleLocalImage(detail = {}) {
   return Boolean(detail.localFile?.exists && String(detail.localFile?.mimeType || '').startsWith('image/'));
 }
 
+function isDownloadableImageSource(detail = {}) {
+  const sourceKind = resourceSourceKindForValidation(detail);
+  return detail.resource?.source?.kind === 'url' && ['http_url', 'backendPath'].includes(sourceKind);
+}
+
+function isConvertibleImageResource(detail = {}) {
+  return isConvertibleLocalImage(detail) || isDownloadableImageSource(detail);
+}
+
 function resourceFormatConversion(rule = {}, detail = {}) {
   if (!isImageRule(rule)) return null;
   const format = normalizeFileFormat(resourceFormatForValidation(detail));
@@ -1133,7 +1467,7 @@ function resourceFormatConversion(rule = {}, detail = {}) {
       fromFormat: format,
       toFormat: policy.autoConvertTo,
       reason: 'image_webp_not_supported',
-      possible: isConvertibleLocalImage(detail),
+      possible: isConvertibleImageResource(detail),
     };
   }
   if (policy.kind === 'normal_plus_webp') return null;
@@ -1142,7 +1476,7 @@ function resourceFormatConversion(rule = {}, detail = {}) {
     fromFormat: format,
     toFormat: policy.autoConvertTo,
     reason: 'image_strict_format_mismatch',
-    possible: isConvertibleLocalImage(detail),
+    possible: isConvertibleImageResource(detail),
     allowed: policy.allowed,
   };
 }
@@ -1182,7 +1516,7 @@ function assertResourceShapeAgainstModel(resourceDetails = [], resourceRules = [
     if (conversion && !conversion.possible) {
       throw argumentError(
         `素材格式需要转换但无法自动处理：${resourceText(resource)}`,
-        `当前格式 ${conversion.fromFormat}，目标格式 ${conversion.toFormat}；请使用本地文件，或先转换后再传远程 URL / asset。`,
+        `当前格式 ${conversion.fromFormat}，目标格式 ${conversion.toFormat}；请使用本地文件、http(s) URL 或平台 backendPath，asset 资源需先转换后再传。`,
       );
     }
     if (!conversion && !fileTypeAllowedByRule(rule, format)) {
@@ -1309,12 +1643,16 @@ function promptParamValue(promptParams = {}, key) {
 }
 
 function providedPromptParamKeys(promptParams = {}) {
-  const keys = [];
+  const keys = new Set();
   for (const key of ['prompt', 'ratio', 'quality', 'duration', 'generateNum', 'needAudio']) {
     const value = promptParamValue(promptParams, key);
-    if (value !== undefined && value !== null && value !== '') keys.push(key);
+    if (value !== undefined && value !== null && value !== '') keys.add(key);
   }
-  return keys;
+  for (const [key, value] of Object.entries(promptParams || {})) {
+    if (key === 'resources' || key === 'generate_num' || key === 'need_audio') continue;
+    if (value !== undefined && value !== null && value !== '') keys.add(key);
+  }
+  return [...keys];
 }
 
 function inferGeneratedMode(resources = []) {
@@ -1512,7 +1850,7 @@ function mergeResourceLimits(base = {}, overrides = {}) {
 function mergeModelParamRules(options = [], rawModel = null) {
   const rawParams = Array.isArray(rawModel?.modelParams) ? rawModel.modelParams : [];
   const rawByKey = new Map(rawParams.map((item) => [item?.paramKey, item]).filter(([key]) => key));
-  return options.map((option) => {
+  const merged = options.map((option) => {
     const raw = rawByKey.get(option.paramKey);
     return {
       ...option,
@@ -1520,6 +1858,62 @@ function mergeModelParamRules(options = [], rawModel = null) {
       rules: option.rules ?? raw?.rules ?? null,
     };
   });
+  const mergedKeys = new Set(merged.map((item) => item.paramKey).filter(Boolean));
+  for (const raw of rawParams) {
+    if (!raw?.paramKey || mergedKeys.has(raw.paramKey)) continue;
+    merged.push(raw);
+  }
+  return merged;
+}
+
+function modelParamDefaultValue(option = {}) {
+  return option.rules?.defaultValue
+    ?? option.defaultValue
+    ?? null;
+}
+
+function modelParamDefaultName(option = {}) {
+  return option.rules?.defaultName
+    ?? option.defaultName
+    ?? null;
+}
+
+function modelParamValueSource(option = {}) {
+  const allowedValues = optionAllowedValues(option);
+  if (allowedValues.length) return '只能从 allowedValues 选择。';
+  if (modelParamDefaultValue(option) != null) return '模型配置提供 defaultValue；这是候选默认值，不代表可以静默代选。';
+  return '来自实时 model options 的通用模型配置参数；用户明确选择后通过 --model-param key=value 或 --model-params-json 传入。';
+}
+
+function isGenericModelConfigParam(option = {}) {
+  const key = trimToNull(option.paramKey);
+  if (!key) return false;
+  const internalResourceKeys = new Set([
+    'generated_mode',
+    'resources',
+    'iref',
+    'cref',
+    'sref',
+    'frames',
+    'multi_param',
+    'multi_prompt',
+    'subject',
+    'subject_reference',
+    'reference_image',
+    'reference_audio',
+    'reference_video',
+    'first_frame',
+    'first_last_frame',
+    'last_frame_only',
+    'storyboard',
+  ]);
+  if (internalResourceKeys.has(key)) return false;
+  const paramType = String(option.paramType || '');
+  return Boolean(
+    optionAllowedValues(option).length
+    || modelParamDefaultValue(option) != null
+    || /Enum|Boolean|Bool|Number|Integer|Float|Double|String|Text|Prompt/i.test(paramType),
+  );
 }
 
 function createParamForModelOption(option = {}, taskKind = 'image') {
@@ -1596,7 +1990,7 @@ function createParamForModelOption(option = {}, taskKind = 'image') {
       requestPath: 'promptParams.resources[]',
       materialLegacyKey: 'iref',
       meaning: '图片任务的参考图输入。',
-      valueSource: '本地文件、http(s) URL 或 material backendPath。',
+      valueSource: '本地文件、http(s) URL 或平台 backendPath。',
       resourceSyntax: ['image:reference=./ref.png'],
     },
     resources: {
@@ -1605,7 +1999,7 @@ function createParamForModelOption(option = {}, taskKind = 'image') {
       requestPath: 'promptParams.resources[]',
       materialLegacyKey: 'resources',
       meaning: '模型声明的素材输入；CLI 统一用 resources 表达。',
-      valueSource: '本地文件、http(s) URL 或 material backendPath。',
+      valueSource: '本地文件、http(s) URL 或平台 backendPath。',
       resourceSyntax: taskKind === 'image' ? ['image:reference=./ref.png'] : ['image:first_frame=./first.png'],
     },
     frames: {
@@ -1614,7 +2008,7 @@ function createParamForModelOption(option = {}, taskKind = 'image') {
       requestPath: 'promptParams.resources[]',
       materialLegacyKey: 'frames',
       meaning: '视频首帧 / 尾帧 / 关键帧输入。',
-      valueSource: '首帧/尾帧可用本地文件、http(s) URL、material backendPath 或 asset:<assetId>；keyframe 仅用文件/URL/backendPath。',
+      valueSource: '首帧/尾帧可用本地文件、http(s) URL、平台 backendPath 或 asset:<assetId>；keyframe 仅用文件/URL/backendPath。',
       resourceSyntax: ['image:first_frame=./first.png', 'image:first_frame=asset:<assetId>', 'image:last_frame=asset:<assetId>', 'image:keyframe#1=./key1.png'],
     },
     multi_param: {
@@ -1655,15 +2049,26 @@ function createParamForModelOption(option = {}, taskKind = 'image') {
     },
   };
   return {
-    ...(definitions[key] ?? {
-      key,
-      cliArg: null,
-      requestPath: null,
-      materialLegacyKey: key,
-      meaning: '模型配置存在该参数，但当前 CLI 没有暴露为稳定创建参数；不要为了调用而硬塞旧字段。',
-      valueSource: '如确实需要，先扩展 CLI 显式参数和 Material adapter。',
-      notExposedByCli: true,
-    }),
+    ...(definitions[key]
+      ?? (isGenericModelConfigParam(option)
+        ? {
+          key,
+          cliArg: '--model-param / --model-params-json',
+          requestPath: `promptParams.${key}`,
+          materialLegacyKey: key,
+          meaning: option.paramName ? `模型配置参数：${option.paramName}` : '模型配置参数。',
+          valueSource: modelParamValueSource(option),
+          genericModelParam: true,
+        }
+        : {
+          key,
+          cliArg: null,
+          requestPath: null,
+          materialLegacyKey: key,
+          meaning: '模型配置存在该参数，但当前 CLI 未将其识别为可安全透传的创建参数。',
+          valueSource: '如确实需要，先确认该字段不是资源或旧 handler 内部字段，再扩展通用参数判定。',
+          notExposedByCli: true,
+        })),
     ...common,
   };
 }
@@ -2032,6 +2437,7 @@ function createSpecParameterControls(createParams, inputModes = []) {
       valueSource: item.valueSource,
       controlKind: item.controlKind,
       allowedValues: item.allowedValues,
+      genericModelParam: item.genericModelParam,
     }));
   const resourceParams = createParams
     .filter((item) => item.key === 'resources')
@@ -2153,7 +2559,8 @@ function cliValueType(option = {}, allowedValues = []) {
   if (allowedValues.length) return 'enum';
   if (option.paramType === 'Prompt') return 'text';
   if (option.paramType === 'BooleanType') return 'boolean';
-  if (/Number|Integer|Float/i.test(String(option.paramType || ''))) return 'number';
+  if (/Enum/i.test(String(option.paramType || ''))) return 'enum';
+  if (/Number|Integer|Float|Double/i.test(String(option.paramType || ''))) return 'number';
   return option.paramType || undefined;
 }
 
@@ -2163,6 +2570,7 @@ function modelOptionParams(options = [], taskKind = 'image') {
     .filter(({ createParam }) => createParam.cliArg && createParam.key !== 'resources' && !createParam.internalOnly)
     .map(({ option, createParam }) => {
       const rules = option.rules || {};
+      const defaultValue = modelParamDefaultValue(option);
       const allowedValues = optionAllowedValues(option);
       const required = option.required === true || rules.required === true ? true : undefined;
       const maxLength = option.paramType === 'Prompt'
@@ -2173,10 +2581,15 @@ function modelOptionParams(options = [], taskKind = 'image') {
         label: option.paramName,
         valueType: cliValueType(option, allowedValues),
         values: allowedValues.length ? allowedValues : undefined,
-        defaultValue: rules.defaultValue,
-        defaultName: rules.defaultName,
+        defaultValue,
+        defaultName: modelParamDefaultName(option),
         maxLength,
         required,
+        cliArg: createParam.cliArg,
+        genericModelParam: createParam.genericModelParam || undefined,
+        modelParamKey: createParam.modelParamKey,
+        modelParamName: createParam.modelParamName,
+        modelParamType: createParam.modelParamType,
       });
     });
 }
@@ -2274,7 +2687,7 @@ export function modelInputGuide() {
       { field: 'resources[].type', values: ['image', 'video', 'audio', 'subject'], description: '资源本体类型；subject 表示已创建的主体对象。' },
       { field: 'resources[].usage', values: ['first_frame', 'last_frame', 'reference', 'keyframe'], description: '素材用途。' },
       { field: 'resources[].reference_key', values: ['custom string'], description: '仅视频 reference 资源需要占位绑定时使用；图片生图 image:reference 不使用 reference_key。subject reference 必须传。' },
-      { field: 'resources[].source.kind', values: ['url', 'asset_id'], description: '只接受 url、asset_id 两个枚举值。本地文件、http(s) URL、material backendPath 一律传 kind=url，CLI 按 value 自动识别；asset_id 表示平台资产或主体对象 ID。注意：模型 resources[].valueShapes 列出的 local_file / http_url / backendPath 是 value 形状分类，不是 kind 枚举。' },
+      { field: 'resources[].source.kind', values: ['url', 'asset_id'], description: '只接受 url、asset_id 两个枚举值。本地文件、http(s) URL、平台 backendPath 一律传 kind=url，CLI 按 value 自动识别；asset_id 表示平台资产或主体对象 ID。注意：模型 resources[].valueShapes 列出的 local_file / http_url / backendPath 是 value 形状分类，不是 kind 枚举。' },
       { field: 'resources[].source.value', description: '资源值，必填。url 传素材地址；asset_id 传资源 ID。' },
       { field: 'resources[].order', description: '仅 usage=keyframe 时需要，且同一请求内不能重复。' },
       { field: 'resources[].duration', description: '仅 keyframe 场景下用于表达该帧持续时长，可传小数秒。' },
@@ -2341,6 +2754,7 @@ export async function modelCreateSpec(kwargs = {}) {
     inputRequirement,
     supportedIntents,
     validationRules: createSpecValidationRules(context.taskKind),
+    parameterControls: createSpecParameterControls(context.createParams, context.inputModes),
     agentGuidance: createSpecAgentGuidance(context.taskKind, inputRequirement),
     preflight: createSpecPreflight(context.taskKind),
     examples: createSpecExamples(context.taskKind, supportedIntents),
@@ -2412,135 +2826,1058 @@ function dryRunBackendPath(filePath, sceneType) {
   return `/${sceneType}/__dry_run__/${safeFileName(filePath)}`;
 }
 
-export async function uploadFilesCommand(kwargs = {}) {
-  const specs = await collectFileSpecs(kwargs, trimToNull(kwargs.sceneType));
-  if (!specs.length) throw argumentError('缺少上传文件', '传 --file <path> 或 --files a.png,b.mp4。');
-  if (toBool(kwargs.dryRun)) {
-    const files = [];
-    for (const spec of specs) {
-      const inspected = await inspectLocalFile(spec.file);
-      files.push(compactRecord({
-        ...inspected,
-        sceneType: spec.sceneType,
-        projectNo: spec.projectNo,
-        backendPath: dryRunBackendPath(spec.file, spec.sceneType),
-        url: null,
-        dryRun: true,
-      }));
+function mb(bytes) {
+  return `${(bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, '')}MB`;
+}
+
+function sourceExtension(value) {
+  const text = trimToNull(value);
+  if (!text) return '';
+  if (/^https?:\/\//i.test(text)) {
+    try {
+      return path.extname(decodeURIComponent(new URL(text).pathname)).toLowerCase();
+    } catch {
+      return path.extname(text.split(/[?#]/)[0] || '').toLowerCase();
     }
-    return { dryRun: true, files };
   }
-  const files = [];
-  for (const spec of specs) {
-    files.push(await uploadLocalFile(spec.file, spec));
-  }
-  return { files };
+  return path.extname(text.split(/[?#]/)[0] || '').toLowerCase();
 }
 
-export async function uploadLocalFile(filePath, options = {}) {
-  const inspected = await inspectLocalFile(filePath);
-  if (!inspected.exists) {
-    throw argumentError(`文件不存在：${filePath}`);
-  }
-  const buffer = await fs.readFile(inspected.filePath);
-  const sceneType = options.sceneType ?? defaultUploadSceneForFile(inspected.filePath, inspected.mimeType);
-  const groupId = crypto.randomUUID().replaceAll('-', '');
-  const secret = await awbApi.fetchUploadSecret({
-    sceneType,
-    groupId,
-    projectNo: options.projectNo ?? '',
-  });
-  const credentials = secret.credentials ?? secret;
-  const objectName = `${secret.path ?? ''}${secret.prefix ?? ''}${Date.now()}-${safeFileName(inspected.filePath)}`.replace(/^\/+/, '');
-  const host = `${secret.bucket}.cos.${secret.region}.myqcloud.com`;
-  const authorization = buildCosAuthorization({
-    secretKey: credentials.tmpSecretKey,
-    secretId: credentials.tmpSecretId,
-    method: 'PUT',
-    objectName,
-    contentLength: buffer.length,
-    host,
-    startTime: secret.startTime,
-    expiredTime: secret.expiredTime,
-  });
-  const response = await fetch(`https://${host}/${encodeObjectNamePath(objectName)}`, {
-    method: 'PUT',
-    headers: {
-      authorization,
-      'content-length': String(buffer.length),
-      'content-type': inspected.mimeType || guessMimeType(inspected.filePath),
-      host,
-      'x-cos-security-token': credentials.sessionToken,
-    },
-    body: buffer,
-  });
-  if (!response.ok) {
-    throw new LingjingAwbCliError(`上传 COS 失败：${response.status} ${response.statusText}`, {
-      type: 'upload_failed',
-      exitCode: 30,
-      details: { filePath: inspected.filePath, objectName },
-    });
+function inferAssetTypeFromExtension(ext) {
+  if (ASSET_IMAGE_EXTENSIONS.has(ext)) return ASSET_TYPE_CODES.Image;
+  if (ASSET_VIDEO_EXTENSIONS.has(ext)) return ASSET_TYPE_CODES.Video;
+  if (ASSET_AUDIO_EXTENSIONS.has(ext)) return ASSET_TYPE_CODES.Audio;
+  return null;
+}
+
+function inferAssetTypeFromSource(value) {
+  const ext = sourceExtension(value);
+  const assetType = inferAssetTypeFromExtension(ext);
+  if (assetType) return assetType;
+  const suffix = ext || '无扩展名';
+  throw argumentError(
+    `无法判断素材类型：${suffix}`,
+    '素材加白支持图片 jpg/jpeg/png/webp/bmp/tiff/gif/heic/heif，视频 mp4/mov，音频 wav/mp3；请传带正确扩展名的 --file、--url 或 --backend-path。',
+  );
+}
+
+function parseFfprobeNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function parseFps(value) {
+  const text = String(value || '').trim();
+  if (!text || text === '0/0') return null;
+  if (text.includes('/')) {
+    const [left, right] = text.split('/').map(Number);
+    return Number.isFinite(left) && Number.isFinite(right) && right !== 0 ? left / right : null;
   }
-  return compactRecord({
-    ...inspected,
-    sceneType,
-    projectNo: options.projectNo ?? '',
-    backendPath: `/${objectName}`,
-    url: `https://${host}/${encodeObjectNamePath(objectName)}`,
-  });
+  return parseFfprobeNumber(text);
 }
 
-function isHttpUrl(value) {
-  return /^https?:\/\//i.test(String(value || '').trim());
+function roundNumber(value, digits = 3) {
+  if (!Number.isFinite(Number(value))) return value;
+  const fixed = Number(value).toFixed(digits);
+  return fixed.replace(/\.?0+$/, '');
 }
 
-function isUploadedMaterialReference(value) {
+function normalizeDisplayFormat(value) {
   const text = trimToNull(value);
-  if (!text) return false;
-  if (text.startsWith('material/') || text.startsWith('/material/')) return true;
-  if (!isHttpUrl(text)) return false;
-  try {
-    const url = new URL(text);
-    return url.hostname.endsWith('.myqcloud.com');
-  } catch {
-    return false;
-  }
+  if (!text) return null;
+  return normalizeFileFormat(text.replace(/^\./, ''));
 }
 
-function remoteFileNameFromUrl(remoteUrl, fallback = 'voice-audio') {
-  try {
-    const pathname = decodeURIComponent(new URL(remoteUrl).pathname);
-    const baseName = safeFileName(path.basename(pathname));
-    if (baseName && baseName !== '.' && baseName !== '/') return baseName;
-  } catch {}
-  return `${fallback}.mp3`;
+function clampNumber(value, min, max) {
+  return Math.min(max, Math.max(min, value));
 }
 
-function extensionFromContentType(contentType = '') {
-  const normalized = String(contentType || '').split(';')[0].trim().toLowerCase();
-  if (normalized === 'audio/mpeg') return '.mp3';
-  if (normalized === 'audio/wav' || normalized === 'audio/x-wav') return '.wav';
-  if (normalized === 'audio/mp4') return '.m4a';
-  if (normalized === 'audio/aac') return '.aac';
-  if (normalized === 'audio/ogg') return '.ogg';
-  if (normalized === 'video/mp4') return '.mp4';
-  return '';
+function evenNumber(value, fallback = 2) {
+  const rounded = Math.max(2, Math.round(value / 2) * 2);
+  return Number.isFinite(rounded) ? rounded : fallback;
 }
 
-function isSupportedRemoteVoiceDownload(contentType = '', fileName = '') {
-  const normalized = String(contentType || '').split(';')[0].trim().toLowerCase();
-  const extension = path.extname(fileName).toLowerCase();
-  if (REMOTE_VOICE_MIME_TYPES.has(normalized)) return true;
-  if ((!normalized || normalized === 'application/octet-stream') && REMOTE_VOICE_EXTENSIONS.has(extension)) return true;
-  return false;
+function roundToStep(value, step = 1) {
+  return Math.round(value / step) * step;
 }
 
-async function downloadRemoteFileToTemp(remoteUrl, options = {}) {
-  const timeoutMs = Math.max(1_000, toInt(options.timeoutMs, REMOTE_VOICE_DOWNLOAD_TIMEOUT_MS));
-  const maxBytes = Math.max(1, toInt(options.maxBytes, REMOTE_VOICE_DOWNLOAD_MAX_BYTES));
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  let dir = null;
+function alignUp(value, step = 1) {
+  return Math.ceil(value / step) * step;
+}
+
+function alignDown(value, step = 1) {
+  return Math.floor(value / step) * step;
+}
+
+function isLegalMediaBox(width, height, options = {}) {
+  const minAspect = options.minAspect ?? ASSET_MEDIA_MIN_ASPECT;
+  const maxAspect = options.maxAspect ?? ASSET_MEDIA_MAX_ASPECT;
+  const minDimension = options.minDimension ?? ASSET_MEDIA_MIN_DIMENSION;
+  const maxDimension = options.maxDimension ?? ASSET_MEDIA_MAX_DIMENSION;
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return false;
+  if (width < minDimension || height < minDimension || width > maxDimension || height > maxDimension) return false;
+  const aspect = width / height;
+  if (aspect < minAspect || aspect > maxAspect) return false;
+  const pixels = width * height;
+  if (options.minPixels != null && pixels < options.minPixels) return false;
+  if (options.maxPixels != null && pixels > options.maxPixels) return false;
+  return true;
+}
+
+function legalMediaBoxOrThrow(target, label, options = {}) {
+  if (isLegalMediaBox(target.width, target.height, options)) return target;
+  throw argumentError(
+    `无法计算合法${label}转码尺寸`,
+    `${label}目标尺寸计算结果为 ${target.width}x${target.height}，仍不满足平台规格；请手动转换素材后重试。`,
+  );
+}
+
+function chooseClosestLegalBox(width, height, options = {}) {
+  const minAspect = options.minAspect ?? ASSET_MEDIA_MIN_ASPECT;
+  const maxAspect = options.maxAspect ?? ASSET_MEDIA_MAX_ASPECT;
+  const minDimension = options.minDimension ?? ASSET_MEDIA_MIN_DIMENSION;
+  const maxDimension = options.maxDimension ?? ASSET_MEDIA_MAX_DIMENSION;
+  const step = options.even ? 2 : 1;
+  const sourceWidth = Math.max(1, Number(width) || minDimension);
+  const sourceHeight = Math.max(1, Number(height) || minDimension);
+  const targetAspect = clampNumber(sourceWidth / sourceHeight, minAspect, maxAspect);
+  const minPixels = options.minPixels;
+  const maxPixels = options.maxPixels;
+  const minArea = minPixels ?? minDimension * minDimension;
+  const maxArea = maxPixels ?? maxDimension * maxDimension;
+  const targetArea = clampNumber(sourceWidth * sourceHeight, minArea, maxArea);
+  let best = null;
+
+  const minHeight = alignUp(minDimension, step);
+  const maxHeight = alignDown(maxDimension, step);
+  for (let candidateHeight = minHeight; candidateHeight <= maxHeight; candidateHeight += step) {
+    const minWidthForAspect = Math.ceil(candidateHeight * minAspect);
+    const maxWidthForAspect = Math.floor(candidateHeight * maxAspect);
+    const minWidthForPixels = minPixels == null ? minDimension : Math.ceil(minPixels / candidateHeight);
+    const maxWidthForPixels = maxPixels == null ? maxDimension : Math.floor(maxPixels / candidateHeight);
+    const minWidth = alignUp(Math.max(minDimension, minWidthForAspect, minWidthForPixels), step);
+    const maxWidth = alignDown(Math.min(maxDimension, maxWidthForAspect, maxWidthForPixels), step);
+    if (minWidth > maxWidth) continue;
+
+    const preferredByAspect = roundToStep(targetAspect * candidateHeight, step);
+    const preferredByArea = roundToStep(targetArea / candidateHeight, step);
+    const candidates = uniqueNonEmpty([
+      preferredByAspect,
+      preferredByArea,
+      minWidth,
+      maxWidth,
+      preferredByAspect - step,
+      preferredByAspect + step,
+      preferredByArea - step,
+      preferredByArea + step,
+    ])
+      .map((item) => Number(item))
+      .filter((item) => Number.isFinite(item))
+      .map((item) => clampNumber(item, minWidth, maxWidth));
+
+    for (const candidateWidth of candidates) {
+      if (!isLegalMediaBox(candidateWidth, candidateHeight, options)) continue;
+      const aspect = candidateWidth / candidateHeight;
+      const area = candidateWidth * candidateHeight;
+      const aspectScore = Math.abs(Math.log(aspect / targetAspect));
+      const areaScore = Math.abs(Math.log(area / targetArea));
+      const sourceScaleScore = Math.abs(Math.log(candidateWidth / sourceWidth)) + Math.abs(Math.log(candidateHeight / sourceHeight));
+      const score = aspectScore * 10 + areaScore + sourceScaleScore * 0.05;
+      if (!best || score < best.score) {
+        best = { width: candidateWidth, height: candidateHeight, pixels: area, score };
+      }
+    }
+  }
+
+  if (!best) {
+    const fallback = options.even ? { width: 640, height: 640, pixels: 640 * 640 } : { width: 300, height: 300, pixels: 300 * 300 };
+    return fallback;
+  }
+  return {
+    width: best.width,
+    height: best.height,
+    pixels: best.pixels,
+  };
+}
+
+function mediaSummary(media = {}) {
+  return compactRecord({
+    width: media.width,
+    height: media.height,
+    pixels: media.width && media.height ? media.width * media.height : undefined,
+    aspectRatio: media.width && media.height ? Number(roundNumber(media.width / media.height, 4)) : undefined,
+    duration: media.duration == null ? undefined : Number(roundNumber(media.duration, 3)),
+    fps: media.fps == null ? undefined : Number(roundNumber(media.fps, 3)),
+  });
+}
+
+function addAssetViolation(violations, code, message, hint = '') {
+  violations.push(compactRecord({ code, message, hint }));
+}
+
+function validateMediaGeometry(violations, media, label, options = {}) {
+  const width = Number(media?.width);
+  const height = Number(media?.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    addAssetViolation(violations, `${label}_dimensions_unknown`, `${label}宽高无法识别`, `${label}宽高必须在 [300,6000] px，宽高比必须在 [0.4,2.5]。`);
+    return;
+  }
+  const aspectRatio = width / height;
+  if (aspectRatio < ASSET_MEDIA_MIN_ASPECT || aspectRatio > ASSET_MEDIA_MAX_ASPECT) {
+    addAssetViolation(
+      violations,
+      `${label}_aspect_ratio`,
+      `${label}宽高比不支持：${roundNumber(aspectRatio, 4)}`,
+      `${label}宽高比（宽/高）必须在 [0.4,2.5]。`,
+    );
+  }
+  if (
+    width < ASSET_MEDIA_MIN_DIMENSION
+    || height < ASSET_MEDIA_MIN_DIMENSION
+    || width > ASSET_MEDIA_MAX_DIMENSION
+    || height > ASSET_MEDIA_MAX_DIMENSION
+  ) {
+    addAssetViolation(
+      violations,
+      `${label}_dimensions`,
+      `${label}宽高不支持：${width}x${height}`,
+      `${label}宽和高都必须在 [300,6000] px。`,
+    );
+  }
+  if (options.videoPixels) {
+    const pixels = width * height;
+    if (pixels < ASSET_VIDEO_MIN_PIXELS || pixels > ASSET_VIDEO_MAX_PIXELS) {
+      addAssetViolation(
+        violations,
+        'video_pixels',
+        `视频总像素数不支持：${pixels}`,
+        `视频宽高乘积必须在 [${ASSET_VIDEO_MIN_PIXELS},${ASSET_VIDEO_MAX_PIXELS}]。`,
+      );
+    }
+  }
+}
+
+function validateDurationRange(violations, media, label, minSeconds, maxSeconds) {
+  const duration = Number(media?.duration);
+  if (!Number.isFinite(duration) || duration < minSeconds || duration > maxSeconds) {
+    addAssetViolation(
+      violations,
+      `${label}_duration`,
+      `${label}时长不支持：${Number.isFinite(duration) ? `${roundNumber(duration)}s` : 'unknown'}`,
+      `${label}时长必须在 [${minSeconds},${maxSeconds}] 秒。`,
+    );
+  }
+}
+
+async function commandSucceeds(command, args = ['--version']) {
+  try {
+    await execFileAsync(command, args, { encoding: 'utf8', timeout: 10_000, maxBuffer: 256 * 1024 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandCandidates(command) {
+  if (path.isAbsolute(command)) return [command];
+  if (command === 'brew') return ['brew', '/opt/homebrew/bin/brew', '/usr/local/bin/brew'];
+  if (command === 'ffprobe') return ['ffprobe', '/opt/homebrew/bin/ffprobe', '/usr/local/bin/ffprobe'];
+  if (command === 'ffmpeg') return ['ffmpeg', '/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg'];
+  return [command];
+}
+
+async function findCommand(command, args = ['--version']) {
+  for (const candidate of commandCandidates(command)) {
+    if (await commandSucceeds(candidate, args)) return candidate;
+  }
+  return null;
+}
+
+function autoInstallFfprobeEnabled() {
+  const value = String(process.env.LINGJING_AWB_AUTO_INSTALL_FFPROBE ?? '1').trim().toLowerCase();
+  return !['0', 'false', 'no', 'off'].includes(value);
+}
+
+async function ensureFfprobeAvailable() {
+  if (ffprobeCommandCache && await commandSucceeds(ffprobeCommandCache, ['-version'])) return ffprobeCommandCache;
+  const existing = await findCommand('ffprobe', ['-version']);
+  if (existing) {
+    ffprobeCommandCache = existing;
+    return existing;
+  }
+  const brewCommand = autoInstallFfprobeEnabled() && process.platform === 'darwin'
+    ? await findCommand('brew', ['--version'])
+    : null;
+  if (brewCommand) {
+    try {
+      await execFileAsync(brewCommand, ['install', 'ffmpeg'], {
+        encoding: 'utf8',
+        timeout: 10 * 60_000,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      const installed = await findCommand('ffprobe', ['-version']);
+      if (installed) {
+        ffprobeCommandCache = installed;
+        return installed;
+      }
+    } catch (error) {
+      throw argumentError(
+        '缺少 ffprobe，且自动安装 ffmpeg 失败',
+        `CLI 已尝试运行 brew install ffmpeg。请手动安装后重试；如需关闭自动安装，设置 LINGJING_AWB_AUTO_INSTALL_FFPROBE=0。原始错误：${error.message}`,
+      );
+    }
+  }
+  throw argumentError(
+    '缺少 ffprobe',
+    '本地图片 / 音频 / 视频素材加白需要 ffprobe 校验尺寸、时长和视频 FPS。macOS 可运行 brew install ffmpeg；Ubuntu/Debian 可运行 sudo apt-get install ffmpeg。',
+  );
+}
+
+async function ensureFfmpegAvailable() {
+  if (ffmpegCommandCache && await commandSucceeds(ffmpegCommandCache, ['-version'])) return ffmpegCommandCache;
+  const existing = await findCommand('ffmpeg', ['-version']);
+  if (existing) {
+    ffmpegCommandCache = existing;
+    return existing;
+  }
+  const brewCommand = autoInstallFfprobeEnabled() && process.platform === 'darwin'
+    ? await findCommand('brew', ['--version'])
+    : null;
+  if (brewCommand) {
+    try {
+      await execFileAsync(brewCommand, ['install', 'ffmpeg'], {
+        encoding: 'utf8',
+        timeout: 10 * 60_000,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      const installed = await findCommand('ffmpeg', ['-version']);
+      if (installed) {
+        ffmpegCommandCache = installed;
+        return installed;
+      }
+    } catch (error) {
+      throw argumentError(
+        '缺少 ffmpeg，且自动安装 ffmpeg 失败',
+        `CLI 已尝试运行 brew install ffmpeg。请手动安装后重试；如需关闭自动安装，设置 LINGJING_AWB_AUTO_INSTALL_FFPROBE=0。原始错误：${error.message}`,
+      );
+    }
+  }
+  throw argumentError(
+    '缺少 ffmpeg',
+    '素材自动转码需要 ffmpeg。macOS 可运行 brew install ffmpeg；Ubuntu/Debian 可运行 sudo apt-get install ffmpeg。',
+  );
+}
+
+async function readMediaMetadata(filePath, assetType) {
+  const ffprobeCommand = await ensureFfprobeAvailable();
+  try {
+    const { stdout } = await execFileAsync(ffprobeCommand, [
+      '-v',
+      'error',
+      '-print_format',
+      'json',
+      '-show_format',
+      '-show_streams',
+      filePath,
+    ], { encoding: 'utf8', timeout: 15_000, maxBuffer: 2 * 1024 * 1024 });
+    const data = JSON.parse(stdout);
+    const streams = Array.isArray(data.streams) ? data.streams : [];
+    const wantedStreamType = assetType === ASSET_TYPE_CODES.Audio ? 'audio' : 'video';
+    const stream = streams.find((item) => item.codec_type === wantedStreamType);
+    if (!stream) {
+      throw new Error(`缺少 ${wantedStreamType} stream`);
+    }
+    const duration = parseFfprobeNumber(stream.duration) ?? parseFfprobeNumber(data.format?.duration);
+    return compactRecord({
+      duration,
+      width: parseFfprobeNumber(stream.width),
+      height: parseFfprobeNumber(stream.height),
+      fps: parseFps(stream.avg_frame_rate) ?? parseFps(stream.r_frame_rate),
+    });
+  } catch (error) {
+    const mediaLabel = assetType === ASSET_TYPE_CODES.Audio ? '音频' : (assetType === ASSET_TYPE_CODES.Video ? '视频' : '图片');
+    throw argumentError(
+      `无法读取${mediaLabel}素材信息`,
+      `请确认文件可被 ffprobe 解析且本机已安装 ffprobe。原始错误：${error.message}`,
+    );
+  }
+}
+
+async function readImageMetadata(filePath) {
+  const inspected = await inspectLocalFile(filePath);
+  if (Number.isFinite(inspected.width) && Number.isFinite(inspected.height)) {
+    return compactRecord({
+      width: inspected.width,
+      height: inspected.height,
+      format: inspected.format ?? null,
+    });
+  }
+  const media = await readMediaMetadata(filePath, ASSET_TYPE_CODES.Image);
+  return compactRecord({
+    width: media.width,
+    height: media.height,
+    format: inspected.format ?? null,
+  });
+}
+
+function chooseLegalMediaBox(width, height, options = {}) {
+  return legalMediaBoxOrThrow(chooseClosestLegalBox(width, height, options), '图片', options);
+}
+
+function chooseLegalVideoBox(width, height) {
+  const options = {
+    even: true,
+    minPixels: ASSET_VIDEO_MIN_PIXELS,
+    maxPixels: ASSET_VIDEO_MAX_PIXELS,
+  };
+  return legalMediaBoxOrThrow(chooseClosestLegalBox(width, height, options), '视频', options);
+}
+
+function validateAssetViolations(assetType, inspected, media = null) {
+  const violations = [];
+  const format = normalizeFileFormat(inspected.format ?? path.extname(inspected.filePath));
+  if (assetType === ASSET_TYPE_CODES.Image) {
+    if (inspected.size >= ASSET_IMAGE_MAX_BYTES) {
+      addAssetViolation(violations, 'image_size', `图片素材过大：${mb(inspected.size)}`, '单张图片必须小于 30MB。');
+    }
+    if (!media?.width || !media?.height) {
+      addAssetViolation(violations, 'image_dimensions_unknown', '图片宽高无法识别', '请确认文件可被 ffprobe 或本地图片解析器解析。');
+    } else {
+      validateMediaGeometry(violations, media, '图片');
+    }
+  } else if (assetType === ASSET_TYPE_CODES.Video) {
+    if (inspected.size > ASSET_VIDEO_MAX_BYTES) {
+      addAssetViolation(violations, 'video_size', `视频素材过大：${mb(inspected.size)}`, '单个视频不能超过 50MB。');
+    }
+    if (!media?.width || !media?.height) {
+      addAssetViolation(violations, 'video_dimensions_unknown', '视频宽高无法识别', '请确认文件可被 ffprobe 解析。');
+    } else {
+      validateMediaGeometry(violations, media, '视频', { videoPixels: true });
+    }
+    if (media?.fps == null || media.fps + 0.05 < ASSET_VIDEO_MIN_FPS || media.fps - 0.05 > ASSET_VIDEO_MAX_FPS) {
+      addAssetViolation(
+        violations,
+        'video_fps',
+        `视频帧率不支持：${media?.fps == null ? 'unknown' : `${roundNumber(media.fps)}fps`}`,
+        '视频 FPS 必须在 [24,60]。',
+      );
+    }
+    if (media?.duration == null || media.duration < ASSET_VIDEO_MIN_SECONDS || media.duration > ASSET_VIDEO_MAX_SECONDS) {
+      addAssetViolation(
+        violations,
+        'video_duration',
+        `视频时长不支持：${media?.duration == null ? 'unknown' : `${roundNumber(media.duration)}s`}`,
+        '单个视频时长必须在 [2,15] 秒。',
+      );
+    }
+  } else if (assetType === ASSET_TYPE_CODES.Audio) {
+    if (media?.duration == null || media.duration < ASSET_AUDIO_MIN_SECONDS || media.duration > ASSET_AUDIO_MAX_SECONDS) {
+      addAssetViolation(
+        violations,
+        'audio_duration',
+        `音频时长不支持：${media?.duration == null ? 'unknown' : `${roundNumber(media.duration)}s`}`,
+        '单个音频时长必须在 [2,15] 秒。',
+      );
+    }
+  }
+  return {
+    legal: violations.length === 0,
+    assetType,
+    format,
+    inspected,
+    media: media ? compactRecord(media) : null,
+    violations,
+  };
+}
+
+function buildAssetConversionPlan(validation) {
+  const { assetType, media, inspected } = validation;
+  if (!media?.width && assetType !== ASSET_TYPE_CODES.Audio) return null;
+  if (assetType === ASSET_TYPE_CODES.Image) {
+    const target = chooseLegalMediaBox(media.width, media.height);
+    return compactRecord({
+      assetType,
+      fromFormat: normalizeDisplayFormat(inspected.format ?? path.extname(inspected.filePath)) || 'unknown',
+      toFormat: 'jpg',
+      targetWidth: target.width,
+      targetHeight: target.height,
+      sourceFile: inspected.filePath,
+      reason: validation.violations.map((item) => item.message).join('；'),
+      filters: `scale=${target.width}:${target.height}:force_original_aspect_ratio=decrease,pad=${target.width}:${target.height}:(ow-iw)/2:(oh-ih)/2:black,setsar=1`,
+    });
+  }
+  if (assetType === ASSET_TYPE_CODES.Video) {
+    const target = chooseLegalVideoBox(media.width, media.height);
+    const targetFps = clampNumber(Number(media.fps ?? ASSET_VIDEO_MIN_FPS), ASSET_VIDEO_MIN_FPS, ASSET_VIDEO_MAX_FPS);
+    const targetDuration = clampNumber(Number(media.duration ?? ASSET_VIDEO_MIN_SECONDS), ASSET_VIDEO_MIN_SECONDS, ASSET_VIDEO_MAX_SECONDS);
+    const filters = [
+      `fps=${roundNumber(targetFps, 3)}`,
+      `scale=${target.width}:${target.height}:force_original_aspect_ratio=decrease`,
+      `pad=${target.width}:${target.height}:(ow-iw)/2:(oh-ih)/2:black`,
+      'setsar=1',
+    ];
+    if (media.duration != null && media.duration < ASSET_VIDEO_MIN_SECONDS) {
+      filters.push(`tpad=stop_mode=clone:stop_duration=${roundNumber(ASSET_VIDEO_MIN_SECONDS - media.duration, 3)}`);
+    }
+    return compactRecord({
+      assetType,
+      fromFormat: normalizeDisplayFormat(inspected.format ?? path.extname(inspected.filePath)) || 'unknown',
+      toFormat: 'mp4',
+      sourceDuration: media.duration,
+      targetWidth: target.width,
+      targetHeight: target.height,
+      targetPixels: target.width * target.height,
+      targetFps: Number(roundNumber(targetFps, 3)),
+      targetDuration,
+      sourceFile: inspected.filePath,
+      reason: validation.violations.map((item) => item.message).join('；'),
+      filters: filters.join(','),
+    });
+  }
+  if (assetType === ASSET_TYPE_CODES.Audio) {
+    return compactRecord({
+      assetType,
+      fromFormat: normalizeDisplayFormat(inspected.format ?? path.extname(inspected.filePath)) || 'unknown',
+      toFormat: 'wav',
+      sourceDuration: media?.duration,
+      targetDuration: clampNumber(Number(media?.duration ?? ASSET_AUDIO_MIN_SECONDS), ASSET_AUDIO_MIN_SECONDS, ASSET_AUDIO_MAX_SECONDS),
+      sourceFile: inspected.filePath,
+      reason: validation.violations.map((item) => item.message).join('；'),
+    });
+  }
+  return null;
+}
+
+function dryRunAssetFileName(source) {
+  const plan = source.conversionPlan;
+  if (!plan?.toFormat) return source.localFile?.filePath;
+  return forceFileExtension(source.localFile?.fileName || source.localFile?.filePath || 'asset', `.${conversionOutputExtension(plan.toFormat)}`);
+}
+
+async function convertLocalVideoFile(filePath, plan) {
+  const ffmpegCommand = await ensureFfmpegAvailable();
+  const outputPath = path.join(tmpdir(), `lj-awb-${crypto.randomUUID()}.mp4`);
+  const args = [
+    '-y',
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-i',
+    filePath,
+    '-vf',
+    plan.filters,
+    '-map',
+    '0:v:0',
+    '-map',
+    '0:a?',
+    '-c:v',
+    'libx264',
+    '-pix_fmt',
+    'yuv420p',
+    '-preset',
+    'medium',
+    '-crf',
+    '20',
+    '-movflags',
+    '+faststart',
+  ];
+  if (Number.isFinite(Number(plan.sourceDuration)) && plan.sourceDuration > ASSET_VIDEO_MAX_SECONDS) {
+    args.push('-t', String(ASSET_VIDEO_MAX_SECONDS));
+  } else if (Number.isFinite(Number(plan.sourceDuration)) && plan.sourceDuration < ASSET_VIDEO_MIN_SECONDS) {
+    args.push('-t', String(ASSET_VIDEO_MIN_SECONDS));
+  }
+  args.push('-c:a', 'aac', '-b:a', '128k', outputPath);
+  try {
+    await execFileAsync(ffmpegCommand, args, { timeout: 15 * 60_000, maxBuffer: 8 * 1024 * 1024 });
+  } catch (error) {
+    await fs.rm(outputPath, { force: true }).catch(() => {});
+    throw argumentError(
+      `视频格式转换失败：${path.basename(filePath)}`,
+      `请确认本机可用 ffmpeg，或手动转换后重试。${error?.message ? ` 原因：${error.message}` : ''}`,
+    );
+  }
+  const inspected = await inspectLocalFile(outputPath);
+  if (!inspected.exists) {
+    throw argumentError(`视频格式转换失败：${path.basename(filePath)}`, '未生成目标视频文件。');
+  }
+  return inspected;
+}
+
+async function convertLocalAudioFile(filePath, plan) {
+  const ffmpegCommand = await ensureFfmpegAvailable();
+  const outputPath = path.join(tmpdir(), `lj-awb-${crypto.randomUUID()}.wav`);
+  const args = [
+    '-y',
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-i',
+    filePath,
+  ];
+  if (Number.isFinite(Number(plan.sourceDuration)) && plan.sourceDuration < ASSET_AUDIO_MIN_SECONDS) {
+    args.push('-af', 'apad');
+    args.push('-t', String(ASSET_AUDIO_MIN_SECONDS));
+  } else if (Number.isFinite(Number(plan.sourceDuration)) && plan.sourceDuration > ASSET_AUDIO_MAX_SECONDS) {
+    args.push('-t', String(ASSET_AUDIO_MAX_SECONDS));
+  }
+  args.push('-c:a', 'pcm_s16le', outputPath);
+  try {
+    await execFileAsync(ffmpegCommand, args, { timeout: 15 * 60_000, maxBuffer: 8 * 1024 * 1024 });
+  } catch (error) {
+    await fs.rm(outputPath, { force: true }).catch(() => {});
+    throw argumentError(
+      `音频格式转换失败：${path.basename(filePath)}`,
+      `请确认本机可用 ffmpeg，或手动转换后重试。${error?.message ? ` 原因：${error.message}` : ''}`,
+    );
+  }
+  const inspected = await inspectLocalFile(outputPath);
+  if (!inspected.exists) {
+    throw argumentError(`音频格式转换失败：${path.basename(filePath)}`, '未生成目标音频文件。');
+  }
+  return inspected;
+}
+
+async function convertLocalImageFile(filePath, targetFormat, options = {}) {
+  const ffmpegCommand = await ensureFfmpegAvailable();
+  const target = normalizeFileFormat(targetFormat) || 'jpg';
+  const outputPath = options.outputPath || path.join(tmpdir(), `lj-awb-${crypto.randomUUID()}.${conversionOutputExtension(target)}`);
+  const codecArgs = target === 'jpg' ? ['-q:v', String(options.quality ?? 2)] : [];
+  const filterArgs = options.filters ? ['-vf', options.filters] : [];
+  try {
+    await execFileAsync(ffmpegCommand, [
+      '-y',
+      '-hide_banner',
+      '-loglevel',
+      'error',
+      '-i',
+      filePath,
+      ...filterArgs,
+      '-frames:v',
+      '1',
+      ...codecArgs,
+      outputPath,
+    ], { timeout: 10 * 60_000, maxBuffer: 8 * 1024 * 1024 });
+  } catch (error) {
+    await fs.rm(outputPath, { force: true }).catch(() => {});
+    throw argumentError(
+      `图片格式转换失败：${path.basename(filePath)}`,
+      `需要把该图片转换为 ${target} 后提交。请确认本机可用 ffmpeg，或手动转换后重试。${error?.message ? ` 原因：${error.message}` : ''}`,
+    );
+  }
+  const inspected = await inspectLocalFile(outputPath);
+  if (!inspected.exists) {
+    throw argumentError(`图片格式转换失败：${path.basename(filePath)}`, `未生成 ${target} 文件。`);
+  }
+  return inspected;
+}
+
+async function inspectAssetLocalFile(localFile) {
+  const inspected = await inspectLocalFile(localFile);
+  if (!inspected.exists) throw argumentError(`文件不存在：${localFile}`);
+  const ext = sourceExtension(inspected.filePath);
+  const assetType = inferAssetTypeFromSource(inspected.filePath);
+  if (assetType === ASSET_TYPE_CODES.Image) {
+    const media = await readImageMetadata(inspected.filePath);
+    const validation = validateAssetViolations(assetType, inspected, media);
+    return {
+      ...validation,
+      localFile: inspected,
+      media,
+      conversionPlan: validation.legal ? null : buildAssetConversionPlan(validation),
+    };
+  }
+  if (assetType === ASSET_TYPE_CODES.Video) {
+    const media = await readMediaMetadata(inspected.filePath, assetType);
+    const validation = validateAssetViolations(assetType, inspected, media);
+    return {
+      ...validation,
+      localFile: inspected,
+      media,
+      conversionPlan: validation.legal ? null : buildAssetConversionPlan(validation),
+    };
+  }
+  if (assetType === ASSET_TYPE_CODES.Audio) {
+    const media = await readMediaMetadata(inspected.filePath, assetType);
+    const validation = validateAssetViolations(assetType, inspected, media);
+    return {
+      ...validation,
+      localFile: inspected,
+      media,
+      conversionPlan: validation.legal ? null : buildAssetConversionPlan(validation),
+    };
+  }
+  throw argumentError(`不支持的素材格式：${ext}`);
+}
+
+function assetValidationSummary(validation) {
+  return validation.violations.map((item) => item.message).join('；');
+}
+
+function assetConversionUnavailableError(validation) {
+  const summary = assetValidationSummary(validation);
+  return argumentError(
+    `素材不符合 JIMENG 加白规格：${summary || '规格不合法'}`,
+    'CLI 无法自动生成转码计划，请手动转换为合法图片 / 视频 / 音频规格后重试。',
+  );
+}
+
+async function confirmAssetConversion(validation) {
+  if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+    throw argumentError(
+      `素材不符合 JIMENG 加白规格：${assetValidationSummary(validation)}`,
+      '非交互终端不会自动询问。请在终端中重试并确认转码，或追加 --auto-convert 自动转换后继续。',
+    );
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question(`素材不符合 JIMENG 加白规格：${assetValidationSummary(validation)}\n是否自动转码为合法规格后继续？[y/N] `);
+    return ['y', 'yes'].includes(String(answer || '').trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+
+async function convertAssetLocalFile(validation) {
+  const plan = validation.conversionPlan;
+  if (!plan) throw assetConversionUnavailableError(validation);
+  let converted;
+  if (validation.assetType === ASSET_TYPE_CODES.Image) {
+    converted = await convertLocalImageFile(validation.localFile.filePath, plan.toFormat, { filters: plan.filters });
+  } else if (validation.assetType === ASSET_TYPE_CODES.Video) {
+    converted = await convertLocalVideoFile(validation.localFile.filePath, plan);
+  } else if (validation.assetType === ASSET_TYPE_CODES.Audio) {
+    converted = await convertLocalAudioFile(validation.localFile.filePath, plan);
+  } else {
+    throw assetConversionUnavailableError(validation);
+  }
+  const nextValidation = await inspectAssetLocalFile(converted.filePath);
+  if (!nextValidation.legal) {
+    await fs.rm(converted.filePath, { force: true }).catch(() => {});
+    throw argumentError(
+      `素材自动转码后仍不符合加白规格：${assetValidationSummary(nextValidation)}`,
+      '请手动转换为合法规格后重试，或检查原始素材是否损坏。',
+    );
+  }
+  return {
+    ...nextValidation,
+    originalLocalFile: validation.localFile,
+    conversion: compactRecord({
+      ...plan,
+      converted: true,
+      convertedFile: converted.filePath,
+      convertedSize: converted.size,
+      originalSize: validation.localFile.size,
+    }),
+  };
+}
+
+async function resolveInvalidAssetLocalFile(validation, kwargs = {}) {
+  if (validation.legal) return validation;
+  if (!validation.conversionPlan) throw assetConversionUnavailableError(validation);
+  const shouldConvert = toBool(kwargs.autoConvert) || await confirmAssetConversion(validation);
+  if (!shouldConvert) {
+    throw argumentError(
+      `素材不符合 JIMENG 加白规格：${assetValidationSummary(validation)}`,
+      '已取消自动转码。请手动转换素材，或追加 --auto-convert 自动转换后继续。',
+    );
+  }
+  return await convertAssetLocalFile(validation);
+}
+
+function validateAssetRemoteSource(assetPath) {
+  return { assetType: inferAssetTypeFromSource(assetPath) };
+}
+
+export async function uploadFilesCommand(kwargs = {}) {
+  const specs = await collectFileSpecs(kwargs, trimToNull(kwargs.sceneType));
+  if (!specs.length) throw argumentError('缺少上传文件', '传 --file <path> 或 --files a.png,b.mp4。');
+  if (toBool(kwargs.dryRun)) {
+    const files = [];
+    for (const spec of specs) {
+      const inspected = await inspectLocalFile(spec.file);
+      files.push(compactRecord({
+        ...inspected,
+        sceneType: spec.sceneType,
+        projectNo: spec.projectNo,
+        backendPath: dryRunBackendPath(spec.file, spec.sceneType),
+        url: null,
+        dryRun: true,
+      }));
+    }
+    return { dryRun: true, files };
+  }
+  const files = [];
+  for (const spec of specs) {
+    files.push(await uploadLocalFile(spec.file, spec));
+  }
+  return { files };
+}
+
+export async function uploadLocalFile(filePath, options = {}) {
+  const inspected = await inspectLocalFile(filePath);
+  if (!inspected.exists) {
+    throw argumentError(`文件不存在：${filePath}`);
+  }
+  const buffer = await fs.readFile(inspected.filePath);
+  const sceneType = options.sceneType ?? defaultUploadSceneForFile(inspected.filePath, inspected.mimeType);
+  const groupId = crypto.randomUUID().replaceAll('-', '');
+  const secret = await awbApi.fetchUploadSecret({
+    sceneType,
+    groupId,
+    projectNo: options.projectNo ?? '',
+  });
+  const credentials = secret.credentials ?? secret;
+  const objectName = `${secret.path ?? ''}${secret.prefix ?? ''}${Date.now()}-${safeFileName(inspected.filePath)}`.replace(/^\/+/, '');
+  const host = `${secret.bucket}.cos.${secret.region}.myqcloud.com`;
+  const authorization = buildCosAuthorization({
+    secretKey: credentials.tmpSecretKey,
+    secretId: credentials.tmpSecretId,
+    method: 'PUT',
+    objectName,
+    contentLength: buffer.length,
+    host,
+    startTime: secret.startTime,
+    expiredTime: secret.expiredTime,
+  });
+  const response = await fetch(`https://${host}/${encodeObjectNamePath(objectName)}`, {
+    method: 'PUT',
+    headers: {
+      authorization,
+      'content-length': String(buffer.length),
+      'content-type': inspected.mimeType || guessMimeType(inspected.filePath),
+      host,
+      'x-cos-security-token': credentials.sessionToken,
+    },
+    body: buffer,
+  });
+  if (!response.ok) {
+    throw new LingjingAwbCliError(`上传 COS 失败：${response.status} ${response.statusText}`, {
+      type: 'upload_failed',
+      exitCode: 30,
+      details: { filePath: inspected.filePath, objectName },
+    });
+  }
+  return compactRecord({
+    ...inspected,
+    sceneType,
+    projectNo: options.projectNo ?? '',
+    backendPath: `/${objectName}`,
+    url: `https://${host}/${encodeObjectNamePath(objectName)}`,
+  });
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value || '').trim());
+}
+
+function backendObjectName(value) {
+  const text = trimToNull(value);
+  if (!text) return null;
+  return text.replace(/^\/+/, '');
+}
+
+function isPlatformBackendPath(value) {
+  const objectName = backendObjectName(value);
+  if (!objectName || /^[a-z][a-z0-9+.-]*:\/\//i.test(objectName)) return false;
+  return PLATFORM_BACKEND_PATH_PREFIXES.some((prefix) => objectName.startsWith(prefix));
+}
+
+function isUploadedMaterialReference(value) {
+  const text = trimToNull(value);
+  if (!text) return false;
+  if (isPlatformBackendPath(text)) return true;
+  if (!isHttpUrl(text)) return false;
+  try {
+    const url = new URL(text);
+    return url.hostname.endsWith('.myqcloud.com') && isPlatformBackendPath(decodeURIComponent(url.pathname));
+  } catch {
+    return false;
+  }
+}
+
+function remoteFileNameFromUrl(remoteUrl, fallback = 'voice-audio') {
+  try {
+    const pathname = decodeURIComponent(new URL(remoteUrl).pathname);
+    const baseName = safeFileName(path.basename(pathname));
+    if (baseName && baseName !== '.' && baseName !== '/') return baseName;
+  } catch {}
+  return `${fallback}.mp3`;
+}
+
+function extensionFromContentType(contentType = '') {
+  const normalized = String(contentType || '').split(';')[0].trim().toLowerCase();
+  if (normalized === 'image/bmp') return '.bmp';
+  if (normalized === 'image/gif') return '.gif';
+  if (normalized === 'image/jpeg' || normalized === 'image/jpg') return '.jpg';
+  if (normalized === 'image/png') return '.png';
+  if (normalized === 'image/webp') return '.webp';
+  if (normalized === 'audio/mpeg') return '.mp3';
+  if (normalized === 'audio/wav' || normalized === 'audio/x-wav') return '.wav';
+  if (normalized === 'audio/mp4') return '.m4a';
+  if (normalized === 'audio/aac') return '.aac';
+  if (normalized === 'audio/ogg') return '.ogg';
+  if (normalized === 'video/mp4') return '.mp4';
+  return '';
+}
+
+function isSupportedRemoteVoiceDownload(contentType = '', fileName = '') {
+  const normalized = String(contentType || '').split(';')[0].trim().toLowerCase();
+  const extension = path.extname(fileName).toLowerCase();
+  if (REMOTE_VOICE_MIME_TYPES.has(normalized)) return true;
+  if ((!normalized || normalized === 'application/octet-stream') && REMOTE_VOICE_EXTENSIONS.has(extension)) return true;
+  return false;
+}
+
+function remoteImageFileNameFromValue(value, fallback = 'resource-image') {
+  const text = trimToNull(value);
+  if (text) {
+    try {
+      const pathname = decodeURIComponent(new URL(text).pathname);
+      const baseName = safeFileName(path.basename(pathname));
+      if (baseName && baseName !== '.' && baseName !== '/') return baseName;
+    } catch {
+      const baseName = safeFileName(path.basename(text.split('?')[0].split('#')[0]));
+      if (baseName && baseName !== '.' && baseName !== '/') return baseName;
+    }
+  }
+  return fallback;
+}
+
+function extensionForImageFormat(format) {
+  const normalized = normalizeFileFormat(format);
+  if (!normalized) return '';
+  return normalized === 'jpg' ? '.jpg' : `.${normalized}`;
+}
+
+function forceFileExtension(fileName, extension) {
+  const safeName = safeFileName(fileName || 'resource-image');
+  if (!extension) return safeName;
+  return `${path.basename(safeName, path.extname(safeName))}${extension}`;
+}
+
+function isSupportedRemoteImageDownload(contentType = '', fileName = '', expectedFormat = null) {
+  const normalized = String(contentType || '').split(';')[0].trim().toLowerCase();
+  const extension = path.extname(fileName).toLowerCase();
+  if (REMOTE_IMAGE_MIME_TYPES.has(normalized)) return true;
+  if ((!normalized || normalized === 'application/octet-stream') && REMOTE_IMAGE_EXTENSIONS.has(extension)) return true;
+  if ((!normalized || normalized === 'application/octet-stream') && expectedFormat && COMMON_IMAGE_FORMATS.has(normalizeFileFormat(expectedFormat))) return true;
+  return false;
+}
+
+function firstHttpUrl(value, depth = 0) {
+  if (depth > 4 || value == null) return null;
+  if (typeof value === 'string') return /^https?:\/\//i.test(value) ? value : null;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = firstHttpUrl(item, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (typeof value !== 'object') return null;
+  for (const key of ['url', 'signedUrl', 'signUrl', 'downloadUrl', 'cosUrl', 'previewUrl', 'data']) {
+    const found = firstHttpUrl(value[key], depth + 1);
+    if (found) return found;
+  }
+  for (const nested of Object.values(value)) {
+    const found = firstHttpUrl(nested, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+async function resolveRemoteResourceDownloadUrl(value) {
+  const text = trimToNull(value);
+  if (!text) throw argumentError('远程图片来源为空');
+  if (/^https?:\/\//i.test(text)) return text;
+  if (isPlatformBackendPath(text)) {
+    const objectName = backendObjectName(text);
+    const signed = await awbApi.fetchObjectSignUrl(objectName);
+    const signedUrl = firstHttpUrl(signed);
+    if (signedUrl) return signedUrl;
+    throw new LingjingAwbCliError('获取素材签名 URL 失败', {
+      type: 'api_error',
+      exitCode: 30,
+      details: { objectName, payload: signed },
+    });
+  }
+  throw argumentError(
+    `远程图片来源不支持自动转换：${text}`,
+    '请传 http(s) URL、平台 backendPath，或先下载为本地文件后重试。',
+  );
+}
+
+async function downloadRemoteImageFileToTemp(sourceValue, options = {}) {
+  const timeoutMs = Math.max(1_000, toInt(options.timeoutMs, REMOTE_IMAGE_DOWNLOAD_TIMEOUT_MS));
+  const maxBytes = Math.max(1, toInt(options.maxBytes, REMOTE_IMAGE_DOWNLOAD_MAX_BYTES));
+  const remoteUrl = await resolveRemoteResourceDownloadUrl(sourceValue);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let dir = null;
+  try {
+    const response = await fetch(remoteUrl, { signal: controller.signal });
+    if (!response.ok) {
+      throw new LingjingAwbCliError(`下载远程图片失败：${response.status} ${response.statusText}`, {
+        type: 'http_error',
+        exitCode: 30,
+        details: { url: sourceValue, status: response.status },
+      });
+    }
+    const contentType = response.headers.get('content-type') || '';
+    const expectedExtension = extensionForImageFormat(options.expectedFormat);
+    let fileName = remoteImageFileNameFromValue(sourceValue, options.fallbackName || 'resource-image');
+    fileName = expectedExtension
+      ? forceFileExtension(fileName, expectedExtension)
+      : (!path.extname(fileName) ? `${fileName}${extensionFromContentType(contentType) || '.img'}` : fileName);
+    if (!isSupportedRemoteImageDownload(contentType, fileName, options.expectedFormat)) {
+      throw argumentError(
+        `远程图片类型不支持：${contentType || path.extname(fileName) || 'unknown'}`,
+        '自动格式转换只支持常见图片输入，请先手动转换为 jpg/png/webp 后重试。',
+      );
+    }
+    const contentLength = toInt(response.headers.get('content-length'), 0);
+    if (contentLength > maxBytes) {
+      throw argumentError(`远程图片过大：${contentLength} bytes`, `最大支持 ${maxBytes} bytes。`);
+    }
+    dir = await fs.mkdtemp(path.join(tmpdir(), 'lj-awb-image-'));
+    const filePath = path.join(dir, fileName);
+    const file = await fs.open(filePath, 'w');
+    let size = 0;
+    try {
+      if (!response.body) throw new Error('empty response body');
+      for await (const chunk of response.body) {
+        const buffer = Buffer.from(chunk);
+        size += buffer.length;
+        if (size > maxBytes) {
+          throw argumentError(`远程图片过大：超过 ${maxBytes} bytes`);
+        }
+        await file.write(buffer);
+      }
+    } finally {
+      await file.close();
+    }
+    return { filePath, dir, contentType, size };
+  } catch (error) {
+    if (dir) await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+    if (error instanceof LingjingAwbCliError) throw error;
+    const isAbort = error?.name === 'AbortError';
+    throw new LingjingAwbCliError(`下载远程图片失败：${error.message}`, {
+      type: 'network_error',
+      exitCode: 30,
+      hint: isAbort ? `远程下载超过 ${timeoutMs}ms，请改用本地文件或已上传平台 backendPath。` : '',
+      details: { url: sourceValue, causeCode: error?.cause?.code },
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function downloadRemoteFileToTemp(remoteUrl, options = {}) {
+  const timeoutMs = Math.max(1_000, toInt(options.timeoutMs, REMOTE_VOICE_DOWNLOAD_TIMEOUT_MS));
+  const maxBytes = Math.max(1, toInt(options.maxBytes, REMOTE_VOICE_DOWNLOAD_MAX_BYTES));
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let dir = null;
   let response;
   try {
     response = await fetch(remoteUrl, { signal: controller.signal });
@@ -2589,7 +3926,7 @@ async function downloadRemoteFileToTemp(remoteUrl, options = {}) {
     throw new LingjingAwbCliError(`下载远程音频失败：${error.message}`, {
       type: 'network_error',
       exitCode: 30,
-      hint: isAbort ? `远程下载超过 ${timeoutMs}ms，请改用本地 --file 或已上传 material 路径。` : '',
+      hint: isAbort ? `远程下载超过 ${timeoutMs}ms，请改用本地 --file 或已上传平台 backendPath。` : '',
       details: { url: remoteUrl, causeCode: error?.cause?.code },
     });
   } finally {
@@ -2635,6 +3972,59 @@ function normalizeUnifiedPromptParams(promptParams) {
   return promptParams;
 }
 
+async function parseModelParamsJsonArg(value) {
+  const parsed = await readJsonMaybeFile(value, null).catch((error) => {
+    throw argumentError(`model-params-json 解析失败：${error.message}`);
+  });
+  if (parsed == null) return {};
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw argumentError('model-params-json 必须是 JSON 对象');
+  }
+  return parsed;
+}
+
+function parseModelParamAssignments(value) {
+  const params = {};
+  for (const item of parseListArg(value)) {
+    const text = trimToNull(item);
+    if (!text) continue;
+    const eqIndex = text.indexOf('=');
+    if (eqIndex <= 0) {
+      throw argumentError(`model-param 格式错误：${text}`, '格式为 --model-param key=value，可重复传。');
+    }
+    const key = trimToNull(text.slice(0, eqIndex));
+    if (!key) {
+      throw argumentError(`model-param 缺少 key：${text}`);
+    }
+    params[key] = text.slice(eqIndex + 1);
+  }
+  return params;
+}
+
+async function collectGenericModelParams(kwargs = {}) {
+  const fromJson = await parseModelParamsJsonArg(kwargs.modelParamsJson ?? kwargs.model_params_json);
+  const fromObject = kwargs.modelParams && typeof kwargs.modelParams === 'object' && !Array.isArray(kwargs.modelParams)
+    ? kwargs.modelParams
+    : {};
+  const fromAssignments = parseModelParamAssignments(kwargs.modelParam);
+  const fromDynamicFlags = {};
+  for (const [key, value] of Object.entries(kwargs || {})) {
+    if (CREATE_STANDARD_KWARG_KEYS.has(key)) continue;
+    if (!key.includes('_') && !isLikelyDynamicModelParamKey(key)) continue;
+    fromDynamicFlags[key] = value;
+  }
+  return normalizeUnifiedPromptParams({
+    ...fromJson,
+    ...fromObject,
+    ...fromDynamicFlags,
+    ...fromAssignments,
+  });
+}
+
+function isLikelyDynamicModelParamKey(key) {
+  return /^(generation|prompt|negative|seed|style|mode|cfg|guidance|aspect|image|output|response|media|safety|watermark|camera|motion|strength|steps)[A-Z]/.test(String(key || ''));
+}
+
 function normalizeResourceType(type, index) {
   const normalized = String(type ?? '').trim().toLowerCase();
   if (!RESOURCE_TYPES.has(normalized)) {
@@ -2670,7 +4060,7 @@ function normalizeResourceSource(source, type, index, options = {}) {
   if (!['url', 'asset_id'].includes(kind)) {
     throw argumentError(
       `resource[${index}] source.kind 不支持：${explicitKind}`,
-      '只支持 url、asset_id 两个值。本地文件 / http(s) URL / material backendPath 都统一传 kind=url（CLI 按 value 自动识别）；平台资产或主体对象传 kind=asset_id。',
+      '只支持 url、asset_id 两个值。本地文件 / http(s) URL / 平台 backendPath 都统一传 kind=url（CLI 按 value 自动识别）；平台资产或主体对象传 kind=asset_id。',
     );
   }
   const value = kind === 'asset_id' ? assetValue : rawValue;
@@ -2831,59 +4221,39 @@ function isRemoteOrBackendPath(value) {
   if (!text) return false;
   return /^https?:\/\//i.test(text)
     || /^[a-z][a-z0-9+.-]*:\/\//i.test(text)
-    || text.startsWith('material/')
-    || text.startsWith('/material/');
+    || isPlatformBackendPath(text);
 }
 
-function normalizeMaterialUrlValue(value) {
+function normalizeBackendPathUrlValue(value) {
   const text = trimToNull(value);
   if (!text) return text;
   if (/^https?:\/\//i.test(text)) {
     try {
       const pathname = decodeURIComponent(new URL(text).pathname);
-      if (pathname.startsWith('/material/')) return pathname;
+      if (isPlatformBackendPath(pathname)) return pathname;
     } catch {}
   }
   return text;
 }
 
+function displayResourceSourceValue(value) {
+  const text = trimToNull(value);
+  if (!text || !/^https?:\/\//i.test(text)) return text;
+  try {
+    const url = new URL(text);
+    const format = imageTransformFormat(text);
+    return `${url.origin}${decodeURIComponent(url.pathname)}${format ? `?format=${format}` : ''}`;
+  } catch {
+    return text.split('?')[0];
+  }
+}
+
 function conversionOutputExtension(format) {
   const normalized = normalizeFileFormat(format);
   if (normalized === 'jpg') return 'jpg';
   return normalized || 'jpg';
 }
 
-async function convertLocalImageFile(filePath, targetFormat) {
-  const target = normalizeFileFormat(targetFormat) || 'jpg';
-  const outputPath = path.join(tmpdir(), `lj-awb-${crypto.randomUUID()}.${conversionOutputExtension(target)}`);
-  const codecArgs = target === 'jpg' ? ['-q:v', '2'] : [];
-  try {
-    await execFileAsync('ffmpeg', [
-      '-y',
-      '-hide_banner',
-      '-loglevel',
-      'error',
-      '-i',
-      filePath,
-      '-frames:v',
-      '1',
-      ...codecArgs,
-      outputPath,
-    ]);
-  } catch (error) {
-    await fs.rm(outputPath, { force: true }).catch(() => {});
-    throw argumentError(
-      `图片格式转换失败：${path.basename(filePath)}`,
-      `需要把该帧图片转换为 ${target} 后提交。请确认本机可用 ffmpeg，或手动转换后重试。${error?.message ? ` 原因：${error.message}` : ''}`,
-    );
-  }
-  const inspected = await inspectLocalFile(outputPath);
-  if (!inspected.exists) {
-    throw argumentError(`图片格式转换失败：${path.basename(filePath)}`, `未生成 ${target} 文件。`);
-  }
-  return inspected;
-}
-
 async function resolveResourceFileValue(resource, options = {}) {
   if (resource.type === 'subject') {
     if (resource._source.kind !== 'asset_id') throw argumentError('subject resource 必须使用 asset_id，例如 subject:reference:hero=asset:element_123');
@@ -2911,13 +4281,67 @@ async function resolveResourceFileValue(resource, options = {}) {
   }
   const value = resource._source.value;
   if (isRemoteOrBackendPath(value)) {
-    return { resource: { ...base, source: { kind: 'url', value: normalizeMaterialUrlValue(value) } }, upload: null, localFile: null };
+    const source = { kind: 'url', value };
+    const conversion = options.resourceRules
+      ? resourceFormatConversion(
+        options.resourceRules.find((item) => resourceRuleMatches(item, { ...base, source })),
+        { resource: { ...base, source } },
+      )
+      : null;
+    if (conversion) {
+      const conversionRecord = compactRecord({
+        resource: resourceText(base),
+        fromFormat: conversion.fromFormat,
+        toFormat: conversion.toFormat,
+        reason: conversion.reason,
+        sourceValue: displayResourceSourceValue(value),
+        dryRun: options.dryRun || undefined,
+      });
+      const convertedName = forceFileExtension(
+        remoteImageFileNameFromValue(value, resourceText(base).replace(/[^0-9A-Za-z._-]+/g, '-')),
+        extensionForImageFormat(conversion.toFormat),
+      );
+      if (options.dryRun) {
+        return {
+          resource: { ...base, source: { kind: 'url', value: dryRunBackendPath(convertedName, options.sceneType) } },
+          upload: null,
+          localFile: null,
+          conversion: conversionRecord,
+        };
+      }
+      const downloaded = await downloadRemoteImageFileToTemp(value, {
+        expectedFormat: conversion.fromFormat,
+        fallbackName: resourceText(base).replace(/[^0-9A-Za-z._-]+/g, '-'),
+      });
+      try {
+        const converted = await convertLocalImageFile(downloaded.filePath, conversion.toFormat);
+        try {
+          const upload = await uploadLocalFile(converted.filePath, { sceneType: options.sceneType });
+          return {
+            resource: { ...base, source: { kind: 'url', value: upload.backendPath } },
+            upload,
+            localFile: null,
+            conversion: {
+              ...conversionRecord,
+              sourceSize: downloaded.size,
+              convertedFile: converted.filePath,
+              convertedSize: converted.size,
+            },
+          };
+        } finally {
+          await fs.rm(converted.filePath, { force: true }).catch(() => {});
+        }
+      } finally {
+        await fs.rm(downloaded.dir, { recursive: true, force: true }).catch(() => {});
+      }
+    }
+    return { resource: { ...base, source: { kind: 'url', value: normalizeBackendPathUrlValue(value) } }, upload: null, localFile: null };
   }
   const inspected = await inspectLocalFile(value);
   if (!inspected.exists) {
     throw argumentError(
       `资源文件不存在：${value}`,
-      'source.kind=url 只接受完整 http(s) URL、material backendPath，或当前工作目录下存在的本地文件路径。',
+      'source.kind=url 只接受完整 http(s) URL、平台 backendPath，或当前工作目录下存在的本地文件路径。',
     );
   }
   const conversion = options.resourceRules
@@ -3040,7 +4464,9 @@ async function buildImageRequest(kwargs = {}, options = {}) {
     kind: 'image',
     sceneType: TASK_UPLOAD_SCENE.IMAGE_CREATE,
   });
+  const genericModelParams = await collectGenericModelParams(kwargs);
   const defaultParams = {
+    ...genericModelParams,
     prompt,
     resources: validationResources.resources,
   };
@@ -3218,7 +4644,9 @@ async function buildVideoRequest(kwargs = {}, options = {}) {
     throw argumentError('缺少视频生成输入', '至少传 --prompt 或 --resource。');
   }
   assertVideoReferenceKeysUsed(prompt, validationResources.resources);
+  const genericModelParams = await collectGenericModelParams(kwargs);
   const defaultParams = {
+    ...genericModelParams,
     prompt,
     resources: validationResources.resources,
   };
@@ -3349,6 +4777,11 @@ const IMAGE_BATCH_ITEM_KEYS = new Set([
   'quality',
   'generate_num',
   'generateNum',
+  'model_param',
+  'modelParam',
+  'model_params',
+  'modelParams',
+  'modelParamsJson',
   'resource',
   'resources',
   'resourcesJson',
@@ -3361,6 +4794,11 @@ const VIDEO_BATCH_ITEM_KEYS = new Set([
   'duration',
   'need_audio',
   'needAudio',
+  'model_param',
+  'modelParam',
+  'model_params',
+  'modelParams',
+  'modelParamsJson',
   'resource',
   'resources',
   'resourcesJson',
@@ -3372,18 +4810,21 @@ function normalizeTaskBatchItem(item, kind, index) {
     throw argumentError(`批量输入第 ${index + 1} 项必须是 JSON 对象或纯文本 prompt`);
   }
   const allowedKeys = kind === 'image' ? IMAGE_BATCH_ITEM_KEYS : VIDEO_BATCH_ITEM_KEYS;
-  const unknownKeys = Object.keys(item).filter((key) => !allowedKeys.has(key));
+  const unknownKeys = Object.keys(item).filter((key) => !allowedKeys.has(key) && !key.includes('_'));
   if (unknownKeys.length) {
     throw argumentError(
       `批量输入第 ${index + 1} 项存在未知字段：${unknownKeys.join(', ')}`,
       kind === 'image'
-        ? '生图批量项只接受 prompt、ratio、quality、generate_num、resources、resource、customBizId。'
-        : '生视频批量项只接受 prompt、ratio、quality、duration、need_audio、resources、resource、customBizId。',
+        ? '生图批量项只接受 prompt、ratio、quality、generate_num、resources、resource、model_params、customBizId，或 model options.params[] 中的下划线参数。'
+        : '生视频批量项只接受 prompt、ratio、quality、duration、need_audio、resources、resource、model_params、customBizId，或 model options.params[] 中的下划线参数。',
     );
   }
   const next = { ...item };
   if (next.generate_num != null && next.generateNum == null) next.generateNum = next.generate_num;
   if (next.need_audio != null && next.needAudio == null) next.needAudio = next.need_audio;
+  if (next.model_param != null && next.modelParam == null) next.modelParam = next.model_param;
+  if (next.model_params != null && next.modelParams == null) next.modelParams = next.model_params;
+  if (next.model_params_json != null && next.modelParamsJson == null) next.modelParamsJson = next.model_params_json;
   return next;
 }
 
@@ -3638,7 +5079,8 @@ function normalizeCosAssetPath(value) {
   if (!text) return null;
   if (/^https?:\/\//i.test(text)) {
     try {
-      return decodeURIComponent(new URL(text).pathname.replace(/^\/+/, ''));
+      const pathname = decodeURIComponent(new URL(text).pathname);
+      return isPlatformBackendPath(pathname) ? pathname.replace(/^\/+/, '') : text;
     } catch {
       return text.replace(/^\/+/, '');
     }
@@ -3926,37 +5368,68 @@ export async function assetRegister(kwargs = {}) {
   const localFile = trimToNull(kwargs.file);
   const assetPath = trimToNull(kwargs.backendPath) ?? normalizeCosAssetPath(kwargs.url);
   if (!localFile && !assetPath) throw argumentError('缺少素材路径', '传 --file、--backend-path 或 --url。');
+  let source = localFile ? await inspectAssetLocalFile(localFile) : validateAssetRemoteSource(assetPath);
   if (toBool(kwargs.dryRun)) {
+    const dryRunFileName = localFile ? dryRunAssetFileName(source) : null;
+    const url = localFile ? normalizeCosAssetPath(dryRunBackendPath(dryRunFileName, TASK_UPLOAD_SCENE.ASSET_REVIEW)) : assetPath;
     return {
       dryRun: true,
       action: 'create asset',
+      groupId,
+      name,
+      platform,
+      assetType: source.assetType,
+      assetPath: url,
       request: {
         assetGroupsId: groupId,
-        url: localFile ? normalizeCosAssetPath(dryRunBackendPath(localFile, TASK_UPLOAD_SCENE.ASSET_REVIEW)) : assetPath,
+        url,
         name,
         platform,
+        assetType: source.assetType,
       },
-      localFile: localFile ? await inspectLocalFile(localFile) : null,
+      localFile: source.localFile ?? null,
+      originalLocalFile: source.originalLocalFile ?? null,
+      media: source.media ?? null,
+      validation: source.legal === false ? {
+        legal: false,
+        violations: source.violations,
+      } : { legal: true },
+      conversionPlan: source.conversionPlan ?? null,
     };
   }
-  ensureConfirmed(kwargs, '注册素材是云端写入动作，需要确认', { action: 'create asset', groupId, name });
-  const uploaded = localFile ? await uploadLocalFile(localFile, { sceneType: TASK_UPLOAD_SCENE.ASSET_REVIEW }) : null;
-  const body = {
-    assetGroupsId: groupId,
-    url: normalizeCosAssetPath(uploaded?.backendPath ?? assetPath),
-    name,
-    platform,
-  };
-  const payload = await awbApi.registerAsset(body);
-  return {
-    registered: true,
-    assetId: extractAssetId(payload),
-    groupId,
-    name,
-    platform,
-    assetPath: body.url,
-    ...(uploaded ? { upload: uploaded } : {}),
-  };
+  if (localFile && source.legal === false) {
+    source = await resolveInvalidAssetLocalFile(source, kwargs);
+  }
+  ensureConfirmed(kwargs, '注册素材是云端写入动作，需要确认', { action: 'create asset', groupId, name, assetType: source.assetType });
+  const uploadPath = source.localFile?.filePath ?? localFile;
+  let uploaded = null;
+  try {
+    uploaded = localFile ? await uploadLocalFile(uploadPath, { sceneType: TASK_UPLOAD_SCENE.ASSET_REVIEW }) : null;
+    const body = {
+      assetGroupsId: groupId,
+      url: normalizeCosAssetPath(uploaded?.backendPath ?? assetPath),
+      name,
+      platform,
+      assetType: source.assetType,
+    };
+    const payload = await awbApi.registerAsset(body);
+    return {
+      registered: true,
+      assetId: extractAssetId(payload),
+      groupId,
+      name,
+      platform,
+      assetType: source.assetType,
+      assetPath: body.url,
+      media: source.media ?? null,
+      ...(source.conversion ? { conversion: source.conversion } : {}),
+      ...(uploaded ? { upload: uploaded } : {}),
+    };
+  } finally {
+    if (source.conversion?.convertedFile) {
+      await fs.rm(source.conversion.convertedFile, { force: true }).catch(() => {});
+    }
+  }
 }
 
 export async function subjectList(kwargs = {}) {
@@ -4497,3 +5970,99 @@ export async function subtitleStatus(kwargs = {}) {
     taskType: 'VIDEO_SUBTITLE_REMOVAL',
   });
 }
+
+export async function videoSuperResolutionStatus(kwargs = {}) {
+  const taskId = requireValue(kwargs, 'taskId', 'task-id');
+  return taskStatus({
+    ...kwargs,
+    taskId,
+    taskType: 'VIDEO_SUPER_RESOLUTION',
+  });
+}
+
+async function buildVideoSuperResolutionRequest(kwargs = {}, options = {}) {
+  const objectName = trimToNull(kwargs.objectName);
+  if (!objectName) {
+    throw argumentError('缺少视频对象路径', '传 --object-name <objectName>；通常是 material 的 backendPath 或 COS 对象路径。');
+  }
+  const dryRun = Boolean(options.dryRun);
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, {
+    allowNull: true,
+    noNetwork: dryRun,
+    noSave: dryRun,
+  }).catch((error) => {
+    if (dryRun) return null;
+    throw error;
+  });
+  return {
+    objectName,
+    projectGroupNo,
+    request: compactRecord({
+      objectName,
+      projectGroupNo,
+    }),
+  };
+}
+
+export async function videoSuperResolutionFee(kwargs = {}) {
+  const built = await buildVideoSuperResolutionRequest(kwargs, { dryRun: toBool(kwargs.dryRun) });
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'create video-super-resolution-fee',
+      objectName: built.objectName,
+      projectGroupNo: built.projectGroupNo,
+      request: built.request,
+      materialEndpoint: '/api/material/creation/videoUpResolutionCal',
+      taskType: 'VIDEO_SUPER_RESOLUTION',
+    };
+  }
+  const payload = await awbApi.fetchVideoSuperResolutionFee(built.request);
+  return {
+    objectName: built.objectName,
+    projectGroupNo: built.projectGroupNo,
+    data: payload,
+    ...(await pointEstimate(payload, built.projectGroupNo)),
+  };
+}
+
+export async function videoSuperResolution(kwargs = {}) {
+  const built = await buildVideoSuperResolutionRequest(kwargs, { dryRun: toBool(kwargs.dryRun) });
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'create video-super-resolution',
+      objectName: built.objectName,
+      projectGroupNo: built.projectGroupNo,
+      request: built.request,
+      materialEndpoint: '/api/material/creation/videoUpResolution',
+      taskType: 'VIDEO_SUPER_RESOLUTION',
+    };
+  }
+  ensureConfirmed(kwargs, '正式视频超分会通过 material 创建任务并消耗积分，需要确认', {
+    action: 'create video-super-resolution',
+    objectName: built.objectName,
+  });
+  const feePayload = await awbApi.fetchVideoSuperResolutionFee(built.request).catch(() => null);
+  const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
+  const payload = await awbApi.createVideoSuperResolutionTask(built.request);
+  const result = normalizeCreatedTask(payload, {
+    ...estimate,
+    submitted: true,
+    taskType: 'VIDEO_SUPER_RESOLUTION',
+    objectName: built.objectName,
+    projectGroupNo: built.projectGroupNo,
+  });
+  await appendTaskRecord(kwargs, {
+    taskId: result.taskId,
+    taskType: 'VIDEO_SUPER_RESOLUTION',
+    projectGroupNo: built.projectGroupNo,
+    promptSummary: `视频超分 objectName=${built.objectName}`,
+  });
+  return {
+    ...result,
+    nextCommand: result.taskId
+      ? `lj-awb task video-super-resolution-status --task-id ${result.taskId}${built.projectGroupNo ? ` --project-group-no ${built.projectGroupNo}` : ''} -f json`
+      : null,
+  };
+}