@lingjingai/lj-awb-cli-pre 0.3.15

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

@@ -0,0 +1,1321 @@
+import { fetchProjectGroupUsers, fetchTeams, fetchUserInfo } from './api.js';
+import * as artifact from './artifact.js';
+import { clearAuth, loadAuth, saveAccessKey, summarizeAuth } from './auth.js';
+import { LingjingAwbCliError, maskSecret, toBool, trimSecret } from './common.js';
+import {
+  assetGroupCreate,
+  assetGroupGet,
+  assetGroupList,
+  assetGroupUpdate,
+  assetMatchActor,
+  assetRegister,
+  creditsBalance,
+  creditsUsageSummary,
+  createProjectGroupCommand,
+  accountInfo,
+  doctor,
+  ensureConfirmed,
+  ensureProjectGroupCommand,
+  fetchProjectGroupSummary,
+  imageCreate,
+  imageCreateBatch,
+  imageFee,
+  listModels,
+  modelOptions,
+  modelCreateSpec,
+  modelInputGuide,
+  listProjectGroups,
+  normalizeRows,
+  normalizeUserInfo,
+  selectProjectGroupCommand,
+  selectTeam,
+  subjectList,
+  subjectPublish,
+  subjectPublishBatch,
+  subjectWait,
+  subtitleRemove,
+  subtitleStatus,
+  taskList,
+  taskRecordPoll,
+  taskRecords,
+  taskStatus,
+  uploadFilesCommand,
+  updateProjectGroupCommand,
+  videoCreate,
+  videoCreateBatch,
+  videoFee,
+  waitTask,
+} from './services.js';
+
+function commandHelp(summary, options = {}) {
+  const lines = [summary];
+  if (options.quickStart?.length) {
+    lines.push('', 'Suggested flow:');
+    for (const item of options.quickStart) lines.push(`  ${item}`);
+  }
+  if (options.examples?.length) {
+    lines.push('', 'Examples:');
+    for (const example of options.examples) lines.push(`  ${example}`);
+  }
+  if (options.hint) {
+    lines.push('', `Hint: ${options.hint}`);
+  }
+  return lines.join('\n');
+}
+
+const YES_ARG = { name: 'yes', description: '确认执行写入 / 扣费 / 切换动作' };
+const DRY_RUN_ARG = { name: 'dry-run', description: '只预览请求，不执行写入 / 扣费动作' };
+const FEE_DRY_RUN_ARG = { name: 'dry-run', description: '只预览估价请求，不调用平台接口' };
+const INCLUDE_RAW_ARG = { name: 'include-raw', description: '在 JSON 中附带平台原始返回' };
+const PROJECT_ID_ARG = { name: 'project-id', valueName: 'projectId', description: 'AWB 项目 ID（不同于 --project-group-no）' };
+const PROJECT_GROUP_ARG = { name: 'project-group-no', valueName: 'no', description: '项目组编号；不传时读取当前项目组 / 环境变量 / 本地状态' };
+const CUSTOM_BIZ_ARG = { name: 'custom-biz-id', valueName: 'id', description: '外部追踪 ID；不传则请求不携带 customBizId' };
+const MODEL_GROUP_ARG = { name: 'model-group-code', valueName: 'code', description: '模型组编码；创建和参数查询只传这个字段' };
+const MODEL_LIST_ARGS = [
+  { name: 'model', valueName: 'keyword', description: '按模型名、编码、供应商或输入方式过滤；不传时查询全部' },
+  { name: 'limit', valueName: 'n', description: '默认文本最多展示 N 条，默认 8；JSON 输出始终返回全部匹配' },
+  { name: 'all', description: '默认文本展示全部匹配模型（覆盖 --limit）' },
+  INCLUDE_RAW_ARG,
+];
+const TASK_RECORD_ARG = { name: 'task-record-file', valueName: 'path', description: '任务台账 JSONL 文件；也可用 LINGJING_AWB_TASK_RECORD_FILE' };
+const RESOURCE_ARG = { name: 'resource', valueName: 'spec', description: '统一素材，格式 type:usage[:key]=path|url|asset，可重复传；音频参考用 audio:reference=./music.mp3' };
+const RESOURCES_JSON_ARG = { name: 'resources-json', valueName: 'json|path', description: 'resources 数组 JSON 或 JSON 文件路径' };
+const CREATE_WAIT_ARGS = [
+  { name: 'wait-seconds', valueName: 'seconds', description: '提交后顺带等待结果的秒数；默认 0 不等待' },
+  { name: 'poll-interval-ms', valueName: 'ms', description: '任务轮询间隔毫秒数，默认 5000' },
+];
+const TASK_WAIT_ARGS = [
+  { name: 'wait-seconds', valueName: 'seconds', description: '最长等待秒数；默认 300，传 0 只查询一次' },
+  { name: 'poll-interval-ms', valueName: 'ms', description: '任务轮询间隔毫秒数，默认 5000' },
+];
+const RECORD_POLL_ARGS = [
+  { name: 'wait-seconds', valueName: 'seconds', description: '最长轮询秒数；默认 0 只轮询一次本地台账' },
+  { name: 'poll-interval-ms', valueName: 'ms', description: '任务轮询间隔毫秒数，默认 5000' },
+];
+const SUBJECT_WAIT_ARGS = [
+  { name: 'wait-seconds', valueName: 'seconds', description: '最长等待 externalId 的秒数；默认 0 只查询一次' },
+  { name: 'poll-interval-ms', valueName: 'ms', description: '轮询间隔毫秒数，默认 2000' },
+];
+const BODY_INPUT_ARGS = [
+  { name: 'body-json', valueName: 'json', description: '直接传接口 body JSON' },
+  { name: 'input-file', valueName: 'path', description: '从本地 JSON 文件读取接口 body' },
+];
+const ARTIFACT_WRITE_ARGS = [DRY_RUN_ARG, YES_ARG];
+
+export function registerAwbCommands(cli) {
+  cli({
+    name: 'doctor',
+    description: commandHelp('检查 CLI 运行环境、认证、API 地址、项目组和 skill 安装状态', {
+      examples: [
+        'lj-awb doctor',
+        'lj-awb doctor --verify',
+        'lj-awb doctor --verify --project-group-no <no>',
+      ],
+      hint: '默认只做本地检查；追加 --verify 才联网校验 access key、当前用户和项目组。',
+    }),
+    args: [
+      { name: 'verify', description: '联网校验 access key、当前用户和项目组' },
+      PROJECT_GROUP_ARG,
+    ],
+    func: async (_ctx, kwargs) => doctor(kwargs),
+  });
+
+  cli({
+    name: 'auth status',
+    description: commandHelp('查看本地 access key 是否已配置；不联网', {
+      examples: ['lj-awb auth status'],
+      hint: '只说明本地是否配置，不代表远端可用；需要联网验证运行 auth verify 或 doctor --verify。',
+    }),
+    args: [],
+    func: async () => {
+      const auth = await loadAuth();
+      return {
+        ...summarizeAuth(auth),
+        verification: 'local_only',
+        verifyCommand: 'lj-awb auth verify',
+      };
+    },
+  });
+
+  cli({
+    name: 'auth verify',
+    description: commandHelp('联网校验 access key 是否远端有效', {
+      examples: ['lj-awb auth verify'],
+      hint: '会调用 userInfo；失败表示当前 access key 缺失、无效、过期或不适用于当前 API 地址。',
+    }),
+    args: [],
+    func: async () => {
+      const auth = await loadAuth();
+      const user = normalizeUserInfo(await fetchUserInfo());
+      return {
+        ...summarizeAuth(auth),
+        verified: true,
+        verification: 'remote',
+        user,
+      };
+    },
+  });
+
+  cli({
+    name: 'auth login',
+    description: commandHelp('登录：使用 access key 校验身份，并保存到本地认证文件', {
+      examples: [
+        'lj-awb auth login --access-key <key>',
+        'LINGJING_AWB_ACCESS_KEY=<key> lj-awb auth login',
+        'lj-awb auth login --access-key <key> --skip-verify',
+      ],
+      hint: '不要写成 lj-awb auth <key>。不传 --access-key 时自动读取 LINGJING_AWB_ACCESS_KEY / AWB_ACCESS_KEY / AWB_CODE 环境变量。',
+    }),
+    args: [
+      { name: 'access-key', valueName: 'key', description: '平台 access key；不传时读取环境变量' },
+      { name: 'skip-verify', description: '只保存 key，不调用 userInfo 校验；仅用于本地调试' },
+      DRY_RUN_ARG,
+    ],
+    func: async (_ctx, kwargs) => {
+      const skipVerify = toBool(kwargs.skipVerify);
+      const accessKey = trimSecret(kwargs.accessKey || process.env.LINGJING_AWB_ACCESS_KEY || process.env.AWB_ACCESS_KEY || process.env.AWB_CODE || process.env.ANIME_ACCESS_KEY || '');
+      if (!accessKey) {
+        throw new LingjingAwbCliError('缺少 access key', {
+          type: 'argument_error',
+          exitCode: 2,
+          hint: '传 --access-key <key>，或设置 LINGJING_AWB_ACCESS_KEY 环境变量。',
+        });
+      }
+      if (toBool(kwargs.dryRun)) {
+        return {
+          dryRun: true,
+          saved: false,
+          verified: false,
+          accessKey: maskSecret(accessKey),
+        };
+      }
+      let user = null;
+      if (!skipVerify) {
+        process.env.LINGJING_AWB_ACCESS_KEY = accessKey;
+        user = normalizeUserInfo(await fetchUserInfo());
+      }
+      const { auth } = await saveAccessKey(accessKey, { verified: !skipVerify });
+      return {
+        auth: summarizeAuth(auth, { accessKey, source: 'saved', sourceName: 'auth' }),
+        accessKey: maskSecret(accessKey),
+        verified: !skipVerify,
+        user,
+      };
+    },
+  });
+
+  cli({
+    name: 'auth clear',
+    description: commandHelp('清空本地认证文件', {
+      examples: ['lj-awb auth clear --dry-run', 'lj-awb auth clear --yes'],
+      hint: '只清本地文件，不清当前 shell 中的环境变量。',
+    }),
+    args: [DRY_RUN_ARG, YES_ARG],
+    func: async (_ctx, kwargs) => {
+      if (toBool(kwargs.dryRun)) return { cleared: false, dryRun: true };
+      ensureConfirmed(kwargs, '清空本地认证文件需要确认', { action: 'auth clear' });
+      await clearAuth();
+      return { cleared: true };
+    },
+  });
+
+  cli({
+    name: 'account info',
+    description: commandHelp('查看当前 AWB 用户、团队、项目组和积分摘要', {
+      examples: ['lj-awb account info'],
+    }),
+    args: [],
+    func: async () => accountInfo(),
+  });
+
+  cli({
+    name: 'account teams',
+    description: commandHelp('列出当前账号可用团队', {
+      examples: ['lj-awb account teams'],
+    }),
+    args: [],
+    func: async () => ({ teams: normalizeRows(await fetchTeams()) }),
+  });
+
+  cli({
+    name: 'account switch-team',
+    description: commandHelp('切换当前团队；会影响后续项目组和积分上下文', {
+      examples: ['lj-awb account switch-team --group-id <groupId> --dry-run', 'lj-awb account switch-team --group-id <groupId> --yes'],
+    }),
+    args: [
+      { name: 'group-id', valueName: 'id', description: '目标团队 groupId' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => selectTeam(kwargs),
+  });
+
+  cli({
+    name: 'project list',
+    description: commandHelp('列出项目组；可按名称关键词过滤', {
+      examples: ['lj-awb project list', 'lj-awb project list --name "测试"'],
+    }),
+    args: [
+      { name: 'name', valueName: 'keyword', description: '按项目组名称或编号过滤' },
+    ],
+    func: async (_ctx, kwargs) => listProjectGroups(kwargs),
+  });
+
+  cli({
+    name: 'project current',
+    description: commandHelp('查看云端当前项目组和项目组预算', {
+      examples: ['lj-awb project current'],
+    }),
+    args: [PROJECT_GROUP_ARG],
+    func: async (_ctx, kwargs) => fetchProjectGroupSummary(kwargs.projectGroupNo),
+  });
+
+  cli({
+    name: 'project use',
+    description: commandHelp('切换当前项目组；后续生成任务会归属到该项目组', {
+      examples: ['lj-awb project use --project-group-no <no> --dry-run', 'lj-awb project use --project-group-no <no> --yes'],
+    }),
+    args: [
+      PROJECT_GROUP_ARG,
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => selectProjectGroupCommand(kwargs),
+  });
+
+  cli({
+    name: 'project users',
+    description: commandHelp('列出创建项目组时可选成员', {
+      examples: ['lj-awb project users'],
+    }),
+    args: [],
+    func: async () => ({ users: normalizeRows(await fetchProjectGroupUsers()) }),
+  });
+
+  cli({
+    name: 'project create',
+    description: commandHelp('创建并切换到新项目组', {
+      examples: [
+        'lj-awb project create --name "CLI 测试项目" --point 1000 --dry-run',
+        'lj-awb project create --name "CLI 测试项目" --point 1000 --yes',
+      ],
+    }),
+    args: [
+      { name: 'name', valueName: 'name', description: '项目组名称' },
+      { name: 'point', valueName: 'num', description: '项目组积分上限，默认 0' },
+      { name: 'user-ids', valueName: 'ids', description: '额外成员 userId，逗号分隔' },
+      { name: 'members-json', valueName: 'json', description: '直接传 groupUser JSON 数组' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => createProjectGroupCommand(kwargs),
+  });
+
+  cli({
+    name: 'project update',
+    description: commandHelp('修改项目组名称或积分上限', {
+      examples: [
+        'lj-awb project update --project-group-no <no> --point 1000 --dry-run',
+        'lj-awb project update --project-group-no <no> --name "新名称" --yes',
+      ],
+    }),
+    args: [
+      PROJECT_GROUP_ARG,
+      { name: 'name', valueName: 'name', description: '新的项目组名称' },
+      { name: 'point', valueName: 'num', description: '新的项目组积分上限' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => updateProjectGroupCommand(kwargs),
+  });
+
+  cli({
+    name: 'project ensure',
+    description: commandHelp('确保项目组存在：先查找同名项目组，找不到再创建', {
+      examples: [
+        'lj-awb project ensure --name "短剧项目A" --point 1000 --dry-run',
+        'lj-awb project ensure --name "短剧项目A" --point 1000 --yes',
+      ],
+    }),
+    args: [
+      { name: 'name', valueName: 'name', description: '目标项目组名称' },
+      { name: 'point', valueName: 'num', description: '不存在时创建的积分上限' },
+      { name: 'user-ids', valueName: 'ids', description: '额外成员 userId，逗号分隔' },
+      { name: 'members-json', valueName: 'json', description: '直接传 groupUser JSON 数组' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => ensureProjectGroupCommand(kwargs),
+  });
+
+  cli({
+    name: 'credits balance',
+    description: commandHelp('查看可扣积分余额和项目组预算', {
+      examples: ['lj-awb credits balance', 'lj-awb credits balance --project-group-no <no>'],
+    }),
+    args: [PROJECT_GROUP_ARG],
+    func: async (_ctx, kwargs) => creditsBalance(kwargs),
+  });
+
+  cli({
+    name: 'credits usage',
+    description: commandHelp('按项目组汇总图片 / 视频任务数与积分消耗', {
+      examples: [
+        'lj-awb credits usage --project-group-no <no> --last-hours 24',
+        'lj-awb credits usage --project-group-no <no> --task-types IMAGE_CREATE,VIDEO_GROUP --include-tasks',
+      ],
+    }),
+    args: [
+      PROJECT_GROUP_ARG,
+      { name: 'task-types', valueName: 'types', description: '任务类型，逗号分隔；默认 IMAGE_CREATE,IMAGE_EDIT,VIDEO_GROUP' },
+      { name: 'since', valueName: 'time', description: '开始时间，支持 ISO 或 2026-05-07 00:00:00' },
+      { name: 'since-ms', valueName: 'ms', description: '开始时间戳' },
+      { name: 'until', valueName: 'time', description: '结束时间' },
+      { name: 'last-hours', valueName: 'hours', description: '最近 N 小时' },
+      { name: 'page-size', valueName: 'n', description: '每次拉取任务数，最大 200' },
+      { name: 'include-tasks', description: 'JSON 中附带扫描到的任务明细' },
+    ],
+    func: async (_ctx, kwargs) => creditsUsageSummary(kwargs),
+  });
+
+  cli({
+    name: 'model image-models',
+    description: commandHelp('查询可用生图模型', {
+      examples: ['lj-awb model image-models', 'lj-awb model image-models --model Banana', 'lj-awb model image-models --all'],
+    }),
+    args: MODEL_LIST_ARGS,
+    func: async (_ctx, kwargs) => listModels('image', kwargs),
+  });
+
+  cli({
+    name: 'model video-models',
+    description: commandHelp('查询可用生视频模型', {
+      examples: ['lj-awb model video-models', 'lj-awb model video-models --model Seedance', 'lj-awb model video-models --all'],
+    }),
+    args: MODEL_LIST_ARGS,
+    func: async (_ctx, kwargs) => listModels('video', kwargs),
+  });
+
+  cli({
+    name: 'model options',
+    description: commandHelp('查询指定模型支持的 CLI 参数、枚举值、素材约束和条件约束', {
+      examples: [
+        'lj-awb model options --model-group-code <code>',
+        'lj-awb model options --model-group-code <code> --selected-configs-json \'{"quality":"720"}\'',
+      ],
+      hint: '用 options 判断 values、fileTypes、maxFiles、duration、constraints 等约束；如何组装 create 命令看 model create-spec。',
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      { name: 'selected-configs-json', valueName: 'json', description: '已选参数 JSON，用于联动查询模型选项' },
+      INCLUDE_RAW_ARG,
+    ],
+    func: async (_ctx, kwargs) => modelOptions(kwargs),
+  });
+
+  cli({
+    name: 'model create-spec',
+    description: commandHelp('查看指定模型如何创建任务：输入模式、素材绑定规则、示例和前置步骤', {
+      examples: [
+        'lj-awb model create-spec --model-group-code <code>',
+      ],
+      hint: '创建前先用 model input-guide 理解统一参数，再用 model options 查具体枚举和素材限制，最后按 create-spec 组装 image create / video create。',
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      INCLUDE_RAW_ARG,
+    ],
+    func: async (_ctx, kwargs) => modelCreateSpec(kwargs),
+  });
+
+  cli({
+    name: 'model input-guide',
+    description: commandHelp('查看统一创建参数和 resources 素材绑定的通用说明', {
+      examples: [
+        'lj-awb model input-guide',
+      ],
+      hint: '这是跨模型的统一参数说明；具体枚举值、文件类型、数量和条件约束仍以 model options 为准。',
+    }),
+    args: [],
+    func: async () => modelInputGuide(),
+  });
+
+  cli({
+    name: 'upload files',
+    description: commandHelp('上传本地图片 / 视频 / 音频到平台 COS，并返回 backendPath / URL', {
+      examples: [
+        'lj-awb upload files --files ./a.png,./b.mp4 --dry-run',
+        'lj-awb upload files --file ./ref.png --scene-type material-video-create',
+      ],
+      hint: '不会暴露 COS 临时密钥；skill 只使用返回的 backendPath / url。',
+    }),
+    args: [
+      { name: 'file', valueName: 'path', description: '单个文件路径' },
+      { name: 'files', valueName: 'paths', description: '多个文件路径，逗号分隔' },
+      { name: 'files-json', valueName: 'path|json', description: '文件数组 JSON 或 JSON 文件路径' },
+      { name: 'scene-type', valueName: 'scene', description: '上传场景，默认 material-image-edit' },
+      { name: 'project-no', valueName: 'no', description: '可选项目组编号；不传时读取当前项目组 / 环境变量 / 本地状态' },
+      DRY_RUN_ARG,
+    ],
+    func: async (_ctx, kwargs) => uploadFilesCommand(kwargs),
+  });
+
+  cli({
+    name: 'image fee',
+    description: commandHelp('计算生图预计积分（必须有 --prompt；参考图通过 --resource 传入）', {
+      examples: ['lj-awb image fee --model-group-code <code> --prompt "一只小狗" --ratio 9:16 --quality 2K'],
+      hint: '估价前先确认 quality、ratio、generate-num 等会影响积分的关键参数。',
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      { name: 'prompt', valueName: 'text', description: '生图提示词；默认原样透传，不润色' },
+      { name: 'ratio', valueName: 'ratio', description: '画幅比例，如 9:16' },
+      { name: 'quality', valueName: 'quality', description: '清晰度，如 2K' },
+      { name: 'generate-num', valueName: 'n', description: '生成张数' },
+      RESOURCE_ARG,
+      RESOURCES_JSON_ARG,
+      FEE_DRY_RUN_ARG,
+    ],
+    func: async (_ctx, kwargs) => imageFee(kwargs),
+  });
+
+  cli({
+    name: 'image create',
+    description: commandHelp('提交生图任务；正式执行需要 --yes', {
+      examples: [
+        'lj-awb image create --model-group-code <code> --prompt "一只小狗" --dry-run',
+        'lj-awb image create --model-group-code <code> --prompt "参考图里的角色奔跑" --resource image:reference=./ref.png --project-group-no <no> --yes',
+        'lj-awb image create --model-group-code <code> --prompt "产品海报" --resources-json \'[{"type":"image","usage":"reference","source":{"kind":"url","value":"./product.jpg"}}]\' --dry-run',
+      ],
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      CUSTOM_BIZ_ARG,
+      { name: 'prompt', valueName: 'text', description: '生图提示词；默认原样透传，不润色' },
+      { name: 'ratio', valueName: 'ratio', description: '画幅比例' },
+      { name: 'quality', valueName: 'quality', description: '清晰度' },
+      { name: 'generate-num', valueName: 'n', description: '生成张数' },
+      RESOURCE_ARG,
+      RESOURCES_JSON_ARG,
+      TASK_RECORD_ARG,
+      ...CREATE_WAIT_ARGS,
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => imageCreate(kwargs),
+  });
+
+  cli({
+    name: 'image create-batch',
+    description: commandHelp('批量提交生图任务；输入支持 JSON / JSONL / 纯文本 prompt（每行一条）', {
+      examples: [
+        'lj-awb image create-batch --input-file ./prompts.txt --model-group-code <code> --dry-run',
+        'lj-awb image create-batch --input-file ./image-input.jsonl --model-group-code <code> --concurrency 3 --yes',
+      ],
+      hint: 'JSON/JSONL 每项只写任务差异字段：prompt、ratio、quality、generate_num、resources、resource、customBizId。',
+    }),
+    args: [
+      { name: 'input-file', valueName: 'path', description: '批量输入文件' },
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      { name: 'concurrency', valueName: 'n', description: '并发数，默认 1' },
+      TASK_RECORD_ARG,
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => imageCreateBatch(kwargs),
+  });
+
+  cli({
+    name: 'image status',
+    description: commandHelp('查询生图任务状态', {
+      examples: ['lj-awb image status --task-id <id>'],
+    }),
+    args: [
+      { name: 'task-id', valueName: 'id', description: '任务 ID' },
+    ],
+    func: async (_ctx, kwargs) => taskStatus({ ...kwargs, taskType: 'IMAGE_CREATE' }),
+  });
+
+  cli({
+    name: 'video fee',
+    description: commandHelp('计算生视频预计积分（--prompt / --resource / --resources-json 至少传一个）', {
+      examples: ['lj-awb video fee --model-group-code <code> --prompt "雨夜奔跑" --duration 5 --quality 720 --ratio 9:16'],
+      hint: '估价前先确认 quality、duration、ratio 等会影响积分的关键参数。',
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      { name: 'prompt', valueName: 'text', description: '视频提示词；默认原样透传，不润色（和 --resource / --resources-json 至少传一个）' },
+      { name: 'ratio', valueName: 'ratio', description: '视频比例' },
+      { name: 'quality', valueName: 'quality', description: '清晰度，如 720' },
+      { name: 'duration', valueName: 'seconds', description: '生成时长秒数' },
+      { name: 'need-audio', valueName: 'bool', description: '输出音效开关：是否让模型在视频中生成音效（true/false）。不接收音频文件；参考音频请用 --resource audio:reference=...' },
+      RESOURCE_ARG,
+      RESOURCES_JSON_ARG,
+      FEE_DRY_RUN_ARG,
+    ],
+    func: async (_ctx, kwargs) => videoFee(kwargs),
+  });
+
+  cli({
+    name: 'video create',
+    description: commandHelp('提交生视频任务；正式执行需要 --yes', {
+      examples: [
+        'lj-awb video create --model-group-code <code> --prompt "雨夜奔跑" --dry-run',
+        'lj-awb video create --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=./actor.png --duration 5 --yes',
+        'lj-awb video create --model-group-code <code> --prompt "首尾帧过渡" --duration 5 --resources-json \'[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"./first.png"}},{"type":"image","usage":"last_frame","source":{"kind":"url","value":"./last.png"}}]\' --dry-run',
+        'lj-awb video create --model-group-code <code> --prompt "让 <<<hero>>> 跟随音乐节奏转身" --resource image:reference:hero=./actor.png --resource audio:reference=./music.mp3 --duration 5 --dry-run',
+      ],
+      hint: '--prompt / --resource / --resources-json 至少传一个；fee / --dry-run 之前先确认 quality、duration、ratio 等关键参数。',
+    }),
+    args: [
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      CUSTOM_BIZ_ARG,
+      { name: 'prompt', valueName: 'text', description: '视频提示词；默认原样透传，不润色（和 --resource / --resources-json 至少传一个）' },
+      { name: 'ratio', valueName: 'ratio', description: '视频比例' },
+      { name: 'quality', valueName: 'quality', description: '清晰度' },
+      { name: 'duration', valueName: 'seconds', description: '生成时长秒数' },
+      { name: 'need-audio', valueName: 'bool', description: '输出音效开关：是否让模型在视频中生成音效（true/false）。不接收音频文件；参考音频请用 --resource audio:reference=...' },
+      RESOURCE_ARG,
+      RESOURCES_JSON_ARG,
+      TASK_RECORD_ARG,
+      ...CREATE_WAIT_ARGS,
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => videoCreate(kwargs),
+  });
+
+  cli({
+    name: 'video create-batch',
+    description: commandHelp('批量提交生视频任务；输入支持 JSON / JSONL / 纯文本 prompt（每行一条）', {
+      examples: [
+        'lj-awb video create-batch --input-file ./prompts.txt --model-group-code <code> --dry-run',
+        'lj-awb video create-batch --input-file ./video-input.jsonl --model-group-code <code> --concurrency 2 --yes',
+      ],
+      hint: 'JSON/JSONL 每项只写任务差异字段：prompt、ratio、quality、duration、need_audio、resources、resource、customBizId。',
+    }),
+    args: [
+      { name: 'input-file', valueName: 'path', description: '批量输入文件' },
+      MODEL_GROUP_ARG,
+      PROJECT_GROUP_ARG,
+      { name: 'concurrency', valueName: 'n', description: '并发数，默认 1' },
+      TASK_RECORD_ARG,
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => videoCreateBatch(kwargs),
+  });
+
+  cli({
+    name: 'video status',
+    description: commandHelp('查询生视频任务状态', {
+      examples: ['lj-awb video status --task-id <id>'],
+    }),
+    args: [{ name: 'task-id', valueName: 'id', description: '任务 ID' }],
+    func: async (_ctx, kwargs) => taskStatus({ ...kwargs, taskType: 'VIDEO_GROUP' }),
+  });
+
+  cli({
+    name: 'video subtitle-remove',
+    description: commandHelp('提交视频去字幕 / 去水印任务', {
+      examples: ['lj-awb video subtitle-remove --video-url "https://..." --dry-run'],
+      hint: '该能力走 asset-edit.lingjingai.cn，适合 Seedance 原始结果后处理。',
+    }),
+    args: [
+      { name: 'video-url', valueName: 'url', description: '待处理视频 URL' },
+      { name: 'name', valueName: 'name', description: '可选任务名' },
+      { name: 'callback-url', valueName: 'url', description: '可选回调 URL' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => subtitleRemove(kwargs),
+  });
+
+  cli({
+    name: 'video subtitle-status',
+    description: commandHelp('查询去字幕 / 去水印任务状态', {
+      examples: ['lj-awb video subtitle-status --remote-task-id <id>', 'lj-awb video subtitle-status --public-id <id>'],
+    }),
+    args: [
+      { name: 'remote-task-id', valueName: 'id', description: '远端任务 ID' },
+      { name: 'public-id', valueName: 'id', description: '公开任务 ID' },
+    ],
+    func: async (_ctx, kwargs) => subtitleStatus(kwargs),
+  });
+
+  cli({
+    name: 'task list',
+    description: commandHelp('查询项目组近期任务流', {
+      examples: ['lj-awb task list --task-type IMAGE_CREATE --project-group-no <no>'],
+    }),
+    args: [
+      { name: 'task-type', valueName: 'type', description: 'IMAGE_CREATE / IMAGE_EDIT / VIDEO_GROUP' },
+      PROJECT_GROUP_ARG,
+      { name: 'page-size', valueName: 'n', description: '每页任务数' },
+      { name: 'min-time', valueName: 'ms', description: '任务流 minTime，默认当前时间' },
+    ],
+    func: async (_ctx, kwargs) => taskList(kwargs),
+  });
+
+  cli({
+    name: 'task wait',
+    description: commandHelp('等待图片或视频任务进入终态', {
+      examples: ['lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180'],
+      hint: '超时返回 task_still_running / exit code 20，不代表远端失败。',
+    }),
+    args: [
+      { name: 'task-id', valueName: 'id', description: '任务 ID' },
+      { name: 'task-type', valueName: 'type', description: 'IMAGE_CREATE / VIDEO_GROUP' },
+      PROJECT_GROUP_ARG,
+      ...TASK_WAIT_ARGS,
+    ],
+    func: async (_ctx, kwargs) => waitTask(kwargs),
+  });
+
+  cli({
+    name: 'task records',
+    description: commandHelp('读取本地任务台账 JSONL', {
+      examples: ['lj-awb task records --task-record-file .awb/tasks.jsonl'],
+    }),
+    args: [
+      TASK_RECORD_ARG,
+      { name: 'task-type', valueName: 'type', description: '按任务类型过滤' },
+      { name: 'pending-only', description: '只看未终态记录' },
+      { name: 'limit', valueName: 'n', description: '最多返回条数' },
+    ],
+    func: async (_ctx, kwargs) => taskRecords(kwargs),
+  });
+
+  cli({
+    name: 'task record-poll',
+    description: commandHelp('根据本地任务台账轮询任务状态', {
+      examples: ['lj-awb task record-poll --task-record-file .awb/tasks.jsonl --wait-seconds 180'],
+    }),
+    args: [
+      TASK_RECORD_ARG,
+      { name: 'task-type', valueName: 'type', description: '按任务类型过滤' },
+      { name: 'pending-only', description: '只轮询未终态记录，默认 true' },
+      ...RECORD_POLL_ARGS,
+    ],
+    func: async (_ctx, kwargs) => taskRecordPoll(kwargs),
+  });
+
+  cli({
+    name: 'asset match-actor',
+    description: commandHelp('按描述和标签匹配平台素材库角色候选', {
+      examples: ['lj-awb asset match-actor --description "十八岁少女，古风，清冷" --tags-json \'{"gender":"女"}\''],
+    }),
+    args: [
+      { name: 'description', valueName: 'text', description: '角色 / 状态描述' },
+      { name: 'tags-json', valueName: 'json', description: '标签 JSON' },
+      { name: 'tag-weight', valueName: 'num', description: '标签权重，默认 0.5' },
+      { name: 'desc-weight', valueName: 'num', description: '描述权重，默认 0.5' },
+      INCLUDE_RAW_ARG,
+    ],
+    func: async (_ctx, kwargs) => assetMatchActor(kwargs),
+  });
+
+  cli({
+    name: 'asset groups',
+    description: commandHelp('查询素材组', {
+      examples: ['lj-awb asset groups --name "女主"'],
+    }),
+    args: [
+      { name: 'name', valueName: 'keyword', description: '素材组名称关键词' },
+      { name: 'group-ids', valueName: 'ids', description: '素材组 ID，逗号分隔' },
+      { name: 'page-number', valueName: 'n', description: '页码' },
+      { name: 'page-size', valueName: 'n', description: '每页数量' },
+      INCLUDE_RAW_ARG,
+    ],
+    func: async (_ctx, kwargs) => assetGroupList(kwargs),
+  });
+
+  cli({
+    name: 'asset group',
+    description: commandHelp('查看素材组详情', {
+      examples: ['lj-awb asset group --group-id <id>'],
+    }),
+    args: [{ name: 'group-id', valueName: 'id', description: '素材组 ID' }],
+    func: async (_ctx, kwargs) => assetGroupGet(kwargs),
+  });
+
+  cli({
+    name: 'asset group-create',
+    description: commandHelp('创建素材组（用于素材注册时作为命名空间）', {
+      examples: [
+        'lj-awb asset group-create --name "女主素材组" --dry-run',
+        'lj-awb asset group-create --name "女主素材组" --description "用于第二集女主相关素材" --yes',
+      ],
+    }),
+    args: [
+      { name: 'name', valueName: 'name', description: '素材组名称' },
+      { name: 'description', valueName: 'text', description: '素材组描述' },
+      { name: 'project-name', valueName: 'name', description: '项目名，默认 default' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => assetGroupCreate(kwargs),
+  });
+
+  cli({
+    name: 'asset group-update',
+    description: commandHelp('更新素材组名称 / 描述', {
+      examples: ['lj-awb asset group-update --group-id <id> --name "新名称" --dry-run'],
+    }),
+    args: [
+      { name: 'group-id', valueName: 'id', description: '素材组 ID' },
+      { name: 'name', valueName: 'name', description: '新名称' },
+      { name: 'description', valueName: 'text', description: '新描述' },
+      { name: 'project-name', valueName: 'name', description: '项目名' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => assetGroupUpdate(kwargs),
+  });
+
+  cli({
+    name: 'asset register',
+    description: commandHelp('把 COS 路径 / URL / 本地文件注册成平台素材', {
+      examples: ['lj-awb asset register --group-id <id> --url "material/upload/a.png" --name "女主正面" --dry-run'],
+    }),
+    args: [
+      { name: 'group-id', valueName: 'id', description: '素材组 ID' },
+      { name: 'name', valueName: 'name', description: '素材名称' },
+      { name: 'file', valueName: 'path', description: '本地素材文件；会先上传' },
+      { name: 'url', valueName: 'url', description: '素材 URL 或 COS 路径' },
+      { name: 'backend-path', valueName: 'path', description: 'upload files 返回的 backendPath' },
+      { name: 'platform', valueName: 'platform', description: '可选平台字段' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => assetRegister(kwargs),
+  });
+
+  const ARTIFACT_ROW_KIND_ARG = { name: 'row-kind', valueName: 'kind', description: 'document/asset/state/speaker/episode/scene/action' };
+  const ARTIFACT_ENTITY_KEY_ARG = { name: 'entity-key', valueName: 'key', description: '业务唯一键；可包含 / 和 #' };
+  const ARTIFACT_EPISODE_ARG = { name: 'episode-id', valueName: 'id', description: '集 ID，例如 ep_001' };
+  const ARTIFACT_SCENE_ARG = { name: 'scene-id', valueName: 'id', description: '场 ID，例如 scn_001' };
+  const ARTIFACT_CLIP_ARG = { name: 'clip-id', valueName: 'id', description: 'clip ID，例如 clip_001' };
+  const ARTIFACT_VIDEO_EPISODE_ID_ARG = { name: 'video-episode-id', valueName: 'id', description: '视频集产物的数字主键，由 artifact video upsert-episode / artifact video episode 返回的 id 字段提供（不是 ep_001 这种业务 ID）' };
+  const ARTIFACT_INCLUDE_STATES_ARG = { name: 'include-states', valueName: 'bool', description: '是否带 states，默认 true' };
+
+  for (const spec of [
+    {
+      name: 'artifact script get',
+      summary: '查询项目完整剧本最终产物',
+      examples: ['lj-awb artifact script get --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactScriptGet,
+    },
+    {
+      name: 'artifact script document',
+      summary: '查询剧本 document 根记录',
+      examples: ['lj-awb artifact script document --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactScriptDocument,
+    },
+    {
+      name: 'artifact script rows',
+      summary: '查询剧本最终产物行列表',
+      examples: [
+        'lj-awb artifact script rows --project-id <projectId> --row-kind scene',
+        'lj-awb artifact script rows --project-id <projectId> --row-kind action --parent-key scn_001',
+      ],
+      args: [
+        PROJECT_ID_ARG,
+        ARTIFACT_ROW_KIND_ARG,
+        { name: 'parent-key', valueName: 'key', description: '按父节点业务键过滤' },
+        { name: 'revision-after', valueName: 'n', description: '只查 revisionNo 大于该值的行' },
+        { name: 'include-deleted', valueName: 'bool', description: '是否包含逻辑删除行，默认 false' },
+      ],
+      func: artifact.artifactScriptRows,
+    },
+    {
+      name: 'artifact script row',
+      summary: '查询单条剧本最终产物行',
+      examples: ['lj-awb artifact script row --project-id <projectId> --row-kind action --entity-key "ep_001/scn_001#0"'],
+      args: [PROJECT_ID_ARG, ARTIFACT_ROW_KIND_ARG, ARTIFACT_ENTITY_KEY_ARG],
+      func: artifact.artifactScriptRow,
+    },
+    {
+      name: 'artifact script children',
+      summary: '按 parentKey 查询剧本子节点',
+      examples: ['lj-awb artifact script children --project-id <projectId> --parent-key scn_001 --row-kind action'],
+      args: [
+        PROJECT_ID_ARG,
+        { name: 'parent-key', valueName: 'key', description: '父节点业务键' },
+        ARTIFACT_ROW_KIND_ARG,
+      ],
+      func: artifact.artifactScriptChildren,
+    },
+    {
+      name: 'artifact script upsert-row',
+      summary: '新增或更新单条剧本最终产物行',
+      examples: ['lj-awb artifact script upsert-row --project-id <projectId> --input-file ./row.json --dry-run', 'lj-awb artifact script upsert-row --project-id <projectId> --input-file ./row.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactScriptUpsertRow,
+    },
+    {
+      name: 'artifact script delete-row',
+      summary: '逻辑删除单条剧本最终产物行',
+      examples: ['lj-awb artifact script delete-row --project-id <projectId> --row-kind action --entity-key "ep_001/scn_001#0" --dry-run', 'lj-awb artifact script delete-row --project-id <projectId> --row-kind action --entity-key "ep_001/scn_001#0" --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_ROW_KIND_ARG, ARTIFACT_ENTITY_KEY_ARG, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactScriptDeleteRow,
+    },
+    {
+      name: 'artifact script import',
+      summary: '从本地 script.json 拆分并批量导入剧本最终产物',
+      examples: [
+        'lj-awb artifact script import --project-id <projectId> --input-file 1_script/output/script.json --dry-run',
+        'lj-awb artifact script import --project-id <projectId> --input-file output/script.json --yes',
+      ],
+      args: [
+        PROJECT_ID_ARG,
+        { name: 'input-file', valueName: 'path', description: 'script.json 路径，默认 output/script.json' },
+        ...ARTIFACT_WRITE_ARGS,
+      ],
+      func: artifact.artifactScriptImport,
+      hint: '不传 --input-file 时默认读取当前目录的 output/script.json。',
+    },
+  ]) {
+    cli({
+      name: spec.name,
+      description: commandHelp(spec.summary, { examples: spec.examples, hint: spec.hint }),
+      args: spec.args,
+      func: async (_ctx, kwargs) => spec.func(kwargs),
+    });
+  }
+
+  for (const spec of [
+    {
+      name: 'artifact asset get',
+      summary: '查询项目完整资产最终产物',
+      examples: ['lj-awb artifact asset get --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactAssetGet,
+    },
+    {
+      name: 'artifact asset actors',
+      summary: '查询角色最终产物列表',
+      examples: ['lj-awb artifact asset actors --project-id <projectId> --include-states true'],
+      args: [PROJECT_ID_ARG, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetActors,
+    },
+    {
+      name: 'artifact asset actor',
+      summary: '查询单个角色最终产物',
+      examples: ['lj-awb artifact asset actor --project-id <projectId> --actor-key act_001'],
+      args: [PROJECT_ID_ARG, { name: 'actor-key', valueName: 'key', description: '角色业务键' }, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetActor,
+    },
+    {
+      name: 'artifact asset props',
+      summary: '查询道具最终产物列表',
+      examples: ['lj-awb artifact asset props --project-id <projectId>'],
+      args: [PROJECT_ID_ARG, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetProps,
+    },
+    {
+      name: 'artifact asset prop',
+      summary: '查询单个道具最终产物',
+      examples: ['lj-awb artifact asset prop --project-id <projectId> --prop-key prp_001'],
+      args: [PROJECT_ID_ARG, { name: 'prop-key', valueName: 'key', description: '道具业务键' }, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetProp,
+    },
+    {
+      name: 'artifact asset locations',
+      summary: '查询场景最终产物列表',
+      examples: ['lj-awb artifact asset locations --project-id <projectId>'],
+      args: [PROJECT_ID_ARG, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetLocations,
+    },
+    {
+      name: 'artifact asset location',
+      summary: '查询单个场景最终产物',
+      examples: ['lj-awb artifact asset location --project-id <projectId> --location-key loc_001'],
+      args: [PROJECT_ID_ARG, { name: 'location-key', valueName: 'key', description: '场景业务键' }, ARTIFACT_INCLUDE_STATES_ARG],
+      func: artifact.artifactAssetLocation,
+    },
+    {
+      name: 'artifact asset upsert-actor',
+      summary: '新增或更新角色最终产物',
+      examples: ['lj-awb artifact asset upsert-actor --project-id <projectId> --input-file ./actor.json --dry-run', 'lj-awb artifact asset upsert-actor --project-id <projectId> --input-file ./actor.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertActor,
+    },
+    {
+      name: 'artifact asset upsert-prop',
+      summary: '新增或更新道具最终产物',
+      examples: ['lj-awb artifact asset upsert-prop --project-id <projectId> --input-file ./prop.json --dry-run', 'lj-awb artifact asset upsert-prop --project-id <projectId> --input-file ./prop.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertProp,
+    },
+    {
+      name: 'artifact asset upsert-location',
+      summary: '新增或更新场景最终产物',
+      examples: ['lj-awb artifact asset upsert-location --project-id <projectId> --input-file ./location.json --dry-run', 'lj-awb artifact asset upsert-location --project-id <projectId> --input-file ./location.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertLocation,
+    },
+    {
+      name: 'artifact asset upsert-actor-state',
+      summary: '新增或更新角色状态最终产物',
+      examples: ['lj-awb artifact asset upsert-actor-state --project-id <projectId> --actor-key act_001 --input-file ./state.json --dry-run', 'lj-awb artifact asset upsert-actor-state --project-id <projectId> --actor-key act_001 --input-file ./state.json --yes'],
+      args: [PROJECT_ID_ARG, { name: 'actor-key', valueName: 'key', description: '角色业务键' }, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertActorState,
+    },
+    {
+      name: 'artifact asset upsert-prop-state',
+      summary: '新增或更新道具状态最终产物',
+      examples: ['lj-awb artifact asset upsert-prop-state --project-id <projectId> --prop-key prp_001 --input-file ./state.json --dry-run', 'lj-awb artifact asset upsert-prop-state --project-id <projectId> --prop-key prp_001 --input-file ./state.json --yes'],
+      args: [PROJECT_ID_ARG, { name: 'prop-key', valueName: 'key', description: '道具业务键' }, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertPropState,
+    },
+    {
+      name: 'artifact asset upsert-location-state',
+      summary: '新增或更新场景状态最终产物',
+      examples: ['lj-awb artifact asset upsert-location-state --project-id <projectId> --location-key loc_001 --input-file ./state.json --dry-run', 'lj-awb artifact asset upsert-location-state --project-id <projectId> --location-key loc_001 --input-file ./state.json --yes'],
+      args: [PROJECT_ID_ARG, { name: 'location-key', valueName: 'key', description: '场景业务键' }, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetUpsertLocationState,
+    },
+    {
+      name: 'artifact asset delete-actor',
+      summary: '逻辑删除角色及其状态最终产物',
+      examples: ['lj-awb artifact asset delete-actor --project-id <projectId> --actor-key act_001 --dry-run', 'lj-awb artifact asset delete-actor --project-id <projectId> --actor-key act_001 --yes'],
+      args: [PROJECT_ID_ARG, { name: 'actor-key', valueName: 'key', description: '角色业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeleteActor,
+    },
+    {
+      name: 'artifact asset delete-prop',
+      summary: '逻辑删除道具及其状态最终产物',
+      examples: ['lj-awb artifact asset delete-prop --project-id <projectId> --prop-key prp_001 --dry-run', 'lj-awb artifact asset delete-prop --project-id <projectId> --prop-key prp_001 --yes'],
+      args: [PROJECT_ID_ARG, { name: 'prop-key', valueName: 'key', description: '道具业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeleteProp,
+    },
+    {
+      name: 'artifact asset delete-location',
+      summary: '逻辑删除场景及其状态最终产物',
+      examples: ['lj-awb artifact asset delete-location --project-id <projectId> --location-key loc_001 --dry-run', 'lj-awb artifact asset delete-location --project-id <projectId> --location-key loc_001 --yes'],
+      args: [PROJECT_ID_ARG, { name: 'location-key', valueName: 'key', description: '场景业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeleteLocation,
+    },
+    {
+      name: 'artifact asset delete-actor-state',
+      summary: '逻辑删除角色状态最终产物',
+      examples: ['lj-awb artifact asset delete-actor-state --project-id <projectId> --actor-key act_001 --state-key default --dry-run', 'lj-awb artifact asset delete-actor-state --project-id <projectId> --actor-key act_001 --state-key default --yes'],
+      args: [PROJECT_ID_ARG, { name: 'actor-key', valueName: 'key', description: '角色业务键' }, { name: 'state-key', valueName: 'key', description: '状态业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeleteActorState,
+    },
+    {
+      name: 'artifact asset delete-prop-state',
+      summary: '逻辑删除道具状态最终产物',
+      examples: ['lj-awb artifact asset delete-prop-state --project-id <projectId> --prop-key prp_001 --state-key default --dry-run', 'lj-awb artifact asset delete-prop-state --project-id <projectId> --prop-key prp_001 --state-key default --yes'],
+      args: [PROJECT_ID_ARG, { name: 'prop-key', valueName: 'key', description: '道具业务键' }, { name: 'state-key', valueName: 'key', description: '状态业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeletePropState,
+    },
+    {
+      name: 'artifact asset delete-location-state',
+      summary: '逻辑删除场景状态最终产物',
+      examples: ['lj-awb artifact asset delete-location-state --project-id <projectId> --location-key loc_001 --state-key default --dry-run', 'lj-awb artifact asset delete-location-state --project-id <projectId> --location-key loc_001 --state-key default --yes'],
+      args: [PROJECT_ID_ARG, { name: 'location-key', valueName: 'key', description: '场景业务键' }, { name: 'state-key', valueName: 'key', description: '状态业务键' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactAssetDeleteLocationState,
+    },
+    {
+      name: 'artifact asset import',
+      summary: '从本地 actors/props/locations JSON 批量导入资产最终产物',
+      examples: [
+        'lj-awb artifact asset import --project-id <projectId> --input-dir 2_asset/output --dry-run',
+        'lj-awb artifact asset import --project-id <projectId> --actors-file output/actors/actors.json --props-file output/props/props.json --locations-file output/locations/locations.json --yes',
+      ],
+      args: [
+        PROJECT_ID_ARG,
+        { name: 'input-dir', valueName: 'path', description: '资产 output 目录，默认 output' },
+        { name: 'actors-file', valueName: 'path', description: '可选 actors.json 路径' },
+        { name: 'props-file', valueName: 'path', description: '可选 props.json 路径' },
+        { name: 'locations-file', valueName: 'path', description: '可选 locations.json 路径' },
+        ...ARTIFACT_WRITE_ARGS,
+      ],
+      func: artifact.artifactAssetImport,
+      hint: '默认在 --input-dir 下查找 actors/actors.json、props/props.json、locations/locations.json；也兼容 actors.json 等扁平文件名。',
+    },
+  ]) {
+    cli({
+      name: spec.name,
+      description: commandHelp(spec.summary, { examples: spec.examples, hint: spec.hint }),
+      args: spec.args,
+      func: async (_ctx, kwargs) => spec.func(kwargs),
+    });
+  }
+
+  for (const spec of [
+    {
+      name: 'artifact video get',
+      summary: '查询项目完整视频最终产物',
+      examples: ['lj-awb artifact video get --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactVideoGet,
+    },
+    {
+      name: 'artifact video episodes',
+      summary: '查询视频集列表',
+      examples: ['lj-awb artifact video episodes --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactVideoEpisodes,
+    },
+    {
+      name: 'artifact video episode',
+      summary: '查询单集视频最终产物',
+      examples: ['lj-awb artifact video episode --project-id <projectId> --episode-id ep_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG],
+      func: artifact.artifactVideoEpisode,
+    },
+    {
+      name: 'artifact video scenes',
+      summary: '查询某集下的场列表',
+      examples: ['lj-awb artifact video scenes --project-id <projectId> --episode-id ep_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG],
+      func: artifact.artifactVideoScenes,
+    },
+    {
+      name: 'artifact video scene',
+      summary: '查询单场视频最终产物',
+      examples: ['lj-awb artifact video scene --project-id <projectId> --episode-id ep_001 --scene-id scn_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG],
+      func: artifact.artifactVideoScene,
+    },
+    {
+      name: 'artifact video clips',
+      summary: '查询某场下的 clip 列表',
+      examples: ['lj-awb artifact video clips --project-id <projectId> --episode-id ep_001 --scene-id scn_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG],
+      func: artifact.artifactVideoClips,
+    },
+    {
+      name: 'artifact video clip',
+      summary: '查询单个 clip 视频最终产物',
+      examples: ['lj-awb artifact video clip --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG, ARTIFACT_CLIP_ARG],
+      func: artifact.artifactVideoClip,
+    },
+    {
+      name: 'artifact video upsert-episode',
+      summary: '新增或更新视频 episode 最终产物',
+      examples: ['lj-awb artifact video upsert-episode --project-id <projectId> --input-file ./episode.json --dry-run', 'lj-awb artifact video upsert-episode --project-id <projectId> --input-file ./episode.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoUpsertEpisode,
+    },
+    {
+      name: 'artifact video upsert-scene',
+      summary: '新增或更新视频 scene 最终产物',
+      examples: ['lj-awb artifact video upsert-scene --project-id <projectId> --episode-id ep_001 --input-file ./scene.json --dry-run', 'lj-awb artifact video upsert-scene --project-id <projectId> --episode-id ep_001 --input-file ./scene.json --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoUpsertScene,
+    },
+    {
+      name: 'artifact video upsert-clip',
+      summary: '新增或更新视频 clip 最终产物',
+      examples: ['lj-awb artifact video upsert-clip --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --input-file ./clip.json --dry-run', 'lj-awb artifact video upsert-clip --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --input-file ./clip.json --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoUpsertClip,
+    },
+    {
+      name: 'artifact video update-clip-urls',
+      summary: '只回写 clip.videoUrls，不覆盖 payload / prompt / duration',
+      examples: [
+        'lj-awb artifact video update-clip-urls --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 --video-urls-json \'["https://example.com/a.mp4"]\' --dry-run',
+        'lj-awb artifact video update-clip-urls --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 --video-urls-json \'["https://example.com/a.mp4"]\' --yes',
+      ],
+      args: [
+        PROJECT_ID_ARG,
+        ARTIFACT_EPISODE_ARG,
+        ARTIFACT_SCENE_ARG,
+        ARTIFACT_CLIP_ARG,
+        { name: 'video-urls-json', valueName: 'json', description: '视频 URL 数组 JSON' },
+        ...ARTIFACT_WRITE_ARGS,
+      ],
+      func: artifact.artifactVideoUpdateClipVideoUrls,
+    },
+    {
+      name: 'artifact video delete-episode',
+      summary: '逻辑删除视频 episode，并级联删除该集 scenes/clips',
+      examples: ['lj-awb artifact video delete-episode --project-id <projectId> --episode-id ep_001 --dry-run', 'lj-awb artifact video delete-episode --project-id <projectId> --episode-id ep_001 --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoDeleteEpisode,
+    },
+    {
+      name: 'artifact video delete-scene',
+      summary: '逻辑删除视频 scene，并级联删除该场 clips',
+      examples: ['lj-awb artifact video delete-scene --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --dry-run', 'lj-awb artifact video delete-scene --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoDeleteScene,
+    },
+    {
+      name: 'artifact video delete-clip',
+      summary: '逻辑删除视频 clip',
+      examples: ['lj-awb artifact video delete-clip --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 --dry-run', 'lj-awb artifact video delete-clip --project-id <projectId> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG, ARTIFACT_SCENE_ARG, ARTIFACT_CLIP_ARG, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoDeleteClip,
+    },
+    {
+      name: 'artifact video import-storyboard',
+      summary: '从 epXXX_storyboard.json 拆分 episode/scenes/clips 并导入视频最终产物',
+      examples: [
+        'lj-awb artifact video import-storyboard --project-id <projectId> --input-file 3_footage/output/ep001/ep001_storyboard.json --dry-run',
+        'lj-awb artifact video import-storyboard --project-id <projectId> --input-file output/ep001/ep001_storyboard.json --yes',
+      ],
+      args: [PROJECT_ID_ARG, { name: 'input-file', valueName: 'path', description: 'epXXX_storyboard.json 路径' }, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactVideoImportStoryboard,
+    },
+  ]) {
+    cli({
+      name: spec.name,
+      description: commandHelp(spec.summary, { examples: spec.examples }),
+      args: spec.args,
+      func: async (_ctx, kwargs) => spec.func(kwargs),
+    });
+  }
+
+  for (const spec of [
+    {
+      name: 'artifact clip get',
+      summary: '查询项目完整剪辑最终产物',
+      examples: ['lj-awb artifact clip get --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactClipGet,
+    },
+    {
+      name: 'artifact clip episodes',
+      summary: '查询项目剪辑产物列表',
+      examples: ['lj-awb artifact clip episodes --project-id <projectId>'],
+      args: [PROJECT_ID_ARG],
+      func: artifact.artifactClipEpisodes,
+    },
+    {
+      name: 'artifact clip episode',
+      summary: '按 videoEpisodeId 查询单集剪辑产物',
+      examples: ['lj-awb artifact clip episode --project-id <projectId> --video-episode-id 101'],
+      args: [PROJECT_ID_ARG, ARTIFACT_VIDEO_EPISODE_ID_ARG],
+      func: artifact.artifactClipEpisode,
+    },
+    {
+      name: 'artifact clip episode-by-id',
+      summary: '按业务 episodeId 查询单集剪辑产物',
+      examples: ['lj-awb artifact clip episode-by-id --project-id <projectId> --episode-id ep_001'],
+      args: [PROJECT_ID_ARG, ARTIFACT_EPISODE_ARG],
+      func: artifact.artifactClipEpisodeById,
+    },
+    {
+      name: 'artifact clip upsert-episode',
+      summary: '新增或更新单集剪辑最终产物',
+      examples: ['lj-awb artifact clip upsert-episode --project-id <projectId> --input-file ./clip-output.json --dry-run', 'lj-awb artifact clip upsert-episode --project-id <projectId> --input-file ./clip-output.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactClipUpsertEpisode,
+    },
+    {
+      name: 'artifact clip upsert-batch',
+      summary: '批量新增或更新剪辑最终产物',
+      examples: ['lj-awb artifact clip upsert-batch --project-id <projectId> --input-file ./clip-output-list.json --dry-run', 'lj-awb artifact clip upsert-batch --project-id <projectId> --input-file ./clip-output-list.json --yes'],
+      args: [PROJECT_ID_ARG, ...BODY_INPUT_ARGS, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactClipUpsertBatch,
+    },
+    {
+      name: 'artifact clip update-status',
+      summary: '只更新剪辑产物 status；messages 非空时覆盖',
+      examples: ['lj-awb artifact clip update-status --project-id <projectId> --video-episode-id 101 --status music_success --messages-json \'[{"level":"info","step":"music","message":"配乐完成"}]\' --dry-run'],
+      args: [
+        PROJECT_ID_ARG,
+        ARTIFACT_VIDEO_EPISODE_ID_ARG,
+        { name: 'status', valueName: 'status', description: '剪辑阶段状态，例如 concat_success / music_success / burn_success' },
+        { name: 'messages-json', valueName: 'json', description: '可选 messages 数组 JSON；传入时覆盖原 messages' },
+        ...ARTIFACT_WRITE_ARGS,
+      ],
+      func: artifact.artifactClipUpdateStatus,
+    },
+    {
+      name: 'artifact clip delete-episode',
+      summary: '逻辑删除单集剪辑最终产物',
+      examples: ['lj-awb artifact clip delete-episode --project-id <projectId> --video-episode-id 101 --dry-run', 'lj-awb artifact clip delete-episode --project-id <projectId> --video-episode-id 101 --yes'],
+      args: [PROJECT_ID_ARG, ARTIFACT_VIDEO_EPISODE_ID_ARG, ...ARTIFACT_WRITE_ARGS],
+      func: artifact.artifactClipDeleteEpisode,
+    },
+  ]) {
+    cli({
+      name: spec.name,
+      description: commandHelp(spec.summary, { examples: spec.examples }),
+      args: spec.args,
+      func: async (_ctx, kwargs) => spec.func(kwargs),
+    });
+  }
+
+  cli({
+    name: 'subject list',
+    description: commandHelp('查询可用于视频主体参考的元素 / 主体', {
+      examples: ['lj-awb subject list --name "女主"'],
+    }),
+    args: [
+      { name: 'name', valueName: 'keyword', description: '主体名称关键词' },
+      { name: 'page-number', valueName: 'n', description: '页码' },
+      { name: 'page-size', valueName: 'n', description: '每页数量' },
+      INCLUDE_RAW_ARG,
+    ],
+    func: async (_ctx, kwargs) => subjectList(kwargs),
+  });
+
+  cli({
+    name: 'subject publish',
+    description: commandHelp('创建平台主体 element，用于 KeLing / 可灵 视频主体参考', {
+      examples: [
+        'lj-awb subject publish --name 女主 --resource primary:./three-view.png --dry-run',
+        'lj-awb subject publish --name 女主 --resource primary:material/assets/a.png --resource face:./face.png --yes',
+      ],
+      hint: '参考图 slot：primary | three-view | face | side | back。无 primary 时 three-view 自动升为主图；本地路径（./ 或绝对路径）会自动上传，含 :// 或 material/ 前缀的视为已上传 URL。',
+    }),
+    args: [
+      { name: 'name', valueName: 'name', description: '主体名称' },
+      { name: 'description', valueName: 'text', description: '主体描述' },
+      { name: 'model-code', valueName: 'code', description: '主体创建模型编码，可选' },
+      { name: 'reference-type', valueName: 'type', description: '参考类型，默认 image_refer' },
+      { name: 'voice-id', valueName: 'id', description: '参考音色 ID，可选' },
+      { name: 'tags-json', valueName: 'json', description: '标签数组，例如 [{"tagId":"o_102"}]' },
+      { name: 'resource', valueName: 'spec', description: '参考图 <slot>:<file|url>，可重复；slot ∈ primary | three-view | face | side | back' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => subjectPublish(kwargs),
+  });
+
+  cli({
+    name: 'subject wait',
+    description: commandHelp('等待主体 externalId 回填，用于后续视频主体参考', {
+      examples: ['lj-awb subject wait --element-id <elementId> --wait-seconds 300'],
+    }),
+    args: [
+      { name: 'element-id', valueName: 'id', description: 'subject publish 返回的 elementId' },
+      ...SUBJECT_WAIT_ARGS,
+    ],
+    func: async (_ctx, kwargs) => subjectWait(kwargs),
+  });
+
+  cli({
+    name: 'subject publish-batch',
+    description: commandHelp('批量发布主体资产；输入支持 JSON 数组文件或 JSONL（每行一条）', {
+      examples: [
+        'lj-awb subject publish-batch --input-file ./subjects.jsonl --dry-run',
+        'lj-awb subject publish-batch --input-file ./subjects.json --concurrency 2 --yes',
+      ],
+    }),
+    args: [
+      { name: 'input-file', valueName: 'path', description: '批量输入文件' },
+      { name: 'project-name', valueName: 'name', description: '默认项目名' },
+      { name: 'concurrency', valueName: 'n', description: '并发数，默认 1' },
+      DRY_RUN_ARG,
+      YES_ARG,
+    ],
+    func: async (_ctx, kwargs) => subjectPublishBatch(kwargs),
+  });
+}