clawt 1.2.0 → 1.3.0

package/.claude/agent-memory/docs-sync-updater/MEMORY.md

@@ -29,11 +29,13 @@
 ## 关键约定
 - `autoDeleteBranch` 配置项影响三处：remove 命令、merge 命令、run 中断清理
 - merge 的清理确认在 merge 操作之前询问（避免交互中断），但清理在 merge 成功后执行
+- merge 成功后自动清理对应的 validate 快照（hasSnapshot + removeSnapshot）
 - run 的中断清理在所有子进程退出后执行
 - 文档中文风格，技术术语保留英文（worktree, merge, branch, SIGINT 等）
 - cleanupWorktrees 是 merge 和 run 共用的公共清理函数（在 src/utils/worktree.ts）
 - `launchInteractiveClaude` 是 run（交互式模式）和 resume 共用的公共函数（在 src/utils/claude.ts）
 - killAllChildProcesses 是 run 专用的子进程终止函数（在 src/utils/shell.ts）
+- validate 快照管理函数在 `src/utils/validate-snapshot.ts`，被 validate 和 merge 两个命令使用
 
 ## 配置项同步检查点
 
@@ -65,3 +67,17 @@ run 命令有两种模式（自 claudeCodeCommand 特性后）：
 Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
 - `claudeCodeCommand` 配置项同时影响 run 交互式模式和 resume 命令
+
+## validate 快照机制
+
+- validate 命令支持首次/增量两种模式，通过 `hasSnapshot()` 判断
+- 快照路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`
+- 常量 `VALIDATE_SNAPSHOTS_DIR` 定义在 `src/constants/paths.ts`
+- validate 新增 `--clean` 选项（`ValidateOptions.clean?: boolean`）
+- 增量模式核心：旧 patch 应用到暂存区 + 新全量变更在工作目录 → `git diff` 可查看增量差异
+- 增量 apply 失败时自动降级为全量模式
+- shell 层新增 `execCommandWithInput()`（`execFileSync` + stdin），用于 `gitApplyCachedFromStdin()`
+- git 层新增 `gitDiffCachedBinary()`（返回 Buffer）和 `gitApplyCachedFromStdin()`
+- merge 成功后自动清理对应快照；merge 时主 worktree 脏 + 存在快照会输出警告提示
+- docs/spec.md 中 validate 章节（5.4）按 `--clean 模式`、`首次 validate`、`增量 validate` 三段描述
+- CLAUDE.md 中在 validate + merge 工作流章节用缩进列表描述两种模式

package/CLAUDE.md

@@ -55,15 +55,19 @@ run 命令有两种模式：
 
 ### validate + merge 工作流
 
-- `validate`：将目标 worktree 的变更通过 git stash 迁移到主 worktree，便于在主 worktree 中测试
-- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）
+- `validate`：将目标 worktree 的变更通过 git stash 迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
+  - **首次 validate**（无历史快照）：stash 迁移 → 保存纯净快照 patch → 结果：暂存区=空，工作目录=全量变更
+  - **增量 validate**（存在历史快照）：读取旧 patch → 清空主 worktree → stash 迁移最新变更 → 保存新快照 → 旧 patch 应用到暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
+  - `--clean` 选项：重置主 worktree + 删除对应快照文件
+  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`
+- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
 - `run` 中断清理：Ctrl+C 终止所有子进程后，根据 `autoDeleteBranch` 配置自动清理或交互式确认清理本次创建的 worktree 和分支
 
 ### 目录层级
 
 - `src/commands/` — 各命令的注册与处理逻辑
-- `src/utils/` — 工具函数（git 操作、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动）
-- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列）
+- `src/utils/` — 工具函数（git 操作、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理）
+- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录）
 - `src/types/` — TypeScript 类型定义
 - `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
 - `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）
@@ -73,6 +77,6 @@ run 命令有两种模式：
 - 所有命令执行前都会调用 `validateMainWorktree()` 确保在主 worktree 根目录（`git rev-parse --git-common-dir === ".git"`）
 - Worktree 统一存放在 `~/.clawt/worktrees/<projectName>/` 下
 - 全局配置文件 `~/.clawt/config.json`，postinstall 时自动创建/合并，包含 `autoDeleteBranch`（是否自动删除分支）、`claudeCodeCommand`（Claude Code CLI 启动指令，用于 `run` 和 `resume` 的交互式界面）、`autoPullPush`（merge 后是否自动 pull/push）三个配置项。配置项以 `CONFIG_DEFINITIONS` 为单一数据源，`DEFAULT_CONFIG` 和 `CONFIG_DESCRIPTIONS` 均从中派生
-- shell 命令执行有同步（`execCommand` → `execSync`）和异步（`spawnProcess` → `spawn`）两种方式
+- shell 命令执行有同步（`execCommand` → `execSync`）、异步（`spawnProcess` → `spawn`）和同步带 stdin（`execCommandWithInput` → `execFileSync`）三种方式
 - 项目为纯 ESM（`"type": "module"`），模块导入需带 `.js` 后缀
 - 分支名特殊字符会被 `sanitizeBranchName()` 自动清理

package/README.md

