clawt 2.6.0 → 2.7.1

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

@@ -6,9 +6,11 @@
 - 完整的软件规格说明，包含 7 大章节
 - 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.13）
 - run 命令对应 `5.2 批量创建 Worktree + 执行 Claude Code 任务`，流程按步骤编号描述
-- merge 命令对应 `5.6 合并验证过的分支`，流程按步骤编号描述
+- merge 命令对应 `5.6 合并验证过的分支`，-b 可选，支持模糊匹配（与 resume/validate 共享匹配逻辑），流程按步骤编号描述
 - config 命令对应 `5.10 查看全局配置`，只读展示配置
 - resume 命令对应 `5.11 在已有 Worktree 中恢复会话`，支持模糊匹配和交互式分支选择（-b 可选）
+- validate 命令对应 `5.4 在主 Worktree 验证其他分支`，-b 可选，支持模糊匹配（与 resume 共享匹配逻辑）
+- sync 命令对应 `5.12 将主分支代码同步到目标 Worktree`，-b 可选，支持模糊匹配（与 resume/validate/merge 共享匹配逻辑）
 - 配置项说明在 `5.7 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
@@ -65,8 +67,11 @@ Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
 - `claudeCodeCommand` 配置项同时影响 run 交互式模式和 resume 命令
 - reset 命令与 validate --clean 的区别：reset 不删除快照文件，validate --clean 会删除快照
-- resume 的 `-b` 参数为可选，核心函数 `resolveTargetWorktree()` 封装匹配策略：精确→模糊（子串，大小写不敏感）→交互选择
-- resume 的交互式选择使用 Enquirer.Select（`promptSelectBranch()`），消息常量在 `MESSAGES.RESUME_*`
+- `resolveTargetWorktree()` 是 resume、validate、merge 和 sync 共用的分支匹配函数（在 src/utils/worktree-matcher.ts）
+- `WorktreeResolveMessages` 接口实现命令间消息解耦，每个命令传入各自的提示文案
+- resume 的消息常量在 `MESSAGES.RESUME_*`，validate 的消息常量在 `MESSAGES.VALIDATE_*`，merge 的消息常量在 `MESSAGES.MERGE_*`，sync 的消息常量在 `MESSAGES.SYNC_*`
+- resume、validate、merge 和 sync 的 `-b` 参数均为可选，匹配策略一致：精确→模糊（子串，大小写不敏感）→交互选择
+- validate 的交互式选择和 resume 使用同一个 `promptSelectBranch()`（Enquirer.Select）
 
 ## validate 快照机制
 

package/README.md

@@ -107,67 +107,110 @@ clawt resume
 ### `clawt validate` — 在主 worktree 验证分支变更
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt validate -b <branchName> [--clean]
+
+# 不指定分支名（列出所有分支供选择）
+clawt validate [--clean]
 ```
 
 | 参数 | 必填 | 说明 |
 | ---- | ---- | ---- |
-| `-b` | 是 | 要验证的分支名 |
+| `-b` | 否 | 要验证的分支名（支持模糊匹配，不传则列出所有分支供选择） |
 | `--clean` | 否 | 清理 validate 状态（重置主 worktree 并删除快照） |
 
 将目标 worktree 的变更通过 `git diff`（三点 diff）迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。同时检测未提交修改和已提交 commit，确保所有变更都能被捕获。
 
