clawt 2.17.1 → 2.19.0

package/src/constants/config.ts

@@ -39,6 +39,10 @@ export const CONFIG_DEFINITIONS: ConfigDefinitions = {
     defaultValue: {} as Record<string, string>,
     description: '命令别名映射',
   },
+  autoUpdate: {
+    defaultValue: true,
+    description: '是否启用自动更新检查（每 24 小时检查一次 npm registry）',
+  },
 };
 
 /**

package/src/constants/index.ts

@@ -1,12 +1,14 @@
-export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR, CLAUDE_PROJECTS_DIR } from './paths.js';
+export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR, CLAUDE_PROJECTS_DIR, UPDATE_CHECK_PATH } from './paths.js';
 export { INVALID_BRANCH_CHARS } from './branch.js';
 export { MESSAGES } from './messages/index.js';
 export { CONFIG_ALIAS_DISABLED_HINT } from './messages/index.js';
+export { UPDATE_MESSAGES, UPDATE_COMMANDS } from './messages/update.js';
 export { EXIT_CODES } from './exitCodes.js';
 export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS, VALID_TERMINAL_APPS, ITERM2_APP_PATH } from './terminal.js';
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, CONFIG_DEFINITIONS, APPEND_SYSTEM_PROMPT } from './config.js';
 export { AUTO_SAVE_COMMIT_MESSAGE } from './git.js';
 export { DEBUG_LOG_PREFIX, DEBUG_TIMESTAMP_FORMAT } from './logger.js';
+export { UPDATE_CHECK_INTERVAL_MS, NPM_REGISTRY_URL, NPM_REGISTRY_TIMEOUT_MS, PACKAGE_NAME } from './update.js';
 export {
   SPINNER_FRAMES,
   SPINNER_INTERVAL_MS,

package/src/constants/messages/index.ts

@@ -8,11 +8,14 @@ import { RESUME_MESSAGES } from './resume.js';
 import { REMOVE_MESSAGES } from './remove.js';
 import { RESET_MESSAGES } from './reset.js';
 import { CONFIG_CMD_MESSAGES, CONFIG_ALIAS_DISABLED_HINT } from './config.js';
-
-export { CONFIG_ALIAS_DISABLED_HINT };
 import { STATUS_MESSAGES } from './status.js';
 import { ALIAS_MESSAGES } from './alias.js';
+import { PROJECTS_MESSAGES } from './projects.js';
 import { COMPLETION_MESSAGES } from './completion.js';
+import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
+
+export { CONFIG_ALIAS_DISABLED_HINT };
+export { UPDATE_MESSAGES, UPDATE_COMMANDS };
 
 /**
  * 提示消息模板
@@ -31,5 +34,6 @@ export const MESSAGES = {
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
   ...ALIAS_MESSAGES,
+  ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
 } as const;

package/src/constants/messages/projects.ts

@@ -0,0 +1,25 @@
+/** projects 命令专属提示消息 */
+export const PROJECTS_MESSAGES = {
+  /** projects 命令全局概览标题 */
+  PROJECTS_OVERVIEW_TITLE: '项目概览',
+  /** projects 命令指定项目详情标题 */
+  PROJECTS_DETAIL_TITLE: (projectName: string) => `项目详情: ${projectName}`,
+  /** 无项目提示 */
+  PROJECTS_NO_PROJECTS: '(暂无项目，worktrees 目录为空)',
+  /** 项目不存在提示 */
+  PROJECTS_NOT_FOUND: (name: string) => `项目 ${name} 不存在`,
+  /** worktree 数量标签 */
+  PROJECTS_WORKTREE_COUNT: (count: number) => `${count} 个 worktree`,
+  /** 最近活跃时间标签 */
+  PROJECTS_LAST_ACTIVE: (relativeTime: string) => `最近活跃: ${relativeTime}`,
+  /** 磁盘占用标签 */
+  PROJECTS_DISK_USAGE: (size: string) => `磁盘占用: ${size}`,
+  /** 总磁盘占用标签 */
+  PROJECTS_TOTAL_DISK_USAGE: (size: string) => `总占用: ${size}`,
+  /** projects 详情无 worktree */
+  PROJECTS_DETAIL_NO_WORKTREES: '(该项目下无 worktree)',
+  /** 路径标签 */
+  PROJECTS_PATH: (path: string) => `路径: ${path}`,
+  /** 最后修改时间标签 */
+  PROJECTS_LAST_MODIFIED: (relativeTime: string) => `最后修改: ${relativeTime}`,
+} as const;

