clawt 1.3.0 → 1.4.0

package/CLAUDE.md

@@ -24,7 +24,7 @@ npm i -g .        # 本地全局安装进行测试
 
 每个命令为独立文件 `src/commands/<name>.ts`，导出 `registerXxxCommand(program)` 函数，在 `src/index.ts` 中统一注册到 Commander。命令内部逻辑封装在对应的 `handleXxx` 函数中。
 
-八个命令：`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`。
+九个命令：`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`。
 
 ### 核心流程（run 命令）
 
@@ -55,19 +55,31 @@ run 命令有两种模式：
 
 ### validate + merge 工作流
 
-- `validate`：将目标 worktree 的变更通过 git stash 迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
-  - **首次 validate**（无历史快照）：stash 迁移 → 保存纯净快照 patch → 结果：暂存区=空，工作目录=全量变更
-  - **增量 validate**（存在历史快照）：读取旧 patch → 清空主 worktree → stash 迁移最新变更 → 保存新快照 → 旧 patch 应用到暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
+- `validate`：将目标分支的全量变更（已提交 + 未提交）通过 `git diff HEAD...branch --binary` 的 patch 方式迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
+  - **首次 validate**（无历史快照）：patch 迁移全量变更 → 保存纯净快照 patch + 主分支 HEAD hash → 结果：暂存区=空，工作目录=全量变更
+  - **增量 validate**（存在历史快照）：校验主分支 HEAD 一致性（不一致则清除旧快照降级为首次模式）→ 读取旧 patch → 确保主 worktree 干净 → patch 迁移最新变更 → 保存新快照 → 旧 patch 应用到暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
   - `--clean` 选项：重置主 worktree + 删除对应快照文件
-  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`
+  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`（patch 文件）+ `<branchName>.head`（主分支 HEAD hash）
+  - 变更检测：同时检测目标 worktree 的未提交修改和已提交 commit，两者均无则提示无需验证
+  - 未提交修改处理：有未提交修改时先做临时 commit，diff 完成后通过 `git reset --soft` 撤销恢复原状
 - `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
 - `run` 中断清理：Ctrl+C 终止所有子进程后，根据 `autoDeleteBranch` 配置自动清理或交互式确认清理本次创建的 worktree 和分支
 
+### sync 命令流程
+
+1. `validateMainWorktree()` 确认在主 worktree 根目录
+2. 检查目标 worktree 是否存在
+3. 获取主分支名（`getCurrentBranch()`，不硬编码 main/master）
+4. 如果目标 worktree 有未提交变更，自动 `git add . && git commit` 保存
+5. 在目标 worktree 中执行 `git merge <mainBranch>` 合并主分支
+6. 冲突处理：有冲突时提示用户手动解决，无冲突则输出成功
+7. 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
+
 ### 目录层级
 
 - `src/commands/` — 各命令的注册与处理逻辑
-- `src/utils/` — 工具函数（git 操作、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理）
-- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录）
+- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理（含 HEAD hash 一致性校验））
+- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息）
 - `src/types/` — TypeScript 类型定义
 - `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
 - `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）

package/README.md

@@ -101,9 +101,11 @@ clawt validate -b <branchName> [--clean]
 | `-b` | 是 | 要验证的分支名 |
 | `--clean` | 否 | 清理 validate 状态（重置主 worktree 并删除快照） |
 
-将目标 worktree 的变更通过 `git stash` 迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。
+将目标 worktree 的变更通过 `git diff`（三点 diff）迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。同时检测未提交修改和已提交 commit，确保所有变更都能被捕获。
 
-支持增量模式：首次 validate 后会自动保存快照，再次 validate 同一分支时会将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
+支持增量模式：首次 validate 后会自动保存快照（patch + 主分支 HEAD hash），再次 validate 同一分支时会先校验主分支 HEAD 一致性（不一致则降级为首次模式），然后将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
+
+> **提示：** 如果 validate 时 patch apply 失败（目标分支与主分支差异过大），可先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
 ```bash
 # 首次验证
@@ -116,6 +118,23 @@ clawt validate -b feature-scheme-1
 clawt validate -b feature-scheme-1 --clean
 ```
 
+### `clawt sync` — 将主分支代码同步到目标 worktree
+
+```bash
+clawt sync -b <branchName>
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `-b` | 是 | 要同步的分支名 |
+
+将主分支最新代码合并到目标 worktree 的分支中。如果目标 worktree 有未提交的修改，会自动保存后再合并。存在冲突时会提示用户手动解决。合并成功后会自动清除该分支的 validate 快照（代码基础已变化，旧快照无效）。
+
+```bash
+# 将主分支最新代码同步到目标 worktree
+clawt sync -b feature-scheme-1
+```
+
 ### `clawt merge` — 合并分支到主 worktree
 
 ```bash

package/dist/index.js

@@ -42,8 +42,6 @@ var MESSAGES = {
   MAIN_WORKTREE_DIRTY: "\u4E3B worktree \u6709\u672A\u63D0\u4EA4\u7684\u66F4\u6539\uFF0C\u8BF7\u5148\u5904\u7406",
   /** 目标 worktree 无更改 */
   TARGET_WORKTREE_CLEAN: "\u8BE5 worktree \u7684\u5206\u652F\u4E0A\u6CA1\u6709\u4EFB\u4F55\u66F4\u6539\uFF0C\u65E0\u9700\u9A8C\u8BC1",
-  /** stash 已变更 */
-  STASH_CHANGED: "git stash list \u5DF2\u53D8\u66F4\uFF0C\u8BF7\u91CD\u65B0\u6267\u884C",
   /** validate 成功 */
   VALIDATE_SUCCESS: (branch) => `\u2713 \u5DF2\u5C06\u5206\u652F ${branch} \u7684\u53D8\u66F4\u5E94\u7528\u5230\u4E3B worktree
   \u53EF\u4EE5\u5F00\u59CB\u9A8C\u8BC1\u4E86`,
@@ -90,10 +88,21 @@ var MESSAGES = {
   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`
