@mison/wecom-cleaner 1.2.1 → 1.3.2

package/src/cli.js

@@ -33,6 +33,17 @@ import { runDoctor } from './doctor.js';
 import { acquireLock, breakLock, LockHeldError } from './lock.js';
 import { classifyErrorType, errorTypeToLabel } from './error-taxonomy.js';
 import { collectRecycleStats, maintainRecycleBin, normalizeRecycleRetention } from './recycle-maintenance.js';
+import {
+  applyUpdateCheckResult,
+  channelLabel,
+  checkLatestVersion,
+  normalizeSelfUpdateConfig,
+  normalizeUpgradeChannel,
+  runUpgrade,
+  shouldCheckForUpdate,
+  shouldSkipVersion,
+  updateWarningMessage,
+} from './updater.js';
 import {
   compareMonthKey,
   expandHome,
@@ -91,6 +102,8 @@ const NON_INTERACTIVE_ACTIONS = new Set([
   MODES.RESTORE,
   MODES.RECYCLE_MAINTAIN,
   MODES.DOCTOR,
+  MODES.CHECK_UPDATE,
+  MODES.UPGRADE,
 ]);
 const INTERACTIVE_MODE_ALIASES = new Map([
   ['start', MODES.START],
@@ -104,10 +117,36 @@ const INTERACTIVE_MODE_ALIASES = new Map([
   ['recycle_maintain', MODES.RECYCLE_MAINTAIN],
   ['recycle-maintain', MODES.RECYCLE_MAINTAIN],
   ['doctor', MODES.DOCTOR],
+  ['check_update', MODES.CHECK_UPDATE],
+  ['check-update', MODES.CHECK_UPDATE],
   ['settings', MODES.SETTINGS],
 ]);
 const OUTPUT_JSON = 'json';
 const OUTPUT_TEXT = 'text';
+const RUN_TASK_PREVIEW = 'preview';
+const RUN_TASK_EXECUTE = 'execute';
+const RUN_TASK_PREVIEW_EXECUTE_VERIFY = 'preview-execute-verify';
+const RUN_TASK_MODES = new Set([RUN_TASK_PREVIEW, RUN_TASK_EXECUTE, RUN_TASK_PREVIEW_EXECUTE_VERIFY]);
+const SCAN_DEBUG_OFF = 'off';
+const SCAN_DEBUG_SUMMARY = 'summary';
+const SCAN_DEBUG_FULL = 'full';
+const SCAN_DEBUG_LEVELS = new Set([SCAN_DEBUG_OFF, SCAN_DEBUG_SUMMARY, SCAN_DEBUG_FULL]);
+const DESTRUCTIVE_ACTIONS = new Set([
+  MODES.CLEANUP_MONTHLY,
+  MODES.SPACE_GOVERNANCE,
+  MODES.RESTORE,
+  MODES.RECYCLE_MAINTAIN,
+]);
+const UPDATE_REPO_OWNER = 'MisonL';
+const UPDATE_REPO_NAME = 'wecom-cleaner';
+const UPDATE_TIMEOUT_MS = 2500;
+
+function allowAutoUpdateByEnv() {
+  const raw = String(process.env.WECOM_CLEANER_AUTO_UPDATE || 'true')
+    .trim()
+    .toLowerCase();
+  return !['0', 'false', 'no', 'off'].includes(raw);
+}
 
 function isBackCommand(inputValue) {
   const normalized = String(inputValue || '')
@@ -1772,6 +1811,58 @@ function uniqueStrings(values = []) {
   return [...new Set(values.map((item) => String(item || '').trim()).filter(Boolean))];
 }
 
+function normalizeRunTaskMode(rawMode) {
+  const value = String(rawMode || '')
+    .trim()
+    .toLowerCase();
+  if (!value) {
+    return null;
+  }
+  if (!RUN_TASK_MODES.has(value)) {
+    throw new UsageError(`参数 --run-task 的值无效: ${rawMode}`);
+  }
+  return value;
+}
+
+function normalizeScanDebugLevel(rawLevel) {
+  const value = String(rawLevel || SCAN_DEBUG_OFF)
+    .trim()
+    .toLowerCase();
+  if (!value) {
+    return SCAN_DEBUG_OFF;
+  }
+  if (!SCAN_DEBUG_LEVELS.has(value)) {
+    throw new UsageError(`参数 --scan-debug 的值无效: ${rawLevel}`);
+  }
+  return value;
+}
+
+function isDestructiveAction(action) {
+  return DESTRUCTIVE_ACTIONS.has(action);
+}
+
+function shouldAttachScanDebug(cliArgs) {
+  return normalizeScanDebugLevel(cliArgs?.scanDebug) !== SCAN_DEBUG_OFF;
+}
+
+function attachScanDebugData(baseData, cliArgs, summaryPayload, fullPayload = {}) {
+  const level = normalizeScanDebugLevel(cliArgs?.scanDebug);
+  if (level === SCAN_DEBUG_OFF) {
+    return baseData || {};
+  }
+  const summary = summaryPayload && typeof summaryPayload === 'object' ? summaryPayload : {};
+  const full = fullPayload && typeof fullPayload === 'object' ? fullPayload : {};
+  return {
+    ...(baseData || {}),
+    scanDebug: {
+      level,
+      summary,
+      ...(level === SCAN_DEBUG_FULL ? { full } : {}),
+      generatedAt: Date.now(),
+    },
+  };
+}
+
 function normalizeActionOutputMode(cliArgs) {
   if (cliArgs.output === OUTPUT_TEXT || cliArgs.output === OUTPUT_JSON) {
     return cliArgs.output;
@@ -1798,6 +1889,12 @@ function actionFlagName(action) {
   if (action === MODES.DOCTOR) {
     return '--doctor';
   }
+  if (action === MODES.CHECK_UPDATE) {
+    return '--check-update';
+  }
+  if (action === MODES.UPGRADE) {
+    return '--upgrade <npm|github-script>';
+  }
   return `--${String(action || '').replace(/_/g, '-')}`;
 }
 
@@ -1809,7 +1906,7 @@ function resolveActionFromCli(cliArgs, hasAnyArgs) {
     throw new UsageError(
       [
         '无交互模式必须指定一个动作参数：',
-        '--cleanup-monthly | --analysis-only | --space-governance | --restore-batch <batchId> | --recycle-maintain | --doctor',
+        '--cleanup-monthly | --analysis-only | --space-governance | --restore-batch <batchId> | --recycle-maintain | --doctor | --check-update | --upgrade <npm|github-script>',
       ].join('\n')
     );
   }
@@ -1832,15 +1929,22 @@ function printCliUsage(appMeta) {
     '  --restore-batch <batchId>',
     '  --recycle-maintain',
     '  --doctor',
+    '  --check-update',
+    '  --upgrade <npm|github-script>',
     '',
     '常用选项：',
     '  --output json|text',
     '  --dry-run true|false',
     '  --yes',
+    '  --run-task preview|execute|preview-execute-verify',
+    '  --scan-debug off|summary|full',
     '  --accounts all|current|id1,id2',
     '  --months YYYY-MM,YYYY-MM',
     '  --cutoff-month YYYY-MM',
     '  --categories key1,key2',
+    '  --upgrade-version x.y.z',
+    '  --upgrade-channel stable|pre',
+    '  --upgrade-yes',
     '  --root <path>',
     '  --state-root <path>',
     '',
@@ -1851,6 +1955,7 @@ function printCliUsage(appMeta) {
     '示例：',
     '  wecom-cleaner --doctor',
     '  wecom-cleaner --cleanup-monthly --accounts all --cutoff-month 2024-04',
+    '  wecom-cleaner --cleanup-monthly --cutoff-month 2024-04 --accounts all --run-task preview-execute-verify --yes',
     '  wecom-cleaner --cleanup-monthly --accounts all --cutoff-month 2024-04 --dry-run false --yes',
   ];
   console.log(lines.join('\n'));
@@ -1869,6 +1974,9 @@ function resolveInteractiveStartMode(cliArgs) {
   }
 
   if (NON_INTERACTIVE_ACTIONS.has(cliArgs.action)) {
+    if (cliArgs.action === MODES.UPGRADE) {
+      throw new UsageError('参数 --upgrade 仅支持无交互模式，请移除 --interactive 后重试。');
+    }
     return cliArgs.action;
   }
   return MODES.START;
@@ -2120,6 +2228,180 @@ function toStructuredError(item = {}, fallbackCode = 'E_ACTION_FAILED') {
   };
 }
 
+function summarizeDimensionRows(rows, { labelKey = 'label', countKey = 'targetCount' } = {}, limit = 20) {
+  const list = Array.isArray(rows) ? rows : [];
+  return list.slice(0, limit).map((row) => ({
+    label:
+      row?.[labelKey] ||
+      row?.categoryLabel ||
+      row?.targetLabel ||
+      row?.monthKey ||
+      row?.rootPath ||
+      row?.accountShortId ||
+      '-',
+    count: Number(row?.[countKey] || row?.count || 0),
+    sizeBytes: Number(row?.sizeBytes || 0),
+  }));
+}
+
+function buildUserFacingSummary(action, result) {
+  const summary = result?.summary || {};
+  const report = result?.data?.report || {};
+  const matched = report?.matched || {};
+
+  if (action === MODES.CLEANUP_MONTHLY) {
+    return {
+      scope: {
+        accountCount: Number(summary.accountCount || 0),
+        monthCount: Number(summary.monthCount || 0),
+        categoryCount: Number(summary.categoryCount || 0),
+        rootPathCount: Number(summary.rootPathCount || 0),
+        cutoffMonth: summary.cutoffMonth || null,
+        monthRange: {
+          from: summary.matchedMonthStart || matched?.monthRange?.from || null,
+          to: summary.matchedMonthEnd || matched?.monthRange?.to || null,
+        },
+      },
+      result: {
+        noTarget: Boolean(summary.noTarget),
+        matchedTargets: Number(summary.matchedTargets || 0),
+        matchedBytes: Number(summary.matchedBytes || 0),
+        reclaimedBytes: Number(summary.reclaimedBytes || 0),
+        successCount: Number(summary.successCount || 0),
+        skippedCount: Number(summary.skippedCount || 0),
+        failedCount: Number(summary.failedCount || 0),
+        batchId: summary.batchId || null,
+      },
+      byMonth: summarizeDimensionRows(matched.monthStats, { labelKey: 'monthKey' }),
+      byCategory: summarizeDimensionRows(matched.categoryStats, { labelKey: 'categoryLabel' }),
+      byRoot: summarizeDimensionRows(matched.rootStats, { labelKey: 'rootPath' }),
+    };
+  }
+
+  if (action === MODES.ANALYSIS_ONLY) {
+    return {
+      scope: {
+        accountCount: Number(summary.accountCount || 0),
+        matchedAccountCount: Number(summary.matchedAccountCount || 0),
+        categoryCount: Number(summary.categoryCount || 0),
+        monthBucketCount: Number(summary.monthBucketCount || 0),
+      },
+      result: {
+        targetCount: Number(summary.targetCount || 0),
+        totalBytes: Number(summary.totalBytes || 0),
+      },
+      byMonth: summarizeDimensionRows(matched.monthStats, { labelKey: 'monthKey' }),
+      byCategory: summarizeDimensionRows(matched.categoryStats, { labelKey: 'categoryLabel' }),
+      byRoot: summarizeDimensionRows(matched.rootStats, { labelKey: 'rootPath' }),
+    };
+  }
+
+  if (action === MODES.SPACE_GOVERNANCE) {
+    return {
+      scope: {
+        accountCount: Number(summary.accountCount || 0),
+        tierCount: Number(summary.tierCount || 0),
+        targetTypeCount: Number(summary.targetTypeCount || 0),
+        rootPathCount: Number(summary.rootPathCount || 0),
+      },
+      result: {
+        noTarget: Boolean(summary.noTarget),
+        matchedTargets: Number(summary.matchedTargets || 0),
+        matchedBytes: Number(summary.matchedBytes || 0),
+        reclaimedBytes: Number(summary.reclaimedBytes || 0),
+        successCount: Number(summary.successCount || 0),
+        skippedCount: Number(summary.skippedCount || 0),
+        failedCount: Number(summary.failedCount || 0),
+        batchId: summary.batchId || null,
+      },
+      byTier: summarizeDimensionRows(matched.byTier, { labelKey: 'tierLabel' }),
+      byCategory: summarizeDimensionRows(matched.byTargetType, { labelKey: 'targetLabel' }),
+      byRoot: summarizeDimensionRows(matched.byRoot, { labelKey: 'rootPath' }),
+    };
+  }
+
+  if (action === MODES.RESTORE) {
+    return {
+      scope: {
+        entryCount: Number(summary.entryCount || 0),
+        conflictStrategy: summary.conflictStrategy || null,
+        rootPathCount: Number(summary.rootPathCount || 0),
+      },
+      result: {
+        batchId: summary.batchId || null,
+        matchedBytes: Number(summary.matchedBytes || 0),
+        restoredBytes: Number(summary.restoredBytes || 0),
+        successCount: Number(summary.successCount || 0),
+        skippedCount: Number(summary.skippedCount || 0),
+        failedCount: Number(summary.failedCount || 0),
+      },
+      byMonth: summarizeDimensionRows(matched.byMonth, { labelKey: 'monthKey' }),
+      byCategory: summarizeDimensionRows(matched.byCategory, { labelKey: 'categoryLabel' }),
+      byRoot: summarizeDimensionRows(matched.byRoot, { labelKey: 'rootPath' }),
+    };
+  }
+
+  if (action === MODES.RECYCLE_MAINTAIN) {
+    return {
+      scope: {
+        candidateCount: Number(summary.candidateCount || 0),
+        selectedByAge: Number(summary.selectedByAge || 0),
+        selectedBySize: Number(summary.selectedBySize || 0),
+      },
+      result: {
+        status: summary.status || null,
+        deletedBatches: Number(summary.deletedBatches || 0),
+        deletedBytes: Number(summary.deletedBytes || 0),
+        failedBatches: Number(summary.failedBatches || 0),
+        remainingBatches: Number(summary.remainingBatches || 0),
+        remainingBytes: Number(summary.remainingBytes || 0),
+      },
+    };
+  }
+
+  if (action === MODES.DOCTOR) {
+    return {
+      scope: {
+        platform: result?.data?.runtime?.targetTag || null,
+      },
+      result: {
+        overall: summary.overall || null,
+        pass: Number(summary.pass || 0),
+        warn: Number(summary.warn || 0),
+        fail: Number(summary.fail || 0),
+      },
+    };
+  }
+
+  if (action === MODES.CHECK_UPDATE) {
+    return {
+      result: {
+        checked: Boolean(summary.checked),
+        hasUpdate: Boolean(summary.hasUpdate),
+        currentVersion: summary.currentVersion || null,
+        latestVersion: summary.latestVersion || null,
+        source: summary.source || null,
+        channel: summary.channel || null,
+      },
+    };
+  }
+
+  if (action === MODES.UPGRADE) {
+    return {
+      result: {
+        executed: Boolean(summary.executed),
+        method: summary.method || null,
+        targetVersion: summary.targetVersion || null,
+        status: hasDisplayValue(summary.status) ? Number(summary.status) : null,
+      },
+    };
+  }
+
+  return {
+    result: summary,
+  };
+}
+
 const ACTION_DISPLAY_NAMES = new Map([
   [MODES.CLEANUP_MONTHLY, '年月清理'],
   [MODES.ANALYSIS_ONLY, '会话分析（只读）'],
@@ -2127,6 +2409,8 @@ const ACTION_DISPLAY_NAMES = new Map([
   [MODES.RESTORE, '恢复已删除批次'],
   [MODES.RECYCLE_MAINTAIN, '回收区治理'],
   [MODES.DOCTOR, '系统自检'],
+  [MODES.CHECK_UPDATE, '检查更新'],
+  [MODES.UPGRADE, '程序升级'],
 ]);
 
 const CONFLICT_STRATEGY_DISPLAY = new Map([
@@ -2744,6 +3028,61 @@ function printDoctorTextResult(payload) {
   printRuntimeAndRisk(payload);
 }
 
+function printCheckUpdateTextResult(payload) {
+  const summary = payload.summary || {};
+  const update = payload.data?.update || {};
+  const conclusion = summary.hasUpdate
+    ? `检测到新版本 v${summary.latestVersion}，可选择 npm 或 GitHub 脚本升级。`
+    : summary.checked
+      ? '当前已是最新版本。'
+      : '本次更新检查失败，请稍后重试。';
+
+  printTextRows('任务结论', [
+    { label: '动作', value: actionDisplayName(payload.action) },
+    { label: '结论', value: conclusion },
+    { label: '状态', value: summary.checked ? '检查完成' : '检查失败' },
+  ]);
+
+  printTextRows('检查结果', [
+    { label: '当前版本', value: summary.currentVersion || '-' },
+    { label: '最新版本', value: summary.latestVersion || '-' },
+    { label: '来源', value: summary.source || '-' },
+    { label: '通道', value: channelLabel(summary.channel) },
+    { label: '跳过提醒', value: formatYesNo(Boolean(summary.skippedByUser)) },
+    { label: '检查时间', value: formatLocalDate(update.checkedAt || Date.now()) },
+  ]);
+
+  printRuntimeAndRisk(payload);
+}
+
+function printUpgradeTextResult(payload) {
+  const summary = payload.summary || {};
+  const upgrade = payload.data?.upgrade || {};
+  const executed = Boolean(summary.executed);
+  const conclusion = !executed
+    ? summary.reason === 'already_latest'
+      ? '当前已是最新版本，无需执行升级。'
+      : '升级前置检查失败，未执行升级。'
+    : payload.ok
+      ? '升级已执行成功，建议重启程序后继续使用。'
+      : '升级执行失败，请按错误提示排查。';
+
+  printTextRows('任务结论', [
+    { label: '动作', value: actionDisplayName(payload.action) },
+    { label: '结论', value: conclusion },
+    { label: '升级方式', value: summary.method || '-' },
+    { label: '目标版本', value: summary.targetVersion || '-' },
+  ]);
+
+  printTextRows('执行明细', [
+    { label: '已执行升级', value: formatYesNo(executed) },
+    { label: '退出码', value: hasDisplayValue(summary.status) ? summary.status : '-' },
+    { label: '命令', value: summary.command || upgrade.command || '-' },
+  ]);
+
+  printRuntimeAndRisk(payload);
+}
+
 function printGenericTextResult(payload) {
   printTextRows('任务结论', [
     { label: '动作', value: actionDisplayName(payload.action) },
@@ -2757,7 +3096,37 @@ function printGenericTextResult(payload) {
   printRuntimeAndRisk(payload);
 }
 
+function printTaskPhasesText(payload) {
+  const phases = Array.isArray(payload?.data?.taskPhases) ? payload.data.taskPhases : [];
+  if (phases.length === 0) {
+    return;
+  }
+  printTextRows(
+    '任务流程',
+    phases.map((phase) => {
+      const summaryText =
+        phase.status === 'completed'
+          ? `命中 ${formatCount(phase?.stats?.matchedTargets)} 项，成功 ${formatCount(phase?.stats?.successCount)} 项，失败 ${formatCount(phase?.stats?.failedCount)} 项，释放 ${formatBytesSafe(phase?.stats?.reclaimedBytes)}`
+          : `已跳过（${phase.reason || '无'}）`;
+      return {
+        label: phase.name,
+        value: `${phase.status}${phase.ok === false ? '（失败）' : ''}`,
+        note: summaryText,
+      };
+    })
+  );
+  const taskCard = payload?.data?.taskCard;
+  if (taskCard && typeof taskCard === 'object') {
+    printTextRows('流程结论', [
+      { label: '模式', value: taskCard.mode || '-' },
+      { label: '决策', value: taskCard.decision || '-' },
+      { label: '结论', value: taskCard.conclusion || '-' },
+    ]);
+  }
+}
+
 function printNonInteractiveTextResult(payload) {
+  printTaskPhasesText(payload);
   if (payload.action === MODES.CLEANUP_MONTHLY) {
     printCleanupTextResult(payload);
     return;
@@ -2782,6 +3151,14 @@ function printNonInteractiveTextResult(payload) {
     printDoctorTextResult(payload);
     return;
   }
+  if (payload.action === MODES.CHECK_UPDATE) {
+    printCheckUpdateTextResult(payload);
+    return;
+  }
+  if (payload.action === MODES.UPGRADE) {
+    printUpgradeTextResult(payload);
+    return;
+  }
   printGenericTextResult(payload);
 }
 
@@ -2846,6 +3223,32 @@ async function runCleanupModeNonInteractive(context, cliArgs, warnings = []) {
   const targets = scan.targets || [];
   const matchedBytes = targets.reduce((total, item) => total + Number(item?.sizeBytes || 0), 0);
   const matchedReport = buildCleanupTargetReport(targets, { topPathLimit: 20 });
+  const scanDebugSummary = {
+    action: MODES.CLEANUP_MONTHLY,
+    engineReady: context.nativeCorePath ? 'zig' : 'node',
+    engineUsed: scan.engineUsed || 'node',
+    nativeFallbackReason: scan.nativeFallbackReason || null,
+    selectedAccountCount: accountResolved.selectedAccountIds.length,
+    availableMonthCount: availableMonths.length,
+    selectedMonthCount: monthFilters.length,
+    selectedCategoryCount: categoryKeys.length,
+    selectedExternalRootCount: externalResolved.roots.length,
+    includeNonMonthDirs,
+    matchedTargets: targets.length,
+    matchedBytes,
+  };
+  const scanDebugFull = {
+    selectedAccounts: accountResolved.selectedAccountIds,
+    selectedMonths: monthFilters,
+    selectedCategories: categoryKeys,
+    availableMonths,
+    selectedExternalRoots: externalResolved.roots,
+    externalDetectionMeta: detectedExternalStorage.meta || null,
+    matchedTopPaths: matchedReport.topPaths || [],
+    matchedCategoryStats: matchedReport.categoryStats || [],
+    matchedMonthStats: matchedReport.monthStats || [],
+    matchedRootStats: matchedReport.rootStats || [],
+  };
   if (targets.length === 0) {
     return {
       ok: true,
@@ -2879,6 +3282,7 @@ async function runCleanupModeNonInteractive(context, cliArgs, warnings = []) {
           matched: matchedReport,
           executed: null,
         },
+        ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
       },
     };
   }
@@ -2918,6 +3322,7 @@ async function runCleanupModeNonInteractive(context, cliArgs, warnings = []) {
         matched: matchedReport,
         executed: result.breakdown || null,
       },
+      ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
     },
   };
 }
@@ -2952,6 +3357,29 @@ async function runAnalysisModeNonInteractive(context, cliArgs, warnings = []) {
     warnings.push(result.nativeFallbackReason);
   }
   const analysisReport = buildCleanupTargetReport(result.targets, { topPathLimit: 20 });
+  const scanDebugSummary = {
+    action: MODES.ANALYSIS_ONLY,
+    engineReady: context.nativeCorePath ? 'zig' : 'node',
+    engineUsed: result.engineUsed || 'node',
+    nativeFallbackReason: result.nativeFallbackReason || null,
+    selectedAccountCount: accountResolved.selectedAccountIds.length,
+    selectedCategoryCount: categoryKeys.length,
+    selectedExternalRootCount: externalResolved.roots.length,
+    matchedTargets: result.targets.length,
+    matchedBytes: result.totalBytes,
+    matchedAccountCount: result.accountsSummary.length,
+    monthBucketCount: result.monthsSummary.length,
+  };
+  const scanDebugFull = {
+    selectedAccounts: accountResolved.selectedAccountIds,
+    selectedCategories: categoryKeys,
+    selectedExternalRoots: externalResolved.roots,
+    externalDetectionMeta: detectedExternalStorage.meta || null,
+    accountsSummary: result.accountsSummary,
+    categoriesSummary: result.categoriesSummary,
+    monthsSummary: result.monthsSummary,
+    matchedTopPaths: analysisReport.topPaths || [],
+  };
 
   return {
     ok: true,
@@ -2978,6 +3406,7 @@ async function runAnalysisModeNonInteractive(context, cliArgs, warnings = []) {
       report: {
         matched: analysisReport,
       },
+      ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
     },
   };
 }
@@ -3036,6 +3465,33 @@ async function runSpaceGovernanceModeNonInteractive(context, cliArgs, warnings =
   const allowRecentActive = cliArgs.allowRecentActive === true;
   const dryRun = resolveDestructiveDryRun(cliArgs);
   const matchedReport = buildGovernanceTargetReport(selectedTargets, { topPathLimit: 20 });
+  const scanDebugSummary = {
+    action: MODES.SPACE_GOVERNANCE,
+    engineReady: context.nativeCorePath ? 'zig' : 'node',
+    engineUsed: scan.engineUsed || 'node',
+    nativeFallbackReason: scan.nativeFallbackReason || null,
+    selectedAccountCount: accountResolved.selectedAccountIds.length,
+    selectedExternalRootCount: externalResolved.roots.length,
+    scannedTargets: scan.targets.length,
+    selectableTargets: selectableTargets.length,
+    selectedTargets: selectedTargets.length,
+    selectedByCliTargets: selectedById.length,
+    allowRecentActive,
+    matchedBytes: matchedReport.totalBytes,
+  };
+  const scanDebugFull = {
+    selectedAccounts: accountResolved.selectedAccountIds,
+    selectedExternalRoots: externalResolved.roots,
+    externalDetectionMeta: detectedExternalStorage.meta || null,
+    tierFilters: tierFilterSet ? [...tierFilterSet] : [],
+    cliSelectedTargets: selectedById,
+    selectedTargetIds: selectedTargets.map((item) => item.id),
+    matchedByTier: matchedReport.byTier || [],
+    matchedByTargetType: matchedReport.byTargetType || [],
+    matchedByRoot: matchedReport.byRoot || [],
+    matchedTopPaths: matchedReport.topPaths || [],
+    scanByTier: scan.byTier || [],
+  };
   const governanceRoot = inferDataRootFromProfilesRoot(config.rootDir);
   const governanceAllowedRoots = governanceRoot
     ? [governanceRoot, ...externalResolved.roots]
@@ -3068,6 +3524,7 @@ async function runSpaceGovernanceModeNonInteractive(context, cliArgs, warnings =
           matched: matchedReport,
           executed: null,
         },
+        ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
       },
     };
   }
@@ -3113,6 +3570,7 @@ async function runSpaceGovernanceModeNonInteractive(context, cliArgs, warnings =
         matched: matchedReport,
         executed: result.breakdown || null,
       },
+      ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
     },
   };
 }
@@ -3158,6 +3616,25 @@ async function runRestoreModeNonInteractive(context, cliArgs, warnings = []) {
     onConflict: async () => ({ action: conflictStrategy, applyToAll: true }),
   });
   const matchedReport = buildRestoreBatchTargetReport(batch.entries, { topPathLimit: 20 });
+  const scanDebugSummary = {
+    action: MODES.RESTORE,
+    selectedExternalRootCount: externalResolved.roots.length,
+    governanceRoot: governanceRoot || null,
+    batchEntryCount: batch.entries.length,
+    matchedBytes: matchedReport.totalBytes,
+    dryRun,
+  };
+  const scanDebugFull = {
+    batchId: batch.batchId,
+    conflictStrategy,
+    selectedExternalRoots: externalResolved.roots,
+    governanceAllowRoots: governanceAllowRoots,
+    matchedByScope: matchedReport.byScope || [],
+    matchedByCategory: matchedReport.byCategory || [],
+    matchedByMonth: matchedReport.byMonth || [],
+    matchedByRoot: matchedReport.byRoot || [],
+    topEntries: matchedReport.topEntries || [],
+  };
 
   return {
     ok: result.failCount === 0,
@@ -3185,6 +3662,7 @@ async function runRestoreModeNonInteractive(context, cliArgs, warnings = []) {
         matched: matchedReport,
         executed: result.breakdown || null,
       },
+      ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
     },
   };
 }
@@ -3226,6 +3704,25 @@ async function runRecycleMaintainModeNonInteractive(context, cliArgs, warnings =
     };
     await saveConfig(config);
   }
+  const scanDebugSummary = {
+    action: MODES.RECYCLE_MAINTAIN,
+    dryRun,
+    candidateCount: result.candidateCount,
+    selectedByAge: result.selectedByAge,
+    selectedBySize: result.selectedBySize,
+    deletedBatches: result.deletedBatches,
+    deletedBytes: result.deletedBytes,
+    failedBatches: result.failBatches,
+  };
+  const scanDebugFull = {
+    policy,
+    before: result.before || null,
+    after: result.after || null,
+    thresholdBytes: result.thresholdBytes,
+    overThreshold: result.overThreshold,
+    selectedCandidates: result.selectedCandidates || [],
+    operations: result.operations || [],
+  };
 
   return {
     ok: result.failBatches === 0,
@@ -3259,6 +3756,7 @@ async function runRecycleMaintainModeNonInteractive(context, cliArgs, warnings =
         selectedCandidates: result.selectedCandidates || [],
         operations: result.operations || [],
       },
+      ...attachScanDebugData({}, cliArgs, scanDebugSummary, scanDebugFull),
     },
   };
 }