package/src/constants/messages/update.ts

@@ -0,0 +1,15 @@
+/** 各包管理器对应的全局安装命令 */
+export const UPDATE_COMMANDS: Record<string, string> = {
+  npm: 'npm i -g clawt',
+  pnpm: 'pnpm add -g clawt',
+  yarn: 'yarn global add clawt',
+} as const;
+
+/** 更新检查相关提示消息 */
+export const UPDATE_MESSAGES = {
+  /** 版本更新提示 */
+  UPDATE_AVAILABLE: (currentVersion: string, latestVersion: string) =>
+    `clawt 有新版本可用: ${currentVersion} → ${latestVersion}`,
+  /** 更新操作提示 */
+  UPDATE_HINT: (command: string) => `执行 ${command} 进行更新`,
+} as const;

package/src/constants/paths.ts

@@ -18,3 +18,6 @@ export const VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, 'validate-snapshots');
 
 /** Claude Code 项目会话目录 ~/.claude/projects/ */
 export const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+/** 更新检查缓存文件路径 ~/.clawt/update-check.json */
+export const UPDATE_CHECK_PATH = join(CLAWT_HOME, 'update-check.json');

package/src/constants/update.ts

@@ -0,0 +1,11 @@
+/** 更新检查间隔，24 小时（毫秒） */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** npm registry 查询地址 */
+export const NPM_REGISTRY_URL = 'https://registry.npmjs.org/clawt/latest';
+
+/** npm registry 请求超时时间（毫秒） */
+export const NPM_REGISTRY_TIMEOUT_MS = 5000;
+
+/** 包名 */
+export const PACKAGE_NAME = 'clawt';

package/src/index.ts

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { ClawtError } from './errors/index.js';
 import { logger, enableConsoleTransport } from './logger/index.js';
 import { EXIT_CODES } from './constants/index.js';
-import { printError, ensureClawtDirs, loadConfig, applyAliases } from './utils/index.js';
+import { printError, ensureClawtDirs, loadConfig, applyAliases, checkForUpdates } from './utils/index.js';
 import { registerListCommand } from './commands/list.js';
 import { registerCreateCommand } from './commands/create.js';
 import { registerRemoveCommand } from './commands/remove.js';
@@ -16,6 +16,7 @@ import { registerSyncCommand } from './commands/sync.js';
 import { registerResetCommand } from './commands/reset.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerAliasCommand } from './commands/alias.js';
+import { registerProjectsCommand } from './commands/projects.js';
 import { registerCompletionCommand } from './commands/completion.js';
 
 // 从 package.json 读取版本号，避免硬编码
@@ -53,6 +54,7 @@ registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
 registerAliasCommand(program);
+registerProjectsCommand(program);
 registerCompletionCommand(program);
 
 // 加载配置并应用命令别名
@@ -83,4 +85,16 @@ process.on('unhandledRejection', (reason) => {
   process.exit(EXIT_CODES.ERROR);
 });
 
-program.parse(process.argv);
+/**
+ * 异步主入口函数
+ * 执行命令解析后，根据配置项决定是否进行自动更新检查
+ */
+async function main(): Promise<void> {
+  await program.parseAsync(process.argv);
+
+  if (config.autoUpdate) {
+    await checkForUpdates(version);
+  }
+}
+
+main();

package/src/types/command.ts

@@ -69,3 +69,11 @@ export interface StatusOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** projects 命令选项 */
+export interface ProjectsOptions {
+  /** 指定项目名（可选，不传则展示所有项目概览） */
+  name?: string;
+  /** 以 JSON 格式输出 */
+  json?: boolean;
+}

package/src/types/config.ts