@@ -93,17 +93,27 @@ clawt resume -b feature-login
 ### `clawt validate` — 在主 worktree 验证分支变更
 
 ```bash
-clawt validate -b <branchName>
+clawt validate -b <branchName> [--clean]
 ```
 
 | 参数 | 必填 | 说明 |
 | ---- | ---- | ---- |
 | `-b` | 是 | 要验证的分支名 |
+| `--clean` | 否 | 清理 validate 状态（重置主 worktree 并删除快照） |
 
 将目标 worktree 的变更通过 `git stash` 迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。
 
+支持增量模式：首次 validate 后会自动保存快照，再次 validate 同一分支时会将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
+
 ```bash
+# 首次验证
+clawt validate -b feature-scheme-1
+
+# 再次验证（增量模式，可通过 git diff 查看增量差异）
 clawt validate -b feature-scheme-1
+
+# 清理 validate 状态
+clawt validate -b feature-scheme-1 --clean
 ```
 
 ### `clawt merge` — 合并分支到主 worktree

package/dist/index.js

@@ -13,6 +13,7 @@ var CLAWT_HOME = join(homedir(), ".clawt");
 var CONFIG_PATH = join(CLAWT_HOME, "config.json");
 var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
+var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 
 // src/constants/branch.ts
 var INVALID_BRANCH_CHARS = /[\/\\.\s~:*?[\]^]+/g;
@@ -81,7 +82,18 @@ var MESSAGES = {
   /** 创建数量参数无效 */
   INVALID_COUNT: (value) => `\u65E0\u6548\u7684\u521B\u5EFA\u6570\u91CF: "${value}"\uFF0C\u8BF7\u8F93\u5165\u6B63\u6574\u6570`,
   /** worktree 状态获取失败 */
-  WORKTREE_STATUS_UNAVAILABLE: "(\u72B6\u6001\u4E0D\u53EF\u7528)"
+  WORKTREE_STATUS_UNAVAILABLE: "(\u72B6\u6001\u4E0D\u53EF\u7528)",
+  /** 增量 validate 成功提示 */
+  INCREMENTAL_VALIDATE_SUCCESS: (branch) => `\u2713 \u5DF2\u5C06\u5206\u652F ${branch} \u7684\u6700\u65B0\u53D8\u66F4\u5E94\u7528\u5230\u4E3B worktree\uFF08\u589E\u91CF\u6A21\u5F0F\uFF09
+  \u6682\u5B58\u533A = \u4E0A\u6B21\u5FEB\u7167\uFF0C\u5DE5\u4F5C\u76EE\u5F55 = \u6700\u65B0\u53D8\u66F4`,
+  /** 增量 validate 降级为全量模式提示 */
+  INCREMENTAL_VALIDATE_FALLBACK: "\u589E\u91CF\u5BF9\u6BD4\u5931\u8D25\uFF0C\u5DF2\u964D\u7EA7\u4E3A\u5168\u91CF\u6A21\u5F0F",
+  /** validate 状态已清理 */
+  VALIDATE_CLEANED: (branch) => `\u2713 \u5206\u652F ${branch} \u7684 validate \u72B6\u6001\u5DF2\u6E05\u7406`,
+  /** 增量 validate 检测到脏状态，即将清空 */
+  INCREMENTAL_VALIDATE_RESET: "\u68C0\u6D4B\u5230\u4E0A\u6B21 validate \u7684\u6B8B\u7559\u72B6\u6001\uFF0C\u5C06\u6E05\u7A7A\u4E3B worktree \u5E76\u91CD\u65B0\u5E94\u7528",
+  /** merge 命令检测到 validate 状态的提示 */
+  MERGE_VALIDATE_STATE_HINT: (branch) => `\u4E3B worktree \u53EF\u80FD\u5B58\u5728 validate \u6B8B\u7559\u72B6\u6001\uFF0C\u53EF\u5148\u6267\u884C clawt validate -b ${branch} --clean \u6E05\u7406`
 };
 
 // src/constants/exitCodes.ts
@@ -168,7 +180,7 @@ var logger = winston.createLogger({
 });
 
 // src/utils/shell.ts
