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

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

@@ -3,7 +3,15 @@ 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 {
+  formatCsvOutput,
+  formatPrettyError,
+  formatPrettyOutput,
+  formatTextError,
+  formatTextOutput,
+  formatYamlEnvelope,
+  normalizeJsonData,
+} from './output.js';
 
 function normalizeKey(value) {
   return String(value || '').replace(/-([a-z])/g, (_, char) => char.toUpperCase());
@@ -24,6 +32,7 @@ const OPTION_SYNONYMS = {
   threads: ['concurrency'],
   output: ['format'],
   json: ['format'],
+  keyword: ['model'],
   input: ['inputFile'],
   in: ['inputFile'],
   dry: ['dryRun'],
@@ -60,6 +69,16 @@ function suggestSimilarOptions(unknownKey, allowedKeys) {
   for (const syn of synonyms) {
     if (allowedKeys.includes(syn)) record(syn, -1);
   }
+  if (unknownKey.length === 1) {
+    const ch = unknownKey.toLowerCase();
+    for (const allowed of allowedKeys) {
+      if (allowed.toLowerCase().startsWith(ch)) record(allowed, 1);
+    }
+    return [...scored.entries()]
+      .sort((x, y) => x[1] - y[1])
+      .slice(0, 3)
+      .map(([key]) => formatOptionName(key));
+  }
   for (const allowed of allowedKeys) {
     const a = unknownKey.toLowerCase();
     const b = allowed.toLowerCase();
@@ -85,6 +104,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);
@@ -130,6 +200,8 @@ 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 } })
@@ -138,6 +210,28 @@ function buildOutputContext(command, kwargs = {}) {
   };
 }
 
+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;
@@ -153,7 +247,8 @@ function assignKwarg(kwargs, key, value) {
 function parseArgv(argv) {
   const commandParts = [];
   const kwargs = {};
-  let format = 'text';
+  const kwargRawFlags = {};
+  let format = 'pretty';
 
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
@@ -182,10 +277,27 @@ function parseArgv(argv) {
       }
       continue;
     }
+    if (token.length > 1 && token.startsWith('-') && /^-[A-Za-z]/.test(token)) {
+      const raw = token.slice(1);
+      const eqIndex = raw.indexOf('=');
+      const keyPart = eqIndex >= 0 ? raw.slice(0, eqIndex) : raw;
+      const inlineValue = eqIndex >= 0 ? raw.slice(eqIndex + 1) : undefined;
+      const key = normalizeKey(keyPart);
+      if (!(key in kwargRawFlags)) kwargRawFlags[key] = token;
+      if (inlineValue !== undefined) {
+        assignKwarg(kwargs, key, inlineValue);
+      } else if (argv[index + 1] && !argv[index + 1].startsWith('-')) {
+        assignKwarg(kwargs, key, argv[index + 1]);
+        index += 1;
+      } else {
+        assignKwarg(kwargs, key, true);
+      }
+      continue;
+    }
     commandParts.push(token);
   }
 
-  return { commandName: commandParts.join(' '), kwargs, format };
+  return { commandName: commandParts.join(' '), kwargs, kwargRawFlags, format };
 }
 
 async function readVersion() {
@@ -203,13 +315,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' },
     ],
