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

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

@@ -28,6 +28,8 @@ const OPTION_SYNONYMS = {
   in: ['inputFile'],
   dry: ['dryRun'],
   force: ['yes'],
+  remoteTaskId: ['taskId'],
+  publicId: ['taskId'],
 };
 
 function levenshtein(a, b) {
@@ -202,14 +204,14 @@ const VIRTUAL_COMMANDS = [
       '',
       'Examples:',
       '  lj-awb schema -f json',
-      '  lj-awb schema --domain video -f json',
-      '  lj-awb schema --domain image --command create -f json',
+      '  lj-awb schema --domain create -f json',
+      '  lj-awb schema --domain create --command image -f json',
       '',
       'Hint: Agent 应优先读取 schema，而不是解析自然语言 help。',
     ].join('\n'),
     args: [
-      { name: 'domain', valueName: 'name', description: '按命令域过滤，如 image / video / task / system' },
-      { name: 'command', valueName: 'name', description: '按子命令过滤，如 create / wait / doctor' },
+      { name: 'domain', valueName: 'name', description: '按命令域过滤，如 create / task / artifact / system' },
+      { name: 'command', valueName: 'name', description: '按子命令过滤，如 image / video / wait / doctor' },
     ],
   },
 ];
@@ -295,13 +297,10 @@ const GROUP_DESCRIPTIONS = {
   project: '项目：查看、切换、创建和更新项目组',
   credits: '积分：查询可扣积分余额、项目组预算和用量统计',
   model: '模型：查询生图 / 生视频模型、参数约束和创建用法',
+  create: '创建：统一提交图片、视频、主体、音色、素材和视频去字幕任务',
   upload: '上传：把本地文件上传为平台可访问素材',
-  image: '图片：估价、提交、批量提交和查询生图任务',
-  video: '视频：估价、提交、批量提交、查询和去字幕',
   task: '任务：任务列表、等待和本地任务台账',
-  asset: '资产：素材库匹配、素材组和素材注册',
   artifact: '最终产物：剧本、资产、视频、剪辑 CRUD 与本地 JSON 导入',
-  subject: '主体：发布和查询可复用主体资产',
 };
 
 const SUBGROUP_DESCRIPTIONS = {
@@ -341,7 +340,7 @@ const GROUP_EXAMPLES = {
     'lj-awb doctor',
     'lj-awb doctor --verify',
     'lj-awb schema -f json',
-    'lj-awb schema --domain video -f json',
+    'lj-awb schema --domain create -f json',
   ],
   auth: [
     'lj-awb auth status',
@@ -375,36 +374,30 @@ const GROUP_EXAMPLES = {
   upload: [
     'lj-awb upload files --files ./a.png,./b.mp4 --dry-run',
   ],
-  image: [
-    'lj-awb image fee --model-group-code <code> --prompt "一只小狗"',
-    'lj-awb image create --model-group-code <code> --prompt "一只小狗" --dry-run',
-    'lj-awb image status --task-id <id>',
-  ],
-  video: [
-    'lj-awb video fee --model-group-code <code> --prompt "雨夜奔跑" --duration 5',
-    'lj-awb video create --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=./actor.png --dry-run',
-    'lj-awb video create --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=asset:<assetId> --dry-run',
-    'lj-awb video subtitle-status --remote-task-id <id>',
+  create: [
+    'lj-awb create image --model-group-code <code> --prompt "一只小狗" --dry-run',
+    'lj-awb create image-fee --model-group-code <code> --prompt "一只小狗"',
+    'lj-awb create video --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=./actor.png --dry-run',
+    'lj-awb create video-fee --model-group-code <code> --prompt "雨夜奔跑" --duration 5',
+    'lj-awb create subject --model-code tx --name 女主 --resource primary:./three-view.png --dry-run',
+    'lj-awb create subject-wait --element-id <elementId> --wait-seconds 300',
+    'lj-awb create asset --group-id <id> --file ./actor.png --name "女主正面" --dry-run',
+    'lj-awb create asset-groups --name "女主"',
   ],
   task: [
     'lj-awb task list --task-type IMAGE_CREATE --project-group-no <no>',
+    'lj-awb task image-status --task-id <imageTaskId>',
+    'lj-awb task video-status --task-id <videoTaskId>',
+    'lj-awb task video-subtitle-status --task-id <subtitleTaskId>',
     'lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180',
     'lj-awb task records --task-record-file .awb/tasks.jsonl',
   ],
-  asset: [
-    'lj-awb asset match-actor --description "十八岁少女，古风" --tags-json \'{"gender":"女"}\'',
-    'lj-awb asset group-create --name "女主素材组" --dry-run',
-  ],
   artifact: [
     'lj-awb artifact script import --project-id <projectId> --input-file 1_script/output/script.json --dry-run',
     'lj-awb artifact asset import --project-id <projectId> --input-dir 2_asset/output --dry-run',
     'lj-awb artifact video import-storyboard --project-id <projectId> --input-file 3_footage/output/ep001/ep001_storyboard.json --dry-run',
     'lj-awb artifact clip upsert-episode --project-id <projectId> --input-file 4_clip/output/ep001_clip_output.json --dry-run',
   ],
-  subject: [
-    'lj-awb subject list --name "女主"',
-    'lj-awb subject publish --name 女主 --resource primary:./three-view.png --dry-run',
-  ],
 };
 
 const COMMAND_REQUIRED_OPTIONS = {
@@ -413,21 +406,21 @@ const COMMAND_REQUIRED_OPTIONS = {
   'project ensure': ['name'],
   'model options': ['modelGroupCode'],
   'model create-spec': ['modelGroupCode'],
-  'image fee': ['modelGroupCode', 'prompt'],
-  'image create': ['modelGroupCode', 'prompt'],
-  'image create-batch': ['inputFile', 'modelGroupCode'],
-  'image status': ['taskId'],
-  'video fee': ['modelGroupCode'],
-  'video create': ['modelGroupCode'],
-  'video create-batch': ['inputFile', 'modelGroupCode'],
-  'video status': ['taskId'],
-  'video subtitle-remove': ['videoUrl'],
+  'create image-fee': ['modelGroupCode', 'prompt'],
+  'create image': ['modelGroupCode', 'prompt'],
+  'create image-batch': ['inputFile', 'modelGroupCode'],
+  'task image-status': ['taskId'],
+  'create video-fee': ['modelGroupCode'],
+  'create video': ['modelGroupCode'],
+  'create video-batch': ['inputFile', 'modelGroupCode'],
+  'task video-status': ['taskId'],
+  'task video-subtitle-status': ['taskId'],
   'task wait': ['taskId', 'taskType'],
-  'asset match-actor': ['description'],
-  'asset group': ['groupId'],
-  'asset group-create': ['name'],
-  'asset group-update': ['groupId'],
-  'asset register': ['groupId', 'name'],
+  'create asset-match-actor': ['description'],
+  'create asset-group-get': ['groupId'],
+  'create asset-group': ['name'],
+  'create asset-group-update': ['groupId'],
+  'create asset': ['groupId', 'name'],
   'artifact script row': ['rowKind', 'entityKey'],
   'artifact script children': ['parentKey'],
   'artifact script delete-row': ['rowKind', 'entityKey'],
@@ -459,18 +452,20 @@ const COMMAND_REQUIRED_OPTIONS = {
   'artifact clip episode-by-id': ['episodeId'],
   'artifact clip update-status': ['videoEpisodeId', 'status'],
   'artifact clip delete-episode': ['videoEpisodeId'],
-  'subject publish': ['name'],
-  'subject wait': ['elementId'],
-  'subject publish-batch': ['inputFile'],
+  'create subject': ['name'],
+  'create subject-wait': ['elementId'],
+  'create subject-voice': ['name'],
+  'create subject-batch': ['inputFile'],
 };
 
 const COMMAND_REQUIRED_ANY_OPTIONS = {
   'project update': [['name', 'point']],
   'upload files': [['file', 'files', 'filesJson']],
-  'video fee': [['prompt', 'resource', 'resourcesJson']],
-  'video create': [['prompt', 'resource', 'resourcesJson']],
-  'asset group-update': [['name', 'description', 'projectName']],
-  'asset register': [['file', 'url', 'backendPath']],
+  'create video-fee': [['prompt', 'resource', 'resourcesJson']],
+  'create video': [['prompt', 'resource', 'resourcesJson']],
+  'create video-subtitle-removal': [['sourceTaskId']],
+  'create asset-group-update': [['name', 'description', 'projectName']],
+  'create asset': [['file', 'url', 'backendPath']],
   'artifact script upsert-row': [['bodyJson', 'inputFile']],
   'artifact asset upsert-actor': [['bodyJson', 'inputFile']],
   'artifact asset upsert-prop': [['bodyJson', 'inputFile']],
@@ -483,7 +478,10 @@ const COMMAND_REQUIRED_ANY_OPTIONS = {
   'artifact video upsert-clip': [['bodyJson', 'inputFile']],
   'artifact clip upsert-episode': [['bodyJson', 'inputFile']],
   'artifact clip upsert-batch': [['bodyJson', 'inputFile']],
-  'subject publish': [['resource']],
+  'create subject': [['resource'], ['modelCode']],
+  'create subject-batch': [['modelCode']],
+  'create subject-voice': [['file', 'voiceUrl', 'audioUrl', 'videoId']],
+  'create subject-voice-wait': [['voiceRecordId', 'reqTaskId']],
 };
 
 const ARTIFACT_WRITE_COMMANDS = [
@@ -526,24 +524,26 @@ const CONFIRMATION_COMMANDS = new Set([
   'project create',
   'project update',
   'project ensure',
-  'image create',
-  'image create-batch',
-  'video create',
-  'video create-batch',
-  'video subtitle-remove',
-  'asset group-create',
-  'asset group-update',
-  'asset register',
+  'create image',
+  'create image-batch',
+  'create video',
+  'create video-batch',
+  'create video-subtitle-removal',
+  'create asset-group',
+  'create asset-group-update',
+  'create asset',
   ...ARTIFACT_WRITE_COMMANDS,
-  'subject publish',
-  'subject publish-batch',
+  'create subject',
+  'create subject-voice',
+  'create subject-batch',
 ]);
 
 const COST_COMMANDS = new Set([
-  'image create',
-  'image create-batch',
-  'video create',
-  'video create-batch',
+  'create image',
+  'create image-batch',
+  'create video',
+  'create video-batch',
+  'create video-subtitle-removal',
 ]);
 
 const REMOTE_WRITE_COMMANDS = new Set([
@@ -553,17 +553,18 @@ const REMOTE_WRITE_COMMANDS = new Set([
   'project update',
   'project ensure',
   'upload files',
-  'image create',
-  'image create-batch',
-  'video create',
-  'video create-batch',
-  'video subtitle-remove',
-  'asset group-create',
-  'asset group-update',
-  'asset register',
+  'create image',
+  'create image-batch',
+  'create video',
+  'create video-batch',
+  'create video-subtitle-removal',
+  'create asset-group',
+  'create asset-group-update',
+  'create asset',
   ...ARTIFACT_WRITE_COMMANDS,
-  'subject publish',
-  'subject publish-batch',
+  'create subject',
+  'create subject-voice',
+  'create subject-batch',
 ]);
 
 const LOCAL_STATE_WRITE_COMMANDS = new Set([
@@ -575,7 +576,7 @@ const LOCAL_STATE_WRITE_COMMANDS = new Set([
 ]);
 
 const DESTRUCTIVE_COMMANDS = new Set(['auth clear', ...ARTIFACT_DELETE_COMMANDS]);
-const LONG_RUNNING_COMMANDS = new Set(['task wait', 'task record-poll', 'subject wait']);
+const LONG_RUNNING_COMMANDS = new Set(['task wait', 'task record-poll', 'create subject-wait', 'create subject-voice-wait']);
 const NETWORK_NONE_COMMANDS = new Set(['schema', 'auth status', 'auth clear', 'model input-guide', 'task records']);
 const NETWORK_CONDITIONAL_COMMANDS = new Set(['doctor', 'auth login']);
 
@@ -598,30 +599,33 @@ const OUTPUT_KIND_BY_COMMAND = {
   'model create-spec': 'model_create_spec',
   'model input-guide': 'model_input_guide',
   'upload files': 'upload_result',
-  'image fee': 'fee_estimate',
-  'image create': 'task_submission',
-  'image create-batch': 'batch_task_submission',
-  'image status': 'task_status',
-  'video fee': 'fee_estimate',
-  'video create': 'task_submission',
-  'video create-batch': 'batch_task_submission',
-  'video status': 'task_status',
-  'video subtitle-remove': 'subtitle_task_submission',
-  'video subtitle-status': 'subtitle_task_status',
+  'create image-fee': 'fee_estimate',
+  'create image': 'task_submission',
+  'create image-batch': 'batch_task_submission',
+  'task image-status': 'task_status',
+  'create video-fee': 'fee_estimate',
+  'create video': 'task_submission',
+  'create video-batch': 'batch_task_submission',
+  'task video-status': 'task_status',
+  'create video-subtitle-removal': 'subtitle_task_submission',
+  'task video-subtitle-status': 'subtitle_task_status',
   'task list': 'task_list',
   'task wait': 'task_status',
   'task records': 'local_task_records',
   'task record-poll': 'batch_task_status',
-  'asset match-actor': 'asset_match_list',
-  'asset groups': 'asset_group_list',
-  'asset group': 'asset_group_detail',
-  'asset group-create': 'asset_group_write_result',
-  'asset group-update': 'asset_group_write_result',
-  'asset register': 'asset_register_result',
-  'subject list': 'subject_list',
-  'subject publish': 'subject_publish_result',
-  'subject wait': 'subject_status',
-  'subject publish-batch': 'batch_subject_publish_result',
+  'create asset-match-actor': 'asset_match_list',
+  'create asset-groups': 'asset_group_list',
+  'create asset-group-get': 'asset_group_detail',
+  'create asset-group': 'asset_group_write_result',
+  'create asset-group-update': 'asset_group_write_result',
+  'create asset': 'asset_register_result',
+  'create subject-list': 'subject_list',
+  'create subject': 'subject_publish_result',
+  'create subject-wait': 'subject_status',
+  'create subject-voice-list': 'subject_voice_list',
+  'create subject-voice': 'subject_voice_create_result',
+  'create subject-voice-wait': 'subject_voice_status',
+  'create subject-batch': 'batch_subject_publish_result',
   'artifact script get': 'artifact_full',
   'artifact script document': 'artifact_record',
   'artifact script rows': 'artifact_list',
@@ -676,16 +680,16 @@ const OUTPUT_KIND_BY_COMMAND = {
 };
 
 const PREFLIGHTS_BY_COMMAND = {
-  'image create': ['doctor --verify', 'model image-models', 'model options', 'model create-spec', 'confirm missing key params', 'image fee', 'image create --dry-run'],
-  'image create-batch': ['doctor --verify', 'model image-models', 'model options', 'model create-spec', 'prepare JSONL input', 'image create-batch --dry-run'],
-  'video create': ['doctor --verify', 'model video-models', 'model options', 'model create-spec', 'confirm missing key params', 'video fee', 'video create --dry-run'],
-  'video create-batch': ['doctor --verify', 'model video-models', 'model options', 'model create-spec', 'prepare JSONL input', 'video create-batch --dry-run'],
-  'subject publish': ['doctor --verify', 'subject publish --dry-run'],
-  'subject publish-batch': ['doctor --verify', 'prepare JSONL input', 'subject publish-batch --dry-run'],
-  'video subtitle-remove': ['doctor --verify', 'video subtitle-remove --dry-run'],
-  'asset group-create': ['asset group-create --dry-run'],
-  'asset group-update': ['asset group-update --dry-run'],
-  'asset register': ['asset register --dry-run'],
+  'create image': ['doctor --verify', 'model image-models', 'model options', 'model create-spec', 'confirm missing key params', 'create image-fee', 'create image --dry-run'],
+  'create image-batch': ['doctor --verify', 'model image-models', 'model options', 'model create-spec', 'prepare JSONL input', 'create image-batch --dry-run'],
+  'create video': ['doctor --verify', 'model video-models', 'model options', 'model create-spec', 'confirm missing key params', 'create video-fee', 'create video --dry-run'],
+  'create video-batch': ['doctor --verify', 'model video-models', 'model options', 'model create-spec', 'prepare JSONL input', 'create video-batch --dry-run'],
+  'create subject': ['doctor --verify', 'create subject --model-code tx|vidu --dry-run'],
+  'create subject-batch': ['doctor --verify', 'prepare JSONL input with modelCode', 'create subject-batch --dry-run'],
+  'create video-subtitle-removal': ['doctor --verify', 'create video-subtitle-removal --source-task-id <videoTaskId> --dry-run'],
+  'create asset-group': ['create asset-group --dry-run'],
+  'create asset-group-update': ['create asset-group-update --dry-run'],
+  'create asset': ['create asset --dry-run'],
   'upload files': ['upload files --dry-run'],
 };
 
@@ -760,13 +764,25 @@ function buildCommandSafety(command, optionKeys) {
 function buildCommandWorkflow(command) {
   const outputKind = OUTPUT_KIND_BY_COMMAND[command.name] || 'generic';
   const next = [];
-  if (['image create', 'video create'].includes(command.name)) {
-    next.push('读取 data.taskId 和 data.nextCommand', '运行 task wait 等待结果');
+  if (command.name === 'create image') {
+    next.push('读取 data.taskId 和 data.nextCommand', '立即运行响应里的 nextCommand，或 task wait --task-type IMAGE_CREATE 等待结果');
+  }
+  if (command.name === 'create video') {
+    next.push('读取 data.taskId 和 data.nextCommand', '立即运行响应里的 nextCommand，或 task wait --task-type VIDEO_GROUP 等待结果');
+  }
+  if (command.name === 'create video-subtitle-removal') {
+    next.push('读取 data.taskId 和 data.nextCommand', '运行 task video-subtitle-status 或响应里的 nextCommand 等待结果');
+  }
+  if (command.name === 'create subject') {
+    next.push('读取 data.elementId / data.externalId', 'externalId 为空时立刻运行 create subject-wait 获取 nextRefSubject');
+  }
+  if (command.name === 'create subject-voice') {
+    next.push('读取 data.voiceRecordId / data.externalId', 'externalId 为空时立刻运行 create subject-voice-wait 获取 nextVoiceArg');
   }
-  if (command.name === 'subject publish') {
-    next.push('读取 data.elementId', '运行 subject wait 获取 externalId / nextRefSubject');
+  if (command.name === 'create asset') {
+    next.push('读取 data.assetPath', '若后端返回审核 taskId，再运行 task wait --task-type ASSET_REGISTER');
   }
-  if (['image create-batch', 'video create-batch', 'subject publish-batch'].includes(command.name)) {
+  if (['create image-batch', 'create video-batch', 'create subject-batch'].includes(command.name)) {
     next.push('读取每项 status / taskId / error', '使用 task record-poll 或对应 wait 命令恢复批量结果');
   }
   return {
@@ -781,6 +797,28 @@ function buildAgentContract() {
     defaultOutputFormat: 'compact-text',
     jsonFlag: '-f json',
     outputPolicy: '默认输出精简 key=value 文本，只保留决策字段；需要稳定 JSON、嵌套结构或脚本严格解析时显式传 -f json 或 --json。JSON envelope 字段已做归一化，见 canonicalFields。',
+    statePolicy: {
+      purpose: 'Agent 应在同一轮 / 同一项目中维护 AWB 上下文账本，减少重复查询和重复提交。',
+      cacheKeys: [
+        'schema version / domains / commands',
+        'auth / account / team / current projectGroup',
+        'modelCandidates by taskKind + keyword',
+        'modelOptions / modelCreateSpec by modelGroupCode',
+        'uploaded backendPath by local file path or remote URL',
+        'taskId -> taskType / projectGroupNo / resultUrls / errorMessage',
+        'subject name + modelCode -> elementId / externalId / nextRefSubject',
+        'subject voice name + source -> voiceRecordId / externalId / nextVoiceArg',
+        'artifact projectId and imported file paths',
+      ],
+      invalidation: '用户切换账号、团队、项目组、模型、素材、prompt 或关键参数后，只刷新受影响的缓存；不要重复跑未变化的 model options / create-spec / fee。',
+    },
+    workflowPolicy: [
+      '模型探索阶段只读 model list / options / create-spec；fee 只在用户确认关键参数后跑一次。',
+      'supportsDryRun=true 的写入 / 扣费命令先 dry-run，确认后 yes；不要把 dry-run 当参数探索工具反复跑。',
+      '用户给出多条同模型同参数任务时优先 batch + task-record-file，不要单条循环 create。',
+      '命令返回 nextCommand / nextRefSubject / nextVoiceArg 时优先复用返回值，不手拼等价命令。',
+      '旧根域 image / video / asset / subject 已移除；只使用 create / task / artifact 等 schema 暴露的 domain。',
+    ],
     canonicalFields: {
       purpose: 'CLI 输出对上游平台多版本字段做了归一化。Agent 只识别 canonical 列，遇到 aliases 列出的旧字段名时说明是上游原始返回，CLI 已在 text / 归一化层做了 fallback。不要把旧名当成独立新字段对外报告。',
       fields: [
@@ -797,7 +835,7 @@ function buildAgentContract() {
     dryRunPolicy: 'schema.commands[].safety.supportsDryRun=true 的写入 / 扣费命令，正式执行前优先跑 --dry-run。',
     resourceShortcut: {
       flag: '--resource',
-      syntax: 'type:usage[:reference_key]=path|url|asset:<id>; image create uses image:reference=... without key',
+      syntax: 'type:usage[:reference_key]=path|url|asset:<id>; create image uses image:reference=... without key',
       examples: [
         'image:reference=./ref.png',
         'image:first_frame=./hero.png',
@@ -811,7 +849,7 @@ function buildAgentContract() {
         {
           type: 'image|video|audio|subject',
           usage: 'reference|first_frame|last_frame|keyframe',
-          reference_key: 'video reference placeholder key; not used by image create image:reference',
+          reference_key: 'video reference placeholder key; not used by create image image:reference',
           source: { kind: 'url|asset_id', value: '<local-file-or-http-url-or-material-backendPath-or-asset-id>' },
         },
       ],
@@ -820,14 +858,14 @@ function buildAgentContract() {
       command: `${commandPrefix()} model options --model-group-code <code>`,
       jsonCommand: `${commandPrefix()} model options --model-group-code <code> -f json`,
       purpose: '查询指定模型支持的 CLI 参数、枚举值、默认值、素材约束和条件约束。',
-      useBefore: ['model create-spec', 'image fee', 'image create', 'video fee', 'video create'],
+      useBefore: ['model create-spec', 'create image-fee', 'create image', 'create video-fee', 'create video'],
       keyFields: ['params[].values', 'params[].defaultValue', 'resources[].mediaType', 'resources[].usage', 'resources[].fileTypes', 'resources[].maxFiles', 'resources[].supportLastFrameOnly', 'resources[].minDurationMs', 'resources[].maxDurationMs', 'constraints[].target', 'constraints[].conditions', 'constraints[].effect'],
     },
     modelCreateSpec: {
       command: `${commandPrefix()} model create-spec --model-group-code <code>`,
       jsonCommand: `${commandPrefix()} model create-spec --model-group-code <code> -f json`,
       purpose: '查看指定模型如何组织 create 命令：输入模式、素材绑定规则、示例和创建前检查项。',
-      useBefore: ['image fee', 'image create', 'video fee', 'video create'],
+      useBefore: ['create image-fee', 'create image', 'create video-fee', 'create video'],
       keyFields: ['inputRequirement', 'supportedIntents', 'validationRules', 'agentGuidance', 'preflight', 'examples'],
     },
     modelInputGuide: {
@@ -839,6 +877,8 @@ function buildAgentContract() {
     taskTypes: {
       image: 'IMAGE_CREATE',
       video: 'VIDEO_GROUP',
+      subtitleRemoval: 'VIDEO_SUBTITLE_REMOVAL',
+      assetRegister: 'ASSET_REGISTER',
     },
     exitCodes: [
       { code: 0, type: 'success', meaning: '命令成功' },
@@ -846,8 +886,11 @@ function buildAgentContract() {
       { code: 2, type: 'argument_error|unknown_command|unknown_option', meaning: '参数或命令错误' },
       { code: 3, type: 'auth_required|auth_failed', meaning: '缺少认证或认证失败' },
       { code: 10, type: 'confirmation_required', meaning: '需要用户确认后追加 --yes' },
+      { code: 1, type: 'subject_failed', meaning: '主体创建任务已失败（error.type=subject_failed）。查看 error.details.errorMessage 后调整参考资源或模型重新创建。' },
+      { code: 1, type: 'subject_voice_failed', meaning: '主体音色创建任务已失败（error.type=subject_voice_failed）。查看 error.details.errorMessage 后调整音频或视频来源重新创建。' },
       { code: 20, type: 'task_still_running', meaning: '生图 / 生视频任务仍在运行，本轮等待窗口结束（error.type=task_still_running）。可继续 task wait 或 record-poll 续等。' },
-      { code: 20, type: 'subject_still_pending', meaning: '主体 externalId 尚未回填，本轮等待窗口结束（error.type=subject_still_pending）。可继续 subject wait 续等。' },
+      { code: 20, type: 'subject_still_pending', meaning: '主体 externalId 尚未回填，本轮等待窗口结束（error.type=subject_still_pending）。可继续 create subject-wait 续等。' },
+      { code: 20, type: 'subject_voice_still_pending', meaning: '主体音色 externalId 尚未回填，本轮等待窗口结束（error.type=subject_voice_still_pending）。可继续 create subject-voice-wait 续等。' },
       { code: 30, type: 'network_error', meaning: '网络、TLS、HTTP 或外部平台不可用' },
     ],
   };
@@ -960,7 +1003,7 @@ function printRootHelp(commands, version) {
     `  ${commandPrefix()} model input-guide`,
     `  ${commandPrefix()} model options --model-group-code <code>`,
     `  ${commandPrefix()} model create-spec --model-group-code <code>`,
-    `  ${commandPrefix()} image create --model-group-code <code> --prompt "一只小狗" --dry-run`,
+    `  ${commandPrefix()} create image --model-group-code <code> --prompt "一只小狗" --dry-run`,
     '',
     'Command groups:',
   ];
@@ -988,6 +1031,7 @@ function printGroupHelp(group, commands, version) {
   const items = commands.filter((command) => commandGroup(command) === group);
   const subgroupMap = SUBGROUP_DESCRIPTIONS[group];
   const hasSubgroups = Boolean(subgroupMap && Object.keys(subgroupMap).length);
+  const directItems = hasSubgroups ? items.filter((command) => !commandSubgroupTokens(command)) : [];
 
   const lines = [
     `lj-awb v${version}`,
@@ -999,6 +1043,7 @@ function printGroupHelp(group, commands, version) {
   if (group === 'system') {
     lines.push(`  ${commandPrefix()} <command> [options]`);
   } else if (hasSubgroups) {
+    if (directItems.length) lines.push(`  ${commandPrefix()} ${group} <command> [options]`);
     lines.push(`  ${commandPrefix()} ${group} <subdomain> <command> [options]`);
   } else {
     lines.push(`  ${commandPrefix()} ${group} <command> [options]`);
@@ -1025,6 +1070,13 @@ function printGroupHelp(group, commands, version) {
       if (!presentSubgroups.has(subgroup)) continue;
       lines.push(`  ${subgroup.padEnd(10)} ${description}`);
     }
+    if (directItems.length) {
+      lines.push('', 'Commands:');
+      for (const command of directItems) {
+        const subcommand = commandSubcommand(command);
+        lines.push(`  ${subcommand.padEnd(28)} ${summaryOf(command)}`);
+      }
+    }
   } else {
     lines.push('Commands:');
     for (const command of items) {
@@ -1163,8 +1215,15 @@ export async function runStandaloneCli(argv = process.argv.slice(2)) {
       printSubgroupHelp(group, subgroup, commands, version);
     } else if (isCommandGroupName(parsed.commandName, commands)) {
       printGroupHelp(parsed.commandName, commands, version);
-    } else {
+    } else if (!parsed.commandName) {
       printRootHelp(commands, version);
+    } else {
+      printError(new LingjingAwbCliError(`未知命令: ${parsed.commandName}`, {
+        type: 'unknown_command',
+        exitCode: 2,
+        hint: unknownCommandHint(parsed.commandName),
+      }), parsed.format, { command: parsed.commandName });
+      process.exitCode = 2;
     }
     return;
   }