@lingjingai/lj-awb-cli-pre 0.3.18 → 0.4.5

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

@@ -3,7 +3,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LingjingAwbCliError, createEnvelope, toBool, toInt } from './common.js';
 import { registerAwbCommands } from './commands.js';
-import { formatTextError, formatTextOutput, normalizeJsonData } from './output.js';
+import { checkCliUpdate } from './update.js';
+import {
+  formatCsvOutput,
+  formatPrettyError,
+  formatPrettyOutput,
+  formatTextError,
+  formatTextOutput,
+  formatYamlEnvelope,
+  normalizeJsonData,
+} from './output.js';
 
 function normalizeKey(value) {
   return String(value || '').replace(/-([a-z])/g, (_, char) => char.toUpperCase());
@@ -96,6 +105,57 @@ function renderCliText(value) {
   return String(value ?? '').replace(/\blj-awb\b/g, commandPrefix());
 }
 
+function shouldColorOutput() {
+  if (String(process.env.LINGJING_AWB_COLOR || '').toLowerCase() === '0') return false;
+  if (String(process.env.LINGJING_AWB_COLOR || '').toLowerCase() === 'false') return false;
+  if (String(process.env.FORCE_COLOR || '').trim() && process.env.FORCE_COLOR !== '0') return true;
+  if (String(process.env.LINGJING_AWB_COLOR || '').toLowerCase() === '1') return true;
+  if (String(process.env.LINGJING_AWB_COLOR || '').toLowerCase() === 'true') return true;
+  if (process.env.NO_COLOR) return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+function colorText(value, code) {
+  const text = String(value ?? '');
+  return shouldColorOutput() && text ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+const HELP_COLOR = {
+  title: '1;38;5;39',
+  accent: '1;38;5;208',
+  heading: '1;38;5;75',
+  command: '38;5;82',
+  group: '38;5;215',
+  muted: '2;38;5;245',
+  option: '38;5;111',
+};
+
+function helpTitle(value) {
+  if (!shouldColorOutput()) return String(value ?? '');
+  return `${colorText('◆', HELP_COLOR.accent)} ${colorText(value, HELP_COLOR.title)}`;
+}
+
+function helpHeading(value) {
+  if (!shouldColorOutput()) return String(value ?? '');
+  return `${colorText('▸', HELP_COLOR.accent)} ${colorText(value, HELP_COLOR.heading)}`;
+}
+
+function helpCommand(value) {
+  return colorText(value, HELP_COLOR.command);
+}
+
+function helpGroup(value) {
+  return colorText(value, HELP_COLOR.group);
+}
+
+function helpMuted(value) {
+  return colorText(value, HELP_COLOR.muted);
+}
+
+function helpOption(value) {
+  return colorText(value, HELP_COLOR.option);
+}
+
 function shellArg(value) {
   const text = String(value ?? '');
   return /^[A-Za-z0-9_./:=@,+-]+$/.test(text) ? text : JSON.stringify(text);
@@ -127,10 +187,14 @@ function commandInvocation(commandName, kwargs = {}, options = {}) {
   return parts.join(' ');
 }
 
-function buildOutputContext(command, kwargs = {}) {
+function buildOutputContext(command, kwargs = {}, data = {}) {
   const optionKeys = new Set((command.args || []).map((arg) => normalizeKey(arg.name)));
   const canSuggestDryRunExecution = command.name !== 'auth login';
   const withoutDryRun = { omit: ['dryRun'] };
+  const confirmSet = { yes: true };
+  if (command.name === 'create asset' && data?.conversionPlan && !toBool(kwargs.autoConvert)) {
+    confirmSet.autoConvert = true;
+  }
   const isModelList = command.name === 'model image-models' || command.name === 'model video-models';
   const modelListAll = isModelList && toBool(kwargs.all);
   const modelListLimit = isModelList
@@ -141,14 +205,53 @@ function buildOutputContext(command, kwargs = {}) {
     : null;
   return {
     jsonCommand: `${commandInvocation(command.name, kwargs)} -f json`,
+    textCommand: `${commandInvocation(command.name, kwargs)} -f text`,
+    outputKind: buildCommandWorkflow(command).outputKind,
     executeCommand: canSuggestDryRunExecution && toBool(kwargs.dryRun) ? commandInvocation(command.name, kwargs, withoutDryRun) : null,
     confirmCommand: canSuggestDryRunExecution && toBool(kwargs.dryRun) && optionKeys.has('yes')
-      ? commandInvocation(command.name, kwargs, { omit: ['dryRun'], set: { yes: true } })
+      ? commandInvocation(command.name, kwargs, { omit: ['dryRun'], set: confirmSet })
       : null,
     ...(isModelList ? { listLimit: modelListLimit, moreCommand: modelListMoreCommand } : {}),
   };
 }
 
+function updateCheckDisabledByEnv() {
+  return ['1', 'true', 'yes', 'on'].includes(String(process.env.LINGJING_AWB_DISABLE_UPDATE_CHECK || '').trim().toLowerCase())
+    || ['1', 'true', 'yes', 'on'].includes(String(process.env.AWB_DISABLE_UPDATE_CHECK || '').trim().toLowerCase());
+}
+
+function shouldSkipUpdateCheck(argv = [], commandName = '') {
+  if (updateCheckDisabledByEnv()) return true;
+  return commandName === 'update';
+}
+
+async function resolveUpdateNotice(argv = [], commandName = '', version = 'unknown') {
+  if (shouldSkipUpdateCheck(argv, commandName)) return null;
+  return await checkCliUpdate({ currentVersion: version }).catch(() => null);
+}
+
+const OUTPUT_FORMAT_ALIASES = {
+  agent: 'text',
+  table: 'pretty',
+  human: 'pretty',
+  compact: 'text',
+  'compact-text': 'text',
+};
+
+const SUPPORTED_OUTPUT_FORMATS = new Set(['auto', 'pretty', 'text', 'json', 'yaml', 'csv']);
+
+function resolveOutputFormat(format) {
+  const raw = String(format || 'pretty').trim().toLowerCase();
+  const normalized = OUTPUT_FORMAT_ALIASES[raw] || raw;
+  if (normalized === 'auto') return process.stdout.isTTY ? 'pretty' : 'text';
+  if (SUPPORTED_OUTPUT_FORMATS.has(normalized)) return normalized;
+  throw new LingjingAwbCliError(`未知输出格式：${format}`, {
+    type: 'argument_error',
+    exitCode: 2,
+    hint: '可用格式：pretty、text、json、yaml、csv、auto。Agent 建议使用 -f text；严格脚本解析再用 -f json。',
+  });
+}
+
 function assignKwarg(kwargs, key, value) {
   if (kwargs[key] === undefined) {
     kwargs[key] = value;
@@ -165,7 +268,7 @@ function parseArgv(argv) {
   const commandParts = [];
   const kwargs = {};
   const kwargRawFlags = {};
-  let format = 'text';
+  let format = 'pretty';
 
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
@@ -232,13 +335,15 @@ const VIRTUAL_COMMANDS = [
       '输出机器可读命令 schema，供 Agent / 脚本理解命令、参数和示例',
       '',
       'Examples:',
+      '  lj-awb schema --brief -f json',
       '  lj-awb schema -f json',
       '  lj-awb schema --domain create -f json',
       '  lj-awb schema --domain create --command image -f json',
       '',
-      'Hint: Agent 应优先读取 schema，而不是解析自然语言 help。',
+      'Hint: Agent 先读 --brief 掌握能力地图；执行具体命令前再读精确 schema。',
     ].join('\n'),
     args: [
+      { name: 'brief', description: '输出面向 Agent 的轻量能力摘要，不展开每个参数' },
       { name: 'domain', valueName: 'name', description: '按命令域过滤，如 create / task / artifact / system' },
       { name: 'command', valueName: 'name', description: '按子命令过滤，如 image / video / wait / doctor' },
     ],
@@ -257,6 +362,9 @@ const RENAMED_COMMAND_HINTS = {
   'video create-batch': 'create video-batch',
   'video status': 'task video-status',
   'video subtitle-remove': 'create video-subtitle-removal',
+  'video super-resolution': 'create video-super-resolution',
+  'video super-resolution-fee': 'create video-super-resolution-fee',
+  'video super-resolution-status': 'task video-super-resolution-status',
   'video subtitle-status': 'task video-subtitle-status',
   asset: 'create asset',
   'asset match-actor': 'create asset-match-actor',
@@ -395,14 +503,21 @@ const GROUP_EXAMPLES = {
   system: [
     'lj-awb doctor',
     'lj-awb doctor --verify',
+    'lj-awb update --check',
+    'lj-awb update',
+    'lj-awb schema --brief -f json',
     'lj-awb schema -f json',
     'lj-awb schema --domain create -f json',
   ],
   auth: [
     'lj-awb auth status',
     'lj-awb auth verify',
+    'lj-awb auth login',
+    'lj-awb auth login --no-wait --json',
+    'lj-awb auth login --flow-id <flowId>',
     'lj-awb auth login --access-key <access-key>',
     'LINGJING_AWB_ACCESS_KEY=<access-key> lj-awb auth login',
+    'lj-awb auth logout',
     'lj-awb auth clear --dry-run',
   ],
   account: [
@@ -436,6 +551,7 @@ const GROUP_EXAMPLES = {
     '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 video-super-resolution --object-name material/video-super/example.mp4 --dry-run',
     '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> --platform JIMENG --file ./actor.png --name "女主正面" --dry-run',
@@ -446,6 +562,7 @@ const GROUP_EXAMPLES = {
     '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 video-super-resolution-status --task-id <superResolutionTaskId>',
     'lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180',
     'lj-awb task records --task-record-file .awb/tasks.jsonl',
   ],
@@ -470,8 +587,11 @@ const COMMAND_REQUIRED_OPTIONS = {
   'create video-fee': ['modelGroupCode'],
   'create video': ['modelGroupCode'],
   'create video-batch': ['inputFile', 'modelGroupCode'],
+  'create video-super-resolution-fee': ['objectName'],
+  'create video-super-resolution': ['objectName'],
   'task video-status': ['taskId'],
   'task video-subtitle-status': ['taskId'],
+  'task video-super-resolution-status': ['taskId'],
   'task wait': ['taskId', 'taskType'],
   'create asset-match-actor': ['description'],
   'create asset-groups': ['platform'],
@@ -521,6 +641,8 @@ const COMMAND_REQUIRED_ANY_OPTIONS = {
   'upload files': [['file', 'files', 'filesJson']],
   'create video-fee': [['prompt', 'resource', 'resourcesJson']],
   'create video': [['prompt', 'resource', 'resourcesJson']],
+  'create video-super-resolution-fee': [['objectName']],
+  'create video-super-resolution': [['objectName']],
   'create video-subtitle-removal': [['sourceTaskId']],
   'create asset-group-update': [['name', 'description', 'projectName']],
   'create asset': [['file', 'url', 'backendPath']],
@@ -586,6 +708,7 @@ const CONFIRMATION_COMMANDS = new Set([
   'create image-batch',
   'create video',
   'create video-batch',
+  'create video-super-resolution',
   'create video-subtitle-removal',
   'create asset-group',
   'create asset-group-update',
@@ -601,6 +724,7 @@ const COST_COMMANDS = new Set([
   'create image-batch',
   'create video',
   'create video-batch',
+  'create video-super-resolution',
   'create video-subtitle-removal',
 ]);
 
@@ -615,6 +739,7 @@ const REMOTE_WRITE_COMMANDS = new Set([
   'create image-batch',
   'create video',
   'create video-batch',
+  'create video-super-resolution',
   'create video-subtitle-removal',
   'create asset-group',
   'create asset-group-update',
@@ -626,24 +751,28 @@ const REMOTE_WRITE_COMMANDS = new Set([
 ]);
 
 const LOCAL_STATE_WRITE_COMMANDS = new Set([
+  'update',
   'auth login',
   'auth clear',
+  'auth logout',
   'project use',
   'project create',
   'project ensure',
 ]);
 
 const DESTRUCTIVE_COMMANDS = new Set(['auth clear', ...ARTIFACT_DELETE_COMMANDS]);
-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 LONG_RUNNING_COMMANDS = new Set(['auth login', 'task wait', 'task record-poll', 'create subject-wait', 'create subject-voice-wait']);
+const NETWORK_NONE_COMMANDS = new Set(['schema', 'auth status', 'auth clear', 'auth logout', 'model input-guide', 'task records']);
 const NETWORK_CONDITIONAL_COMMANDS = new Set(['doctor', 'auth login']);
 
 const OUTPUT_KIND_BY_COMMAND = {
   doctor: 'environment_report',
+  update: 'update_result',
   schema: 'command_schema',
   'auth status': 'auth_status',
   'auth verify': 'auth_status',
   'auth login': 'auth_result',
+  'auth logout': 'auth_result',
   'account info': 'account_summary',
   'account teams': 'team_list',
   'project list': 'project_list',
@@ -665,9 +794,12 @@ const OUTPUT_KIND_BY_COMMAND = {
   'create video-fee': 'fee_estimate',
   'create video': 'task_submission',
   'create video-batch': 'batch_task_submission',
+  'create video-super-resolution-fee': 'fee_estimate',
+  'create video-super-resolution': 'task_submission',
   'task video-status': 'task_status',
   'create video-subtitle-removal': 'subtitle_task_submission',
   'task video-subtitle-status': 'subtitle_task_status',
+  'task video-super-resolution-status': 'task_status',
   'task list': 'task_list',
   'task wait': 'task_status',
   'task records': 'local_task_records',
@@ -743,6 +875,8 @@ const PREFLIGHTS_BY_COMMAND = {
   '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 video-super-resolution-fee': ['doctor --verify', 'create video-super-resolution-fee --object-name <objectName>'],
+  'create video-super-resolution': ['doctor --verify', 'create video-super-resolution --object-name <objectName> --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'],
@@ -805,9 +939,10 @@ function buildCommandSafety(command, optionKeys) {
   const costsPoints = COST_COMMANDS.has(name);
   const destructive = DESTRUCTIVE_COMMANDS.has(name);
   const supportsDryRun = optionKeys.has('dryRun');
+  const updateInstall = name === 'update';
   return {
-    safeToAutoRun: !(remoteWrite || localStateWrite || requiresConfirmation || costsPoints || destructive),
-    network: commandNetworkMode(name),
+    safeToAutoRun: !(remoteWrite || localStateWrite || requiresConfirmation || costsPoints || destructive || updateInstall),
+    network: updateInstall ? 'conditional' : commandNetworkMode(name),
     remoteWrite,
     localStateWrite,
     costsPoints,
@@ -829,6 +964,9 @@ function buildCommandWorkflow(command) {
   if (command.name === 'create video') {
     next.push('读取 data.taskId 和 data.nextCommand', '立即运行响应里的 nextCommand，或 task wait --task-type VIDEO_GROUP 等待结果');
   }
+  if (command.name === 'create video-super-resolution') {
+    next.push('读取 data.taskId 和 data.nextCommand', '运行响应里的 task video-super-resolution-status 命令查询结果');
+  }
   if (command.name === 'create video-subtitle-removal') {
     next.push('读取 data.taskId 和 data.nextCommand', '运行 task video-subtitle-status 或响应里的 nextCommand 等待结果');
   }
@@ -839,12 +977,12 @@ function buildCommandWorkflow(command) {
     next.push('读取 data.voiceRecordId / data.externalId', 'externalId 为空时立刻运行 create subject-voice-wait 获取 nextVoiceArg');
   }
   if (command.name === 'create asset') {
-    next.push('读取 data.assetPath', '若后端返回审核 taskId，再运行 task wait --task-type ASSET_REGISTER');
+    next.push('读取 data.assetType / data.assetPath', 'data.conversionRequired=true 时先确认是否转码；正式执行可交互确认或追加 --auto-convert', '若后端返回审核 taskId，再运行 task wait --task-type ASSET_REGISTER');
   }
   if (command.name === 'model image-models' || command.name === 'model video-models') {
     next.push('读取 data.models[] 得到全部候选；用户给了模型口语名时保留同族全部候选，不只取第一个');
     next.push('对每个候选运行 model options --model-group-code <modelGroupCode> 查看真实参数和素材约束');
-    next.push('先向用户展示候选模型 + 参数取值 + 资源能力，再推荐模型或进入 fee/dry-run');
+    next.push('向用户展示候选模型 + 参数取值 + 资源能力后 STOP；等待用户选择或明确授权默认，未确认不得进入 create-spec/fee/dry-run/create');
   }
   if (command.name === 'model asset-review-models') {
     next.push('读取 data.models[].platform', '用 create asset-groups --platform <platform> 查重或创建素材组');
@@ -868,11 +1006,167 @@ function buildCommandWorkflow(command) {
   };
 }
 
+function buildDomainSummaries(commands) {
+  const domains = new Map();
+  for (const command of commands) {
+    const group = commandGroup(command);
+    domains.set(group, {
+      name: group,
+      description: GROUP_DESCRIPTIONS[group] || '',
+      commandCount: (domains.get(group)?.commandCount || 0) + 1,
+    });
+  }
+  return Array.from(domains.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function requiredOptionsForCommand(command) {
+  const requiredOptions = new Set();
+  if (commandGroup(command) === 'artifact') requiredOptions.add('projectId');
+  for (const key of COMMAND_REQUIRED_OPTIONS[command.name] || []) requiredOptions.add(key);
+  return [...requiredOptions];
+}
+
+function requiredAnyOptionsForCommand(command) {
+  return COMMAND_REQUIRED_ANY_OPTIONS[command.name] || [];
+}
+
+function buildCommandSchemaEntry(command) {
+  const requiredOptions = requiredOptionsForCommand(command);
+  const requiredAnyOptions = requiredAnyOptionsForCommand(command);
+  const optionKeys = new Set((command.args || []).map((arg) => normalizeKey(arg.name)));
+  return {
+    name: command.name,
+    domain: commandGroup(command),
+    command: commandSubcommand(command),
+    invocation: `${commandPrefix()} ${command.name}`,
+    helpCommand: `${commandPrefix()} ${command.name} -h`,
+    summary: summaryOf(command),
+    description: renderCliText(summaryOf(command)),
+    examples: extractExamples(command).map(renderCliText),
+    jsonExamples: extractExamples(command).map(asJsonExample),
+    requiredOptions,
+    requiredAnyOptions,
+    safety: buildCommandSafety(command, optionKeys),
+    workflow: buildCommandWorkflow(command),
+    options: (command.args || []).map((arg) => {
+      const key = normalizeKey(arg.name);
+      return {
+        name: arg.name,
+        key,
+        flag: formatOptionName(arg.name),
+        valueName: arg.valueName || null,
+        required: requiredOptions.includes(key),
+        requiredAnyGroup: requiredAnyOptions.find((group) => group.includes(key)) || null,
+        description: arg.description || '',
+      };
+    }),
+  };
+}
+
+function namesWhere(entries, predicate) {
+  return entries.filter(predicate).map((entry) => entry.name);
+}
+
+function buildAgentBrief(commands, version = 'unknown') {
+  const contract = buildAgentContract();
+  const entries = commands.map(buildCommandSchemaEntry);
+  const domains = buildDomainSummaries(commands).map((domain) => ({
+    ...domain,
+    commands: entries
+      .filter((entry) => entry.domain === domain.name)
+      .map((entry) => entry.name),
+  }));
+  return {
+    schemaVersion: 1,
+    kind: 'agent_brief',
+    cli: {
+      name: 'lj-awb',
+      version,
+      commandPrefix: commandPrefix(),
+    },
+    commandCount: entries.length,
+    domains,
+    outputPolicy: {
+      agentRecommendedOutputFormat: contract.agentRecommendedOutputFormat,
+      scriptRecommendedOutputFormat: contract.scriptRecommendedOutputFormat,
+      textFlag: contract.textFlag,
+      jsonFlag: contract.jsonFlag,
+      policy: contract.outputPolicy,
+    },
+    statePolicy: contract.statePolicy,
+    workflowPolicy: contract.workflowPolicy,
+    safetyPolicy: {
+      confirmationPolicy: contract.confirmationPolicy,
+      dryRunPolicy: contract.dryRunPolicy,
+      remoteWriteCount: namesWhere(entries, (entry) => entry.safety.remoteWrite).length,
+      costsPointsCount: namesWhere(entries, (entry) => entry.safety.costsPoints).length,
+      localStateWriteCount: namesWhere(entries, (entry) => entry.safety.localStateWrite).length,
+      destructiveCount: namesWhere(entries, (entry) => entry.safety.destructive).length,
+      longRunningCount: namesWhere(entries, (entry) => entry.safety.longRunning).length,
+    },
+    commandClasses: {
+      costsPoints: namesWhere(entries, (entry) => entry.safety.costsPoints),
+      remoteWrite: namesWhere(entries, (entry) => entry.safety.remoteWrite),
+      localStateWrite: namesWhere(entries, (entry) => entry.safety.localStateWrite),
+      destructive: namesWhere(entries, (entry) => entry.safety.destructive),
+      longRunning: namesWhere(entries, (entry) => entry.safety.longRunning),
+      safeRead: namesWhere(entries, (entry) => entry.safety.safeToAutoRun && entry.safety.network !== 'none'),
+      offlineRead: namesWhere(entries, (entry) => entry.safety.safeToAutoRun && entry.safety.network === 'none'),
+    },
+    routing: [
+      {
+        intent: '环境、认证、账号、团队、项目组、积分',
+        start: ['doctor --verify', 'account info', 'project current', 'credits balance'],
+        rule: '只读查询可自动运行；切换团队、切换/创建/更新项目组和清空认证按 safety dry-run/confirm 处理。',
+      },
+      {
+        intent: '模型发现和创作任务',
+        start: ['model image-models', 'model video-models', 'model options', 'model create-spec'],
+        rule: '先展示候选模型、真实参数和资源能力并 STOP；用户选择或明确授权默认后，关键参数确认，再只跑一次 fee、dry-run 和最终 --yes。',
+      },
+      {
+        intent: '上传、主体、音色、素材加白',
+        start: ['upload files', 'create subject-list', 'create subject-voice-list', 'model asset-review-models'],
+        rule: '复用已上传 backendPath、已有主体/音色/素材组；素材加白平台来自 model asset-review-models 或用户明确选择。',
+      },
+      {
+        intent: '异步任务和批量恢复',
+        start: ['task wait', 'task record-poll', 'task records'],
+        rule: '优先复用 create 返回的 nextCommand；批量任务使用 task-record-file，失败项单独重试。',
+      },
+      {
+        intent: '最终产物 artifact',
+        start: ['artifact script', 'artifact asset', 'artifact video', 'artifact clip'],
+        rule: 'artifact 使用 project-id，不是 project-group-no；写入/删除/导入先 dry-run，再一次性确认写入面。',
+      },
+    ],
+    lookup: {
+      preciseSchema: `${commandPrefix()} schema --domain <domain> --command <command> -f json`,
+      fullSchema: `${commandPrefix()} schema -f json`,
+      commandHelp: `${commandPrefix()} <domain> <command> -h`,
+      modelInputGuide: contract.modelInputGuide.textCommand,
+      schemaPolicy: contract.schemaPolicy,
+    },
+    canonicalFields: contract.canonicalFields,
+    resourceShortcut: contract.resourceShortcut,
+    resourcesJson: contract.resourcesJson,
+    modelCandidatePresentation: contract.modelCandidatePresentation,
+    taskTypes: contract.taskTypes,
+    exitCodes: contract.exitCodes,
+  };
+}
+
 function buildAgentContract() {
   return {
-    defaultOutputFormat: 'compact-text',
+    defaultOutputFormat: 'pretty',
+    humanDefaultOutputFormat: 'pretty',
+    agentRecommendedOutputFormat: 'text',
+    agentCompactOutputFormat: 'text',
+    scriptRecommendedOutputFormat: 'json',
     jsonFlag: '-f json',
-    outputPolicy: '默认输出精简 key=value 文本，只保留决策字段；需要稳定 JSON、嵌套结构或脚本严格解析时显式传 -f json 或 --json。JSON envelope 字段已做归一化，见 canonicalFields。',
+    textFlag: '-f text',
+    outputFormats: ['pretty', 'text', 'json', 'yaml', 'csv', 'auto'],
+    outputPolicy: '默认输出 pretty 人类友好视图，包含标题、摘要表格、列表表格和下一步建议；Agent 推荐显式传 -f text 读取稳定的分区 key=value 输出；脚本严格解析或需要完整嵌套结构时再传 -f json 或 --json。JSON envelope 字段已做归一化，见 canonicalFields。',
     statePolicy: {
       purpose: 'Agent 应在同一轮 / 同一项目中维护 AWB 上下文账本，减少重复查询和重复提交。',
       cacheKeys: [
@@ -890,12 +1184,13 @@ function buildAgentContract() {
       invalidation: '用户切换账号、团队、项目组、模型、素材、prompt 或关键参数后，只刷新受影响的缓存；不要重复跑未变化的 model options / create-spec / fee。',
     },
     workflowPolicy: [
-      '模型口语名命中后必须先展示候选模型、真实参数取值和资源能力；没有完成用户可见候选清单前，不得代选默认模型 / 参数，也不得进入 fee 或 dry-run。',
+      '模型口语名命中后必须先展示候选模型、真实参数取值和资源能力，并在清单后 STOP 等用户选择或明确授权默认；没有完成用户可见候选清单和确认前，不得代选默认模型 / 参数，也不得进入 create-spec、fee、dry-run 或 create。',
       '模型探索阶段只读 model list / options / create-spec；fee 只在用户确认关键参数后跑一次。',
+      'model options.params[] 中带 cliArg/genericModelParam 的新增模型配置参数可通过 --model-param key=value、--model-params-json 或同名下划线长参数传入；defaultValue 只能展示为候选默认，不能静默代选。',
       'supportsDryRun=true 的写入 / 扣费命令先 dry-run，确认后 yes；不要把 dry-run 当参数探索工具反复跑。',
       '用户给出多条同模型同参数任务时优先 batch + task-record-file，不要单条循环 create。',
       '命令返回 nextCommand / nextRefSubject / nextVoiceArg 时优先复用返回值，不手拼等价命令。',
-      '素材加白平台先通过 model asset-review-models 或用户明确输入确定；create asset-* 必须显式传 --platform，不要依赖默认平台。',
+      '素材加白平台先通过 model asset-review-models 或用户明确输入确定；create asset-* 必须显式传 --platform，不要依赖默认平台。create asset 会自动判断 assetType=Image/Video/Audio，本地文件会用 ffprobe 校验图片/视频尺寸、视频时长/FPS/像素数和音频时长；不合法素材正式执行时会询问是否转码，非交互场景可追加 --auto-convert；macOS + Homebrew 环境缺失时 CLI 会自动安装 ffmpeg。',
       '旧根域 image / video / asset / subject 已移除；只使用 create / task / artifact 等 schema 暴露的 domain。',
     ],
     canonicalFields: {
@@ -909,7 +1204,7 @@ function buildAgentContract() {
         { canonical: 'pointCost', aliases: ['points', 'point', 'costPoint', 'estimatePoint'], meaning: '本次任务预计 / 实际消耗积分' },
       ],
     },
-    schemaPolicy: 'schema 是机器契约，只给摘要、参数 key、安全规则和示例；查看长帮助用 schema.commands[].helpCommand 或 lj-awb <domain> <command> -h。',
+    schemaPolicy: 'Agent 先读 schema --brief 建立能力地图；执行具体命令前再读精确 schema --domain <domain> --command <command>。完整 schema -f json 只用于覆盖校验、脚本生成或调试 schema 本身；查看长帮助用 schema.commands[].helpCommand 或 lj-awb <domain> <command> -h。',
     confirmationPolicy: 'schema.commands[].safety.requiresConfirmation=true 的命令，Agent 必须先向用户确认，再追加 --yes。',
     dryRunPolicy: 'schema.commands[].safety.supportsDryRun=true 的写入 / 扣费命令，正式执行前优先跑 --dry-run。',
     resourceShortcut: {
@@ -936,32 +1231,39 @@ function buildAgentContract() {
     modelCandidatePresentation: {
       purpose: '把 model image-models / video-models 与每个候选的 model options 转成用户可见清单，避免 Agent 内部看完 options 后直接代选。',
       trigger: '用户问有哪些模型、给出口语名、或模型列表返回候选时都触发；即使只有一个候选也要展示真实可选项。',
+      gateType: 'hard_stop',
+      stopAfterPresentation: true,
+      resumeCondition: '用户选择模型和关键参数，或明确说“按默认 / 你来选”。',
       requiredVisibleFields: ['displayName', 'modelDesc', 'taskQueueNum', 'quality values/default', 'ratio values/default', 'duration or generateNum values/default', 'resource modes/media/usages', 'channel or fast/pro differences'],
-      blockedBeforePresentation: ['create image-fee', 'create video-fee', 'create image --dry-run', 'create video --dry-run', 'default model recommendation', 'default quality/ratio/duration choice'],
+      blockedBeforePresentation: ['model create-spec', 'create image-fee', 'create video-fee', 'create image-batch --dry-run', 'create video-batch --dry-run', 'create image --dry-run', 'create video --dry-run', 'create image', 'create video', 'default model recommendation', 'default quality/ratio/duration choice'],
     },
     modelOptions: {
       command: `${commandPrefix()} model options --model-group-code <code>`,
+      textCommand: `${commandPrefix()} model options --model-group-code <code> -f text`,
       jsonCommand: `${commandPrefix()} model options --model-group-code <code> -f json`,
-      purpose: '查询指定模型支持的 CLI 参数、枚举值、默认值、素材约束和条件约束。',
+      purpose: '查询指定模型支持的 CLI 参数、枚举值、默认值、素材约束和条件约束。Agent 默认读 textCommand；只有程序化校验完整嵌套结构时读 jsonCommand。',
       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'],
+      keyFields: ['params[].key', 'params[].cliArg', 'params[].genericModelParam', '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>`,
+      textCommand: `${commandPrefix()} model create-spec --model-group-code <code> -f text`,
       jsonCommand: `${commandPrefix()} model create-spec --model-group-code <code> -f json`,
-      purpose: '查看指定模型如何组织 create 命令：输入模式、素材绑定规则、示例和创建前检查项。',
+      purpose: '查看指定模型如何组织 create 命令：输入模式、素材绑定规则、示例和创建前检查项。Agent 默认读 textCommand；只有程序化校验完整嵌套结构时读 jsonCommand。',
       useBefore: ['create image-fee', 'create image', 'create video-fee', 'create video'],
       keyFields: ['inputRequirement', 'supportedIntents', 'validationRules', 'agentGuidance', 'preflight', 'examples'],
     },
     modelInputGuide: {
       command: `${commandPrefix()} model input-guide`,
+      textCommand: `${commandPrefix()} model input-guide -f text`,
       jsonCommand: `${commandPrefix()} model input-guide -f json`,
-      purpose: '查看跨模型统一创建参数、resources 字段和素材绑定规则。',
+      purpose: '查看跨模型统一创建参数、resources 字段和素材绑定规则。Agent 默认读 textCommand；脚本严格解析时读 jsonCommand。',
       useBefore: ['model options', 'model create-spec'],
     },
     taskTypes: {
       image: 'IMAGE_CREATE',
       video: 'VIDEO_GROUP',
+      videoSuperResolution: 'VIDEO_SUPER_RESOLUTION',
       subtitleRemoval: 'VIDEO_SUBTITLE_REMOVAL',
       assetRegister: 'ASSET_REGISTER',
     },
@@ -982,17 +1284,10 @@ function buildAgentContract() {
 }
 
 function buildCommandSchema(commands, kwargs = {}, version = 'unknown') {
+  if (toBool(kwargs.brief)) return buildAgentBrief(commands, version);
   const domainFilter = String(kwargs.domain ?? '').trim();
   const commandFilter = String(kwargs.command ?? '').trim();
-  const domains = new Map();
-  for (const command of commands) {
-    const group = commandGroup(command);
-    domains.set(group, {
-      name: group,
-      description: GROUP_DESCRIPTIONS[group] || '',
-      commandCount: (domains.get(group)?.commandCount || 0) + 1,
-    });
-  }
+  const domains = buildDomainSummaries(commands);
   const filteredCommands = commands
     .filter((command) => !domainFilter || commandGroup(command) === domainFilter)
     .filter((command) => !commandFilter || command.name === commandFilter || commandSubcommand(command) === commandFilter);
@@ -1016,49 +1311,16 @@ function buildCommandSchema(commands, kwargs = {}, version = 'unknown') {
       `${commandPrefix()} <domain> <command> -h`,
     ],
     globalOptions: [
-      { flag: '-f, --format json', key: 'format', description: '输出 JSON；默认不传时输出精简文本' },
+      { flag: '-f, --format <format>', key: 'format', description: '输出格式：pretty（默认）、text、json、yaml、csv、auto' },
       { flag: '--json', key: 'format', value: 'json', description: '等同于 -f json' },
       { flag: '-h, --help', key: 'help', description: '查看帮助' },
       { flag: '-v, --version', key: 'version', description: '查看版本' },
     ],
     agentContract: buildAgentContract(),
-    domains: Array.from(domains.values())
+    domains: domains
       .filter((domain) => !shouldFilterDomains || matchedDomains.has(domain.name))
       .sort((a, b) => a.name.localeCompare(b.name)),
-    commands: filteredCommands.map((command) => {
-      const requiredOptions = new Set();
-      if (commandGroup(command) === 'artifact') requiredOptions.add('projectId');
-      for (const key of COMMAND_REQUIRED_OPTIONS[command.name] || []) requiredOptions.add(key);
-      const requiredAnyOptions = COMMAND_REQUIRED_ANY_OPTIONS[command.name] || [];
-      const optionKeys = new Set((command.args || []).map((arg) => normalizeKey(arg.name)));
-      return {
-        name: command.name,
-        domain: commandGroup(command),
-        command: commandSubcommand(command),
-        invocation: `${commandPrefix()} ${command.name}`,
-        helpCommand: `${commandPrefix()} ${command.name} -h`,
-        summary: summaryOf(command),
-        description: renderCliText(summaryOf(command)),
-        examples: extractExamples(command).map(renderCliText),
-        jsonExamples: extractExamples(command).map(asJsonExample),
-        requiredOptions: [...requiredOptions],
-        requiredAnyOptions,
-        safety: buildCommandSafety(command, optionKeys),
-        workflow: buildCommandWorkflow(command),
-        options: (command.args || []).map((arg) => {
-          const key = normalizeKey(arg.name);
-          return {
-            name: arg.name,
-            key,
-            flag: formatOptionName(arg.name),
-            valueName: arg.valueName || null,
-            required: requiredOptions.has(key),
-            requiredAnyGroup: requiredAnyOptions.find((group) => group.includes(key)) || null,
-            description: arg.description || '',
-          };
-        }),
-      };
-    }),
+    commands: filteredCommands.map(buildCommandSchemaEntry),
   };
 }
 
@@ -1071,43 +1333,44 @@ function printRootHelp(commands, version) {
   }
 
   const lines = [
-    `lj-awb v${version}`,
+    helpTitle(`lj-awb v${version}`),
     '',
-    '灵境 AWB 命令行工具。默认输出精简文本；需要 JSON 时传 -f json。',
+    '灵境 AWB 命令行工具。默认输出人类友好的 pretty 视图；Agent 建议显式传 -f text，脚本严格解析用 -f json。',
     '',
-    'Usage:',
-    `  ${commandPrefix()} <domain> <command> [options]`,
-    `  ${commandPrefix()} <command> [options]`,
-    `  ${commandPrefix()} <domain> -h`,
-    `  ${commandPrefix()} <domain> <command> -h`,
+    helpHeading('Usage:'),
+    helpCommand(`  ${commandPrefix()} <domain> <command> [options]`),
+    helpCommand(`  ${commandPrefix()} <command> [options]`),
+    helpCommand(`  ${commandPrefix()} <domain> -h`),
+    helpCommand(`  ${commandPrefix()} <domain> <command> -h`),
     '',
-    'Quick start:',
-    `  ${commandPrefix()} auth status`,
-    `  ${commandPrefix()} auth login --access-key <access-key>`,
-    `  ${commandPrefix()} model image-models --model Banana`,
-    `  ${commandPrefix()} model input-guide`,
-    `  ${commandPrefix()} model options --model-group-code <code>`,
-    `  ${commandPrefix()} model create-spec --model-group-code <code>`,
-    `  ${commandPrefix()} create image --model-group-code <code> --prompt "一只小狗" --dry-run`,
+    helpHeading('Quick start:'),
+    helpCommand(`  ${commandPrefix()} auth status`),
+    helpCommand(`  ${commandPrefix()} auth login --access-key <access-key>`),
+    helpCommand(`  ${commandPrefix()} model image-models --model Banana`),
+    helpCommand(`  ${commandPrefix()} model input-guide`),
+    helpCommand(`  ${commandPrefix()} model options --model-group-code <code>`),
+    helpCommand(`  ${commandPrefix()} model create-spec --model-group-code <code>`),
+    helpCommand(`  ${commandPrefix()} create image --model-group-code <code> --prompt "一只小狗" --dry-run`),
     '',
-    'Command groups:',
+    helpHeading('Command groups:'),
   ];
   for (const [group] of groups.entries()) {
-    lines.push(`  ${group.padEnd(12)} ${GROUP_DESCRIPTIONS[group] || ''}`);
+    lines.push(`  ${helpGroup(group.padEnd(12))} ${GROUP_DESCRIPTIONS[group] || ''}`);
   }
   lines.push(
     '',
-    'More help:',
-    `  ${commandPrefix()} <domain> -h`,
-    `  ${commandPrefix()} <domain> <command> -h`,
-    `  ${commandPrefix()} schema -f json`,
-    `  ${commandPrefix()} doctor -h`,
+    helpHeading('More help:'),
+    helpCommand(`  ${commandPrefix()} <domain> -h`),
+    helpCommand(`  ${commandPrefix()} <domain> <command> -h`),
+    helpCommand(`  ${commandPrefix()} schema --brief -f json`),
+    helpCommand(`  ${commandPrefix()} schema -f json`),
+    helpCommand(`  ${commandPrefix()} doctor -h`),
     '',
-    'Global options:',
-    '  -f, --format json       输出 JSON；默认不传时输出精简文本',
-    '  --json                  等同于 -f json',
-    '  -h, --help              查看帮助',
-    '  -v, --version           查看版本',
+    helpHeading('Global options:'),
+    `  ${helpOption('-f, --format <format>')}   输出格式：pretty（默认）、text、json、yaml、csv、auto`,
+    `  ${helpOption('--json'.padEnd(22))} 等同于 -f json`,
+    `  ${helpOption('-h, --help'.padEnd(22))} 查看帮助`,
+    `  ${helpOption('-v, --version'.padEnd(22))} 查看版本`,
   );
   process.stdout.write(`${lines.join('\n')}\n`);
 }
@@ -1119,27 +1382,27 @@ function printGroupHelp(group, commands, version) {
   const directItems = hasSubgroups ? items.filter((command) => !commandSubgroupTokens(command)) : [];
 
   const lines = [
-    `lj-awb v${version}`,
+    helpTitle(`lj-awb v${version}`),
     '',
     GROUP_DESCRIPTIONS[group] || `${group} 命令组`,
     '',
-    'Usage:',
+    helpHeading('Usage:'),
   ];
   if (group === 'system') {
-    lines.push(`  ${commandPrefix()} <command> [options]`);
+    lines.push(helpCommand(`  ${commandPrefix()} <command> [options]`));
   } else if (hasSubgroups) {
-    if (directItems.length) lines.push(`  ${commandPrefix()} ${group} <command> [options]`);
-    lines.push(`  ${commandPrefix()} ${group} <subdomain> <command> [options]`);
+    if (directItems.length) lines.push(helpCommand(`  ${commandPrefix()} ${group} <command> [options]`));
+    lines.push(helpCommand(`  ${commandPrefix()} ${group} <subdomain> <command> [options]`));
   } else {
-    lines.push(`  ${commandPrefix()} ${group} <command> [options]`);
+    lines.push(helpCommand(`  ${commandPrefix()} ${group} <command> [options]`));
   }
   lines.push('');
   if (group === 'system') {
-    lines.push(`提示：system 是命令组；下面的命令可直接运行，例如 ${commandPrefix()} doctor。`);
+    lines.push(helpMuted(`提示：system 是命令组；下面的命令可直接运行，例如 ${commandPrefix()} doctor。`));
   } else if (hasSubgroups) {
-    lines.push(`提示：${group} 下按子领域分组；先选子领域再看具体命令。`);
+    lines.push(helpMuted(`提示：${group} 下按子领域分组；先选子领域再看具体命令。`));
   } else {
-    lines.push(`提示：${group} 是命令组；请选择下面的子命令运行。`);
+    lines.push(helpMuted(`提示：${group} 是命令组；请选择下面的子命令运行。`));
   }
   lines.push('');
 
@@ -1147,43 +1410,43 @@ function printGroupHelp(group, commands, version) {
     const presentSubgroups = new Set(
       items
         .map((command) => commandSubgroupTokens(command))
-        .filter(Boolean)
-        .map(([, subgroup]) => subgroup),
+      .filter(Boolean)
+      .map(([, subgroup]) => subgroup),
     );
-    lines.push('Subdomains:');
+    lines.push(helpHeading('Subdomains:'));
     for (const [subgroup, description] of Object.entries(subgroupMap)) {
       if (!presentSubgroups.has(subgroup)) continue;
-      lines.push(`  ${subgroup.padEnd(10)} ${description}`);
+      lines.push(`  ${helpGroup(subgroup.padEnd(10))} ${description}`);
     }
     if (directItems.length) {
-      lines.push('', 'Commands:');
+      lines.push('', helpHeading('Commands:'));
       for (const command of directItems) {
         const subcommand = commandSubcommand(command);
-        lines.push(`  ${subcommand.padEnd(28)} ${summaryOf(command)}`);
+        lines.push(`  ${helpCommand(subcommand.padEnd(28))} ${summaryOf(command)}`);
       }
     }
   } else {
-    lines.push('Commands:');
+    lines.push(helpHeading('Commands:'));
     for (const command of items) {
       const subcommand = commandSubcommand(command);
-      lines.push(`  ${subcommand.padEnd(28)} ${summaryOf(command)}`);
+      lines.push(`  ${helpCommand(subcommand.padEnd(28))} ${summaryOf(command)}`);
     }
   }
 
   if (GROUP_EXAMPLES[group]?.length) {
-    lines.push('', 'Examples:');
+    lines.push('', helpHeading('Examples:'));
     for (const example of GROUP_EXAMPLES[group]) {
-      lines.push(`  ${renderCliText(example)}`);
+      lines.push(helpCommand(`  ${renderCliText(example)}`));
     }
   }
-  lines.push('', 'More help:');
+  lines.push('', helpHeading('More help:'));
   if (group === 'system') {
-    for (const command of items) lines.push(`  ${commandPrefix()} ${command.name} -h`);
+    for (const command of items) lines.push(helpCommand(`  ${commandPrefix()} ${command.name} -h`));
   } else if (hasSubgroups) {
-    lines.push(`  ${commandPrefix()} ${group} <subdomain> -h`);
-    lines.push(`  ${commandPrefix()} ${group} <subdomain> <command> -h`);
+    lines.push(helpCommand(`  ${commandPrefix()} ${group} <subdomain> -h`));
+    lines.push(helpCommand(`  ${commandPrefix()} ${group} <subdomain> <command> -h`));
   } else {
-    lines.push(`  ${commandPrefix()} ${group} <command> -h`);
+    lines.push(helpCommand(`  ${commandPrefix()} ${group} <command> -h`));
   }
   process.stdout.write(`${lines.join('\n')}\n`);
 }
@@ -1195,50 +1458,58 @@ function printSubgroupHelp(group, subgroup, commands, version) {
   });
   const description = SUBGROUP_DESCRIPTIONS[group]?.[subgroup] || `${group} ${subgroup} 子领域`;
   const lines = [
-    `lj-awb v${version}`,
+    helpTitle(`lj-awb v${version}`),
     '',
     description,
     '',
-    'Usage:',
-    `  ${commandPrefix()} ${group} ${subgroup} <command> [options]`,
+    helpHeading('Usage:'),
+    helpCommand(`  ${commandPrefix()} ${group} ${subgroup} <command> [options]`),
     '',
-    'Commands:',
+    helpHeading('Commands:'),
   ];
   for (const command of items) {
     const parts = String(command.name || '').split(' ').filter(Boolean);
     const tail = parts.slice(2).join(' ');
-    lines.push(`  ${tail.padEnd(28)} ${summaryOf(command)}`);
+    lines.push(`  ${helpCommand(tail.padEnd(28))} ${summaryOf(command)}`);
   }
   const examples = SUBGROUP_EXAMPLES[`${group} ${subgroup}`];
   if (examples?.length) {
-    lines.push('', 'Examples:');
+    lines.push('', helpHeading('Examples:'));
     for (const example of examples) {
-      lines.push(`  ${renderCliText(example)}`);
+      lines.push(helpCommand(`  ${renderCliText(example)}`));
     }
   }
-  lines.push('', 'More help:');
-  lines.push(`  ${commandPrefix()} ${group} ${subgroup} <command> -h`);
+  lines.push('', helpHeading('More help:'));
+  lines.push(helpCommand(`  ${commandPrefix()} ${group} ${subgroup} <command> -h`));
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 
 function printCommandHelp(command) {
-  const lines = [`Usage: ${commandPrefix()} ${command.name} [options]`, '', renderCliText(command.description || '')];
+  const lines = [helpHeading(`Usage: ${commandPrefix()} ${command.name} [options]`), '', renderCliText(command.description || '')];
   if (command.args?.length) {
-    lines.push('', 'Options:');
+    lines.push('', helpHeading('Options:'));
     for (const arg of command.args) {
       const value = arg.valueName ? ` <${arg.valueName}>` : '';
       const description = arg.description ? `  ${arg.description}` : '';
-      lines.push(`  --${arg.name}${value}${description}`);
+      lines.push(`  ${helpOption(`--${arg.name}${value}`)}${description}`);
     }
   }
-  lines.push('', 'Global options:', '  -f, --format json       输出 JSON；默认不传时输出精简文本', '  --json                  等同于 -f json');
+  lines.push(
+    '',
+    helpHeading('Global options:'),
+    `  ${helpOption('-f, --format <format>')}   输出格式：pretty（默认）、text、json、yaml、csv、auto`,
+    `  ${helpOption('--json'.padEnd(22))} 等同于 -f json`,
+  );
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 
 function validateCommandOptions(command, kwargs, kwargRawFlags = {}) {
   const allowedKeys = (command.args || []).map((arg) => normalizeKey(arg.name));
   const allowed = new Set(allowedKeys);
-  const unknown = Object.keys(kwargs).filter((key) => !allowed.has(key));
+  const unknown = Object.keys(kwargs).filter((key) => (
+    !allowed.has(key)
+    && !(command.allowDynamicModelParams && isAllowedDynamicModelParamFlag(key))
+  ));
   if (!unknown.length) return;
   const displayFlag = (key) => kwargRawFlags[key] || formatOptionName(key);
   const suggestions = {};
@@ -1271,23 +1542,78 @@ function validateCommandOptions(command, kwargs, kwargRawFlags = {}) {
   });
 }
 
+function normalizeDynamicModelParamFlags(command, kwargs = {}, kwargRawFlags = {}) {
+  if (!command.allowDynamicModelParams) return;
+  const allowed = new Set((command.args || []).map((arg) => normalizeKey(arg.name)));
+  for (const key of Object.keys(kwargs)) {
+    if (allowed.has(key) || key.includes('_')) continue;
+    const flag = kwargRawFlags[key] || formatOptionName(key);
+    if (!flag.startsWith('--') || !flag.includes('-')) continue;
+    const normalized = flag.slice(2).replaceAll('-', '_');
+    if (!normalized || normalized === key || allowed.has(normalized)) continue;
+    if (kwargs[normalized] === undefined) kwargs[normalized] = kwargs[key];
+    delete kwargs[key];
+    if (kwargRawFlags[key] && !kwargRawFlags[normalized]) kwargRawFlags[normalized] = kwargRawFlags[key];
+  }
+}
+
+function isAllowedDynamicModelParamFlag(key) {
+  return /^(generation|prompt|negative|seed|style|mode|cfg|guidance|aspect|image|video|audio|subject|output|response|media|safety|watermark|camera|motion|strength|steps)_/i.test(String(key || ''));
+}
+
 function printData(data, format, meta = {}, context = {}) {
-  if (format === 'json') {
+  const outputFormat = resolveOutputFormat(format);
+  if (outputFormat === 'json') {
     process.stdout.write(`${JSON.stringify(createEnvelope({ status: 'success', data: normalizeJsonData(meta.command, data), meta }), null, 2)}\n`);
     return;
   }
-  process.stdout.write(formatTextOutput(meta.command, data, context));
+  if (outputFormat === 'yaml') {
+    process.stdout.write(formatYamlEnvelope(createEnvelope({ status: 'success', data: normalizeJsonData(meta.command, data), meta })));
+    return;
+  }
+  if (outputFormat === 'csv') {
+    process.stdout.write(formatCsvOutput(meta.command, data, context));
+    return;
+  }
+  if (outputFormat === 'text') {
+    process.stdout.write(formatTextOutput(meta.command, data, context));
+    return;
+  }
+  process.stdout.write(formatPrettyOutput(meta.command, data, context));
+}
+
+function printUpdateNotice(updateNotice) {
+  if (!updateNotice?.message) return;
+  process.stderr.write(`${updateNotice.message}\n`);
+}
+
+function isStructuredOutputFormat(format) {
+  try {
+    return ['json', 'yaml'].includes(resolveOutputFormat(format));
+  } catch {
+    return false;
+  }
 }
 
 function printError(error, format, meta = {}) {
+  let outputFormat = 'text';
+  try {
+    outputFormat = resolveOutputFormat(format);
+  } catch {
+    outputFormat = 'text';
+  }
   const payload = {
     type: error.type || 'error',
     message: error.message || String(error),
     ...(error.hint ? { hint: error.hint } : {}),
     ...(error.details ? { details: error.details } : {}),
   };
-  if (format === 'json') {
+  if (outputFormat === 'json') {
     process.stderr.write(`${JSON.stringify(createEnvelope({ status: 'error', error: payload, meta }), null, 2)}\n`);
+  } else if (outputFormat === 'yaml') {
+    process.stderr.write(formatYamlEnvelope(createEnvelope({ status: 'error', error: payload, meta })));
+  } else if (outputFormat === 'pretty') {
+    process.stderr.write(formatPrettyError(payload));
   } else {
     process.stderr.write(formatTextError(payload));
   }
@@ -1330,6 +1656,7 @@ export async function runStandaloneCli(argv = process.argv.slice(2)) {
   const { commandName: rawCommandName, kwargs, kwargRawFlags, format } = parseArgv(argv);
   const commandName = resolveCommandName(rawCommandName, commands);
   const command = commands.find((item) => item.name === commandName);
+  const updateNotice = await resolveUpdateNotice(argv, commandName || rawCommandName, version);
   if (!command) {
     if (isCommandSubgroupName(rawCommandName, commands)) {
       const [group, subgroup] = rawCommandName.split(' ');
@@ -1344,18 +1671,27 @@ export async function runStandaloneCli(argv = process.argv.slice(2)) {
       type: 'unknown_command',
       exitCode: 2,
       hint: unknownCommandHint(rawCommandName),
-    }), format, { command: rawCommandName });
+    }), format, {
+      command: rawCommandName,
+      ...(updateNotice ? { _notice: { update: updateNotice } } : {}),
+    });
     process.exitCode = 2;
+    if (!isStructuredOutputFormat(format)) printUpdateNotice(updateNotice);
     return;
   }
 
   const startedAt = Date.now();
   try {
+    const outputFormat = resolveOutputFormat(format);
+    normalizeDynamicModelParamFlags(command, kwargs, kwargRawFlags);
     validateCommandOptions(command, kwargs, kwargRawFlags);
     const data = command.virtual === 'schema'
       ? buildCommandSchema(commands, kwargs, version)
       : await command.func({ command }, kwargs);
-    printData(data, format, { command: command.name, elapsedMs: Date.now() - startedAt }, buildOutputContext(command, kwargs));
+    const meta = { command: command.name, elapsedMs: Date.now() - startedAt };
+    if (updateNotice) meta._notice = { update: updateNotice };
+    printData(data, outputFormat, meta, buildOutputContext(command, kwargs, data));
+    if (outputFormat !== 'json' && outputFormat !== 'yaml') printUpdateNotice(updateNotice);
   } catch (error) {
     const cliError = error instanceof LingjingAwbCliError
       ? error