clawt 2.16.3 → 2.16.4

package/README.md

@@ -128,6 +128,8 @@ clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命
 
 支持增量模式：再次 validate 同一分支时，可通过 `git diff` 查看两次之间的增量差异。
 
+当 patch apply 失败（目标分支与主分支差异过大）时，会自动询问是否执行 `sync` 同步主分支到目标 worktree，无需手动操作。
+
 `-r, --run` 选项可在 validate 成功后自动在主 worktree 中执行指定命令（如测试、构建等），命令执行失败不影响 validate 结果。支持用 `&` 分隔多个命令并行执行：
 
 | 用法 | 行为 |
@@ -142,6 +144,8 @@ clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命
 clawt sync -b <branch>
 ```
 
+当 `validate` 的 patch apply 失败时也会自动提示执行 sync，通常无需手动调用。
+
 ### `clawt merge` — 合并分支到主 worktree
 
 ```bash

package/dist/index.js

@@ -211,7 +211,16 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 并行执行中单个命令失败 */
   VALIDATE_PARALLEL_CMD_FAILED: (command, exitCode) => `  \u2717 ${command}\uFF08\u9000\u51FA\u7801: ${exitCode}\uFF09`,
   /** 并行执行中单个命令启动失败 */
-  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`
+  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`,
+  /** patch apply 失败后询问用户是否执行 sync */
+  VALIDATE_CONFIRM_AUTO_SYNC: (branch) => `\u662F\u5426\u7ACB\u5373\u6267\u884C sync \u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch}\uFF1F`,
+  /** 自动 sync 开始提示 */
+  VALIDATE_AUTO_SYNC_START: (branch) => `\u6B63\u5728\u81EA\u52A8\u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch} ...`,
+  /** 自动 sync 存在冲突，无法重试 */
+  VALIDATE_AUTO_SYNC_CONFLICT: (worktreePath) => `\u540C\u6B65\u5B58\u5728\u51B2\u7A81\uFF0C\u8BF7\u8FDB\u5165\u76EE\u6807 worktree \u624B\u52A8\u89E3\u51B3\u51B2\u7A81\u540E\u91CD\u8BD5
+  cd ${worktreePath}`,
+  /** 用户拒绝自动 sync */
+  VALIDATE_AUTO_SYNC_DECLINED: (branch) => `\u8BF7\u624B\u52A8\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
 };
 
 // src/constants/messages/sync.ts
@@ -2337,6 +2346,66 @@ async function handleBatchResume(worktrees) {
 
 // src/commands/validate.ts
 import Enquirer4 from "enquirer";
+
+// src/commands/sync.ts
+function registerSyncCommand(program2) {
+  program2.command("sync").description("\u5C06\u4E3B\u5206\u652F\u6700\u65B0\u4EE3\u7801\u540C\u6B65\u5230\u76EE\u6807 worktree").option("-b, --branch <branchName>", "\u8981\u540C\u6B65\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").action(async (options) => {
+    await handleSync(options);
+  });
+}
+var SYNC_RESOLVE_MESSAGES = {
+  noWorktrees: MESSAGES.SYNC_NO_WORKTREES,
+  selectBranch: MESSAGES.SYNC_SELECT_BRANCH,
+  multipleMatches: MESSAGES.SYNC_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.SYNC_NO_MATCH
+};
+function autoSaveChanges(worktreePath, branch) {
+  gitAddAll(worktreePath);
+  gitCommit(AUTO_SAVE_COMMIT_MESSAGE, 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`);
+  }
+}
+function executeSyncForBranch(targetWorktreePath, 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 { success: false, hasConflict: true };
+  }
+  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));
+  return { success: true, hasConflict: false };
+}
+async function handleSync(options) {
+  validateMainWorktree();
+  logger.info(`sync \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}`);
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
+  executeSyncForBranch(targetWorktreePath, branch);
+}
+
+// src/commands/validate.ts
 var VALIDATE_RESOLVE_MESSAGES = {
   noWorktrees: MESSAGES.VALIDATE_NO_WORKTREES,
   selectBranch: MESSAGES.VALIDATE_SELECT_BRANCH,
@@ -2397,9 +2466,10 @@ function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName
       } catch (error) {
         logger.warn(`patch apply \u5931\u8D25: ${error}`);
         printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
-        throw error;
+        return { success: false };
       }
     }
