clawt 2.15.0 → 2.16.1

package/README.md

@@ -119,12 +119,16 @@ clawt create -b <branch> -n 3      # 批量创建 3 个
 ### `clawt validate` — 在主 worktree 中验证分支变更
 
 ```bash
-clawt validate -b <branch>         # 将变更迁移到主 worktree 测试
-clawt validate -b <branch> --clean  # 清理 validate 状态
+clawt validate -b <branch>                    # 将变更迁移到主 worktree 测试
+clawt validate -b <branch> --clean             # 清理 validate 状态
+clawt validate -b <branch> -r "npm test"       # validate 成功后自动运行测试
+clawt validate -b <branch> -r "npm run build"  # validate 成功后自动构建
 ```
 
 支持增量模式：再次 validate 同一分支时，可通过 `git diff` 查看两次之间的增量差异。
 
+`-r, --run` 选项可在 validate 成功后自动在主 worktree 中执行指定命令（如测试、构建等），命令执行失败不影响 validate 结果。
+
 ### `clawt sync` — 同步主分支代码到目标 worktree
 
 ```bash

package/dist/index.js

@@ -189,7 +189,15 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** validate 交互选择提示 */
   VALIDATE_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u9A8C\u8BC1\u7684\u5206\u652F",
   /** validate 模糊匹配到多个结果提示 */
-  VALIDATE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
+  VALIDATE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** --run 命令开始执行提示 */
+  VALIDATE_RUN_START: (command) => `\u6B63\u5728\u4E3B worktree \u4E2D\u6267\u884C\u547D\u4EE4: ${command}`,
+  /** --run 命令执行成功（退出码 0） */
+  VALIDATE_RUN_SUCCESS: (command) => `\u2713 \u547D\u4EE4\u6267\u884C\u5B8C\u6210: ${command}\uFF0C\u9000\u51FA\u7801: 0`,
+  /** --run 命令执行失败（退出码非 0） */
+  VALIDATE_RUN_FAILED: (command, exitCode) => `\u2717 \u547D\u4EE4\u6267\u884C\u5B8C\u6210: ${command}\uFF0C\u9000\u51FA\u7801: ${exitCode}`,
+  /** --run 命令执行异常（进程启动失败等） */
+  VALIDATE_RUN_ERROR: (command, errorMessage) => `\u2717 \u547D\u4EE4\u6267\u884C\u51FA\u9519: ${errorMessage}`
 };
 
 // src/constants/messages/sync.ts
@@ -253,7 +261,9 @@ var REMOVE_MESSAGES = {
 ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 批量移除部分失败 */
   REMOVE_PARTIAL_FAILURE: (failures) => `\u4EE5\u4E0B worktree \u79FB\u9664\u5931\u8D25\uFF1A
-${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`
+${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`,
+  /** 用户选择保留本地分支 */
+  REMOVE_BRANCHES_KEPT: "\u5DF2\u4FDD\u7559\u672C\u5730\u5206\u652F\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 git branch -D <\u5206\u652F\u540D> \u624B\u52A8\u5220\u9664"
 };
 
 // src/constants/messages/reset.ts
@@ -521,7 +531,7 @@ function enableConsoleTransport() {
 }
 
 // src/utils/shell.ts