+  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`,
+  /** sync 自动保存未提交变更 */
+  SYNC_AUTO_COMMITTED: (branch) => `\u5DF2\u81EA\u52A8\u4FDD\u5B58 ${branch} \u5206\u652F\u7684\u672A\u63D0\u4EA4\u53D8\u66F4`,
+  /** sync 开始合并 */
+  SYNC_MERGING: (targetBranch, mainBranch) => `\u6B63\u5728\u5C06 ${mainBranch} \u5408\u5E76\u5230 ${targetBranch} ...`,
+  /** sync 成功 */
+  SYNC_SUCCESS: (targetBranch, mainBranch) => `\u2713 \u5DF2\u5C06 ${mainBranch} \u7684\u6700\u65B0\u4EE3\u7801\u540C\u6B65\u5230 ${targetBranch}`,
+  /** sync 冲突 */
+  SYNC_CONFLICT: (worktreePath) => `\u5408\u5E76\u5B58\u5728\u51B2\u7A81\uFF0C\u8BF7\u8FDB\u5165\u76EE\u6807 worktree \u624B\u52A8\u89E3\u51B3\uFF1A
+  cd ${worktreePath}
+  \u89E3\u51B3\u51B2\u7A81\u540E\u6267\u884C git add . && git merge --continue`,
+  /** validate patch apply 失败，提示用户同步主分支 */
+  VALIDATE_PATCH_APPLY_FAILED: (branch) => `\u53D8\u66F4\u8FC1\u79FB\u5931\u8D25\uFF1A\u76EE\u6807\u5206\u652F\u4E0E\u4E3B\u5206\u652F\u5DEE\u5F02\u8FC7\u5927
+  \u8BF7\u5148\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
 };
 
 // src/constants/exitCodes.ts
@@ -282,19 +291,6 @@ function gitCleanForce(cwd) {
 function gitStashPush(message, cwd) {
   execCommand(`git stash push -m "${message}"`, { cwd });
 }
-function gitStashApply(cwd) {
-  execCommand("git stash apply", { cwd });
-}
-function gitStashPop(index = 0, cwd) {
-  execCommand(`git stash pop stash@{${index}}`, { cwd });
-}
-function gitStashList(cwd) {
-  try {
-    return execCommand("git stash list", { cwd });
-  } catch {
-    return "";
-  }
-}
 function gitRestoreStaged(cwd) {
   execCommand("git restore --staged .", { cwd });
 }
@@ -349,6 +345,25 @@ function gitDiffCachedBinary(cwd) {
 function gitApplyCachedFromStdin(patchContent, cwd) {
   execCommandWithInput("git", ["apply", "--cached"], { input: patchContent, cwd });
 }
+function getCurrentBranch(cwd) {
+  return execCommand("git rev-parse --abbrev-ref HEAD", { cwd });
+}
+function getHeadCommitHash(cwd) {
+  return execCommand("git rev-parse HEAD", { cwd });
+}
+function gitDiffBinaryAgainstBranch(branchName, cwd) {
+  logger.debug(`\u6267\u884C\u547D\u4EE4: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
+  return execSync2(`git diff HEAD...${branchName} --binary`, {
+    cwd,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function gitApplyFromStdin(patchContent, cwd) {
+  execCommandWithInput("git", ["apply"], { input: patchContent, cwd });
+}
+function gitResetSoft(count = 1, cwd) {
+  execCommand(`git reset --soft HEAD~${count}`, { cwd });
+}
 
 // src/utils/formatter.ts
 import chalk from "chalk";
@@ -604,6 +619,9 @@ import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync
 function getSnapshotPath(projectName, branchName) {
   return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
 }
+function getSnapshotHeadPath(projectName, branchName) {
+  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+}
 function hasSnapshot(projectName, branchName) {
   return existsSync5(getSnapshotPath(projectName, branchName));
 }
@@ -612,11 +630,14 @@ function readSnapshot(projectName, branchName) {
   logger.debug(`\u8BFB\u53D6 validate \u5FEB\u7167: ${snapshotPath}`);
   return readFileSync2(snapshotPath);
 }
-function writeSnapshot(projectName, branchName, patch) {
+function writeSnapshot(projectName, branchName, patch, headHash) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const snapshotDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   writeFileSync2(snapshotPath, patch);
+  if (headHash) {
+    writeFileSync2(getSnapshotHeadPath(projectName, branchName), headHash, "utf-8");
+  }
   logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}`);
 }
 function removeSnapshot(projectName, branchName) {
@@ -625,6 +646,17 @@ function removeSnapshot(projectName, branchName) {
     unlinkSync(snapshotPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
   }
+  const headPath = getSnapshotHeadPath(projectName, branchName);
+  if (existsSync5(headPath)) {
+    unlinkSync(headPath);
+  }
+}
+function readSnapshotHead(projectName, branchName) {
+  const headPath = getSnapshotHeadPath(projectName, branchName);
+  if (!existsSync5(headPath)) {
+    return null;
+  }
+  return readFileSync2(headPath, "utf-8").trim();
 }
 
 // src/commands/list.ts
@@ -985,24 +1017,37 @@ async function handleDirtyMainWorktree(mainWorktreePath) {
     throw new ClawtError("\u5DE5\u4F5C\u533A\u4ECD\u7136\u4E0D\u5E72\u51C0\uFF0C\u8BF7\u624B\u52A8\u5904\u7406");
   }
 }
-function migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName) {
-  const stashMessage = `clawt:validate:${branchName}`;
-  gitAddAll(targetWorktreePath);
-  gitStashPush(stashMessage, targetWorktreePath);
-  gitStashApply(targetWorktreePath);
-  gitRestoreStaged(targetWorktreePath);
-  const stashList = gitStashList(mainWorktreePath);
-  const firstLine = stashList.split("\n")[0] || "";
-  if (!firstLine.includes(stashMessage)) {
-    throw new ClawtError(MESSAGES.STASH_CHANGED);
+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));
+        throw error;
+      }
+    }
+  } finally {
+    if (didTempCommit) {
+      gitResetSoft(1, targetWorktreePath);
+      gitRestoreStaged(targetWorktreePath);
+    }
   }