@@ -14,6 +14,8 @@ export interface ClawtConfig {
   terminalApp: string;
   /** 命令别名映射，键为别名，值为目标内置命令名 */
   aliases: Record<string, string>;
+  /** 是否启用自动更新检查 */
+  autoUpdate: boolean;
 }
 
 /** 单个配置项的完整定义（默认值 + 描述） */

package/src/types/index.ts

@@ -1,7 +1,8 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions, ProjectsOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';
 export type { WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, SnapshotSummary, StatusResult } from './status.js';
 export type { TaskFileEntry, ParseTaskFileOptions } from './taskFile.js';
+export type { ProjectOverview, ProjectWorktreeDetail, ProjectDetailResult, ProjectsOverviewResult } from './project.js';

package/src/types/project.ts

@@ -0,0 +1,45 @@
+/** 单个项目的概览信息 */
+export interface ProjectOverview {
+  /** 项目名称 */
+  name: string;
+  /** worktree 数量 */
+  worktreeCount: number;
+  /** 最近活跃时间（ISO 8601 格式），无 worktree 时为目录修改时间 */
+  lastActiveTime: string;
+  /** 磁盘占用（字节） */
+  diskUsage: number;
+}
+
+/** 单个项目的 worktree 详情 */
+export interface ProjectWorktreeDetail {
+  /** 分支名 */
+  branch: string;
+  /** worktree 路径 */
+  path: string;
+  /** 最后修改时间（ISO 8601 格式） */
+  lastModifiedTime: string;
+  /** 磁盘占用（字节） */
+  diskUsage: number;
+}
+
+/** projects 命令展示指定项目时的完整结果 */
+export interface ProjectDetailResult {
+  /** 项目名称 */
+  name: string;
+  /** 项目 worktree 根目录 */
+  projectDir: string;
+  /** worktree 详情列表（按最近活跃时间排序） */
+  worktrees: ProjectWorktreeDetail[];
+  /** 总磁盘占用（字节） */
+  totalDiskUsage: number;
+}
+
+/** projects 命令展示所有项目概览时的完整结果 */
+export interface ProjectsOverviewResult {
+  /** 所有项目概览列表（按最近活跃时间排序） */
+  projects: ProjectOverview[];
+  /** 项目总数 */
+  totalProjects: number;
+  /** 总磁盘占用（字节） */
+  totalDiskUsage: number;
+}

package/src/utils/formatter.ts

@@ -184,3 +184,49 @@ export function formatRelativeTime(isoDateString: string): string | null {
   const years = Math.floor(diffDays / 365);
   return `${years} 年前`;
 }
+
+/**
+ * 将字节数格式化为带单位的磁盘大小字符串
+ * @param {number} bytes - 字节数
+ * @returns {string} 格式化后的大小字符串，如 "1.5 GB"、"256.0 MB"、"10.2 KB"
+ */
+export function formatDiskSize(bytes: number): string {
+  /** 1 KB 的字节数 */
+  const KB = 1024;
+  /** 1 MB 的字节数 */
+  const MB = KB * 1024;
+  /** 1 GB 的字节数 */
+  const GB = MB * 1024;
+
+  if (bytes >= GB) {
+    return `${(bytes / GB).toFixed(1)} GB`;
+  }
+  if (bytes >= MB) {
+    return `${(bytes / MB).toFixed(1)} MB`;
+  }
+  if (bytes >= KB) {
+    return `${(bytes / KB).toFixed(1)} KB`;
+  }
+  return `${bytes} B`;
+}
+
+/**
+ * 将 Date 对象格式化为本机时区的 ISO 8601 字符串
+ * 输出格式: YYYY-MM-DDTHH:mm:ss.sss+HH:MM
+ * @param {Date} date - 日期对象
+ * @returns {string} 本机时区的 ISO 8601 格式字符串
+ */
+export function formatLocalISOString(date: Date): string {
+  const tzOffsetMs = date.getTimezoneOffset() * 60 * 1000;
+  const localDate = new Date(date.getTime() - tzOffsetMs);
+  const iso = localDate.toISOString().slice(0, -1);
+
+  // 拼接时区偏移量
+  const totalMinutes = -date.getTimezoneOffset();
+  const sign = totalMinutes >= 0 ? '+' : '-';
+  const absMinutes = Math.abs(totalMinutes);
+  const hours = String(Math.floor(absMinutes / 60)).padStart(2, '0');
+  const minutes = String(absMinutes % 60).padStart(2, '0');
+
+  return `${iso}${sign}${hours}:${minutes}`;
+}