@@ -3287,6 +3785,337 @@ async function runDoctorModeNonInteractive(context, _cliArgs, warnings = []) {
   };
 }
 
+function resolveUpdateChannel(cliArgs, config) {
+  const fallback = normalizeSelfUpdateConfig(config?.selfUpdate).channel;
+  return normalizeUpgradeChannel(cliArgs.upgradeChannel, fallback);
+}
+
+function buildUpdateData(result, skipVersion = '') {
+  const data = result && typeof result === 'object' ? result : {};
+  return {
+    checked: Boolean(data.checked),
+    currentVersion: data.currentVersion || '',
+    latestVersion: data.latestVersion || null,
+    hasUpdate: Boolean(data.hasUpdate),
+    sourceUsed: data.sourceUsed || 'none',
+    channel: data.channel || 'stable',
+    checkReason: data.checkReason || 'manual',
+    checkedAt: Number(data.checkedAt || Date.now()),
+    skippedByUser: shouldSkipVersion(data, skipVersion),
+    errors: Array.isArray(data.errors) ? data.errors : [],
+    upgradeMethods: Array.isArray(data.upgradeMethods) ? data.upgradeMethods : ['npm', 'github-script'],
+  };
+}
+
+async function persistSelfUpdateState(context) {
+  if (context.readOnlyConfig) {
+    return;
+  }
+  await saveConfig(context.config).catch(() => {});
+}
+
+async function runCheckUpdateModeNonInteractive(context, cliArgs, warnings = []) {
+  const channel = resolveUpdateChannel(cliArgs, context.config);
+  const checkResult = await checkLatestVersion({
+    currentVersion: context.appMeta?.version || '0.0.0',
+    packageName: PACKAGE_NAME,
+    githubOwner: UPDATE_REPO_OWNER,
+    githubRepo: UPDATE_REPO_NAME,
+    channel,
+    timeoutMs: UPDATE_TIMEOUT_MS,
+    reason: 'manual',
+  });
+  const normalizedSelfUpdate = normalizeSelfUpdateConfig({
+    ...context.config.selfUpdate,
+    channel,
+  });
+  context.config.selfUpdate = applyUpdateCheckResult(normalizedSelfUpdate, checkResult, '');
+  await persistSelfUpdateState(context);
+  const updateData = buildUpdateData(checkResult, context.config.selfUpdate.skipVersion);
+
+  if (updateData.hasUpdate && !updateData.skippedByUser) {
+    warnings.push(updateWarningMessage(updateData, context.config.selfUpdate.skipVersion));
+  }
+
+  return {
+    ok: updateData.checked,
+    action: MODES.CHECK_UPDATE,
+    dryRun: null,
+    summary: {
+      checked: updateData.checked,
+      hasUpdate: updateData.hasUpdate,
+      currentVersion: updateData.currentVersion || '-',
+      latestVersion: updateData.latestVersion || '-',
+      source: updateData.sourceUsed,
+      channel: updateData.channel,
+      skippedByUser: updateData.skippedByUser,
+    },
+    warnings: uniqueStrings(warnings),
+    errors: updateData.errors.map((message) => ({
+      code: 'E_UPDATE_CHECK_FAILED',
+      message,
+    })),
+    data: {
+      update: updateData,
+    },
+  };
+}
+
+async function runUpgradeModeNonInteractive(context, cliArgs, warnings = []) {
+  const method = String(cliArgs.upgradeMethod || '').trim();
+  if (!method) {
+    throw new UsageError('参数 --upgrade 缺少升级方式（npm|github-script）');
+  }
+  if (!cliArgs.upgradeYes) {
+    throw new ConfirmationRequiredError('检测到升级请求，但未提供 --upgrade-yes 确认参数。');
+  }
+
+  const channel = resolveUpdateChannel(cliArgs, context.config);
+  let targetVersion = String(cliArgs.upgradeVersion || '').trim();
+  let checkResult = null;
+
+  if (!targetVersion) {
+    checkResult = await checkLatestVersion({
+      currentVersion: context.appMeta?.version || '0.0.0',
+      packageName: PACKAGE_NAME,
+      githubOwner: UPDATE_REPO_OWNER,
+      githubRepo: UPDATE_REPO_NAME,
+      channel,
+      timeoutMs: UPDATE_TIMEOUT_MS,
+      reason: 'manual',
+    });
+
+    if (!checkResult.checked) {
+      return {
+        ok: false,
+        action: MODES.UPGRADE,
+        dryRun: null,
+        summary: {
+          executed: false,
+          method,
+          targetVersion: '-',
+          reason: 'check_failed',
+        },
+        warnings: uniqueStrings(warnings),
+        errors: (checkResult.errors || []).map((message) => ({
+          code: 'E_UPGRADE_CHECK_FAILED',
+          message,
+        })),
+        data: {
+          update: buildUpdateData(checkResult, context.config.selfUpdate.skipVersion),
+        },
+      };
+    }
+    if (!checkResult.hasUpdate) {
+      return {
+        ok: true,
+        action: MODES.UPGRADE,
+        dryRun: null,
+        summary: {
+          executed: false,
+          method,
+          targetVersion: checkResult.currentVersion || '-',
+          reason: 'already_latest',
+        },
+        warnings: uniqueStrings(warnings),
+        errors: [],
+        data: {
+          update: buildUpdateData(checkResult, context.config.selfUpdate.skipVersion),
+        },
+      };
+    }
+    targetVersion = checkResult.latestVersion;
+  }
+
+  const upgrade = runUpgrade({
+    method,
+    packageName: PACKAGE_NAME,
+    targetVersion,
+    githubOwner: UPDATE_REPO_OWNER,
+    githubRepo: UPDATE_REPO_NAME,
+  });
+
+  if (upgrade.ok) {
+    context.config.selfUpdate = normalizeSelfUpdateConfig({
+      ...context.config.selfUpdate,
+      skipVersion: '',
+      lastKnownLatest: targetVersion,
+      lastKnownSource: upgrade.method,
+    });
+    await persistSelfUpdateState(context);
+  }
+
+  return {
+    ok: upgrade.ok,
+    action: MODES.UPGRADE,
+    dryRun: null,
+    summary: {
+      executed: true,
+      method: upgrade.method,
+      targetVersion: upgrade.targetVersion || targetVersion || '-',
+      command: upgrade.command,
+      status: upgrade.status,
+    },
+    warnings: uniqueStrings(warnings),
+    errors: upgrade.ok
+      ? []
+      : [
+          {
+            code: 'E_UPGRADE_FAILED',
+            message: upgrade.error || upgrade.stderr || 'upgrade_failed',
+          },
+        ],
+    data: {
+      update: checkResult ? buildUpdateData(checkResult, context.config.selfUpdate.skipVersion) : null,
+      upgrade,
+    },
+  };
+}
+
+function attachStartupUpdateToResult(result, startupUpdate, skipVersion) {
+  if (!startupUpdate) {
+    return result;
+  }
+  const output = result && typeof result === 'object' ? result : {};
+  const warnings = uniqueStrings(Array.isArray(output.warnings) ? output.warnings : []);
+  const updateData = buildUpdateData(startupUpdate, skipVersion);
+  if (updateData.hasUpdate && !updateData.skippedByUser) {
+    warnings.push(updateWarningMessage(updateData, skipVersion));
+  }
+  return {
+    ...output,
+    warnings: uniqueStrings(warnings),
+    data: {
+      ...(output.data || {}),
+      update: updateData,
+    },
+  };
+}
+
+async function maybeRunStartupUpdateCheck(context, cliArgs, action, interactiveMode) {
+  if (!allowAutoUpdateByEnv()) {
+    return null;
+  }
+  const selfUpdate = normalizeSelfUpdateConfig(context.config.selfUpdate);
+  context.config.selfUpdate = selfUpdate;
+
+  if (!selfUpdate.enabled) {
+    return null;
+  }
+  if (action === MODES.CHECK_UPDATE || action === MODES.UPGRADE) {
+    return null;
+  }
+  if (!interactiveMode && action === MODES.DOCTOR) {
+    return null;
+  }
+
+  const decision = shouldCheckForUpdate(selfUpdate, Date.now());
+  if (!decision.shouldCheck) {
+    return null;
+  }
+
+  const channel = resolveUpdateChannel(cliArgs, context.config);
+  const checkResult = await checkLatestVersion({
+    currentVersion: context.appMeta?.version || '0.0.0',
+    packageName: PACKAGE_NAME,
+    githubOwner: UPDATE_REPO_OWNER,
+    githubRepo: UPDATE_REPO_NAME,
+    channel,
+    timeoutMs: UPDATE_TIMEOUT_MS,
+    reason: 'startup_slot',
+  });
+  context.config.selfUpdate = applyUpdateCheckResult(
+    normalizeSelfUpdateConfig({
+      ...context.config.selfUpdate,
+      channel,
+    }),
+    checkResult,
+    decision.slot || ''
+  );
+  await persistSelfUpdateState(context);
+  return buildUpdateData(checkResult, context.config.selfUpdate.skipVersion);
+}
+
+async function maybePromptInteractiveUpgrade(context, startupUpdate) {
+  if (!startupUpdate || !startupUpdate.hasUpdate || startupUpdate.skippedByUser) {
+    return false;
+  }
+
+  printSection('可用更新');
+  printTextRows('更新提示', [
+    {
+      label: '版本',
+      value: `当前 v${startupUpdate.currentVersion || '-'} -> 最新 v${startupUpdate.latestVersion || '-'}`,
+    },
+    { label: '来源', value: startupUpdate.sourceUsed || '-' },
+    { label: '通道', value: channelLabel(startupUpdate.channel) },
+  ]);
+
+  const choice = await askSelect({
+    message: '检测到新版本，是否升级？',
+    default: 'npm',
+    choices: [
+      { name: '通过 npm 升级（默认）', value: 'npm' },
+      { name: '通过 GitHub 脚本升级', value: 'github-script' },
+      { name: '稍后提醒', value: 'later' },
+      { name: '跳过该版本（不再提醒）', value: 'skip-version' },
+    ],
+  });
+
+  if (choice === 'later') {
+    return false;
+  }
+  if (choice === 'skip-version') {
+    context.config.selfUpdate = normalizeSelfUpdateConfig({
+      ...context.config.selfUpdate,
+      skipVersion: startupUpdate.latestVersion || '',
+    });
+    await persistSelfUpdateState(context);
+    console.log(`已记录：v${startupUpdate.latestVersion} 将不再自动提醒。`);
+    return false;
+  }
+
+  const confirmed = await askConfirm({
+    message: `确认升级到 v${startupUpdate.latestVersion}？`,
+    default: true,
+  });
+  if (!confirmed) {
+    return false;
+  }
+
+  const upgrade = runUpgrade({
+    method: choice,
+    packageName: PACKAGE_NAME,
+    targetVersion: startupUpdate.latestVersion,
+    githubOwner: UPDATE_REPO_OWNER,
+    githubRepo: UPDATE_REPO_NAME,
+  });
+  if (!upgrade.ok) {
+    printTextRows('升级结果', [
+      { label: '状态', value: '失败' },
+      { label: '方式', value: choice },
+      { label: '命令', value: upgrade.command },
+      { label: '错误', value: upgrade.error || upgrade.stderr || 'unknown_error' },
+    ]);
+    return false;
+  }
+
+  context.config.selfUpdate = normalizeSelfUpdateConfig({
+    ...context.config.selfUpdate,
+    skipVersion: '',
+    lastKnownLatest: startupUpdate.latestVersion || '',
+    lastKnownSource: choice,
+  });
+  await persistSelfUpdateState(context);
+  printTextRows('升级结果', [
+    { label: '状态', value: '成功' },
+    { label: '方式', value: choice },
+    { label: '版本', value: `v${startupUpdate.latestVersion}` },
+  ]);
+  console.log('升级已完成，建议重新启动 wecom-cleaner 后继续。');
+  return true;
+}
+
 async function runNonInteractiveAction(action, context, cliArgs) {
   const warnings = [];
   if (cliArgs.actionFromMode) {
@@ -3311,9 +4140,360 @@ async function runNonInteractiveAction(action, context, cliArgs) {
   if (action === MODES.DOCTOR) {
     return runDoctorModeNonInteractive(context, cliArgs, warnings);
   }
+  if (action === MODES.CHECK_UPDATE) {
+    return runCheckUpdateModeNonInteractive(context, cliArgs, warnings);
+  }
+  if (action === MODES.UPGRADE) {
+    return runUpgradeModeNonInteractive(context, cliArgs, warnings);
+  }
   throw new UsageError(`不支持的无交互动作: ${action}`);
 }
 
+function phaseMatchedTargets(action, result) {
+  const summary = result?.summary || {};
+  if (action === MODES.CLEANUP_MONTHLY || action === MODES.SPACE_GOVERNANCE) {
+    return Number(summary.matchedTargets || 0);
+  }
+  if (action === MODES.RESTORE) {
+    return Number(summary.entryCount || 0);
+  }
+  if (action === MODES.RECYCLE_MAINTAIN) {
+    return Number(summary.candidateCount || 0);
+  }
+  if (action === MODES.ANALYSIS_ONLY) {
+    return Number(summary.targetCount || 0);
+  }
+  return 0;
+}
+
+function phaseMatchedBytes(action, result) {
+  const summary = result?.summary || {};
+  if (action === MODES.CLEANUP_MONTHLY || action === MODES.SPACE_GOVERNANCE || action === MODES.RESTORE) {
+    return Number(summary.matchedBytes || 0);
+  }
+  if (action === MODES.ANALYSIS_ONLY) {
+    return Number(summary.totalBytes || 0);
+  }
+  if (action === MODES.RECYCLE_MAINTAIN) {
+    return Number(summary.deletedBytes || 0);
+  }
+  return 0;
+}
+
+function phaseReclaimedBytes(action, result) {
+  const summary = result?.summary || {};
+  if (action === MODES.RESTORE) {
+    return Number(summary.restoredBytes || 0);
+  }
+  if (action === MODES.RECYCLE_MAINTAIN) {
+    return Number(summary.deletedBytes || 0);
+  }
+  return Number(summary.reclaimedBytes || 0);
+}
+
+function buildTaskPhaseEntry(action, phaseName, result, durationMs) {
+  const summary = result?.summary || {};
+  const warnings = Array.isArray(result?.warnings) ? result.warnings : [];
+  const errors = Array.isArray(result?.errors) ? result.errors : [];
+  return {
+    name: phaseName,
+    status: 'completed',
+    ok: Boolean(result?.ok),
+    dryRun: result?.dryRun ?? null,
+    durationMs: Math.max(0, Number(durationMs || 0)),
+    summary,
+    warningCount: warnings.length,
+    errorCount: errors.length,
+    warnings,
+    errors,
+    stats: {
+      matchedTargets: phaseMatchedTargets(action, result),
+      matchedBytes: phaseMatchedBytes(action, result),
+      reclaimedBytes: phaseReclaimedBytes(action, result),
+      successCount: Number(summary.successCount || 0),
+      skippedCount: Number(summary.skippedCount || 0),
+      failedCount: Number(summary.failedCount || summary.failedBatches || 0),
+      batchId: summary.batchId || null,
+    },
+    userFacingSummary: buildUserFacingSummary(action, result),
+  };
+}
+
+function buildSkippedTaskPhase(phaseName, reason) {
+  return {
+    name: phaseName,
+    status: 'skipped',
+    reason,
+    ok: true,
+    dryRun: null,
+    durationMs: 0,
+    summary: {},
+    warningCount: 0,
+    errorCount: 0,
+    warnings: [],
+    errors: [],
+    stats: {
+      matchedTargets: 0,
+      matchedBytes: 0,
+      reclaimedBytes: 0,
+      successCount: 0,
+      skippedCount: 0,
+      failedCount: 0,
+      batchId: null,
+    },
+    userFacingSummary: {},
+  };
+}
+
+function buildTaskCardBreakdown(action, report) {
+  const matched = report?.matched || {};
+  if (action === MODES.CLEANUP_MONTHLY || action === MODES.ANALYSIS_ONLY) {
+    return {
+      byCategory: summarizeDimensionRows(matched.categoryStats, { labelKey: 'categoryLabel' }, 16),
+      byMonth: summarizeDimensionRows(matched.monthStats, { labelKey: 'monthKey' }, 16),
+      byRoot: summarizeDimensionRows(matched.rootStats, { labelKey: 'rootPath' }, 12),
+      topPaths: Array.isArray(matched.topPaths)
+        ? matched.topPaths.slice(0, 12).map((item) => ({
+            path: item.path || '-',
+            category: item.categoryLabel || item.categoryKey || '-',
+            month: item.monthKey || '非月份目录',
+            sizeBytes: Number(item.sizeBytes || 0),
+          }))
+        : [],
+    };
+  }
+  if (action === MODES.SPACE_GOVERNANCE) {
+    return {
+      byCategory: summarizeDimensionRows(matched.byTargetType, { labelKey: 'targetLabel' }, 16),
+      byMonth: [],
+      byRoot: summarizeDimensionRows(matched.byRoot, { labelKey: 'rootPath' }, 12),
+      byTier: summarizeDimensionRows(matched.byTier, { labelKey: 'tierLabel' }, 8),
+      topPaths: Array.isArray(matched.topPaths)
+        ? matched.topPaths.slice(0, 12).map((item) => ({
+            path: item.path || '-',
+            category: item.targetLabel || item.targetKey || '-',
+            month: '-',
+            sizeBytes: Number(item.sizeBytes || 0),
+          }))
+        : [],
+    };
+  }
+  if (action === MODES.RESTORE) {
+    return {
+      byCategory: summarizeDimensionRows(matched.byCategory, { labelKey: 'categoryLabel' }, 16),
+      byMonth: summarizeDimensionRows(matched.byMonth, { labelKey: 'monthKey' }, 16),
+      byRoot: summarizeDimensionRows(matched.byRoot, { labelKey: 'rootPath' }, 12),
+      topPaths: Array.isArray(matched.topEntries)
+        ? matched.topEntries.slice(0, 12).map((item) => ({
+            path: item.originalPath || '-',
+            category: item.categoryLabel || item.categoryKey || '-',
+            month: item.monthKey || '非月份目录',
+            sizeBytes: Number(item.sizeBytes || 0),
+          }))
+        : [],
+    };
+  }
+  if (action === MODES.RECYCLE_MAINTAIN) {
+    const operations = Array.isArray(report?.operations) ? report.operations : [];
+    const byStatus = operations.reduce((acc, item) => {
+      const key = String(item?.status || 'unknown');
+      acc.set(key, (acc.get(key) || 0) + 1);
+      return acc;
+    }, new Map());
+    return {
+      byCategory: [...byStatus.entries()].map(([label, count]) => ({
+        label,
+        count: Number(count || 0),
+        sizeBytes: 0,
+      })),
+      byMonth: [],
+      byRoot: [],
+      topPaths: [],
+    };
+  }
+  return {
+    byCategory: [],
+    byMonth: [],
+    byRoot: [],
+    topPaths: [],
+  };
+}
+
+function buildRunTaskCard(action, runTaskMode, taskDecision, phases, finalResult) {
+  const previewPhase = phases.find((item) => item.name === 'preview' && item.status === 'completed') || null;
+  const executePhase = phases.find((item) => item.name === 'execute' && item.status === 'completed') || null;
+  const verifyPhase = phases.find((item) => item.name === 'verify' && item.status === 'completed') || null;
+  const report = finalResult?.data?.report || {};
+  const breakdown = buildTaskCardBreakdown(action, report);
+
+  let conclusion = '任务已完成。';
+  if (taskDecision === 'skipped_no_target') {
+    conclusion = '预演命中为 0，已按安全策略跳过真实执行。';
+  } else if (taskDecision === 'preview_only') {
+    conclusion = '已完成预演，本次未执行真实操作。';
+  } else if (taskDecision === 'execute_only' && executePhase) {
+    conclusion = executePhase.ok ? '已完成真实执行。' : '已尝试真实执行，但存在失败项。';
+  } else if (taskDecision === 'executed_and_verified') {
+    conclusion =
+      verifyPhase && Number(verifyPhase.stats.matchedTargets || 0) === 0
+        ? '已完成真实执行并通过复核，范围内无剩余目标。'
+        : '已完成真实执行与复核。';
+  } else if (taskDecision === 'preview_failed') {
+    conclusion = '预演阶段失败，后续阶段未执行。';
+  }
+
+  return {
+    action,
+    actionLabel: actionDisplayName(action),
+    mode: runTaskMode,
+    decision: taskDecision,
+    conclusion,
+    phases: phases.map((item) => ({
+      name: item.name,
+      status: item.status,
+      reason: item.reason || null,
+      dryRun: item.dryRun,
+      ok: item.ok,
+      durationMs: item.durationMs,
+      matchedTargets: Number(item?.stats?.matchedTargets || 0),
+      matchedBytes: Number(item?.stats?.matchedBytes || 0),
+      reclaimedBytes: Number(item?.stats?.reclaimedBytes || 0),
+      successCount: Number(item?.stats?.successCount || 0),
+      skippedCount: Number(item?.stats?.skippedCount || 0),
+      failedCount: Number(item?.stats?.failedCount || 0),
+      batchId: item?.stats?.batchId || null,
+    })),
+    scope: {
+      accountCount: Number(finalResult?.summary?.accountCount || 0),
+      monthCount: Number(finalResult?.summary?.monthCount || 0),
+      categoryCount: Number(finalResult?.summary?.categoryCount || 0),
+      rootPathCount: Number(finalResult?.summary?.rootPathCount || 0),
+      cutoffMonth: finalResult?.summary?.cutoffMonth || null,
+      selectedAccounts: uniqueStrings(finalResult?.data?.selectedAccounts || []),
+      selectedMonths: uniqueStrings(finalResult?.data?.selectedMonths || []),
+      selectedCategories: uniqueStrings(finalResult?.data?.selectedCategories || []),
+      selectedExternalRoots: uniqueStrings(finalResult?.data?.selectedExternalRoots || []),
+    },
+    preview: previewPhase
+      ? {
+          matchedTargets: Number(previewPhase.stats.matchedTargets || 0),
+          matchedBytes: Number(previewPhase.stats.matchedBytes || 0),
+          reclaimedBytes: Number(previewPhase.stats.reclaimedBytes || 0),
+          failedCount: Number(previewPhase.stats.failedCount || 0),
+        }
+      : null,
+    execute: executePhase
+      ? {
+          successCount: Number(executePhase.stats.successCount || 0),
+          skippedCount: Number(executePhase.stats.skippedCount || 0),
+          failedCount: Number(executePhase.stats.failedCount || 0),
+          reclaimedBytes: Number(executePhase.stats.reclaimedBytes || 0),
+          batchId: executePhase.stats.batchId || null,
+        }
+      : null,
+    verify: verifyPhase
+      ? {
+          matchedTargets: Number(verifyPhase.stats.matchedTargets || 0),
+          matchedBytes: Number(verifyPhase.stats.matchedBytes || 0),
+          failedCount: Number(verifyPhase.stats.failedCount || 0),
+        }
+      : null,
+    breakdown,
+  };
+}
+
+function withRunTaskResult(baseResult, action, runTaskMode, taskDecision, phases) {
+  const output = baseResult && typeof baseResult === 'object' ? baseResult : {};
+  const data = output.data && typeof output.data === 'object' ? output.data : {};
+  const summary = output.summary && typeof output.summary === 'object' ? output.summary : {};
+  return {
+    ...output,
+    summary: {
+      ...summary,
+      runTaskMode,
+      taskDecision,
+      phaseCount: phases.length,
+    },
+    data: {
+      ...data,
+      taskPhases: phases,
+      taskCard: buildRunTaskCard(action, runTaskMode, taskDecision, phases, output),
+    },
+  };
+}
+
+async function runNonInteractiveTask(action, context, cliArgs) {
+  const runTaskMode = normalizeRunTaskMode(cliArgs.runTask);
+  if (!runTaskMode) {
+    return runNonInteractiveAction(action, context, cliArgs);
+  }
+
+  if (!isDestructiveAction(action) && runTaskMode !== RUN_TASK_PREVIEW) {
+    throw new UsageError(`动作 ${actionDisplayName(action)} 仅支持 --run-task preview`);
+  }
+  if (
+    isDestructiveAction(action) &&
+    (runTaskMode === RUN_TASK_EXECUTE || runTaskMode === RUN_TASK_PREVIEW_EXECUTE_VERIFY) &&
+    !cliArgs.yes
+  ) {
+    throw new ConfirmationRequiredError('检测到真实执行任务流程，但未提供 --yes 确认参数。');
+  }
+
+  const execPhase = async (phaseName, phaseArgs) => {
+    const startedAt = Date.now();
+    const result = await runNonInteractiveAction(action, context, phaseArgs);
+    return {
+      result,
+      phase: buildTaskPhaseEntry(action, phaseName, result, Date.now() - startedAt),
+    };
+  };
+
+  if (runTaskMode === RUN_TASK_PREVIEW) {
+    const previewArgs = isDestructiveAction(action)
+      ? { ...cliArgs, dryRun: true, yes: false, runTask: null }
+      : { ...cliArgs, runTask: null };
+    const preview = await execPhase('preview', previewArgs);
+    return withRunTaskResult(preview.result, action, runTaskMode, 'preview_only', [preview.phase]);
+  }
+
+  if (runTaskMode === RUN_TASK_EXECUTE) {
+    const executeArgs = isDestructiveAction(action)
+      ? { ...cliArgs, dryRun: false, yes: true, runTask: null }
+      : { ...cliArgs, runTask: null };
+    const execute = await execPhase('execute', executeArgs);
+    return withRunTaskResult(execute.result, action, runTaskMode, 'execute_only', [execute.phase]);
+  }
+
+  const previewArgs = { ...cliArgs, dryRun: true, yes: false, runTask: null };
+  const preview = await execPhase('preview', previewArgs);
+  if (!preview.result.ok) {
+    const phases = [
+      preview.phase,
+      buildSkippedTaskPhase('execute', 'preview_failed'),
+      buildSkippedTaskPhase('verify', 'preview_failed'),
+    ];
+    return withRunTaskResult(preview.result, action, runTaskMode, 'preview_failed', phases);
+  }
+
+  if (phaseMatchedTargets(action, preview.result) <= 0) {
+    const phases = [
+      preview.phase,
+      buildSkippedTaskPhase('execute', 'no_target'),
+      buildSkippedTaskPhase('verify', 'no_execute'),
+    ];
+    return withRunTaskResult(preview.result, action, runTaskMode, 'skipped_no_target', phases);
+  }
+
+  const executeArgs = { ...cliArgs, dryRun: false, yes: true, runTask: null };
+  const execute = await execPhase('execute', executeArgs);
+  const verify = await execPhase('verify', previewArgs);
+  return withRunTaskResult(execute.result, action, runTaskMode, 'executed_and_verified', [
+    preview.phase,
+    execute.phase,
+    verify.phase,
+  ]);
+}
+
 async function runCleanupMode(context) {
   const { config, aliases, nativeCorePath } = context;
 
@@ -4078,6 +5258,74 @@ async function runDoctorMode(context, options = {}) {
   await printDoctorReport(report, Boolean(options.jsonOutput));
 }
 
+async function runCheckUpdateMode(context, cliArgs = {}) {
+  const channel = resolveUpdateChannel(cliArgs, context.config);
+  const startedAt = Date.now();
+  const checkResult = await checkLatestVersion({
+    currentVersion: context.appMeta?.version || '0.0.0',
+    packageName: PACKAGE_NAME,
+    githubOwner: UPDATE_REPO_OWNER,
+    githubRepo: UPDATE_REPO_NAME,
+    channel,
+    timeoutMs: UPDATE_TIMEOUT_MS,
+    reason: 'manual',
+  });
+
+  context.config.selfUpdate = applyUpdateCheckResult(
+    normalizeSelfUpdateConfig({
+      ...context.config.selfUpdate,
+      channel,
+    }),
+    checkResult,
+    ''
+  );
+  await persistSelfUpdateState(context);
+
+  const payload = {
+    ok: checkResult.checked,
+    action: MODES.CHECK_UPDATE,
+    dryRun: null,
+    summary: {
+      checked: Boolean(checkResult.checked),
+      hasUpdate: Boolean(checkResult.hasUpdate),
+      currentVersion: checkResult.currentVersion || '-',
+      latestVersion: checkResult.latestVersion || '-',
+      source: checkResult.sourceUsed || 'none',
+      channel: checkResult.channel || channel,
+      skippedByUser: shouldSkipVersion(checkResult, context.config.selfUpdate.skipVersion),
+    },
+    warnings: [],
+    errors: Array.isArray(checkResult.errors)
+      ? checkResult.errors.map((message) => ({
+          code: 'E_UPDATE_CHECK_FAILED',
+          message,
+        }))
+      : [],
+    data: {
+      update: buildUpdateData(checkResult, context.config.selfUpdate.skipVersion),
+    },
+    meta: {
+      app: APP_NAME,
+      package: PACKAGE_NAME,
+      version: context.appMeta?.version || '0.0.0',
+      timestamp: Date.now(),
+      durationMs: Date.now() - startedAt,
+      output: OUTPUT_TEXT,
+      engine: context.lastRunEngineUsed || (context.nativeCorePath ? 'zig_ready' : 'node'),
+    },
+  };
+
+  if (payload.summary.hasUpdate && !payload.summary.skippedByUser) {
+    payload.warnings.push(updateWarningMessage(payload.data.update, context.config.selfUpdate.skipVersion));
+  }
+  printCheckUpdateTextResult(payload);
+
+  const upgraded = await maybePromptInteractiveUpgrade(context, payload.data.update);
+  if (upgraded) {
+    return;
+  }
+}
+
 async function runRecycleMaintainMode(context, options = {}) {
   const { config } = context;
   const policy = normalizeRecycleRetention(config.recycleRetention);
@@ -4438,6 +5686,10 @@ async function runMode(mode, context, options = {}) {
     await runDoctorMode(context, options);
     return;
   }
+  if (mode === MODES.CHECK_UPDATE) {
+    await runCheckUpdateMode(context, options.cliArgs || {});
+    return;
+  }
   if (mode === MODES.RECYCLE_MAINTAIN) {
     await runRecycleMaintainMode(context, options);
     return;
@@ -4528,6 +5780,7 @@ async function runInteractiveLoop(context) {
         { name: '恢复已删除批次', value: MODES.RESTORE },
         { name: '回收区治理（保留策略）', value: MODES.RECYCLE_MAINTAIN },
         { name: '系统自检（doctor）', value: MODES.DOCTOR },
+        { name: '检查更新与升级', value: MODES.CHECK_UPDATE },
         { name: '交互配置', value: MODES.SETTINGS },
         { name: '退出', value: 'exit' },
       ],
@@ -4540,6 +5793,7 @@ async function runInteractiveLoop(context) {
     await runMode(mode, context, {
       jsonOutput: false,
       force: false,
+      cliArgs: {},
     });
 
     const back = await askConfirm({
@@ -4602,6 +5856,7 @@ async function main() {
     nativeRepairNote: nativeProbe.repairNote || null,
     appMeta,
     projectRoot,
+    readOnlyConfig,
   };
 
   let lockHandle = null;
@@ -4610,11 +5865,18 @@ async function main() {
   }
 
   try {
+    const startupUpdate = await maybeRunStartupUpdateCheck(context, cliArgs, action, interactiveMode);
+
     if (interactiveMode) {
+      const upgraded = await maybePromptInteractiveUpgrade(context, startupUpdate);
+      if (upgraded) {
+        return;
+      }
       if (interactiveStartMode !== MODES.START) {
         await runMode(interactiveStartMode, context, {
           jsonOutput: false,
           force: cliArgs.force,
+          cliArgs,
         });
         return;
       }
@@ -4623,7 +5885,17 @@ async function main() {
     }
 
     const startedAt = Date.now();
-    const result = await runNonInteractiveAction(action, context, cliArgs);
+    let result = await runNonInteractiveTask(action, context, cliArgs);
+    if (action !== MODES.CHECK_UPDATE && action !== MODES.UPGRADE) {
+      result = attachStartupUpdateToResult(result, startupUpdate, context.config.selfUpdate.skipVersion);
+    }
+    result = {
+      ...(result || {}),
+      data: {
+        ...((result && result.data) || {}),
+        userFacingSummary: buildUserFacingSummary(action, result),
+      },
+    };
     if (cliArgs.saveConfig) {
       await saveConfig(config);
     }