-import { execSync, execFileSync, spawn } from "child_process";
+import { execSync, execFileSync, spawn, spawnSync } from "child_process";
 function execCommand(command, options) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ""}`);
   const result = execSync(command, {
@@ -555,6 +565,14 @@ function execCommandWithInput(command, args, options) {
   });
   return result.trim();
 }
+function runCommandInherited(command, options) {
+  logger.debug(`\u6267\u884C\u547D\u4EE4(inherit): ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ""}`);
+  return spawnSync(command, {
+    cwd: options?.cwd,
+    stdio: "inherit",
+    shell: true
+  });
+}
 
 // src/utils/git.ts
 import { basename } from "path";
@@ -746,6 +764,9 @@ function printWarning(message) {
 function printInfo(message) {
   console.log(message);
 }
+function printHint(message) {
+  console.log(chalk2.hex("#FF8C00")(message));
+}
 function printSeparator() {
   console.log(MESSAGES.SEPARATOR);
 }
@@ -1000,7 +1021,7 @@ function parseConcurrency(optionValue, configValue) {
 import Enquirer from "enquirer";
 
 // src/utils/claude.ts
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync6, readdirSync as readdirSync3 } from "fs";
 import { join as join3 } from "path";
 
@@ -1109,7 +1130,7 @@ function launchInteractiveClaude(worktree, options = {}) {
     printInfo(`  \u6A21\u5F0F: ${hasPreviousSession ? "\u7EE7\u7EED\u4E0A\u6B21\u5BF9\u8BDD" : "\u65B0\u5BF9\u8BDD"}`);
   }
   printInfo("");
-  const result = spawnSync(cmd, args, {
+  const result = spawnSync2(cmd, args, {
     cwd: worktree.path,
     stdio: "inherit"
   });
@@ -1779,7 +1800,7 @@ async function executeBatchTasks(worktrees, tasks, concurrency) {
 // src/utils/dry-run.ts
 import chalk4 from "chalk";
 import { join as join5 } from "path";
-var DRY_RUN_TASK_DESC_MAX_LENGTH = 70;
+var DRY_RUN_TASK_DESC_MAX_LENGTH = 80;
 function truncateTaskDesc(task) {
   const oneLine = task.replace(/\n/g, " ").trim();
   if (oneLine.length <= DRY_RUN_TASK_DESC_MAX_LENGTH) {
@@ -2046,6 +2067,9 @@ async function handleRemove(options) {
   let shouldDeleteBranch = autoDelete;
   if (!autoDelete) {
     shouldDeleteBranch = await confirmAction("\u662F\u5426\u540C\u65F6\u5220\u9664\u5BF9\u5E94\u7684\u672C\u5730\u5206\u652F\uFF1F");
+    if (!shouldDeleteBranch) {
+      printHint(MESSAGES.REMOVE_BRANCHES_KEPT);
+    }
   }
   const failures = [];
   for (const wt of worktreesToRemove) {
@@ -2227,7 +2251,7 @@ var VALIDATE_RESOLVE_MESSAGES = {
   noMatch: MESSAGES.VALIDATE_NO_MATCH
 };
 function registerValidateCommand(program2) {
-  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").option("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").action(async (options) => {
+  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").option("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").option("-r, --run <command>", "validate \u6210\u529F\u540E\u5728\u4E3B worktree \u4E2D\u6267\u884C\u7684\u547D\u4EE4").action(async (options) => {
     await handleValidate(options);
   });
 }
@@ -2368,6 +2392,23 @@ function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, project
   }
   printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
+function executeRunCommand(command, mainWorktreePath) {
+  printInfo("");
+  printInfo(MESSAGES.VALIDATE_RUN_START(command));
+  printSeparator();
+  const result = runCommandInherited(command, { cwd: mainWorktreePath });
+  printSeparator();
+  if (result.error) {
+    printError(MESSAGES.VALIDATE_RUN_ERROR(command, result.error.message));
+    return;
+  }
+  const exitCode = result.status ?? 1;
+  if (exitCode === 0) {
+    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
+  } else {
+    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
+  }
+}
 async function handleValidate(options) {
   if (options.clean) {
     await handleValidateClean(options);
@@ -2399,6 +2440,9 @@ async function handleValidate(options) {
     }
     handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
+  if (options.run) {
+    executeRunCommand(options.run, mainWorktreePath);
+  }
 }
 
 // src/commands/merge.ts

package/dist/postinstall.js

@@ -181,7 +181,15 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** validate 交互选择提示 */
   VALIDATE_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u9A8C\u8BC1\u7684\u5206\u652F",
   /** validate 模糊匹配到多个结果提示 */
-  VALIDATE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
+  VALIDATE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** --run 命令开始执行提示 */
+  VALIDATE_RUN_START: (command) => `\u6B63\u5728\u4E3B worktree \u4E2D\u6267\u884C\u547D\u4EE4: ${command}`,
+  /** --run 命令执行成功（退出码 0） */
+  VALIDATE_RUN_SUCCESS: (command) => `\u2713 \u547D\u4EE4\u6267\u884C\u5B8C\u6210: ${command}\uFF0C\u9000\u51FA\u7801: 0`,
+  /** --run 命令执行失败（退出码非 0） */
+  VALIDATE_RUN_FAILED: (command, exitCode) => `\u2717 \u547D\u4EE4\u6267\u884C\u5B8C\u6210: ${command}\uFF0C\u9000\u51FA\u7801: ${exitCode}`,
+  /** --run 命令执行异常（进程启动失败等） */
+  VALIDATE_RUN_ERROR: (command, errorMessage) => `\u2717 \u547D\u4EE4\u6267\u884C\u51FA\u9519: ${errorMessage}`
 };
 
 // src/constants/messages/sync.ts
@@ -245,7 +253,9 @@ var REMOVE_MESSAGES = {
 ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 批量移除部分失败 */
   REMOVE_PARTIAL_FAILURE: (failures) => `\u4EE5\u4E0B worktree \u79FB\u9664\u5931\u8D25\uFF1A