+**分支匹配策略：**
+- 传 `-b` 时，优先精确匹配分支名；未精确匹配则进行模糊匹配（子串匹配，大小写不敏感）；模糊匹配到多个时通过交互列表选择；无匹配时报错并列出所有可用分支
+- 不传 `-b` 时，列出当前项目所有可用分支供交互式选择（仅 1 个时自动使用）
+
 支持增量模式：首次 validate 后会自动保存快照（通过 `git write-tree` 将变更存储为 git tree 对象，并记录当前 HEAD commit hash），再次 validate 同一分支时会将上次快照载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。当主分支 HEAD 发生变化（如合并了其他分支）时，会自动将旧变更 patch 重放到当前 HEAD 暂存区上，避免 diff 混入 HEAD 变化的内容；若 patch 存在冲突则自动降级为全量模式。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
 
 > **提示：** 如果 validate 时 patch apply 失败（目标分支与主分支差异过大），可先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
 ```bash
-# 首次验证
+# 精确匹配分支名
 clawt validate -b feature-scheme-1
 
+# 模糊匹配（匹配包含 "scheme" 的分支）
+clawt validate -b scheme
+
+# 交互式选择所有分支
+clawt validate
+
 # 再次验证（增量模式，可通过 git diff 查看增量差异）
 clawt validate -b feature-scheme-1
 
-# 清理 validate 状态
+# 清理 validate 状态（同样支持模糊匹配）
 clawt validate -b feature-scheme-1 --clean
+clawt validate --clean
 ```
 
 ### `clawt sync` — 将主分支代码同步到目标 worktree
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt sync -b <branchName>
+
+# 不指定分支名（列出所有分支供选择）
+clawt sync
 ```
 
 | 参数 | 必填 | 说明 |
 | ---- | ---- | ---- |
-| `-b` | 是 | 要同步的分支名 |
+| `-b` | 否 | 要同步的分支名（支持模糊匹配，不传则列出所有分支供选择） |
 
 将主分支最新代码合并到目标 worktree 的分支中。如果目标 worktree 有未提交的修改，会自动保存后再合并。存在冲突时会提示用户手动解决。合并成功后会自动清除该分支的 validate 快照（代码基础已变化，旧快照无效）。
 
+**分支匹配策略：**
+- 传 `-b` 时，优先精确匹配分支名；未精确匹配则进行模糊匹配（子串匹配，大小写不敏感）；模糊匹配到多个时通过交互列表选择；无匹配时报错并列出所有可用分支
+- 不传 `-b` 时，列出当前项目所有可用分支供交互式选择（仅 1 个时自动使用）
+
 ```bash
-# 将主分支最新代码同步到目标 worktree
+# 精确匹配分支名
 clawt sync -b feature-scheme-1
+
+# 模糊匹配（匹配包含 "scheme" 的分支）
+clawt sync -b scheme
+
+# 交互式选择所有分支
+clawt sync
 ```
 
 ### `clawt merge` — 合并分支到主 worktree
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt merge -b <branchName> [-m <commitMessage>]
+
+# 不指定分支名（列出所有分支供选择）
+clawt merge [-m <commitMessage>]
 ```
 
 | 参数 | 必填 | 说明 |
 | ---- | ---- | ---- |
-| `-b` | 是 | 要合并的分支名 |
+| `-b` | 否 | 要合并的分支名（支持模糊匹配，不传则列出所有分支供选择） |
 | `-m` | 否 | 提交信息（目标 worktree 工作区有修改时必填） |
 
 将目标 worktree 的变更合并到主 worktree 的当前分支。如果配置了 `autoPullPush: true`，合并后会自动推送到远程仓库。如果目标 worktree 工作区有未提交的修改，需要通过 `-m` 提供提交信息；如果目标 worktree 已经提交过（工作区干净但有本地提交），可以省略 `-m` 直接合并。merge 成功后会询问是否清理对应的 worktree 和分支（如果配置了 `autoDeleteBranch: true` 则自动清理）。
 
+**分支匹配策略：**
+- 传 `-b` 时，优先精确匹配分支名；未精确匹配则进行模糊匹配（子串匹配，大小写不敏感）；模糊匹配到多个时通过交互列表选择；无匹配时报错并列出所有可用分支
+- 不传 `-b` 时，列出当前项目所有可用分支供交互式选择（仅 1 个时自动使用）
+
 如果检测到目标分支存在 `clawt sync` 产生的临时提交（auto-save commit），会自动提示是否将所有提交压缩（squash）为一个。用户选择压缩后，所有 commit 会被 reset 到暂存区：如果提供了 `-m` 则直接提交并继续合并流程；如果未提供 `-m` 则提示用户前往目标 worktree 自行提交后重新执行 merge。
 
 ```bash
-# 目标 worktree 有未提交修改，需提供 -m
+# 精确匹配，目标 worktree 有未提交修改，需提供 -m
 clawt merge -b feature-scheme-1 -m "feat: 实现用户登录功能"
 
+# 模糊匹配（匹配包含 "scheme" 的分支）
+clawt merge -b scheme
+
+# 交互式选择所有分支
+clawt merge
+
 # 目标 worktree 已提交过，可省略 -m
 clawt merge -b feature-scheme-1
 ```