-import { execSync, spawn } from "child_process";
+import { execSync, execFileSync, spawn } from "child_process";
 function execCommand(command, options) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ""}`);
   const result = execSync(command, {
@@ -192,9 +204,20 @@ function killAllChildProcesses(children) {
     }
   }
 }
+function execCommandWithInput(command, args, options) {
+  logger.debug(`\u6267\u884C\u547D\u4EE4(stdin): ${command} ${args.join(" ")}${options.cwd ? ` (cwd: ${options.cwd})` : ""}`);
+  const result = execFileSync(command, args, {
+    cwd: options.cwd,
+    input: options.input,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return result.trim();
+}
 
 // src/utils/git.ts
 import { basename } from "path";
+import { execSync as execSync2 } from "child_process";
 function getGitCommonDir(cwd) {
   return execCommand("git rev-parse --git-common-dir", { cwd });
 }
@@ -316,6 +339,16 @@ function getDiffStat(branchName, worktreePath, cwd) {
     deletions: committed.deletions + uncommitted.deletions
   };
 }
+function gitDiffCachedBinary(cwd) {
+  logger.debug(`\u6267\u884C\u547D\u4EE4: git diff --cached --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
+  return execSync2("git diff --cached --binary", {
+    cwd,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function gitApplyCachedFromStdin(patchContent, cwd) {
+  execCommandWithInput("git", ["apply", "--cached"], { input: patchContent, cwd });
+}
 
 // src/utils/formatter.ts
 import chalk from "chalk";
@@ -565,6 +598,35 @@ function launchInteractiveClaude(worktree) {
   }
 }
 
+// src/utils/validate-snapshot.ts
+import { join as join3 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync, readdirSync as readdirSync3, rmdirSync as rmdirSync2 } from "fs";
+function getSnapshotPath(projectName, branchName) {
+  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
+}
+function hasSnapshot(projectName, branchName) {
+  return existsSync5(getSnapshotPath(projectName, branchName));
+}
+function readSnapshot(projectName, branchName) {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  logger.debug(`\u8BFB\u53D6 validate \u5FEB\u7167: ${snapshotPath}`);
+  return readFileSync2(snapshotPath);
+}
+function writeSnapshot(projectName, branchName, patch) {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  const snapshotDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
+  ensureDir(snapshotDir);
+  writeFileSync2(snapshotPath, patch);
+  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}`);
+}
+function removeSnapshot(projectName, branchName) {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  if (existsSync5(snapshotPath)) {
+    unlinkSync(snapshotPath);
+    logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
+  }
+}
+
 // src/commands/list.ts
 import chalk2 from "chalk";
 function registerListCommand(program2) {
@@ -624,7 +686,7 @@ function handleCreate(options) {
 }
 
 // src/commands/remove.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 function registerRemoveCommand(program2) {
   program2.command("remove").description("\u79FB\u9664 worktree\uFF08\u652F\u6301\u5355\u4E2A/\u6279\u91CF/\u5168\u90E8\uFF09").option("--all", "\u79FB\u9664\u5F53\u524D\u9879\u76EE\u4E0B\u6240\u6709 worktree").option("-b, --branch <branchName>", "\u6307\u5B9A\u5206\u652F\u540D").option("-i, --index <index>", "\u6307\u5B9A\u7D22\u5F15\uFF08\u914D\u5408 -b \u4F7F\u7528\uFF09").action(async (options) => {
     await handleRemove(options);
@@ -641,7 +703,7 @@ function resolveWorktreesToRemove(options) {
   }
   if (options.index !== void 0) {
     const targetName = `${options.branch}-${options.index}`;
-    const targetPath = join3(projectDir, targetName);
+    const targetPath = join4(projectDir, targetName);
     const found = allWorktrees.find((wt) => wt.path === targetPath);
     if (!found) {
       throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(targetName));
@@ -881,11 +943,11 @@ async function handleResume(options) {
 }
 
 // src/commands/validate.ts
-import { join as join4 } from "path";
-import { existsSync as existsSync5 } from "fs";
+import { join as join5 } from "path";
+import { existsSync as existsSync6 } from "fs";
 import Enquirer2 from "enquirer";
 function registerValidateCommand(program2) {
-  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").requiredOption("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D").action(async (options) => {
+  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").requiredOption("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").action(async (options) => {
     await handleValidate(options);
   });
 }
@@ -923,24 +985,8 @@ async function handleDirtyMainWorktree(mainWorktreePath) {
     throw new ClawtError("\u5DE5\u4F5C\u533A\u4ECD\u7136\u4E0D\u5E72\u51C0\uFF0C\u8BF7\u624B\u52A8\u5904\u7406");
   }
 }
-async function handleValidate(options) {
-  validateMainWorktree();
-  const projectName = getProjectName();
-  const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join4(projectDir, options.branch);
-  logger.info(`validate \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
-  if (!existsSync5(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
-  }
-  if (!isWorkingDirClean(mainWorktreePath)) {
-    await handleDirtyMainWorktree(mainWorktreePath);
-  }
-  if (isWorkingDirClean(targetWorktreePath)) {
-    printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-    return;
-  }
-  const stashMessage = `clawt:validate:${options.branch}`;
+function migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName) {
+  const stashMessage = `clawt:validate:${branchName}`;
   gitAddAll(targetWorktreePath);
   gitStashPush(stashMessage, targetWorktreePath);
   gitStashApply(targetWorktreePath);
@@ -951,12 +997,86 @@ async function handleValidate(options) {
     throw new ClawtError(MESSAGES.STASH_CHANGED);
   }
   gitStashPop(0, mainWorktreePath);
-  printSuccess(MESSAGES.VALIDATE_SUCCESS(options.branch));
+}
+function saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName) {
+  gitAddAll(mainWorktreePath);
+  const patch = gitDiffCachedBinary(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  writeSnapshot(projectName, branchName, patch);
+  return patch;
+}
+function handleValidateClean(options) {
+  validateMainWorktree();
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+  logger.info(`validate --clean \u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+  }
+  removeSnapshot(projectName, options.branch);
+  printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
+}
+function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName) {
+  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+  printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+}
+function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName) {
+  const oldPatch = readSnapshot(projectName, branchName);
+  printInfo(MESSAGES.INCREMENTAL_VALIDATE_RESET);
+  gitResetHard(mainWorktreePath);
+  gitCleanForce(mainWorktreePath);
+  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+  const newPatch = saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+  if (oldPatch.length > 0) {
+    try {
+      gitApplyCachedFromStdin(oldPatch, mainWorktreePath);
+    } catch (error) {
+      logger.warn(`\u589E\u91CF apply \u5931\u8D25: ${error}`);
+      printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+      printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+      return;
+    }
+  }
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
+}
+async function handleValidate(options) {
+  if (options.clean) {
+    handleValidateClean(options);
+    return;
+  }
+  validateMainWorktree();
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+  const projectDir = getProjectWorktreeDir();
+  const targetWorktreePath = join5(projectDir, options.branch);
+  logger.info(`validate \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
+  if (!existsSync6(targetWorktreePath)) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
+  }
+  const isIncremental = hasSnapshot(projectName, options.branch);
+  if (isIncremental) {
+    if (isWorkingDirClean(targetWorktreePath)) {
+      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+      return;
+    }
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+  } else {
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
+    }
+    if (isWorkingDirClean(targetWorktreePath)) {
+      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+      return;
+    }
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+  }
 }
 
 // src/commands/merge.ts