-${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`
+${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`,
+  /** 用户选择保留本地分支 */
+  REMOVE_BRANCHES_KEPT: "\u5DF2\u4FDD\u7559\u672C\u5730\u5206\u652F\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 git branch -D <\u5206\u652F\u540D> \u624B\u52A8\u5220\u9664"
 };
 
 // src/constants/messages/reset.ts

package/docs/spec.md

@@ -460,18 +460,19 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 
 ```bash
 # 指定分支名（支持模糊匹配）
-clawt validate -b <branchName> [--clean]
+clawt validate -b <branchName> [--clean] [-r <command>]
 
 # 不指定分支名（列出所有分支供选择）
-clawt validate [--clean]
+clawt validate [--clean] [-r <command>]
 ```
 
 **参数：**
 
-| 参数      | 必填 | 说明                                                                     |
-| --------- | ---- | ------------------------------------------------------------------------ |
-| `-b`      | 否   | 要验证的 worktree 分支名（支持模糊匹配，不传则列出所有分支供选择）           |
-| `--clean` | 否   | 清理 validate 状态（重置主 worktree 并删除快照）                            |
+| 参数          | 必填 | 说明                                                                     |
+| ------------- | ---- | ------------------------------------------------------------------------ |
+| `-b`          | 否   | 要验证的 worktree 分支名（支持模糊匹配，不传则列出所有分支供选择）           |
+| `--clean`     | 否   | 清理 validate 状态（重置主 worktree 并删除快照）                            |
+| `-r, --run`   | 否   | validate 成功后在主 worktree 中执行的命令（如测试、构建等）                  |
 
 > **限制：** 单次只能验证一个分支，不支持批量验证。
 
@@ -597,6 +598,45 @@ git restore --staged .
   可以开始验证了
 ```
 
+##### 步骤 6：执行 `--run` 命令（可选）
+
+如果用户传入了 `-r, --run` 选项，在 validate 成功后自动在主 worktree 中执行指定命令：
+
+```bash
+# 示例
+clawt validate -b feature-scheme-1 -r "npm test"
+```
+
+**执行说明：**
+
+- 命令通过 `spawnSync` + `inherit` stdio 模式在主 worktree 中执行，输出实时显示在终端
+- 命令执行失败（退出码非 0 或进程启动失败）**不影响** validate 本身的结果，仅输出提示信息
+- `--clean` 模式下传入 `--run` 会被忽略（只执行 clean 逻辑）
+
+**输出格式：**
+
+```
+# 命令执行成功
+正在主 worktree 中执行命令: npm test
+────────────────────────────────────────
+... 命令的实时输出 ...
+────────────────────────────────────────
+✓ 命令执行完成: npm test，退出码: 0
+
+# 命令执行失败（退出码非 0）
+正在主 worktree 中执行命令: npm test
+────────────────────────────────────────
+... 命令的实时输出 ...
+────────────────────────────────────────
+✗ 命令执行完成: npm test，退出码: 1
+
+# 命令执行出错（进程启动失败）
+正在主 worktree 中执行命令: nonexistent
+────────────────────────────────────────
+────────────────────────────────────────
+✗ 命令执行出错: spawn ENOENT
+```
+
 #### 增量 validate（存在历史快照）
 
 当 `~/.clawt/validate-snapshots/<project>/<branchName>.tree` 存在时，自动进入增量模式：
@@ -666,6 +706,10 @@ git apply --cached < patch
   可以开始验证了
 ```
 
