clawt 3.1.3 → 3.2.0

package/dist/index.js

@@ -180,6 +180,8 @@ var VALIDATE_MESSAGES = {
   \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 检测到目标 worktree 无新变更 */
+  INCREMENTAL_VALIDATE_NO_CHANGES: (branch) => `\u5206\u652F ${branch} \u81EA\u4E0A\u6B21 validate \u4EE5\u6765\u6CA1\u6709\u65B0\u7684\u53D8\u66F4\uFF0C\u5DF2\u6062\u590D\u5230\u4E0A\u6B21\u9A8C\u8BC1\u72B6\u6001`,
   /** validate 状态已清理 */
   VALIDATE_CLEANED: (branch) => `\u2713 \u5206\u652F ${branch} \u7684 validate \u72B6\u6001\u5DF2\u6E05\u7406`,
   /** validate patch apply 失败，提示用户同步主分支 */
@@ -1672,6 +1674,9 @@ function getSnapshotPath(projectName, branchName) {
 function getSnapshotHeadPath(projectName, branchName) {
   return join6(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
 }
+function getSnapshotStagedPath(projectName, branchName) {
+  return join6(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.staged`);
+}
 function hasSnapshot(projectName, branchName) {
   return existsSync8(getSnapshotPath(projectName, branchName));
 }
@@ -1684,23 +1689,28 @@ function getSnapshotModifiedTime(projectName, branchName) {
 function readSnapshot(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const headPath = getSnapshotHeadPath(projectName, branchName);
+  const stagedPath = getSnapshotStagedPath(projectName, branchName);
   logger.debug(`\u8BFB\u53D6 validate \u5FEB\u7167: ${snapshotPath}`);
   const treeHash = existsSync8(snapshotPath) ? readFileSync3(snapshotPath, "utf-8").trim() : "";
   const headCommitHash = existsSync8(headPath) ? readFileSync3(headPath, "utf-8").trim() : "";
-  return { treeHash, headCommitHash };
+  const stagedTreeHash = existsSync8(stagedPath) ? readFileSync3(stagedPath, "utf-8").trim() : "";
+  return { treeHash, headCommitHash, stagedTreeHash };
 }
-function writeSnapshot(projectName, branchName, treeHash, headCommitHash) {
+function writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash = "") {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const headPath = getSnapshotHeadPath(projectName, branchName);
+  const stagedPath = getSnapshotStagedPath(projectName, branchName);
   const snapshotDir = join6(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   writeFileSync3(snapshotPath, treeHash, "utf-8");
   writeFileSync3(headPath, headCommitHash, "utf-8");
-  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}, ${headPath}`);
+  writeFileSync3(stagedPath, stagedTreeHash, "utf-8");
+  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}, ${headPath}, ${stagedPath}`);
 }
 function removeSnapshot(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const headPath = getSnapshotHeadPath(projectName, branchName);
+  const stagedPath = getSnapshotStagedPath(projectName, branchName);
   if (existsSync8(snapshotPath)) {
     unlinkSync(snapshotPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
@@ -1709,6 +1719,10 @@ function removeSnapshot(projectName, branchName) {
     unlinkSync(headPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${headPath}`);
   }
+  if (existsSync8(stagedPath)) {
+    unlinkSync(stagedPath);
+    logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${stagedPath}`);
+  }
 }
 function getProjectSnapshotBranches(projectName) {
   const projectDir = join6(VALIDATE_SNAPSHOTS_DIR, projectName);
@@ -2968,6 +2982,145 @@ async function checkForUpdates(currentVersion) {
   }
 }
 
+// src/utils/validate-runner.ts
+function executeSingleCommand(command, mainWorktreePath) {
+  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));
+  }
+}
+function reportParallelResults(results) {
+  printSeparator();
+  const successCount = results.filter((r) => r.exitCode === 0 && !r.error).length;
+  const failedCount = results.length - successCount;
+  for (const result of results) {
+    if (result.error) {
+      printError(MESSAGES.VALIDATE_PARALLEL_CMD_ERROR(result.command, result.error));
+    } else if (result.exitCode === 0) {
+      printSuccess(MESSAGES.VALIDATE_PARALLEL_CMD_SUCCESS(result.command));
+    } else {
+      printError(MESSAGES.VALIDATE_PARALLEL_CMD_FAILED(result.command, result.exitCode));
+    }
+  }
+  if (failedCount === 0) {
+    printSuccess(MESSAGES.VALIDATE_PARALLEL_RUN_ALL_SUCCESS(results.length));
+  } else {
+    printError(MESSAGES.VALIDATE_PARALLEL_RUN_SUMMARY(successCount, failedCount));
+  }
+}
+async function executeParallelCommands(commands, mainWorktreePath) {
+  printInfo(MESSAGES.VALIDATE_PARALLEL_RUN_START(commands.length));
+  for (let i = 0; i < commands.length; i++) {
+    printInfo(MESSAGES.VALIDATE_PARALLEL_CMD_START(i + 1, commands.length, commands[i]));
+  }
+  printSeparator();
+  const results = await runParallelCommands(commands, { cwd: mainWorktreePath });
+  reportParallelResults(results);
+}
+async function executeRunCommand(command, mainWorktreePath) {
+  printInfo("");
+  const commands = parseParallelCommands(command);
+  if (commands.length <= 1) {
+    executeSingleCommand(commands[0] || command, mainWorktreePath);
+  } else {
+    await executeParallelCommands(commands, mainWorktreePath);
+  }
+}
+
+// src/utils/validate-core.ts
+function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted) {
+  let didTempCommit = false;
+  try {
+    if (hasUncommitted) {
+      gitAddAll(targetWorktreePath);
+      gitCommit("clawt:temp-commit-for-validate", targetWorktreePath);
+      didTempCommit = true;
+    }
+    const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
+    if (patch.length > 0) {
+      try {
+        gitApplyFromStdin(patch, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`patch apply \u5931\u8D25: ${error}`);
+        printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
+        return { success: false };
+      }
+    }
+    return { success: true };
+  } finally {
+    if (didTempCommit) {
+      try {
+        gitResetSoft(1, targetWorktreePath);
+      } catch (error) {
+        logger.error(`\u64A4\u9500\u4E34\u65F6 commit \u5931\u8D25: ${error}`);
+      }
+      try {
+        gitRestoreStaged(targetWorktreePath);
+      } catch (error) {
+        logger.error(`\u6062\u590D\u6682\u5B58\u533A\u5931\u8D25: ${error}`);
+      }
+    }
+  }
+}
+function computeCurrentTreeHash(mainWorktreePath) {
+  gitAddAll(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  return treeHash;
+}
+function saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName, stagedTreeHash = "") {
+  gitAddAll(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  const headCommitHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash);
+  return treeHash;
+}
+function loadOldSnapshotToStage(oldTreeHash, oldHeadCommitHash, currentHeadCommitHash, mainWorktreePath) {
+  try {
+    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
+      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
+      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
+      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
+        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
+        const stagedTreeHash = gitWriteTree(mainWorktreePath);
+        return { success: true, stagedTreeHash };
+      } else if (oldChangePatch.length > 0) {
+        logger.warn("\u65E7\u53D8\u66F4 patch \u4E0E\u5F53\u524D HEAD \u51B2\u7A81\uFF0C\u964D\u7EA7\u4E3A\u5168\u91CF\u6A21\u5F0F");
+        return { success: false, stagedTreeHash: "" };
+      }
+      return { success: true, stagedTreeHash: "" };
+    } else {
+      gitReadTree(oldTreeHash, mainWorktreePath);
+      return { success: true, stagedTreeHash: oldTreeHash };
+    }
+  } catch (error) {
+    logger.warn(`\u589E\u91CF read-tree \u5931\u8D25: ${error}`);
+    return { success: false, stagedTreeHash: "" };
+  }
+}
+function switchToValidateBranch(branchName, mainWorktreePath) {
+  const validateBranchName = getValidateBranchName(branchName);
+  if (!checkBranchExists(validateBranchName)) {
+    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
+  }
+  const currentBranch = getCurrentBranch(mainWorktreePath);
+  if (currentBranch !== validateBranchName) {
+    gitCheckout(validateBranchName, mainWorktreePath);
+  }
+  return validateBranchName;
+}
+
 // src/utils/interactive-panel.ts
 import { createInterface as createInterface2 } from "readline";
 
@@ -3934,40 +4087,6 @@ function registerValidateCommand(program2) {
 async function handleDirtyMainWorktree(mainWorktreePath) {
   await handleDirtyWorkingDir(mainWorktreePath);
 }
-function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted) {
-  let didTempCommit = false;
-  try {
-    if (hasUncommitted) {
-      gitAddAll(targetWorktreePath);
-      gitCommit("clawt:temp-commit-for-validate", targetWorktreePath);
-      didTempCommit = true;
-    }
-    const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
-    if (patch.length > 0) {
-      try {
-        gitApplyFromStdin(patch, mainWorktreePath);
-      } catch (error) {
-        logger.warn(`patch apply \u5931\u8D25: ${error}`);
-        printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
-        return { success: false };
-      }
-    }
-    return { success: true };
-  } finally {
-    if (didTempCommit) {
-      try {
-        gitResetSoft(1, targetWorktreePath);
-      } catch (error) {
-        logger.error(`\u64A4\u9500\u4E34\u65F6 commit \u5931\u8D25: ${error}`);
-      }
-      try {
-        gitRestoreStaged(targetWorktreePath);
-      } catch (error) {
-        logger.error(`\u6062\u590D\u6682\u5B58\u533A\u5931\u8D25: ${error}`);
-      }
-    }
-  }
-}
 async function handlePatchApplyFailure(targetWorktreePath, branchName) {
   const confirmed = await confirmAction(MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC(branchName));
   if (!confirmed) {
@@ -3977,14 +4096,6 @@ async function handlePatchApplyFailure(targetWorktreePath, branchName) {
   printInfo(MESSAGES.VALIDATE_AUTO_SYNC_START(branchName));
   const syncResult = await executeSyncForBranch(targetWorktreePath, branchName);
 }
-function saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName) {
-  gitAddAll(mainWorktreePath);
-  const treeHash = gitWriteTree(mainWorktreePath);
-  gitRestoreStaged(mainWorktreePath);
-  const headCommitHash = getHeadCommitHash(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
-  return treeHash;
-}
 async function handleValidateClean(options) {
   validateMainWorktree();
   requireProjectConfig();
@@ -4013,11 +4124,7 @@ async function handleValidateClean(options) {
   printSuccess(MESSAGES.VALIDATE_CLEANED(branchName));
 }
 async function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  gitCheckout(validateBranchName, mainWorktreePath);
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
   if (!result.success) {
     await ensureOnMainWorkBranch(mainWorktreePath);
@@ -4028,102 +4135,42 @@ async function handleFirstValidate(targetWorktreePath, mainWorktreePath, project
   printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
 }
 async function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
-  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash, stagedTreeHash: oldStagedTreeHash } = readSnapshot(projectName, branchName);
   if (!isWorkingDirClean(mainWorktreePath)) {
     gitResetHard(mainWorktreePath);
     gitCleanForce(mainWorktreePath);
   }
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  const currentBranch = getCurrentBranch(mainWorktreePath);
-  if (currentBranch !== validateBranchName) {
-    gitCheckout(validateBranchName, mainWorktreePath);
-  }
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
   if (!result.success) {
     await ensureOnMainWorkBranch(mainWorktreePath);
     await handlePatchApplyFailure(targetWorktreePath, branchName);
     return;
   }
-  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
-  try {
-    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
-    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
-      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
-      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
-      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
-        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
-      } else if (oldChangePatch.length > 0) {
-        logger.warn("\u65E7\u53D8\u66F4 patch \u4E0E\u5F53\u524D HEAD \u51B2\u7A81\uFF0C\u964D\u7EA7\u4E3A\u5168\u91CF\u6A21\u5F0F");
-        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-        printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
-        return;
+  const newTreeHash = computeCurrentTreeHash(mainWorktreePath);
+  const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
+  const hasNewChanges = newTreeHash !== oldTreeHash || oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash;
+  if (!hasNewChanges) {
+    if (oldStagedTreeHash) {
+      try {
+        gitReadTree(oldStagedTreeHash, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`\u6062\u590D\u6682\u5B58\u533A\u5931\u8D25: ${error}`);
       }
-    } else {
-      gitReadTree(oldTreeHash, mainWorktreePath);
     }
-  } catch (error) {
-    logger.warn(`\u589E\u91CF read-tree \u5931\u8D25: ${error}`);
-    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    printInfo(MESSAGES.INCREMENTAL_VALIDATE_NO_CHANGES(branchName));
     printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
-  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
-}
-function executeSingleCommand(command, mainWorktreePath) {
-  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));
+  const stageResult = loadOldSnapshotToStage(oldTreeHash, oldHeadCommitHash, currentHeadCommitHash, mainWorktreePath);
+  if (!stageResult.success) {
+    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, "");
+    printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
-  const exitCode = result.status ?? 1;
-  if (exitCode === 0) {
-    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
-  } else {
-    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
-  }
-}
-function reportParallelResults(results) {
-  printSeparator();
-  const successCount = results.filter((r) => r.exitCode === 0 && !r.error).length;
-  const failedCount = results.length - successCount;
-  for (const result of results) {
-    if (result.error) {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_ERROR(result.command, result.error));
-    } else if (result.exitCode === 0) {
-      printSuccess(MESSAGES.VALIDATE_PARALLEL_CMD_SUCCESS(result.command));
-    } else {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_FAILED(result.command, result.exitCode));
-    }
-  }
-  if (failedCount === 0) {
-    printSuccess(MESSAGES.VALIDATE_PARALLEL_RUN_ALL_SUCCESS(results.length));
-  } else {
-    printError(MESSAGES.VALIDATE_PARALLEL_RUN_SUMMARY(successCount, failedCount));
-  }
-}
-async function executeParallelCommands(commands, mainWorktreePath) {
-  printInfo(MESSAGES.VALIDATE_PARALLEL_RUN_START(commands.length));
-  for (let i = 0; i < commands.length; i++) {
-    printInfo(MESSAGES.VALIDATE_PARALLEL_CMD_START(i + 1, commands.length, commands[i]));
-  }
-  printSeparator();
-  const results = await runParallelCommands(commands, { cwd: mainWorktreePath });
-  reportParallelResults(results);
-}
-async function executeRunCommand(command, mainWorktreePath) {
-  printInfo("");
-  const commands = parseParallelCommands(command);
-  if (commands.length <= 1) {
-    executeSingleCommand(commands[0] || command, mainWorktreePath);
-  } else {
-    await executeParallelCommands(commands, mainWorktreePath);
-  }
+  writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, stageResult.stagedTreeHash);
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
 function resolveRunCommand(optionRun) {
   if (optionRun) {

package/dist/postinstall.js

@@ -171,6 +171,8 @@ var VALIDATE_MESSAGES = {
   \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 检测到目标 worktree 无新变更 */
+  INCREMENTAL_VALIDATE_NO_CHANGES: (branch) => `\u5206\u652F ${branch} \u81EA\u4E0A\u6B21 validate \u4EE5\u6765\u6CA1\u6709\u65B0\u7684\u53D8\u66F4\uFF0C\u5DF2\u6062\u590D\u5230\u4E0A\u6B21\u9A8C\u8BC1\u72B6\u6001`,
   /** validate 状态已清理 */
   VALIDATE_CLEANED: (branch) => `\u2713 \u5206\u652F ${branch} \u7684 validate \u72B6\u6001\u5DF2\u6E05\u7406`,
   /** validate patch apply 失败，提示用户同步主分支 */

package/docs/spec.md

@@ -254,6 +254,7 @@ async function interactiveConfigEditor<T extends object>(
 │   └── <project-name>/                  # 以项目名分组
 │       ├── <branchName>.tree            # 每个分支一个 tree hash 快照文件（存储 git tree 对象的 hash）
 │       ├── <branchName>.head            # 每个分支一个 HEAD commit hash 快照文件（存储快照时验证分支的 HEAD commit hash）
+│       ├── <branchName>.staged          # 每个分支一个 staged tree hash 快照文件（存储 validate 结束时暂存区对应的 tree hash，用于无变更时恢复）
 │       └── ...
 ├── projects/<project-name>/             # 项目级配置目录
 │   └── config.json                      # 项目级配置（含 clawtMainWorkBranch）

package/docs/validate.md

@@ -30,7 +30,7 @@ validate 不再在主工作分支上直接 apply patch，而是先切换到目
 
 **快照机制：**
 
-validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），同时将验证分支的 HEAD commit hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.head`），用于增量 validate 时对齐基准。当再次执行 validate 时，如果验证分支 HEAD 未变化（正常情况），通过 `git read-tree` 将上次快照的 tree 对象载入暂存区；如果验证分支 HEAD 已变化（sync 后重建了验证分支），则将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容。最终用户可通过 `git diff` 查看两次 validate 之间的增量差异。
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），同时将验证分支的 HEAD commit hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.head`），以及 validate 结束时暂存区对应的 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.staged`），用于增量 validate 时对齐基准和无变更恢复。当再次执行 validate 时，先计算当前变更的 tree hash 与旧快照对比：如果没有新变更（tree hash 和 HEAD 均未变化），直接通过 `git read-tree` 恢复上次 validate 结束时的暂存区状态，跳过后续步骤；如果有新变更，则继续执行暂存区载入流程——如果验证分支 HEAD 未变化（正常情况），通过 `git read-tree` 将上次快照的 tree 对象载入暂存区；如果验证分支 HEAD 已变化（sync 后重建了验证分支），则将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容。最终用户可通过 `git diff` 查看两次 validate 之间的增量差异。
 
 **运行流程：**
 
@@ -289,7 +289,7 @@ clawt validate -b feature-scheme-1 -r "pnpm test & pnpm build"
 
 ##### 步骤 1：读取旧快照
 
-在清空主 worktree 之前，读取上次保存的快照 tree hash 及当时的 HEAD commit hash。
+在清空主 worktree 之前，读取上次保存的快照 tree hash、当时的 HEAD commit hash 和暂存区 tree hash（`stagedTreeHash`）。
 
 ##### 步骤 2：确保主 worktree 干净
 
@@ -307,9 +307,27 @@ git checkout clawt-validate-<branchName>
 
 通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 4）。如果 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
 
-##### 步骤 5：保存最新快照为 git tree 对象
+##### 步骤 5：检测是否有新变更
 
-将最新全量变更保存为新的 tree 对象（覆盖旧快照），同时记录验证分支的 HEAD commit hash（流程同首次 validate 的步骤 5）。
+计算当前工作目录变更的 tree hash（`git add . → git write-tree → git restore --staged .`），并与旧快照的 tree hash 及 HEAD commit hash 对比：
+
+```bash
+# 计算当前变更的 tree hash
+git add .
+git write-tree  # → newTreeHash
+git restore --staged .
+
+# 获取当前 HEAD
+git rev-parse HEAD  # → currentHeadCommitHash
+
+# 判断是否有新变更
+hasNewChanges = (newTreeHash !== oldTreeHash) || (oldHeadCommitHash !== currentHeadCommitHash)
+```
+
+- **无新变更**（tree hash 和 HEAD 均未变化）→ 不更新快照，直接通过 `git read-tree <oldStagedTreeHash>` 恢复上次 validate 结束时的暂存区状态，输出提示后返回
+- **有新变更** → 继续步骤 6
+
+> 无变更检测避免了重复 validate 时不必要的快照更新和暂存区重载操作。恢复上次暂存区状态后，用户看到的 `git diff` 结果与上次 validate 结束时完全一致。
 
 ##### 步骤 6：将旧变更状态载入暂存区
 
@@ -323,8 +341,8 @@ git checkout clawt-validate-<branchName>
 git read-tree <旧 tree hash>
 ```
 
-- **读取成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
-- **读取失败**（tree 对象可能被 git gc 回收）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
+- **读取成功** → 记录 `newStagedTreeHash = oldTreeHash`，结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
+- **读取失败**（tree 对象可能被 git gc 回收）→ 降级为全量模式，写入快照（`stagedTreeHash` 为空）后返回，暂存区保持为空，等同于首次 validate 的结果
 
 > 这是最常见的路径。相比重构前，正常情况不再需要处理 HEAD 变化的复杂逻辑，代码路径更简单、更可靠。
 
@@ -344,25 +362,48 @@ git apply --cached --check < patch
 
 # 无冲突：apply --cached 到当前 HEAD 暂存区
 git apply --cached < patch
+
+# 记录暂存区的 tree hash
+git write-tree  # → newStagedTreeHash
 ```
 
 - **patch 为空**（旧变更为空）→ 暂存区保持干净
-- **无冲突** → apply --cached 到当前 HEAD 暂存区，结果与正常情况一致
-- **有冲突** → 降级为全量模式（暂存区保持为空），等同于首次 validate 的结果
+- **无冲突** → apply --cached 到当前 HEAD 暂存区，通过 `git write-tree` 记录 `newStagedTreeHash`，结果与正常情况一致
+- **有冲突** → 降级为全量模式（暂存区保持为空），写入快照（`stagedTreeHash` 为空）后返回
 
-##### 步骤 7：输出成功提示
+##### 步骤 7：写入新快照
+
+将步骤 5 计算的 `newTreeHash`、当前 HEAD commit hash 和步骤 6 记录的 `newStagedTreeHash` 写入快照文件，供下次 validate 使用：
+
+```bash
+# 写入 ~/.clawt/validate-snapshots/<project>/<branchName>.tree
+echo <newTreeHash>
+
+# 写入 ~/.clawt/validate-snapshots/<project>/<branchName>.head
+echo <currentHeadCommitHash>
+
+# 写入 ~/.clawt/validate-snapshots/<project>/<branchName>.staged
+echo <newStagedTreeHash>
+```
+
+> `stagedTreeHash` 记录了 validate 结束时暂存区的完整状态。下次 validate 如果检测到无新变更，可直接通过此值恢复暂存区，避免重复执行 read-tree 或 apply --cached 流程。
+
+##### 步骤 8：输出成功提示
 
 ```
 # 增量模式成功
 ✓ 已将分支 feature-scheme-1 的最新变更应用到主 worktree（增量模式）
   暂存区 = 上次快照，工作目录 = 最新变更
 
+# 增量无变更
+分支 feature-scheme-1 自上次 validate 以来没有新的变更，已恢复到上次验证状态
+
 # 增量降级为全量
 ✓ 已切换到验证分支 clawt-validate-feature-scheme-1 并应用分支 feature-scheme-1 的变更
   可以开始验证了
 ```
 
-##### 步骤 8：执行 `--run` 命令（可选）
+##### 步骤 9：执行 `--run` 命令（可选）
 
 与首次 validate 的步骤 7 相同，增量 validate 成功后也会执行 `-r, --run` 指定的命令（或从项目配置 `validateRunCommand` 读取的默认命令）。
 

package/package.json

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