-import { join as join5 } from "path";
-import { existsSync as existsSync6 } from "fs";
+import { join as join6 } from "path";
+import { existsSync as existsSync7 } from "fs";
 function registerMergeCommand(program2) {
   program2.command("merge").description("\u5408\u5E76\u67D0\u4E2A\u5DF2\u9A8C\u8BC1\u7684 worktree \u5206\u652F\u5230\u4E3B worktree").requiredOption("-b, --branch <branchName>", "\u8981\u5408\u5E76\u7684\u5206\u652F\u540D").option("-m, --message <message>", "\u63D0\u4EA4\u4FE1\u606F\uFF08\u5DE5\u4F5C\u533A\u6709\u4FEE\u6539\u65F6\u5FC5\u586B\uFF09").action(async (options) => {
     await handleMerge(options);
@@ -978,12 +1098,16 @@ async function handleMerge(options) {
   validateMainWorktree();
   const mainWorktreePath = getGitTopLevel();
   const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join5(projectDir, options.branch);
+  const targetWorktreePath = join6(projectDir, options.branch);
   logger.info(`merge \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u63D0\u4EA4\u4FE1\u606F: ${options.message ?? "(\u672A\u63D0\u4F9B)"}`);
-  if (!existsSync6(targetWorktreePath)) {
+  if (!existsSync7(targetWorktreePath)) {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
+  const projectName = getProjectName();
   if (!isWorkingDirClean(mainWorktreePath)) {
+    if (hasSnapshot(projectName, options.branch)) {
+      printWarning(MESSAGES.MERGE_VALIDATE_STATE_HINT(options.branch));
+    }
     throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
   }
   const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
@@ -1024,6 +1148,9 @@ async function handleMerge(options) {
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }
+  if (hasSnapshot(projectName, options.branch)) {
+    removeSnapshot(projectName, options.branch);
+  }
 }
 
 // src/commands/config.ts

package/dist/postinstall.js

@@ -10,6 +10,7 @@ var CLAWT_HOME = join(homedir(), ".clawt");
 var CONFIG_PATH = join(CLAWT_HOME, "config.json");
 var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
+var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 
 // src/constants/config.ts
 var CONFIG_DEFINITIONS = {

package/docs/spec.md

@@ -137,6 +137,10 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ├── logs/                                # 日志目录
 │   ├── clawt-2025-02-06.log
 │   └── ...
+├── validate-snapshots/                  # validate 快照目录
+│   └── <project-name>/                  # 以项目名分组
+│       ├── <branchName>.patch           # 每个分支一个 patch 快照文件
+│       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
         ├── <branchName>/                # n=1 时直接使用分支名
@@ -336,14 +340,15 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 **命令：**
 
 ```bash
-clawt validate -b <branchName>
+clawt validate -b <branchName> [--clean]
 ```
 
 **参数：**
 
-| 参数 | 必填 | 说明                                                                     |
-| ---- | ---- | ------------------------------------------------------------------------ |
-| `-b` | 是   | 要验证的 worktree 分支名（例如 `feature-scheme-1`）                        |
+| 参数      | 必填 | 说明                                                                     |
+| --------- | ---- | ------------------------------------------------------------------------ |
+| `-b`      | 是   | 要验证的 worktree 分支名（例如 `feature-scheme-1`）                        |
+| `--clean` | 否   | 清理 validate 状态（重置主 worktree 并删除快照）                            |
 
 > **限制：** 单次只能验证一个分支，不支持批量验证。
 
@@ -351,9 +356,24 @@ clawt validate -b <branchName>
 
 Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安装依赖耗时较长。利用 `git stash` 可以在所有 worktree 间共享的特性，将目标 worktree 的变更迁移到主 worktree 进行测试，无需重新安装依赖。
 
+**快照机制：**
+
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更保存为 patch 文件（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`）。当再次执行 validate 时，通过对比新旧快照，将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。
+
 **运行流程：**
 
-#### 步骤 1：检测主 worktree 工作区状态
+#### `--clean` 模式
+
+当指定 `--clean` 选项时，执行清理逻辑后直接返回，不进入常规 validate 流程：
+
+1. **主 worktree 校验** (2.1)
+2. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
+3. 删除对应分支的 patch 快照文件
+4. 输出清理成功提示
+
+#### 首次 validate（无历史快照）
+
+##### 步骤 1：检测主 worktree 工作区状态
 
 执行 `git status --porcelain`，判断主 worktree 是否有未提交的更改。
 
@@ -376,7 +396,7 @@ Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安
 
 执行完毕后，通过 `git status --porcelain` 再次检测状态，确保工作区干净。如果仍然不干净，报错退出。
 
-#### 步骤 2：在目标 worktree 中创建 stash
+##### 步骤 2：通过 stash 迁移目标 worktree 变更
 
 ```bash
 # 定位目标 worktree
@@ -398,13 +418,10 @@ git restore --staged .
 
 > 此步骤结束后，目标 worktree 的代码保持原样（变更仍然存在于工作区），同时变更已被记录到共享的 stash 中。
 
-#### 步骤 3：在主 worktree 应用 stash
+在主 worktree 中应用 stash：
 
 ```bash
-# 回到主 worktree
 cd <主 worktree 路径>
-
-# 校验 stash@{0} 是否为我们创建的
 git stash list
 ```
 
@@ -417,9 +434,67 @@ git stash list
 git stash pop stash@{0}
 ```
 
-#### 步骤 4：输出成功提示
+##### 步骤 3：保存纯净快照
+
+将主 worktree 工作目录的全量变更保存为 patch 文件：
+
+```bash
+git add .
+git diff --cached --binary > ~/.clawt/validate-snapshots/<project>/<branchName>.patch
+git restore --staged .
+```
+
+> 结果：暂存区=空，工作目录=全量变更。
+
+##### 步骤 4：输出成功提示
+
+```
+✓ 已将分支 feature-scheme-1 的变更应用到主 worktree
+  可以开始验证了
+```
+
+#### 增量 validate（存在历史快照）
+
+当 `~/.clawt/validate-snapshots/<project>/<branchName>.patch` 存在时，自动进入增量模式：
+
+##### 步骤 1：读取旧 patch
+
+在清空主 worktree 之前，读取上次保存的快照 patch 内容。
+
+##### 步骤 2：清空主 worktree
+
+丢弃上次 validate 留下的变更和用户手动修改：
 
+```bash
+git reset --hard
+git clean -fd
 ```
+
+##### 步骤 3：从目标 worktree 获取最新全量变更
+
+检查目标 worktree 是否有更改（无更改则退出）。通过 stash 迁移目标 worktree 的最新变更到主 worktree（流程同首次 validate 的步骤 2）。
+
+##### 步骤 4：保存最新快照
+
+将最新全量变更保存为新的 patch 文件（覆盖旧快照，流程同首次 validate 的步骤 3）。
+
+##### 步骤 5：将旧 patch 应用到暂存区
+
+```bash
+git apply --cached < <旧 patch 内容>
+```
+
+- **应用成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
+- **应用失败**（文件结构变化过大）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
+
+##### 步骤 6：输出成功提示
+
+```
+# 增量模式成功
+✓ 已将分支 feature-scheme-1 的最新变更应用到主 worktree（增量模式）
+  暂存区 = 上次快照，工作目录 = 最新变更
+
+# 增量降级为全量
 ✓ 已将分支 feature-scheme-1 的变更应用到主 worktree
   可以开始验证了
 ```
@@ -503,7 +578,9 @@ clawt merge -b <branchName> [-m <commitMessage>]
 1. **主 worktree 校验** (2.1)
 2. **主 worktree 状态检测**
    - 执行 `git status --porcelain`
-   - 如果有更改 → 提示 `主 worktree 有未提交的更改，请先处理`，退出
+   - 如果有更改：
+     - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），额外输出警告提示用户可先执行 `clawt validate -b <branchName> --clean` 清理
+     - 提示 `主 worktree 有未提交的更改，请先处理`，退出
    - 无更改 → 继续
 3. **根据目标 worktree 状态决定是否需要提交**
    - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
@@ -561,6 +638,9 @@ clawt merge -b <branchName> [-m <commitMessage>]
      ```
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
+9. **清理 validate 快照**
+   - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），自动删除该快照文件（merge 成功后快照已无意义）
+
 > **注意：** 清理确认在 merge 操作之前询问（避免 merge 成功后因交互中断而遗留未清理的 worktree），但清理操作在 merge 成功后才执行。
 
 ---

package/package.json

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

package/src/commands/merge.ts

@@ -7,6 +7,7 @@ import { MESSAGES } from '../constants/index.js';
 import type { MergeOptions } from '../types/index.js';
 import {
   validateMainWorktree,
+  getProjectName,
   getGitTopLevel,
   getProjectWorktreeDir,
   isWorkingDirClean,
@@ -17,8 +18,11 @@ import {
   gitPull,
   gitPush,
   hasLocalCommits,
+  hasSnapshot,
+  removeSnapshot,
   printSuccess,
   printInfo,
+  printWarning,
   getConfigValue,
   confirmAction,
   cleanupWorktrees,
@@ -82,8 +86,14 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
 
+  const projectName = getProjectName();
+
   // 步骤 3：主 worktree 状态检测
   if (!isWorkingDirClean(mainWorktreePath)) {
+    // 如果存在 validate 快照状态，提示用户先清理
+    if (hasSnapshot(projectName, options.branch)) {
+      printWarning(MESSAGES.MERGE_VALIDATE_STATE_HINT(options.branch));
+    }
     throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
   }
 
@@ -143,4 +153,9 @@ async function handleMerge(options: MergeOptions): Promise<void> {
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }
+
+  // 步骤 10：清理 validate 快照（merge 成功后快照已无意义）
+  if (hasSnapshot(projectName, options.branch)) {
+    removeSnapshot(projectName, options.branch);
+  }
 }

package/src/commands/validate.ts

@@ -20,9 +20,13 @@ import {
   gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
-  getStatusPorcelain,
+  gitDiffCachedBinary,
+  gitApplyCachedFromStdin,
+  hasSnapshot,
+  readSnapshot,
+  writeSnapshot,
+  removeSnapshot,
   printSuccess,
-  printError,
   printWarning,
   printInfo,
 } from '../utils/index.js';
@@ -36,13 +40,14 @@ export function registerValidateCommand(program: Command): void {
     .command('validate')
     .description('在主 worktree 验证某个 worktree 分支的变更')
     .requiredOption('-b, --branch <branchName>', '要验证的分支名')
+    .option('--clean', '清理 validate 状态（重置主 worktree 并删除快照）')
     .action(async (options: ValidateOptions) => {
       await handleValidate(options);
     });
 }
 
 /**
- * 处理主 worktree 工作区有未提交更改的情况
+ * 处理主 worktree 工作区有未提交更改的情况（首次 validate 时使用）
  * @param {string} mainWorktreePath - 主 worktree 路径
  */
 async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void> {
@@ -86,11 +91,139 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
   }
 }
 
+/**
+ * 通过 stash 将目标 worktree 的变更迁移到主 worktree
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} branchName - 分支名
+ */
+function migrateChangesViaStash(targetWorktreePath: string, mainWorktreePath: string, branchName: string): void {
+  const stashMessage = `clawt:validate:${branchName}`;
+  gitAddAll(targetWorktreePath);
+  gitStashPush(stashMessage, targetWorktreePath);
+  gitStashApply(targetWorktreePath);
+  gitRestoreStaged(targetWorktreePath);
+
+  // 在主 worktree 验证并应用 stash
+  const stashList = gitStashList(mainWorktreePath);
+  const firstLine = stashList.split('\n')[0] || '';
+
+  if (!firstLine.includes(stashMessage)) {
+    throw new ClawtError(MESSAGES.STASH_CHANGED);
+  }
+
+  gitStashPop(0, mainWorktreePath);
+}
+
+/**
+ * 保存当前主 worktree 工作目录变更为纯净快照 patch
+ * 操作序列：git add . → git diff --cached --binary → git restore --staged .
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {Buffer} 生成的 patch 内容
+ */
+function saveCurrentSnapshotPatch(mainWorktreePath: string, projectName: string, branchName: string): Buffer {
+  gitAddAll(mainWorktreePath);
+  const patch = gitDiffCachedBinary(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  writeSnapshot(projectName, branchName, patch);
+  return patch;
+}
+
+/**
+ * 处理 --clean 选项：清理 validate 状态
+ * @param {ValidateOptions} options - 命令选项
+ */
+function handleValidateClean(options: ValidateOptions): void {
+  validateMainWorktree();
+
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+
+  logger.info(`validate --clean 执行，分支: ${options.branch}`);
+
+  // 清空主 worktree
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+  }
+
+  // 删除对应的 patch 文件
+  removeSnapshot(projectName, options.branch);
+
+  printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
+}
+
+/**
+ * 首次 validate 逻辑（无历史快照）
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string): void {
+  // 通过 stash 迁移目标 worktree 变更到主 worktree
+  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+
+  // 保存纯净快照到 patch 文件
+  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+
+  // 结果：暂存区=空，工作目录=全量变更
+  printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+}
+
+/**
+ * 增量 validate 逻辑（存在历史快照）
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string): void {
+  // 步骤 1：读取旧 patch（在清空前读取）
+  const oldPatch = readSnapshot(projectName, branchName);
+
+  // 步骤 2：清空主 worktree（丢弃手动修改和上次 validate 留下的变更）
+  printInfo(MESSAGES.INCREMENTAL_VALIDATE_RESET);
+  gitResetHard(mainWorktreePath);
+  gitCleanForce(mainWorktreePath);
+
+  // 步骤 3：从目标 worktree 获取最新全量变更
+  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+
+  // 步骤 4：保存最新快照
+  const newPatch = saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+
+  // 步骤 5：将旧 patch 应用到暂存区
+  if (oldPatch.length > 0) {
+    try {
+      gitApplyCachedFromStdin(oldPatch, mainWorktreePath);
+    } catch (error) {
+      // 旧 patch 无法应用（可能文件结构变化太大），降级为全量模式
+      logger.warn(`增量 apply 失败: ${error}`);
+      printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+      // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+      printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+      return;
+    }
+  }
+
+  // 结果：暂存区=上次快照，工作目录=最新全量变更
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
+}
+
 /**
  * 执行 validate 命令的核心逻辑
  * @param {ValidateOptions} options - 命令选项
  */
 async function handleValidate(options: ValidateOptions): Promise<void> {
+  // 处理 --clean 选项
+  if (options.clean) {
+    handleValidateClean(options);
+    return;
+  }
+
   validateMainWorktree();
 
   const projectName = getProjectName();
@@ -105,33 +238,28 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
 
-  // 步骤 1：检测主 worktree 工作区状态
-  if (!isWorkingDirClean(mainWorktreePath)) {
-    await handleDirtyMainWorktree(mainWorktreePath);
-  }
+  // 判断是否为增量 validate
+  const isIncremental = hasSnapshot(projectName, options.branch);
 
-  // 步骤 2：在目标 worktree 中创建 stash
-  if (isWorkingDirClean(targetWorktreePath)) {
-    printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-    return;
-  }
+  if (isIncremental) {
+    // 增量模式：检查目标 worktree 是否有变更
+    if (isWorkingDirClean(targetWorktreePath)) {
+      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+      return;
+    }
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+  } else {
+    // 首次模式：先确保主 worktree 干净
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
+    }
 
-  const stashMessage = `clawt:validate:${options.branch}`;
-  gitAddAll(targetWorktreePath);
-  gitStashPush(stashMessage, targetWorktreePath);
-  gitStashApply(targetWorktreePath);
-  gitRestoreStaged(targetWorktreePath);
+    // 检查目标 worktree 是否有变更
+    if (isWorkingDirClean(targetWorktreePath)) {
+      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+      return;
+    }
 
-  // 步骤 3：在主 worktree 应用 stash
-  const stashList = gitStashList(mainWorktreePath);
-  const firstLine = stashList.split('\n')[0] || '';
-
-  if (!firstLine.includes(stashMessage)) {
-    throw new ClawtError(MESSAGES.STASH_CHANGED);
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
   }
-
-  gitStashPop(0, mainWorktreePath);
-
-  // 步骤 4：输出成功提示
-  printSuccess(MESSAGES.VALIDATE_SUCCESS(options.branch));
 }

package/src/constants/index.ts

@@ -1,4 +1,4 @@
-export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR } from './paths.js';
+export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR } from './paths.js';
 export { INVALID_BRANCH_CHARS } from './branch.js';
 export { MESSAGES } from './messages.js';
 export { EXIT_CODES } from './exitCodes.js';

package/src/constants/messages.ts

@@ -64,4 +64,16 @@ export const MESSAGES = {
   INVALID_COUNT: (value: string) => `无效的创建数量: "${value}"，请输入正整数`,
   /** worktree 状态获取失败 */
   WORKTREE_STATUS_UNAVAILABLE: '(状态不可用)',
+  /** 增量 validate 成功提示 */
+  INCREMENTAL_VALIDATE_SUCCESS: (branch: string) =>
+    `✓ 已将分支 ${branch} 的最新变更应用到主 worktree（增量模式）\n  暂存区 = 上次快照，工作目录 = 最新变更`,
+  /** 增量 validate 降级为全量模式提示 */
+  INCREMENTAL_VALIDATE_FALLBACK: '增量对比失败，已降级为全量模式',
+  /** validate 状态已清理 */
+  VALIDATE_CLEANED: (branch: string) => `✓ 分支 ${branch} 的 validate 状态已清理`,
+  /** 增量 validate 检测到脏状态，即将清空 */
+  INCREMENTAL_VALIDATE_RESET: '检测到上次 validate 的残留状态，将清空主 worktree 并重新应用',
+  /** merge 命令检测到 validate 状态的提示 */
+  MERGE_VALIDATE_STATE_HINT: (branch: string) =>
+    `主 worktree 可能存在 validate 残留状态，可先执行 clawt validate -b ${branch} --clean 清理`,
 } as const;

package/src/constants/paths.ts

@@ -12,3 +12,6 @@ export const LOGS_DIR = join(CLAWT_HOME, 'logs');
 
 /** worktree 统一存放目录 ~/.clawt/worktrees/ */
 export const WORKTREES_DIR = join(CLAWT_HOME, 'worktrees');
+
+/** validate 快照目录 ~/.clawt/validate-snapshots/ */
+export const VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, 'validate-snapshots');

package/src/types/command.ts

@@ -18,6 +18,8 @@ export interface RunOptions {
 export interface ValidateOptions {
   /** 要验证的分支名 */
   branch: string;
+  /** 清理 validate 状态 */
+  clean?: boolean;
 }
 
 /** merge 命令选项 */

package/src/utils/git.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path';
-import { execCommand } from './shell.js';
+import { execSync } from 'node:child_process';
+import { execCommand, execCommandWithInput } from './shell.js';
 import { logger } from '../logger/index.js';
 
 /**
@@ -296,3 +297,26 @@ export function getDiffStat(branchName: string, worktreePath: string, cwd?: stri
     deletions: committed.deletions + uncommitted.deletions,
   };
 }
+
+/**
+ * 获取暂存区相对于 HEAD 的完整 diff（含二进制文件）
+ * 注意：返回原始输出不做 trim，保留 patch 格式完整性
+ * @param {string} [cwd] - 工作目录
+ * @returns {Buffer} diff 原始输出（Buffer 格式，保留二进制数据完整性）
+ */
+export function gitDiffCachedBinary(cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff --cached --binary${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync('git diff --cached --binary', {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 将 patch 内容通过 stdin 应用到暂存区
+ * @param {Buffer} patchContent - patch 内容（Buffer 格式）
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitApplyCachedFromStdin(patchContent: Buffer, cwd?: string): void {
+  execCommandWithInput('git', ['apply', '--cached'], { input: patchContent, cwd });
+}

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { execCommand, spawnProcess, killAllChildProcesses } from './shell.js';
+export { execCommand, spawnProcess, killAllChildProcesses, execCommandWithInput } from './shell.js';
 export {
   getGitCommonDir,
   getGitTopLevel,
@@ -27,6 +27,8 @@ export {
   hasLocalCommits,
   getCommitCountAhead,
   getDiffStat,
+  gitDiffCachedBinary,
+  gitApplyCachedFromStdin,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -36,3 +38,4 @@ export { printSuccess, printError, printWarning, printInfo, printSeparator, prin
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
+export { getSnapshotPath, hasSnapshot, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';

package/src/utils/shell.ts

@@ -1,4 +1,4 @@
-import { execSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
+import { execSync, execFileSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
 import { logger } from '../logger/index.js';
 
 /**
@@ -51,3 +51,24 @@ export function killAllChildProcesses(children: ChildProcess[]): void {
     }
   }
 }
+
+/**
+ * 同步执行命令，通过 stdin 传入数据
+ * @param {string} command - 要执行的命令
+ * @param {string[]} args - 命令参数
+ * @param {object} options - 配置
+ * @param {Buffer} options.input - 通过 stdin 传入的数据（Buffer 格式，保留二进制完整性）
+ * @param {string} [options.cwd] - 工作目录
+ * @returns {string} 命令的标准输出（已 trim）
+ * @throws {Error} 命令执行失败时抛出
+ */
+export function execCommandWithInput(command: string, args: string[], options: { input: Buffer; cwd?: string }): string {
+  logger.debug(`执行命令(stdin): ${command} ${args.join(' ')}${options.cwd ? ` (cwd: ${options.cwd})` : ''}`);
+  const result = execFileSync(command, args, {
+    cwd: options.cwd,
+    input: options.input,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.trim();
+}

package/src/utils/validate-snapshot.ts

@@ -0,0 +1,89 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from 'node:fs';
+import { VALIDATE_SNAPSHOTS_DIR } from '../constants/index.js';
+import { ensureDir } from './fs.js';
+import { logger } from '../logger/index.js';
+
+/**
+ * 获取指定项目和分支的 validate 快照文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} patch 文件的绝对路径
+ */
+export function getSnapshotPath(projectName: string, branchName: string): string {
+  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
+}
+
+/**
+ * 判断指定项目和分支是否存在 validate 快照
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {boolean} 快照是否存在
+ */
+export function hasSnapshot(projectName: string, branchName: string): boolean {
+  return existsSync(getSnapshotPath(projectName, branchName));
+}
+
+/**
+ * 读取指定项目和分支的 validate 快照内容
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {Buffer} patch 文件内容（Buffer 格式，保留二进制完整性）
+ */
+export function readSnapshot(projectName: string, branchName: string): Buffer {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  logger.debug(`读取 validate 快照: ${snapshotPath}`);
+  return readFileSync(snapshotPath);
+}
+
+/**
+ * 写入 validate 快照内容（自动创建目录）
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @param {Buffer} patch - patch 内容（Buffer 格式）
+ */
+export function writeSnapshot(projectName: string, branchName: string, patch: Buffer): void {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  const snapshotDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
+  ensureDir(snapshotDir);
+  writeFileSync(snapshotPath, patch);
+  logger.info(`已保存 validate 快照: ${snapshotPath}`);
+}
+
+/**
+ * 删除指定项目和分支的 validate 快照
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+export function removeSnapshot(projectName: string, branchName: string): void {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  if (existsSync(snapshotPath)) {
+    unlinkSync(snapshotPath);
+    logger.info(`已删除 validate 快照: ${snapshotPath}`);
+  }
+}
+
+/**
+ * 删除指定项目的所有 validate 快照
+ * @param {string} projectName - 项目名
+ */
+export function removeProjectSnapshots(projectName: string): void {
+  const projectDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
+  if (!existsSync(projectDir)) {
+    return;
+  }
+
+  const files = readdirSync(projectDir);
+  for (const file of files) {
+    unlinkSync(join(projectDir, file));
+  }
+
+  // 尝试删除空目录
+  try {
+    rmdirSync(projectDir);
+  } catch {
+    // 目录非空或其他原因，忽略
+  }
+
+  logger.info(`已删除项目 ${projectName} 的所有 validate 快照`);
+}