@lingjingai/lj-awb-cli-pre 0.3.15 → 0.3.17

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

@@ -46,6 +46,21 @@ 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_VOICE_DOWNLOAD_TIMEOUT_MS = 30_000;
+const REMOTE_VOICE_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
+const REMOTE_VOICE_MIME_TYPES = new Set([
+  'audio/mpeg',
+  'audio/wav',
+  'audio/x-wav',
+  'audio/mp4',
+  'audio/aac',
+  'audio/ogg',
+  'video/mp4',
+]);
+const REMOTE_VOICE_EXTENSIONS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.mp4']);
+const ASSET_PLATFORM_CODES = ['JIMENG', 'BYTEPLUS'];
+const ASSET_PLATFORM_CODE_SET = new Set(ASSET_PLATFORM_CODES);
+const ASSET_PLATFORM_HINT = ASSET_PLATFORM_CODES.join('|');
 
 export function normalizeUserInfo(payload) {
   const data = payload && typeof payload === 'object' ? payload : {};
@@ -371,7 +386,6 @@ export async function doctor(kwargs = {}) {
     },
     origins: {
       apiOrigin: API_ORIGIN,
-      assetEditOrigin: awbApi.ASSET_EDIT_ORIGIN,
     },
     auth: summarizeAuth(auth, authContext.accessKeyInfo),
     paths: {
@@ -683,6 +697,7 @@ function normalizeModelRows(payload, kind, options = {}) {
     const row = compactRecord({
       modelGroupCode,
       displayName: item?.modelName ?? item?.name ?? item?.label ?? null,
+      modelDesc: item?.modelDesc ?? null,
       provider: item?.provider ?? item?.vendor ?? item?.supplier ?? item?.componyName ?? null,
       enabled: item?.enabled ?? item?.available ?? item?.status ?? null,
       modelStatus: item?.modelStatus ?? null,
@@ -720,6 +735,44 @@ export async function listModels(kind, kwargs = {}) {
   return { usage, models };
 }
 
+function requireAssetPlatform(value, options = {}) {
+  const flag = options.flag || '--platform';
+  const platform = trimToNull(value);
+  if (!platform) {
+    throw argumentError(`缺少参数：${flag}`, `素材加白平台必须显式传入 ${ASSET_PLATFORM_HINT}，不要依赖默认平台。`);
+  }
+  if (!ASSET_PLATFORM_CODE_SET.has(platform)) {
+    throw argumentError(`不支持的平台：${platform}`, `只接受 ${ASSET_PLATFORM_HINT}；请使用 model asset-review-models 查看模型支持的平台。`);
+  }
+  return platform;
+}
+
+function optionalAssetPlatform(value) {
+  if (value == null || value === '') return null;
+  return requireAssetPlatform(value);
+}
+
+function normalizeAssetReviewModelRecord(item = {}) {
+  return compactRecord({
+    modelGroupCode: item?.modelGroupCode ?? item?.groupCode ?? null,
+    platform: item?.platform ?? null,
+  });
+}
+
+export async function assetReviewModels(kwargs = {}) {
+  const modelGroupCode = trimToNull(kwargs.modelGroupCode);
+  const platform = optionalAssetPlatform(kwargs.platform);
+  const payload = await awbApi.fetchAssetReviewModels();
+  const models = normalizeRows(payload)
+    .map((item) => normalizeAssetReviewModelRecord(item))
+    .filter((item) => !modelGroupCode || item.modelGroupCode === modelGroupCode)
+    .filter((item) => !platform || item.platform === platform);
+  return {
+    models,
+    ...(toBool(kwargs.includeRaw) ? { raw: payload } : {}),
+  };
+}
+
 async function findModelGroup(modelGroupCode, options = {}) {
   const includeRaw = Boolean(options.includeRaw);
   const [imageResult, videoResult] = await Promise.allSettled([
@@ -898,9 +951,9 @@ function resourceSourceKindForValidation(detail = {}) {
 }
 
 function sourceAllowedByRule(rule = {}, sourceKind) {
-  const sources = Array.isArray(rule.sources) ? rule.sources : [];
-  if (!sources.length) return true;
-  return sources.includes(sourceKind);
+  const shapes = Array.isArray(rule.valueShapes) ? rule.valueShapes : [];
+  if (!shapes.length) return true;
+  return shapes.includes(sourceKind);
 }
 
 function resourceFormatForValidation(detail = {}) {
@@ -1033,7 +1086,7 @@ function assertResourceShapeAgainstModel(resourceDetails = [], resourceRules = [
     if (!sourceAllowedByRule(rule, sourceKind)) {
       throw argumentError(
         `模型不支持 ${resourceText(resource)} 的来源：${sourceKind}`,
-        `该资源允许来源：${(rule.sources || []).join(', ') || '未限制'}。`,
+        `该资源允许的 value 形状：${(rule.valueShapes || []).join(', ') || '未限制'}。`,
       );
     }
     const format = resourceFormatForValidation(detail);
@@ -1759,7 +1812,7 @@ function createSpecResourceRequirements(inputModes) {
       intent: item.intent,
       resource: item.requiredResources,
       syntax: item.resourceSyntax,
-      sources: item.sourceKinds,
+      valueShapes: item.sourceKinds,
       ...item.resourceLimits,
       promptBinding: item.promptBinding,
       constraints: item.resourceConstraints,
@@ -1898,7 +1951,7 @@ function createSpecValidationRules(taskKind) {
   ];
   if (taskKind === 'video') {
     rules.splice(4, 0, 'reference_key 仅用于视频 reference 资源的可选 prompt 占位符绑定；prompt 中出现 <<<key>>> 时，必须有同名 reference 资源。');
-    rules.push('subject reference 必须使用 asset:<externalId>，externalId 应来自 subject publish + subject wait。');
+    rules.push('subject reference 必须使用 asset:<externalId>，externalId 应来自 create subject + create subject-wait。');
   } else {
     rules.push('图片任务 resources 只接受 image reference，且不接受 reference_key 或 <<<key>>>；请用自然 prompt 描述图一、图二、参考图、主体等映射。');
   }
@@ -1907,8 +1960,8 @@ function createSpecValidationRules(taskKind) {
 
 function createSpecPreflight(taskKind) {
   const modelListCommand = taskKind === 'image' ? 'model image-models' : 'model video-models';
-  const feeCommand = taskKind === 'image' ? 'image fee' : 'video fee';
-  const createCommand = taskKind === 'image' ? 'image create' : 'video create';
+  const feeCommand = taskKind === 'image' ? 'create image-fee' : 'create video-fee';
+  const createCommand = taskKind === 'image' ? 'create image' : 'create video';
   return [
     'doctor --verify',
     `${modelListCommand} --model <keyword>`,
@@ -1927,26 +1980,26 @@ function createSpecExamples(taskKind, supportedIntents) {
   const examples = [];
   const hasIntent = (mode) => supportedIntents.some((item) => item.mode === mode);
   if (taskKind === 'image') {
-    if (hasIntent('prompt_only')) examples.push('lj-awb image create --model-group-code <code> --prompt "品牌吉祥物表情包四宫格" --ratio 1:1 --quality 1K --dry-run');
-    if (hasIntent('reference')) examples.push('lj-awb image create --model-group-code <code> --prompt "保持参考图主体，生成海报" --resource image:reference=./ref.png --dry-run');
+    if (hasIntent('prompt_only')) examples.push('lj-awb create image --model-group-code <code> --prompt "品牌吉祥物表情包四宫格" --ratio 1:1 --quality 1K --dry-run');
+    if (hasIntent('reference')) examples.push('lj-awb create image --model-group-code <code> --prompt "保持参考图主体，生成海报" --resource image:reference=./ref.png --dry-run');
   } else {
-    if (hasIntent('prompt_only')) examples.push('lj-awb video create --model-group-code <code> --prompt "机器人站在白色展台中央，缓慢转身" --duration 6 --dry-run');
+    if (hasIntent('prompt_only')) examples.push('lj-awb create video --model-group-code <code> --prompt "机器人站在白色展台中央，缓慢转身" --duration 6 --dry-run');
     if (hasIntent('reference')) {
       const referenceIntent = supportedIntents.find((item) => item.mode === 'reference');
-      examples.push('lj-awb video create --model-group-code <code> --prompt "人物转身看向镜头" --resource image:reference=./hero.png --duration 5 --dry-run');
+      examples.push('lj-awb create video --model-group-code <code> --prompt "人物转身看向镜头" --resource image:reference=./hero.png --duration 5 --dry-run');
       if (referenceIntent?.resourceSyntax?.some((item) => String(item).startsWith('audio:reference'))) {
-        examples.push('lj-awb video create --model-group-code <code> --prompt "让 <<<hero>>> 跟随音乐节奏转身" --resource image:reference:hero=./hero.png --resource audio:reference=./music.mp3 --duration 5 --dry-run');
+        examples.push('lj-awb create video --model-group-code <code> --prompt "让 <<<hero>>> 跟随音乐节奏转身" --resource image:reference:hero=./hero.png --resource audio:reference=./music.mp3 --duration 5 --dry-run');
       }
     }
     if (hasIntent('frames')) {
       const framesIntent = supportedIntents.find((item) => item.mode === 'frames');
-      examples.push('lj-awb video create --model-group-code <code> --prompt "镜头缓慢推进" --resource image:first_frame=./first.png --duration 5 --dry-run');
-      examples.push('lj-awb video create --model-group-code <code> --prompt "镜头缓慢推进" --resource image:first_frame=asset:<assetId> --duration 5 --dry-run');
+      examples.push('lj-awb create video --model-group-code <code> --prompt "镜头缓慢推进" --resource image:first_frame=./first.png --duration 5 --dry-run');
+      examples.push('lj-awb create video --model-group-code <code> --prompt "镜头缓慢推进" --resource image:first_frame=asset:<assetId> --duration 5 --dry-run');
       if (framesIntent?.resourceUsages?.includes('last_frame')) {
-        examples.push('lj-awb video create --model-group-code <code> --prompt "从第一张过渡到第二张" --resource image:first_frame=./first.png --resource image:last_frame=./last.png --duration 5 --dry-run');
+        examples.push('lj-awb create video --model-group-code <code> --prompt "从第一张过渡到第二张" --resource image:first_frame=./first.png --resource image:last_frame=./last.png --duration 5 --dry-run');
       }
     }
-    if (hasIntent('storyboard')) examples.push('lj-awb video create --model-group-code <code> --resources-json ./storyboard.json --duration 5 --dry-run');
+    if (hasIntent('storyboard')) examples.push('lj-awb create video --model-group-code <code> --resources-json ./storyboard.json --duration 5 --dry-run');
   }
   return examples;
 }
@@ -2019,7 +2072,7 @@ function modelOptionsResources(inputModes = []) {
           mode: 'frames',
           mediaType: 'IMAGE',
           usage: supportedFrameMode.optionResourceUsages,
-          sources: supportedFrameMode.sourceKinds,
+          valueShapes: supportedFrameMode.sourceKinds,
           ...supportedFrameMode.optionResourceLimits,
           formatPolicy: framePolicy.summary,
           webpSupported: framePolicy.webpSupported,
@@ -2036,7 +2089,7 @@ function modelOptionsResources(inputModes = []) {
       mode: optionResourceMode(sourceMode),
       mediaType,
       usage: optionResourceUsage(sourceMode),
-      sources: item.sources,
+      valueShapes: item.valueShapes,
       fileTypes: sourceMode === 'subject_reference' ? undefined : item.fileTypes,
       formatPolicy: imagePolicy?.summary,
       webpSupported: imagePolicy?.webpSupported,
@@ -2074,7 +2127,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 表示平台资产或主体对象 ID。' },
+      { 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.value', description: '资源值，必填。url 传素材地址；asset_id 传资源 ID。' },
       { field: 'resources[].order', description: '仅 usage=keyframe 时需要，且同一请求内不能重复。' },
       { field: 'resources[].duration', description: '仅 keyframe 场景下用于表达该帧持续时长，可传小数秒。' },
@@ -2133,8 +2186,8 @@ export async function modelCreateSpec(kwargs = {}) {
     schemaVersion: 1,
     modelGroupCode,
     taskKind: context.taskKind,
-    createCommand: context.taskKind === 'image' ? 'image create' : 'video create',
-    feeCommand: context.taskKind === 'image' ? 'image fee' : 'video fee',
+    createCommand: context.taskKind === 'image' ? 'create image' : 'create video',
+    feeCommand: context.taskKind === 'image' ? 'create image-fee' : 'create video-fee',
     statusCommandTaskType: context.taskKind === 'image' ? 'IMAGE_CREATE' : 'VIDEO_GROUP',
     optionsCommand: `model options --model-group-code ${modelGroupCode}`,
     model: context.model,
@@ -2156,7 +2209,35 @@ async function readJsonMaybeFile(value, fallback) {
   return JSON.parse(fileText);
 }
 
-async function collectFileSpecs(kwargs = {}, defaultSceneType = TASK_UPLOAD_SCENE.DEFAULT) {
+const AUDIO_VIDEO_EXTENSIONS = new Set([
+  '.aac',
+  '.aiff',
+  '.avi',
+  '.flac',
+  '.m4a',
+  '.m4v',
+  '.mkv',
+  '.mov',
+  '.mp3',
+  '.mp4',
+  '.mpeg',
+  '.mpg',
+  '.oga',
+  '.ogg',
+  '.ogv',
+  '.wav',
+  '.webm',
+]);
+
+function defaultUploadSceneForFile(filePath, mimeType = '') {
+  const normalizedMime = String(mimeType || '').toLowerCase();
+  if (normalizedMime.startsWith('audio/') || normalizedMime.startsWith('video/')) return TASK_UPLOAD_SCENE.VIDEO_CREATE;
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  if (AUDIO_VIDEO_EXTENSIONS.has(ext)) return TASK_UPLOAD_SCENE.VIDEO_CREATE;
+  return TASK_UPLOAD_SCENE.DEFAULT;
+}
+
+async function collectFileSpecs(kwargs = {}, defaultSceneType = null) {
   const specs = [];
   for (const file of parseListArg(kwargs.file)) specs.push({ file });
   for (const file of parseListArg(kwargs.files)) specs.push({ file });
@@ -2169,11 +2250,14 @@ async function collectFileSpecs(kwargs = {}, defaultSceneType = TASK_UPLOAD_SCEN
     }
   }
   return specs
-    .map((item) => ({
-      file: trimToNull(item.file ?? item.path ?? item.filePath),
-      sceneType: trimToNull(item.sceneType ?? kwargs.sceneType) ?? defaultSceneType,
-      projectNo: trimToNull(item.projectNo ?? kwargs.projectNo) ?? '',
-    }))
+    .map((item) => {
+      const file = trimToNull(item.file ?? item.path ?? item.filePath);
+      return {
+        file,
+        sceneType: trimToNull(item.sceneType ?? kwargs.sceneType) ?? defaultSceneType ?? defaultUploadSceneForFile(file),
+        projectNo: trimToNull(item.projectNo ?? kwargs.projectNo) ?? '',
+      };
+    })
     .filter((item) => item.file);
 }
 
@@ -2182,7 +2266,7 @@ function dryRunBackendPath(filePath, sceneType) {
 }
 
 export async function uploadFilesCommand(kwargs = {}) {
-  const specs = await collectFileSpecs(kwargs, trimToNull(kwargs.sceneType) ?? TASK_UPLOAD_SCENE.DEFAULT);
+  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 = [];
@@ -2212,7 +2296,7 @@ export async function uploadLocalFile(filePath, options = {}) {
     throw argumentError(`文件不存在：${filePath}`);
   }
   const buffer = await fs.readFile(inspected.filePath);
-  const sceneType = options.sceneType ?? TASK_UPLOAD_SCENE.DEFAULT;
+  const sceneType = options.sceneType ?? defaultUploadSceneForFile(inspected.filePath, inspected.mimeType);
   const groupId = crypto.randomUUID().replaceAll('-', '');
   const secret = await awbApi.fetchUploadSecret({
     sceneType,
@@ -2259,6 +2343,113 @@ export async function uploadLocalFile(filePath, options = {}) {
   });
 }
 
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value || '').trim());
+}
+
+function isUploadedMaterialReference(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;
+  }
+}
+
+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 === '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;
+}
+
+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 });
+    if (!response.ok) {
+      throw new LingjingAwbCliError(`下载远程音频失败：${response.status} ${response.statusText}`, {
+        type: 'http_error',
+        exitCode: 30,
+        details: { url: remoteUrl, status: response.status },
+      });
+    }
+    const contentType = response.headers.get('content-type') || '';
+    let fileName = remoteFileNameFromUrl(remoteUrl, options.fallbackName || 'voice-audio');
+    if (!path.extname(fileName)) fileName = `${fileName}${extensionFromContentType(contentType) || '.mp3'}`;
+    if (!isSupportedRemoteVoiceDownload(contentType, fileName)) {
+      throw argumentError(
+        `远程音频类型不支持：${contentType || path.extname(fileName) || 'unknown'}`,
+        'create subject-voice 只支持 mp3、wav、m4a、aac、ogg 音频或 mp4 视频来源。',
+      );
+    }
+    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-voice-'));
+    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，请改用本地 --file 或已上传 material 路径。` : '',
+      details: { url: remoteUrl, causeCode: error?.cause?.code },
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 function resolveCustomBizId(explicit) {
   return trimToNull(explicit);
 }
@@ -2330,7 +2521,10 @@ function normalizeResourceSource(source, type, index, options = {}) {
     ? explicitKind.toLowerCase()
     : (rawValue?.startsWith('asset:') || type === 'subject' ? 'asset_id' : 'url');
   if (!['url', 'asset_id'].includes(kind)) {
-    throw argumentError(`resource[${index}] source.kind 不支持：${kind}`, '支持 url、asset_id。');
+    throw argumentError(
+      `resource[${index}] source.kind 不支持：${explicitKind}`,
+      '只支持 url、asset_id 两个值。本地文件 / http(s) URL / material backendPath 都统一传 kind=url（CLI 按 value 自动识别）；平台资产或主体对象传 kind=asset_id。',
+    );
   }
   const value = kind === 'asset_id' ? assetValue : rawValue;
   if (!value) {
@@ -2765,7 +2959,7 @@ export async function imageFee(kwargs = {}) {
     const built = await buildImageRequest(kwargs, { dryRun: true, includeCustomBizId: false });
     return compactRecord({
       dryRun: true,
-      action: 'image fee',
+      action: 'create image-fee',
       request: built.request,
       ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
     });
@@ -2820,13 +3014,13 @@ export async function imageCreate(kwargs = {}) {
     const built = await buildImageRequest(kwargs, { dryRun: true });
     return compactRecord({
       dryRun: true,
-      action: 'image create',
+      action: 'create image',
       request: built.request,
       ...(built.localFiles.length ? { localFiles: built.localFiles } : {}),
       ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
     });
   }
-  ensureConfirmed(kwargs, '正式生图会消耗积分，需要确认', { action: 'image create' });
+  ensureConfirmed(kwargs, '正式生图会消耗积分，需要确认', { action: 'create image' });
   const built = await buildImageRequest(kwargs);
   const feePayload = await awbApi.fetchImageFee(built.request).catch(() => null);
   const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
@@ -2919,7 +3113,7 @@ export async function videoFee(kwargs = {}) {
     const built = await buildVideoRequest(kwargs, { dryRun: true, includeCustomBizId: false });
     return compactRecord({
       dryRun: true,
-      action: 'video fee',
+      action: 'create video-fee',
       request: built.request,
       ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
     });
@@ -2937,13 +3131,13 @@ export async function videoCreate(kwargs = {}) {
     const built = await buildVideoRequest(kwargs, { dryRun: true });
     return compactRecord({
       dryRun: true,
-      action: 'video create',
+      action: 'create video',
       request: built.request,
       ...(built.localFiles.length ? { localFiles: built.localFiles } : {}),
       ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
     });
   }
-  ensureConfirmed(kwargs, '正式生视频会消耗积分，需要确认', { action: 'video create' });
+  ensureConfirmed(kwargs, '正式生视频会消耗积分，需要确认', { action: 'create video' });
   const built = await buildVideoRequest(kwargs);
   const feePayload = await awbApi.fetchVideoFee(built.request).catch(() => null);
   const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
@@ -3079,7 +3273,7 @@ export async function imageCreateBatch(kwargs = {}) {
     }
     return { dryRun: true, count: items.length, results };
   }
-  ensureConfirmed(kwargs, '批量生图会多次消耗积分，需要确认', { action: 'image create-batch', count: items.length });
+  ensureConfirmed(kwargs, '批量生图会多次消耗积分，需要确认', { action: 'create image-batch', count: items.length });
   const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
     inputIndex: index,
     status: 'success',
@@ -3098,7 +3292,7 @@ export async function videoCreateBatch(kwargs = {}) {
     }
     return { dryRun: true, count: items.length, results };
   }
-  ensureConfirmed(kwargs, '批量生视频会多次消耗积分，需要确认', { action: 'video create-batch', count: items.length });
+  ensureConfirmed(kwargs, '批量生视频会多次消耗积分，需要确认', { action: 'create video-batch', count: items.length });
   const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
     inputIndex: index,
     status: 'success',
@@ -3311,6 +3505,7 @@ function normalizeAssetGroup(item = {}) {
     groupId: item?.id ?? item?.groupId ?? item?.assetGroupsId ?? null,
     name: item?.name ?? item?.groupName ?? null,
     description: item?.description ?? null,
+    platform: item?.platform ?? null,
     projectName: item?.projectName ?? null,
   };
 }
@@ -3384,12 +3579,64 @@ function normalizeSubjectTagIds(tagList) {
   return uniqueNonEmpty(tagList.map((item) => (typeof item === 'string' ? item : item?.tagId ?? item?.id ?? item?.tagCode)));
 }
 
+function normalizeSubjectTaskMeta(item = {}) {
+  const rawTaskStatus = item?.taskStatus ?? item?.task_status ?? null;
+  const taskStatus = rawTaskStatus ? taskStatusText(rawTaskStatus) : null;
+  const errorMessage = trimToNull(
+    item?.errorMessage
+    ?? item?.error_msg
+    ?? item?.errorMsg
+    ?? item?.resultMessage
+    ?? item?.result_msg
+    ?? item?.resultMsg
+    ?? item?.message
+    ?? item?.msg,
+  );
+  return {
+    taskStatus,
+    errorMessage,
+    isTerminal: taskStatus ? isTerminalTaskStatus(taskStatus) : false,
+    isSuccess: taskStatus ? isSuccessTaskStatus(taskStatus) : false,
+  };
+}
+
+function subjectResourceStatus(externalId, taskMeta) {
+  if (externalId) return 'ready';
+  if (taskMeta?.taskStatus && taskMeta.isTerminal) {
+    return taskMeta.isSuccess ? 'missing_external_id' : 'failed';
+  }
+  return 'pending_external_id';
+}
+
+function subjectFailureDetails(record, kind = 'subject') {
+  if (!record) return null;
+  const taskStatus = taskStatusText(record.taskStatus);
+  if (!taskStatus || !isTerminalTaskStatus(taskStatus)) return null;
+  const fallback = kind === 'voice'
+    ? '主体音色创建失败'
+    : '主体创建失败';
+  if (!isSuccessTaskStatus(taskStatus)) {
+    return {
+      taskStatus,
+      errorMessage: record.errorMessage || fallback,
+    };
+  }
+  if (!record.externalId) {
+    return {
+      taskStatus,
+      errorMessage: record.errorMessage || `${fallback}：任务已终态但未返回externalId`,
+    };
+  }
+  return null;
+}
+
 function normalizeSubjectRecord(item = {}) {
   const referList = Array.isArray(item?.elementReferList) ? item.elementReferList : [];
   const videoList = Array.isArray(item?.elementVideoList) ? item.elementVideoList : [];
   const elementId = item?.id ?? item?.subjectId ?? item?.elementId ?? null;
   const externalId = item?.externalId ?? item?.external_id ?? null;
   const name = item?.elementName ?? item?.name ?? item?.subjectName ?? null;
+  const taskMeta = normalizeSubjectTaskMeta(item);
   return {
     subjectId: externalId ?? elementId,
     elementId,
@@ -3412,6 +3659,33 @@ function normalizeSubjectRecord(item = {}) {
     tagIds: normalizeSubjectTagIds(item?.tagList),
     ...(trimToNull(item?.elementVoiceId) ? { voiceId: trimToNull(item.elementVoiceId) } : {}),
     ...(externalId && name ? { nextRefSubject: `${name}=${externalId}` } : {}),
+    taskStatus: taskMeta.taskStatus,
+    errorMessage: taskMeta.errorMessage,
+    isTerminal: externalId ? true : taskMeta.isTerminal,
+    status: subjectResourceStatus(externalId, taskMeta),
+    createdAt: item?.gmtCreate ?? item?.createdAt ?? null,
+  };
+}
+
+function normalizeSubjectVoiceRecord(item = {}) {
+  const voiceRecordId = item?.voiceRecordId ?? item?.id ?? item?.reqTaskId ?? item?.voiceTaskId ?? null;
+  const reqTaskId = item?.reqTaskId ?? voiceRecordId;
+  const externalId = item?.externalId ?? item?.external_id ?? item?.voice_id ?? item?.voiceId ?? null;
+  const name = item?.voiceName ?? item?.name ?? null;
+  const taskMeta = normalizeSubjectTaskMeta(item);
+  return {
+    voiceRecordId,
+    reqTaskId,
+    voiceId: externalId,
+    externalId,
+    name,
+    voiceUrl: item?.voiceUrl ?? item?.voice_url ?? item?.audioUrl ?? item?.audio_url ?? null,
+    videoId: item?.videoId ?? item?.video_id ?? null,
+    status: subjectResourceStatus(externalId, taskMeta),
+    taskStatus: taskMeta.taskStatus,
+    errorMessage: taskMeta.errorMessage,
+    isTerminal: externalId ? true : taskMeta.isTerminal,
+    ...(externalId ? { nextVoiceArg: `--voice-id ${externalId}` } : {}),
     createdAt: item?.gmtCreate ?? item?.createdAt ?? null,
   };
 }
@@ -3439,45 +3713,55 @@ export async function assetMatchActor(kwargs = {}) {
 }
 
 export async function assetGroupList(kwargs = {}) {
+  const platform = requireAssetPlatform(kwargs.platform);
   const payload = await awbApi.listAssetGroups({
     name: kwargs.name ?? '',
+    platform,
     pageNumber: toInt(kwargs.pageNumber, 1),
     pageSize: toInt(kwargs.pageSize, 20),
     ...(parseListArg(kwargs.groupIds).length ? { groupIds: parseListArg(kwargs.groupIds) } : {}),
   });
-  return { groups: extractAssetGroupRows(payload), raw: toBool(kwargs.includeRaw) ? payload : undefined };
+  return { platform, groups: extractAssetGroupRows(payload), raw: toBool(kwargs.includeRaw) ? payload : undefined };
 }
 
 export async function assetGroupGet(kwargs = {}) {
   const groupId = requireValue(kwargs, 'groupId', 'group-id');
-  const payload = await awbApi.getAssetGroup(groupId);
-  return payload && typeof payload === 'object' && !Array.isArray(payload)
-    ? normalizeAssetGroup(payload)
-    : extractAssetGroupRows(payload)[0] ?? { groupId };
+  const platform = requireAssetPlatform(kwargs.platform);
+  const payload = await awbApi.getAssetGroup(groupId, { platform });
+  if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+    const group = normalizeAssetGroup(payload);
+    return { ...group, platform: group.platform ?? platform };
+  }
+  return extractAssetGroupRows(payload)[0] ?? { groupId, platform };
 }
 
 export async function assetGroupCreate(kwargs = {}) {
   const name = requireValue(kwargs, 'name');
+  const platform = requireAssetPlatform(kwargs.platform);
   const body = {
     name,
     description: kwargs.description ?? '',
+    platform,
     projectName: kwargs.projectName ?? 'default',
   };
-  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'asset group-create', request: body };
-  ensureConfirmed(kwargs, '创建素材组是云端写入动作，需要确认', { action: 'asset group-create', body });
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'create asset-group', request: body };
+  ensureConfirmed(kwargs, '创建素材组是云端写入动作，需要确认', { action: 'create asset-group', body });
   const payload = await awbApi.createAssetGroup(body);
-  return { created: true, groupId: payload?.id ?? payload?.groupId ?? payload ?? null, name, projectName: body.projectName };
+  return { created: true, groupId: payload?.id ?? payload?.groupId ?? payload ?? null, name, platform, projectName: body.projectName };
 }
 
 export async function assetGroupUpdate(kwargs = {}) {
   const groupId = requireValue(kwargs, 'groupId', 'group-id');
-  const body = {};
+  const platform = requireAssetPlatform(kwargs.platform);
+  const body = { platform };
   if (kwargs.name != null) body.name = kwargs.name;
   if (kwargs.description != null) body.description = kwargs.description;
   if (kwargs.projectName != null) body.projectName = kwargs.projectName;
-  if (!Object.keys(body).length) throw argumentError('缺少素材组更新字段', '至少传 --name、--description 或 --project-name。');
-  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'asset group-update', groupId, request: body };
-  ensureConfirmed(kwargs, '更新素材组是云端写入动作，需要确认', { action: 'asset group-update', groupId, body });
+  if (!['name', 'description', 'projectName'].some((key) => Object.prototype.hasOwnProperty.call(body, key))) {
+    throw argumentError('缺少素材组更新字段', '至少传 --name、--description 或 --project-name；--platform 只用于定位平台资产组。');
+  }
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'create asset-group-update', groupId, request: body };
+  ensureConfirmed(kwargs, '更新素材组是云端写入动作，需要确认', { action: 'create asset-group-update', groupId, body });
   await awbApi.updateAssetGroup(groupId, body);
   return { updated: true, groupId, ...body };
 }
@@ -3491,29 +3775,30 @@ function extractAssetId(payload) {
 export async function assetRegister(kwargs = {}) {
   const groupId = requireValue(kwargs, 'groupId', 'group-id');
   const name = requireValue(kwargs, 'name');
+  const platform = requireAssetPlatform(kwargs.platform);
   const localFile = trimToNull(kwargs.file);
   const assetPath = trimToNull(kwargs.backendPath) ?? normalizeCosAssetPath(kwargs.url);
   if (!localFile && !assetPath) throw argumentError('缺少素材路径', '传 --file、--backend-path 或 --url。');
   if (toBool(kwargs.dryRun)) {
     return {
       dryRun: true,
-      action: 'asset register',
+      action: 'create asset',
       request: {
         assetGroupsId: groupId,
-        url: localFile ? normalizeCosAssetPath(dryRunBackendPath(localFile, TASK_UPLOAD_SCENE.SUBJECT)) : assetPath,
+        url: localFile ? normalizeCosAssetPath(dryRunBackendPath(localFile, TASK_UPLOAD_SCENE.ASSET_REVIEW)) : assetPath,
         name,
-        ...(kwargs.platform ? { platform: kwargs.platform } : {}),
+        platform,
       },
       localFile: localFile ? await inspectLocalFile(localFile) : null,
     };
   }
-  ensureConfirmed(kwargs, '注册素材是云端写入动作，需要确认', { action: 'asset register', groupId, name });
-  const uploaded = localFile ? await uploadLocalFile(localFile, { sceneType: TASK_UPLOAD_SCENE.SUBJECT }) : 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,
-    ...(kwargs.platform ? { platform: kwargs.platform } : {}),
+    platform,
   };
   const payload = await awbApi.registerAsset(body);
   return {
@@ -3521,6 +3806,7 @@ export async function assetRegister(kwargs = {}) {
     assetId: extractAssetId(payload),
     groupId,
     name,
+    platform,
     assetPath: body.url,
     ...(uploaded ? { upload: uploaded } : {}),
   };
@@ -3542,6 +3828,194 @@ export async function subjectList(kwargs = {}) {
   };
 }
 
+export async function subjectVoiceList(kwargs = {}) {
+  const keyword = trimToNull(kwargs.keyword ?? kwargs.name);
+  const payload = keyword
+    ? await awbApi.listVoicesByName(keyword)
+    : await awbApi.listVoices();
+  const voices = paginateRows(
+    normalizeRows(payload).map((item) => normalizeSubjectVoiceRecord(item)),
+    kwargs.pageNumber,
+    kwargs.pageSize,
+  );
+  return {
+    voices,
+    ...(toBool(kwargs.includeRaw) ? { raw: payload } : {}),
+  };
+}
+
+function subjectVoiceSource(kwargs = {}) {
+  const file = trimToNull(kwargs.file);
+  const voiceUrlArg = trimToNull(kwargs.voiceUrl);
+  const audioUrlArg = trimToNull(kwargs.audioUrl);
+  if (voiceUrlArg && audioUrlArg) {
+    throw argumentError('音色来源只能选择一种', '--voice-url 和 --audio-url 是同一含义的别名，只能传一个。');
+  }
+  const voiceUrl = voiceUrlArg ?? audioUrlArg ?? trimToNull(kwargs.url);
+  const videoId = trimToNull(kwargs.videoId);
+  const sourceCount = [file, voiceUrl, videoId].filter(Boolean).length;
+  if (sourceCount === 0) {
+    throw argumentError('缺少音色来源', '传 --file <audio>、--voice-url/--audio-url <material path> 或 --video-id <id>。');
+  }
+  if (sourceCount > 1) {
+    throw argumentError('音色来源只能选择一种', '--file、--voice-url/--audio-url、--video-id 三者只能传一个。');
+  }
+  const shouldUploadRemoteUrl = Boolean(voiceUrl && isHttpUrl(voiceUrl) && !isUploadedMaterialReference(voiceUrl));
+  return { file, voiceUrl, videoId, shouldUploadRemoteUrl };
+}
+
+function buildSubjectVoiceCreateBody(kwargs, source, uploaded = null) {
+  const name = requireValue(kwargs, 'name');
+  const voiceUrl = uploaded
+    ? normalizeCosAssetPath(uploaded.backendPath)
+    : normalizeCosAssetPath(source.voiceUrl);
+  return compactRecord({
+    reqTaskId: trimToNull(kwargs.reqTaskId),
+    voiceName: name,
+    voiceUrl,
+    videoId: source.videoId,
+  });
+}
+
+function extractCreatedVoiceRecordId(payload) {
+  if (typeof payload === 'string') return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  return payload.id
+    ?? payload.voiceRecordId
+    ?? payload.reqTaskId
+    ?? payload.voiceTaskId
+    ?? payload.data?.id
+    ?? payload.data?.voiceRecordId
+    ?? payload.data?.reqTaskId
+    ?? null;
+}
+
+async function fetchSubjectVoiceByReqTaskId(reqTaskId, options = {}) {
+  if (!reqTaskId) return null;
+  const payload = await awbApi.getVoiceByReqTaskId(reqTaskId).catch((error) => {
+    if (options.optional) return null;
+    throw error;
+  });
+  return payload && typeof payload === 'object' ? normalizeSubjectVoiceRecord(payload) : null;
+}
+
+async function waitForSubjectVoiceExternalId(reqTaskId, options = {}) {
+  const waitSeconds = Math.max(0, toInt(options.waitSeconds, 0));
+  const pollIntervalMs = Math.max(500, toInt(options.pollIntervalMs, 2000));
+  const deadline = Date.now() + waitSeconds * 1000;
+  let latest = await fetchSubjectVoiceByReqTaskId(reqTaskId);
+  while (waitSeconds > 0 && !latest?.externalId && !subjectFailureDetails(latest, 'voice') && Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+    latest = await fetchSubjectVoiceByReqTaskId(reqTaskId);
+  }
+  return latest;
+}
+
+function subjectVoiceWaitPayload(voiceRecordId, voice) {
+  const externalId = voice?.externalId ?? null;
+  return {
+    voiceRecordId,
+    reqTaskId: voice?.reqTaskId ?? voiceRecordId,
+    voiceId: externalId,
+    externalId,
+    nextVoiceArg: externalId ? `--voice-id ${externalId}` : null,
+    status: voice?.status ?? (externalId ? 'ready' : 'pending_external_id'),
+    taskStatus: voice?.taskStatus ?? null,
+    errorMessage: voice?.errorMessage ?? null,
+    isTerminal: externalId ? true : Boolean(voice?.isTerminal),
+    voice,
+  };
+}
+
+export async function subjectVoiceCreate(kwargs = {}) {
+  const name = requireValue(kwargs, 'name');
+  const source = subjectVoiceSource(kwargs);
+  if (toBool(kwargs.dryRun)) {
+    const localFiles = source.file ? [await inspectLocalFile(source.file)] : [];
+    let dryRunSource = source;
+    if (source.file) {
+      dryRunSource = { ...source, voiceUrl: dryRunBackendPath(source.file, TASK_UPLOAD_SCENE.SUBJECT) };
+    } else if (source.shouldUploadRemoteUrl) {
+      dryRunSource = {
+        ...source,
+        voiceUrl: dryRunBackendPath(remoteFileNameFromUrl(source.voiceUrl), TASK_UPLOAD_SCENE.SUBJECT),
+      };
+    }
+    return {
+      dryRun: true,
+      action: 'create subject-voice',
+      name,
+      request: buildSubjectVoiceCreateBody(kwargs, dryRunSource),
+      localFiles,
+      remoteUpload: source.shouldUploadRemoteUrl || undefined,
+      remoteUrl: source.shouldUploadRemoteUrl ? source.voiceUrl : undefined,
+      nextVoiceArg: '--voice-id <externalId>',
+    };
+  }
+  ensureConfirmed(kwargs, '创建主体音色是云端写入动作，需要确认', { action: 'create subject-voice', name });
+  let uploaded = null;
+  let tempDownload = null;
+  try {
+    if (source.file) {
+      uploaded = await uploadLocalFile(source.file, { sceneType: TASK_UPLOAD_SCENE.SUBJECT });
+    } else if (source.shouldUploadRemoteUrl) {
+      tempDownload = await downloadRemoteFileToTemp(source.voiceUrl, { fallbackName: safeFileName(name) || 'voice-audio' });
+      uploaded = await uploadLocalFile(tempDownload.filePath, { sceneType: TASK_UPLOAD_SCENE.SUBJECT });
+    }
+  } finally {
+    if (tempDownload?.dir) await fs.rm(tempDownload.dir, { recursive: true, force: true }).catch(() => {});
+  }
+  const body = buildSubjectVoiceCreateBody(kwargs, source, uploaded);
+  const payload = await awbApi.createVoice(body);
+  const voiceRecordId = extractCreatedVoiceRecordId(payload);
+  if (!voiceRecordId) throw new LingjingAwbCliError('音色创建完成但未拿到 voiceRecordId', { type: 'api_error', exitCode: 1, details: payload });
+  const voice = await fetchSubjectVoiceByReqTaskId(voiceRecordId, { optional: true });
+  const waitPayload = subjectVoiceWaitPayload(voiceRecordId, voice);
+  return {
+    created: true,
+    name,
+    voiceRecordId,
+    reqTaskId: waitPayload.reqTaskId,
+    voiceId: waitPayload.voiceId,
+    externalId: waitPayload.externalId,
+    nextVoiceArg: waitPayload.nextVoiceArg,
+    status: waitPayload.status,
+    request: body,
+    ...(uploaded ? { upload: uploaded } : {}),
+    voice,
+  };
+}
+
+function requireSubjectVoiceRecordId(kwargs = {}) {
+  const value = trimToNull(kwargs.voiceRecordId ?? kwargs.reqTaskId);
+  if (!value) throw argumentError('缺少参数：--voice-record-id', '传 create subject-voice 返回的 voiceRecordId；也可用 --req-task-id。');
+  return value;
+}
+
+export async function subjectVoiceWait(kwargs = {}) {
+  const voiceRecordId = requireSubjectVoiceRecordId(kwargs);
+  const voice = await waitForSubjectVoiceExternalId(voiceRecordId, kwargs);
+  const payload = subjectVoiceWaitPayload(voiceRecordId, voice);
+  const failure = subjectFailureDetails(voice, 'voice');
+  if (failure) {
+    throw new LingjingAwbCliError(failure.errorMessage, {
+      type: 'subject_voice_failed',
+      exitCode: 1,
+      hint: '主体音色创建任务已失败，请根据 error.details.errorMessage 调整音频/视频来源后重新创建。',
+      details: payload,
+    });
+  }
+  if (!payload.externalId) {
+    throw new LingjingAwbCliError('主体音色 externalId 尚未回填', {
+      type: 'subject_voice_still_pending',
+      exitCode: 20,
+      hint: '稍后重试 create subject-voice-wait，或用 create subject-voice-list --name 查询。',
+      details: payload,
+    });
+  }
+  return payload;
+}
+
 const SUBJECT_SLOT_ALIASES = {
   primary: 'primary',
   'three-view': 'three-view',
@@ -3619,15 +4093,37 @@ function tagListFromArg(value) {
     .filter((item) => item.tagId);
 }
 
-function buildSubjectCreateBody(kwargs, specs, assets) {
+const SUBJECT_MODEL_CODE_HINT = '传 --model-code tx|vidu；KeLing / 可灵主体明确传 tx，Vidu 主体明确传 vidu。';
+
+function resolveSubjectCreateModelCode(kwargs = {}) {
+  const explicitModelCode = trimToNull(kwargs.modelCode ?? kwargs.model_code);
+  if (explicitModelCode === 'tx' || explicitModelCode === 'vidu') {
+    return { modelCode: explicitModelCode };
+  }
+  if (explicitModelCode) {
+    throw argumentError(
+      `主体 modelCode 不支持：${explicitModelCode}`,
+      SUBJECT_MODEL_CODE_HINT,
+    );
+  }
+
+  throw argumentError(
+    '缺少主体 modelCode',
+    SUBJECT_MODEL_CODE_HINT,
+  );
+}
+
+function buildSubjectCreateBody(kwargs, specs, assets, modelCodeResolution = resolveSubjectCreateModelCode(kwargs)) {
   const name = requireValue(kwargs, 'name');
+  const description = trimToNull(kwargs.description ?? kwargs.elementDescription) ?? name;
   const primary = assets.find((item) => item.isPrimary);
   const referAssets = assets.filter((item) => item.assetPath);
+  const { modelCode } = modelCodeResolution;
   return compactRecord({
     reqTaskId: trimToNull(kwargs.reqTaskId),
-    modelCode: trimToNull(kwargs.modelCode),
+    modelCode,
     elementName: name,
-    elementDescription: trimToNull(kwargs.description ?? kwargs.elementDescription),
+    elementDescription: description,
     elementFrontalImage: primary?.assetPath ?? null,
     elementReferList: referAssets.map((item) => ({
       imageUrl: item.assetPath,
@@ -3645,9 +4141,12 @@ function extractCreatedElementId(payload) {
   return payload.id ?? payload.elementId ?? payload.subjectId ?? payload.reqTaskId ?? payload.data?.id ?? payload.data?.elementId ?? null;
 }
 
-async function fetchSubjectByReqTaskId(reqTaskId) {
+async function fetchSubjectByReqTaskId(reqTaskId, options = {}) {
   if (!reqTaskId) return null;
-  const payload = await awbApi.getElementByReqTaskId(reqTaskId).catch(() => null);
+  const payload = await awbApi.getElementByReqTaskId(reqTaskId).catch((error) => {
+    if (options.optional) return null;
+    throw error;
+  });
   return payload && typeof payload === 'object' ? normalizeSubjectRecord(payload) : null;
 }
 
@@ -3656,7 +4155,7 @@ async function waitForSubjectExternalId(reqTaskId, options = {}) {
   const pollIntervalMs = Math.max(500, toInt(options.pollIntervalMs, 2000));
   const deadline = Date.now() + waitSeconds * 1000;
   let latest = await fetchSubjectByReqTaskId(reqTaskId);
-  while (waitSeconds > 0 && !latest?.externalId && Date.now() < deadline) {
+  while (waitSeconds > 0 && !latest?.externalId && !subjectFailureDetails(latest, 'subject') && Date.now() < deadline) {
     await sleep(pollIntervalMs);
     latest = await fetchSubjectByReqTaskId(reqTaskId);
   }
@@ -3670,7 +4169,10 @@ function subjectWaitPayload(elementId, subject) {
     subjectId: externalId ?? elementId,
     externalId,
     nextRefSubject: externalId && subject?.name ? `${subject.name}=${externalId}` : null,
-    status: externalId ? 'ready' : 'pending_external_id',
+    status: subject?.status ?? (externalId ? 'ready' : 'pending_external_id'),
+    taskStatus: subject?.taskStatus ?? null,
+    errorMessage: subject?.errorMessage ?? null,
+    isTerminal: externalId ? true : Boolean(subject?.isTerminal),
     subject,
   };
 }
@@ -3681,6 +4183,7 @@ export async function subjectPublish(kwargs = {}) {
   if (!specs.some((item) => item.isPrimary)) {
     throw argumentError('缺少主体主参考图', '传 --resource primary:<path|url>（或 --resource three-view:<path|url> 自动升为主图）。');
   }
+  const modelCodeResolution = resolveSubjectCreateModelCode(kwargs);
   if (toBool(kwargs.dryRun)) {
     const assets = specs.map((item) => ({
       label: item.label,
@@ -3692,15 +4195,15 @@ export async function subjectPublish(kwargs = {}) {
     }));
     return {
       dryRun: true,
-      action: 'subject publish',
+      action: 'create subject',
       name,
-      request: buildSubjectCreateBody(kwargs, specs, assets),
+      request: buildSubjectCreateBody(kwargs, specs, assets, modelCodeResolution),
       assets,
       localFiles: await inspectLocalFiles(specs.map((item) => item.file).filter(Boolean)),
       nextRefSubject: `${name}=<externalId>`,
     };
   }
-  ensureConfirmed(kwargs, '创建平台主体 element 是云端写入动作，需要确认', { action: 'subject publish', name });
+  ensureConfirmed(kwargs, '创建平台主体 element 是云端写入动作，需要确认', { action: 'create subject', name });
   const assets = [];
   for (const spec of specs) {
     const uploaded = spec.file ? await uploadLocalFile(spec.file, { sceneType: TASK_UPLOAD_SCENE.SUBJECT }) : null;
@@ -3714,11 +4217,11 @@ export async function subjectPublish(kwargs = {}) {
       ...(uploaded ? { upload: uploaded } : {}),
     });
   }
-  const body = buildSubjectCreateBody(kwargs, specs, assets);
+  const body = buildSubjectCreateBody(kwargs, specs, assets, modelCodeResolution);
   const payload = await awbApi.createElement(body);
   const elementId = extractCreatedElementId(payload);
   if (!elementId) throw new LingjingAwbCliError('主体创建完成但未拿到 elementId', { type: 'api_error', exitCode: 1, details: payload });
-  const subject = await fetchSubjectByReqTaskId(elementId);
+  const subject = await fetchSubjectByReqTaskId(elementId, { optional: true });
   const waitPayload = subjectWaitPayload(elementId, subject);
   return {
     created: true,
@@ -3738,11 +4241,20 @@ export async function subjectWait(kwargs = {}) {
   const elementId = requireValue(kwargs, 'elementId', 'element-id');
   const subject = await waitForSubjectExternalId(elementId, kwargs);
   const payload = subjectWaitPayload(elementId, subject);
+  const failure = subjectFailureDetails(subject, 'subject');
+  if (failure) {
+    throw new LingjingAwbCliError(failure.errorMessage, {
+      type: 'subject_failed',
+      exitCode: 1,
+      hint: '主体创建任务已失败，请根据 error.details.errorMessage 调整参考资源/模型后重新创建。',
+      details: payload,
+    });
+  }
   if (!payload.externalId) {
     throw new LingjingAwbCliError('主体 externalId 尚未回填', {
       type: 'subject_still_pending',
       exitCode: 20,
-      hint: '稍后重试 subject wait，或用 subject list --name 查询。',
+      hint: '稍后重试 create subject-wait，或用 create subject-list --name 查询。',
       details: payload,
     });
   }
@@ -3758,7 +4270,7 @@ export async function subjectPublishBatch(kwargs = {}) {
     }
     return { dryRun: true, count: items.length, results };
   }
-  ensureConfirmed(kwargs, '批量发布主体资产是云端写入动作，需要确认', { action: 'subject publish-batch', count: items.length });
+  ensureConfirmed(kwargs, '批量发布主体资产是云端写入动作，需要确认', { action: 'create subject-batch', count: items.length });
   const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
     inputIndex: index,
     status: 'success',
@@ -3768,44 +4280,73 @@ export async function subjectPublishBatch(kwargs = {}) {
 }
 
 export async function subtitleRemove(kwargs = {}) {
-  const videoUrl = requireValue(kwargs, 'videoUrl', 'video-url');
+  const built = await buildSubtitleRemovalRequest(kwargs, { dryRun: toBool(kwargs.dryRun) });
   if (toBool(kwargs.dryRun)) {
-    return { dryRun: true, action: 'video subtitle-remove', request: { input_type: 'url', video_url: videoUrl } };
-  }
-  ensureConfirmed(kwargs, '提交视频去字幕任务是云端写入动作，需要确认', { action: 'video subtitle-remove', videoUrl });
-  const payload = await awbApi.createSubtitleRemoveTask({
-    input_type: 'url',
-    video_url: videoUrl,
-    ...(kwargs.name ? { name: kwargs.name } : {}),
-    ...(kwargs.taskId ? { task_id: kwargs.taskId } : {}),
-    ...(kwargs.callbackUrl ? { callback_url: kwargs.callbackUrl } : {}),
+    return {
+      dryRun: true,
+      action: 'create video-subtitle-removal',
+      request: built.request,
+      materialEndpoint: '/api/material/creation/videoSubtitleRemoval',
+      taskType: 'VIDEO_SUBTITLE_REMOVAL',
+    };
+  }
+  ensureConfirmed(kwargs, '提交视频去字幕任务会通过 material 创建任务并消耗积分，需要确认', {
+    action: 'create video-subtitle-removal',
+    sourceTaskId: built.sourceTaskId,
   });
-  return {
+  const feePayload = await awbApi.fetchVideoSubtitleRemovalFee(built.request).catch(() => null);
+  const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
+  const payload = await awbApi.createVideoSubtitleRemovalTask(built.request);
+  const result = normalizeCreatedTask(payload, {
+    ...estimate,
     submitted: true,
-    remoteTaskId: payload?.remote_task_id ?? payload?.remoteTaskId ?? null,
-    publicId: payload?.public_id ?? payload?.publicId ?? payload?.id ?? null,
+    taskType: 'VIDEO_SUBTITLE_REMOVAL',
+    sourceTaskId: built.sourceTaskId,
+    projectGroupNo: built.projectGroupNo,
+  });
+  await appendTaskRecord(kwargs, {
+    taskId: result.taskId,
+    taskType: 'VIDEO_SUBTITLE_REMOVAL',
+    projectGroupNo: built.projectGroupNo,
+    promptSummary: `去字幕 sourceTaskId=${built.sourceTaskId}`,
+  });
+  return {
+    ...result,
+    nextCommand: result.taskId
+      ? `lj-awb task video-subtitle-status --task-id ${result.taskId}${built.projectGroupNo ? ` --project-group-no ${built.projectGroupNo}` : ''} -f json`
+      : null,
+  };
+}
+
+async function buildSubtitleRemovalRequest(kwargs = {}, options = {}) {
+  const sourceTaskId = trimToNull(kwargs.sourceTaskId);
+  if (!sourceTaskId) {
+    throw argumentError('缺少来源视频任务 ID', '传 --source-task-id <taskId>；必须是 material 中已成功的视频任务。');
+  }
+  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 {
+    sourceTaskId,
+    projectGroupNo,
+    request: compactRecord({
+      sourceTaskId,
+      projectGroupNo,
+    }),
   };
 }
 
 export async function subtitleStatus(kwargs = {}) {
-  const publicId = trimToNull(kwargs.publicId);
-  const remoteTaskId = trimToNull(kwargs.remoteTaskId);
-  if (!publicId && !remoteTaskId) throw argumentError('缺少去字幕任务 ID', '传 --public-id 或 --remote-task-id。');
-  const payload = publicId
-    ? await awbApi.fetchSubtitleTaskByPublicId(publicId)
-    : await awbApi.fetchSubtitleTaskByRemoteId(remoteTaskId);
-  const resultUrls = uniqueNonEmpty([
-    ...parseListArg(payload?.result_url ?? payload?.resultUrl),
-    ...parseListArg(payload?.output_url ?? payload?.outputUrl),
-    ...parseListArg(payload?.url),
-  ]);
-  return compactRecord({
-    publicId: publicId ?? payload?.public_id ?? payload?.publicId ?? payload?.id ?? null,
-    remoteTaskId: remoteTaskId ?? payload?.remote_task_id ?? payload?.remoteTaskId ?? null,
-    taskStatus: payload?.status ?? payload?.taskStatus ?? payload?.state ?? null,
-    isTerminal: isTerminalTaskStatus(payload?.status ?? payload?.taskStatus ?? payload?.state),
-    resultCount: resultUrls.length,
-    ...(resultUrls.length ? { resultUrls } : {}),
-    errorMessage: payload?.error_message ?? payload?.errorMessage ?? payload?.message ?? null,
+  const taskId = requireValue(kwargs, 'taskId', 'task-id');
+  return taskStatus({
+    ...kwargs,
+    taskId,
+    taskType: 'VIDEO_SUBTITLE_REMOVAL',
   });
 }