package/dist/index.js

@@ -134,7 +134,37 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** resume 交互选择提示 */
   RESUME_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u6062\u590D\u7684\u5206\u652F",
   /** resume 模糊匹配到多个结果提示 */
-  RESUME_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
+  RESUME_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** validate 无可用 worktree */
+  VALIDATE_NO_WORKTREES: "\u5F53\u524D\u9879\u76EE\u6CA1\u6709\u53EF\u7528\u7684 worktree\uFF0C\u8BF7\u5148\u901A\u8FC7 clawt run \u6216 clawt create \u521B\u5EFA",
+  /** validate 模糊匹配无结果，列出可用分支 */
+  VALIDATE_NO_MATCH: (name, branches) => `\u672A\u627E\u5230\u4E0E "${name}" \u5339\u914D\u7684\u5206\u652F
+  \u53EF\u7528\u5206\u652F\uFF1A
+${branches.map((b) => `    - ${b}`).join("\n")}`,
+  /** validate 交互选择提示 */
+  VALIDATE_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u9A8C\u8BC1\u7684\u5206\u652F",
+  /** validate 模糊匹配到多个结果提示 */
+  VALIDATE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** merge 无可用 worktree */
+  MERGE_NO_WORKTREES: "\u5F53\u524D\u9879\u76EE\u6CA1\u6709\u53EF\u7528\u7684 worktree\uFF0C\u8BF7\u5148\u901A\u8FC7 clawt run \u6216 clawt create \u521B\u5EFA",
+  /** merge 模糊匹配无结果，列出可用分支 */
+  MERGE_NO_MATCH: (name, branches) => `\u672A\u627E\u5230\u4E0E "${name}" \u5339\u914D\u7684\u5206\u652F
+  \u53EF\u7528\u5206\u652F\uFF1A
+${branches.map((b) => `    - ${b}`).join("\n")}`,
+  /** merge 交互选择提示 */
+  MERGE_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u5408\u5E76\u7684\u5206\u652F",
+  /** merge 模糊匹配到多个结果提示 */
+  MERGE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** sync 无可用 worktree */
+  SYNC_NO_WORKTREES: "\u5F53\u524D\u9879\u76EE\u6CA1\u6709\u53EF\u7528\u7684 worktree\uFF0C\u8BF7\u5148\u901A\u8FC7 clawt run \u6216 clawt create \u521B\u5EFA",
+  /** sync 模糊匹配无结果，列出可用分支 */
+  SYNC_NO_MATCH: (name, branches) => `\u672A\u627E\u5230\u4E0E "${name}" \u5339\u914D\u7684\u5206\u652F
+  \u53EF\u7528\u5206\u652F\uFF1A
+${branches.map((b) => `    - ${b}`).join("\n")}`,
+  /** sync 交互选择提示 */
+  SYNC_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u540C\u6B65\u7684\u5206\u652F",
+  /** sync 模糊匹配到多个结果提示 */
+  SYNC_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
 };
 
 // src/constants/exitCodes.ts
@@ -742,6 +772,50 @@ function removeProjectSnapshots(projectName) {
   logger.info(`\u5DF2\u5220\u9664\u9879\u76EE ${projectName} \u7684\u6240\u6709 validate \u5FEB\u7167`);
 }
 
