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

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LingjingAwbCliError, createEnvelope, toBool, toInt } from './common.js';
 import { registerAwbCommands } from './commands.js';
+import { checkCliUpdate } from './update.js';
 import {
   formatCsvOutput,
   formatPrettyError,
@@ -186,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
@@ -204,12 +209,27 @@ function buildOutputContext(command, kwargs = {}) {
     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',
@@ -342,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',
@@ -480,6 +503,8 @@ 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',
@@ -487,8 +512,12 @@ const GROUP_EXAMPLES = {
   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: [
@@ -522,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',
@@ -532,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',
   ],
@@ -556,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'],
@@ -607,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']],
@@ -672,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',
@@ -687,6 +724,7 @@ const COST_COMMANDS = new Set([
   'create image-batch',
   'create video',
   'create video-batch',
+  'create video-super-resolution',
   'create video-subtitle-removal',
 ]);
 
@@ -701,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',
@@ -712,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',
@@ -751,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',
@@ -829,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'],
@@ -891,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,
@@ -915,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 等待结果');
   }
@@ -925,7 +977,7 @@ 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[] 得到全部候选；用户给了模型口语名时保留同族全部候选，不只取第一个');
@@ -1134,10 +1186,11 @@ function buildAgentContract() {
     workflowPolicy: [
       '模型口语名命中后必须先展示候选模型、真实参数取值和资源能力，并在清单后 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: {
@@ -1190,7 +1243,7 @@ function buildAgentContract() {
       jsonCommand: `${commandPrefix()} model options --model-group-code <code> -f json`,
       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>`,
@@ -1210,6 +1263,7 @@ function buildAgentContract() {
     taskTypes: {
       image: 'IMAGE_CREATE',
       video: 'VIDEO_GROUP',
+      videoSuperResolution: 'VIDEO_SUPER_RESOLUTION',
       subtitleRemoval: 'VIDEO_SUBTITLE_REMOVAL',
       assetRegister: 'ASSET_REGISTER',
     },
@@ -1452,7 +1506,10 @@ function printCommandHelp(command) {
 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 = {};
@@ -1485,6 +1542,25 @@ 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 = {}) {
   const outputFormat = resolveOutputFormat(format);
   if (outputFormat === 'json') {
@@ -1506,6 +1582,19 @@ function printData(data, format, meta = {}, context = {}) {
   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 {
@@ -1567,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(' ');
@@ -1581,19 +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, outputFormat, { 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

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

@@ -0,0 +1,327 @@
+import { execFile } from 'node:child_process';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import {
+  LingjingAwbCliError,
+  loadState,
+  nowIso,
+  saveState,
+  toBool,
+  toInt,
+  trimToNull,
+} from './common.js';
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_CLI_PACKAGE_NAME = '@lingjingai/lj-awb-cli';
+const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org/';
+const DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_NPM_TIMEOUT_MS = 15_000;
+const AUTO_CHECK_TIMEOUT_MS = 4_000;
+
+function commandPrefix() {
+  return process.env.LINGJING_AWB_COMMAND_PREFIX || 'lj-awb';
+}
+
+function boolEnv(value) {
+  return ['1', 'true', 'yes', 'y', 'on'].includes(String(value ?? '').trim().toLowerCase());
+}
+
+function readPackageJsonSync(packagePath) {
+  try {
+    return JSON.parse(fsSync.readFileSync(packagePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function corePackagePath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+}
+
+function rootPackagePath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
+}
+
+export async function readCurrentCliVersion() {
+  const pkg = JSON.parse(await fs.readFile(corePackagePath(), 'utf8'));
+  return pkg.version || 'unknown';
+}
+
+function currentRootDir() {
+  return path.dirname(rootPackagePath());
+}
+
+function isLocalCheckout() {
+  return fsSync.existsSync(path.join(currentRootDir(), '.git'));
+}
+
+export function resolveCliPackageName(kwargs = {}) {
+  const explicit = trimToNull(kwargs.packageName || kwargs.package || process.env.LINGJING_AWB_CLI_PACKAGE);
+  if (explicit) return explicit;
+  const rootPkg = readPackageJsonSync(rootPackagePath());
+  const name = trimToNull(rootPkg?.name);
+  return name?.startsWith('@lingjingai/lj-awb-cli') ? name : DEFAULT_CLI_PACKAGE_NAME;
+}
+
+function resolveRegistry(kwargs = {}) {
+  return trimToNull(
+    kwargs.registry
+    || process.env.LINGJING_AWB_UPDATE_REGISTRY
+    || process.env.NPM_CONFIG_REGISTRY
+    || process.env.npm_config_registry,
+  ) || DEFAULT_NPM_REGISTRY;
+}
+
+function updateCheckIntervalMs() {
+  const raw = process.env.LINGJING_AWB_UPDATE_CHECK_INTERVAL_MS;
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_CHECK_INTERVAL_MS;
+  return Math.max(0, toInt(raw, DEFAULT_CHECK_INTERVAL_MS));
+}
+
+function updateCheckDisabled() {
+  return boolEnv(process.env.LINGJING_AWB_DISABLE_UPDATE_CHECK)
+    || boolEnv(process.env.AWB_DISABLE_UPDATE_CHECK)
+    || ['0', 'false', 'off', 'no'].includes(String(process.env.LINGJING_AWB_UPDATE_CHECK ?? '').trim().toLowerCase());
+}
+
+function forceAutoUpdateCheck() {
+  return boolEnv(process.env.LINGJING_AWB_UPDATE_CHECK)
+    || String(process.env.LINGJING_AWB_UPDATE_CHECK || '').trim().toLowerCase() === 'force';
+}
+
+function parseVersion(value) {
+  const text = String(value || '').trim().replace(/^v/i, '');
+  const [main, pre = ''] = text.split('-', 2);
+  const parts = main.split('.').map((item) => Number.parseInt(item, 10));
+  if (parts.some((item) => !Number.isFinite(item))) return null;
+  return { parts, pre };
+}
+
+export function semverLessThan(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return false;
+  for (let index = 0; index < 3; index += 1) {
+    const lv = left.parts[index] || 0;
+    const rv = right.parts[index] || 0;
+    if (lv < rv) return true;
+    if (lv > rv) return false;
+  }
+  if (left.pre && !right.pre) return true;
+  if (!left.pre && right.pre) return false;
+  return left.pre < right.pre;
+}
+
+function npmArgsWithRegistry(args, registry) {
+  return registry ? [...args, `--registry=${registry}`] : args;
+}
+
+function npmInstallSpec(packageName, version) {
+  return version && version !== 'latest' ? `${packageName}@${version}` : packageName;
+}
+
+async function runNpm(args, options = {}) {
+  try {
+    const result = await execFileAsync('npm', args, {
+      cwd: currentRootDir(),
+      encoding: 'utf8',
+      timeout: options.timeoutMs || DEFAULT_NPM_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+      env: process.env,
+    });
+    return result;
+  } catch (error) {
+    const stderr = String(error.stderr || '').trim();
+    const stdout = String(error.stdout || '').trim();
+    throw new LingjingAwbCliError('npm 命令执行失败', {
+      type: 'network_error',
+      exitCode: 30,
+      hint: stderr || stdout || error.message || '请确认 npm 可用，并且当前网络可以访问 npm registry。',
+      details: {
+        command: `npm ${args.join(' ')}`,
+        code: error.code,
+        signal: error.signal,
+      },
+    });
+  }
+}
+
+export async function fetchLatestCliVersion(options = {}) {
+  const mocked = trimToNull(process.env.LINGJING_AWB_UPDATE_LATEST_VERSION);
+  if (mocked) return mocked;
+  const packageName = options.packageName || resolveCliPackageName(options);
+  const registry = options.registry || resolveRegistry(options);
+  const result = await runNpm(
+    npmArgsWithRegistry(['view', packageName, 'version'], registry),
+    { timeoutMs: options.timeoutMs || DEFAULT_NPM_TIMEOUT_MS },
+  );
+  const version = String(result.stdout || '').trim().replace(/^"|"$/g, '');
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new LingjingAwbCliError('无法识别 npm latest 版本', {
+      type: 'runtime_error',
+      exitCode: 1,
+      hint: `npm view ${packageName} version 返回了非 semver 内容。`,
+      details: { version },
+    });
+  }
+  return version;
+}
+
+function buildUpdateNotice({ currentVersion, latestVersion, packageName, checkedAt }) {
+  const command = `${commandPrefix()} update`;
+  return {
+    message: `检测到 ${commandPrefix()} 新版本 ${latestVersion}（当前 ${currentVersion}）。运行 ${command} 更新 CLI 和 skill。`,
+    command,
+    checkCommand: `${commandPrefix()} update --check`,
+    packageName,
+    currentVersion,
+    latestVersion,
+    checkedAt,
+  };
+}
+
+function cachedNotice(state, currentVersion, packageName) {
+  const cached = state?.updateCheck;
+  if (!cached || cached.packageName !== packageName || cached.currentVersion !== currentVersion) return null;
+  if (!cached.latestVersion || !semverLessThan(currentVersion, cached.latestVersion)) return null;
+  return buildUpdateNotice({
+    currentVersion,
+    latestVersion: cached.latestVersion,
+    packageName,
+    checkedAt: cached.checkedAtText || null,
+  });
+}
+
+function shouldSkipAutoCheck() {
+  if (updateCheckDisabled()) return true;
+  if (forceAutoUpdateCheck()) return false;
+  if (process.env.CI) return true;
+  if (isLocalCheckout()) return true;
+  return false;
+}
+
+export async function checkCliUpdate(options = {}) {
+  const currentVersion = options.currentVersion || await readCurrentCliVersion().catch(() => 'unknown');
+  const packageName = resolveCliPackageName(options);
+  if (!currentVersion || currentVersion === 'unknown' || shouldSkipAutoCheck()) return null;
+
+  const state = await loadState().catch(() => ({}));
+  const cached = state?.updateCheck || {};
+  const now = Date.now();
+  const intervalMs = options.force ? 0 : updateCheckIntervalMs();
+  const cacheHit = cached.packageName === packageName
+    && cached.currentVersion === currentVersion
+    && cached.checkedAt
+    && (now - Number(cached.checkedAt) < intervalMs);
+  if (cacheHit) return cachedNotice(state, currentVersion, packageName);
+
+  try {
+    const registry = resolveRegistry(options);
+    const latestVersion = await fetchLatestCliVersion({
+      packageName,
+      registry,
+      timeoutMs: options.timeoutMs || AUTO_CHECK_TIMEOUT_MS,
+    });
+    const checkedAtText = nowIso();
+    await saveState({
+      updateCheck: {
+        packageName,
+        registry,
+        currentVersion,
+        latestVersion,
+        checkedAt: now,
+        checkedAtText,
+      },
+    }).catch(() => {});
+    if (!semverLessThan(currentVersion, latestVersion)) return null;
+    return buildUpdateNotice({ currentVersion, latestVersion, packageName, checkedAt: checkedAtText });
+  } catch (error) {
+    await saveState({
+      updateCheck: {
+        packageName,
+        currentVersion,
+        latestVersion: cached.latestVersion || null,
+        checkedAt: now,
+        checkedAtText: nowIso(),
+        error: error.message || String(error),
+      },
+    }).catch(() => {});
+    return cachedNotice({ updateCheck: cached }, currentVersion, packageName);
+  }
+}
+
+function tailLines(value, limit = 8) {
+  const lines = String(value || '').trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(Math.max(0, lines.length - limit));
+}
+
+export async function runCliUpdate(kwargs = {}) {
+  const currentVersion = await readCurrentCliVersion().catch(() => 'unknown');
+  const packageName = resolveCliPackageName(kwargs);
+  const registry = resolveRegistry(kwargs);
+  const latestVersion = await fetchLatestCliVersion({ packageName, registry });
+  const updateAvailable = currentVersion !== 'unknown' && semverLessThan(currentVersion, latestVersion);
+  const checkOnly = toBool(kwargs.check);
+  const force = toBool(kwargs.force);
+  const installVersion = latestVersion || 'latest';
+  const installSpec = npmInstallSpec(packageName, force ? 'latest' : installVersion);
+  const installArgs = npmArgsWithRegistry(['install', '-g', installSpec], registry);
+
+  if (checkOnly) {
+    return {
+      checked: true,
+      updated: false,
+      updateAvailable,
+      packageName,
+      currentVersion,
+      latestVersion,
+      command: updateAvailable ? `${commandPrefix()} update` : null,
+      message: updateAvailable
+        ? `发现新版本 ${latestVersion}，运行 ${commandPrefix()} update 更新。`
+        : '当前已是最新版本。',
+    };
+  }
+
+  if (!updateAvailable && !force) {
+    return {
+      checked: true,
+      updated: false,
+      updateAvailable: false,
+      packageName,
+      currentVersion,
+      latestVersion,
+      message: '当前已是最新版本。',
+    };
+  }
+
+  const result = await runNpm(installArgs, { timeoutMs: 120_000 });
+  await saveState({
+    updateCheck: {
+      packageName,
+      registry,
+      currentVersion: latestVersion,
+      latestVersion,
+      checkedAt: Date.now(),
+      checkedAtText: nowIso(),
+    },
+  }).catch(() => {});
+
+  return {
+    checked: true,
+    updated: true,
+    updateAvailable,
+    packageName,
+    previousVersion: currentVersion,
+    currentVersion: latestVersion,
+    latestVersion,
+    command: `npm ${installArgs.join(' ')}`,
+    skillUpdated: true,
+    restartRecommended: true,
+    message: '更新完成。请退出并重新打开 AI Agent，以加载最新 CLI 和 skill。',
+    stdoutTail: tailLines(result.stdout),
+    stderrTail: tailLines(result.stderr),
+  };
+}