+    return { success: true };
   } finally {
     if (didTempCommit) {
       try {
@@ -2415,6 +2485,18 @@ function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName
     }
   }
 }
+async function handlePatchApplyFailure(targetWorktreePath, branchName) {
+  const confirmed = await confirmAction(MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC(branchName));
+  if (!confirmed) {
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_DECLINED(branchName));
+    return;
+  }
+  printInfo(MESSAGES.VALIDATE_AUTO_SYNC_START(branchName));
+  const syncResult = executeSyncForBranch(targetWorktreePath, branchName);
+  if (syncResult.hasConflict) {
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_CONFLICT(targetWorktreePath));
+  }
+}
 function saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName) {
   gitAddAll(mainWorktreePath);
   const treeHash = gitWriteTree(mainWorktreePath);
@@ -2448,18 +2530,26 @@ async function handleValidateClean(options) {
   removeSnapshot(projectName, branchName);
   printSuccess(MESSAGES.VALIDATE_CLEANED(branchName));
 }
-function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+async function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  if (!result.success) {
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
   printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
 }
-function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
+async function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
   const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
   if (!isWorkingDirClean(mainWorktreePath)) {
     gitResetHard(mainWorktreePath);
     gitCleanForce(mainWorktreePath);
   }
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  if (!result.success) {
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
   try {
     const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
@@ -2562,12 +2652,12 @@ async function handleValidate(options) {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   } else {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
   if (options.run) {
     await executeRunCommand(options.run, mainWorktreePath);
@@ -2780,60 +2870,6 @@ function handleConfigGet(key) {
   printInfo(MESSAGES.CONFIG_GET_VALUE(key, String(value)));
 }
 
-// src/commands/sync.ts
-function registerSyncCommand(program2) {
-  program2.command("sync").description("\u5C06\u4E3B\u5206\u652F\u6700\u65B0\u4EE3\u7801\u540C\u6B65\u5230\u76EE\u6807 worktree").option("-b, --branch <branchName>", "\u8981\u540C\u6B65\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").action(async (options) => {
-    await handleSync(options);
-  });
-}
-var SYNC_RESOLVE_MESSAGES = {
-  noWorktrees: MESSAGES.SYNC_NO_WORKTREES,
-  selectBranch: MESSAGES.SYNC_SELECT_BRANCH,
-  multipleMatches: MESSAGES.SYNC_MULTIPLE_MATCHES,
-  noMatch: MESSAGES.SYNC_NO_MATCH
-};
-function autoSaveChanges(worktreePath, branch) {
-  gitAddAll(worktreePath);
-  gitCommit(AUTO_SAVE_COMMIT_MESSAGE, 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();
-  logger.info(`sync \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}`);
-  const worktrees = getProjectWorktrees();
-  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
-  const { path: targetWorktreePath, branch } = worktree;
-  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/commands/reset.ts
 function registerResetCommand(program2) {
   program2.command("reset").description("\u91CD\u7F6E\u4E3B worktree \u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\uFF08\u4FDD\u7559 validate \u5FEB\u7167\uFF09").action(async () => {

package/dist/postinstall.js

@@ -203,7 +203,16 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 并行执行中单个命令失败 */
   VALIDATE_PARALLEL_CMD_FAILED: (command, exitCode) => `  \u2717 ${command}\uFF08\u9000\u51FA\u7801: ${exitCode}\uFF09`,
   /** 并行执行中单个命令启动失败 */
-  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`
+  VALIDATE_PARALLEL_CMD_ERROR: (command, errorMessage) => `  \u2717 ${command}\uFF08\u9519\u8BEF: ${errorMessage}\uFF09`,
+  /** patch apply 失败后询问用户是否执行 sync */
+  VALIDATE_CONFIRM_AUTO_SYNC: (branch) => `\u662F\u5426\u7ACB\u5373\u6267\u884C sync \u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch}\uFF1F`,
+  /** 自动 sync 开始提示 */
+  VALIDATE_AUTO_SYNC_START: (branch) => `\u6B63\u5728\u81EA\u52A8\u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch} ...`,
+  /** 自动 sync 存在冲突，无法重试 */
+  VALIDATE_AUTO_SYNC_CONFLICT: (worktreePath) => `\u540C\u6B65\u5B58\u5728\u51B2\u7A81\uFF0C\u8BF7\u8FDB\u5165\u76EE\u6807 worktree \u624B\u52A8\u89E3\u51B3\u51B2\u7A81\u540E\u91CD\u8BD5
+  cd ${worktreePath}`,
+  /** 用户拒绝自动 sync */
+  VALIDATE_AUTO_SYNC_DECLINED: (branch) => `\u8BF7\u624B\u52A8\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
 };
 
 // src/constants/messages/sync.ts

package/docs/spec.md

@@ -576,7 +576,26 @@ git restore --staged .
 ```
 
 > 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
-> 如果 patch apply 失败（目标分支与主分支差异过大），会提示用户先执行 `clawt sync -b <branchName>` 同步主分支后重试。
+> 如果 patch apply 失败（目标分支与主分支差异过大），`migrateChangesViaPatch` 返回 `{ success: false }`，进入自动 sync 交互流程（见下文 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)）。
+
+##### patch apply 失败后的自动 sync 流程
+
+当 patch apply 失败时，validate 不再直接退出，而是通过 `handlePatchApplyFailure()` 函数进入交互流程：
+
+1. **询问用户**：提示 `是否立即执行 sync 同步主分支到 <branchName>？`
+2. **用户拒绝** → 输出提示 `请手动执行 clawt sync -b <branchName> 同步主分支后重试`，退出
+3. **用户确认** → 调用 `executeSyncForBranch(targetWorktreePath, branchName)` 自动执行 sync
+   - **sync 成功** → validate 流程结束（用户需重新执行 validate）
+   - **sync 存在冲突** → 输出提示 `同步存在冲突，请进入目标 worktree 手动解决冲突后重试`，退出
+
+> `executeSyncForBranch` 为 sync 命令抽取的核心操作函数（见 [5.12](#512-将主分支代码同步到目标-worktree)），供 validate 等命令复用。
+
+**实现要点：**
+
+- `migrateChangesViaPatch()` 返回类型从 `void` 改为 `{ success: boolean }`，patch apply 失败时返回 `{ success: false }` 而非抛出异常
+- `handleFirstValidate()` 和 `handleIncrementalValidate()` 从同步函数改为 `async` 函数，以支持交互式确认
+- `handlePatchApplyFailure()` 为新增的异步函数（`src/commands/validate.ts`），负责 patch 失败后的交互逻辑
+- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_CONFLICT`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`（`src/constants/messages/validate.ts`）
 
 ##### 步骤 4：保存快照为 git tree 对象
 
@@ -715,7 +734,7 @@ clawt validate -b feature-scheme-1 -r "pnpm test & pnpm build"
 
 ##### 步骤 3：从目标分支获取最新全量变更
 
-通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。如果 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
 
 ##### 步骤 4：保存最新快照为 git tree 对象
 
@@ -1356,16 +1375,36 @@ clawt sync
         - 唯一匹配 → 直接使用
         - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
      3. **无匹配** → 报错退出，并列出所有可用分支名
-3. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
-4. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
+3. 调用 `executeSyncForBranch(targetWorktreePath, branch)` 执行核心同步逻辑
+
+#### `executeSyncForBranch` — sync 核心操作函数
+
+`executeSyncForBranch(targetWorktreePath: string, branch: string): SyncResult` 是从 `handleSync` 中抽取的核心同步逻辑，不包含 worktree 解析交互，供 validate 等命令复用。
+
+**接口定义：**
+
+```typescript
+/** sync 核心操作的执行结果 */
+export interface SyncResult {
+  /** 是否同步成功 */
+  success: boolean;
+  /** 是否存在合并冲突 */
+  hasConflict: boolean;
+}
+```
+
+**执行流程：**
+
+1. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
+2. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
    - 有修改 → 自动执行 `git add . && git commit -m "<AUTO_SAVE_COMMIT_MESSAGE>"` 保存变更（commit message 由常量 `AUTO_SAVE_COMMIT_MESSAGE` 定义，值为 `chore: auto-save before sync`，同时用于 merge 命令的 squash 检测）
    - 无修改 → 跳过
-5. **在目标 worktree 中合并主分支**：
+3. **在目标 worktree 中合并主分支**：
    ```bash
    cd ~/.clawt/worktrees/<project>/<branchName>
    git merge <mainBranch>
    ```
-6. **冲突处理**：
+4. **冲突处理**：
    - **有冲突** → 输出警告，提示用户进入目标 worktree 手动解决：
      ```
      合并存在冲突，请进入目标 worktree 手动解决：
@@ -1373,9 +1412,10 @@ clawt sync
        解决冲突后执行 git add . && git merge --continue
        clawt validate -b <branch> 验证变更
      ```
+   - 返回 `{ success: false, hasConflict: true }`
    - **无冲突** → 继续
-7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
-8. **输出成功提示**：
+5. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
+6. **输出成功提示**并返回 `{ success: true, hasConflict: false }`：
    ```
    ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
    ```

package/package.json

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

package/src/commands/sync.ts

@@ -77,21 +77,22 @@ function mergeMainBranch(worktreePath: string, mainBranch: string): boolean {
   }
 }
 
+/** sync 核心操作的执行结果 */
+export interface SyncResult {
+  /** 是否同步成功 */
+  success: boolean;
+  /** 是否存在合并冲突 */
+  hasConflict: boolean;
+}
+
 /**
- * 执行 sync 命令的核心逻辑
- * 将主分支最新代码同步到目标 worktree
- * @param {SyncOptions} options - 命令选项
+ * 执行 sync 核心操作（检查未提交→自动保存→merge 主分支→清除快照）
+ * 不包含 worktree 解析交互，供 validate 等命令复用
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} branch - 分支名
+ * @returns {SyncResult} sync 执行结果
  */
-async function handleSync(options: SyncOptions): Promise<void> {
-  validateMainWorktree();
-
-  logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
-
-  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
-  const worktrees = getProjectWorktrees();
-  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
-  const { path: targetWorktreePath, branch } = worktree;
-
+export function executeSyncForBranch(targetWorktreePath: string, branch: string): SyncResult {
   // 获取主分支名（不硬编码 main/master）
   const mainWorktreePath = getGitTopLevel();
   const mainBranch = getCurrentBranch(mainWorktreePath);
@@ -107,7 +108,7 @@ async function handleSync(options: SyncOptions): Promise<void> {
 
   if (hasConflict) {
     printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
-    return;
+    return { success: false, hasConflict: true };
   }
 
   // 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
@@ -118,4 +119,23 @@ async function handleSync(options: SyncOptions): Promise<void> {
   }
 
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+  return { success: true, hasConflict: false };
+}
+
+/**
+ * 执行 sync 命令的核心逻辑
+ * 将主分支最新代码同步到目标 worktree
+ * @param {SyncOptions} options - 命令选项
+ */
+async function handleSync(options: SyncOptions): Promise<void> {
+  validateMainWorktree();
+
+  logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
+
+  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
+
+  executeSyncForBranch(targetWorktreePath, branch);
 }

package/src/commands/validate.ts

@@ -4,6 +4,7 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { ValidateOptions } from '../types/index.js';
+import { executeSyncForBranch } from './sync.js';
 import {
   validateMainWorktree,
   getProjectName,
@@ -33,6 +34,7 @@ import {
   writeSnapshot,
   removeSnapshot,
   confirmDestructiveAction,
+  confirmAction,
   printSuccess,
   printError,
   printWarning,
@@ -121,8 +123,9 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ * @returns {{ success: boolean }} patch 迁移结果
  */
-function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): void {
+function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): { success: boolean } {
   let didTempCommit = false;
 
   try {
@@ -143,9 +146,11 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
       } catch (error) {
         logger.warn(`patch apply 失败: ${error}`);
         printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
-        throw error;
+        return { success: false };
       }
     }
+
+    return { success: true };
   } finally {
     // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
     // 每个操作独立 try-catch，避免前一个失败导致后续操作不执行
@@ -164,6 +169,31 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
   }
 }
 
+/**
+ * patch apply 失败后的交互处理：询问用户是否自动执行 sync
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} branchName - 分支名
+ */
+async function handlePatchApplyFailure(targetWorktreePath: string, branchName: string): Promise<void> {
+  // 询问用户是否自动执行 sync
+  const confirmed = await confirmAction(MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC(branchName));
+
+  if (!confirmed) {
+    // 用户拒绝自动 sync
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_DECLINED(branchName));
+    return;
+  }
+
+  // 用户确认，执行 sync
+  printInfo(MESSAGES.VALIDATE_AUTO_SYNC_START(branchName));
+  const syncResult = executeSyncForBranch(targetWorktreePath, branchName);
+
+  if (syncResult.hasConflict) {
+    // sync 存在冲突，提示用户手动解决
+    printWarning(MESSAGES.VALIDATE_AUTO_SYNC_CONFLICT(targetWorktreePath));
+  }
+}
+
 /**
  * 保存当前主 worktree 工作目录变更为 git tree 对象快照
  * 操作序列：git add . → git write-tree → git restore --staged .
@@ -231,9 +261,15 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 通过 patch 迁移目标分支全量变更到主 worktree
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+
+  if (!result.success) {
+    // patch 失败，询问用户是否自动 sync
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
 
   // 保存快照为 git tree 对象
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
@@ -250,7 +286,7 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
  * @param {string} branchName - 分支名
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
-function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+async function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
   const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
 
@@ -262,7 +298,13 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   }
 
   // 步骤 3：通过 patch 从目标分支获取最新全量变更
-  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+  const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+
+  if (!result.success) {
+    // patch 失败，询问用户是否自动 sync
+    await handlePatchApplyFailure(targetWorktreePath, branchName);
+    return;
+  }
 
   // 步骤 4：保存最新快照为 git tree 对象（同时记录当前 HEAD）
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
@@ -441,14 +483,14 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   } else {
     // 首次模式：先确保主 worktree 干净
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
 
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
+    await handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
 
   // validate 成功后执行用户指定的命令

package/src/constants/messages/validate.ts

@@ -53,4 +53,16 @@ export const VALIDATE_MESSAGES = {
   /** 并行执行中单个命令启动失败 */
   VALIDATE_PARALLEL_CMD_ERROR: (command: string, errorMessage: string) =>
     `  ✗ ${command}（错误: ${errorMessage}）`,
+  /** patch apply 失败后询问用户是否执行 sync */
+  VALIDATE_CONFIRM_AUTO_SYNC: (branch: string) =>
+    `是否立即执行 sync 同步主分支到 ${branch}？`,
+  /** 自动 sync 开始提示 */
+  VALIDATE_AUTO_SYNC_START: (branch: string) =>
+    `正在自动同步主分支到 ${branch} ...`,
+  /** 自动 sync 存在冲突，无法重试 */
+  VALIDATE_AUTO_SYNC_CONFLICT: (worktreePath: string) =>
+    `同步存在冲突，请进入目标 worktree 手动解决冲突后重试\n  cd ${worktreePath}`,
+  /** 用户拒绝自动 sync */
+  VALIDATE_AUTO_SYNC_DECLINED: (branch: string) =>
+    `请手动执行 clawt sync -b ${branch} 同步主分支后重试`,
 } as const;