+// src/utils/worktree-matcher.ts
+import Enquirer2 from "enquirer";
+function findExactMatch(worktrees, branchName) {
+  return worktrees.find((wt) => wt.branch === branchName);
+}
+function findFuzzyMatches(worktrees, keyword) {
+  const lowerKeyword = keyword.toLowerCase();
+  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
+}
+async function promptSelectBranch(worktrees, message) {
+  const selectedBranch = await new Enquirer2.Select({
+    message,
+    choices: worktrees.map((wt) => ({
+      name: wt.branch,
+      message: wt.branch
+    }))
+  }).run();
+  return worktrees.find((wt) => wt.branch === selectedBranch);
+}
+async function resolveTargetWorktree(worktrees, messages, branchName) {
+  if (worktrees.length === 0) {
+    throw new ClawtError(messages.noWorktrees);
+  }
+  if (!branchName) {
+    if (worktrees.length === 1) {
+      return worktrees[0];
+    }
+    return promptSelectBranch(worktrees, messages.selectBranch);
+  }
+  const exactMatch = findExactMatch(worktrees, branchName);
+  if (exactMatch) {
+    return exactMatch;
+  }
+  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
+  if (fuzzyMatches.length === 1) {
+    return fuzzyMatches[0];
+  }
+  if (fuzzyMatches.length > 1) {
+    return promptSelectBranch(fuzzyMatches, messages.multipleMatches(branchName));
+  }
+  const allBranches = worktrees.map((wt) => wt.branch);
+  throw new ClawtError(messages.noMatch(branchName, allBranches));
+}
+
 // src/commands/list.ts
 import chalk2 from "chalk";
 function registerListCommand(program2) {
@@ -1059,68 +1133,36 @@ async function handleRun(options) {
 }
 
 // src/commands/resume.ts
-import Enquirer2 from "enquirer";
+var RESUME_RESOLVE_MESSAGES = {
+  noWorktrees: MESSAGES.RESUME_NO_WORKTREES,
+  selectBranch: MESSAGES.RESUME_SELECT_BRANCH,
+  multipleMatches: MESSAGES.RESUME_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.RESUME_NO_MATCH
+};
 function registerResumeCommand(program2) {
   program2.command("resume").description("\u5728\u5DF2\u6709 worktree \u4E2D\u6062\u590D Claude Code \u4EA4\u4E92\u5F0F\u4F1A\u8BDD").option("-b, --branch <branchName>", "\u8981\u6062\u590D\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 handleResume(options);
   });
 }
-function findExactMatch(worktrees, branchName) {
-  return worktrees.find((wt) => wt.branch === branchName);
-}
-function findFuzzyMatches(worktrees, keyword) {
-  const lowerKeyword = keyword.toLowerCase();
-  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
-}
-async function promptSelectBranch(worktrees, message) {
-  const selectedBranch = await new Enquirer2.Select({
-    message,
-    choices: worktrees.map((wt) => ({
-      name: wt.branch,
-      message: wt.branch
-    }))
-  }).run();
-  return worktrees.find((wt) => wt.branch === selectedBranch);
-}
-async function resolveTargetWorktree(branchName) {
-  const worktrees = getProjectWorktrees();
-  if (worktrees.length === 0) {
-    throw new ClawtError(MESSAGES.RESUME_NO_WORKTREES);
-  }
-  if (!branchName) {
-    if (worktrees.length === 1) {
-      return worktrees[0];
-    }
-    return promptSelectBranch(worktrees, MESSAGES.RESUME_SELECT_BRANCH);
-  }
-  const exactMatch = findExactMatch(worktrees, branchName);
-  if (exactMatch) {
-    return exactMatch;
-  }
-  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
-  if (fuzzyMatches.length === 1) {
-    return fuzzyMatches[0];
-  }
-  if (fuzzyMatches.length > 1) {
-    return promptSelectBranch(fuzzyMatches, MESSAGES.RESUME_MULTIPLE_MATCHES(branchName));
-  }
-  const allBranches = worktrees.map((wt) => wt.branch);
-  throw new ClawtError(MESSAGES.RESUME_NO_MATCH(branchName, allBranches));
-}
 async function handleResume(options) {
   validateMainWorktree();
   validateClaudeCodeInstalled();
   logger.info(`resume \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}`);
-  const worktree = await resolveTargetWorktree(options.branch);
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, RESUME_RESOLVE_MESSAGES, options.branch);
   launchInteractiveClaude(worktree);
 }
 
 // src/commands/validate.ts
-import { join as join4 } from "path";
-import { existsSync as existsSync6 } from "fs";
 import Enquirer3 from "enquirer";
