@lingjingai/lj-awb-cli-pre 0.3.15

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

@@ -0,0 +1,1213 @@
+import fs from 'node:fs/promises';
+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';
+
+function normalizeKey(value) {
+  return String(value || '').replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+function formatOptionName(value) {
+  return `--${String(value || '').replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`;
+}
+
+const OPTION_SYNONYMS = {
+  timeout: ['waitSeconds'],
+  deadline: ['waitSeconds'],
+  maxWait: ['waitSeconds'],
+  wait: ['waitSeconds'],
+  parallel: ['concurrency'],
+  workers: ['concurrency'],
+  jobs: ['concurrency'],
+  threads: ['concurrency'],
+  output: ['format'],
+  json: ['format'],
+  input: ['inputFile'],
+  in: ['inputFile'],
+  dry: ['dryRun'],
+  force: ['yes'],
+};
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (!m) return n;
+  if (!n) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+function suggestSimilarOptions(unknownKey, allowedKeys) {
+  const scored = new Map();
+  const record = (key, score) => {
+    if (!scored.has(key) || scored.get(key) > score) scored.set(key, score);
+  };
+  const synonyms = OPTION_SYNONYMS[unknownKey] || [];
+  for (const syn of synonyms) {
+    if (allowedKeys.includes(syn)) record(syn, -1);
+  }
+  for (const allowed of allowedKeys) {
+    const a = unknownKey.toLowerCase();
+    const b = allowed.toLowerCase();
+    if (b.includes(a) || a.includes(b)) {
+      record(allowed, 0);
+      continue;
+    }
+    const d = levenshtein(a, b);
+    const threshold = Math.max(2, Math.ceil(Math.min(a.length, b.length) / 3));
+    if (d <= threshold) record(allowed, d);
+  }
+  return [...scored.entries()]
+    .sort((x, y) => x[1] - y[1])
+    .slice(0, 3)
+    .map(([key]) => formatOptionName(key));
+}
+
+function commandPrefix() {
+  return process.env.LINGJING_AWB_COMMAND_PREFIX || 'lj-awb';
+}
+
+function renderCliText(value) {
+  return String(value ?? '').replace(/\blj-awb\b/g, commandPrefix());
+}
+
+function shellArg(value) {
+  const text = String(value ?? '');
+  return /^[A-Za-z0-9_./:=@,+-]+$/.test(text) ? text : JSON.stringify(text);
+}
+
+function appendCommandOption(parts, key, value) {
+  if (value === undefined || value === null || value === '') return;
+  if (Array.isArray(value)) {
+    for (const item of value) appendCommandOption(parts, key, item);
+    return;
+  }
+  const flag = formatOptionName(key);
+  if (value === true) {
+    parts.push(flag);
+    return;
+  }
+  parts.push(flag, shellArg(value));
+}
+
+function commandInvocation(commandName, kwargs = {}, options = {}) {
+  const omit = new Set(options.omit || []);
+  const sensitive = new Set(['accessKey']);
+  const next = { ...kwargs, ...(options.set || {}) };
+  const parts = [commandPrefix(), ...String(commandName || '').split(' ').filter(Boolean)];
+  for (const [key, value] of Object.entries(next)) {
+    if (omit.has(key) || sensitive.has(key)) continue;
+    appendCommandOption(parts, key, value);
+  }
+  return parts.join(' ');
+}
+
+function buildOutputContext(command, kwargs = {}) {
+  const optionKeys = new Set((command.args || []).map((arg) => normalizeKey(arg.name)));
+  const canSuggestDryRunExecution = command.name !== 'auth login';
+  const withoutDryRun = { omit: ['dryRun'] };
+  const isModelList = command.name === 'model image-models' || command.name === 'model video-models';
+  const modelListAll = isModelList && toBool(kwargs.all);
+  const modelListLimit = isModelList
+    ? (modelListAll ? Number.POSITIVE_INFINITY : Math.max(1, toInt(kwargs.limit, 8)))
+    : undefined;
+  const modelListMoreCommand = isModelList && !modelListAll
+    ? commandInvocation(command.name, kwargs, { omit: ['limit'], set: { all: true } })
+    : null;
+  return {
+    jsonCommand: `${commandInvocation(command.name, kwargs)} -f json`,
+    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 } })
+      : null,
+    ...(isModelList ? { listLimit: modelListLimit, moreCommand: modelListMoreCommand } : {}),
+  };
+}
+
+function assignKwarg(kwargs, key, value) {
+  if (kwargs[key] === undefined) {
+    kwargs[key] = value;
+    return;
+  }
+  if (Array.isArray(kwargs[key])) {
+    kwargs[key].push(value);
+    return;
+  }
+  kwargs[key] = [kwargs[key], value];
+}
+
+function parseArgv(argv) {
+  const commandParts = [];
+  const kwargs = {};
+  let format = 'text';
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '-f' || token === '--format') {
+      format = argv[index + 1] || 'json';
+      index += 1;
+      continue;
+    }
+    if (token === '--json') {
+      format = 'json';
+      continue;
+    }
+    if (token.startsWith('--')) {
+      const raw = token.slice(2);
+      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 (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 };
+}
+
+async function readVersion() {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  const packagePath = path.join(currentDir, '..', 'package.json');
+  const pkg = JSON.parse(await fs.readFile(packagePath, 'utf8'));
+  return pkg.version || 'unknown';
+}
+
+const VIRTUAL_COMMANDS = [
+  {
+    name: 'schema',
+    virtual: 'schema',
+    description: [
+      '输出机器可读命令 schema，供 Agent / 脚本理解命令、参数和示例',
+      '',
+      'Examples:',
+      '  lj-awb schema -f json',
+      '  lj-awb schema --domain video -f json',
+      '  lj-awb schema --domain image --command create -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' },
+    ],
+  },
+];
+
+const RENAMED_COMMAND_HINTS = {
+  'workspace me': 'account info',
+  'workspace teams': 'account teams',
+  'workspace team-select': 'account switch-team',
+  'workspace project-groups': 'project list',
+  'workspace project-group-current': 'project current',
+  'workspace project-group-select': 'project use',
+  'workspace project-group-users': 'project users',
+  'workspace project-group-create': 'project create',
+  'workspace project-group-update': 'project update',
+  'workspace project-group-ensure': 'project ensure',
+  'billing points': 'credits balance',
+  'billing usage-summary': 'credits usage',
+};
+
+const MODEL_LIST_GUESS_HINT = `按任务类型分开查询：生图候选用 ${'`'}lj-awb model image-models${'`'}，生视频候选用 ${'`'}lj-awb model video-models${'`'}。运行 lj-awb model -h 查看 model 域全部命令。`;
+const COMMAND_GUESS_HINTS = {
+  'model list': MODEL_LIST_GUESS_HINT,
+  'model models': MODEL_LIST_GUESS_HINT,
+  'model ls': MODEL_LIST_GUESS_HINT,
+  'model image': MODEL_LIST_GUESS_HINT,
+  'model video': MODEL_LIST_GUESS_HINT,
+  'models': MODEL_LIST_GUESS_HINT,
+};
+
+function buildRegistry() {
+  const commands = [];
+  registerAwbCommands((spec) => commands.push(spec));
+  return [...commands, ...VIRTUAL_COMMANDS];
+}
+
+function commandGroup(command) {
+  const parts = String(command.name || '').split(' ').filter(Boolean);
+  return parts.length === 1 ? 'system' : parts[0];
+}
+
+function commandSubcommand(command) {
+  const parts = String(command.name || '').split(' ').filter(Boolean);
+  return parts.length === 1 ? parts[0] : parts.slice(1).join(' ');
+}
+
+function isCommandGroupName(commandName, commands) {
+  return Boolean(commandName && commands.some((command) => commandGroup(command) === commandName));
+}
+
+function commandSubgroupTokens(command) {
+  const parts = String(command.name || '').split(' ').filter(Boolean);
+  if (parts.length < 3) return null;
+  return [parts[0], parts[1]];
+}
+
+function isCommandSubgroupName(commandName, commands) {
+  const parts = String(commandName || '').split(' ').filter(Boolean);
+  if (parts.length !== 2) return false;
+  const [group, subgroup] = parts;
+  if (!SUBGROUP_DESCRIPTIONS[group]?.[subgroup]) return false;
+  return commands.some((command) => {
+    const tokens = commandSubgroupTokens(command);
+    return tokens && tokens[0] === group && tokens[1] === subgroup;
+  });
+}
+
+function resolveCommandName(commandName, commands) {
+  const exact = commands.find((command) => command.name === commandName);
+  if (exact) return commandName;
+  const parts = String(commandName || '').split(' ').filter(Boolean);
+  if (parts[0] === 'system' && parts.length > 1) {
+    const rootCommandName = parts.slice(1).join(' ');
+    const rootCommand = commands.find((command) => command.name === rootCommandName && commandGroup(command) === 'system');
+    if (rootCommand) return rootCommand.name;
+  }
+  return commandName;
+}
+
+const GROUP_DESCRIPTIONS = {
+  system: '系统：环境体检和机器可读命令 schema',
+  auth: '认证：登录、查看和清空本地 access key',
+  account: '账号：查看账号和团队',
+  project: '项目：查看、切换、创建和更新项目组',
+  credits: '积分：查询可扣积分余额、项目组预算和用量统计',
+  model: '模型：查询生图 / 生视频模型、参数约束和创建用法',
+  upload: '上传：把本地文件上传为平台可访问素材',
+  image: '图片：估价、提交、批量提交和查询生图任务',
+  video: '视频：估价、提交、批量提交、查询和去字幕',
+  task: '任务：任务列表、等待和本地任务台账',
+  asset: '资产：素材库匹配、素材组和素材注册',
+  artifact: '最终产物：剧本、资产、视频、剪辑 CRUD 与本地 JSON 导入',
+  subject: '主体：发布和查询可复用主体资产',
+};
+
+const SUBGROUP_DESCRIPTIONS = {
+  artifact: {
+    script: '剧本：document / asset / state / speaker / episode / scene / action 行 CRUD 与 script.json 批量导入',
+    asset: '资产：角色 / 道具 / 场景 及其状态 CRUD，actors/props/locations JSON 批量导入',
+    video: '视频：集 / 场 / clip 三级最终产物 CRUD 与 storyboard 批量导入',
+    clip: '剪辑：按集组织的剪辑宽表 CRUD 与状态更新',
+  },
+};
+
+const SUBGROUP_EXAMPLES = {
+  'artifact script': [
+    'lj-awb artifact script import --project-id <projectId> --input-file 1_script/output/script.json --dry-run',
+    'lj-awb artifact script get --project-id <projectId>',
+    'lj-awb artifact script rows --project-id <projectId> --row-kind scene',
+  ],
+  'artifact asset': [
+    'lj-awb artifact asset import --project-id <projectId> --input-dir 2_asset/output --dry-run',
+    'lj-awb artifact asset actors --project-id <projectId> --include-states true',
+    'lj-awb artifact asset props --project-id <projectId>',
+  ],
+  'artifact video': [
+    'lj-awb artifact video import-storyboard --project-id <projectId> --input-file 3_footage/output/ep001/ep001_storyboard.json --dry-run',
+    'lj-awb artifact video episodes --project-id <projectId>',
+    'lj-awb artifact video clips --project-id <projectId> --episode-id ep_001 --scene-id scn_001',
+  ],
+  'artifact clip': [
+    'lj-awb artifact clip upsert-episode --project-id <projectId> --input-file 4_clip/output/ep001_clip_output.json --dry-run',
+    'lj-awb artifact clip episodes --project-id <projectId>',
+    'lj-awb artifact clip episode-by-id --project-id <projectId> --episode-id ep_001',
+  ],
+};
+
+const GROUP_EXAMPLES = {
+  system: [
+    'lj-awb doctor',
+    'lj-awb doctor --verify',
+    'lj-awb schema -f json',
+    'lj-awb schema --domain video -f json',
+  ],
+  auth: [
+    'lj-awb auth status',
+    'lj-awb auth verify',
+    'lj-awb auth login --access-key <access-key>',
+    'LINGJING_AWB_ACCESS_KEY=<access-key> lj-awb auth login',
+    'lj-awb auth clear --dry-run',
+  ],
+  account: [
+    'lj-awb account info',
+    'lj-awb account teams',
+    'lj-awb account switch-team --group-id <groupId> --yes',
+  ],
+  project: [
+    'lj-awb project list',
+    'lj-awb project current',
+    'lj-awb project use --project-group-no <no> --yes',
+    'lj-awb project create --name "CLI 测试项目" --point 1000 --yes',
+  ],
+  credits: [
+    'lj-awb credits balance',
+    'lj-awb credits usage --project-group-no <no> --last-hours 24',
+  ],
+  model: [
+    'lj-awb model image-models --model Banana',
+    'lj-awb model video-models --model Seedance',
+    'lj-awb model input-guide',
+    'lj-awb model options --model-group-code <code>',
+    'lj-awb model create-spec --model-group-code <code>',
+  ],
+  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>',
+  ],
+  task: [
+    'lj-awb task list --task-type IMAGE_CREATE --project-group-no <no>',
+    '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 = {
+  'account switch-team': ['groupId'],
+  'project create': ['name'],
+  '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'],
+  'task wait': ['taskId', 'taskType'],
+  'asset match-actor': ['description'],
+  'asset group': ['groupId'],
+  'asset group-create': ['name'],
+  'asset group-update': ['groupId'],
+  'asset register': ['groupId', 'name'],
+  'artifact script row': ['rowKind', 'entityKey'],
+  'artifact script children': ['parentKey'],
+  'artifact script delete-row': ['rowKind', 'entityKey'],
+  'artifact asset actor': ['actorKey'],
+  'artifact asset prop': ['propKey'],
+  'artifact asset location': ['locationKey'],
+  'artifact asset upsert-actor-state': ['actorKey'],
+  'artifact asset upsert-prop-state': ['propKey'],
+  'artifact asset upsert-location-state': ['locationKey'],
+  'artifact asset delete-actor': ['actorKey'],
+  'artifact asset delete-prop': ['propKey'],
+  'artifact asset delete-location': ['locationKey'],
+  'artifact asset delete-actor-state': ['actorKey', 'stateKey'],
+  'artifact asset delete-prop-state': ['propKey', 'stateKey'],
+  'artifact asset delete-location-state': ['locationKey', 'stateKey'],
+  'artifact video episode': ['episodeId'],
+  'artifact video scenes': ['episodeId'],
+  'artifact video scene': ['episodeId', 'sceneId'],
+  'artifact video clips': ['episodeId', 'sceneId'],
+  'artifact video clip': ['episodeId', 'sceneId', 'clipId'],
+  'artifact video upsert-scene': ['episodeId'],
+  'artifact video upsert-clip': ['episodeId', 'sceneId'],
+  'artifact video update-clip-urls': ['episodeId', 'sceneId', 'clipId', 'videoUrlsJson'],
+  'artifact video delete-episode': ['episodeId'],
+  'artifact video delete-scene': ['episodeId', 'sceneId'],
+  'artifact video delete-clip': ['episodeId', 'sceneId', 'clipId'],
+  'artifact video import-storyboard': ['inputFile'],
+  'artifact clip episode': ['videoEpisodeId'],
+  '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'],
+};
+
+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']],
+  'artifact script upsert-row': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-actor': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-prop': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-location': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-actor-state': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-prop-state': [['bodyJson', 'inputFile']],
+  'artifact asset upsert-location-state': [['bodyJson', 'inputFile']],
+  'artifact video upsert-episode': [['bodyJson', 'inputFile']],
+  'artifact video upsert-scene': [['bodyJson', 'inputFile']],
+  'artifact video upsert-clip': [['bodyJson', 'inputFile']],
+  'artifact clip upsert-episode': [['bodyJson', 'inputFile']],
+  'artifact clip upsert-batch': [['bodyJson', 'inputFile']],
+  'subject publish': [['resource']],
+};
+
+const ARTIFACT_WRITE_COMMANDS = [
+  'artifact script upsert-row',
+  'artifact script delete-row',
+  'artifact script import',
+  'artifact asset upsert-actor',
+  'artifact asset upsert-prop',
+  'artifact asset upsert-location',
+  'artifact asset upsert-actor-state',
+  'artifact asset upsert-prop-state',
+  'artifact asset upsert-location-state',
+  'artifact asset delete-actor',
+  'artifact asset delete-prop',
+  'artifact asset delete-location',
+  'artifact asset delete-actor-state',
+  'artifact asset delete-prop-state',
+  'artifact asset delete-location-state',
+  'artifact asset import',
+  'artifact video upsert-episode',
+  'artifact video upsert-scene',
+  'artifact video upsert-clip',
+  'artifact video update-clip-urls',
+  'artifact video delete-episode',
+  'artifact video delete-scene',
+  'artifact video delete-clip',
+  'artifact video import-storyboard',
+  'artifact clip upsert-episode',
+  'artifact clip upsert-batch',
+  'artifact clip update-status',
+  'artifact clip delete-episode',
+];
+
+const ARTIFACT_DELETE_COMMANDS = ARTIFACT_WRITE_COMMANDS.filter((name) => name.includes(' delete-'));
+
+const CONFIRMATION_COMMANDS = new Set([
+  'auth clear',
+  'account switch-team',
+  'project use',
+  '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',
+  ...ARTIFACT_WRITE_COMMANDS,
+  'subject publish',
+  'subject publish-batch',
+]);
+
+const COST_COMMANDS = new Set([
+  'image create',
+  'image create-batch',
+  'video create',
+  'video create-batch',
+]);
+
+const REMOTE_WRITE_COMMANDS = new Set([
+  'account switch-team',
+  'project use',
+  'project create',
+  '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',
+  ...ARTIFACT_WRITE_COMMANDS,
+  'subject publish',
+  'subject publish-batch',
+]);
+
+const LOCAL_STATE_WRITE_COMMANDS = new Set([
+  'auth login',
+  'auth clear',
+  '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', 'subject 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']);
+
+const OUTPUT_KIND_BY_COMMAND = {
+  doctor: 'environment_report',
+  schema: 'command_schema',
+  'auth status': 'auth_status',
+  'auth verify': 'auth_status',
+  'auth login': 'auth_result',
+  'account info': 'account_summary',
+  'account teams': 'team_list',
+  'project list': 'project_list',
+  'project current': 'project_summary',
+  'project users': 'project_user_list',
+  'credits balance': 'credits_balance',
+  'credits usage': 'credits_usage',
+  'model image-models': 'model_list',
+  'model video-models': 'model_list',
+  'model options': 'model_options',
+  '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',
+  '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',
+  'artifact script get': 'artifact_full',
+  'artifact script document': 'artifact_record',
+  'artifact script rows': 'artifact_list',
+  'artifact script row': 'artifact_record',
+  'artifact script children': 'artifact_list',
+  'artifact script upsert-row': 'artifact_write_result',
+  'artifact script delete-row': 'artifact_delete_result',
+  'artifact script import': 'artifact_import_result',
+  'artifact asset get': 'artifact_full',
+  'artifact asset actors': 'artifact_list',
+  'artifact asset actor': 'artifact_record',
+  'artifact asset props': 'artifact_list',
+  'artifact asset prop': 'artifact_record',
+  'artifact asset locations': 'artifact_list',
+  'artifact asset location': 'artifact_record',
+  'artifact asset upsert-actor': 'artifact_write_result',
+  'artifact asset upsert-prop': 'artifact_write_result',
+  'artifact asset upsert-location': 'artifact_write_result',
+  'artifact asset upsert-actor-state': 'artifact_write_result',
+  'artifact asset upsert-prop-state': 'artifact_write_result',
+  'artifact asset upsert-location-state': 'artifact_write_result',
+  'artifact asset delete-actor': 'artifact_delete_result',
+  'artifact asset delete-prop': 'artifact_delete_result',
+  'artifact asset delete-location': 'artifact_delete_result',
+  'artifact asset delete-actor-state': 'artifact_delete_result',
+  'artifact asset delete-prop-state': 'artifact_delete_result',
+  'artifact asset delete-location-state': 'artifact_delete_result',
+  'artifact asset import': 'artifact_import_result',
+  'artifact video get': 'artifact_full',
+  'artifact video episodes': 'artifact_list',
+  'artifact video episode': 'artifact_record',
+  'artifact video scenes': 'artifact_list',
+  'artifact video scene': 'artifact_record',
+  'artifact video clips': 'artifact_list',
+  'artifact video clip': 'artifact_record',
+  'artifact video upsert-episode': 'artifact_write_result',
+  'artifact video upsert-scene': 'artifact_write_result',
+  'artifact video upsert-clip': 'artifact_write_result',
+  'artifact video update-clip-urls': 'artifact_write_result',
+  'artifact video delete-episode': 'artifact_delete_result',
+  'artifact video delete-scene': 'artifact_delete_result',
+  'artifact video delete-clip': 'artifact_delete_result',
+  'artifact video import-storyboard': 'artifact_import_result',
+  'artifact clip get': 'artifact_full',
+  'artifact clip episodes': 'artifact_list',
+  'artifact clip episode': 'artifact_record',
+  'artifact clip episode-by-id': 'artifact_record',
+  'artifact clip upsert-episode': 'artifact_write_result',
+  'artifact clip upsert-batch': 'artifact_import_result',
+  'artifact clip update-status': 'artifact_status_update',
+  'artifact clip delete-episode': 'artifact_delete_result',
+};
+
+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'],
+  'upload files': ['upload files --dry-run'],
+};
+
+function summaryOf(command) {
+  return String(command.description || '').split('\n')[0];
+}
+
+function extractExamples(command) {
+  const lines = String(command.description || '').split('\n');
+  const examples = [];
+  let inExamples = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === 'Examples:') {
+      inExamples = true;
+      continue;
+    }
+    if (!inExamples) continue;
+    if (!trimmed) break;
+    if (/^[A-Za-z][A-Za-z ]+:$/.test(trimmed)) break;
+    examples.push(trimmed);
+  }
+  return examples;
+}
+
+function asJsonExample(example) {
+  const text = renderCliText(example);
+  if (/(^|\s)(-f\s+json|--format\s+json|--json)(\s|$)/.test(text)) return text;
+  return `${text} -f json`;
+}
+
+function commandNetworkMode(commandName) {
+  if (NETWORK_NONE_COMMANDS.has(commandName)) return 'none';
+  if (NETWORK_CONDITIONAL_COMMANDS.has(commandName)) return 'conditional';
+  return 'required';
+}
+
+function unknownCommandHint(commandName) {
+  const replacement = RENAMED_COMMAND_HINTS[commandName];
+  if (replacement) return `该命令已产品化命名为 ${commandPrefix()} ${replacement}。运行 ${commandPrefix()} ${replacement.split(' ')[0]} -h 查看同组命令。`;
+  const guess = COMMAND_GUESS_HINTS[commandName];
+  if (guess) return guess;
+  const group = String(commandName || '').split(' ').filter(Boolean)[0];
+  if (group === 'workspace') return `账号用 ${commandPrefix()} account ...，项目组用 ${commandPrefix()} project ...。运行 ${commandPrefix()} --help 查看可用命令。`;
+  if (group === 'billing') return `积分查询用 ${commandPrefix()} credits ...。运行 ${commandPrefix()} credits -h 查看可用命令。`;
+  return `运行 ${commandPrefix()} --help 查看可用命令。`;
+}
+
+function buildCommandSafety(command, optionKeys) {
+  const name = command.name;
+  const remoteWrite = REMOTE_WRITE_COMMANDS.has(name);
+  const localStateWrite = LOCAL_STATE_WRITE_COMMANDS.has(name);
+  const requiresConfirmation = CONFIRMATION_COMMANDS.has(name);
+  const costsPoints = COST_COMMANDS.has(name);
+  const destructive = DESTRUCTIVE_COMMANDS.has(name);
+  const supportsDryRun = optionKeys.has('dryRun');
+  return {
+    safeToAutoRun: !(remoteWrite || localStateWrite || requiresConfirmation || costsPoints || destructive),
+    network: commandNetworkMode(name),
+    remoteWrite,
+    localStateWrite,
+    costsPoints,
+    destructive,
+    requiresConfirmation,
+    confirmationFlag: requiresConfirmation ? '--yes' : null,
+    supportsDryRun,
+    dryRunFlag: supportsDryRun ? '--dry-run' : null,
+    longRunning: LONG_RUNNING_COMMANDS.has(name),
+  };
+}
+
+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 === 'subject publish') {
+    next.push('读取 data.elementId', '运行 subject wait 获取 externalId / nextRefSubject');
+  }
+  if (['image create-batch', 'video create-batch', 'subject publish-batch'].includes(command.name)) {
+    next.push('读取每项 status / taskId / error', '使用 task record-poll 或对应 wait 命令恢复批量结果');
+  }
+  return {
+    outputKind,
+    recommendedPreflight: PREFLIGHTS_BY_COMMAND[command.name] || (ARTIFACT_WRITE_COMMANDS.includes(command.name) ? [`${command.name} --dry-run`] : []),
+    nextActions: next,
+  };
+}
+
+function buildAgentContract() {
+  return {
+    defaultOutputFormat: 'compact-text',
+    jsonFlag: '-f json',
+    outputPolicy: '默认输出精简 key=value 文本，只保留决策字段；需要稳定 JSON、嵌套结构或脚本严格解析时显式传 -f json 或 --json。JSON envelope 字段已做归一化，见 canonicalFields。',
+    canonicalFields: {
+      purpose: 'CLI 输出对上游平台多版本字段做了归一化。Agent 只识别 canonical 列，遇到 aliases 列出的旧字段名时说明是上游原始返回，CLI 已在 text / 归一化层做了 fallback。不要把旧名当成独立新字段对外报告。',
+      fields: [
+        { canonical: 'billingPointBalance', aliases: ['teamPointBalance'], meaning: '实际可扣积分余额（/api/anime/member/benefits/queryGroupPoint）' },
+        { canonical: 'billingPointRemainingAfter', aliases: ['teamPointRemainingAfter'], meaning: '本次任务后预计可扣积分余额' },
+        { canonical: 'projectBudgetBalance', aliases: ['projectPointBalance'], meaning: '项目组预算 / ROI 余额（不是积分）' },
+        { canonical: 'projectBudgetMax', aliases: ['projectPointMax'], meaning: '项目组预算上限' },
+        { canonical: 'projectBudgetRemainingAfter', aliases: ['projectPointRemainingAfter'], meaning: '本次任务后预计项目组预算余额' },
+        { canonical: 'pointCost', aliases: ['points', 'point', 'costPoint', 'estimatePoint'], meaning: '本次任务预计 / 实际消耗积分' },
+      ],
+    },
+    schemaPolicy: 'schema 是机器契约，只给摘要、参数 key、安全规则和示例；查看长帮助用 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: {
+      flag: '--resource',
+      syntax: 'type:usage[:reference_key]=path|url|asset:<id>; image create uses image:reference=... without key',
+      examples: [
+        'image:reference=./ref.png',
+        'image:first_frame=./hero.png',
+        'image:first_frame=asset:<assetId>',
+        'subject:reference:hero=asset:<externalId>',
+      ],
+    },
+    resourcesJson: {
+      flag: '--resources-json',
+      shape: [
+        {
+          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',
+          source: { kind: 'url|asset_id', value: '<local-file-or-http-url-or-material-backendPath-or-asset-id>' },
+        },
+      ],
+    },
+    modelOptions: {
+      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'],
+      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'],
+      keyFields: ['inputRequirement', 'supportedIntents', 'validationRules', 'agentGuidance', 'preflight', 'examples'],
+    },
+    modelInputGuide: {
+      command: `${commandPrefix()} model input-guide`,
+      jsonCommand: `${commandPrefix()} model input-guide -f json`,
+      purpose: '查看跨模型统一创建参数、resources 字段和素材绑定规则。',
+      useBefore: ['model options', 'model create-spec'],
+    },
+    taskTypes: {
+      image: 'IMAGE_CREATE',
+      video: 'VIDEO_GROUP',
+    },
+    exitCodes: [
+      { code: 0, type: 'success', meaning: '命令成功' },
+      { code: 1, type: 'runtime_error', meaning: '普通运行失败或平台业务失败' },
+      { 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: 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: 30, type: 'network_error', meaning: '网络、TLS、HTTP 或外部平台不可用' },
+    ],
+  };
+}
+
+function buildCommandSchema(commands, kwargs = {}, version = 'unknown') {
+  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 filteredCommands = commands
+    .filter((command) => !domainFilter || commandGroup(command) === domainFilter)
+    .filter((command) => !commandFilter || command.name === commandFilter || commandSubcommand(command) === commandFilter);
+  const matchedDomains = new Set(filteredCommands.map((command) => commandGroup(command)));
+  const shouldFilterDomains = Boolean(domainFilter || commandFilter);
+  return {
+    schemaVersion: 1,
+    filters: {
+      domain: domainFilter || null,
+      command: commandFilter || null,
+    },
+    cli: {
+      name: 'lj-awb',
+      version,
+      commandPrefix: commandPrefix(),
+    },
+    usage: [
+      `${commandPrefix()} <domain> <command> [options]`,
+      `${commandPrefix()} <command> [options]`,
+      `${commandPrefix()} <domain> -h`,
+      `${commandPrefix()} <domain> <command> -h`,
+    ],
+    globalOptions: [
+      { flag: '-f, --format json', key: 'format', description: '输出 JSON；默认不传时输出精简文本' },
+      { 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())
+      .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 || '',
+          };
+        }),
+      };
+    }),
+  };
+}
+
+function printRootHelp(commands, version) {
+  const groups = new Map();
+  for (const command of commands) {
+    const group = commandGroup(command);
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(command);
+  }
+
+  const lines = [
+    `lj-awb v${version}`,
+    '',
+    '灵境 AWB 命令行工具。默认输出精简文本；需要 JSON 时传 -f json。',
+    '',
+    'Usage:',
+    `  ${commandPrefix()} <domain> <command> [options]`,
+    `  ${commandPrefix()} <command> [options]`,
+    `  ${commandPrefix()} <domain> -h`,
+    `  ${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()} image create --model-group-code <code> --prompt "一只小狗" --dry-run`,
+    '',
+    'Command groups:',
+  ];
+  for (const [group] of groups.entries()) {
+    lines.push(`  ${group.padEnd(12)} ${GROUP_DESCRIPTIONS[group] || ''}`);
+  }
+  lines.push(
+    '',
+    'More help:',
+    `  ${commandPrefix()} <domain> -h`,
+    `  ${commandPrefix()} <domain> <command> -h`,
+    `  ${commandPrefix()} schema -f json`,
+    `  ${commandPrefix()} doctor -h`,
+    '',
+    'Global options:',
+    '  -f, --format json       输出 JSON；默认不传时输出精简文本',
+    '  --json                  等同于 -f json',
+    '  -h, --help              查看帮助',
+    '  -v, --version           查看版本',
+  );
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+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 lines = [
+    `lj-awb v${version}`,
+    '',
+    GROUP_DESCRIPTIONS[group] || `${group} 命令组`,
+    '',
+    'Usage:',
+  ];
+  if (group === 'system') {
+    lines.push(`  ${commandPrefix()} <command> [options]`);
+  } else if (hasSubgroups) {
+    lines.push(`  ${commandPrefix()} ${group} <subdomain> <command> [options]`);
+  } else {
+    lines.push(`  ${commandPrefix()} ${group} <command> [options]`);
+  }
+  lines.push('');
+  if (group === 'system') {
+    lines.push(`提示：system 是命令组；下面的命令可直接运行，例如 ${commandPrefix()} doctor。`);
+  } else if (hasSubgroups) {
+    lines.push(`提示：${group} 下按子领域分组；先选子领域再看具体命令。`);
+  } else {
+    lines.push(`提示：${group} 是命令组；请选择下面的子命令运行。`);
+  }
+  lines.push('');
+
+  if (hasSubgroups) {
+    const presentSubgroups = new Set(
+      items
+        .map((command) => commandSubgroupTokens(command))
+        .filter(Boolean)
+        .map(([, subgroup]) => subgroup),
+    );
+    lines.push('Subdomains:');
+    for (const [subgroup, description] of Object.entries(subgroupMap)) {
+      if (!presentSubgroups.has(subgroup)) continue;
+      lines.push(`  ${subgroup.padEnd(10)} ${description}`);
+    }
+  } else {
+    lines.push('Commands:');
+    for (const command of items) {
+      const subcommand = commandSubcommand(command);
+      lines.push(`  ${subcommand.padEnd(28)} ${summaryOf(command)}`);
+    }
+  }
+
+  if (GROUP_EXAMPLES[group]?.length) {
+    lines.push('', 'Examples:');
+    for (const example of GROUP_EXAMPLES[group]) {
+      lines.push(`  ${renderCliText(example)}`);
+    }
+  }
+  lines.push('', 'More help:');
+  if (group === 'system') {
+    for (const command of items) lines.push(`  ${commandPrefix()} ${command.name} -h`);
+  } else if (hasSubgroups) {
+    lines.push(`  ${commandPrefix()} ${group} <subdomain> -h`);
+    lines.push(`  ${commandPrefix()} ${group} <subdomain> <command> -h`);
+  } else {
+    lines.push(`  ${commandPrefix()} ${group} <command> -h`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function printSubgroupHelp(group, subgroup, commands, version) {
+  const items = commands.filter((command) => {
+    const tokens = commandSubgroupTokens(command);
+    return tokens && tokens[0] === group && tokens[1] === subgroup;
+  });
+  const description = SUBGROUP_DESCRIPTIONS[group]?.[subgroup] || `${group} ${subgroup} 子领域`;
+  const lines = [
+    `lj-awb v${version}`,
+    '',
+    description,
+    '',
+    'Usage:',
+    `  ${commandPrefix()} ${group} ${subgroup} <command> [options]`,
+    '',
+    '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)}`);
+  }
+  const examples = SUBGROUP_EXAMPLES[`${group} ${subgroup}`];
+  if (examples?.length) {
+    lines.push('', 'Examples:');
+    for (const example of examples) {
+      lines.push(`  ${renderCliText(example)}`);
+    }
+  }
+  lines.push('', 'More help:');
+  lines.push(`  ${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 || '')];
+  if (command.args?.length) {
+    lines.push('', '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('', 'Global options:', '  -f, --format json       输出 JSON；默认不传时输出精简文本', '  --json                  等同于 -f json');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function validateCommandOptions(command, kwargs) {
+  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 suggestions = {};
+  for (const unk of unknown) {
+    const matches = suggestSimilarOptions(unk, allowedKeys);
+    if (matches.length) suggestions[formatOptionName(unk)] = matches;
+  }
+  const baseHint = `运行 ${commandPrefix()} ${command.name} -h 查看可用参数。`;
+  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(', ')}`, {
+    type: 'unknown_option',
+    exitCode: 2,
+    hint,
+    details: {
+      command: command.name,
+      unknownOptions: unknown.map(formatOptionName),
+      ...(Object.keys(suggestions).length ? { suggestions } : {}),
+    },
+  });
+}
+
+function printData(data, format, meta = {}, context = {}) {
+  if (format === '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));
+}
+
+function printError(error, format, meta = {}) {
+  const payload = {
+    type: error.type || 'error',
+    message: error.message || String(error),
+    ...(error.hint ? { hint: error.hint } : {}),
+    ...(error.details ? { details: error.details } : {}),
+  };
+  if (format === 'json') {
+    process.stderr.write(`${JSON.stringify(createEnvelope({ status: 'error', error: payload, meta }), null, 2)}\n`);
+  } else {
+    process.stderr.write(formatTextError(payload));
+  }
+}
+
+export async function runStandaloneCli(argv = process.argv.slice(2)) {
+  process.env.LINGJING_AWB_COMMAND_PREFIX ??= 'lj-awb';
+  const commands = buildRegistry();
+  const version = await readVersion().catch(() => 'unknown');
+
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    const parsed = parseArgv(argv.filter((item) => item !== '-h' && item !== '--help'));
+    const resolvedCommandName = resolveCommandName(parsed.commandName, commands);
+    const command = commands.find((item) => item.name === resolvedCommandName);
+    if (command) {
+      printCommandHelp(command);
+    } else if (isCommandSubgroupName(parsed.commandName, commands)) {
+      const [group, subgroup] = parsed.commandName.split(' ');
+      printSubgroupHelp(group, subgroup, commands, version);
+    } else if (isCommandGroupName(parsed.commandName, commands)) {
+      printGroupHelp(parsed.commandName, commands, version);
+    } else {
+      printRootHelp(commands, version);
+    }
+    return;
+  }
+
+  if (argv.length === 1 && ['-v', '--version'].includes(argv[0])) {
+    process.stdout.write(`lj-awb v${version}\n`);
+    return;
+  }
+
+  const { commandName: rawCommandName, kwargs, format } = parseArgv(argv);
+  const commandName = resolveCommandName(rawCommandName, commands);
+  const command = commands.find((item) => item.name === commandName);
+  if (!command) {
+    if (isCommandSubgroupName(rawCommandName, commands)) {
+      const [group, subgroup] = rawCommandName.split(' ');
+      printSubgroupHelp(group, subgroup, commands, version);
+      return;
+    }
+    if (isCommandGroupName(rawCommandName, commands)) {
+      printGroupHelp(rawCommandName, commands, version);
+      return;
+    }
+    printError(new LingjingAwbCliError(`未知命令: ${rawCommandName || '(empty)'}`, {
+      type: 'unknown_command',
+      exitCode: 2,
+      hint: unknownCommandHint(rawCommandName),
+    }), format, { command: rawCommandName });
+    process.exitCode = 2;
+    return;
+  }
+
+  const startedAt = Date.now();
+  try {
+    validateCommandOptions(command, kwargs);
+    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));
+  } catch (error) {
+    const cliError = error instanceof LingjingAwbCliError
+      ? error
+      : new LingjingAwbCliError(error.message || String(error), { type: 'runtime_error', exitCode: 1 });
+    printError(cliError, format, { command: command.name, elapsedMs: Date.now() - startedAt });
+    process.exitCode = cliError.exitCode || 1;
+  }
+}