@@ -366,6 +480,7 @@ const GROUP_EXAMPLES = {
   system: [
     'lj-awb doctor',
     'lj-awb doctor --verify',
+    'lj-awb schema --brief -f json',
     'lj-awb schema -f json',
     'lj-awb schema --domain create -f json',
   ],
@@ -812,6 +927,23 @@ function buildCommandWorkflow(command) {
   if (command.name === 'create asset') {
     next.push('读取 data.assetPath', '若后端返回审核 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('向用户展示候选模型 + 参数取值 + 资源能力后 STOP；等待用户选择或明确授权默认，未确认不得进入 create-spec/fee/dry-run/create');
+  }
+  if (command.name === 'model asset-review-models') {
+    next.push('读取 data.models[].platform', '用 create asset-groups --platform <platform> 查重或创建素材组');
+  }
+  if (command.name === 'model options') {
+    next.push('读取 params/resources/constraints 确认参数与素材约束', '运行 model create-spec --model-group-code <code> 查看创建写法和示例');
+  }
+  if (command.name === 'model create-spec') {
+    next.push('按 examples / supportedIntents 组装命令', '用户确认关键参数后先运行 create image-fee 或 create video-fee，再 dry-run');
+  }
+  if (command.name === 'model input-guide') {
+    next.push('运行 model image-models 或 model video-models 选择模型', '选定模型后运行 model options --model-group-code <code>');
+  }
   if (['create image-batch', 'create video-batch', 'create subject-batch'].includes(command.name)) {
     next.push('读取每项 status / taskId / error', '使用 task record-poll 或对应 wait 命令恢复批量结果');
   }
@@ -822,11 +954,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: [
@@ -844,6 +1132,7 @@ function buildAgentContract() {
       invalidation: '用户切换账号、团队、项目组、模型、素材、prompt 或关键参数后，只刷新受影响的缓存；不要重复跑未变化的 model options / create-spec / fee。',
     },
     workflowPolicy: [
+      '模型口语名命中后必须先展示候选模型、真实参数取值和资源能力，并在清单后 STOP 等用户选择或明确授权默认；没有完成用户可见候选清单和确认前，不得代选默认模型 / 参数，也不得进入 create-spec、fee、dry-run 或 create。',
       '模型探索阶段只读 model list / options / create-spec；fee 只在用户确认关键参数后跑一次。',
       'supportsDryRun=true 的写入 / 扣费命令先 dry-run，确认后 yes；不要把 dry-run 当参数探索工具反复跑。',
       '用户给出多条同模型同参数任务时优先 batch + task-record-file，不要单条循环 create。',
@@ -862,7 +1151,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: {
@@ -886,24 +1175,36 @@ 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: ['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'],
     },
     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: {
@@ -929,17 +1230,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);
@@ -963,49 +1257,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),
   };
 }
 
@@ -1018,43 +1279,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`);
 }
@@ -1066,27 +1328,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('');
 
@@ -1094,43 +1356,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`);
 }
@@ -1142,90 +1404,127 @@ 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) {
+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));
   if (!unknown.length) return;
+  const displayFlag = (key) => kwargRawFlags[key] || formatOptionName(key);
   const suggestions = {};
   for (const unk of unknown) {
     const matches = suggestSimilarOptions(unk, allowedKeys);
-    if (matches.length) suggestions[formatOptionName(unk)] = matches;
+    if (matches.length) suggestions[displayFlag(unk)] = matches;
   }
+  const usedShortForm = unknown.some((key) => {
+    const flag = kwargRawFlags[key];
+    return flag && flag.startsWith('-') && !flag.startsWith('--');
+  });
   const baseHint = `运行 ${commandPrefix()} ${command.name} -h 查看可用参数。`;
+  const shortHint = usedShortForm
+    ? `本 CLI 仅支持 -f / -h / -v 等少数短选项，业务参数请使用 --xxx 长形式。`
+    : '';
   const suggestionParts = Object.entries(suggestions).map(([opt, matches]) => `${opt} → ${matches.join(' / ')}`);
-  const hint = suggestionParts.length
-    ? `你是不是想用：${suggestionParts.join('；')}？否则 ${baseHint}`
-    : baseHint;
-  throw new LingjingAwbCliError(`未知参数：${unknown.map(formatOptionName).join(', ')}`, {
+  const hintParts = [];
+  if (suggestionParts.length) hintParts.push(`你是不是想用：${suggestionParts.join('；')}？`);
+  if (shortHint) hintParts.push(shortHint);
+  hintParts.push(baseHint);
+  throw new LingjingAwbCliError(`未知参数：${unknown.map(displayFlag).join(', ')}`, {
     type: 'unknown_option',
     exitCode: 2,
-    hint,
+    hint: hintParts.join(' '),
     details: {
       command: command.name,
-      unknownOptions: unknown.map(formatOptionName),
+      unknownOptions: unknown.map(displayFlag),
       ...(Object.keys(suggestions).length ? { suggestions } : {}),
     },
   });
 }
 
 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 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));
   }
@@ -1265,7 +1564,7 @@ export async function runStandaloneCli(argv = process.argv.slice(2)) {
     return;
   }
 
-  const { commandName: rawCommandName, kwargs, format } = parseArgv(argv);
+  const { commandName: rawCommandName, kwargs, kwargRawFlags, format } = parseArgv(argv);
   const commandName = resolveCommandName(rawCommandName, commands);
   const command = commands.find((item) => item.name === commandName);
   if (!command) {
@@ -1289,11 +1588,12 @@ export async function runStandaloneCli(argv = process.argv.slice(2)) {
 
   const startedAt = Date.now();
   try {
-    validateCommandOptions(command, kwargs);
+    const outputFormat = resolveOutputFormat(format);
+    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));
+    printData(data, outputFormat, { command: command.name, elapsedMs: Date.now() - startedAt }, buildOutputContext(command, kwargs));
   } catch (error) {
     const cliError = error instanceof LingjingAwbCliError
       ? error