+var VALIDATE_RESOLVE_MESSAGES = {
+  noWorktrees: MESSAGES.VALIDATE_NO_WORKTREES,
+  selectBranch: MESSAGES.VALIDATE_SELECT_BRANCH,
+  multipleMatches: MESSAGES.VALIDATE_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.VALIDATE_NO_MATCH
+};
 function registerValidateCommand(program2) {
-  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").requiredOption("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").action(async (options) => {
+  program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").option("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").action(async (options) => {
     await handleValidate(options);
   });
 }
@@ -1203,11 +1245,14 @@ async function handleValidateClean(options) {
   validateMainWorktree();
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
-  logger.info(`validate --clean \u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, VALIDATE_RESOLVE_MESSAGES, options.branch);
+  const branchName = worktree.branch;
+  logger.info(`validate --clean \u6267\u884C\uFF0C\u5206\u652F: ${branchName}`);
   if (getConfigValue("confirmDestructiveOps")) {
     const confirmed = await confirmDestructiveAction(
       "git reset --hard + git clean -fd",
-      `\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5206\u652F ${options.branch} \u7684 validate \u5FEB\u7167`
+      `\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5206\u652F ${branchName} \u7684 validate \u5FEB\u7167`
     );
     if (!confirmed) {
       printInfo(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
@@ -1218,8 +1263,8 @@ async function handleValidateClean(options) {
     gitResetHard(mainWorktreePath);
     gitCleanForce(mainWorktreePath);
   }
-  removeSnapshot(projectName, options.branch);
-  printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
+  removeSnapshot(projectName, branchName);
+  printSuccess(MESSAGES.VALIDATE_CLEANED(branchName));
 }
 function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
@@ -1266,40 +1311,43 @@ async function handleValidate(options) {
   validateMainWorktree();
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join4(projectDir, options.branch);
-  logger.info(`validate \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
-  if (!existsSync6(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
-  }
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, VALIDATE_RESOLVE_MESSAGES, options.branch);
+  const branchName = worktree.branch;
+  const targetWorktreePath = worktree.path;
+  logger.info(`validate \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${branchName}`);
   const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
-  const hasCommitted = hasLocalCommits(options.branch, mainWorktreePath);
+  const hasCommitted = hasLocalCommits(branchName, mainWorktreePath);
   if (!hasUncommitted && !hasCommitted) {
     printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
     return;
   }
-  const isIncremental = hasSnapshot(projectName, options.branch);
+  const isIncremental = hasSnapshot(projectName, branchName);
   if (isIncremental) {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   } else {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
 }
 
 // src/commands/merge.ts
-import { join as join5 } from "path";
-import { existsSync as existsSync7 } from "fs";
 function registerMergeCommand(program2) {
-  program2.command("merge").description("\u5408\u5E76\u67D0\u4E2A\u5DF2\u9A8C\u8BC1\u7684 worktree \u5206\u652F\u5230\u4E3B worktree").requiredOption("-b, --branch <branchName>", "\u8981\u5408\u5E76\u7684\u5206\u652F\u540D").option("-m, --message <message>", "\u63D0\u4EA4\u4FE1\u606F\uFF08\u5DE5\u4F5C\u533A\u6709\u4FEE\u6539\u65F6\u5FC5\u586B\uFF09").action(async (options) => {
+  program2.command("merge").description("\u5408\u5E76\u67D0\u4E2A\u5DF2\u9A8C\u8BC1\u7684 worktree \u5206\u652F\u5230\u4E3B worktree").option("-b, --branch <branchName>", "\u8981\u5408\u5E76\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").option("-m, --message <message>", "\u63D0\u4EA4\u4FE1\u606F\uFF08\u5DE5\u4F5C\u533A\u6709\u4FEE\u6539\u65F6\u5FC5\u586B\uFF09").action(async (options) => {
     await handleMerge(options);
   });
 }
+var MERGE_RESOLVE_MESSAGES = {
+  noWorktrees: MESSAGES.MERGE_NO_WORKTREES,
+  selectBranch: MESSAGES.MERGE_SELECT_BRANCH,
+  multipleMatches: MESSAGES.MERGE_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.MERGE_NO_MATCH
+};
 async function handleSquashIfNeeded(targetWorktreePath, mainWorktreePath, branchName, commitMessage) {
   if (!hasCommitWithMessage(branchName, AUTO_SAVE_COMMIT_MESSAGE, mainWorktreePath)) {
     return false;
@@ -1335,20 +1383,18 @@ function cleanupWorktreeAndBranch(worktreePath, branchName) {
 async function handleMerge(options) {
   validateMainWorktree();
   const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join5(projectDir, options.branch);
-  logger.info(`merge \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u63D0\u4EA4\u4FE1\u606F: ${options.message ?? "(\u672A\u63D0\u4F9B)"}`);
-  if (!existsSync7(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
-  }
+  logger.info(`merge \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}\uFF0C\u63D0\u4EA4\u4FE1\u606F: ${options.message ?? "(\u672A\u63D0\u4F9B)"}`);
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, MERGE_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
   const projectName = getProjectName();
   if (!isWorkingDirClean(mainWorktreePath)) {
-    if (hasSnapshot(projectName, options.branch)) {
-      printWarning(MESSAGES.MERGE_VALIDATE_STATE_HINT(options.branch));
+    if (hasSnapshot(projectName, branch)) {
+      printWarning(MESSAGES.MERGE_VALIDATE_STATE_HINT(branch));
     }
     throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
   }
-  const shouldExit = await handleSquashIfNeeded(targetWorktreePath, mainWorktreePath, options.branch, options.message);
+  const shouldExit = await handleSquashIfNeeded(targetWorktreePath, mainWorktreePath, branch, options.message);
   if (shouldExit) {
     return;
   }
@@ -1360,12 +1406,12 @@ async function handleMerge(options) {
     gitAddAll(targetWorktreePath);
     gitCommit(options.message, targetWorktreePath);
   } else {
-    if (!hasLocalCommits(options.branch, mainWorktreePath)) {
+    if (!hasLocalCommits(branch, mainWorktreePath)) {
       throw new ClawtError(MESSAGES.TARGET_WORKTREE_NO_CHANGES);
     }
   }
   try {
-    gitMerge(options.branch, mainWorktreePath);
+    gitMerge(branch, mainWorktreePath);
   } catch (error) {
     if (hasMergeConflict(mainWorktreePath)) {
       throw new ClawtError(MESSAGES.MERGE_CONFLICT);
@@ -1383,16 +1429,16 @@ async function handleMerge(options) {
     printInfo("\u5DF2\u8DF3\u8FC7\u81EA\u52A8 pull/push\uFF0C\u8BF7\u624B\u52A8\u6267\u884C git pull && git push");
   }
   if (options.message) {
-    printSuccess(MESSAGES.MERGE_SUCCESS(options.branch, options.message, autoPullPush));
+    printSuccess(MESSAGES.MERGE_SUCCESS(branch, options.message, autoPullPush));
   } else {
-    printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch, autoPullPush));
+    printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(branch, autoPullPush));
   }
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
+  const shouldCleanup = await shouldCleanupAfterMerge(branch);
   if (shouldCleanup) {
-    cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
+    cleanupWorktreeAndBranch(targetWorktreePath, branch);
   }
-  if (hasSnapshot(projectName, options.branch)) {
-    removeSnapshot(projectName, options.branch);
+  if (hasSnapshot(projectName, branch)) {
+    removeSnapshot(projectName, branch);
   }
 }
 
@@ -1431,13 +1477,17 @@ function formatConfigValue(value) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync8 } from "fs";
-import { join as join6 } from "path";
 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) => {
+  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);
@@ -1457,13 +1507,10 @@ function mergeMainBranch(worktreePath, mainBranch) {
 }
 async function handleSync(options) {
   validateMainWorktree();
-  const { branch } = options;
-  logger.info(`sync \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${branch}`);
-  const projectWorktreeDir = getProjectWorktreeDir();
-  const targetWorktreePath = join6(projectWorktreeDir, branch);
-  if (!existsSync8(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
-  }
+  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)) {