clawt 2.17.1 → 2.18.0

package/README.md

@@ -292,6 +292,7 @@ clawt alias remove l
 | `maxConcurrency` | `0` | run 命令最大并发数，`0` 为不限制 |
 | `terminalApp` | `"auto"` | 批量 resume 使用的终端：`auto` / `iterm2` / `terminal` |
 | `aliases` | `{}` | 命令别名映射（如 `{"l": "list", "r": "run"}`） |
+| `autoUpdate` | `true` | 自动检查新版本（每 24 小时检查一次 npm registry） |
 
 ## 全局选项
 

package/dist/index.js

@@ -15,6 +15,7 @@ var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
 var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 var CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+var UPDATE_CHECK_PATH = join(CLAWT_HOME, "update-check.json");
 
 // src/constants/branch.ts
 var INVALID_BRANCH_CHARS = /[\/\\.\s~:*?[\]^]+/g;
@@ -394,6 +395,19 @@ var COMPLETION_MESSAGES = {
   COMPLETION_INSTALL_WRITE_ERROR: (filePath) => `\u65E0\u6CD5\u5199\u5165\u6587\u4EF6 ${filePath}\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u6743\u9650\u6216\u624B\u52A8\u914D\u7F6E\u3002`
 };
 
+// src/constants/messages/update.ts
+var UPDATE_COMMANDS = {
+  npm: "npm i -g clawt",
+  pnpm: "pnpm add -g clawt",
+  yarn: "yarn global add clawt"
+};
+var UPDATE_MESSAGES = {
+  /** 版本更新提示 */
+  UPDATE_AVAILABLE: (currentVersion, latestVersion) => `clawt \u6709\u65B0\u7248\u672C\u53EF\u7528: ${currentVersion} \u2192 ${latestVersion}`,
+  /** 更新操作提示 */
+  UPDATE_HINT: (command) => `\u6267\u884C ${command} \u8FDB\u884C\u66F4\u65B0`
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -456,6 +470,10 @@ var CONFIG_DEFINITIONS = {
   aliases: {
     defaultValue: {},
     description: "\u547D\u4EE4\u522B\u540D\u6620\u5C04"
+  },
+  autoUpdate: {
+    defaultValue: true,
+    description: "\u662F\u5426\u542F\u7528\u81EA\u52A8\u66F4\u65B0\u68C0\u67E5\uFF08\u6BCF 24 \u5C0F\u65F6\u68C0\u67E5\u4E00\u6B21 npm registry\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {
@@ -479,6 +497,12 @@ var AUTO_SAVE_COMMIT_MESSAGE = "chore: auto-save before sync";
 // src/constants/logger.ts
 var DEBUG_TIMESTAMP_FORMAT = "HH:mm:ss.SSS";
 
+// src/constants/update.ts
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/clawt/latest";
+var NPM_REGISTRY_TIMEOUT_MS = 5e3;
+var PACKAGE_NAME = "clawt";
+
 // src/constants/progress.ts
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var SPINNER_INTERVAL_MS = 100;
@@ -2299,8 +2323,139 @@ async function promptStringValue(key, currentValue) {
   }).run();
 }
 
-// src/commands/list.ts
+// src/utils/update-checker.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { execSync as execSync3 } from "child_process";
+import { request } from "https";
 import chalk6 from "chalk";
+import stringWidth2 from "string-width";
+function readUpdateCache() {
+  try {
+    const raw = readFileSync4(UPDATE_CHECK_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeUpdateCache(cache) {
+  try {
+    writeFileSync3(UPDATE_CHECK_PATH, JSON.stringify(cache, null, 2), "utf-8");
+  } catch {
+  }
+}
+function isCacheExpired(cache, currentVersion) {
+  if (cache.currentVersion !== currentVersion) {
+    return true;
+  }
+  return Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
+}
+function isNewerVersion(latest, current) {
+  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;
+}
+function fetchLatestVersion() {
+  return new Promise((resolve3) => {
+    const req = request(NPM_REGISTRY_URL, { timeout: NPM_REGISTRY_TIMEOUT_MS }, (res) => {
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk.toString();
+      });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(data);
+          resolve3(parsed.version ?? null);
+        } catch {
+          resolve3(null);
+        }
+      });
+    });
+    req.on("error", () => resolve3(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve3(null);
+    });
+    req.end();
+  });
+}
+function detectPackageManager() {
+  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 = execSync3(command, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+      if (output.includes(PACKAGE_NAME)) {
+        return name;
+      }
+    } catch {
+    }
+  }
+  return "npm";
+}
+function printUpdateNotification(currentVersion, latestVersion) {
+  const updateText = UPDATE_MESSAGES.UPDATE_AVAILABLE(
+    chalk6.red(currentVersion),
+    chalk6.green(latestVersion)
+  );
+  const pm = detectPackageManager();
+  const updateCommand = UPDATE_COMMANDS[pm] || UPDATE_COMMANDS.npm;
+  const commandText = UPDATE_MESSAGES.UPDATE_HINT(chalk6.cyan(updateCommand));
+  const updateTextWidth = stringWidth2(updateText);
+  const commandTextWidth = stringWidth2(commandText);
+  const innerWidth = Math.max(updateTextWidth, commandTextWidth) + 4;
+  const padLine = (text) => {
+    const textWidth = stringWidth2(text);
+    const leftPad = Math.floor((innerWidth - textWidth) / 2);
+    const rightPad = innerWidth - textWidth - leftPad;
+    return `\u2502${" ".repeat(leftPad)}${text}${" ".repeat(rightPad)}\u2502`;
+  };
+  const top = `\u256D${"\u2500".repeat(innerWidth)}\u256E`;
+  const bottom = `\u2570${"\u2500".repeat(innerWidth)}\u256F`;
+  const emptyLine = `\u2502${" ".repeat(innerWidth)}\u2502`;
+  console.log();
+  console.log(top);
+  console.log(emptyLine);
+  console.log(padLine(updateText));
+  console.log(padLine(commandText));
+  console.log(emptyLine);
+  console.log(bottom);
+  console.log();
+}
+async function checkForUpdates(currentVersion) {
+  try {
+    const cache = readUpdateCache();
+    if (cache && !isCacheExpired(cache, currentVersion)) {
+      if (isNewerVersion(cache.latestVersion, currentVersion)) {
+        printUpdateNotification(currentVersion, cache.latestVersion);
+      }
+      return;
+    }
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) {
+      return;
+    }
+    writeUpdateCache({
+      lastCheck: Date.now(),
+      latestVersion,
+      currentVersion
+    });
+    if (isNewerVersion(latestVersion, currentVersion)) {
+      printUpdateNotification(currentVersion, latestVersion);
+    }
+  } catch {
+  }
+}
+
+// src/commands/list.ts
+import chalk7 from "chalk";
 function registerListCommand(program2) {
   program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
     handleList(options);
@@ -2337,12 +2492,12 @@ function printListAsText(projectName, worktrees) {
     for (const wt of worktrees) {
       const status = getWorktreeStatus(wt);
       const isIdle = status ? isWorktreeIdle(status) : false;
-      const pathDisplay = isIdle ? chalk6.hex("#FF8C00")(wt.path) : wt.path;
+      const pathDisplay = isIdle ? chalk7.hex("#FF8C00")(wt.path) : wt.path;
       printInfo(`  ${pathDisplay}   [${wt.branch}]`);
       if (status) {
         printInfo(`    ${formatWorktreeStatus(status)}`);
       } else {
-        printInfo(`    ${chalk6.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
+        printInfo(`    ${chalk7.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
       }
       printInfo("");
     }
@@ -3025,7 +3180,7 @@ async function handleMerge(options) {
 }
 
 // src/commands/config.ts
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import Enquirer5 from "enquirer";
 function registerConfigCommand(program2) {
   const configCmd = program2.command("config").description("\u4EA4\u4E92\u5F0F\u67E5\u770B\u548C\u4FEE\u6539\u5168\u5C40\u914D\u7F6E").action(async () => {
@@ -3086,7 +3241,7 @@ async function handleInteractiveConfigSet() {
     const isObject = typeof DEFAULT_CONFIG[k] === "object";
     return {
       name: k,
-      message: `${k}: ${isObject ? chalk7.dim(JSON.stringify(config2[k])) : formatConfigValue(config2[k])}  ${chalk7.dim(`\u2014 ${CONFIG_DESCRIPTIONS[k]}`)}`,
+      message: `${k}: ${isObject ? chalk8.dim(JSON.stringify(config2[k])) : formatConfigValue(config2[k])}  ${chalk8.dim(`\u2014 ${CONFIG_DESCRIPTIONS[k]}`)}`,
       ...isObject && { disabled: CONFIG_ALIAS_DISABLED_HINT }
     };
   });
@@ -3141,7 +3296,7 @@ async function handleReset() {
 }
 
 // src/commands/status.ts
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 function registerStatusCommand(program2) {
   program2.command("status").description("\u663E\u793A\u9879\u76EE\u5168\u5C40\u72B6\u6001\u603B\u89C8").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
     handleStatus(options);
@@ -3161,7 +3316,7 @@ function collectStatus() {
   const projectName = getProjectName();
   const currentBranch = getCurrentBranch();
   const isClean = isWorkingDirClean();
-  const main = {
+  const main2 = {
     branch: currentBranch,
     isClean,
     projectName
@@ -3170,7 +3325,7 @@ function collectStatus() {
   const worktreeStatuses = worktrees.map((wt) => collectWorktreeDetailedStatus(wt, projectName));
   const snapshots = collectSnapshots(projectName, worktrees);
   return {
-    main,
+    main: main2,
     worktrees: worktreeStatuses,
     snapshots,
     totalWorktrees: worktrees.length
@@ -3254,7 +3409,7 @@ function printStatusAsJson(result) {
 }
 function printStatusAsText(result) {
   printDoubleSeparator();
-  printInfo(`  ${chalk8.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
+  printInfo(`  ${chalk9.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
   printDoubleSeparator();
   printInfo("");
   printMainSection(result.main);
@@ -3266,18 +3421,18 @@ function printStatusAsText(result) {
   printSnapshotsSection(result.snapshots);
   printDoubleSeparator();
 }
-function printMainSection(main) {
-  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
-  printInfo(`    \u5206\u652F: ${chalk8.bold(main.branch)}`);
-  if (main.isClean) {
-    printInfo(`    \u72B6\u6001: ${chalk8.green("\u2713 \u5E72\u51C0")}`);
+function printMainSection(main2) {
+  printInfo(`  ${chalk9.bold("\u25C6")} ${chalk9.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
+  printInfo(`    \u5206\u652F: ${chalk9.bold(main2.branch)}`);
+  if (main2.isClean) {
+    printInfo(`    \u72B6\u6001: ${chalk9.green("\u2713 \u5E72\u51C0")}`);
   } else {
-    printInfo(`    \u72B6\u6001: ${chalk8.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
+    printInfo(`    \u72B6\u6001: ${chalk9.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
   }
   printInfo("");
 }
 function printWorktreesSection(worktrees, total) {
-  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} \u4E2A)`);
+  printInfo(`  ${chalk9.bold("\u25C6")} ${chalk9.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} \u4E2A)`);
   printInfo("");
   if (worktrees.length === 0) {
     printInfo(`    ${MESSAGES.STATUS_NO_WORKTREES}`);
@@ -3289,56 +3444,56 @@ function printWorktreesSection(worktrees, total) {
 }
 function printWorktreeItem(wt) {
   const statusLabel = formatChangeStatusLabel(wt.changeStatus);
-  printInfo(`  ${chalk8.bold("\u25CF")} ${chalk8.bold(wt.branch)}   [${statusLabel}]`);
+  printInfo(`  ${chalk9.bold("\u25CF")} ${chalk9.bold(wt.branch)}   [${statusLabel}]`);
   if (wt.insertions > 0 || wt.deletions > 0) {
-    printInfo(`    ${chalk8.green(`+${wt.insertions}`)} ${chalk8.red(`-${wt.deletions}`)}`);
+    printInfo(`    ${chalk9.green(`+${wt.insertions}`)} ${chalk9.red(`-${wt.deletions}`)}`);
   }
   if (wt.commitsAhead > 0) {
-    printInfo(`    ${chalk8.yellow(`${wt.commitsAhead} \u4E2A\u672C\u5730\u63D0\u4EA4`)}`);
+    printInfo(`    ${chalk9.yellow(`${wt.commitsAhead} \u4E2A\u672C\u5730\u63D0\u4EA4`)}`);
   }
   if (wt.commitsBehind > 0) {
-    printInfo(`    ${chalk8.yellow(`\u843D\u540E\u4E3B\u5206\u652F ${wt.commitsBehind} \u4E2A\u63D0\u4EA4`)}`);
+    printInfo(`    ${chalk9.yellow(`\u843D\u540E\u4E3B\u5206\u652F ${wt.commitsBehind} \u4E2A\u63D0\u4EA4`)}`);
   } else {
-    printInfo(`    ${chalk8.green("\u4E0E\u4E3B\u5206\u652F\u540C\u6B65")}`);
+    printInfo(`    ${chalk9.green("\u4E0E\u4E3B\u5206\u652F\u540C\u6B65")}`);
   }
   if (wt.createdAt) {
     const relativeTime = formatRelativeTime(wt.createdAt);
     if (relativeTime) {
-      printInfo(`    ${chalk8.gray(MESSAGES.STATUS_CREATED_AT(relativeTime))}`);
+      printInfo(`    ${chalk9.gray(MESSAGES.STATUS_CREATED_AT(relativeTime))}`);
     }
   }
   if (wt.snapshotTime) {
     const relativeTime = formatRelativeTime(wt.snapshotTime);
     if (relativeTime) {
-      printInfo(`    ${chalk8.green(MESSAGES.STATUS_LAST_VALIDATED(relativeTime))}`);
+      printInfo(`    ${chalk9.green(MESSAGES.STATUS_LAST_VALIDATED(relativeTime))}`);
     }
   } else {
-    printInfo(`    ${chalk8.red(MESSAGES.STATUS_NOT_VALIDATED)}`);
+    printInfo(`    ${chalk9.red(MESSAGES.STATUS_NOT_VALIDATED)}`);
   }
   printInfo("");
 }
 function formatChangeStatusLabel(status) {
   switch (status) {
     case "committed":
-      return chalk8.green(MESSAGES.STATUS_CHANGE_COMMITTED);
+      return chalk9.green(MESSAGES.STATUS_CHANGE_COMMITTED);
     case "uncommitted":
-      return chalk8.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
+      return chalk9.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
     case "conflict":
-      return chalk8.red(MESSAGES.STATUS_CHANGE_CONFLICT);
+      return chalk9.red(MESSAGES.STATUS_CHANGE_CONFLICT);
     case "clean":
-      return chalk8.gray(MESSAGES.STATUS_CHANGE_CLEAN);
+      return chalk9.gray(MESSAGES.STATUS_CHANGE_CLEAN);
   }
 }
 function printSnapshotsSection(snapshots) {
-  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.total} \u4E2A)`);
+  printInfo(`  ${chalk9.bold("\u25C6")} ${chalk9.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.total} \u4E2A)`);
   if (snapshots.orphaned > 0) {
-    printInfo(`    ${chalk8.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED(snapshots.orphaned))}`);
+    printInfo(`    ${chalk9.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED(snapshots.orphaned))}`);
   }
   printInfo("");
 }
 
 // src/commands/alias.ts
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function getRegisteredCommandNames(program2) {
   return program2.commands.map((cmd) => cmd.name());
 }
@@ -3359,7 +3514,7 @@ ${MESSAGES.ALIAS_LIST_TITLE}
 `);
   printSeparator();
   for (const [alias, command] of entries) {
-    printInfo(`  ${chalk9.bold(alias)} \u2192 ${chalk9.cyan(command)}`);
+    printInfo(`  ${chalk10.bold(alias)} \u2192 ${chalk10.cyan(command)}`);
   }
   printInfo("");
   printSeparator();
@@ -3406,7 +3561,7 @@ function registerAliasCommand(program2) {
 }
 
 // src/commands/completion.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync10 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync10 } from "fs";
 import { resolve as resolve2 } from "path";
 import { homedir as homedir2 } from "os";
 
@@ -3563,14 +3718,14 @@ function generateCompletions(program2, args) {
 // src/commands/completion.ts
 function appendToFile(filePath, content) {
   if (existsSync10(filePath)) {
-    const current = readFileSync4(filePath, "utf-8");
+    const current = readFileSync5(filePath, "utf-8");
     if (current.includes("clawt completion")) {
       printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ": " + filePath);
       return;
     }
     content = current + content;
   }
-  writeFileSync3(filePath, content, "utf-8");
+  writeFileSync4(filePath, content, "utf-8");
   printSuccess(MESSAGES.COMPLETION_INSTALL_SUCCESS + ": " + filePath);
   printInfo(MESSAGES.COMPLETION_INSTALL_RESTART(filePath));
 }
@@ -3665,4 +3820,10 @@ process.on("unhandledRejection", (reason) => {
   logger.error(`\u672A\u5904\u7406\u7684 Promise \u62D2\u7EDD: ${error.message}`);
   process.exit(EXIT_CODES.ERROR);
 });
-program.parse(process.argv);
+async function main() {
+  await program.parseAsync(process.argv);
+  if (config.autoUpdate) {
+    await checkForUpdates(version);
+  }
+}
+main();

package/dist/postinstall.js

@@ -10,6 +10,7 @@ var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
 var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 var CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+var UPDATE_CHECK_PATH = join(CLAWT_HOME, "update-check.json");
 
 // src/constants/messages/common.ts
 var COMMON_MESSAGES = {
@@ -435,6 +436,10 @@ var CONFIG_DEFINITIONS = {
   aliases: {
     defaultValue: {},
     description: "\u547D\u4EE4\u522B\u540D\u6620\u5C04"
+  },
+  autoUpdate: {
+    defaultValue: true,
+    description: "\u662F\u5426\u542F\u7528\u81EA\u52A8\u66F4\u65B0\u68C0\u67E5\uFF08\u6BCF 24 \u5C0F\u65F6\u68C0\u67E5\u4E00\u6B21 npm registry\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {
@@ -452,6 +457,9 @@ function deriveConfigDescriptions(definitions) {
 var DEFAULT_CONFIG = deriveDefaultConfig(CONFIG_DEFINITIONS);
 var CONFIG_DESCRIPTIONS = deriveConfigDescriptions(CONFIG_DEFINITIONS);
 
+// src/constants/update.ts
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+
 // scripts/postinstall.ts
 function ensureDirectory(dirPath) {
   if (!existsSync(dirPath)) {

package/docs/spec.md

@@ -28,6 +28,7 @@
   - [5.14 项目全局状态总览](#514-项目全局状态总览)
   - [5.15 命令别名管理](#515-命令别名管理)
   - [5.16 Shell 自动补全](#516-clawt-completion-命令)
+  - [5.17 自动更新检查](#517-自动更新检查)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -146,6 +147,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ```
 ~/.clawt/
 ├── config.json                          # 全局配置文件
+├── update-check.json                    # 更新检查缓存文件（自动生成）
 ├── logs/                                # 日志目录
 │   ├── clawt-2025-02-06.log
 │   └── ...
@@ -1067,7 +1069,8 @@ clawt merge [-m <commitMessage>]
   "confirmDestructiveOps": true,
   "maxConcurrency": 0,
   "terminalApp": "auto",
-  "aliases": {}
+  "aliases": {},
+  "autoUpdate": true
 }
 ```
 
@@ -1082,6 +1085,7 @@ clawt merge [-m <commitMessage>]
 | `maxConcurrency` | `number` | `0` | run 命令默认最大并发数，`0` 表示不限制 |
 | `terminalApp` | `string` | `"auto"` | 批量 resume 使用的终端应用：`auto`（自动检测）、`iterm2`、`terminal`（macOS） |
 | `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
+| `autoUpdate` | `boolean` | `true` | 是否启用自动更新检查（每 24 小时通过 npm registry 检查一次新版本） |
 
 ---
 
@@ -1816,6 +1820,102 @@ clawt completion install
 
 ---
 
+### 5.17 自动更新检查
+
+CLI 在每次命令执行完毕后，根据配置项 `autoUpdate` 决定是否检查 npm registry 上的最新版本。当发现新版本时，以带边框的提示框在终端输出版本更新信息和升级命令。
+
+#### 触发条件
+
+- 配置项 `autoUpdate` 为 `true`（默认启用）
+- 命令正常执行完毕后触发（在 `program.parseAsync()` 之后）
+
+#### 检查流程
+
+1. 读取缓存文件 `~/.clawt/update-check.json`
+2. 判断缓存是否有效：
+   - 缓存不存在或解析失败 → 视为过期
+   - 缓存中的 `currentVersion` 与本地版本不一致 → 视为过期
+   - 距离上次检查超过 24 小时 → 视为过期
+3. **缓存有效**：直接使用缓存中的 `latestVersion` 与本地版本比较，有新版本则打印提示
+4. **缓存过期**：向 npm registry 发起 HTTPS 请求获取最新版本号（5 秒超时），更新缓存文件后判断并打印提示
+
+#### 缓存文件
+
+**路径：** `~/.clawt/update-check.json`
+
+**结构：**
+
+```json
+{
+  "lastCheck": 1709000000000,
+  "latestVersion": "2.18.0",
+  "currentVersion": "2.17.1"
+}
+```
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `lastCheck` | `number` | 上次检查时间戳（毫秒） |
+| `latestVersion` | `string` | 从 registry 获取的最新版本号 |
+| `currentVersion` | `string` | 检查时的本地版本号 |
+
+#### 版本比较
+
+使用简易 semver 比较（不引入额外依赖），逐级比较 `major.minor.patch`：
+
+- `latest > current` → 提示更新
+- `latest <= current` → 不提示
+
+#### 包管理器检测
+
+更新提示中会显示与用户安装方式匹配的升级命令。检测逻辑依次尝试：
+
+1. `pnpm list -g --depth=0 clawt` → 匹配则提示 `pnpm add -g clawt`
+2. `yarn global list --depth=0` → 输出含 `clawt` 则提示 `yarn global add clawt`
+3. 以上均未匹配 → 默认提示 `npm i -g clawt`
+
+#### 提示框格式
+
+当检测到新版本时，输出带 Unicode 圆角边框的居中提示框：
+
+```
+╭──────────────────────────────────────────────╮
+│                                              │
+│   clawt 有新版本可用: 2.17.1 → 2.18.0       │
+│   执行 npm i -g clawt 进行更新               │
+│                                              │
+╰──────────────────────────────────────────────╯
+```
+
+版本号和命令使用 chalk 着色：当前版本红色、最新版本绿色、更新命令青色。
+
+#### 容错设计
+
+所有异常静默处理，不影响 CLI 正常功能：
+
+- 网络请求失败或超时（5 秒） → 静默忽略
+- registry 返回无效 JSON 或缺少 `version` 字段 → 静默忽略
+- 缓存文件读写失败 → 静默忽略
+- `checkForUpdates()` 入口函数的最外层 `try/catch` 确保任何未预期异常都不会中断 CLI
+
+#### 常量定义
+
+| 常量 | 值 | 位置 |
+| ---- | -- | ---- |
+| `UPDATE_CHECK_INTERVAL_MS` | `86400000`（24 小时） | `src/constants/update.ts` |
+| `NPM_REGISTRY_URL` | `https://registry.npmjs.org/clawt/latest` | `src/constants/update.ts` |
+| `NPM_REGISTRY_TIMEOUT_MS` | `5000` | `src/constants/update.ts` |
+| `PACKAGE_NAME` | `clawt` | `src/constants/update.ts` |
+| `UPDATE_CHECK_PATH` | `~/.clawt/update-check.json` | `src/constants/paths.ts` |
+
+#### 实现说明
+
+- 入口函数：`checkForUpdates()`（在 `src/utils/update-checker.ts`）
+- 消息常量：`UPDATE_MESSAGES`、`UPDATE_COMMANDS`（在 `src/constants/messages/update.ts`）
+- 入口调用点：`src/index.ts` 的 `main()` 异步函数中，`program.parseAsync()` 之后根据 `config.autoUpdate` 条件调用
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.17.1",
+  "version": "2.18.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

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,13 @@ 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 { COMPLETION_MESSAGES } from './completion.js';
+import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
+
+export { CONFIG_ALIAS_DISABLED_HINT };
+export { UPDATE_MESSAGES, UPDATE_COMMANDS };
 
 /**
  * 提示消息模板

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';