-  gitStashPop(0, mainWorktreePath);
 }
 function saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName) {
   gitAddAll(mainWorktreePath);
   const patch = gitDiffCachedBinary(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  writeSnapshot(projectName, branchName, patch);
+  const headHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, patch, headHash);
   return patch;
 }
 function handleValidateClean(options) {
@@ -1017,18 +1062,19 @@ function handleValidateClean(options) {
   removeSnapshot(projectName, options.branch);
   printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
 }
-function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName) {
-  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
+  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
   saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
   printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
 }
-function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName) {
+function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
   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 (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+  }
+  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
   if (oldPatch.length > 0) {
     try {
       gitApplyCachedFromStdin(oldPatch, mainWorktreePath);
@@ -1055,22 +1101,32 @@ async function handleValidate(options) {
   if (!existsSync6(targetWorktreePath)) {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
-  const isIncremental = hasSnapshot(projectName, options.branch);
+  const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
+  const hasCommitted = hasLocalCommits(options.branch, mainWorktreePath);
+  if (!hasUncommitted && !hasCommitted) {
+    printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+    return;
+  }
+  let isIncremental = hasSnapshot(projectName, options.branch);
   if (isIncremental) {
-    if (isWorkingDirClean(targetWorktreePath)) {
-      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-      return;
+    const savedHead = readSnapshotHead(projectName, options.branch);
+    const currentHead = getHeadCommitHash(mainWorktreePath);
+    if (!savedHead || savedHead !== currentHead) {
+      logger.info(`\u4E3B\u5206\u652F HEAD \u4E0D\u5339\u914D (${savedHead ?? "null"} \u2192 ${currentHead})\uFF0C\u6E05\u9664\u65E7\u5FEB\u7167`);
+      removeSnapshot(projectName, options.branch);
+      isIncremental = false;
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
-  } else {
+  }
+  if (isIncremental) {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    if (isWorkingDirClean(targetWorktreePath)) {
-      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-      return;
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+  } else {
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
   }
 }
 
@@ -1187,6 +1243,58 @@ function formatConfigValue(value) {
   return chalk3.cyan(String(value));
 }
 
+// src/commands/sync.ts
+import { existsSync as existsSync8 } from "fs";
+function registerSyncCommand(program2) {
+  program2.command("sync").description("\u5C06\u4E3B\u5206\u652F\u6700\u65B0\u4EE3\u7801\u540C\u6B65\u5230\u76EE\u6807 worktree").requiredOption("-b, --branch <branchName>", "\u8981\u540C\u6B65\u7684\u5206\u652F\u540D").action(async (options) => {
+    await handleSync(options);
+  });
+}
+function autoSaveChanges(worktreePath, branch) {
+  gitAddAll(worktreePath);
+  gitCommit("chore: auto-save before sync", worktreePath);
+  printInfo(MESSAGES.SYNC_AUTO_COMMITTED(branch));
+  logger.info(`\u5DF2\u81EA\u52A8\u4FDD\u5B58 ${branch} \u5206\u652F\u7684\u672A\u63D0\u4EA4\u53D8\u66F4`);
+}
+function mergeMainBranch(worktreePath, mainBranch) {
+  try {
+    gitMerge(mainBranch, worktreePath);
+    return false;
+  } catch {
+    if (hasMergeConflict(worktreePath)) {
+      return true;
+    }
+    throw new ClawtError(`\u5408\u5E76 ${mainBranch} \u5931\u8D25`);
+  }
+}
+async function handleSync(options) {
+  validateMainWorktree();
+  const { branch } = options;
+  logger.info(`sync \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${branch}`);
+  const projectWorktreeDir = getProjectWorktreeDir();
+  const targetWorktreePath = `${projectWorktreeDir}/${branch}`;
+  if (!existsSync8(targetWorktreePath)) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
+  }
+  const mainWorktreePath = getGitTopLevel();
+  const mainBranch = getCurrentBranch(mainWorktreePath);
+  if (!isWorkingDirClean(targetWorktreePath)) {
+    autoSaveChanges(targetWorktreePath, branch);
+  }
+  printInfo(MESSAGES.SYNC_MERGING(branch, mainBranch));
+  const hasConflict = mergeMainBranch(targetWorktreePath, mainBranch);
+  if (hasConflict) {
+    printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
+    return;
+  }
+  const projectName = getProjectName();
+  if (hasSnapshot(projectName, branch)) {
+    removeSnapshot(projectName, branch);
+    logger.info(`\u5DF2\u6E05\u9664\u5206\u652F ${branch} \u7684 validate \u5FEB\u7167`);
+  }
+  printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1201,6 +1309,7 @@ registerResumeCommand(program);
 registerValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
+registerSyncCommand(program);
 process.on("uncaughtException", (error) => {
   if (error instanceof ClawtError) {
     printError(error.message);

package/docs/spec.md

@@ -23,6 +23,7 @@
   - [5.9 日志系统](#59-日志系统)
   - [5.10 查看全局配置](#510-查看全局配置)
   - [5.11 在已有 Worktree 中恢复会话](#511-在已有-worktree-中恢复会话)
+  - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
 
@@ -140,6 +141,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ├── validate-snapshots/                  # validate 快照目录
 │   └── <project-name>/                  # 以项目名分组
 │       ├── <branchName>.patch           # 每个分支一个 patch 快照文件
+│       ├── <branchName>.head            # 对应的主分支 HEAD commit hash（用于增量 validate 一致性校验）
 │       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
@@ -165,6 +167,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt list`          | 列出当前项目所有 worktree                        | 5.8      |
 | `clawt config`        | 查看全局配置                                     | 5.10     |
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 交互式会话      | 5.11     |
+| `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
 
 所有命令执行前，都必须先执行**主 worktree 校验**（见 [2.1](#21-主-worktree-的定义与定位规则)）。
 
@@ -354,11 +357,11 @@ clawt validate -b <branchName> [--clean]
 
 **背景说明：**
 
-Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安装依赖耗时较长。利用 `git stash` 可以在所有 worktree 间共享的特性，将目标 worktree 的变更迁移到主 worktree 进行测试，无需重新安装依赖。
+Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安装依赖耗时较长。利用 `git diff HEAD...branch --binary`（三点 diff）可以获取目标分支自分叉点以来的全量变更（包含已提交和未提交的修改），将其作为 patch 应用到主 worktree 中进行测试，无需重新安装依赖。
 
 **快照机制：**
 
-validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更保存为 patch 文件（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`）。当再次执行 validate 时，通过对比新旧快照，将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更保存为 patch 文件（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），同时保存主分支 HEAD commit hash 到 `.head` 文件（用于一致性校验）。当再次执行 validate 时，先校验主分支 HEAD 是否与快照记录一致（不一致则清除旧快照降级为首次模式），然后通过对比新旧快照，将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。
 
 **运行流程：**
 
@@ -396,57 +399,60 @@ validate 命令引入了**快照（snapshot）机制**来支持增量对比。
 
 执行完毕后，通过 `git status --porcelain` 再次检测状态，确保工作区干净。如果仍然不干净，报错退出。
 
-##### 步骤 2：通过 stash 迁移目标 worktree 变更
+##### 步骤 2：检测目标分支变更
+
+统一检测目标 worktree 的未提交修改和已提交 commit：
 
 ```bash
-# 定位目标 worktree
+# 检测未提交修改
 cd ~/.clawt/worktrees/<project>/<branchName>
-
-# 校验目标 worktree 是否有更改
 git status --porcelain
-```
-
-- **无更改** → 输出提示 `该 worktree 的分支上没有任何更改，无需验证`，退出
-- **有更改** → 继续
 
-```bash
-git add .
-git stash push -m "clawt:validate:<branchName>"
-git stash apply
-git restore --staged .
+# 检测已提交 commit（在主 worktree 中执行）
+cd <主 worktree 路径>
+git log HEAD..<branchName> --oneline
 ```
 
-> 此步骤结束后，目标 worktree 的代码保持原样（变更仍然存在于工作区），同时变更已被记录到共享的 stash 中。
+- **两者均无** → 输出提示 `该 worktree 的分支上没有任何更改，无需验证`，退出
+- **至少有一项** → 继续
 
-在主 worktree 中应用 stash：
+##### 步骤 3：通过 patch 迁移目标分支全量变更
 
-```bash
-cd <主 worktree 路径>
-git stash list
-```
+使用三点 diff（`git diff HEAD...branchName --binary`）获取目标分支自分叉点以来的全量变更。如果目标 worktree 有未提交修改，先做临时 commit 以便 diff 能捕获全部变更，diff 完成后撤销临时 commit 恢复原状。
 
-检查 `stash@{0}` 的消息是否包含 `clawt:validate:<branchName>`：
+```bash
+# 如果有未提交修改，先临时提交
+cd ~/.clawt/worktrees/<project>/<branchName>
+git add .
+git commit -m "clawt:temp-commit-for-validate"
 
-- **不包含** → 报错：`git stash list 已变更，请重新执行`，退出
-- **包含** → 继续
+# 在主 worktree 中执行三点 diff
+cd <主 worktree 路径>
+git diff HEAD...<branchName> --binary | git apply
 
-```bash
-git stash pop stash@{0}
+# 撤销临时 commit，恢复目标 worktree 原状
+cd ~/.clawt/worktrees/<project>/<branchName>
+git reset --soft HEAD~1
+git restore --staged .
 ```
 
-##### 步骤 3：保存纯净快照
+> 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
+> 如果 patch apply 失败（目标分支与主分支差异过大），会提示用户先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
-将主 worktree 工作目录的全量变更保存为 patch 文件：
+##### 步骤 4：保存纯净快照
+
+将主 worktree 工作目录的全量变更保存为 patch 文件，同时记录主分支 HEAD commit hash：
 
 ```bash
 git add .
 git diff --cached --binary > ~/.clawt/validate-snapshots/<project>/<branchName>.patch
+git rev-parse HEAD > ~/.clawt/validate-snapshots/<project>/<branchName>.head
 git restore --staged .
 ```
 
 > 结果：暂存区=空，工作目录=全量变更。
 
-##### 步骤 4：输出成功提示
+##### 步骤 5：输出成功提示
 
 ```
 ✓ 已将分支 feature-scheme-1 的变更应用到主 worktree
@@ -457,28 +463,30 @@ git restore --staged .
 
 当 `~/.clawt/validate-snapshots/<project>/<branchName>.patch` 存在时，自动进入增量模式：
 
-##### 步骤 1：读取旧 patch
+##### 步骤 1：校验主分支 HEAD 一致性
 
-在清空主 worktree 之前，读取上次保存的快照 patch 内容。
+读取 `.head` 文件中保存的主分支 HEAD hash，与当前主分支 HEAD 对比：
 
-##### 步骤 2：清空主 worktree
+- **不一致或 `.head` 文件不存在** → 清除旧快照（`.patch` + `.head`），降级为首次 validate 模式
+- **一致** → 继续增量流程
 
-丢弃上次 validate 留下的变更和用户手动修改：
+##### 步骤 2：读取旧 patch
 
-```bash
-git reset --hard
-git clean -fd
-```
+在清空主 worktree 之前，读取上次保存的快照 patch 内容。
+
+##### 步骤 3：确保主 worktree 干净
 
-##### 步骤 3：从目标 worktree 获取最新全量变更
+如果主 worktree 有残留状态，让用户选择处理方式（同首次 validate 步骤 1 的交互），做兜底清理。
 
-检查目标 worktree 是否有更改（无更改则退出）。通过 stash 迁移目标 worktree 的最新变更到主 worktree（流程同首次 validate 的步骤 2）。
+##### 步骤 4：从目标分支获取最新全量变更
 
-##### 步骤 4：保存最新快照
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。
 
-将最新全量变更保存为新的 patch 文件（覆盖旧快照，流程同首次 validate 的步骤 3）。
+##### 步骤 5：保存最新快照
 
-##### 步骤 5：将旧 patch 应用到暂存区
+将最新全量变更保存为新的 patch 文件 + HEAD hash（覆盖旧快照，流程同首次 validate 的步骤 4）。
+
+##### 步骤 6：将旧 patch 应用到暂存区
 
 ```bash
 git apply --cached < <旧 patch 内容>
@@ -487,7 +495,7 @@ git apply --cached < <旧 patch 内容>
 - **应用成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
 - **应用失败**（文件结构变化过大）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
 
-##### 步骤 6：输出成功提示
+##### 步骤 7：输出成功提示
 
 ```
 # 增量模式成功
@@ -819,6 +827,54 @@ clawt resume -b <branchName>
 
 ---
 
+### 5.12 将主分支代码同步到目标 Worktree
+
+**命令：**
+
+```bash
+clawt sync -b <branchName>
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                  |
+| ---- | ---- | ----------------------------------------------------- |
+| `-b` | 是   | 要同步的分支名（对应已有 worktree 的分支）               |
+
+**使用场景：**
+
+当目标 worktree 的分支与主分支差异过大（例如主分支有了新的提交），导致 `clawt validate` 的 patch apply 失败时，可以通过 `clawt sync` 将主分支最新代码合并到目标 worktree，使其保持与主分支同步。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **检查目标 worktree 是否存在**：确认 `~/.clawt/worktrees/<project>/<branchName>` 目录存在
+   - 不存在 → 报错退出
+3. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
+4. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
+   - 有修改 → 自动执行 `git add . && git commit -m "chore: auto-save before sync"` 保存变更
+   - 无修改 → 跳过
+5. **在目标 worktree 中合并主分支**：
+   ```bash
+   cd ~/.clawt/worktrees/<project>/<branchName>
+   git merge <mainBranch>
+   ```
+6. **冲突处理**：
+   - **有冲突** → 输出警告，提示用户进入目标 worktree 手动解决：
+     ```
+     合并存在冲突，请进入目标 worktree 手动解决：
+       cd ~/.clawt/worktrees/<project>/<branchName>
+       解决冲突后执行 git add . && git merge --continue
+     ```
+   - **无冲突** → 继续
+7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.patch` + `.head`），自动删除（代码基础已变化，旧快照无效）
+8. **输出成功提示**：
+   ```
+   ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
+   ```
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/sync.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import type { Command } from 'commander';
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import type { SyncOptions } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getGitTopLevel,
+  getProjectName,
+  getProjectWorktreeDir,
+  isWorkingDirClean,
+  gitAddAll,
+  gitCommit,
+  gitMerge,
+  hasMergeConflict,
+  getCurrentBranch,
+  hasSnapshot,
+  removeSnapshot,
+  printSuccess,
+  printInfo,
+  printWarning,
+} from '../utils/index.js';
+
+/**
+ * 注册 sync 命令：将主分支最新代码同步到目标 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerSyncCommand(program: Command): void {
+  program
+    .command('sync')
+    .description('将主分支最新代码同步到目标 worktree')
+    .requiredOption('-b, --branch <branchName>', '要同步的分支名')
+    .action(async (options: SyncOptions) => {
+      await handleSync(options);
+    });
+}
+
+/**
+ * 自动保存目标 worktree 中的未提交变更
+ * @param {string} worktreePath - 目标 worktree 路径
+ * @param {string} branch - 分支名
+ */
+function autoSaveChanges(worktreePath: string, branch: string): void {
+  gitAddAll(worktreePath);
+  gitCommit('chore: auto-save before sync', worktreePath);
+  printInfo(MESSAGES.SYNC_AUTO_COMMITTED(branch));
+  logger.info(`已自动保存 ${branch} 分支的未提交变更`);
+}
+
+/**
+ * 在目标 worktree 中合并主分支
+ * @param {string} worktreePath - 目标 worktree 路径
+ * @param {string} mainBranch - 主分支名
+ * @returns {boolean} 是否存在冲突（true 表示有冲突）
+ */
+function mergeMainBranch(worktreePath: string, mainBranch: string): boolean {
+  try {
+    gitMerge(mainBranch, worktreePath);
+    return false;
+  } catch {
+    // 合并失败时检查是否为冲突
+    if (hasMergeConflict(worktreePath)) {
+      return true;
+    }
+    // 非冲突错误则向上抛出
+    throw new ClawtError(`合并 ${mainBranch} 失败`);
+  }
+}
+
+/**
+ * 执行 sync 命令的核心逻辑
+ * 将主分支最新代码同步到目标 worktree
+ * @param {SyncOptions} options - 命令选项
+ */
+async function handleSync(options: SyncOptions): Promise<void> {
+  validateMainWorktree();
+
+  const { branch } = options;
+  logger.info(`sync 命令执行，分支: ${branch}`);
+
+  // 检查目标 worktree 是否存在
+  const projectWorktreeDir = getProjectWorktreeDir();
+  const targetWorktreePath = `${projectWorktreeDir}/${branch}`;
+
+  if (!existsSync(targetWorktreePath)) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
+  }
+
+  // 获取主分支名（不硬编码 main/master）
+  const mainWorktreePath = getGitTopLevel();
+  const mainBranch = getCurrentBranch(mainWorktreePath);
+
+  // 检查目标 worktree 是否有未提交变更，有则自动保存
+  if (!isWorkingDirClean(targetWorktreePath)) {
+    autoSaveChanges(targetWorktreePath, branch);
+  }
+
+  // 在目标 worktree 中合并主分支
+  printInfo(MESSAGES.SYNC_MERGING(branch, mainBranch));
+  const hasConflict = mergeMainBranch(targetWorktreePath, mainBranch);
+
+  if (hasConflict) {
+    printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
+    return;
+  }
+
+  // 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
+  const projectName = getProjectName();
+  if (hasSnapshot(projectName, branch)) {
+    removeSnapshot(projectName, branch);
+    logger.info(`已清除分支 ${branch} 的 validate 快照`);
+  }
+
+  printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+}

package/src/commands/validate.ts

@@ -13,17 +13,21 @@ import {
   getProjectWorktreeDir,
   isWorkingDirClean,
   gitAddAll,
+  gitCommit,
   gitStashPush,
-  gitStashApply,
-  gitStashPop,
-  gitStashList,
   gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
   gitDiffCachedBinary,
   gitApplyCachedFromStdin,
+  gitDiffBinaryAgainstBranch,
+  gitApplyFromStdin,
+  gitResetSoft,
+  getHeadCommitHash,
+  hasLocalCommits,
   hasSnapshot,
   readSnapshot,
+  readSnapshotHead,
   writeSnapshot,
   removeSnapshot,
   printSuccess,
@@ -92,32 +96,50 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
 }
 
 /**
- * 通过 stash 将目标 worktree 的变更迁移到主 worktree
+ * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
+ * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
  * @param {string} targetWorktreePath - 目标 worktree 路径
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-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);
-  }
+function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): void {
+  let didTempCommit = false;
+
+  try {
+    // 如果有未提交修改，先做临时 commit 以便 diff 能捕获全部变更
+    if (hasUncommitted) {
+      gitAddAll(targetWorktreePath);
+      gitCommit('clawt:temp-commit-for-validate', targetWorktreePath);
+      didTempCommit = true;
+    }
 
-  gitStashPop(0, mainWorktreePath);
+    // 在主 worktree 执行三点 diff，获取目标分支自分叉点以来的全量变更
+    const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
+
+    // 应用 patch 到主 worktree 工作目录
+    if (patch.length > 0) {
+      try {
+        gitApplyFromStdin(patch, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`patch apply 失败: ${error}`);
+        printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
+        throw error;
+      }
+    }
+  } finally {
+    // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
+    if (didTempCommit) {
+      gitResetSoft(1, targetWorktreePath);
+      gitRestoreStaged(targetWorktreePath);
+    }
+  }
 }
 
 /**
  * 保存当前主 worktree 工作目录变更为纯净快照 patch
  * 操作序列：git add . → git diff --cached --binary → git restore --staged .
+ * 同时记录主分支 HEAD hash，用于增量 validate 一致性校验
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
@@ -127,7 +149,8 @@ function saveCurrentSnapshotPatch(mainWorktreePath: string, projectName: string,
   gitAddAll(mainWorktreePath);
   const patch = gitDiffCachedBinary(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  writeSnapshot(projectName, branchName, patch);
+  const headHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, patch, headHash);
   return patch;
 }
 
@@ -161,10 +184,11 @@ function handleValidateClean(options: ValidateOptions): void {
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string): void {
-  // 通过 stash 迁移目标 worktree 变更到主 worktree
-  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+  // 通过 patch 迁移目标分支全量变更到主 worktree
+  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
   // 保存纯净快照到 patch 文件
   saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
@@ -179,21 +203,24 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string): void {
+function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
   // 步骤 1：读取旧 patch（在清空前读取）
   const oldPatch = readSnapshot(projectName, branchName);
 
-  // 步骤 2：清空主 worktree（丢弃手动修改和上次 validate 留下的变更）
-  printInfo(MESSAGES.INCREMENTAL_VALIDATE_RESET);
-  gitResetHard(mainWorktreePath);
-  gitCleanForce(mainWorktreePath);
+  // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
+  // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+  }
 
-  // 步骤 3：从目标 worktree 获取最新全量变更
-  migrateChangesViaStash(targetWorktreePath, mainWorktreePath, branchName);
+  // 步骤 3：通过 patch 从目标分支获取最新全量变更
+  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
   // 步骤 4：保存最新快照
-  const newPatch = saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
 
   // 步骤 5：将旧 patch 应用到暂存区
   if (oldPatch.length > 0) {
@@ -238,28 +265,41 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
 
+  // 统一检测未提交修改 + 已提交 commit
+  const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
+  const hasCommitted = hasLocalCommits(options.branch, mainWorktreePath);
+
+  if (!hasUncommitted && !hasCommitted) {
+    printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
+    return;
+  }
+
   // 判断是否为增量 validate
-  const isIncremental = hasSnapshot(projectName, options.branch);
+  let isIncremental = hasSnapshot(projectName, options.branch);
 
+  // 主分支 HEAD 发生变化或旧快照无 .head 记录时，清除后走首次全量模式
   if (isIncremental) {
-    // 增量模式：检查目标 worktree 是否有变更
-    if (isWorkingDirClean(targetWorktreePath)) {
-      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-      return;
+    const savedHead = readSnapshotHead(projectName, options.branch);
+    const currentHead = getHeadCommitHash(mainWorktreePath);
+    if (!savedHead || savedHead !== currentHead) {
+      logger.info(`主分支 HEAD 不匹配 (${savedHead ?? 'null'} → ${currentHead})，清除旧快照`);
+      removeSnapshot(projectName, options.branch);
+      isIncremental = false;
+    }
+  }
+
+  if (isIncremental) {
+    // 增量模式：主 worktree 有残留状态时让用户选择处理方式
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
   } else {
     // 首次模式：先确保主 worktree 干净
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
 
-    // 检查目标 worktree 是否有变更
-    if (isWorkingDirClean(targetWorktreePath)) {
-      printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
-      return;
-    }
-
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch);
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
   }
 }

package/src/constants/messages.ts

@@ -23,8 +23,6 @@ export const MESSAGES = {
   MAIN_WORKTREE_DIRTY: '主 worktree 有未提交的更改，请先处理',
   /** 目标 worktree 无更改 */
   TARGET_WORKTREE_CLEAN: '该 worktree 的分支上没有任何更改，无需验证',
-  /** stash 已变更 */
-  STASH_CHANGED: 'git stash list 已变更，请重新执行',
   /** validate 成功 */
   VALIDATE_SUCCESS: (branch: string) =>
     `✓ 已将分支 ${branch} 的变更应用到主 worktree\n  可以开始验证了`,
@@ -71,9 +69,22 @@ export const MESSAGES = {
   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 清理`,
+  /** sync 自动保存未提交变更 */
+  SYNC_AUTO_COMMITTED: (branch: string) =>
+    `已自动保存 ${branch} 分支的未提交变更`,
+  /** sync 开始合并 */
+  SYNC_MERGING: (targetBranch: string, mainBranch: string) =>
+    `正在将 ${mainBranch} 合并到 ${targetBranch} ...`,
+  /** sync 成功 */
+  SYNC_SUCCESS: (targetBranch: string, mainBranch: string) =>
+    `✓ 已将 ${mainBranch} 的最新代码同步到 ${targetBranch}`,
+  /** sync 冲突 */
+  SYNC_CONFLICT: (worktreePath: string) =>
+    `合并存在冲突，请进入目标 worktree 手动解决：\n  cd ${worktreePath}\n  解决冲突后执行 git add . && git merge --continue`,
+  /** validate patch apply 失败，提示用户同步主分支 */
+  VALIDATE_PATCH_APPLY_FAILED: (branch: string) =>
+    `变更迁移失败：目标分支与主分支差异过大\n  请先执行 clawt sync -b ${branch} 同步主分支后重试`,
 } as const;

package/src/index.ts

@@ -12,6 +12,7 @@ import { registerResumeCommand } from './commands/resume.js';
 import { registerValidateCommand } from './commands/validate.js';
 import { registerMergeCommand } from './commands/merge.js';
 import { registerConfigCommand } from './commands/config.js';
+import { registerSyncCommand } from './commands/sync.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -36,6 +37,7 @@ registerResumeCommand(program);
 registerValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
+registerSyncCommand(program);
 
 // 全局未捕获异常处理
 process.on('uncaughtException', (error) => {

package/src/types/command.ts

@@ -45,3 +45,9 @@ export interface ResumeOptions {
   /** 要恢复的分支名 */
   branch: string;
 }
+
+/** sync 命令选项 */
+export interface SyncOptions {
+  /** 要同步的分支名 */
+  branch: string;
+}

package/src/types/index.ts

@@ -1,5 +1,5 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';

package/src/utils/git.ts

@@ -190,6 +190,15 @@ export function gitStashPop(index: number = 0, cwd?: string): void {
   execCommand(`git stash pop stash@{${index}}`, { cwd });
 }
 
+/**
+ * git stash drop stash@{index}
+ * @param {number} index - stash 索引
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitStashDrop(index: number = 0, cwd?: string): void {
+  execCommand(`git stash drop stash@{${index}}`, { cwd });
+}
+
 /**
  * git stash list
  * @param {string} cwd - 工作目录
@@ -320,3 +329,54 @@ export function gitDiffCachedBinary(cwd?: string): Buffer {
 export function gitApplyCachedFromStdin(patchContent: Buffer, cwd?: string): void {
   execCommandWithInput('git', ['apply', '--cached'], { input: patchContent, cwd });
 }
+
+/**
+ * 获取当前分支名
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} 当前分支名
+ */
+export function getCurrentBranch(cwd?: string): string {
+  return execCommand('git rev-parse --abbrev-ref HEAD', { cwd });
+}
+
+/**
+ * 获取当前 HEAD 的 commit hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} commit hash
+ */
+export function getHeadCommitHash(cwd?: string): string {
+  return execCommand('git rev-parse HEAD', { cwd });
+}
+
+/**
+ * 获取目标分支相对于当前分支的已提交变更（含二进制文件）
+ * 使用三点 diff（HEAD...branchName）获取自分叉点以来的变更
+ * @param {string} branchName - 目标分支名
+ * @param {string} [cwd] - 工作目录（应在主 worktree 中执行）
+ * @returns {Buffer} diff 原始输出
+ */
+export function gitDiffBinaryAgainstBranch(branchName: string, cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync(`git diff HEAD...${branchName} --binary`, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 将 patch 内容通过 stdin 应用到工作目录（不带 --cached）
+ * @param {Buffer} patchContent - patch 内容
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitApplyFromStdin(patchContent: Buffer, cwd?: string): void {
+  execCommandWithInput('git', ['apply'], { input: patchContent, cwd });
+}
+
+/**
+ * git reset --soft HEAD~<count>，撤销 commit 但保留变更在暂存区
+ * @param {number} count - 撤销的 commit 数量
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitResetSoft(count: number = 1, cwd?: string): void {
+  execCommand(`git reset --soft HEAD~${count}`, { cwd });
+}

package/src/utils/index.ts

@@ -20,6 +20,7 @@ export {
   gitStashPush,
   gitStashApply,
   gitStashPop,
+  gitStashDrop,
   gitStashList,
   gitRestoreStaged,
   gitWorktreeList,
@@ -29,6 +30,11 @@ export {
   getDiffStat,
   gitDiffCachedBinary,
   gitApplyCachedFromStdin,
+  getCurrentBranch,
+  getHeadCommitHash,
+  gitDiffBinaryAgainstBranch,
+  gitApplyFromStdin,
+  gitResetSoft,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -38,4 +44,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';
+export { getSnapshotPath, hasSnapshot, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, readSnapshotHead } from './validate-snapshot.js';

package/src/utils/validate-snapshot.ts

@@ -14,6 +14,16 @@ export function getSnapshotPath(projectName: string, branchName: string): string
   return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
 }
 
+/**
+ * 获取指定项目和分支的快照 HEAD hash 文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} head 文件的绝对路径
+ */
+function getSnapshotHeadPath(projectName: string, branchName: string): string {
+  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+}
+
 /**
  * 判断指定项目和分支是否存在 validate 快照
  * @param {string} projectName - 项目名
@@ -41,12 +51,17 @@ export function readSnapshot(projectName: string, branchName: string): Buffer {
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
  * @param {Buffer} patch - patch 内容（Buffer 格式）
+ * @param {string} [headHash] - 主分支 HEAD commit hash（用于增量 validate 一致性校验）
  */
-export function writeSnapshot(projectName: string, branchName: string, patch: Buffer): void {
+export function writeSnapshot(projectName: string, branchName: string, patch: Buffer, headHash?: string): void {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const snapshotDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   writeFileSync(snapshotPath, patch);
+  // 保存主分支 HEAD hash，用于下次增量 validate 时校验一致性
+  if (headHash) {
+    writeFileSync(getSnapshotHeadPath(projectName, branchName), headHash, 'utf-8');
+  }
   logger.info(`已保存 validate 快照: ${snapshotPath}`);
 }
 
@@ -61,6 +76,25 @@ export function removeSnapshot(projectName: string, branchName: string): void {
     unlinkSync(snapshotPath);
     logger.info(`已删除 validate 快照: ${snapshotPath}`);
   }
+  // 同时删除对应的 .head 文件
+  const headPath = getSnapshotHeadPath(projectName, branchName);
+  if (existsSync(headPath)) {
+    unlinkSync(headPath);
+  }
+}
+
+/**
+ * 读取快照保存时的主分支 HEAD commit hash
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string | null} HEAD hash，不存在则返回 null
+ */
+export function readSnapshotHead(projectName: string, branchName: string): string | null {
+  const headPath = getSnapshotHeadPath(projectName, branchName);
+  if (!existsSync(headPath)) {
+    return null;
+  }
+  return readFileSync(headPath, 'utf-8').trim();
 }
 
 /**