package/src/utils/fs.ts

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 
 /**
  * 确保目录存在，不存在则递归创建
@@ -26,3 +27,33 @@ export function removeEmptyDir(dirPath: string): boolean {
   }
   return false;
 }
+
+/**
+ * 递归计算目录占用的磁盘大小（字节）
+ * @param {string} dirPath - 目录路径
+ * @returns {number} 目录总大小（字节）
+ */
+export function calculateDirSize(dirPath: string): number {
+  let totalSize = 0;
+
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      try {
+        if (entry.isDirectory()) {
+          totalSize += calculateDirSize(fullPath);
+        } else if (entry.isFile()) {
+          totalSize += statSync(fullPath).size;
+        }
+      } catch {
+        // 忽略无法访问的文件
+      }
+    }
+  } catch {
+    // 忽略无法读取的目录
+  }
+
+  return totalSize;
+}

package/src/utils/index.ts

@@ -51,8 +51,8 @@ export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } fro
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
-export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime } from './formatter.js';
-export { ensureDir, removeEmptyDir } from './fs.js';
+export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString } from './formatter.js';
+export { ensureDir, removeEmptyDir, calculateDirSize } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude, hasClaudeSessionHistory, launchInteractiveClaudeInNewTerminal } from './claude.js';
 export { getSnapshotPath, hasSnapshot, getSnapshotModifiedTime, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';
@@ -67,4 +67,5 @@ export { detectTerminalApp, openCommandInNewTerminalTab } from './terminal.js';
 export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
 export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue } from './config-strategy.js';
+export { checkForUpdates } from './update-checker.js';
 

package/src/utils/update-checker.ts