+##### 步骤 7：执行 `--run` 命令（可选）
+
+与首次 validate 的步骤 6 相同，增量 validate 成功后也会执行 `-r, --run` 指定的命令。
+
 ---
 
 ### 5.5 移除 Worktree

package/package.json

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

package/src/commands/remove.ts

@@ -16,6 +16,7 @@ import {
   printInfo,
   printSuccess,
   printError,
+  printHint,
   confirmAction,
   removeSnapshot,
   removeProjectSnapshots,
@@ -85,6 +86,9 @@ async function handleRemove(options: RemoveOptions): Promise<void> {
 
   if (!autoDelete) {
     shouldDeleteBranch = await confirmAction('是否同时删除对应的本地分支？');
+    if (!shouldDeleteBranch) {
+      printHint(MESSAGES.REMOVE_BRANCHES_KEPT);
+    }
   }
 
   // 执行移除，收集失败项

package/src/commands/validate.ts

@@ -34,9 +34,12 @@ import {
   removeSnapshot,
   confirmDestructiveAction,
   printSuccess,
+  printError,
   printWarning,
   printInfo,
+  printSeparator,
   resolveTargetWorktree,
+  runCommandInherited,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -58,6 +61,7 @@ export function registerValidateCommand(program: Command): void {
     .description('在主 worktree 验证某个 worktree 分支的变更')
     .option('-b, --branch <branchName>', '要验证的分支名（支持模糊匹配，不传则列出所有分支）')
     .option('--clean', '清理 validate 状态（重置主 worktree 并删除快照）')
+    .option('-r, --run <command>', 'validate 成功后在主 worktree 中执行的命令')
     .action(async (options: ValidateOptions) => {
       await handleValidate(options);
     });
@@ -300,6 +304,35 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
 
+/**
+ * 在主 worktree 中执行用户指定的命令
+ * 命令执行失败不影响 validate 本身的结果，仅输出提示
+ * @param {string} command - 要执行的命令字符串
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ */
+function executeRunCommand(command: string, mainWorktreePath: string): void {
+  printInfo('');
+  printInfo(MESSAGES.VALIDATE_RUN_START(command));
+  printSeparator();
+
+  const result = runCommandInherited(command, { cwd: mainWorktreePath });
+
+  printSeparator();
+
+  if (result.error) {
+    // 进程启动失败（如命令不存在）
+    printError(MESSAGES.VALIDATE_RUN_ERROR(command, result.error.message));
+    return;
+  }
+
+  const exitCode = result.status ?? 1;
+  if (exitCode === 0) {
+    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
+  } else {
+    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
+  }
+}
+
 /**
  * 执行 validate 命令的核心逻辑
  * @param {ValidateOptions} options - 命令选项
@@ -350,4 +383,9 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
 
     handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
+
+  // validate 成功后执行用户指定的命令
+  if (options.run) {
+    executeRunCommand(options.run, mainWorktreePath);
+  }
 }

package/src/constants/messages/remove.ts

@@ -12,4 +12,6 @@ export const REMOVE_MESSAGES = {
   /** 批量移除部分失败 */
   REMOVE_PARTIAL_FAILURE: (failures: Array<{ path: string; error: string }>) =>
     `以下 worktree 移除失败：\n${failures.map((f) => `  ✗ ${f.path}: ${f.error}`).join('\n')}`,
+  /** 用户选择保留本地分支 */
+  REMOVE_BRANCHES_KEPT: '已保留本地分支，可稍后使用 git branch -D <分支名> 手动删除',
 } as const;

package/src/constants/messages/validate.ts

@@ -22,4 +22,14 @@ export const VALIDATE_MESSAGES = {
   VALIDATE_SELECT_BRANCH: '请选择要验证的分支',
   /** validate 模糊匹配到多个结果提示 */
   VALIDATE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** --run 命令开始执行提示 */
+  VALIDATE_RUN_START: (command: string) => `正在主 worktree 中执行命令: ${command}`,
+  /** --run 命令执行成功（退出码 0） */
+  VALIDATE_RUN_SUCCESS: (command: string) => `✓ 命令执行完成: ${command}，退出码: 0`,
+  /** --run 命令执行失败（退出码非 0） */
+  VALIDATE_RUN_FAILED: (command: string, exitCode: number) =>
+    `✗ 命令执行完成: ${command}，退出码: ${exitCode}`,
+  /** --run 命令执行异常（进程启动失败等） */
+  VALIDATE_RUN_ERROR: (command: string, errorMessage: string) =>
+    `✗ 命令执行出错: ${errorMessage}`,
 } as const;

package/src/types/command.ts

@@ -26,6 +26,8 @@ export interface ValidateOptions {
   branch?: string;
   /** 清理 validate 状态 */
   clean?: boolean;
+  /** validate 成功后在主 worktree 中执行的命令 */
+  run?: string;
 }
 
 /** merge 命令选项 */

package/src/utils/dry-run.ts

@@ -6,7 +6,7 @@ import { getProjectWorktreeDir } from './worktree.js';
 import { printInfo, printDoubleSeparator, printSeparator } from './formatter.js';
 
 /** dry-run 模式下任务描述的最大显示长度 */
-const DRY_RUN_TASK_DESC_MAX_LENGTH = 70;
+const DRY_RUN_TASK_DESC_MAX_LENGTH = 80;
 
 /**
  * 截取任务描述，超出最大长度时末尾加省略号

package/src/utils/formatter.ts

@@ -35,6 +35,14 @@ export function printInfo(message: string): void {
   console.log(message);
 }
 
+/**
+ * 输出提示信息（橙色）
+ * @param {string} message - 消息内容
+ */
+export function printHint(message: string): void {
+  console.log(chalk.hex('#FF8C00')(message));
+}
+
 /**
  * 输出分隔线
  */

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { execCommand, spawnProcess, killAllChildProcesses, execCommandWithInput } from './shell.js';
+export { execCommand, spawnProcess, killAllChildProcesses, execCommandWithInput, runCommandInherited } from './shell.js';
 export {
   getGitCommonDir,
   getGitTopLevel,
@@ -49,7 +49,7 @@ 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, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration } from './formatter.js';
+export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration } from './formatter.js';
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude, hasClaudeSessionHistory, launchInteractiveClaudeInNewTerminal } from './claude.js';

package/src/utils/shell.ts

@@ -1,4 +1,4 @@
-import { execSync, execFileSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
+import { execSync, execFileSync, spawn, spawnSync, type ChildProcess, type SpawnSyncReturns, type StdioOptions } from 'node:child_process';
 import { logger } from '../logger/index.js';
 
 /**
@@ -72,3 +72,23 @@ export function execCommandWithInput(command: string, args: string[], options: {
   });
   return result.trim();
 }
+
+/**
+ * 同步执行命令，继承父进程的 stdio（实时输出到终端）
+ * 使用 shell 模式以支持管道、重定向等 shell 语法
+ * @param {string} command - 要执行的命令字符串
+ * @param {object} options - 可选配置
+ * @param {string} options.cwd - 工作目录
+ * @returns {SpawnSyncReturns<Buffer>} spawnSync 的返回结果
+ */
+export function runCommandInherited(
+  command: string,
+  options?: { cwd?: string },
+): SpawnSyncReturns<Buffer> {
+  logger.debug(`执行命令(inherit): ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ''}`);
+  return spawnSync(command, {
+    cwd: options?.cwd,
+    stdio: 'inherit',
+    shell: true,
+  });
+}

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

@@ -24,6 +24,7 @@ vi.mock('../../../src/constants/index.js', () => ({
     REMOVE_SELECT_BRANCH: '请选择要移除的分支（空格选择，回车确认）',
     REMOVE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支`,
     REMOVE_NO_MATCH: (name: string, branches: string[]) => `未找到与 "${name}" 匹配的分支，可用：${branches.join(', ')}`,
+    REMOVE_BRANCHES_KEPT: '已保留本地分支，可稍后使用 git branch -D <分支名> 手动删除',
   },
 }));
 
@@ -40,6 +41,7 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   printSuccess: vi.fn(),
   printError: vi.fn(),
+  printHint: vi.fn(),
   confirmAction: vi.fn(),
   removeSnapshot: vi.fn(),
   removeProjectSnapshots: vi.fn(),
@@ -59,6 +61,7 @@ import {
   removeProjectSnapshots,
   printSuccess,
   printError,
+  printHint,
   resolveTargetWorktrees,
 } from '../../../src/utils/index.js';
 
@@ -72,6 +75,7 @@ const mockedRemoveSnapshot = vi.mocked(removeSnapshot);
 const mockedRemoveProjectSnapshots = vi.mocked(removeProjectSnapshots);
 const mockedPrintSuccess = vi.mocked(printSuccess);
 const mockedPrintError = vi.mocked(printError);
+const mockedPrintHint = vi.mocked(printHint);
 const mockedResolveTargetWorktrees = vi.mocked(resolveTargetWorktrees);
 
 beforeEach(() => {
@@ -86,6 +90,7 @@ beforeEach(() => {
   mockedRemoveProjectSnapshots.mockReset();
   mockedPrintSuccess.mockReset();
   mockedPrintError.mockReset();
+  mockedPrintHint.mockReset();
   mockedResolveTargetWorktrees.mockReset();
 });
 
@@ -199,6 +204,8 @@ describe('handleRemove', () => {
     expect(mockedConfirmAction).toHaveBeenCalled();
     // 用户拒绝删除分支
     expect(mockedDeleteBranch).not.toHaveBeenCalled();
+    // 应提示用户分支已保留
+    expect(mockedPrintHint).toHaveBeenCalledWith('已保留本地分支，可稍后使用 git branch -D <分支名> 手动删除');
   });
 
   it('-b 指定不存在的分支时 resolveTargetWorktrees 抛出错误', async () => {

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

@@ -28,6 +28,11 @@ vi.mock('../../../src/constants/index.js', () => ({
     INCREMENTAL_VALIDATE_SUCCESS: (branch: string) => `✓ 增量验证 ${branch}`,
     INCREMENTAL_VALIDATE_FALLBACK: '降级为全量模式',
     DESTRUCTIVE_OP_CANCELLED: '已取消操作',
+    VALIDATE_RUN_START: (cmd: string) => `正在执行命令: ${cmd}`,
+    VALIDATE_RUN_SUCCESS: (cmd: string) => `✓ 命令执行完成: ${cmd}`,
+    VALIDATE_RUN_FAILED: (cmd: string, code: number) => `✗ 命令失败: ${cmd}，退出码: ${code}`,
+    VALIDATE_RUN_ERROR: (cmd: string, msg: string) => `✗ 命令出错: ${msg}`,
+    SEPARATOR: '────',
   },
 }));
 
@@ -71,6 +76,9 @@ vi.mock('../../../src/utils/index.js', () => ({
   printWarning: vi.fn(),
   printInfo: vi.fn(),
   resolveTargetWorktree: vi.fn(),
+  runCommandInherited: vi.fn(),
+  printError: vi.fn(),
+  printSeparator: vi.fn(),
 }));
 
 import { registerValidateCommand } from '../../../src/commands/validate.js';
@@ -105,6 +113,9 @@ import {
   gitApplyCachedCheck,
   gitApplyCachedFromStdin,
   printWarning,
+  runCommandInherited,
+  printError,
+  printSeparator,
 } from '../../../src/utils/index.js';
 
 const mockedGetProjectName = vi.mocked(getProjectName);
@@ -137,6 +148,9 @@ const mockedGitDiffTree = vi.mocked(gitDiffTree);
 const mockedGitApplyCachedCheck = vi.mocked(gitApplyCachedCheck);
 const mockedGitApplyCachedFromStdin = vi.mocked(gitApplyCachedFromStdin);
 const mockedPrintWarning = vi.mocked(printWarning);
+const mockedRunCommandInherited = vi.mocked(runCommandInherited);
+const mockedPrintError = vi.mocked(printError);
+const mockedPrintSeparator = vi.mocked(printSeparator);
 
 const worktree = { path: '/path/feature', branch: 'feature' };
 
@@ -171,6 +185,9 @@ beforeEach(() => {
   mockedGitApplyCachedCheck.mockReset();
   mockedGitApplyCachedFromStdin.mockReset();
   mockedPrintWarning.mockReset();
+  mockedRunCommandInherited.mockReset();
+  mockedPrintError.mockReset();
+  mockedPrintSeparator.mockReset();
 });
 
 describe('registerValidateCommand', () => {
@@ -380,3 +397,122 @@ describe('增量 validate', () => {
     expect(mockedPrintSuccess).toHaveBeenCalled();
   });
 });
+
+describe('--run 选项', () => {
+  /** 设置首次 validate 成功的公共 mock */
+  function setupSuccessfulFirstValidate(): void {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedHasLocalCommits.mockReturnValue(true);
+    mockedHasSnapshot.mockReturnValue(false);
+    mockedGitDiffBinaryAgainstBranch.mockReturnValue(Buffer.from('diff'));
+    mockedGitWriteTree.mockReturnValue('treehash');
+    mockedGetHeadCommitHash.mockReturnValue('headhash');
+  }
+
+  /** 构造 spawnSync 返回值的辅助函数 */
+  function createSpawnResult(overrides: { status?: number | null; error?: Error }) {
+    return {
+      pid: 0,
+      output: [],
+      stdout: Buffer.alloc(0),
+      stderr: Buffer.alloc(0),
+      status: overrides.status ?? null,
+      signal: null,
+      error: overrides.error,
+    };
+  }
+
+  it('validate 成功后执行 --run 指定的命令', async () => {
+    setupSuccessfulFirstValidate();
+    mockedRunCommandInherited.mockReturnValue(createSpawnResult({ status: 0 }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'npm test'], { from: 'user' });
+
+    expect(mockedRunCommandInherited).toHaveBeenCalledWith('npm test', { cwd: '/repo' });
+    expect(mockedPrintSuccess).toHaveBeenCalledTimes(2);
+  });
+
+  it('--run 命令失败时输出错误信息但不抛异常', async () => {
+    setupSuccessfulFirstValidate();
+    mockedRunCommandInherited.mockReturnValue(createSpawnResult({ status: 1 }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '--run', 'npm test'], { from: 'user' });
+
+    expect(mockedRunCommandInherited).toHaveBeenCalledWith('npm test', { cwd: '/repo' });
+    expect(mockedPrintError).toHaveBeenCalled();
+  });
+
+  it('--run 命令进程启动失败时输出错误信息', async () => {
+    setupSuccessfulFirstValidate();
+    mockedRunCommandInherited.mockReturnValue(createSpawnResult({ error: new Error('spawn ENOENT') }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'nonexistent'], { from: 'user' });
+
+    expect(mockedPrintError).toHaveBeenCalled();
+    // validate 成功 + run 出错，printSuccess 只被调用 1 次（validate 成功）
+    expect(mockedPrintSuccess).toHaveBeenCalledTimes(1);
+  });
+
+  it('未传 --run 时不执行任何命令', async () => {
+    setupSuccessfulFirstValidate();
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature'], { from: 'user' });
+
+    expect(mockedRunCommandInherited).not.toHaveBeenCalled();
+  });
+
+  it('--clean 与 --run 同时传入时只执行 clean 不执行 run', async () => {
+    mockedGetConfigValue.mockReturnValue(false);
+    mockedIsWorkingDirClean.mockReturnValue(true);
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '--clean', '-b', 'feature', '-r', 'npm test'], { from: 'user' });
+
+    expect(mockedRemoveSnapshot).toHaveBeenCalled();
+    expect(mockedRunCommandInherited).not.toHaveBeenCalled();
+  });
+
+  it('增量 validate 成功后也执行 --run 命令', async () => {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedHasLocalCommits.mockReturnValue(true);
+    mockedHasSnapshot.mockReturnValue(true);
+    mockedReadSnapshot.mockReturnValue({ treeHash: 'oldtree', headCommitHash: 'headhash' });
+    mockedGetHeadCommitHash.mockReturnValue('headhash');
+    mockedGitDiffBinaryAgainstBranch.mockReturnValue(Buffer.from('diff'));
+    mockedGitWriteTree.mockReturnValue('newtree');
+    mockedRunCommandInherited.mockReturnValue(createSpawnResult({ status: 0 }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'npm test'], { from: 'user' });
+
+    expect(mockedRunCommandInherited).toHaveBeenCalledWith('npm test', { cwd: '/repo' });
+  });
+
+  it('目标分支无变更时不执行 --run', async () => {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedHasLocalCommits.mockReturnValue(false);
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'npm test'], { from: 'user' });
+
+    expect(mockedRunCommandInherited).not.toHaveBeenCalled();
+  });
+});