@lingjingai/lj-awb-cli-pre 0.3.15

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

@@ -0,0 +1,3811 @@
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import {
+  API_ORIGIN,
+  APP_HOME_DIR,
+  AUTH_PATH,
+  DEFAULT_API_ORIGIN,
+  STATE_PATH,
+  TASK_UPLOAD_SCENE,
+  LingjingAwbCliError,
+  buildCosAuthorization,
+  encodeObjectNamePath,
+  firstArray,
+  flattenRecord,
+  guessMimeType,
+  inspectLocalFile,
+  inspectLocalFiles,
+  isSuccessTaskStatus,
+  isTerminalTaskStatus,
+  loadState,
+  normalizeFeedTaskType,
+  nowIso,
+  parseJsonArg,
+  parseListArg,
+  safeFileName,
+  saveState,
+  sleep,
+  splitCsv,
+  taskStatusText,
+  taskTypeToStatusKind,
+  toBool,
+  toInt,
+  toNumberOrNull,
+  trimToNull,
+  uniqueNonEmpty,
+} from './common.js';
+import { loadAuth, resolveAuthContext, summarizeAuth } from './auth.js';
+import * as awbApi from './api.js';
+
+const SITE = 'lj-awb';
+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']);
+
+export function normalizeUserInfo(payload) {
+  const data = payload && typeof payload === 'object' ? payload : {};
+  return {
+    userId: data.userId ?? data.id ?? null,
+    userName: data.userName ?? data.name ?? data.nickName ?? null,
+    phone: data.phone ?? null,
+    avatarUrl: data.avatarUrl ?? data.avatar ?? null,
+    groupId: data.groupId ?? data.currentGroupId ?? null,
+    groupName: data.groupName ?? data.currentGroupName ?? null,
+    permission: data.permission ?? null,
+  };
+}
+
+export function normalizeRows(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== 'object') return [];
+  for (const value of Object.values(payload)) {
+    if (Array.isArray(value)) return value;
+  }
+  return firstArray(payload);
+}
+
+function argumentError(message, hint = '') {
+  return new LingjingAwbCliError(message, {
+    type: 'argument_error',
+    exitCode: 2,
+    hint,
+  });
+}
+
+function compactRecord(record = {}) {
+  return Object.fromEntries(Object.entries(record)
+    .filter(([, value]) => value !== undefined && value !== null && value !== ''));
+}
+
+function requireValue(kwargs, key, label = key) {
+  const value = trimToNull(kwargs?.[key]);
+  if (!value) {
+    throw argumentError(`缺少参数：--${label.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`);
+  }
+  return value;
+}
+
+export function ensureConfirmed(kwargs, message, details = {}) {
+  if (toBool(kwargs?.dryRun)) return;
+  if (toBool(kwargs?.yes)) return;
+  throw new LingjingAwbCliError(message, {
+    type: 'confirmation_required',
+    exitCode: 10,
+    hint: '确认后追加 --yes 重试；如果只是预览，请追加 --dry-run。',
+    details,
+  });
+}
+
+function envProjectGroupNo() {
+  return trimToNull(
+    process.env.LINGJING_AWB_PROJECT_GROUP_NO
+    || process.env.AWB_PROJECT_GROUP_NO
+    || process.env.PROJECT_GROUP_NO
+    || process.env.SANDBOX_PROJECT_GROUP_NO,
+  );
+}
+
+function extractProjectGroupNo(payload) {
+  if (typeof payload === 'string') return trimToNull(payload);
+  if (!payload || typeof payload !== 'object') return null;
+  return trimToNull(
+    payload.projectGroupNo
+    ?? payload.lastProjectGroupNo
+    ?? payload.no
+    ?? payload.projectGroup?.projectGroupNo
+    ?? payload.projectGroup?.no,
+  );
+}
+
+export async function resolveProjectGroupNo(explicit, options = {}) {
+  const explicitProjectGroupNo = trimToNull(explicit);
+  if (explicitProjectGroupNo) {
+    if (!options.noSave) await saveState({ currentProjectGroupNo: explicitProjectGroupNo }).catch(() => {});
+    return explicitProjectGroupNo;
+  }
+  const fromEnv = envProjectGroupNo();
+  if (fromEnv) {
+    if (!options.noSave) await saveState({ currentProjectGroupNo: fromEnv }).catch(() => {});
+    return fromEnv;
+  }
+  if (!options.noNetwork) {
+    const current = await awbApi.fetchCurrentProjectGroup().catch(() => null);
+    const currentNo = extractProjectGroupNo(current);
+    if (currentNo) {
+      if (!options.noSave) await saveState({ currentProjectGroupNo: currentNo }).catch(() => {});
+      return currentNo;
+    }
+  }
+  const state = await loadState().catch(() => ({}));
+  if (trimToNull(state?.currentProjectGroupNo)) return trimToNull(state.currentProjectGroupNo);
+  if (options.allowNull) return null;
+  throw argumentError('未识别当前项目组', '请传 --project-group-no <no>，或先运行 project list 查看并选择。');
+}
+
+function extractPointBalance(payload) {
+  if (payload == null) return null;
+  if (typeof payload === 'number') return payload;
+  if (typeof payload !== 'object') return null;
+  for (const value of [
+    payload.point,
+    payload.groupPoint,
+    payload.availablePoint,
+    payload.totalPoint,
+    payload.teamIntegral,
+    payload.projectGroupIntegralCurrent,
+    payload.personIntegralCurrent,
+  ]) {
+    const numeric = toNumberOrNull(value);
+    if (numeric != null) return numeric;
+  }
+  return null;
+}
+
+function normalizeProjectGroupRecord(item, selectedProjectGroupNo = null) {
+  const projectGroupNo = item?.projectGroupNo ?? item?.no ?? null;
+  return {
+    projectGroupNo,
+    projectGroupName: item?.projectGroupName ?? item?.name ?? null,
+    point: item?.point ?? null,
+    isSelected: Boolean(projectGroupNo && selectedProjectGroupNo && projectGroupNo === selectedProjectGroupNo),
+  };
+}
+
+export async function listProjectGroups(kwargs = {}) {
+  const [listPayload, currentPayload] = await Promise.all([
+    awbApi.fetchProjectGroups(),
+    awbApi.fetchCurrentProjectGroup().catch(() => null),
+  ]);
+  const selectedProjectGroupNo = extractProjectGroupNo(currentPayload);
+  if (selectedProjectGroupNo) await saveState({ currentProjectGroupNo: selectedProjectGroupNo }).catch(() => {});
+  const keyword = trimToNull(kwargs.name ?? kwargs.keyword)?.toLowerCase();
+  const rows = normalizeRows(listPayload)
+    .map((item) => normalizeProjectGroupRecord(item, selectedProjectGroupNo))
+    .filter((item) => {
+      if (!keyword) return true;
+      return [item.projectGroupNo, item.projectGroupName]
+        .map((value) => String(value ?? '').toLowerCase())
+        .some((value) => value.includes(keyword));
+    });
+  return { projectGroups: rows, currentProjectGroupNo: selectedProjectGroupNo };
+}
+
+export async function fetchProjectGroupSummary(projectGroupNo) {
+  const actualProjectGroupNo = await resolveProjectGroupNo(projectGroupNo);
+  const [groupsPayload, currentPayload, integralPayload] = await Promise.all([
+    awbApi.fetchProjectGroups().catch(() => []),
+    awbApi.fetchCurrentProjectGroup().catch(() => null),
+    awbApi.fetchProjectGroupIntegral(actualProjectGroupNo).catch(() => null),
+  ]);
+  const groups = normalizeRows(groupsPayload);
+  const currentNo = extractProjectGroupNo(currentPayload);
+  const row = groups.find((item) => (item?.projectGroupNo ?? item?.no) === actualProjectGroupNo);
+  const summary = {
+    projectGroupNo: actualProjectGroupNo,
+    projectGroupName: row?.projectGroupName ?? row?.name ?? null,
+    isSelected: actualProjectGroupNo === currentNo,
+    projectBudgetBalance: integralPayload?.projectGroupIntegralCurrent ?? extractPointBalance(integralPayload),
+    projectBudgetMax: integralPayload?.projectGroupIntegralMax ?? null,
+  };
+  await saveState({
+    currentProjectGroupNo: summary.projectGroupNo,
+    currentProjectGroupName: summary.projectGroupName,
+  }).catch(() => {});
+  return summary;
+}
+
+export async function accountInfo() {
+  const [userInfo, pointPayload, currentProjectGroup] = await Promise.all([
+    awbApi.fetchUserInfo(),
+    awbApi.fetchPoints().catch(() => null),
+    fetchProjectGroupSummary().catch(() => null),
+  ]);
+  const user = normalizeUserInfo(userInfo);
+  await saveState({
+    currentUserId: user.userId,
+    currentUserName: user.userName,
+    currentGroupId: user.groupId,
+    currentGroupName: user.groupName,
+    currentProjectGroupNo: currentProjectGroup?.projectGroupNo ?? null,
+    currentProjectGroupName: currentProjectGroup?.projectGroupName ?? null,
+  }).catch(() => {});
+  return {
+    ...user,
+    billingPointBalance: extractPointBalance(pointPayload),
+    teamPointBalance: extractPointBalance(pointPayload),
+    currentProjectGroupNo: currentProjectGroup?.projectGroupNo ?? null,
+    currentProjectGroupName: currentProjectGroup?.projectGroupName ?? null,
+    projectBudgetBalance: currentProjectGroup?.projectBudgetBalance ?? currentProjectGroup?.projectPointBalance ?? null,
+    projectBudgetMax: currentProjectGroup?.projectBudgetMax ?? currentProjectGroup?.projectPointMax ?? null,
+    projectPointBalance: currentProjectGroup?.projectPointBalance ?? null,
+    projectPointMax: currentProjectGroup?.projectPointMax ?? null,
+  };
+}
+
+async function pathExists(filePath) {
+  if (!filePath) return false;
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function doctorCheck(name, status, message, details = {}) {
+  return compactRecord({ name, status, message, details: Object.keys(details).length ? details : undefined });
+}
+
+function doctorStatus(checks) {
+  if (checks.some((item) => item.status === 'error')) return 'error';
+  if (checks.some((item) => item.status === 'warning')) return 'warning';
+  return 'ready';
+}
+
+function doctorUserSummary(user) {
+  return compactRecord({
+    userId: user?.userId,
+    userName: user?.userName,
+    groupId: user?.groupId,
+    groupName: user?.groupName,
+    permission: user?.permission,
+  });
+}
+
+export async function doctor(kwargs = {}) {
+  const verify = toBool(kwargs.verify);
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
+  const auth = await loadAuth().catch(() => ({}));
+  const authContext = await resolveAuthContext({ required: false }).catch(() => ({ authenticated: false }));
+  const skillInstallDir = trimToNull(process.env.LINGJING_AWB_SKILL_INSTALL_DIR || process.env.ANIME_SKILL_INSTALL_DIR)
+    || path.join(process.env.HOME || '', '.cc-switch', 'skills', 'lj-awb');
+  const skillInstalled = await pathExists(path.join(skillInstallDir, 'SKILL.md'));
+  const locale = trimToNull(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG);
+  const localeIsUtf8 = locale ? /utf-?8/i.test(locale) : false;
+  const apiOriginIsDefault = API_ORIGIN === DEFAULT_API_ORIGIN;
+  const checks = [
+    doctorCheck(
+      'node',
+      nodeMajor >= 20 ? 'ok' : 'error',
+      nodeMajor >= 20 ? 'Node.js 版本满足 CLI 要求' : 'Node.js 版本过低，CLI 要求 >=20',
+      { nodeVersion: process.versions.node },
+    ),
+    doctorCheck(
+      'auth',
+      authContext.authenticated ? 'ok' : 'warning',
+      authContext.authenticated ? '已配置 access key' : '未配置 access key，只能运行本地检查类命令',
+      { source: authContext.accessKeyInfo?.source ?? null, sourceName: authContext.accessKeyInfo?.sourceName ?? null },
+    ),
+    doctorCheck(
+      'api_origin',
+      'ok',
+      apiOriginIsDefault ? '正在使用默认 API origin' : '已显式配置 API origin',
+      { apiOrigin: API_ORIGIN, isDefault: apiOriginIsDefault },
+    ),
+    doctorCheck(
+      'locale',
+      localeIsUtf8 ? 'ok' : 'warning',
+      localeIsUtf8 ? '终端字符集支持 UTF-8' : '当前终端字符集可能不是 UTF-8，中文参数可能出现乱码',
+      { locale },
+    ),
+    doctorCheck(
+      'skill',
+      skillInstalled ? 'ok' : 'warning',
+      skillInstalled ? '已检测到本地 lj-awb skill' : '未检测到本地 lj-awb skill；不影响 CLI，但会影响 Agent 工作流体验',
+      { skillInstallDir },
+    ),
+  ];
+
+  let user = null;
+  let projectGroup = null;
+  if (verify) {
+    if (!authContext.authenticated) {
+      checks.push(doctorCheck('network_auth', 'error', '无法联网校验：缺少 access key'));
+    } else {
+      try {
+        user = doctorUserSummary(normalizeUserInfo(await awbApi.fetchUserInfo()));
+        checks.push(doctorCheck('network_auth', 'ok', 'access key 联网校验通过', {
+          userId: user.userId,
+          userName: user.userName,
+          groupId: user.groupId,
+          groupName: user.groupName,
+        }));
+      } catch (error) {
+        checks.push(doctorCheck('network_auth', 'error', 'access key 联网校验失败', {
+          type: error?.type ?? 'error',
+          message: error?.message ?? String(error),
+        }));
+      }
+      try {
+        const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, { allowNull: true });
+        projectGroup = projectGroupNo ? await fetchProjectGroupSummary(projectGroupNo) : null;
+        checks.push(doctorCheck(
+          'project_group',
+          projectGroup?.projectGroupNo ? 'ok' : 'warning',
+          projectGroup?.projectGroupNo ? '已识别当前项目组' : '未识别当前项目组；生成任务前需要传 --project-group-no 或先选择项目组',
+          { projectGroupNo: projectGroup?.projectGroupNo ?? null, projectGroupName: projectGroup?.projectGroupName ?? null },
+        ));
+      } catch (error) {
+        checks.push(doctorCheck('project_group', 'warning', '项目组检查失败', {
+          type: error?.type ?? 'error',
+          message: error?.message ?? String(error),
+        }));
+      }
+    }
+  } else {
+    checks.push(doctorCheck('network', 'skipped', '默认不做联网校验；需要时追加 --verify'));
+  }
+
+  return {
+    doctorStatus: doctorStatus(checks),
+    verify,
+    runtime: {
+      nodeVersion: process.versions.node,
+      platform: process.platform,
+      arch: process.arch,
+    },
+    origins: {
+      apiOrigin: API_ORIGIN,
+      assetEditOrigin: awbApi.ASSET_EDIT_ORIGIN,
+    },
+    auth: summarizeAuth(auth, authContext.accessKeyInfo),
+    paths: {
+      appHomeDir: APP_HOME_DIR,
+      authPath: AUTH_PATH,
+      statePath: STATE_PATH,
+      skillInstallDir,
+    },
+    user,
+    projectGroup,
+    checks,
+  };
+}
+
+export async function selectTeam(kwargs = {}) {
+  const groupId = requireValue(kwargs, 'groupId', 'group-id');
+  if (toBool(kwargs.dryRun)) {
+    return { dryRun: true, action: 'account switch-team', selected: false, request: { groupId } };
+  }
+  ensureConfirmed(kwargs, '切换团队会改变后续 CLI 调用上下文，需要确认', {
+    action: 'account switch-team',
+    groupId,
+  });
+  await awbApi.updateCurrentTeam(groupId);
+  await saveState({ currentGroupId: groupId }).catch(() => {});
+  return { selected: true, groupId };
+}
+
+export async function selectProjectGroupCommand(kwargs = {}) {
+  const projectGroupNo = requireValue(kwargs, 'projectGroupNo', 'project-group-no');
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'project use',
+      selected: false,
+      request: { projectGroupNo },
+    };
+  }
+  ensureConfirmed(kwargs, '切换项目组会改变后续生成任务归属，需要确认', {
+    action: 'project use',
+    projectGroupNo,
+  });
+  await awbApi.selectProjectGroup(projectGroupNo);
+  await saveState({ currentProjectGroupNo: projectGroupNo }).catch(() => {});
+  return { selected: true, ...(await fetchProjectGroupSummary(projectGroupNo)) };
+}
+
+function buildProjectGroupUsersFromArgs(kwargs, allUsers = []) {
+  const membersJson = parseJsonArg(kwargs.membersJson, null);
+  if (Array.isArray(membersJson)) return membersJson;
+  const selectedUserIds = new Set(parseListArg(kwargs.userIds));
+  const rows = Array.isArray(allUsers) ? allUsers : [];
+  const groupUser = rows
+    .filter((user) => Boolean(user?.isCheck) || selectedUserIds.has(user?.userId))
+    .map((user) => ({
+      userId: user.userId,
+      role: user.isCheck ? user.role ?? 'CREATOR' : 'USER',
+    }))
+    .filter((item) => item.userId);
+  if (!groupUser.length && selectedUserIds.size) {
+    return [...selectedUserIds].map((userId, index) => ({ userId, role: index === 0 ? 'CREATOR' : 'USER' }));
+  }
+  if (groupUser.length && !groupUser.some((item) => item.role === 'CREATOR')) {
+    groupUser[0] = { ...groupUser[0], role: 'CREATOR' };
+  }
+  return groupUser;
+}
+
+export async function createProjectGroupCommand(kwargs = {}) {
+  const name = requireValue(kwargs, 'name');
+  const point = toInt(kwargs.point, 0);
+  if (toBool(kwargs.dryRun)) {
+    const groupUser = buildProjectGroupUsersFromArgs(kwargs, []);
+    return {
+      dryRun: true,
+      action: 'project create',
+      created: false,
+      request: { projectGroupName: name, point, groupUser },
+      memberCount: groupUser.length,
+      note: groupUser.length ? null : 'dry-run 未联网拉取团队默认成员；正式执行会自动获取已选成员。',
+    };
+  }
+  ensureConfirmed(kwargs, '创建项目组是云端写入动作，需要确认', {
+    action: 'project create',
+    projectGroupName: name,
+    point,
+  });
+  const before = normalizeRows(await awbApi.fetchProjectGroups().catch(() => []));
+  const allUsers = await awbApi.fetchProjectGroupUsers();
+  const groupUser = buildProjectGroupUsersFromArgs(kwargs, allUsers);
+  if (!groupUser.length) {
+    throw argumentError('未解析到项目组成员', '请先运行 project users，或传 --members-json / --user-ids。');
+  }
+  await awbApi.createProjectGroup({ projectGroupName: name, point, groupUser });
+  const after = normalizeRows(await awbApi.fetchProjectGroups());
+  const beforeIds = new Set(before.map((item) => item?.projectGroupNo ?? item?.no).filter(Boolean));
+  const created = after.find((item) => !beforeIds.has(item?.projectGroupNo ?? item?.no))
+    ?? after.find((item) => (item?.projectGroupName ?? item?.name) === name);
+  const projectGroupNo = created?.projectGroupNo ?? created?.no ?? null;
+  if (!projectGroupNo) {
+    throw new LingjingAwbCliError('项目组已创建，但没有解析到新 projectGroupNo', {
+      type: 'api_error',
+      exitCode: 1,
+      details: { name },
+    });
+  }
+  await awbApi.selectProjectGroup(projectGroupNo).catch(() => {});
+  return {
+    ...(await fetchProjectGroupSummary(projectGroupNo)),
+    created: true,
+    memberCount: groupUser.length,
+  };
+}
+
+export async function updateProjectGroupCommand(kwargs = {}) {
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, {
+    allowNull: toBool(kwargs.dryRun),
+    noNetwork: toBool(kwargs.dryRun),
+    noSave: toBool(kwargs.dryRun),
+  });
+  if (!projectGroupNo) {
+    throw argumentError('缺少项目组编号', '传 --project-group-no <no>，或先选择当前项目组。');
+  }
+  const body = { projectGroupNo };
+  if (kwargs.name != null && String(kwargs.name).trim() !== '') {
+    body.projectGroupName = String(kwargs.name).trim();
+  }
+  if (kwargs.point != null && String(kwargs.point).trim() !== '') {
+    body.point = toInt(kwargs.point, 0);
+  }
+  if (Object.keys(body).length === 1) {
+    throw argumentError('缺少项目组更新字段', '至少传 --name 或 --point。');
+  }
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'project update',
+      updated: false,
+      request: body,
+    };
+  }
+  ensureConfirmed(kwargs, '修改项目组是云端写入动作，需要确认', {
+    action: 'project update',
+    body,
+  });
+  await awbApi.updateProjectGroup(body);
+  return {
+    ...(await fetchProjectGroupSummary(projectGroupNo).catch(() => ({ projectGroupNo }))),
+    updated: true,
+  };
+}
+
+export async function ensureProjectGroupCommand(kwargs = {}) {
+  const name = requireValue(kwargs, 'name');
+  if (toBool(kwargs.dryRun)) {
+    return {
+      dryRun: true,
+      action: 'project ensure',
+      request: {
+        projectGroupName: name,
+        point: toInt(kwargs.point, 0),
+        selectExisting: kwargs.selectExisting !== false,
+      },
+      note: 'dry-run 不联网判断是否已存在；正式执行会先查找同名项目组。',
+    };
+  }
+  const { projectGroups } = await listProjectGroups({ name });
+  const existing = projectGroups.find((item) => item.projectGroupName === name) ?? null;
+  if (existing?.projectGroupNo) {
+    ensureConfirmed(kwargs, '确认复用并切换到已存在项目组', {
+      action: 'project ensure',
+      projectGroupNo: existing.projectGroupNo,
+    });
+    await awbApi.selectProjectGroup(existing.projectGroupNo).catch(() => {});
+    return {
+      ...(await fetchProjectGroupSummary(existing.projectGroupNo)),
+      created: false,
+      reused: true,
+    };
+  }
+  return await createProjectGroupCommand(kwargs);
+}
+
+export async function creditsBalance(kwargs = {}) {
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, { allowNull: true }).catch(() => null);
+  const [teamPayload, projectGroup] = await Promise.all([
+    awbApi.fetchPoints(),
+    projectGroupNo ? fetchProjectGroupSummary(projectGroupNo).catch(() => null) : Promise.resolve(null),
+  ]);
+  const billingPointBalance = extractPointBalance(teamPayload);
+  return {
+    billingPointBalance,
+    teamPointBalance: billingPointBalance,
+    currentProjectGroupNo: projectGroup?.projectGroupNo ?? projectGroupNo,
+    currentProjectGroupName: projectGroup?.projectGroupName ?? null,
+    projectBudgetBalance: projectGroup?.projectBudgetBalance ?? projectGroup?.projectPointBalance ?? null,
+    projectBudgetMax: projectGroup?.projectBudgetMax ?? projectGroup?.projectPointMax ?? null,
+    projectPointBalance: projectGroup?.projectPointBalance ?? null,
+    projectPointMax: projectGroup?.projectPointMax ?? null,
+  };
+}
+
+function parseTimeMs(value, fallback = null) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) return numeric < 1_000_000_000_000 ? numeric * 1000 : numeric;
+  const text = String(value).trim();
+  const parsed = Date.parse(/\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}/.test(text) ? `${text.replace(' ', 'T')}+08:00` : text);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function taskTimeMs(row) {
+  return parseTimeMs(row.gmtCreate ?? row.createdAt ?? row.createTime, null);
+}
+
+function usageBucket() {
+  return {
+    taskCount: 0,
+    successTaskCount: 0,
+    resultCount: 0,
+    pointTotal: 0,
+  };
+}
+
+function addTaskToUsage(bucket, row) {
+  bucket.taskCount += 1;
+  if (isSuccessTaskStatus(row.taskStatus)) bucket.successTaskCount += 1;
+  bucket.resultCount += toInt(row.resultCount, 0);
+  bucket.pointTotal += toNumberOrNull(row.pointNo) ?? 0;
+}
+
+export async function creditsUsageSummary(kwargs = {}) {
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo);
+  const sinceMs = parseTimeMs(kwargs.sinceMs ?? kwargs.since, null)
+    ?? (kwargs.lastHours ? Date.now() - toNumberOrNull(kwargs.lastHours) * 60 * 60 * 1000 : null);
+  const untilMs = parseTimeMs(kwargs.untilMs ?? kwargs.until, Date.now());
+  const taskTypes = parseListArg(kwargs.taskTypes).length
+    ? parseListArg(kwargs.taskTypes)
+    : ['IMAGE_CREATE', 'IMAGE_EDIT', 'VIDEO_GROUP'];
+  const pageSize = Math.min(Math.max(toInt(kwargs.pageSize, 100), 1), 200);
+  const tasks = [];
+  for (const taskType of taskTypes) {
+    const rows = await taskList({
+      taskType,
+      projectGroupNo,
+      pageSize,
+      minTime: untilMs,
+    });
+    for (const row of rows.tasks) {
+      const createdMs = taskTimeMs(row);
+      if (sinceMs != null && createdMs != null && createdMs < sinceMs) continue;
+      if (untilMs != null && createdMs != null && createdMs > untilMs) continue;
+      tasks.push(row);
+    }
+  }
+  const buckets = {};
+  for (const row of tasks) {
+    const key = normalizeFeedTaskType(row.feedTaskType ?? row.taskType);
+    buckets[key] ??= usageBucket();
+    addTaskToUsage(buckets[key], row);
+  }
+  const pointTotal = Object.values(buckets).reduce((sum, bucket) => sum + bucket.pointTotal, 0);
+  return {
+    projectGroupNo,
+    sinceMs,
+    sinceText: sinceMs ? new Date(sinceMs).toISOString() : null,
+    untilMs,
+    untilText: untilMs ? new Date(untilMs).toISOString() : null,
+    scannedTaskCount: tasks.length,
+    pointTotal,
+    buckets,
+    ...(toBool(kwargs.includeTasks) ? { tasks } : {}),
+  };
+}
+
+function modelListMetadata(kind, paramKeys = [], rulesByKey = new Map()) {
+  const keys = new Set(paramKeys);
+  const imageReferenceParams = ['cref', 'sref', 'iref', 'resources'].filter((key) => keys.has(key));
+  const videoResourceParams = ['frames', 'multi_param', 'multi_prompt'].filter((key) => keys.has(key));
+  const inputModes = createSpecSupportedIntents(createSpecInputModes(kind, keys, rulesByKey), kind)
+    .map((item) => item.mode);
+  const controls = [];
+  if (keys.has('ratio')) controls.push('ratio');
+  if (keys.has('quality')) controls.push('quality');
+  if (kind === 'image' && keys.has('generate_num')) controls.push('generateNum');
+  if (kind === 'video' && keys.has('generated_time')) controls.push('duration');
+  if (kind === 'video' && (keys.has('need_audio') || keys.has('audio'))) controls.push('needAudio');
+  return {
+    inputModes,
+    controls,
+    resourceParams: kind === 'image' ? imageReferenceParams : videoResourceParams,
+  };
+}
+
+function normalizeModelRows(payload, kind, options = {}) {
+  const includeRaw = Boolean(options.includeRaw);
+  const includeInternal = Boolean(options.includeInternal);
+  return normalizeRows(payload).map((item) => {
+    const modelCode = item?.modelCode ?? item?.code ?? item?.value ?? null;
+    const modelGroupCode = item?.modelGroupCode ?? item?.groupCode ?? item?.modelGroup?.modelGroupCode ?? item?.modelGroup?.code ?? null;
+    const rawText = JSON.stringify(item);
+    const rawOptions = normalizeRawModelOptions(item);
+    const rawParamKeys = rawOptions.map((option) => option.paramKey).filter(Boolean);
+    const paramKeys = rawParamKeys.length ? uniqueNonEmpty(rawParamKeys) : uniqueNonEmpty([
+      ...rawText.matchAll(/"paramKey"\s*:\s*"([^"]+)"/g),
+    ].map((match) => match[1]));
+    const rulesByKey = new Map(rawOptions.map((option) => [option.paramKey, option.rules]).filter(([key, rules]) => key && rules));
+    const metadata = modelListMetadata(kind, paramKeys, rulesByKey);
+    const row = compactRecord({
+      modelGroupCode,
+      displayName: item?.modelName ?? item?.name ?? item?.label ?? null,
+      provider: item?.provider ?? item?.vendor ?? item?.supplier ?? item?.componyName ?? null,
+      enabled: item?.enabled ?? item?.available ?? item?.status ?? null,
+      modelStatus: item?.modelStatus ?? null,
+      taskQueueNum: item?.taskQueueNum ?? null,
+      feeCalcType: item?.feeCalcType ?? item?.feeType ?? null,
+      inputModes: metadata.inputModes,
+      params: metadata.controls,
+      _searchText: JSON.stringify([
+        modelCode,
+        modelGroupCode,
+        item?.modelName ?? item?.name ?? item?.label,
+        item?.provider ?? item?.vendor ?? item?.supplier ?? item?.componyName,
+        metadata.inputModes.join(','),
+        metadata.controls.join(','),
+        metadata.resourceParams.join(','),
+        paramKeys.join(','),
+      ]),
+      ...(includeInternal ? { _modelCode: modelCode } : {}),
+    });
+    return includeRaw ? { ...row, raw: item } : row;
+  });
+}
+
+export async function listModels(kind, kwargs = {}) {
+  const usage = kind === 'image' ? 'IMAGE_CREATE' : 'VIDEO_CREATE';
+  const payload = await awbApi.fetchModelsByUsage(usage, {});
+  const keyword = trimToNull(kwargs.model ?? kwargs.keyword)?.toLowerCase();
+  const includeRaw = toBool(kwargs.includeRaw);
+  const models = normalizeModelRows(payload, kind, { includeRaw })
+    .filter((item) => {
+      if (!keyword) return true;
+      return String(item._searchText ?? '').toLowerCase().includes(keyword);
+    })
+    .map(({ _searchText, _modelCode, ...item }) => item);
+  return { usage, models };
+}
+
+async function findModelGroup(modelGroupCode, options = {}) {
+  const includeRaw = Boolean(options.includeRaw);
+  const [imageResult, videoResult] = await Promise.allSettled([
+    awbApi.fetchModelsByUsage('IMAGE_CREATE', {}),
+    awbApi.fetchModelsByUsage('VIDEO_CREATE', {}),
+  ]);
+  const imageModels = imageResult.status === 'fulfilled'
+    ? normalizeModelRows(imageResult.value, 'image', { includeRaw, includeInternal: true }).map((item) => ({ ...item, kind: 'image' }))
+    : [];
+  const videoModels = videoResult.status === 'fulfilled'
+    ? normalizeModelRows(videoResult.value, 'video', { includeRaw, includeInternal: true }).map((item) => ({ ...item, kind: 'video' }))
+    : [];
+  return [...imageModels, ...videoModels].find((item) => item.modelGroupCode === modelGroupCode) ?? null;
+}
+
+function resolveTaskModel(kind, kwargs = {}) {
+  const modelGroupCode = trimToNull(kwargs.modelGroupCode);
+  if (!modelGroupCode) {
+    throw argumentError('缺少模型组编码', '传 --model-group-code <code>；推荐先运行 model image-models / model video-models。');
+  }
+  return {
+    kind,
+    modelGroupCode,
+  };
+}
+
+async function fetchNormalizedModelOptions(options = {}) {
+  const payload = await awbApi.fetchModelOptions({
+    modelCode: options.modelCode,
+    modelGroupCode: options.modelGroupCode,
+    selectedConfigs: options.selectedConfigs,
+  });
+  const normalizedOptions = normalizeRows(payload).map((item) => ({
+    rank: item?.rank ?? null,
+    paramKey: item?.paramKey ?? null,
+    paramName: item?.paramName ?? null,
+    paramType: item?.paramType ?? null,
+    optionList: typeof item?.optionList === 'string' ? parseJsonArg(item.optionList, item.optionList) : item?.optionList ?? null,
+    required: item?.required ?? item?.rule?.required ?? null,
+    hasConstraint: item?.hasConstraint ?? null,
+    rules: item?.rules ?? item?.rule?.rules ?? null,
+    raw: options.includeRaw ? item : undefined,
+  }));
+  return {
+    modelGroupCode: options.modelGroupCode,
+    selectedConfigs: options.selectedConfigs,
+    options: normalizedOptions,
+  };
+}
+
+function normalizeRawModelOptions(rawModel = {}, options = {}) {
+  const rawParams = Array.isArray(rawModel?.modelParams) ? rawModel.modelParams : [];
+  return rawParams.map((item) => ({
+    rank: item?.rank ?? null,
+    paramKey: item?.paramKey ?? null,
+    paramName: item?.paramName ?? null,
+    paramType: item?.paramType ?? null,
+    optionList: typeof item?.optionList === 'string' ? parseJsonArg(item.optionList, item.optionList) : item?.optionList ?? null,
+    required: item?.required ?? item?.rules?.required ?? null,
+    hasConstraint: item?.hasConstraint ?? null,
+    rules: item?.rules ?? null,
+    raw: options.includeRaw ? item : undefined,
+  }));
+}
+
+function modelSummaryFromRaw(rawModel = {}, modelGroupCode, taskKind) {
+  return compactRecord({
+    modelGroupCode: rawModel?.modelGroupCode ?? modelGroupCode,
+    displayName: rawModel?.modelName ?? rawModel?.name ?? null,
+    provider: rawModel?.componyName ?? rawModel?.provider ?? rawModel?.vendor ?? null,
+    taskKind,
+    modelStatus: rawModel?.modelStatus ?? null,
+    taskQueueNum: rawModel?.taskQueueNum ?? null,
+    feeCalcType: rawModel?.feeCalcType ?? null,
+  });
+}
+
+async function fetchModelConstraintSchema(rawModel = {}, modelGroupCode) {
+  const usage = trimToNull(rawModel?.usage);
+  if (!usage) return [];
+  const payload = await awbApi.fetchModelsByUsage(usage, { includeConstraintSchema: true }).catch(() => null);
+  const rows = normalizeRows(payload);
+  const found = rows.find((item) => (
+    item?.modelGroupCode === modelGroupCode
+    || (rawModel?.modelCode && item?.modelCode === rawModel.modelCode)
+  ));
+  return Array.isArray(found?.constraintSchema) ? found.constraintSchema : [];
+}
+
+function configCodeDecisionKey(code, taskKind = 'image') {
+  const normalized = String(code || '');
+  const mappings = {
+    generated_time: 'duration',
+    generate_num: 'generateNum',
+    need_audio: 'needAudio',
+    audio: 'needAudio',
+    frames: 'resource.image.frame',
+    multi_param: 'resource.reference',
+    multi_prompt: 'resource.keyframe',
+    iref: 'resource.image.reference',
+    cref: 'resource.image.reference',
+    sref: 'resource.image.reference',
+    resources: 'resource.image.reference',
+    generated_mode: 'generatedMode',
+    generate_mode: 'generatedMode',
+  };
+  if (normalized === 'prompt') return 'prompt';
+  if (normalized === 'ratio') return 'ratio';
+  if (normalized === 'quality') return 'quality';
+  if (taskKind === 'video' && normalized === 'duration') return 'duration';
+  return mappings[normalized] ?? normalized;
+}
+
+function constraintTriggerMeaning(value) {
+  if (value === '__NOT_EMPTY__') return 'present';
+  if (value === '__EMPTY__') return 'empty';
+  return 'equals';
+}
+
+function normalizeConstraintConditions(conditions = [], taskKind = 'image') {
+  return (Array.isArray(conditions) ? conditions : []).map((condition) => compactRecord({
+    key: configCodeDecisionKey(condition?.triggerConfigCode, taskKind),
+    configCode: condition?.triggerConfigCode,
+    value: condition?.triggerConfigValue,
+    meaning: constraintTriggerMeaning(condition?.triggerConfigValue),
+  }));
+}
+
+function normalizeModelConstraints(constraintSchema = [], taskKind = 'image') {
+  return (Array.isArray(constraintSchema) ? constraintSchema : []).map((constraint) => {
+    const allowValues = Array.isArray(constraint?.allowValues) ? constraint.allowValues : [];
+    return compactRecord({
+      id: constraint?.constraintId,
+      name: constraint?.constraintName,
+      target: configCodeDecisionKey(constraint?.targetConfigCode, taskKind),
+      targetConfigCode: constraint?.targetConfigCode,
+      allowValues,
+      effect: allowValues.length ? 'allow_only_values' : 'no_selectable_values',
+      priority: constraint?.priority,
+      conditions: normalizeConstraintConditions(constraint?.conditions, taskKind),
+    });
+  }).filter((constraint) => constraint.target || constraint.targetConfigCode);
+}
+
+function resourceUsageList(usage) {
+  return (Array.isArray(usage) ? usage : [usage])
+    .map((item) => trimToNull(item))
+    .filter(Boolean);
+}
+
+function resourceMediaType(resource = {}) {
+  const type = String(resource.type || '').toLowerCase();
+  if (type === 'image') return 'IMAGE';
+  if (type === 'video') return 'VIDEO';
+  if (type === 'audio') return 'AUDIO';
+  if (type === 'subject') return 'SUBJECT';
+  return type.toUpperCase();
+}
+
+function resourceRuleMatches(rule = {}, resource = {}) {
+  return String(rule.mediaType || '').toUpperCase() === resourceMediaType(resource)
+    && resourceUsageList(rule.usage).includes(resource.usage);
+}
+
+function resourceText(resource = {}) {
+  return `${resource.type}:${resource.usage}${resource.reference_key ? `:${resource.reference_key}` : ''}`;
+}
+
+function resourceSourceKindForValidation(detail = {}) {
+  if (detail.localFile) return 'local_file';
+  const source = detail.resource?.source || {};
+  if (source.kind === 'asset_id') return 'asset_id';
+  const value = trimToNull(source.value);
+  if (/^https?:\/\//i.test(value || '')) return 'http_url';
+  return 'backendPath';
+}
+
+function sourceAllowedByRule(rule = {}, sourceKind) {
+  const sources = Array.isArray(rule.sources) ? rule.sources : [];
+  if (!sources.length) return true;
+  return sources.includes(sourceKind);
+}
+
+function resourceFormatForValidation(detail = {}) {
+  if (detail.localFile?.format) return String(detail.localFile.format).toLowerCase();
+  const value = detail.resource?.source?.value;
+  const pathname = (() => {
+    try {
+      return new URL(String(value)).pathname;
+    } catch {
+      return String(value || '').split('?')[0].split('#')[0];
+    }
+  })();
+  const ext = path.extname(pathname).replace(/^\./, '').toLowerCase();
+  return ext || null;
+}
+
+function normalizeFileFormat(value) {
+  const format = trimToNull(value)?.toLowerCase();
+  if (!format) return null;
+  if (format === 'jpeg' || format === 'jfif') return 'jpg';
+  return format;
+}
+
+function normalizedFileTypes(fileTypes = []) {
+  return Array.isArray(fileTypes)
+    ? uniqueNonEmpty(fileTypes.map((item) => normalizeFileFormat(item)))
+    : [];
+}
+
+function fileTypeIncludes(fileTypes = [], format) {
+  const normalized = normalizeFileFormat(format);
+  if (!normalized) return true;
+  return normalizedFileTypes(fileTypes).includes(normalized);
+}
+
+function isImageRule(rule = {}) {
+  return String(rule.mediaType || '').toUpperCase() === 'IMAGE';
+}
+
+function imageFormatPolicy(fileTypes = []) {
+  const types = normalizedFileTypes(fileTypes);
+  if (!types.length) {
+    return {
+      kind: 'normal_without_webp',
+      webpSupported: false,
+      autoConvertTo: 'jpg',
+      strict: false,
+      summary: 'normal_without_webp',
+    };
+  }
+  if (types.length === 1 && types[0] === 'webp') {
+    return {
+      kind: 'normal_plus_webp',
+      webpSupported: true,
+      strict: false,
+      summary: 'normal_plus_webp',
+    };
+  }
+  return {
+    kind: 'strict',
+    webpSupported: types.includes('webp'),
+    allowed: types,
+    autoConvertTo: preferredImageConversionTarget(types),
+    strict: true,
+    summary: `strict:${types.join('|')}`,
+  };
+}
+
+function preferredImageConversionTarget(fileTypes = []) {
+  const types = normalizedFileTypes(fileTypes);
+  if (types.includes('jpg')) return 'jpg';
+  if (types.includes('png')) return 'png';
+  if (types.includes('webp')) return 'webp';
+  return types[0] || 'jpg';
+}
+
+function isConvertibleLocalImage(detail = {}) {
+  return Boolean(detail.localFile?.exists && String(detail.localFile?.mimeType || '').startsWith('image/'));
+}
+
+function resourceFormatConversion(rule = {}, detail = {}) {
+  if (!isImageRule(rule)) return null;
+  const format = normalizeFileFormat(resourceFormatForValidation(detail));
+  if (!format) return null;
+  const policy = imageFormatPolicy(rule.fileTypes);
+  if (policy.kind === 'normal_without_webp') {
+    if (format !== 'webp') return null;
+    return {
+      fromFormat: format,
+      toFormat: policy.autoConvertTo,
+      reason: 'image_webp_not_supported',
+      possible: isConvertibleLocalImage(detail),
+    };
+  }
+  if (policy.kind === 'normal_plus_webp') return null;
+  if (!policy.strict || fileTypeIncludes(policy.allowed, format)) return null;
+  return {
+    fromFormat: format,
+    toFormat: policy.autoConvertTo,
+    reason: 'image_strict_format_mismatch',
+    possible: isConvertibleLocalImage(detail),
+    allowed: policy.allowed,
+  };
+}
+
+function fileTypeAllowedByRule(rule = {}, format) {
+  const fileTypes = normalizedFileTypes(rule.fileTypes);
+  if (!format) return true;
+  if (isImageRule(rule)) {
+    const policy = imageFormatPolicy(fileTypes);
+    if (policy.kind === 'normal_without_webp') return normalizeFileFormat(format) !== 'webp';
+    if (policy.kind === 'normal_plus_webp') return COMMON_IMAGE_FORMATS.has(normalizeFileFormat(format));
+    return fileTypeIncludes(policy.allowed, format);
+  }
+  if (!fileTypes.length) return true;
+  return fileTypeIncludes(fileTypes, format);
+}
+
+function assertResourceShapeAgainstModel(resourceDetails = [], resourceRules = []) {
+  for (const [index, detail] of resourceDetails.entries()) {
+    const resource = detail.resource;
+    const rule = resourceRules.find((item) => resourceRuleMatches(item, resource));
+    if (!rule) {
+      throw argumentError(
+        `模型不支持素材输入：${resourceText(resource)}`,
+        '请先运行 model options --model-group-code <code>，只使用 resources[] 中列出的 media/usage；上传音频参考必须存在 media=AUDIO usage=reference。',
+      );
+    }
+    const sourceKind = resourceSourceKindForValidation(detail);
+    if (!sourceAllowedByRule(rule, sourceKind)) {
+      throw argumentError(
+        `模型不支持 ${resourceText(resource)} 的来源：${sourceKind}`,
+        `该资源允许来源：${(rule.sources || []).join(', ') || '未限制'}。`,
+      );
+    }
+    const format = resourceFormatForValidation(detail);
+    const conversion = resourceFormatConversion(rule, detail);
+    if (conversion && !conversion.possible) {
+      throw argumentError(
+        `素材格式需要转换但无法自动处理：${resourceText(resource)}`,
+        `当前格式 ${conversion.fromFormat}，目标格式 ${conversion.toFormat}；请使用本地文件，或先转换后再传远程 URL / asset。`,
+      );
+    }
+    if (!conversion && !fileTypeAllowedByRule(rule, format)) {
+      throw argumentError(
+        `模型不支持 ${resourceText(resource)} 的文件格式：${format}`,
+        `该资源允许格式：${(rule.fileTypes || []).join(', ')}。`,
+      );
+    }
+    if (detail.localFile?.size != null && rule.maxSizeKB != null && detail.localFile.size > rule.maxSizeKB * 1024) {
+      throw argumentError(
+        `素材超过模型大小限制：${resourceText(resource)}`,
+        `文件大小 ${(detail.localFile.size / 1024).toFixed(0)}KB，模型限制 <=${rule.maxSizeKB}KB。`,
+      );
+    }
+    if (resource.usage === 'keyframe') {
+      if (rule.maxPromptLength != null && resource.prompt && resource.prompt.length > rule.maxPromptLength) {
+        throw argumentError(`keyframe prompt 超过模型长度限制：${resource.prompt.length}/${rule.maxPromptLength}`);
+      }
+      if (rule.minDurationMs != null && resource.duration != null && resource.duration * 1000 < rule.minDurationMs) {
+        throw argumentError(`keyframe duration 小于模型限制：${resource.duration}s`, `最小 ${(rule.minDurationMs / 1000).toFixed(3).replace(/\.?0+$/, '')}s。`);
+      }
+      if (rule.maxDurationMs != null && resource.duration != null && resource.duration * 1000 > rule.maxDurationMs) {
+        throw argumentError(`keyframe duration 超过模型限制：${resource.duration}s`, `最大 ${(rule.maxDurationMs / 1000).toFixed(3).replace(/\.?0+$/, '')}s。`);
+      }
+    }
+  }
+}
+
+function assertResourceCountsAgainstModel(resourceDetails = [], resourceRules = []) {
+  for (const rule of resourceRules) {
+    const matches = resourceDetails.filter((detail) => resourceRuleMatches(rule, detail.resource));
+    if (!matches.length) continue;
+    const count = matches.length;
+    const minCount = rule.minFiles ?? rule.minItems;
+    const maxCount = rule.maxFiles ?? rule.maxItems;
+    if (minCount != null && count < minCount) {
+      throw argumentError(`模型素材数量不足：${rule.mediaType}:${resourceUsageList(rule.usage).join('|')}`, `当前 ${count} 个，至少 ${minCount} 个。`);
+    }
+    if (maxCount != null && count > maxCount) {
+      throw argumentError(`模型素材数量超限：${rule.mediaType}:${resourceUsageList(rule.usage).join('|')}`, `当前 ${count} 个，最多 ${maxCount} 个。`);
+    }
+  }
+
+  const firstFrames = resourceDetails.filter((detail) => detail.resource.type === 'image' && detail.resource.usage === 'first_frame');
+  const lastFrames = resourceDetails.filter((detail) => detail.resource.type === 'image' && detail.resource.usage === 'last_frame');
+  if (firstFrames.length > 1) throw argumentError('同一请求最多只能有 1 个 first_frame');
+  if (lastFrames.length > 1) throw argumentError('同一请求最多只能有 1 个 last_frame');
+  if (lastFrames.length && !firstFrames.length) {
+    const frameRule = resourceRules.find((rule) => (
+      String(rule.mediaType || '').toUpperCase() === 'IMAGE'
+      && resourceUsageList(rule.usage).includes('last_frame')
+    ));
+    if (frameRule?.supportLastFrameOnly !== true) {
+      throw argumentError('当前模型不支持仅尾帧输入', '请同时提供 image:first_frame，或换用 supportLastFrameOnly=true 的模型。');
+    }
+  }
+
+  const keyframes = resourceDetails.filter((detail) => detail.resource.usage === 'keyframe');
+  const orders = new Set();
+  for (const detail of keyframes) {
+    const order = detail.resource.order;
+    if (orders.has(order)) throw argumentError(`keyframe order 重复：${order}`);
+    orders.add(order);
+  }
+}
+
+function promptParamValue(promptParams = {}, key) {
+  if (key === 'duration') return promptParams.duration;
+  if (key === 'generateNum') return promptParams.generate_num;
+  if (key === 'needAudio') return promptParams.need_audio;
+  return promptParams[key];
+}
+
+function providedPromptParamKeys(promptParams = {}) {
+  const keys = [];
+  for (const key of ['prompt', 'ratio', 'quality', 'duration', 'generateNum', 'needAudio']) {
+    const value = promptParamValue(promptParams, key);
+    if (value !== undefined && value !== null && value !== '') keys.push(key);
+  }
+  return keys;
+}
+
+function inferGeneratedMode(resources = []) {
+  if (resources.some((resource) => resource.usage === 'keyframe')) return 'multi_prompt';
+  if (resources.some((resource) => ['first_frame', 'last_frame'].includes(resource.usage))) return 'frames';
+  if (resources.some((resource) => resource.usage === 'reference')) return 'multi_param';
+  return null;
+}
+
+function conditionValue(condition = {}, promptParams = {}) {
+  const resources = Array.isArray(promptParams.resources) ? promptParams.resources : [];
+  if (condition.key === 'resource.image.frame') return resources.some((resource) => resource.type === 'image' && ['first_frame', 'last_frame'].includes(resource.usage));
+  if (condition.key === 'resource.reference') return resources.some((resource) => resource.usage === 'reference');
+  if (condition.key === 'resource.keyframe') return resources.some((resource) => resource.usage === 'keyframe');
+  if (condition.key === 'generatedMode') return inferGeneratedMode(resources);
+  return promptParamValue(promptParams, condition.key);
+}
+
+function constraintConditionMatches(condition = {}, promptParams = {}) {
+  const actual = conditionValue(condition, promptParams);
+  if (condition.meaning === 'present') return actual !== undefined && actual !== null && actual !== '' && actual !== false;
+  if (condition.meaning === 'empty') return actual === undefined || actual === null || actual === '' || actual === false;
+  return String(actual ?? '') === String(condition.value ?? '');
+}
+
+function assertParamsAgainstModel(promptParams = {}, params = [], constraints = []) {
+  const paramByKey = new Map(params.map((item) => [item.key, item]));
+  for (const key of providedPromptParamKeys(promptParams)) {
+    const param = paramByKey.get(key);
+    if (!param) {
+      throw argumentError(`模型不支持参数：${key}`, '请先运行 model options，只传 params[] 中暴露的参数。');
+    }
+    const value = promptParamValue(promptParams, key);
+    if (Array.isArray(param.values) && param.values.length && !param.values.map(String).includes(String(value))) {
+      throw argumentError(`参数 ${key} 不在模型允许值中：${value}`, `允许值：${param.values.join(', ')}。`);
+    }
+    if (param.maxLength != null && typeof value === 'string' && value.length > param.maxLength) {
+      throw argumentError(`参数 ${key} 超过模型长度限制：${value.length}/${param.maxLength}`);
+    }
+  }
+
+  for (const constraint of constraints) {
+    const conditions = Array.isArray(constraint.conditions) ? constraint.conditions : [];
+    if (!conditions.length || !conditions.every((condition) => constraintConditionMatches(condition, promptParams))) continue;
+    const target = constraint.target;
+    const value = promptParamValue(promptParams, target);
+    if (value === undefined || value === null || value === '') continue;
+    const allowedValues = Array.isArray(constraint.allowValues) ? constraint.allowValues : [];
+    if (!allowedValues.length) {
+      throw argumentError(`当前输入触发模型约束，不能传参数：${target}`, `约束：${constraint.name || constraint.targetConfigCode || target}。`);
+    }
+    if (!allowedValues.map(String).includes(String(value))) {
+      throw argumentError(`参数 ${target} 不满足当前输入触发的模型约束：${value}`, `允许值：${allowedValues.join(', ')}。`);
+    }
+  }
+}
+
+async function validateCreateRequestAgainstModel(kind, modelGroupCode, promptParams = {}, resourceDetails = []) {
+  const context = await loadModelOptionContext(modelGroupCode, { includeConstraintSchema: true });
+  if (context.taskKind !== kind) {
+    throw argumentError(`模型任务类型不匹配：${context.taskKind}`, `当前命令是 ${kind} create，请换用对应任务类型的模型。`);
+  }
+  const params = modelOptionParams(context.options, context.taskKind);
+  const resources = modelOptionsResources(context.inputModes);
+  assertParamsAgainstModel(promptParams, params, context.constraints);
+  assertResourceShapeAgainstModel(resourceDetails, resources);
+  assertResourceCountsAgainstModel(resourceDetails, resources);
+  if (kind === 'video') {
+    const supportedIntents = createSpecSupportedIntents(context.inputModes, context.taskKind);
+    const inputRequirement = createSpecInputRequirement(context.taskKind, context.inputModes, supportedIntents);
+    if (inputRequirement.visualInputRequired && !resourceDetails.length) {
+      throw argumentError('当前视频模型不能只传 prompt 创建', `必须选择一种受支持的素材输入：${inputRequirement.acceptedModes?.join(', ') || 'reference/frames/storyboard'}。`);
+    }
+  }
+  return { context, params, resourceRules: resources };
+}
+
+async function loadModelOptionContext(modelGroupCode, options = {}) {
+  const rawModel = await awbApi.fetchModelGroupInfoAll(modelGroupCode);
+  const rawOptions = normalizeRawModelOptions(rawModel, { includeRaw: options.includeRaw });
+  let configOptions = [];
+  if (rawModel?.modelCode) {
+    const optionsPayload = await fetchNormalizedModelOptions({
+      modelCode: rawModel.modelCode,
+      modelGroupCode,
+      selectedConfigs: options.selectedConfigs ?? {},
+      includeRaw: options.includeRaw,
+    });
+    configOptions = Array.isArray(optionsPayload.options) ? optionsPayload.options : [];
+  }
+  const mergedOptions = mergeModelParamRules(configOptions.length ? configOptions : rawOptions, rawModel);
+  const optionKeys = new Set(mergedOptions.map((item) => item.paramKey).filter(Boolean));
+  const taskKind = inferTaskKind(rawModel, optionKeys);
+  const rulesByKey = new Map(mergedOptions.map((item) => [item.paramKey, item.rules]).filter(([key, rules]) => key && rules));
+  const inputModes = createSpecInputModes(taskKind, optionKeys, rulesByKey);
+  const createParams = mergedOptions.map((option) => createParamForModelOption(option, taskKind));
+  const constraintSchema = options.includeConstraintSchema
+    ? await fetchModelConstraintSchema(rawModel, modelGroupCode)
+    : [];
+  return {
+    rawModel,
+    model: modelSummaryFromRaw(rawModel, modelGroupCode, taskKind),
+    options: mergedOptions,
+    constraintSchema,
+    constraints: normalizeModelConstraints(constraintSchema, taskKind),
+    optionKeys,
+    rulesByKey,
+    taskKind,
+    inputModes,
+    createParams,
+  };
+}
+
+function optionAllowedValues(option = {}) {
+  if (!Array.isArray(option.optionList)) return [];
+  return option.optionList
+    .filter((item) => item?.available !== false)
+    .map((item) => item?.enumValue ?? item?.value ?? item?.code ?? item?.id ?? item)
+    .filter((value) => value !== undefined && value !== null && value !== '');
+}
+
+function optionAllowedOptions(option = {}) {
+  if (!Array.isArray(option.optionList)) return [];
+  return option.optionList
+    .filter((item) => item?.available !== false)
+    .map((item) => compactRecord({
+      label: item?.enumName ?? item?.label ?? item?.name ?? item?.enumValue ?? item?.value ?? null,
+      value: item?.enumValue ?? item?.value ?? item?.code ?? item?.id ?? item,
+      rank: item?.rank,
+    }));
+}
+
+function arrayOrUndefined(value) {
+  return Array.isArray(value) && value.length ? value : undefined;
+}
+
+function ruleNumber(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function normalizeMediaRule(rule = {}) {
+  if (!rule || typeof rule !== 'object') return {};
+  return compactRecord({
+    mediaType: rule.mediaType,
+    fileTypes: arrayOrUndefined(rule.supportedFileTypes),
+    minFiles: ruleNumber(rule.minFrameNum ?? rule.minPromptNum),
+    maxFiles: ruleNumber(rule.fileListMaxNum ?? rule.maxFrameNum),
+    maxSizeKB: ruleNumber(rule.resourceFileMaxSize),
+    minDurationMs: ruleNumber(rule.minDuration),
+    maxDurationMs: ruleNumber(rule.maxDuration),
+    maxTotalDurationMs: ruleNumber(rule.maxTotalDuration),
+    minItems: ruleNumber(rule.minPromptNum),
+    maxItems: ruleNumber(rule.maxPromptNum),
+    maxPromptLength: ruleNumber(rule.maxPromptLength),
+    supportLastFrameOnly: rule.supportLastFrame,
+    required: rule.required,
+  });
+}
+
+function frameRuleCapabilities(rule = {}) {
+  const maxFrameNum = ruleNumber(rule.maxFrameNum ?? rule.fileListMaxNum);
+  const minFrameNum = ruleNumber(rule.minFrameNum ?? rule.fileListMinNum);
+  const supportLastFrameOnly = rule.supportLastFrame === true;
+  const supportsFirstFrame = maxFrameNum == null || maxFrameNum >= 1;
+  const supportsFirstLastFrame = maxFrameNum != null && maxFrameNum >= 2;
+  const usages = ['first_frame'];
+  if (supportsFirstLastFrame || supportLastFrameOnly) usages.push('last_frame');
+  return compactRecord({
+    minFrameNum,
+    maxFrameNum,
+    supportsFirstFrame,
+    supportsFirstLastFrame,
+    supportLastFrameOnly,
+    usages,
+  });
+}
+
+function mediaRuleFromMultiParam(rules = {}, mediaType) {
+  const resources = Array.isArray(rules?.resources) ? rules.resources : [];
+  const found = resources.find((item) => String(item?.mediaType || '').toUpperCase() === mediaType);
+  return found ? normalizeMediaRule(found) : {};
+}
+
+function mergeResourceLimits(base = {}, overrides = {}) {
+  return compactRecord({ ...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 raw = rawByKey.get(option.paramKey);
+    return {
+      ...option,
+      hasConstraint: option.hasConstraint ?? raw?.hasConstraint ?? null,
+      rules: option.rules ?? raw?.rules ?? null,
+    };
+  });
+}
+
+function createParamForModelOption(option = {}, taskKind = 'image') {
+  const key = option.paramKey;
+  const common = {
+    modelParamKey: key,
+    modelParamName: option.paramName ?? null,
+    modelParamType: option.paramType ?? null,
+    allowedValues: optionAllowedValues(option),
+    allowedOptions: optionAllowedOptions(option),
+  };
+  const definitions = {
+    prompt: {
+      key: 'prompt',
+      cliArg: '--prompt',
+      requestPath: 'promptParams.prompt',
+      materialLegacyKey: 'prompt',
+      meaning: taskKind === 'image' ? '用户提供的图片生成提示词文本。' : '用户提供的视频生成提示词文本。',
+      valueSource: '以用户明确的创作描述为 prompt 基底；CLI/Agent 负责资源占位符、key 对齐、转义清理和模型约束组装。需求不明确时先追问或使用最小中性表达，不主动编内容补空白。',
+    },
+    ratio: {
+      key: 'ratio',
+      cliArg: '--ratio',
+      requestPath: 'promptParams.ratio',
+      materialLegacyKey: 'ratio',
+      meaning: taskKind === 'image' ? '图片画幅比例。' : '视频画面比例。',
+      valueSource: '只能从 allowedValues 选择。',
+    },
+    quality: {
+      key: 'quality',
+      cliArg: '--quality',
+      requestPath: 'promptParams.quality',
+      materialLegacyKey: 'quality',
+      meaning: taskKind === 'image' ? '图片清晰度 / 分辨率档位。' : '视频清晰度 / 分辨率档位。',
+      valueSource: '只能从 allowedValues 选择。',
+    },
+    generate_num: {
+      key: 'generateNum',
+      cliArg: '--generate-num',
+      requestPath: 'promptParams.generate_num',
+      materialLegacyKey: 'generate_num',
+      meaning: '一次任务生成的图片张数。',
+      valueSource: '只能从 allowedValues 选择；CLI 会转成整数。',
+    },
+    generated_time: {
+      key: 'duration',
+      cliArg: '--duration',
+      requestPath: 'promptParams.duration',
+      materialLegacyKey: 'generated_time',
+      meaning: '视频生成时长，单位秒。',
+      valueSource: '只能从 allowedValues 选择；CLI 会转成整数。',
+    },
+    need_audio: {
+      key: 'needAudio',
+      cliArg: '--need-audio',
+      requestPath: 'promptParams.need_audio',
+      materialLegacyKey: 'need_audio',
+      meaning: '是否需要输出音效 / 模型生成音频。',
+      valueSource: '布尔值 true / false；仅模型配置存在该项且用户明确要求输出音效时使用。它不是上传音频文件的入口。',
+      controlKind: 'output_audio_toggle',
+    },
+    audio: {
+      key: 'needAudio',
+      cliArg: '--need-audio',
+      requestPath: 'promptParams.need_audio',
+      materialLegacyKey: 'audio',
+      meaning: '是否需要输出音效 / 模型生成音频。',
+      valueSource: '布尔值 true / false；仅模型配置存在该项且用户明确要求输出音效时使用。它不是上传音频文件的入口。',
+      controlKind: 'output_audio_toggle',
+    },
+    iref: {
+      key: 'resources',
+      cliArg: '--resource / --resources-json',
+      requestPath: 'promptParams.resources[]',
+      materialLegacyKey: 'iref',
+      meaning: '图片任务的参考图输入。',
+      valueSource: '本地文件、http(s) URL 或 material backendPath。',
+      resourceSyntax: ['image:reference=./ref.png'],
+    },
+    resources: {
+      key: 'resources',
+      cliArg: '--resource / --resources-json',
+      requestPath: 'promptParams.resources[]',
+      materialLegacyKey: 'resources',
+      meaning: '模型声明的素材输入；CLI 统一用 resources 表达。',
+      valueSource: '本地文件、http(s) URL 或 material backendPath。',
+      resourceSyntax: taskKind === 'image' ? ['image:reference=./ref.png'] : ['image:first_frame=./first.png'],
+    },
+    frames: {
+      key: 'resources',
+      cliArg: '--resource / --resources-json',
+      requestPath: 'promptParams.resources[]',
+      materialLegacyKey: 'frames',
+      meaning: '视频首帧 / 尾帧 / 关键帧输入。',
+      valueSource: '首帧/尾帧可用本地文件、http(s) URL、material 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: {
+      key: 'resources',
+      cliArg: '--resource / --resources-json',
+      requestPath: 'promptParams.resources[]',
+      materialLegacyKey: 'multi_param',
+      meaning: '参考模式输入；图片、视频、音频和主体都用 type=...、usage=reference 表达。',
+      valueSource: 'reference_key 是可选绑定。prompt 可以不写占位符；如果写了 <<<key>>>，必须能匹配同名 reference 资源。',
+      resourceSyntax: [
+        'image:reference=./hero.png',
+        'image:reference:hero=./hero.png',
+        'image:reference:hero=asset:<assetId>',
+        'video:reference=./motion.mp4',
+        'video:reference:motion=./motion.mp4',
+        'audio:reference=./music.mp3',
+        'audio:reference:voice=./voice.wav',
+        'subject:reference:hero=asset:<externalId>',
+      ],
+    },
+    multi_prompt: {
+      key: 'resources',
+      cliArg: '--resources-json',
+      requestPath: 'promptParams.resources[]',
+      materialLegacyKey: 'multi_prompt',
+      meaning: '多段提示 / 关键帧提示输入；仅模型配置存在该项时使用。',
+      valueSource: '使用 resources-json，在 keyframe resource 上携带 prompt / duration。',
+      resourceSyntax: ['[{"type":"image","usage":"keyframe","order":1,"prompt":"...","source":{"kind":"url","value":"./k1.png"}}]'],
+    },
+    generated_mode: {
+      key: 'generatedMode',
+      cliArg: null,
+      requestPath: null,
+      materialLegacyKey: 'generated_mode',
+      meaning: '平台旧参数的生成模式。Agent 不要手动传；CLI/Material 会根据 resources usage 推导 frames 或 multi_param。',
+      valueSource: '由资源类型推导，不是用户输入。',
+      internalOnly: true,
+    },
+  };
+  return {
+    ...(definitions[key] ?? {
+      key,
+      cliArg: null,
+      requestPath: null,
+      materialLegacyKey: key,
+      meaning: '模型配置存在该参数，但当前 CLI 没有暴露为稳定创建参数；不要为了调用而硬塞旧字段。',
+      valueSource: '如确实需要，先扩展 CLI 显式参数和 Material adapter。',
+      notExposedByCli: true,
+    }),
+    ...common,
+  };
+}
+
+function inferTaskKind(found, optionKeys) {
+  if (found?.kind) return found.kind;
+  if (found?.usage === 'IMAGE_CREATE') return 'image';
+  if (found?.usage === 'VIDEO_CREATE') return 'video';
+  return ['generated_time', 'frames', 'multi_param', 'multi_prompt', 'generated_mode', 'need_audio']
+    .some((key) => optionKeys.has(key)) ? 'video' : 'image';
+}
+
+function createSpecInputModes(taskKind, optionKeys, rulesByKey = new Map()) {
+  const hasPrompt = optionKeys.has('prompt');
+  const hasImageReference = ['iref', 'cref', 'sref', 'resources'].some((key) => optionKeys.has(key));
+  const hasFrames = optionKeys.has('frames');
+  const hasMultiParam = optionKeys.has('multi_param');
+  const hasMultiPrompt = optionKeys.has('multi_prompt');
+  const imageReferenceRules = rulesByKey.get('iref') || rulesByKey.get('cref') || rulesByKey.get('sref') || rulesByKey.get('resources') || {};
+  const framesRules = rulesByKey.get('frames') || {};
+  const multiParamRules = rulesByKey.get('multi_param') || {};
+  const multiPromptRules = rulesByKey.get('multi_prompt') || {};
+  const multiParamResources = Array.isArray(multiParamRules.resources) ? multiParamRules.resources : [];
+  const supportsMultiMedia = (mediaType) => {
+    if (!hasMultiParam) return false;
+    if (!multiParamResources.length) return true;
+    return multiParamResources.some((item) => String(item?.mediaType || '').toUpperCase() === mediaType);
+  };
+  const supportsMultiImage = supportsMultiMedia('IMAGE');
+  const supportsMultiVideo = supportsMultiMedia('VIDEO');
+  const supportsMultiAudio = supportsMultiMedia('AUDIO');
+  const frameCapabilities = frameRuleCapabilities(framesRules);
+  const frameOptionResourceLimits = normalizeMediaRule(framesRules);
+  const supportsFirstFrame = hasFrames && frameCapabilities.supportsFirstFrame !== false;
+  const supportsFirstLastFrame = hasFrames && frameCapabilities.supportsFirstLastFrame === true;
+  const supportLastFrameOnly = hasFrames && frameCapabilities.supportLastFrameOnly === true;
+  const frameMinFiles = frameOptionResourceLimits.minFiles ?? 0;
+  const framesRequired = hasFrames && (framesRules.required === true || frameMinFiles > 0);
+  const videoPromptOnlyBlocked = taskKind === 'video' && hasPrompt && (framesRequired || hasMultiParam || hasMultiPrompt);
+  const modes = [];
+  modes.push({
+    mode: 'prompt_only',
+    supported: taskKind === 'image' ? hasPrompt : hasPrompt && !videoPromptOnlyBlocked,
+    intent: taskKind === 'image' ? '文生图' : '文生视频',
+    requiredArgs: ['--model-group-code', '--prompt'],
+    userInput: '只提供 prompt，不提供参考素材。',
+    ...(videoPromptOnlyBlocked ? { unsupportedReason: '该视频模型配置要求在 reference、frames 或 storyboard 模式中选择一种素材输入，不能只传 prompt。' } : {}),
+  });
+  modes.push({
+    mode: 'reference_image',
+    supported: taskKind === 'image' ? hasImageReference : supportsMultiImage,
+    intent: taskKind === 'image' ? '参考图生图 / 图像编辑式生成' : '参考图生视频',
+    requiredArgs: taskKind === 'image'
+      ? ['--model-group-code', '--prompt', '--resource image:reference=...']
+      : ['--model-group-code', '--prompt', '--resource image:reference[:key]=...'],
+    userInput: taskKind === 'image' ? '用户提供参考图，希望生成或编辑图片。' : '用户提供参考图，希望参考图中主体、风格或构图生成视频。',
+    resourceSyntax: taskKind === 'image'
+      ? ['image:reference=./ref.png']
+      : ['image:reference:hero=./hero.png', 'image:reference:hero=asset:<assetId>'],
+    requiredResources: taskKind === 'image' ? ['image:reference'] : ['image:reference[:key]'],
+    sourceKinds: taskKind === 'image' ? ['local_file', 'http_url', 'backendPath'] : ['local_file', 'http_url', 'backendPath', 'asset_id'],
+    resourceLimits: taskKind === 'image' ? normalizeMediaRule(imageReferenceRules) : mediaRuleFromMultiParam(multiParamRules, 'IMAGE'),
+    promptBinding: taskKind === 'video' ? 'optional_key' : 'none',
+    promptPlaceholder: taskKind === 'video' ? 'reference_key 可选；prompt 中写了 <<<key>>> 时必须有同名 image reference。' : null,
+    resourceConstraints: taskKind === 'video' ? ['reference_key_optional', 'if_prompt_has_key_then_resource_must_exist'] : [],
+    ...((taskKind === 'image' ? !hasImageReference : !supportsMultiImage) ? { unsupportedReason: '模型配置没有对应参考图片资源参数。' } : {}),
+  });
+  if (taskKind === 'video') {
+    modes.push({
+      mode: 'reference_audio',
+      supported: supportsMultiAudio,
+      intent: '参考音频生视频',
+      requiredArgs: ['--model-group-code', '--prompt', '--resource audio:reference=...'],
+      userInput: '用户上传或提供音乐、声音、配音、节奏等音频，希望作为生成参考；这属于 resources 输入，不是 --need-audio。',
+      resourceSyntax: ['audio:reference=./music.mp3', 'audio:reference:voice=./voice.wav'],
+      requiredResources: ['audio:reference'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath', 'asset_id'],
+      resourceLimits: mediaRuleFromMultiParam(multiParamRules, 'AUDIO'),
+      promptBinding: 'optional_key',
+      promptPlaceholder: '普通音频参考可不写 key；当用户强调音频也要参考 / 显式绑定音频时，可用 audio:reference:<key> 并在 prompt 中包含同名 <<<key>>>。',
+      resourceConstraints: ['use_resource_not_need_audio', 'if_prompt_has_key_then_resource_must_exist'],
+      ...(!supportsMultiAudio ? { unsupportedReason: '模型配置没有音频参考资源规则。' } : {}),
+    });
+    modes.push({
+      mode: 'reference_video',
+      supported: supportsMultiVideo,
+      intent: '参考视频生视频',
+      requiredArgs: ['--model-group-code', '--prompt', '--resource video:reference[:key]=...'],
+      userInput: '用户提供参考视频，希望参考运动、节奏或镜头生成视频。',
+      resourceSyntax: ['video:reference:motion=./motion.mp4', 'video:reference:motion=asset:<assetId>'],
+      requiredResources: ['video:reference[:key]'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath', 'asset_id'],
+      resourceLimits: mediaRuleFromMultiParam(multiParamRules, 'VIDEO'),
+      promptBinding: 'optional_key',
+      promptPlaceholder: 'reference_key 可选；prompt 中写了 <<<key>>> 时必须有同名 video reference。',
+      resourceConstraints: ['reference_key_optional', 'if_prompt_has_key_then_resource_must_exist'],
+      ...(!supportsMultiVideo ? { unsupportedReason: '模型配置没有视频参考资源规则。' } : {}),
+    });
+    modes.push({
+      mode: 'first_frame',
+      supported: supportsFirstFrame,
+      intent: '首帧生视频',
+      requiredArgs: ['--model-group-code', '--resource image:first_frame=...'],
+      userInput: '用户提供起始画面，希望从这张图延展成视频。',
+      resourceSyntax: ['image:first_frame=./first.png', 'image:first_frame=asset:<assetId>'],
+      requiredResources: ['image:first_frame'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath', 'asset_id'],
+      resourceLimits: mergeResourceLimits(normalizeMediaRule(framesRules), { minFiles: 1, maxFiles: 1 }),
+      optionResourceLimits: frameOptionResourceLimits,
+      optionResourceUsages: frameCapabilities.usages,
+      promptBinding: 'none',
+      promptPlaceholder: '不需要 <<<key>>> 占位符。',
+      resourceConstraints: ['last_frame_not_required', 'key_not_used'],
+      supportLastFrameOnly,
+      ...(!hasFrames ? { unsupportedReason: '模型配置没有 frames 参数。' } : (!supportsFirstFrame ? { unsupportedReason: '模型配置 frames.maxFrameNum 小于 1。' } : {})),
+    });
+    modes.push({
+      mode: 'first_last_frame',
+      supported: supportsFirstLastFrame,
+      intent: '首尾帧过渡生视频',
+      requiredArgs: ['--model-group-code', '--resource image:first_frame=...', '--resource image:last_frame=...'],
+      userInput: '用户提供起始画面和结束画面，希望生成中间过渡视频。',
+      resourceSyntax: ['image:first_frame=./first.png', 'image:last_frame=./last.png', 'image:first_frame=asset:<assetId>', 'image:last_frame=asset:<assetId>'],
+      requiredResources: ['image:first_frame', 'image:last_frame'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath', 'asset_id'],
+      resourceLimits: mergeResourceLimits(normalizeMediaRule(framesRules), { minFiles: 2, maxFiles: 2 }),
+      optionResourceLimits: frameOptionResourceLimits,
+      optionResourceUsages: frameCapabilities.usages,
+      promptBinding: 'none',
+      promptPlaceholder: '不需要 <<<key>>> 占位符。',
+      resourceConstraints: ['both_first_and_last_required', 'key_not_used'],
+      supportLastFrameOnly,
+      ...(!hasFrames ? { unsupportedReason: '模型配置没有 frames 参数。' } : (!supportsFirstLastFrame ? { unsupportedReason: '模型配置 frames.maxFrameNum 小于 2。' } : {})),
+    });
+    modes.push({
+      mode: 'last_frame_only',
+      supported: supportLastFrameOnly,
+      intent: '仅尾帧生视频',
+      requiredArgs: ['--model-group-code', '--resource image:last_frame=...'],
+      userInput: '用户只提供结束画面，希望反向约束视频收束到该画面；这是少数模型才支持的特殊能力。',
+      resourceSyntax: ['image:last_frame=./last.png', 'image:last_frame=asset:<assetId>'],
+      requiredResources: ['image:last_frame'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath', 'asset_id'],
+      resourceLimits: mergeResourceLimits(normalizeMediaRule(framesRules), { minFiles: 1, maxFiles: 1 }),
+      optionResourceLimits: frameOptionResourceLimits,
+      optionResourceUsages: frameCapabilities.usages,
+      promptBinding: 'none',
+      promptPlaceholder: 'last_frame 不使用 reference_key；prompt 可选，用于补充动作、镜头或画面要求。',
+      resourceConstraints: ['last_frame_only_requires_supportLastFrameOnly', 'key_not_used'],
+      supportLastFrameOnly,
+      ...(!hasFrames ? { unsupportedReason: '模型配置没有 frames 参数。' } : (!supportLastFrameOnly ? { unsupportedReason: '模型配置未声明支持仅尾帧。' } : {})),
+    });
+    modes.push({
+      mode: 'subject_reference',
+      supported: supportsMultiImage,
+      intent: '可复用主体参考生视频',
+      requiredArgs: ['--model-group-code', '--prompt "<<<key>>> ..."', '--resource subject:reference:<key>=asset:<externalId>'],
+      userInput: '用户要长期复用同一个角色 / 主体，并希望 prompt 显式引用该主体。',
+      resourceSyntax: ['subject:reference:hero=asset:<externalId>'],
+      requiredResources: ['subject:reference:<key>=asset:<externalId>'],
+      sourceKinds: ['asset_id'],
+      resourceLimits: mediaRuleFromMultiParam(multiParamRules, 'IMAGE'),
+      promptBinding: 'optional_key',
+      promptPlaceholder: 'subject reference 必须带 reference_key；是否在 prompt 中写 <<<key>>> 由用户表达决定。',
+      resourceConstraints: ['external_id_from_subject_wait', 'reference_key_required_for_subject'],
+      ...(!supportsMultiImage ? { unsupportedReason: '模型配置没有图片 / 主体参考资源规则。' } : {}),
+    });
+    modes.push({
+      mode: 'storyboard',
+      supported: hasMultiPrompt,
+      intent: '故事板 / 多段关键帧生视频',
+      requiredArgs: ['--model-group-code', '--resources-json <keyframe[]>'],
+      userInput: '用户提供多段分镜，每段可包含 keyframe 图片、局部 prompt 和小数秒 duration。',
+      resourceSyntax: ['[{"type":"image","usage":"keyframe","order":1,"prompt":"...","duration":0.8,"source":{"kind":"url","value":"./k1.png"}}]'],
+      requiredResources: ['image:keyframe#<order>'],
+      sourceKinds: ['local_file', 'http_url', 'backendPath'],
+      resourceLimits: normalizeMediaRule(multiPromptRules),
+      promptBinding: 'none',
+      promptPlaceholder: '不需要 <<<key>>> 占位符；每段文案写在 keyframe.prompt。',
+      resourceConstraints: ['order_required_positive_integer', 'duration_allows_decimal_seconds', 'asset_id_not_supported'],
+      ...(!hasMultiPrompt ? { unsupportedReason: '模型配置没有 multi_prompt 参数。' } : {}),
+    });
+  }
+  return modes;
+}
+
+function createSpecSupportedIntents(inputModes, taskKind = null) {
+  const supported = (mode) => inputModes.find((item) => item.mode === mode && item.supported);
+  const referenceModes = ['reference_image', 'reference_audio', 'reference_video', 'subject_reference']
+    .map((mode) => supported(mode))
+    .filter(Boolean);
+  const firstFrame = supported('first_frame');
+  const firstLastFrame = supported('first_last_frame');
+  const lastFrameOnly = supported('last_frame_only');
+  const intents = [];
+  const promptOnly = supported('prompt_only');
+  if (promptOnly) {
+    intents.push(compactRecord({
+      mode: 'prompt_only',
+      intent: promptOnly.intent,
+      userInput: promptOnly.userInput,
+      requiredArgs: promptOnly.requiredArgs,
+      promptBinding: 'none',
+    }));
+  }
+  if (referenceModes.length) {
+    const referenceLabels = uniqueNonEmpty(referenceModes.map((item) => ({
+      reference_image: '图片',
+      reference_audio: '音频',
+      reference_video: '视频',
+      subject_reference: '主体',
+    }[item.mode])));
+    if (taskKind === 'image') {
+      intents.push(compactRecord({
+        mode: 'reference',
+        intent: '参考图生图',
+        userInput: '用户提供图片作为参考素材；图片任务不使用 reference_key 或 <<<key>>>，prompt 用图一、图二、参考图、主体等自然描述指代素材。',
+        requiredArgs: ['--model-group-code', '--prompt', '--resource image:reference=...'],
+        resourceUsages: ['reference'],
+        resourceSyntax: uniqueNonEmpty(referenceModes.flatMap((item) => item.resourceSyntax || [])),
+        promptBinding: 'none',
+        promptPlaceholder: '图片任务不使用 reference_key 或 <<<key>>>；在 prompt 中用自然语言指代参考图。',
+      }));
+    } else {
+      intents.push(compactRecord({
+        mode: 'reference',
+        intent: '参考模式',
+        userInput: `用户提供${referenceLabels.join('、')}作为参考素材；同一 reference_key 可聚合多条参考资源。`,
+        requiredArgs: ['--model-group-code', '--prompt', '--resource <type>:reference[:key]=...'],
+        resourceUsages: ['reference'],
+        resourceSyntax: uniqueNonEmpty(referenceModes.flatMap((item) => item.resourceSyntax || []).flatMap((syntax) => {
+          const text = String(syntax);
+          if (text.startsWith('image:reference:hero=')) return [text.replace('image:reference:hero=', 'image:reference='), text];
+          if (text.startsWith('video:reference:motion=')) return [text.replace('video:reference:motion=', 'video:reference='), text];
+          return [text];
+        })),
+        promptBinding: 'optional_key',
+        promptPlaceholder: 'reference_key 可选；prompt 可以不写占位符。如果 prompt 写了 <<<key>>>，必须能匹配同名 reference 资源。',
+      }));
+    }
+  }
+  if (firstFrame || firstLastFrame || lastFrameOnly) {
+    const resourceSyntax = uniqueNonEmpty([
+      ...(firstFrame?.resourceSyntax || []),
+      ...(firstLastFrame?.resourceSyntax || []),
+      ...(lastFrameOnly?.resourceSyntax || []),
+    ]);
+    const resourceUsages = uniqueNonEmpty([
+      ...(firstFrame ? ['first_frame'] : []),
+      ...(firstLastFrame || lastFrameOnly ? ['last_frame'] : []),
+    ]);
+    const userInputParts = uniqueNonEmpty([
+      firstFrame ? '可提供 first_frame 作为起始画面' : null,
+      firstLastFrame ? '可同时提供 first_frame + last_frame 表达起止画面' : null,
+      lastFrameOnly ? '也支持只提供 last_frame 作为结束画面约束' : null,
+    ]);
+    intents.push(compactRecord({
+      mode: 'frames',
+      intent: 'frames 模式',
+      userInput: `${userInputParts.join('；')}。`,
+      requiredArgs: firstFrame
+        ? ['--model-group-code', '--resource image:first_frame=...', ...(firstLastFrame ? ['[--resource image:last_frame=...]'] : [])]
+        : ['--model-group-code', '--resource image:last_frame=...'],
+      resourceUsages,
+      resourceSyntax,
+      promptBinding: 'none',
+      promptPlaceholder: 'first_frame / last_frame 不使用 reference_key；prompt 可选，用于补充动作、镜头或画面要求。',
+    }));
+  }
+  const storyboard = supported('storyboard');
+  if (storyboard) {
+    intents.push(compactRecord({
+      mode: 'storyboard',
+      intent: '多帧 / 故事板模式',
+      userInput: storyboard.userInput,
+      requiredArgs: storyboard.requiredArgs,
+      resourceUsages: ['keyframe'],
+      resourceSyntax: storyboard.resourceSyntax,
+      promptBinding: 'none',
+      promptPlaceholder: 'keyframe 不使用 reference_key；每帧可在 resources-json 中携带 prompt / duration。',
+    }));
+  }
+  return intents;
+}
+
+function createSpecResourceRequirements(inputModes) {
+  return inputModes
+    .filter((item) => item.supported && Array.isArray(item.resourceSyntax) && item.resourceSyntax.length)
+    .map((item) => compactRecord({
+      mode: item.mode,
+      intent: item.intent,
+      resource: item.requiredResources,
+      syntax: item.resourceSyntax,
+      sources: item.sourceKinds,
+      ...item.resourceLimits,
+      promptBinding: item.promptBinding,
+      constraints: item.resourceConstraints,
+    }));
+}
+
+function createSpecUnsupportedIntents(inputModes) {
+  return inputModes
+    .filter((item) => !item.supported)
+    .map((item) => compactRecord({
+      mode: item.mode,
+      intent: item.intent,
+      userInput: item.userInput,
+      reason: item.unsupportedReason,
+    }));
+}
+
+function createSpecInputRequirement(taskKind, inputModes, supportedIntents = createSpecSupportedIntents(inputModes, taskKind)) {
+  const supportedModes = supportedIntents.map((item) => item.mode);
+  const promptRequiredModes = supportedIntents
+    .filter((item) => (item.requiredArgs || []).some((arg) => String(arg).includes('--prompt')))
+    .map((item) => item.mode);
+  const promptOptionalModes = supportedIntents
+    .filter((item) => !(item.requiredArgs || []).some((arg) => String(arg).includes('--prompt')))
+    .map((item) => item.mode);
+  const promptOnly = inputModes.find((item) => item.mode === 'prompt_only');
+  const visualModes = supportedModes.filter((mode) => mode !== 'prompt_only');
+  const visualInputRequired = taskKind === 'video' && promptOnly && !promptOnly.supported && visualModes.length > 0;
+  const promptRequired = taskKind === 'image'
+    ? true
+    : supportedModes.length > 0 && promptRequiredModes.length === supportedModes.length;
+  return compactRecord({
+    promptRequired,
+    promptRequiredModes: arrayOrUndefined(promptRequiredModes),
+    promptOptionalModes: arrayOrUndefined(promptOptionalModes),
+    visualInputRequired,
+    summary: visualInputRequired
+      ? '必须选择 reference、frames 或 storyboard 中的一种视觉输入；不能只传 prompt 创建视频。'
+      : (taskKind === 'image' ? '至少需要 prompt；参考图按用户意图选择。' : '至少需要 prompt；是否需要素材取决于 selected input mode。'),
+    acceptedModes: supportedModes,
+    blockedModes: inputModes.filter((item) => !item.supported).map((item) => item.mode),
+  });
+}
+
+function resourceRequiredInModes(legacyKey, inputModes = []) {
+  const supportedModes = inputModes.filter((item) => item.supported);
+  return supportedModes
+    .filter((item) => {
+      const syntax = Array.isArray(item.resourceSyntax) ? item.resourceSyntax : [];
+      if (['iref', 'cref', 'sref', 'resources'].includes(legacyKey)) {
+        return item.mode === 'reference_image' && syntax.some((value) => String(value).startsWith('image:reference'));
+      }
+      if (legacyKey === 'frames') {
+        return syntax.some((value) => /image:(first_frame|last_frame)=/.test(String(value)));
+      }
+      if (legacyKey === 'multi_param') {
+        return syntax.some((value) => /^(image|video|audio|subject):reference/.test(String(value)));
+      }
+      if (legacyKey === 'multi_prompt') return item.mode === 'storyboard';
+      return false;
+    })
+    .map((item) => item.mode);
+}
+
+function createSpecParameterControls(createParams, inputModes = []) {
+  const userParams = createParams
+    .filter((item) => item.cliArg && item.key !== 'resources')
+    .map((item) => compactRecord({
+      key: item.key,
+      cliArg: item.cliArg,
+      meaning: item.meaning,
+      valueSource: item.valueSource,
+      controlKind: item.controlKind,
+      allowedValues: item.allowedValues,
+    }));
+  const resourceParams = createParams
+    .filter((item) => item.key === 'resources')
+    .map((item) => compactRecord({
+      legacyKey: item.materialLegacyKey,
+      meaning: item.meaning,
+      resourceSyntax: item.resourceSyntax,
+      requiredInModes: resourceRequiredInModes(item.materialLegacyKey, inputModes),
+      valueSource: item.valueSource,
+    }));
+  const hasAudioResource = resourceParams.some((item) => item.legacyKey === 'multi_param');
+  const hasGeneratedAudioToggle = userParams.some((item) => item.key === 'needAudio');
+  return compactRecord({
+    userParams,
+    resourceParams,
+    audioSemantics: {
+      uploadedAudioInput: hasAudioResource
+        ? '用户上传音频、音乐、配音、节奏参考时，使用 --resource audio:reference=... 或 resources-json 中 type=audio；不要用 --need-audio。'
+        : '当前模型规格没有 multi_param 资源通道，create-spec 未声明可上传音频参考资源。',
+      generatedAudioToggle: hasGeneratedAudioToggle
+        ? '该模型支持“是否需要输出音效”控制；命令层用 --need-audio true/false，不接收音频文件或 URL。'
+        : '当前模型没有暴露“是否需要输出音效”控制项；这不等价于不能使用音频参考资源。',
+    },
+    note: '这里只列当前模型明确暴露的 CLI 可控参数。不要主动把未列出的参数总结成“不支持”；只有用户明确要求对应控制时，才说明 create-spec 没有该参数。',
+  });
+}
+
+function createSpecAgentGuidance(taskKind, inputRequirement) {
+  const keyParamGuidance = taskKind === 'video'
+    ? 'fee 或 create --dry-run 前，必须先确认用户未提供的价格 / 效果关键参数：quality、duration、约束后仍可选的 ratio；needAudio 只在用户明确要输出音效时确认。不要静默使用 defaultValue 先估价。'
+    : 'fee 或 create --dry-run 前，必须先确认用户未提供的价格 / 效果关键参数：quality、ratio、generateNum。不要静默使用 defaultValue 先估价。';
+  const guidance = [
+    '先用 model options 获取枚举值、文件类型、数量、大小、时长和条件约束；create-spec 只负责创建方式。',
+    '用 inputRequirement 和 supportedIntents 在 prompt_only、reference、frames、storyboard 中选择一种输入模式；不要按媒体类型拆成多个任务。',
+  ];
+  if (taskKind === 'image') {
+    guidance.push('图片任务不使用 reference_key 或 <<<key>>>。参考图只用 --resource image:reference=... 传入，prompt 用“图一 / 图二 / 参考图 / 白发女 / 背景图”等自然语言指代。');
+  } else {
+    guidance.push('reference_key 是视频参考资源的可选绑定；prompt 可以不写占位符。如果 prompt 写了 <<<key>>>，必须能匹配同名 reference 资源。');
+    guidance.push('只有 model options.resources[] 存在 media=AUDIO usage=reference 时，音频文件 / URL / asset 才能走 --resource audio:reference=...；是否需要输出音效才使用 --need-audio true/false。');
+  }
+  guidance.push(
+    keyParamGuidance,
+    '费用确认优先使用 billingPointBalance / billingPointRemainingAfter，它来自 queryGroupPoint，表示实际可扣积分；projectBudgetBalance 只是项目组预算信息。',
+    'prompt 以用户明确文本为基底；不要为了引用素材而强行补 <<<key>>>。',
+  );
+  if (taskKind === 'video' && inputRequirement.visualInputRequired) {
+    guidance.push('该视频模型必须带视觉输入；创建前必须从 supportedIntents 中选择 reference、frames 或 storyboard。');
+  }
+  return guidance;
+}
+
+function createSpecValidationRules(taskKind) {
+  const rules = [
+    'ratio、quality、duration、generateNum 等参数值以 model options.params[].values 为准。',
+    '素材类型、文件格式、数量、大小和时长以 model options.resources[] 为准。',
+    '参数 / 资源联动限制以 model options.constraints[] 为准；触发 no_selectable_values 后不要传该目标参数。',
+    'prompt 以用户明确创作描述为基底；没有明确需求时先追问或使用最小中性表达，不主动编内容补空白。',
+    'fee 和 create --dry-run 前，先让用户选择或确认缺失的关键价格 / 效果参数；defaultValue 只能作为候选默认展示。',
+    'fee 输出中的 billingPointBalance 是实际可扣积分余额；projectBudgetBalance 是项目组预算余额，不要混用。',
+    '用户确认关键参数后先运行 fee，再运行 create --dry-run，给用户确认后才追加 --yes。',
+  ];
+  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。');
+  } else {
+    rules.push('图片任务 resources 只接受 image reference，且不接受 reference_key 或 <<<key>>>；请用自然 prompt 描述图一、图二、参考图、主体等映射。');
+  }
+  return rules;
+}
+
+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';
+  return [
+    'doctor --verify',
+    `${modelListCommand} --model <keyword>`,
+    'model options --model-group-code <code>',
+    'model create-spec --model-group-code <code>',
+    '按 options 的约束和 create-spec 的 supportedIntents 组装参数',
+    '向用户确认缺失的关键参数候选值',
+    feeCommand,
+    `${createCommand} --dry-run`,
+    '向用户确认模型、项目组、最终 prompt 文本、素材、关键参数、预估积分、可扣积分余额和项目组预算',
+    `${createCommand} --yes`,
+  ];
+}
+
+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');
+  } else {
+    if (hasIntent('prompt_only')) examples.push('lj-awb video create --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');
+      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');
+      }
+    }
+    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');
+      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');
+      }
+    }
+    if (hasIntent('storyboard')) examples.push('lj-awb video create --model-group-code <code> --resources-json ./storyboard.json --duration 5 --dry-run');
+  }
+  return examples;
+}
+
+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';
+  return option.paramType || undefined;
+}
+
+function modelOptionParams(options = [], taskKind = 'image') {
+  return options
+    .map((option) => ({ option, createParam: createParamForModelOption(option, taskKind) }))
+    .filter(({ createParam }) => createParam.cliArg && createParam.key !== 'resources' && !createParam.internalOnly)
+    .map(({ option, createParam }) => {
+      const rules = option.rules || {};
+      const allowedValues = optionAllowedValues(option);
+      const required = option.required === true || rules.required === true ? true : undefined;
+      const maxLength = option.paramType === 'Prompt'
+        ? ruleNumber(rules.maxValue ?? rules.maxLength ?? rules.maxPromptLength)
+        : undefined;
+      return compactRecord({
+        key: createParam.key,
+        label: option.paramName,
+        valueType: cliValueType(option, allowedValues),
+        values: allowedValues.length ? allowedValues : undefined,
+        defaultValue: rules.defaultValue,
+        defaultName: rules.defaultName,
+        maxLength,
+        required,
+      });
+    });
+}
+
+function optionResourceMedia(mode) {
+  if (mode === 'reference_audio') return 'AUDIO';
+  if (mode === 'reference_video') return 'VIDEO';
+  if (mode === 'subject_reference') return 'SUBJECT';
+  return 'IMAGE';
+}
+
+function optionResourceUsage(mode) {
+  if (mode === 'first_frame') return 'first_frame';
+  if (mode === 'first_last_frame') return ['first_frame', 'last_frame'];
+  if (mode === 'last_frame_only') return 'last_frame';
+  if (mode === 'storyboard') return 'keyframe';
+  return 'reference';
+}
+
+function optionResourceMode(mode) {
+  if (['reference_image', 'reference_audio', 'reference_video', 'subject_reference'].includes(mode)) return 'reference';
+  if (['first_frame', 'first_last_frame', 'last_frame_only'].includes(mode)) return 'frames';
+  if (mode === 'storyboard') return 'storyboard';
+  return mode;
+}
+
+function modelOptionsResources(inputModes = []) {
+  const resources = [];
+  const frameModes = inputModes.filter((item) => ['first_frame', 'first_last_frame', 'last_frame_only'].includes(item.mode));
+  const supportedFrameMode = frameModes.find((item) => item.supported);
+  let frameResourcePushed = false;
+  for (const item of createSpecResourceRequirements(inputModes)) {
+    const sourceMode = item.mode;
+    if (['first_frame', 'first_last_frame', 'last_frame_only'].includes(sourceMode)) {
+      if (!frameResourcePushed && supportedFrameMode) {
+        const framePolicy = imageFormatPolicy(supportedFrameMode.optionResourceLimits?.fileTypes);
+        resources.push(compactRecord({
+          mode: 'frames',
+          mediaType: 'IMAGE',
+          usage: supportedFrameMode.optionResourceUsages,
+          sources: supportedFrameMode.sourceKinds,
+          ...supportedFrameMode.optionResourceLimits,
+          formatPolicy: framePolicy.summary,
+          webpSupported: framePolicy.webpSupported,
+          autoConvertTo: framePolicy.autoConvertTo,
+          supportLastFrameOnly: supportedFrameMode.supportLastFrameOnly,
+        }));
+        frameResourcePushed = true;
+      }
+      continue;
+    }
+    const mediaType = optionResourceMedia(sourceMode);
+    const imagePolicy = mediaType === 'IMAGE' ? imageFormatPolicy(item.fileTypes) : null;
+    resources.push(compactRecord({
+      mode: optionResourceMode(sourceMode),
+      mediaType,
+      usage: optionResourceUsage(sourceMode),
+      sources: item.sources,
+      fileTypes: sourceMode === 'subject_reference' ? undefined : item.fileTypes,
+      formatPolicy: imagePolicy?.summary,
+      webpSupported: imagePolicy?.webpSupported,
+      autoConvertTo: imagePolicy?.autoConvertTo,
+      minFiles: sourceMode === 'subject_reference' ? undefined : item.minFiles,
+      maxFiles: sourceMode === 'subject_reference' ? undefined : item.maxFiles,
+      maxSizeKB: sourceMode === 'subject_reference' ? undefined : item.maxSizeKB,
+      minDurationMs: sourceMode === 'subject_reference' ? undefined : item.minDurationMs,
+      maxDurationMs: sourceMode === 'subject_reference' ? undefined : item.maxDurationMs,
+      maxTotalDurationMs: sourceMode === 'subject_reference' ? undefined : item.maxTotalDurationMs,
+      minItems: item.minItems,
+      maxItems: item.maxItems,
+      maxPromptLength: item.maxPromptLength,
+      supportLastFrameOnly: item.supportLastFrameOnly,
+    }));
+  }
+  return resources;
+}
+
+export function modelInputGuide() {
+  return {
+    schemaVersion: 1,
+    commonFields: [
+      { field: 'prompt', description: '提示词，描述希望生成什么。' },
+      { field: 'quality', description: '清晰度 / 尺寸档位。' },
+      { field: 'ratio', description: '宽高比，例如 16:9、9:16、1:1。' },
+      { field: 'duration', description: '视频时长，单位秒。' },
+      { field: 'generate_num', description: '一次生成几张图。' },
+      { field: 'need_audio', description: '是否生成音频 / 音效；仅部分视频模型支持。' },
+      { field: 'prompt_optimizer', description: '是否开启提示词增强；不传等同 false。' },
+      { field: 'resources', description: '输入素材列表，例如首帧、尾帧、参考图、关键帧、参考视频、参考音频。' },
+      { field: 'subject', description: '主体创建输入，仅主体创建专用接口使用。' },
+    ],
+    resourceFields: [
+      { 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.value', description: '资源值，必填。url 传素材地址；asset_id 传资源 ID。' },
+      { field: 'resources[].order', description: '仅 usage=keyframe 时需要，且同一请求内不能重复。' },
+      { field: 'resources[].duration', description: '仅 keyframe 场景下用于表达该帧持续时长，可传小数秒。' },
+      { field: 'resources[].prompt', description: '仅 keyframe 场景下可为该帧补充说明。' },
+    ],
+    resourceRules: [
+      '同一请求里最多只能有 1 个 first_frame。',
+      '同一请求里最多只能有 1 个 last_frame；默认必须和 first_frame 成对使用，只有模型声明 supportLastFrameOnly=true 时才可仅传 last_frame。',
+      '图片生图的 image:reference 不使用 reference_key 或 <<<key>>>；在 prompt 中用图一、图二、参考图、主体等自然语言描述资源映射。',
+      '视频 reference prompt 中可以不写 <<<reference_key>>>；如果写了，必须能匹配某个 reference 素材的 reference_key。',
+      '视频 reference 同一个 reference_key 可以对应多条 image / video / audio / subject 参考资源，系统会按 provider 规则聚合后提交。',
+      'type=subject 只支持 usage=reference，且必须传 reference_key。',
+      'first_frame / last_frame / keyframe 不需要、也不使用 reference_key。',
+    ],
+    referenceKeyGuide: [
+      '图片生图没有 reference_key 概念；多张参考图按资源顺序和 prompt 中“图一 / 图二 / 参考图 / 背景图”等自然描述理解。',
+      '视频普通参考图 / 参考视频 / 参考音频可以不传 reference_key。',
+      '视频里需要在 prompt 中用 <<<hero>>> 明确指代素材时，再传 reference_key=hero。',
+      '视频同一个主体可以由多条资源组成，例如形象图、动作视频、音频都使用 reference_key=hero。',
+      '视频里不需要被 prompt 占位符引用的普通场景参考，继续使用 type=image / video / audio + usage=reference。',
+    ],
+  };
+}
+
+export async function modelOptions(kwargs = {}) {
+  const modelGroupCode = trimToNull(kwargs.modelGroupCode);
+  if (!modelGroupCode) {
+    throw argumentError('缺少模型组编码', '传 --model-group-code <code>。');
+  }
+  const selectedConfigs = parseJsonArg(kwargs.selectedConfigsJson, {}) ?? {};
+  const includeRaw = toBool(kwargs.includeRaw);
+  const context = await loadModelOptionContext(modelGroupCode, { selectedConfigs, includeRaw, includeConstraintSchema: true });
+  return compactRecord({
+    schemaVersion: 1,
+    modelGroupCode,
+    selectedConfigs,
+    taskKind: context.taskKind,
+    model: context.model,
+    params: modelOptionParams(context.options, context.taskKind),
+    resources: modelOptionsResources(context.inputModes),
+    constraints: context.constraints,
+    ...(includeRaw ? { options: context.options, constraintSchema: context.constraintSchema, rawModel: context.rawModel } : {}),
+  });
+}
+
+export async function modelCreateSpec(kwargs = {}) {
+  const modelGroupCode = trimToNull(kwargs.modelGroupCode);
+  if (!modelGroupCode) {
+    throw argumentError('缺少模型组编码', '传 --model-group-code <code>。');
+  }
+  const includeRaw = toBool(kwargs.includeRaw);
+  const context = await loadModelOptionContext(modelGroupCode, { includeRaw });
+  const supportedIntents = createSpecSupportedIntents(context.inputModes, context.taskKind);
+  const inputRequirement = createSpecInputRequirement(context.taskKind, context.inputModes, supportedIntents);
+  return compactRecord({
+    schemaVersion: 1,
+    modelGroupCode,
+    taskKind: context.taskKind,
+    createCommand: context.taskKind === 'image' ? 'image create' : 'video create',
+    feeCommand: context.taskKind === 'image' ? 'image fee' : 'video fee',
+    statusCommandTaskType: context.taskKind === 'image' ? 'IMAGE_CREATE' : 'VIDEO_GROUP',
+    optionsCommand: `model options --model-group-code ${modelGroupCode}`,
+    model: context.model,
+    inputRequirement,
+    supportedIntents,
+    validationRules: createSpecValidationRules(context.taskKind),
+    agentGuidance: createSpecAgentGuidance(context.taskKind, inputRequirement),
+    preflight: createSpecPreflight(context.taskKind),
+    examples: createSpecExamples(context.taskKind, supportedIntents),
+    ...(includeRaw ? { options: context.options, rawModel: context.rawModel } : {}),
+  });
+}
+
+async function readJsonMaybeFile(value, fallback) {
+  const text = trimToNull(value);
+  if (!text) return fallback;
+  if (text.startsWith('{') || text.startsWith('[')) return parseJsonArg(text, fallback);
+  const fileText = await fs.readFile(path.resolve(text), 'utf8');
+  return JSON.parse(fileText);
+}
+
+async function collectFileSpecs(kwargs = {}, defaultSceneType = TASK_UPLOAD_SCENE.DEFAULT) {
+  const specs = [];
+  for (const file of parseListArg(kwargs.file)) specs.push({ file });
+  for (const file of parseListArg(kwargs.files)) specs.push({ file });
+  const filesJson = await readJsonMaybeFile(kwargs.filesJson, null).catch((error) => {
+    throw argumentError(`files-json 解析失败：${error.message}`);
+  });
+  if (Array.isArray(filesJson)) {
+    for (const item of filesJson) {
+      specs.push(typeof item === 'string' ? { file: item } : item);
+    }
+  }
+  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) ?? '',
+    }))
+    .filter((item) => item.file);
+}
+
+function dryRunBackendPath(filePath, sceneType) {
+  return `/${sceneType}/__dry_run__/${safeFileName(filePath)}`;
+}
+
+export async function uploadFilesCommand(kwargs = {}) {
+  const specs = await collectFileSpecs(kwargs, trimToNull(kwargs.sceneType) ?? TASK_UPLOAD_SCENE.DEFAULT);
+  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 ?? TASK_UPLOAD_SCENE.DEFAULT;
+  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 resolveCustomBizId(explicit) {
+  return trimToNull(explicit);
+}
+
+const RESOURCE_OBJECT_KEYS = new Set(['type', 'usage', 'reference_key', 'source', 'order', 'prompt', 'duration']);
+const RESOURCE_SOURCE_KEYS = new Set(['kind', 'value']);
+const RESOURCE_TYPES = new Set(['image', 'video', 'audio', 'subject']);
+const RESOURCE_USAGES = new Set(['reference', 'first_frame', 'last_frame', 'keyframe']);
+
+function parseIntegerParam(value, name, minValue) {
+  if (value == null || value === '') return null;
+  const text = String(value).trim();
+  if (!/^[+-]?\d+$/.test(text)) {
+    throw argumentError(`${name} 必须是整数`);
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed)) {
+    throw argumentError(`${name} 超出安全整数范围`);
+  }
+  if (parsed < minValue) {
+    throw argumentError(`${name} 必须是${minValue === 0 ? '非负整数' : '正整数'}`);
+  }
+  return parsed;
+}
+
+function normalizeUnifiedPromptParams(promptParams) {
+  if (promptParams.duration != null && promptParams.duration !== '') {
+    promptParams.duration = parseIntegerParam(promptParams.duration, 'promptParams.duration', 0);
+  }
+  if (promptParams.generate_num != null && promptParams.generate_num !== '') {
+    promptParams.generate_num = parseIntegerParam(promptParams.generate_num, 'promptParams.generate_num', 1);
+  }
+  if (promptParams.need_audio != null && promptParams.need_audio !== '') {
+    promptParams.need_audio = toBool(promptParams.need_audio);
+  }
+  return promptParams;
+}
+
+function normalizeResourceType(type, index) {
+  const normalized = String(type ?? '').trim().toLowerCase();
+  if (!RESOURCE_TYPES.has(normalized)) {
+    throw argumentError(`resource[${index}] type 不支持：${type}`, '支持 image、video、audio、subject。');
+  }
+  return normalized;
+}
+
+function normalizeResourceUsage(usage, index) {
+  const normalized = String(usage ?? '').trim().toLowerCase();
+  if (!RESOURCE_USAGES.has(normalized)) {
+    throw argumentError(`resource[${index}] usage 不支持：${usage}`, '支持 reference、first_frame、last_frame、keyframe。');
+  }
+  return normalized;
+}
+
+function stripAssetPrefix(value) {
+  const text = trimToNull(value);
+  if (!text) return null;
+  return text.startsWith('asset:') ? text.slice('asset:'.length) : text;
+}
+
+function normalizeResourceSource(source, type, index, options = {}) {
+  const explicitKind = trimToNull(source.source?.kind);
+  const rawValue = trimToNull(source.source?.value ?? (options.allowShortcutValue ? source.value : null));
+  if (!options.allowShortcutValue && !explicitKind) {
+    throw argumentError(`resource[${index}] source.kind 不能为空`);
+  }
+  const assetValue = stripAssetPrefix(rawValue);
+  const kind = explicitKind
+    ? 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。');
+  }
+  const value = kind === 'asset_id' ? assetValue : rawValue;
+  if (!value) {
+    throw argumentError(`resource[${index}] source.value 不能为空`);
+  }
+  return { kind, value };
+}
+
+function parseResourceShortcut(input, index) {
+  const text = String(input ?? '').trim();
+  const eqIndex = text.indexOf('=');
+  if (!text || eqIndex <= 0) {
+    throw argumentError(
+      `resource[${index}] 格式错误`,
+      '格式：--resource image:reference=./ref.png，或 --resource image:first_frame=material/a.png。',
+    );
+  }
+  const left = text.slice(0, eqIndex).trim();
+  const value = text.slice(eqIndex + 1).trim();
+  const parts = left.split(':').map((item) => item.trim()).filter(Boolean);
+  if (parts.length < 2 || parts.length > 3) {
+    throw argumentError(`resource[${index}] 格式错误`, '格式：type:usage[:key]=value。');
+  }
+  const usageMatch = parts[1].match(/^([A-Za-z_]+)(?:#([0-9]+))?$/);
+  if (!usageMatch) {
+    throw argumentError(`resource[${index}] usage 格式错误`);
+  }
+  return {
+    type: parts[0],
+    usage: usageMatch[1],
+    key: parts[2] || null,
+    value,
+    order: usageMatch[2] ? Number.parseInt(usageMatch[2], 10) : undefined,
+  };
+}
+
+function normalizeResourceObject(item, index) {
+  const isShortcut = typeof item === 'string';
+  const source = isShortcut ? parseResourceShortcut(item, index) : item;
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    throw argumentError(`resource[${index}] 必须是字符串短语法或 JSON 对象`);
+  }
+  if (!isShortcut) assertAllowedResourceObjectKeys(source, index);
+  const type = normalizeResourceType(source.type, index);
+  const usage = normalizeResourceUsage(source.usage, index);
+  const resourceSource = normalizeResourceSource(source, type, index, { allowShortcutValue: isShortcut });
+  const referenceKey = trimToNull(source.reference_key ?? (isShortcut ? source.key : null));
+  const duration = normalizeResourceDuration(source.duration, index);
+  const normalized = {
+    type,
+    usage,
+    ...(referenceKey ? { reference_key: referenceKey } : {}),
+    ...(source.order != null ? { order: Number(source.order) } : {}),
+    ...(trimToNull(source.prompt) ? { prompt: trimToNull(source.prompt) } : {}),
+    ...(duration != null ? { duration } : {}),
+    _source: resourceSource,
+  };
+  if (usage !== 'reference' && referenceKey) {
+    throw argumentError(`resource[${index}] reference_key 只能用于 usage=reference`);
+  }
+  if (usage !== 'keyframe' && normalized.order != null) {
+    throw argumentError(`resource[${index}] order 只能用于 usage=keyframe`);
+  }
+  if (usage !== 'keyframe' && duration != null) {
+    throw argumentError(`resource[${index}] duration 只能用于 usage=keyframe`);
+  }
+  if (usage !== 'keyframe' && normalized.prompt) {
+    throw argumentError(`resource[${index}] prompt 只能用于 usage=keyframe`);
+  }
+  if (usage === 'keyframe' && resourceSource.kind === 'asset_id') {
+    throw argumentError(`resource[${index}] keyframe 暂只支持 url，本地文件会自动上传为 url`);
+  }
+  if (type === 'subject' && usage !== 'reference') {
+    throw argumentError(`resource[${index}] type=subject 只能用于 usage=reference`);
+  }
+  if (type === 'subject' && !referenceKey) {
+    throw argumentError(`resource[${index}] type=subject 时 reference_key 不能为空`);
+  }
+  if (type === 'subject' && resourceSource.kind !== 'asset_id') {
+    throw argumentError(`resource[${index}] type=subject 时 source.kind 必须为 asset_id`);
+  }
+  if (usage === 'keyframe') {
+    if (!Number.isInteger(normalized.order) || normalized.order <= 0) {
+      throw argumentError(`resource[${index}] keyframe 必须使用正整数 order，例如 image:keyframe#1=./k1.png`);
+    }
+    if (duration != null && duration < 0) {
+      throw argumentError(`resource[${index}] keyframe duration 不能为负数`);
+    }
+  }
+  return normalized;
+}
+
+function assertAllowedResourceObjectKeys(source, index) {
+  for (const key of Object.keys(source)) {
+    if (!RESOURCE_OBJECT_KEYS.has(key)) {
+      throw argumentError(
+        `resource[${index}] JSON 对象存在未知字段：${key}`,
+        'JSON 素材只接受 type、usage、reference_key、source、order、prompt、duration。',
+      );
+    }
+  }
+  if (source.source != null) {
+    if (!source.source || typeof source.source !== 'object' || Array.isArray(source.source)) {
+      throw argumentError(`resource[${index}] source 必须是 JSON 对象`);
+    }
+    for (const key of Object.keys(source.source)) {
+      if (!RESOURCE_SOURCE_KEYS.has(key)) {
+        throw argumentError(
+          `resource[${index}] source 存在未知字段：${key}`,
+          'source 只接受 kind、value。',
+        );
+      }
+    }
+  }
+}
+
+function normalizeResourceDuration(value, index) {
+  if (value == null || value === '') return null;
+  const duration = Number(value);
+  if (!Number.isFinite(duration)) {
+    throw argumentError(`resource[${index}] duration 必须是数字`);
+  }
+  return duration;
+}
+
+async function collectResourceSpecs(kwargs = {}, options = {}) {
+  const items = [];
+  for (const item of parseListArg(kwargs.resource)) items.push(item);
+  if (Array.isArray(kwargs.resources)) items.push(...kwargs.resources);
+  const resourcesJson = await readJsonMaybeFile(kwargs.resourcesJson, null).catch((error) => {
+    throw argumentError(`resources-json 解析失败：${error.message}`);
+  });
+  if (Array.isArray(resourcesJson)) items.push(...resourcesJson);
+  return items.map((item, index) => normalizeResourceObject(item, index)).filter((item) => {
+    if (options.kind !== 'image') return true;
+    if (item.type !== 'image') {
+      throw argumentError('图片任务 resource 只支持 type=image');
+    }
+    if (item.usage !== 'reference') {
+      throw argumentError('图片任务 resource 只支持 usage=reference');
+    }
+    if (item.reference_key) {
+      throw argumentError(
+        '图片任务 reference 不支持 reference_key',
+        '生图参考图不会按 <<<key>>> 绑定；请使用 image:reference=...，并在 prompt 中用“图一 / 图二 / 参考图 / 主体”等自然语言指代。',
+      );
+    }
+    if (item._source.kind !== 'url') {
+      throw argumentError('图片任务 resource 暂只支持 url，本地文件会自动上传为 url');
+    }
+    return true;
+  });
+}
+
+function isRemoteOrBackendPath(value) {
+  const text = trimToNull(value);
+  if (!text) return false;
+  return /^https?:\/\//i.test(text)
+    || /^[a-z][a-z0-9+.-]*:\/\//i.test(text)
+    || text.startsWith('material/')
+    || text.startsWith('/material/');
+}
+
+function normalizeMaterialUrlValue(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;
+    } catch {}
+  }
+  return text;
+}
+
+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');
+    return {
+      resource: {
+        type: resource.type,
+        usage: resource.usage,
+        ...(resource.reference_key ? { reference_key: resource.reference_key } : {}),
+        source: resource._source,
+      },
+      upload: null,
+      localFile: null,
+    };
+  }
+  const base = {
+    type: resource.type,
+    usage: resource.usage,
+    ...(resource.reference_key ? { reference_key: resource.reference_key } : {}),
+    ...(resource.order ? { order: resource.order } : {}),
+    ...(resource.prompt ? { prompt: resource.prompt } : {}),
+    ...(resource.duration != null ? { duration: resource.duration } : {}),
+  };
+  if (resource._source.kind === 'asset_id') {
+    return { resource: { ...base, source: resource._source }, upload: null, localFile: null };
+  }
+  const value = resource._source.value;
+  if (isRemoteOrBackendPath(value)) {
+    return { resource: { ...base, source: { kind: 'url', value: normalizeMaterialUrlValue(value) } }, upload: null, localFile: null };
+  }
+  const inspected = await inspectLocalFile(value);
+  if (!inspected.exists) {
+    throw argumentError(
+      `资源文件不存在：${value}`,
+      'source.kind=url 只接受完整 http(s) URL、material backendPath，或当前工作目录下存在的本地文件路径。',
+    );
+  }
+  const conversion = options.resourceRules
+    ? resourceFormatConversion(
+      options.resourceRules.find((item) => resourceRuleMatches(item, { ...base, source: { kind: 'url', value } })),
+      { resource: { ...base, source: { kind: 'url', value } }, localFile: inspected },
+    )
+    : null;
+  if (conversion) {
+    const conversionRecord = compactRecord({
+      resource: resourceText(base),
+      fromFormat: conversion.fromFormat,
+      toFormat: conversion.toFormat,
+      reason: conversion.reason,
+      sourceFile: inspected.filePath,
+      dryRun: options.dryRun || undefined,
+    });
+    if (options.dryRun) {
+      const convertedName = `${path.basename(inspected.filePath, path.extname(inspected.filePath))}.${conversionOutputExtension(conversion.toFormat)}`;
+      return {
+        resource: { ...base, source: { kind: 'url', value: dryRunBackendPath(convertedName, options.sceneType) } },
+        upload: null,
+        localFile: inspected,
+        conversion: conversionRecord,
+      };
+    }
+    const converted = await convertLocalImageFile(inspected.filePath, conversion.toFormat);
+    try {
+      const upload = await uploadLocalFile(converted.filePath, { sceneType: options.sceneType });
+      return {
+        resource: { ...base, source: { kind: 'url', value: upload.backendPath } },
+        upload,
+        localFile: inspected,
+        conversion: {
+          ...conversionRecord,
+          convertedFile: converted.filePath,
+          convertedSize: converted.size,
+        },
+      };
+    } finally {
+      await fs.rm(converted.filePath, { force: true }).catch(() => {});
+    }
+  }
+  if (options.dryRun) {
+    return {
+      resource: { ...base, source: { kind: 'url', value: dryRunBackendPath(inspected.filePath, options.sceneType) } },
+      upload: null,
+      localFile: inspected,
+    };
+  }
+  const upload = await uploadLocalFile(inspected.filePath, { sceneType: options.sceneType });
+  return {
+    resource: { ...base, source: { kind: 'url', value: upload.backendPath } },
+    upload,
+    localFile: inspected,
+  };
+}
+
+async function resolveResources(kwargs = {}, options = {}) {
+  const specs = await collectResourceSpecs(kwargs, options);
+  const resources = [];
+  const uploads = [];
+  const localFiles = [];
+  const resourceDetails = [];
+  const resourceConversions = [];
+  for (const spec of specs) {
+    const resolved = await resolveResourceFileValue(spec, options);
+    resources.push(resolved.resource);
+    if (resolved.upload) uploads.push(resolved.upload);
+    if (resolved.localFile) localFiles.push(resolved.localFile);
+    if (resolved.conversion) resourceConversions.push(resolved.conversion);
+    resourceDetails.push({
+      resource: resolved.resource,
+      upload: resolved.upload,
+      localFile: resolved.localFile,
+    });
+  }
+  return { resources, uploads, localFiles, resourceDetails, resourceConversions };
+}
+
+function extractPromptReferenceKeys(prompt) {
+  const keys = new Set();
+  const matcher = /<<<([^<>\s]+)>>>/g;
+  const text = String(prompt ?? '');
+  let match;
+  while ((match = matcher.exec(text)) !== null) {
+    keys.add(match[1]);
+  }
+  return keys;
+}
+
+function assertVideoReferenceKeysUsed(prompt, resources = []) {
+  const declaredKeys = new Set(resources
+    .filter((resource) => resource?.usage === 'reference' && trimToNull(resource.reference_key))
+    .map((resource) => trimToNull(resource.reference_key)));
+  const promptKeys = extractPromptReferenceKeys(prompt);
+  for (const key of promptKeys) {
+    if (!declaredKeys.has(key)) {
+      throw argumentError(`prompt 引用了未声明的资源占位符：<<<${key}>>>`);
+    }
+  }
+}
+
+async function buildImageRequest(kwargs = {}, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const model = resolveTaskModel('image', kwargs);
+  const prompt = trimToNull(kwargs.prompt) ?? '';
+  if (!prompt) {
+    throw argumentError('缺少生图 prompt', '传 --prompt "..."。');
+  }
+  const promptReferenceKeys = extractPromptReferenceKeys(prompt);
+  if (promptReferenceKeys.size) {
+    throw argumentError(
+      '图片任务 prompt 不支持 <<<key>>> 资源占位符',
+      '生图参考图没有 reference_key 绑定概念；请改用自然描述，例如“图一中的白发女在图二背景里坐秋千”。',
+    );
+  }
+  const validationResources = await resolveResources(kwargs, {
+    dryRun: true,
+    kind: 'image',
+    sceneType: TASK_UPLOAD_SCENE.IMAGE_CREATE,
+  });
+  const defaultParams = {
+    prompt,
+    resources: validationResources.resources,
+  };
+  if (kwargs.ratio != null && kwargs.ratio !== '') defaultParams.ratio = kwargs.ratio;
+  if (kwargs.quality != null && kwargs.quality !== '') defaultParams.quality = kwargs.quality;
+  if (kwargs.generateNum != null && kwargs.generateNum !== '') {
+    defaultParams.generate_num = parseIntegerParam(kwargs.generateNum, '--generate-num', 1);
+  }
+  const promptParams = normalizeUnifiedPromptParams(defaultParams);
+  const validation = await validateCreateRequestAgainstModel('image', model.modelGroupCode, promptParams, validationResources.resourceDetails);
+  const resolvedResources = await resolveResources(kwargs, {
+    dryRun,
+    kind: 'image',
+    sceneType: TASK_UPLOAD_SCENE.IMAGE_CREATE,
+    resourceRules: validation.resourceRules,
+  });
+  const requestPromptParams = normalizeUnifiedPromptParams({ ...defaultParams, resources: resolvedResources.resources });
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, { allowNull: dryRun, noNetwork: dryRun, noSave: dryRun });
+  const customBizId = options.includeCustomBizId === false ? null : resolveCustomBizId(kwargs.customBizId);
+  return {
+    model,
+    projectGroupNo,
+    uploads: resolvedResources.uploads,
+    localFiles: resolvedResources.localFiles,
+    resourceConversions: resolvedResources.resourceConversions,
+    request: {
+      requestSource: REQUEST_SOURCE_CLI,
+      modelGroupCode: model.modelGroupCode,
+      ...(customBizId ? { customBizId } : {}),
+      promptParams: requestPromptParams,
+      ...(projectGroupNo ? { projectGroupNo } : {}),
+    },
+  };
+}
+
+function extractPointCost(payload) {
+  if (typeof payload === 'number') return payload;
+  return toNumberOrNull(payload?.point ?? payload?.pointNo ?? payload?.cost ?? payload);
+}
+
+async function pointEstimate(pointCost, projectGroupNo) {
+  const snapshot = projectGroupNo ? await creditsBalance({ projectGroupNo }).catch(() => null) : null;
+  const normalizedPointCost = extractPointCost(pointCost);
+  const billingPointBalance = toNumberOrNull(snapshot?.billingPointBalance ?? snapshot?.teamPointBalance);
+  const projectBudgetBalance = toNumberOrNull(snapshot?.projectBudgetBalance ?? snapshot?.projectPointBalance);
+  return {
+    pointCost: normalizedPointCost,
+    billingPointBalance,
+    billingPointRemainingAfter: normalizedPointCost != null && billingPointBalance != null ? billingPointBalance - normalizedPointCost : null,
+    projectBudgetBalance,
+    projectBudgetMax: snapshot?.projectBudgetMax ?? snapshot?.projectPointMax ?? null,
+    projectBudgetRemainingAfter: normalizedPointCost != null && projectBudgetBalance != null ? projectBudgetBalance - normalizedPointCost : null,
+    teamPointBalance: billingPointBalance,
+    projectPointBalance: projectBudgetBalance,
+    projectPointMax: snapshot?.projectPointMax ?? null,
+    teamPointRemainingAfter: normalizedPointCost != null && billingPointBalance != null ? billingPointBalance - normalizedPointCost : null,
+    projectPointRemainingAfter: normalizedPointCost != null && projectBudgetBalance != null ? projectBudgetBalance - normalizedPointCost : null,
+  };
+}
+
+export async function imageFee(kwargs = {}) {
+  if (toBool(kwargs.dryRun)) {
+    const built = await buildImageRequest(kwargs, { dryRun: true, includeCustomBizId: false });
+    return compactRecord({
+      dryRun: true,
+      action: 'image fee',
+      request: built.request,
+      ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
+    });
+  }
+  const built = await buildImageRequest(kwargs, { includeCustomBizId: false });
+  const payload = await awbApi.fetchImageFee(built.request);
+  return {
+    data: payload,
+    ...(await pointEstimate(payload, built.projectGroupNo)),
+  };
+}
+
+function normalizeCreateUploads(uploads = []) {
+  return uploads.map((item) => compactRecord({
+    filePath: item.filePath,
+    fileName: item.fileName,
+    exists: item.exists,
+    size: item.size,
+    mimeType: item.mimeType,
+    width: item.width,
+    height: item.height,
+    format: item.format,
+    backendPath: item.backendPath,
+    url: item.url,
+  }));
+}
+
+function extractCreatedTaskId(payload, flat = {}) {
+  if (typeof payload === 'string' || typeof payload === 'number') return String(payload);
+  if (!payload || typeof payload !== 'object') return null;
+  return payload.taskId
+    ?? payload.id
+    ?? payload.task_id
+    ?? flat.taskId
+    ?? flat.id
+    ?? flat.task_id
+    ?? null;
+}
+
+function normalizeCreatedTask(payload, extra = {}) {
+  const flat = payload && typeof payload === 'object' ? flattenRecord(payload) : {};
+  const taskId = extractCreatedTaskId(payload, flat);
+  return compactRecord({
+    ...(taskId ? { taskId: String(taskId) } : {}),
+    ...flat,
+    ...extra,
+  });
+}
+
+export async function imageCreate(kwargs = {}) {
+  if (toBool(kwargs.dryRun)) {
+    const built = await buildImageRequest(kwargs, { dryRun: true });
+    return compactRecord({
+      dryRun: true,
+      action: 'image create',
+      request: built.request,
+      ...(built.localFiles.length ? { localFiles: built.localFiles } : {}),
+      ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
+    });
+  }
+  ensureConfirmed(kwargs, '正式生图会消耗积分，需要确认', { action: 'image create' });
+  const built = await buildImageRequest(kwargs);
+  const feePayload = await awbApi.fetchImageFee(built.request).catch(() => null);
+  const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
+  const payload = await awbApi.createImageTask(built.request);
+  const result = normalizeCreatedTask(payload, {
+    ...estimate,
+    projectGroupNo: built.projectGroupNo,
+    modelGroupCode: built.request.modelGroupCode,
+    ...(built.uploads.length ? { uploads: normalizeCreateUploads(built.uploads) } : {}),
+  });
+  await appendTaskRecord(kwargs, {
+    taskId: result.taskId,
+    taskType: 'IMAGE_CREATE',
+    projectGroupNo: built.projectGroupNo,
+    modelGroupCode: built.request.modelGroupCode,
+    promptSummary: taskPromptSummary({ prompt: built.request.promptParams?.prompt }),
+  });
+  if (toInt(kwargs.waitSeconds, 0) > 0 && result.taskId) {
+    return {
+      ...result,
+      waited: await waitTask({
+        taskId: result.taskId,
+        taskType: 'IMAGE_CREATE',
+        projectGroupNo: built.projectGroupNo,
+        waitSeconds: kwargs.waitSeconds,
+        pollIntervalMs: kwargs.pollIntervalMs,
+      }),
+    };
+  }
+  return {
+    ...result,
+    nextCommand: result.taskId
+      ? `lj-awb task wait --task-id ${result.taskId} --task-type IMAGE_CREATE --project-group-no ${built.projectGroupNo} -f json`
+      : null,
+  };
+}
+
+async function buildVideoRequest(kwargs = {}, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const model = resolveTaskModel('video', kwargs);
+  const validationResources = await resolveResources(kwargs, {
+    dryRun: true,
+    kind: 'video',
+    sceneType: TASK_UPLOAD_SCENE.VIDEO_CREATE,
+  });
+  const prompt = trimToNull(kwargs.prompt) ?? '';
+  if (!prompt && !validationResources.resources.length) {
+    throw argumentError('缺少视频生成输入', '至少传 --prompt 或 --resource。');
+  }
+  assertVideoReferenceKeysUsed(prompt, validationResources.resources);
+  const defaultParams = {
+    prompt,
+    resources: validationResources.resources,
+  };
+  if (kwargs.duration != null && kwargs.duration !== '') {
+    defaultParams.duration = parseIntegerParam(kwargs.duration, '--duration', 0);
+  }
+  if (kwargs.ratio != null && kwargs.ratio !== '') defaultParams.ratio = kwargs.ratio;
+  if (kwargs.quality != null && kwargs.quality !== '') defaultParams.quality = kwargs.quality;
+  if (kwargs.needAudio != null && kwargs.needAudio !== '') defaultParams.need_audio = toBool(kwargs.needAudio);
+  const promptParams = normalizeUnifiedPromptParams(defaultParams);
+  const validation = await validateCreateRequestAgainstModel('video', model.modelGroupCode, promptParams, validationResources.resourceDetails);
+  const resolvedResources = await resolveResources(kwargs, {
+    dryRun,
+    kind: 'video',
+    sceneType: TASK_UPLOAD_SCENE.VIDEO_CREATE,
+    resourceRules: validation.resourceRules,
+  });
+  const requestPromptParams = normalizeUnifiedPromptParams({ ...defaultParams, resources: resolvedResources.resources });
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo, { allowNull: dryRun, noNetwork: dryRun, noSave: dryRun });
+  const customBizId = options.includeCustomBizId === false ? null : resolveCustomBizId(kwargs.customBizId);
+  return {
+    model,
+    projectGroupNo,
+    uploads: resolvedResources.uploads,
+    localFiles: resolvedResources.localFiles,
+    resourceConversions: resolvedResources.resourceConversions,
+    request: {
+      requestSource: REQUEST_SOURCE_CLI,
+      modelGroupCode: model.modelGroupCode,
+      ...(customBizId ? { customBizId } : {}),
+      promptParams: requestPromptParams,
+      ...(projectGroupNo ? { projectGroupNo } : {}),
+    },
+  };
+}
+
+export async function videoFee(kwargs = {}) {
+  if (toBool(kwargs.dryRun)) {
+    const built = await buildVideoRequest(kwargs, { dryRun: true, includeCustomBizId: false });
+    return compactRecord({
+      dryRun: true,
+      action: 'video fee',
+      request: built.request,
+      ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
+    });
+  }
+  const built = await buildVideoRequest(kwargs, { includeCustomBizId: false });
+  const payload = await awbApi.fetchVideoFee(built.request);
+  return {
+    data: payload,
+    ...(await pointEstimate(payload, built.projectGroupNo)),
+  };
+}
+
+export async function videoCreate(kwargs = {}) {
+  if (toBool(kwargs.dryRun)) {
+    const built = await buildVideoRequest(kwargs, { dryRun: true });
+    return compactRecord({
+      dryRun: true,
+      action: 'video create',
+      request: built.request,
+      ...(built.localFiles.length ? { localFiles: built.localFiles } : {}),
+      ...(built.resourceConversions.length ? { resourceConversions: built.resourceConversions } : {}),
+    });
+  }
+  ensureConfirmed(kwargs, '正式生视频会消耗积分，需要确认', { action: 'video create' });
+  const built = await buildVideoRequest(kwargs);
+  const feePayload = await awbApi.fetchVideoFee(built.request).catch(() => null);
+  const estimate = await pointEstimate(feePayload, built.projectGroupNo).catch(() => ({}));
+  const payload = await awbApi.createVideoTask(built.request);
+  const result = normalizeCreatedTask(payload, {
+    ...estimate,
+    projectGroupNo: built.projectGroupNo,
+    modelGroupCode: built.request.modelGroupCode,
+    ...(built.uploads.length ? { uploads: normalizeCreateUploads(built.uploads) } : {}),
+  });
+  await appendTaskRecord(kwargs, {
+    taskId: result.taskId,
+    taskType: 'VIDEO_GROUP',
+    projectGroupNo: built.projectGroupNo,
+    modelGroupCode: built.request.modelGroupCode,
+    promptSummary: taskPromptSummary({ prompt: built.request.promptParams?.prompt }),
+  });
+  if (toInt(kwargs.waitSeconds, 0) > 0 && result.taskId) {
+    return {
+      ...result,
+      waited: await waitTask({
+        taskId: result.taskId,
+        taskType: 'VIDEO_GROUP',
+        projectGroupNo: built.projectGroupNo,
+        waitSeconds: kwargs.waitSeconds,
+        pollIntervalMs: kwargs.pollIntervalMs,
+      }),
+    };
+  }
+  return {
+    ...result,
+    nextCommand: result.taskId
+      ? `lj-awb task wait --task-id ${result.taskId} --task-type VIDEO_GROUP --project-group-no ${built.projectGroupNo} -f json`
+      : null,
+  };
+}
+
+export async function loadBatchItems(inputFile, mode = 'generic') {
+  const filePath = trimToNull(inputFile);
+  if (!filePath) throw argumentError('缺少批量输入文件', '传 --input-file <json|jsonl|txt>。');
+  const text = await fs.readFile(path.resolve(filePath), 'utf8');
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.startsWith('[')) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) throw argumentError('批量 JSON 必须是数组');
+    return parsed;
+  }
+  const lines = trimmed.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.every((line) => line.startsWith('{'))) return lines.map((line) => JSON.parse(line));
+  if (lines.length === 1 && lines[0].startsWith('{')) {
+    const parsed = JSON.parse(lines[0]);
+    if (Array.isArray(parsed.items)) return parsed.items;
+    return [parsed];
+  }
+  return lines.map((line) => (mode === 'subject' ? { name: line } : { prompt: line }));
+}
+
+const IMAGE_BATCH_ITEM_KEYS = new Set([
+  'prompt',
+  'ratio',
+  'quality',
+  'generate_num',
+  'generateNum',
+  'resource',
+  'resources',
+  'resourcesJson',
+  'customBizId',
+]);
+const VIDEO_BATCH_ITEM_KEYS = new Set([
+  'prompt',
+  'ratio',
+  'quality',
+  'duration',
+  'need_audio',
+  'needAudio',
+  'resource',
+  'resources',
+  'resourcesJson',
+  'customBizId',
+]);
+
+function normalizeTaskBatchItem(item, kind, index) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    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));
+  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。',
+    );
+  }
+  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;
+  return next;
+}
+
+async function runConcurrent(items, limit, worker) {
+  const safeLimit = Math.max(1, toInt(limit, 1));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function runOne() {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      try {
+        results[index] = await worker(items[index], index);
+      } catch (error) {
+        results[index] = {
+          inputIndex: index,
+          status: 'error',
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(safeLimit, Math.max(items.length, 1)) }, runOne));
+  return results;
+}
+
+export async function imageCreateBatch(kwargs = {}) {
+  const items = (await loadBatchItems(kwargs.inputFile, 'image'))
+    .map((item, index) => normalizeTaskBatchItem(item, 'image', index));
+  if (toBool(kwargs.dryRun)) {
+    const results = [];
+    for (const [index, item] of items.entries()) {
+      results.push({ inputIndex: index, ...(await imageCreate({ ...kwargs, ...item, dryRun: true })) });
+    }
+    return { dryRun: true, count: items.length, results };
+  }
+  ensureConfirmed(kwargs, '批量生图会多次消耗积分，需要确认', { action: 'image create-batch', count: items.length });
+  const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
+    inputIndex: index,
+    status: 'success',
+    ...(await imageCreate({ ...kwargs, ...item, yes: true, dryRun: false })),
+  }));
+  return { count: items.length, results };
+}
+
+export async function videoCreateBatch(kwargs = {}) {
+  const items = (await loadBatchItems(kwargs.inputFile, 'video'))
+    .map((item, index) => normalizeTaskBatchItem(item, 'video', index));
+  if (toBool(kwargs.dryRun)) {
+    const results = [];
+    for (const [index, item] of items.entries()) {
+      results.push({ inputIndex: index, ...(await videoCreate({ ...kwargs, ...item, dryRun: true })) });
+    }
+    return { dryRun: true, count: items.length, results };
+  }
+  ensureConfirmed(kwargs, '批量生视频会多次消耗积分，需要确认', { action: 'video create-batch', count: items.length });
+  const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
+    inputIndex: index,
+    status: 'success',
+    ...(await videoCreate({ ...kwargs, ...item, yes: true, dryRun: false })),
+  }));
+  return { count: items.length, results };
+}
+
+function taskPromptSummary(input = {}) {
+  const text = trimToNull(input.prompt ?? input.taskPrompt);
+  return text ? text.slice(0, 160) : null;
+}
+
+function resolveTaskRecordFile(kwargs = {}) {
+  const filePath = trimToNull(kwargs.taskRecordFile ?? DEFAULT_TASK_RECORD_FILE_ENV);
+  return filePath ? path.resolve(filePath) : null;
+}
+
+async function appendTaskRecord(kwargs, record) {
+  const filePath = resolveTaskRecordFile(kwargs);
+  if (!filePath || !record?.taskId) return null;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.appendFile(filePath, `${JSON.stringify({
+    schemaVersion: 1,
+    site: SITE,
+    recordedAt: nowIso(),
+    ...record,
+  })}\n`, 'utf8');
+  return filePath;
+}
+
+function normalizeTask(payload, taskType = null, extra = {}) {
+  const item = Array.isArray(payload) ? payload[0] : payload ?? {};
+  const resultFileList = Array.isArray(item?.resultFileList) ? item.resultFileList : [];
+  const resultFileDisplayList = Array.isArray(item?.resultFileDisplayList) ? item.resultFileDisplayList : [];
+  const taskExt = item?.taskExt && typeof item.taskExt === 'object' ? item.taskExt : null;
+  const originUrls = uniqueNonEmpty([
+    ...parseListArg(taskExt?.ORIGIN_URL ?? taskExt?.originUrl ?? taskExt?.origin_url),
+    ...parseListArg(item?.originUrl ?? item?.origin_url),
+  ]);
+  const resultUrls = uniqueNonEmpty([
+    ...resultFileDisplayList,
+    ...resultFileList,
+    ...parseListArg(item?.resultUrl),
+    ...parseListArg(item?.url),
+  ]);
+  const taskStatus = item?.taskStatus ?? item?.status ?? item?.state ?? null;
+  return compactRecord({
+    taskId: item?.taskId ?? extra.taskId ?? null,
+    taskType: item?.taskType ?? taskType ?? extra.taskType ?? null,
+    ...(extra.projectGroupNo ? { projectGroupNo: extra.projectGroupNo } : {}),
+    taskStatus,
+    isTerminal: isTerminalTaskStatus(taskStatus),
+    modelGroupCode: item?.modelGroupCode ?? null,
+    pointNo: item?.pointNo ?? null,
+    gmtCreate: item?.gmtCreate ?? item?.createTime ?? item?.createdAt ?? null,
+    gmtModified: item?.gmtModified ?? item?.updateTime ?? item?.updatedAt ?? null,
+    promptSummary: taskPromptSummary({ prompt: item?.taskPrompt }),
+    resultCount: resultUrls.length,
+    ...(resultUrls.length ? { resultUrls } : {}),
+    ...(originUrls.length ? { originUrls } : {}),
+    errorMessage: item?.errorMsg ?? item?.resultMsg ?? item?.message ?? null,
+    ...extra,
+  });
+}
+
+export async function taskStatus(kwargs = {}) {
+  const taskId = requireValue(kwargs, 'taskId', 'task-id');
+  const taskType = normalizeFeedTaskType(kwargs.taskType ?? 'IMAGE_CREATE');
+  const kind = taskTypeToStatusKind(taskType);
+  const payload = kind === 'video' ? await awbApi.fetchVideoTask(taskId) : await awbApi.fetchImageTask(taskId);
+  return normalizeTask(payload, taskType, {
+    taskId,
+    taskType,
+    ...(trimToNull(kwargs.projectGroupNo) ? { projectGroupNo: trimToNull(kwargs.projectGroupNo) } : {}),
+  });
+}
+
+export async function taskList(kwargs = {}) {
+  const taskType = normalizeFeedTaskType(kwargs.taskType ?? 'IMAGE_CREATE');
+  const projectGroupNo = await resolveProjectGroupNo(kwargs.projectGroupNo);
+  const request = {
+    taskType,
+    minTime: toInt(kwargs.minTime, Date.now()),
+    pageSize: Math.min(Math.max(toInt(kwargs.pageSize, 20), 1), 200),
+    projectGroupNo,
+  };
+  const payload = await awbApi.fetchTaskFeed(request);
+  const tasks = normalizeRows(payload).map((item) => normalizeTask(item, item?.taskType ?? taskType, {
+    projectGroupNo,
+  }));
+  return {
+    taskType,
+    projectGroupNo,
+    pageSize: request.pageSize,
+    minTime: request.minTime,
+    tasks,
+  };
+}
+
+export async function waitTask(kwargs = {}) {
+  const taskId = requireValue(kwargs, 'taskId', 'task-id');
+  const taskType = normalizeFeedTaskType(kwargs.taskType ?? 'IMAGE_CREATE');
+  const waitSeconds = Math.max(0, toInt(kwargs.waitSeconds, 300));
+  const pollIntervalMs = Math.max(500, toInt(kwargs.pollIntervalMs, 5000));
+  const deadline = Date.now() + waitSeconds * 1000;
+  let last = null;
+  while (true) {
+    last = await taskStatus({ ...kwargs, taskId, taskType }).catch(async (error) => {
+      if (['network_error', 'auth_failed'].includes(error?.type)) {
+        throw error;
+      }
+      const list = await taskList({ ...kwargs, taskId, taskType, pageSize: kwargs.pageSize ?? 100 }).catch((listError) => {
+        if (['network_error', 'auth_failed'].includes(listError?.type)) {
+          throw listError;
+        }
+        return { tasks: [] };
+      });
+      return list.tasks.find((item) => item.taskId === taskId) ?? null;
+    });
+    if (last?.isTerminal) {
+      return { ...last, timedOut: false, waitedMs: waitSeconds * 1000 - Math.max(0, deadline - Date.now()) };
+    }
+    if (Date.now() >= deadline || waitSeconds === 0) break;
+    await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+  }
+  throw new LingjingAwbCliError('任务仍在运行，当前等待窗口已结束', {
+    type: 'task_still_running',
+    exitCode: 20,
+    hint: '稍后再次运行 task wait，或增大 --wait-seconds。',
+    details: {
+      taskId,
+      taskType,
+      waitSeconds,
+      last,
+    },
+  });
+}
+
+export async function taskRecords(kwargs = {}) {
+  const filePath = resolveTaskRecordFile(kwargs);
+  if (!filePath) throw argumentError('缺少任务台账文件', '传 --task-record-file <path>，或设置 LINGJING_AWB_TASK_RECORD_FILE。');
+  const text = await fs.readFile(filePath, 'utf8').catch((error) => {
+    if (error?.code === 'ENOENT') return '';
+    throw error;
+  });
+  const records = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
+  const latest = new Map();
+  for (const record of records) {
+    if (record?.taskId) latest.set(record.taskId, record);
+  }
+  const taskType = trimToNull(kwargs.taskType);
+  const pendingOnly = toBool(kwargs.pendingOnly);
+  const rows = [...latest.values()]
+    .filter((record) => !taskType || normalizeFeedTaskType(record.taskType) === normalizeFeedTaskType(taskType))
+    .filter((record) => !pendingOnly || !isTerminalTaskStatus(record.taskStatus))
+    .sort((left, right) => String(right.recordedAt ?? '').localeCompare(String(left.recordedAt ?? '')))
+    .slice(0, Math.max(1, toInt(kwargs.limit, 100)));
+  return { filePath, count: rows.length, records: rows };
+}
+
+export async function taskRecordPoll(kwargs = {}) {
+  const source = await taskRecords({ ...kwargs, pendingOnly: kwargs.pendingOnly ?? true });
+  const waitSeconds = Math.max(0, toInt(kwargs.waitSeconds, 0));
+  const deadline = Date.now() + waitSeconds * 1000;
+  const results = new Map();
+  do {
+    for (const record of source.records) {
+      if (results.get(record.taskId)?.isTerminal) continue;
+      const status = await taskStatus({
+        taskId: record.taskId,
+        taskType: record.taskType,
+        projectGroupNo: record.projectGroupNo,
+      }).catch((error) => ({
+        taskId: record.taskId,
+        taskType: record.taskType,
+        isTerminal: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      results.set(record.taskId, { ...record, ...status });
+    }
+    if ([...results.values()].every((item) => item.isTerminal)) break;
+    if (Date.now() > deadline) break;
+    await sleep(Math.max(500, toInt(kwargs.pollIntervalMs, 5000)));
+  } while (waitSeconds > 0);
+  return {
+    filePath: source.filePath,
+    count: source.records.length,
+    timedOut: ![...results.values()].every((item) => item.isTerminal),
+    records: [...results.values()],
+  };
+}
+
+function normalizeCosAssetPath(value) {
+  const text = trimToNull(value);
+  if (!text) return null;
+  if (/^https?:\/\//i.test(text)) {
+    try {
+      return decodeURIComponent(new URL(text).pathname.replace(/^\/+/, ''));
+    } catch {
+      return text.replace(/^\/+/, '');
+    }
+  }
+  return text.replace(/^\/+/, '');
+}
+
+function normalizeAssetGroup(item = {}) {
+  return {
+    id: item?.id ?? item?.groupId ?? item?.assetGroupsId ?? null,
+    groupId: item?.id ?? item?.groupId ?? item?.assetGroupsId ?? null,
+    name: item?.name ?? item?.groupName ?? null,
+    description: item?.description ?? null,
+    projectName: item?.projectName ?? null,
+  };
+}
+
+function extractAssetGroupRows(payload) {
+  return normalizeRows(payload).map((item) => normalizeAssetGroup(item));
+}
+
+function parseJsonString(value) {
+  if (value == null || value === '') return null;
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function stringifyJsonObjectArg(value, fallback = '{}') {
+  if (value === undefined || value === null || value === '') return fallback;
+  const parsed = parseJsonArg(value, {});
+  return typeof parsed === 'string' ? parsed : JSON.stringify(parsed);
+}
+
+function normalizeAssetMatchRecord(item = {}, fallbackPartType = null) {
+  return {
+    assetId: item?.materialId ?? item?.assetId ?? item?.id ?? null,
+    partType: item?.partType ?? fallbackPartType,
+    imageUrl: item?.imageUrl ?? item?.image ?? item?.url ?? null,
+    description: item?.description ?? null,
+    score: toNumberOrNull(item?.matchScore ?? item?.score ?? item?.similarity),
+    tags: parseJsonString(item?.tagInfo ?? item?.tags),
+  };
+}
+
+function normalizeAssetMatchRows(payload) {
+  if (Array.isArray(payload)) {
+    return payload
+      .map((item) => normalizeAssetMatchRecord(item))
+      .sort((left, right) => (right.score ?? -Infinity) - (left.score ?? -Infinity));
+  }
+  if (!payload || typeof payload !== 'object') return [];
+
+  const groupSpecs = [
+    ['head', 'HEAD'],
+    ['body', 'BODY'],
+    ['realPersonHead', 'REAL_PERSON_HEAD'],
+  ];
+  const rows = [];
+  for (const [key, partType] of groupSpecs) {
+    for (const item of Array.isArray(payload[key]) ? payload[key] : []) {
+      rows.push(normalizeAssetMatchRecord(item, partType));
+    }
+  }
+  if (rows.length) {
+    return rows.sort((left, right) => (right.score ?? -Infinity) - (left.score ?? -Infinity));
+  }
+  return normalizeRows(payload)
+    .map((item) => normalizeAssetMatchRecord(item))
+    .sort((left, right) => (right.score ?? -Infinity) - (left.score ?? -Infinity));
+}
+
+function normalizeSubjectResourceUrls(list, key) {
+  if (!Array.isArray(list)) return [];
+  const upperKey = key.charAt(0).toUpperCase() + key.slice(1);
+  return uniqueNonEmpty(list.map((item) => (typeof item === 'string' ? item : item?.[key] ?? item?.[upperKey])));
+}
+
+function normalizeSubjectTagIds(tagList) {
+  if (!Array.isArray(tagList)) return [];
+  return uniqueNonEmpty(tagList.map((item) => (typeof item === 'string' ? item : item?.tagId ?? item?.id ?? item?.tagCode)));
+}
+
+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;
+  return {
+    subjectId: externalId ?? elementId,
+    elementId,
+    externalId,
+    name,
+    description: item?.elementDescription ?? item?.description ?? item?.subjectDesc ?? null,
+    referenceType: item?.referenceType ?? null,
+    modelCode: item?.modelCode ?? null,
+    imageUrls: uniqueNonEmpty([
+      item?.elementFrontalImage,
+      item?.imageUrl,
+      item?.coverUrl,
+      ...normalizeSubjectResourceUrls(referList, 'imageUrl'),
+    ]),
+    videoUrls: uniqueNonEmpty([
+      item?.videoUrl,
+      ...normalizeSubjectResourceUrls(videoList, 'videoUrl'),
+    ]),
+    audioUrls: normalizeSubjectResourceUrls(referList, 'audioUrl'),
+    tagIds: normalizeSubjectTagIds(item?.tagList),
+    ...(trimToNull(item?.elementVoiceId) ? { voiceId: trimToNull(item.elementVoiceId) } : {}),
+    ...(externalId && name ? { nextRefSubject: `${name}=${externalId}` } : {}),
+    createdAt: item?.gmtCreate ?? item?.createdAt ?? null,
+  };
+}
+
+function paginateRows(rows, pageNumber, pageSize) {
+  const actualPageNumber = Math.max(1, toInt(pageNumber, 1));
+  const actualPageSize = Math.max(1, toInt(pageSize, 20));
+  const start = (actualPageNumber - 1) * actualPageSize;
+  return rows.slice(start, start + actualPageSize);
+}
+
+export async function assetMatchActor(kwargs = {}) {
+  const description = requireValue(kwargs, 'description');
+  const tagJson = stringifyJsonObjectArg(kwargs.tagsJson ?? kwargs.tagJson);
+  const payload = await awbApi.matchAssetMaterial({
+    description,
+    tagJson,
+    tagWeight: toNumberOrNull(kwargs.tagWeight) ?? 0.5,
+    descWeight: toNumberOrNull(kwargs.descWeight) ?? 0.5,
+  });
+  return {
+    matches: normalizeAssetMatchRows(payload),
+    ...(toBool(kwargs.includeRaw) ? { raw: payload } : {}),
+  };
+}
+
+export async function assetGroupList(kwargs = {}) {
+  const payload = await awbApi.listAssetGroups({
+    name: kwargs.name ?? '',
+    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 };
+}
+
+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 };
+}
+
+export async function assetGroupCreate(kwargs = {}) {
+  const name = requireValue(kwargs, 'name');
+  const body = {
+    name,
+    description: kwargs.description ?? '',
+    projectName: kwargs.projectName ?? 'default',
+  };
+  if (toBool(kwargs.dryRun)) return { dryRun: true, action: 'asset group-create', request: body };
+  ensureConfirmed(kwargs, '创建素材组是云端写入动作，需要确认', { action: 'asset group-create', body });
+  const payload = await awbApi.createAssetGroup(body);
+  return { created: true, groupId: payload?.id ?? payload?.groupId ?? payload ?? null, name, projectName: body.projectName };
+}
+
+export async function assetGroupUpdate(kwargs = {}) {
+  const groupId = requireValue(kwargs, 'groupId', 'group-id');
+  const body = {};
+  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 });
+  await awbApi.updateAssetGroup(groupId, body);
+  return { updated: true, groupId, ...body };
+}
+
+function extractAssetId(payload) {
+  if (typeof payload === 'string') return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  return payload.id ?? payload.assetId ?? payload.thirdAssetId ?? payload.resourceNo ?? payload.data?.id ?? null;
+}
+
+export async function assetRegister(kwargs = {}) {
+  const groupId = requireValue(kwargs, 'groupId', 'group-id');
+  const name = requireValue(kwargs, 'name');
+  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',
+      request: {
+        assetGroupsId: groupId,
+        url: localFile ? normalizeCosAssetPath(dryRunBackendPath(localFile, TASK_UPLOAD_SCENE.SUBJECT)) : assetPath,
+        name,
+        ...(kwargs.platform ? { platform: kwargs.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;
+  const body = {
+    assetGroupsId: groupId,
+    url: normalizeCosAssetPath(uploaded?.backendPath ?? assetPath),
+    name,
+    ...(kwargs.platform ? { platform: kwargs.platform } : {}),
+  };
+  const payload = await awbApi.registerAsset(body);
+  return {
+    registered: true,
+    assetId: extractAssetId(payload),
+    groupId,
+    name,
+    assetPath: body.url,
+    ...(uploaded ? { upload: uploaded } : {}),
+  };
+}
+
+export async function subjectList(kwargs = {}) {
+  const keyword = trimToNull(kwargs.keyword ?? kwargs.name);
+  const payload = keyword
+    ? await awbApi.listElementsByName(keyword)
+    : await awbApi.listElements();
+  const subjects = paginateRows(
+    normalizeRows(payload).map((item) => normalizeSubjectRecord(item)),
+    kwargs.pageNumber,
+    kwargs.pageSize,
+  );
+  return {
+    subjects,
+    ...(toBool(kwargs.includeRaw) ? { raw: payload } : {}),
+  };
+}
+
+const SUBJECT_SLOT_ALIASES = {
+  primary: 'primary',
+  'three-view': 'three-view',
+  three_view: 'three-view',
+  threeview: 'three-view',
+  face: 'face',
+  side: 'side',
+  back: 'back',
+};
+
+const SUBJECT_SLOT_META = {
+  primary: { idField: 'subjectId' },
+  'three-view': { idField: 'subjectId' },
+  face: { idField: 'faceViewId' },
+  side: { idField: 'sideViewId' },
+  back: { idField: 'backViewId' },
+};
+
+function parseSubjectResourceItem(raw, index) {
+  const text = String(raw ?? '').trim();
+  if (!text) {
+    throw argumentError(`resource[${index}] 为空`, '格式：--resource <slot>:<file|url>，slot ∈ primary | three-view | face | side | back。');
+  }
+  const colonIndex = text.indexOf(':');
+  if (colonIndex <= 0) {
+    throw argumentError(
+      `resource[${index}] 缺少 slot`,
+      '格式：--resource <slot>:<file|url>，例如 --resource primary:./three-view.png。',
+    );
+  }
+  const slotRaw = text.slice(0, colonIndex).trim().toLowerCase();
+  const slot = SUBJECT_SLOT_ALIASES[slotRaw];
+  if (!slot) {
+    throw argumentError(`resource[${index}] slot 不支持：${slotRaw}`, 'slot ∈ primary | three-view | face | side | back。');
+  }
+  const value = text.slice(colonIndex + 1).trim();
+  if (!value) {
+    throw argumentError(`resource[${index}] value 不能为空`);
+  }
+  return { slot, value };
+}
+
+function subjectAssetSpecs(kwargs = {}) {
+  const bySlot = new Map();
+  const items = parseListArg(kwargs.resource);
+  for (const [index, raw] of items.entries()) {
+    const { slot, value } = parseSubjectResourceItem(raw, index);
+    if (bySlot.has(slot)) {
+      throw argumentError(`resource[${index}] slot 重复：${slot}`, '每个 slot 只能传一次。');
+    }
+    const isUrl = isRemoteOrBackendPath(value);
+    bySlot.set(slot, { label: slot, idField: SUBJECT_SLOT_META[slot].idField, file: isUrl ? null : value, url: isUrl ? value : null });
+  }
+  const primary = bySlot.get('primary') ?? bySlot.get('three-view');
+  if (!primary) return [];
+  const ordered = [{ ...primary, label: 'primary', isPrimary: true }];
+  for (const slot of ['face', 'side', 'back']) {
+    const item = bySlot.get(slot);
+    if (item) ordered.push(item);
+  }
+  return ordered;
+}
+
+function subjectAssetPathForDryRun(item) {
+  return item.file
+    ? normalizeCosAssetPath(dryRunBackendPath(item.file, TASK_UPLOAD_SCENE.SUBJECT))
+    : normalizeCosAssetPath(item.url);
+}
+
+function tagListFromArg(value) {
+  const parsed = parseJsonArg(value, []);
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map((item) => (typeof item === 'string' ? { tagId: item } : { tagId: trimToNull(item?.tagId ?? item?.id ?? item?.tagCode) }))
+    .filter((item) => item.tagId);
+}
+
+function buildSubjectCreateBody(kwargs, specs, assets) {
+  const name = requireValue(kwargs, 'name');
+  const primary = assets.find((item) => item.isPrimary);
+  const referAssets = assets.filter((item) => item.assetPath);
+  return compactRecord({
+    reqTaskId: trimToNull(kwargs.reqTaskId),
+    modelCode: trimToNull(kwargs.modelCode),
+    elementName: name,
+    elementDescription: trimToNull(kwargs.description ?? kwargs.elementDescription),
+    elementFrontalImage: primary?.assetPath ?? null,
+    elementReferList: referAssets.map((item) => ({
+      imageUrl: item.assetPath,
+      audioUrl: null,
+    })),
+    referenceType: trimToNull(kwargs.referenceType) ?? 'image_refer',
+    elementVoiceId: trimToNull(kwargs.voiceId ?? kwargs.elementVoiceId),
+    tagList: tagListFromArg(kwargs.tagsJson ?? kwargs.tagJson),
+  });
+}
+
+function extractCreatedElementId(payload) {
+  if (typeof payload === 'string') return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  return payload.id ?? payload.elementId ?? payload.subjectId ?? payload.reqTaskId ?? payload.data?.id ?? payload.data?.elementId ?? null;
+}
+
+async function fetchSubjectByReqTaskId(reqTaskId) {
+  if (!reqTaskId) return null;
+  const payload = await awbApi.getElementByReqTaskId(reqTaskId).catch(() => null);
+  return payload && typeof payload === 'object' ? normalizeSubjectRecord(payload) : null;
+}
+
+async function waitForSubjectExternalId(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 fetchSubjectByReqTaskId(reqTaskId);
+  while (waitSeconds > 0 && !latest?.externalId && Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+    latest = await fetchSubjectByReqTaskId(reqTaskId);
+  }
+  return latest;
+}
+
+function subjectWaitPayload(elementId, subject) {
+  const externalId = subject?.externalId ?? null;
+  return {
+    elementId,
+    subjectId: externalId ?? elementId,
+    externalId,
+    nextRefSubject: externalId && subject?.name ? `${subject.name}=${externalId}` : null,
+    status: externalId ? 'ready' : 'pending_external_id',
+    subject,
+  };
+}
+
+export async function subjectPublish(kwargs = {}) {
+  const name = requireValue(kwargs, 'name');
+  const specs = subjectAssetSpecs(kwargs);
+  if (!specs.some((item) => item.isPrimary)) {
+    throw argumentError('缺少主体主参考图', '传 --resource primary:<path|url>（或 --resource three-view:<path|url> 自动升为主图）。');
+  }
+  if (toBool(kwargs.dryRun)) {
+    const assets = specs.map((item) => ({
+      label: item.label,
+      file: item.file ?? null,
+      url: item.url ?? null,
+      assetPath: subjectAssetPathForDryRun(item),
+      isPrimary: Boolean(item.isPrimary),
+      dryRun: true,
+    }));
+    return {
+      dryRun: true,
+      action: 'subject publish',
+      name,
+      request: buildSubjectCreateBody(kwargs, specs, assets),
+      assets,
+      localFiles: await inspectLocalFiles(specs.map((item) => item.file).filter(Boolean)),
+      nextRefSubject: `${name}=<externalId>`,
+    };
+  }
+  ensureConfirmed(kwargs, '创建平台主体 element 是云端写入动作，需要确认', { action: 'subject publish', name });
+  const assets = [];
+  for (const spec of specs) {
+    const uploaded = spec.file ? await uploadLocalFile(spec.file, { sceneType: TASK_UPLOAD_SCENE.SUBJECT }) : null;
+    const assetPath = normalizeCosAssetPath(uploaded?.backendPath ?? spec.url);
+    assets.push({
+      label: spec.label,
+      file: spec.file ?? null,
+      url: spec.url ?? null,
+      assetPath,
+      isPrimary: Boolean(spec.isPrimary),
+      ...(uploaded ? { upload: uploaded } : {}),
+    });
+  }
+  const body = buildSubjectCreateBody(kwargs, specs, assets);
+  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 waitPayload = subjectWaitPayload(elementId, subject);
+  return {
+    created: true,
+    name,
+    elementId,
+    subjectId: waitPayload.subjectId,
+    externalId: waitPayload.externalId,
+    nextRefSubject: waitPayload.nextRefSubject,
+    status: waitPayload.status,
+    request: body,
+    assets,
+    subject,
+  };
+}
+
+export async function subjectWait(kwargs = {}) {
+  const elementId = requireValue(kwargs, 'elementId', 'element-id');
+  const subject = await waitForSubjectExternalId(elementId, kwargs);
+  const payload = subjectWaitPayload(elementId, subject);
+  if (!payload.externalId) {
+    throw new LingjingAwbCliError('主体 externalId 尚未回填', {
+      type: 'subject_still_pending',
+      exitCode: 20,
+      hint: '稍后重试 subject wait，或用 subject list --name 查询。',
+      details: payload,
+    });
+  }
+  return payload;
+}
+
+export async function subjectPublishBatch(kwargs = {}) {
+  const items = await loadBatchItems(kwargs.inputFile, 'subject');
+  if (toBool(kwargs.dryRun)) {
+    const results = [];
+    for (const [index, item] of items.entries()) {
+      results.push({ inputIndex: index, ...(await subjectPublish({ ...kwargs, ...item, dryRun: true })) });
+    }
+    return { dryRun: true, count: items.length, results };
+  }
+  ensureConfirmed(kwargs, '批量发布主体资产是云端写入动作，需要确认', { action: 'subject publish-batch', count: items.length });
+  const results = await runConcurrent(items, kwargs.concurrency ?? 1, async (item, index) => ({
+    inputIndex: index,
+    status: 'success',
+    ...(await subjectPublish({ ...kwargs, ...item, yes: true, dryRun: false })),
+  }));
+  return { count: items.length, results };
+}
+
+export async function subtitleRemove(kwargs = {}) {
+  const videoUrl = requireValue(kwargs, 'videoUrl', 'video-url');
+  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 {
+    submitted: true,
+    remoteTaskId: payload?.remote_task_id ?? payload?.remoteTaskId ?? null,
+    publicId: payload?.public_id ?? payload?.publicId ?? payload?.id ?? null,
+  };
+}
+
+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,
+  });
+}