@@ -0,0 +1,213 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { request } from 'node:https';
+import chalk from 'chalk';
+import stringWidth from 'string-width';
+import {
+  UPDATE_CHECK_PATH,
+  UPDATE_CHECK_INTERVAL_MS,
+  NPM_REGISTRY_URL,
+  NPM_REGISTRY_TIMEOUT_MS,
+  PACKAGE_NAME,
+} from '../constants/index.js';
+import { UPDATE_MESSAGES, UPDATE_COMMANDS } from '../constants/messages/index.js';
+
+/** 更新检查缓存结构 */
+interface UpdateCache {
+  /** 上次检查时间戳 */
+  lastCheck: number;
+  /** 最新版本号 */
+  latestVersion: string;
+  /** 检查时的本地版本号 */
+  currentVersion: string;
+}
+
+/**
+ * 读取更新检查缓存文件
+ * @returns {UpdateCache | null} 缓存数据，文件不存在或解析失败返回 null
+ */
+function readUpdateCache(): UpdateCache | null {
+  try {
+    const raw = readFileSync(UPDATE_CHECK_PATH, 'utf-8');
+    return JSON.parse(raw) as UpdateCache;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写入更新检查缓存文件
+ * @param {UpdateCache} cache - 缓存数据
+ */
+function writeUpdateCache(cache: UpdateCache): void {
+  try {
+    writeFileSync(UPDATE_CHECK_PATH, JSON.stringify(cache, null, 2), 'utf-8');
+  } catch {
+    // 写入失败时静默忽略，不影响 CLI 正常功能
+  }
+}
+
+/**
+ * 判断缓存是否过期（超过 24 小时或本地版本已变化）
+ * @param {UpdateCache} cache - 缓存数据
+ * @param {string} currentVersion - 当前本地版本号
+ * @returns {boolean} 缓存是否已过期
+ */
+function isCacheExpired(cache: UpdateCache, currentVersion: string): boolean {
+  if (cache.currentVersion !== currentVersion) {
+    return true;
+  }
+  return Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
+}
+
+/**
+ * 简易 semver 版本比较（不引入新依赖）
+ * @param {string} latest - 最新版本号
+ * @param {string} current - 当前版本号
+ * @returns {boolean} latest 是否大于 current
+ */
+function isNewerVersion(latest: string, current: string): boolean {
+  const latestParts = latest.split('.').map(Number);
+  const currentParts = current.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const l = latestParts[i] || 0;
+    const c = currentParts[i] || 0;
+    if (l > c) return true;
+    if (l < c) return false;
+  }
+  return false;
+}
+
+/**
+ * 从 npm registry 获取最新版本号（5 秒超时）
+ * @returns {Promise<string | null>} 最新版本号，请求失败返回 null
+ */
+function fetchLatestVersion(): Promise<string | null> {
+  return new Promise((resolve) => {
+    const req = request(NPM_REGISTRY_URL, { timeout: NPM_REGISTRY_TIMEOUT_MS }, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => { data += chunk.toString(); });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data) as { version?: string };
+          resolve(parsed.version ?? null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+
+    req.end();
+  });
+}
+
+/**
+ * 探测当前全局安装 clawt 所用的包管理器
+ * 依次尝试 pnpm、yarn 的全局列表命令，匹配到则返回对应名称，否则默认 npm
+ * @returns {string} 包管理器名称：'pnpm' | 'yarn' | 'npm'
+ */
+function detectPackageManager(): string {
+  const checks = [
+    { name: 'pnpm', command: `pnpm list -g --depth=0 ${PACKAGE_NAME}` },
+    { name: 'yarn', command: `yarn global list --depth=0 2>/dev/null` },
+  ];
+
+  for (const { name, command } of checks) {
+    try {
+      const output = execSync(command, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+      if (output.includes(PACKAGE_NAME)) {
+        return name;
+      }
+    } catch {
+      // 命令不存在或执行失败，跳过
+    }
+  }
+
+  return 'npm';
+}
+
+/**
+ * 绘制带边框的版本更新提示框
+ * @param {string} currentVersion - 当前版本号
+ * @param {string} latestVersion - 最新版本号
+ */
+function printUpdateNotification(currentVersion: string, latestVersion: string): void {
+  const updateText = UPDATE_MESSAGES.UPDATE_AVAILABLE(
+    chalk.red(currentVersion),
+    chalk.green(latestVersion),
+  );
+  const pm = detectPackageManager();
+  const updateCommand = UPDATE_COMMANDS[pm] || UPDATE_COMMANDS.npm;
+  const commandText = UPDATE_MESSAGES.UPDATE_HINT(chalk.cyan(updateCommand));
+
+  const updateTextWidth = stringWidth(updateText);
+  const commandTextWidth = stringWidth(commandText);
+  const innerWidth = Math.max(updateTextWidth, commandTextWidth) + 4;
+
+  const padLine = (text: string): string => {
+    const textWidth = stringWidth(text);
+    const leftPad = Math.floor((innerWidth - textWidth) / 2);
+    const rightPad = innerWidth - textWidth - leftPad;
+    return `│${' '.repeat(leftPad)}${text}${' '.repeat(rightPad)}│`;
+  };
+
+  const top = `╭${'─'.repeat(innerWidth)}╮`;
+  const bottom = `╰${'─'.repeat(innerWidth)}╯`;
+  const emptyLine = `│${' '.repeat(innerWidth)}│`;
+
+  console.log();
+  console.log(top);
+  console.log(emptyLine);
+  console.log(padLine(updateText));
+  console.log(padLine(commandText));
+  console.log(emptyLine);
+  console.log(bottom);
+  console.log();
+}
+
+/**
+ * 检查更新入口函数
+ * 读取缓存 → 缓存有效且有新版本则打印提示 → 缓存过期则请求 registry 刷新
+ * 所有异常静默处理，不影响 CLI 正常功能
+ * @param {string} currentVersion - 当前本地版本号
+ */
+export async function checkForUpdates(currentVersion: string): Promise<void> {
+  try {
+    const cache = readUpdateCache();
+
+    // 缓存有效：直接判断是否需要提示
+    if (cache && !isCacheExpired(cache, currentVersion)) {
+      if (isNewerVersion(cache.latestVersion, currentVersion)) {
+        printUpdateNotification(currentVersion, cache.latestVersion);
+      }
+      return;
+    }
+
+    // 缓存过期或不存在：请求 registry
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) {
+      return;
+    }
+
+    // 写入新缓存
+    writeUpdateCache({
+      lastCheck: Date.now(),
+      latestVersion,
+      currentVersion,
+    });
+
+    // 有新版本则打印提示
+    if (isNewerVersion(latestVersion, currentVersion)) {
+      printUpdateNotification(currentVersion, latestVersion);
+    }
+  } catch {
+    // 任何异常静默忽略，不影响 CLI 正常功能
+  }
+}

package/tests/unit/commands/alias.test.ts

@@ -50,6 +50,7 @@ function mockDefaultConfig(aliases: Record<string, string> = {}) {
     maxConcurrency: 0,
     terminalApp: 'auto',
     aliases,
+    autoUpdate: true,
   };
 }
 

package/tests/unit/commands/config.test.ts

@@ -51,6 +51,7 @@ vi.mock('../../../src/constants/index.js', () => ({
     maxConcurrency: 0,
     terminalApp: 'auto',
     aliases: {},
+    autoUpdate: true,
   },
   CONFIG_DESCRIPTIONS: {
     autoDeleteBranch: '自动删除分支',
@@ -60,6 +61,7 @@ vi.mock('../../../src/constants/index.js', () => ({
     maxConcurrency: '最大并发数',
     terminalApp: '终端应用',
     aliases: '命令别名映射',
+    autoUpdate: '自动更新',
   },
   CONFIG_DEFINITIONS: {
     autoDeleteBranch: { defaultValue: false, description: '自动删除分支' },
@@ -69,6 +71,7 @@ vi.mock('../../../src/constants/index.js', () => ({
     maxConcurrency: { defaultValue: 0, description: '最大并发数' },
     terminalApp: { defaultValue: 'auto', description: '终端应用', allowedValues: ['auto', 'iterm2', 'terminal'] },
     aliases: { defaultValue: {}, description: '命令别名映射' },
+    autoUpdate: { defaultValue: true, description: '自动更新' },
   },
   CONFIG_ALIAS_DISABLED_HINT: '(通过 clawt alias 命令管理)',
   MESSAGES: {
@@ -111,6 +114,7 @@ function createMockConfig() {
     maxConcurrency: 0,
     terminalApp: 'auto',
     aliases: {},
+    autoUpdate: true,
   };
 }
 

package/tests/unit/utils/config-strategy.test.ts

@@ -29,6 +29,7 @@ vi.mock('../../../src/constants/index.js', async (importOriginal) => {
       confirmDestructiveOps: true,
       maxConcurrency: 0,
       terminalApp: 'auto',
+      autoUpdate: true,
     },
     CONFIG_DEFINITIONS: {
       autoDeleteBranch: { defaultValue: false, description: '自动删除分支' },
@@ -37,6 +38,7 @@ vi.mock('../../../src/constants/index.js', async (importOriginal) => {
       confirmDestructiveOps: { defaultValue: true, description: '破坏性操作确认' },
       maxConcurrency: { defaultValue: 0, description: '最大并发数' },
       terminalApp: { defaultValue: 'auto', description: '终端应用', allowedValues: ['auto', 'iterm2', 'terminal'] },
+      autoUpdate: { defaultValue: true, description: '自动更新' },
     },
     MESSAGES: {
       CONFIG_INVALID_BOOLEAN: (key: string) =>
@@ -86,7 +88,8 @@ describe('getValidConfigKeys', () => {
     expect(keys).toContain('confirmDestructiveOps');
     expect(keys).toContain('maxConcurrency');
     expect(keys).toContain('terminalApp');
-    expect(keys).toHaveLength(6);
+    expect(keys).toContain('autoUpdate');
+    expect(keys).toHaveLength(7);
   });
 });