clawt 2.7.0 → 2.7.1

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

@@ -6,10 +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 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
@@ -66,10 +67,10 @@ Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
 - `claudeCodeCommand` 配置项同时影响 run 交互式模式和 resume 命令
 - reset 命令与 validate --clean 的区别：reset 不删除快照文件，validate --clean 会删除快照
-- `resolveTargetWorktree()` 是 resume 和 validate 共用的分支匹配函数（在 src/utils/worktree-matcher.ts）
+- `resolveTargetWorktree()` 是 resume、validate、merge 和 sync 共用的分支匹配函数（在 src/utils/worktree-matcher.ts）
 - `WorktreeResolveMessages` 接口实现命令间消息解耦，每个命令传入各自的提示文案
-- resume 的消息常量在 `MESSAGES.RESUME_*`，validate 的消息常量在 `MESSAGES.VALIDATE_*`
-- resume 和 validate 的 `-b` 参数均为可选，匹配策略一致：精确→模糊（子串，大小写不敏感）→交互选择
+- 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

@@ -150,39 +150,67 @@ 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

@@ -144,7 +144,27 @@ ${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`
+  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
@@ -1317,13 +1337,17 @@ async function handleValidate(options) {
 }
 
 // src/commands/merge.ts
-import { join as join4 } from "path";
-import { existsSync as existsSync6 } 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;
@@ -1359,20 +1383,18 @@ function cleanupWorktreeAndBranch(worktreePath, branchName) {
 async function handleMerge(options) {
   validateMainWorktree();
   const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join4(projectDir, options.branch);
-  logger.info(`merge \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u63D0\u4EA4\u4FE1\u606F: ${options.message ?? "(\u672A\u63D0\u4F9B)"}`);
-  if (!existsSync6(targetWorktreePath)) {
-    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;
   }
@@ -1384,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);
@@ -1407,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);
   }
 }
 
@@ -1455,13 +1477,17 @@ function formatConfigValue(value) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync7 } from "fs";
-import { join as join5 } 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);
@@ -1481,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 = join5(projectWorktreeDir, branch);
-  if (!existsSync7(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)) {

package/docs/spec.md

@@ -622,41 +622,57 @@ git branch -D <branchName>
 **命令：**
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt merge -b <branchName> [-m <commitMessage>]
+
+# 不指定分支名（列出所有分支供选择）
+clawt merge [-m <commitMessage>]
 ```
 
 **参数：**
 
-| 参数 | 必填 | 说明                                     |
-| ---- | ---- | ---------------------------------------- |
-| `-b` | 是   | 要合并的分支名                           |
-| `-m` | 否   | 提交信息（目标 worktree 工作区有修改时必填） |
+| 参数 | 必填 | 说明                                                                     |
+| ---- | ---- | ------------------------------------------------------------------------ |
+| `-b` | 否   | 要合并的分支名（支持模糊匹配，不传则列出所有分支供选择）                   |
+| `-m` | 否   | 提交信息（目标 worktree 工作区有修改时必填）                               |
 
 **运行流程：**
 
 1. **主 worktree 校验** (2.1)
-2. **主 worktree 状态检测**
+2. **解析目标 worktree**：根据 `-b` 参数解析目标 worktree，匹配策略如下：
+   - **未传 `-b` 参数**：
+     - 获取当前项目所有 worktree
+     - 无可用 worktree → 报错退出
+     - 仅 1 个 worktree → 直接使用，无需选择
+     - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
+   - **传了 `-b` 参数**：
+     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+     2. **模糊匹配**（子串匹配，大小写不敏感）：
+        - 唯一匹配 → 直接使用
+        - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
+     3. **无匹配** → 报错退出，并列出所有可用分支名
+3. **主 worktree 状态检测**
    - 执行 `git status --porcelain`
    - 如果有更改：
      - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），额外输出警告提示用户可先执行 `clawt validate -b <branchName> --clean` 清理
      - 提示 `主 worktree 有未提交的更改，请先处理`，退出
    - 无更改 → 继续
-3. **Squash 检测与执行（auto-save 临时提交压缩）**
+4. **Squash 检测与执行（auto-save 临时提交压缩）**
    - 通过 `git log HEAD..<branchName> --format=%s` 检查目标分支是否存在以 `AUTO_SAVE_COMMIT_MESSAGE`（`chore: auto-save before sync`）为前缀的 commit
-   - **不存在** → 跳过，进入步骤 4
+   - **不存在** → 跳过，进入步骤 5
    - **存在** → 提示用户是否将所有提交压缩为一个：
      ```
      检测到 sync 产生的临时提交，是否将所有提交压缩为一个？
        压缩后变更将保留在目标worktree的暂存区，需要重新提交
      ```
-   - **用户选择不压缩** → 跳过，进入步骤 4
+   - **用户选择不压缩** → 跳过，进入步骤 5
    - **用户选择压缩** →
      1. 获取主分支名（`git rev-parse --abbrev-ref HEAD`）
      2. 计算分叉点：`git merge-base <mainBranch> <branchName>`
      3. 在目标 worktree 中执行 `git reset --soft <merge-base>`，将所有 commit 撤销到暂存区
-     4. 如果用户提供了 `-m` → 直接在目标 worktree 执行 `git commit -m '<commitMessage>'`，输出成功提示，继续步骤 4
+     4. 如果用户提供了 `-m` → 直接在目标 worktree 执行 `git commit -m '<commitMessage>'`，输出成功提示，继续步骤 5
      5. 如果用户未提供 `-m` → 提示用户前往目标 worktree 自行提交后重新执行 `clawt merge`，**退出流程**
-4. **根据目标 worktree 状态决定是否需要提交**
+5. **根据目标 worktree 状态决定是否需要提交**
    - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
    - **工作区有未提交修改**：
      - 如果用户未提供 `-m`，提示 `目标 worktree 有未提交的修改，请通过 -m 参数提供提交信息`，退出
@@ -670,22 +686,22 @@ clawt merge -b <branchName> [-m <commitMessage>]
      - 检查目标分支相对于主分支是否有本地提交（`git log HEAD..<branchName> --oneline`）
      - 有本地提交 → 跳过提交步骤，直接进入合并
      - 无本地提交 → 提示 `目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）`，退出
-5. **回到主 worktree 进行合并**
+6. **回到主 worktree 进行合并**
    ```bash
    cd <主 worktree 路径>
    git merge <branchName>
    ```
-6. **冲突检测**
+7. **冲突检测**
    - 检查 merge 退出码及 `git status` 是否存在冲突
    - **有冲突** → 提示 `合并存在冲突，请手动处理`，退出
    - **无冲突** → 继续
-7. **推送（受 `autoPullPush` 配置控制）**
+8. **推送（受 `autoPullPush` 配置控制）**
    ```bash
    # 仅当 autoPullPush 为 true 时执行
    git pull
    git push
    ```
-8. **输出成功提示**
+9. **输出成功提示**
 
 ```
 # 提供了 -m 且已推送时
@@ -705,7 +721,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 ✓ 分支 feature-scheme-1 已成功合并到当前分支
 ```
 
-9. **merge 成功后确认并清理 worktree 和分支（可选）**
+10. **merge 成功后确认并清理 worktree 和分支（可选）**
    - 如果配置文件中 `autoDeleteBranch` 为 `true`，自动执行清理
    - 否则交互式询问用户是否清理
    - 用户确认后，依次执行：
@@ -720,7 +736,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
      ```
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
-10. **清理 validate 快照**
+11. **清理 validate 快照**
     - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree` 和 `<branchName>.head`），自动删除这些快照文件（merge 成功后快照已无意义）
 
 > **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。
@@ -951,14 +967,18 @@ clawt resume
 **命令：**
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt sync -b <branchName>
+
+# 不指定分支名（列出所有分支供选择）
+clawt sync
 ```
 
 **参数：**
 
-| 参数 | 必填 | 说明                                                  |
-| ---- | ---- | ----------------------------------------------------- |
-| `-b` | 是   | 要同步的分支名（对应已有 worktree 的分支）               |
+| 参数 | 必填 | 说明                                                                     |
+| ---- | ---- | ------------------------------------------------------------------------ |
+| `-b` | 否   | 要同步的分支名（支持模糊匹配，不传则列出所有分支供选择）                   |
 
 **使用场景：**
 
@@ -967,8 +987,18 @@ clawt sync -b <branchName>
 **运行流程：**
 
 1. **主 worktree 校验** (2.1)
-2. **检查目标 worktree 是否存在**：确认 `~/.clawt/worktrees/<project>/<branchName>` 目录存在
-   - 不存在 → 报错退出
+2. **解析目标 worktree**：根据 `-b` 参数解析目标 worktree，匹配策略如下：
+   - **未传 `-b` 参数**：
+     - 获取当前项目所有 worktree
+     - 无可用 worktree → 报错退出
+     - 仅 1 个 worktree → 直接使用，无需选择
+     - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
+   - **传了 `-b` 参数**：
+     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+     2. **模糊匹配**（子串匹配，大小写不敏感）：
+        - 唯一匹配 → 直接使用
+        - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
+     3. **无匹配** → 报错退出，并列出所有可用分支名
 3. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
 4. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
    - 有修改 → 自动执行 `git add . && git commit -m "<AUTO_SAVE_COMMIT_MESSAGE>"` 保存变更（commit message 由常量 `AUTO_SAVE_COMMIT_MESSAGE` 定义，值为 `chore: auto-save before sync`，同时用于 merge 命令的 squash 检测）

package/package.json

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

package/src/commands/merge.ts

@@ -1,6 +1,4 @@
 import type { Command } from 'commander';
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES, AUTO_SAVE_COMMIT_MESSAGE } from '../constants/index.js';
@@ -9,7 +7,7 @@ import {
   validateMainWorktree,
   getProjectName,
   getGitTopLevel,
-  getProjectWorktreeDir,
+  getProjectWorktrees,
   isWorkingDirClean,
   gitAddAll,
   gitCommit,
@@ -30,7 +28,9 @@ import {
   gitMergeBase,
   gitResetSoftTo,
   getCurrentBranch,
+  resolveTargetWorktree,
 } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
 
 /**
  * 注册 merge 命令：合并验证过的分支到主 worktree
@@ -40,13 +40,21 @@ export function registerMergeCommand(program: Command): void {
   program
     .command('merge')
     .description('合并某个已验证的 worktree 分支到主 worktree')
-    .requiredOption('-b, --branch <branchName>', '要合并的分支名')
+    .option('-b, --branch <branchName>', '要合并的分支名（支持模糊匹配，不传则列出所有分支）')
     .option('-m, --message <message>', '提交信息（工作区有修改时必填）')
     .action(async (options: MergeOptions) => {
       await handleMerge(options);
     });
 }
 
+/** merge 命令的分支解析消息配置 */
+const MERGE_RESOLVE_MESSAGES: WorktreeResolveMessages = {
+  noWorktrees: MESSAGES.MERGE_NO_WORKTREES,
+  selectBranch: MESSAGES.MERGE_SELECT_BRANCH,
+  multipleMatches: MESSAGES.MERGE_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.MERGE_NO_MATCH,
+};
+
 /**
  * 检测并处理目标分支的 auto-save 提交压缩
  * 如果检测到 sync 产生的临时提交，提示用户是否将所有提交压缩为一个
@@ -126,29 +134,27 @@ async function handleMerge(options: MergeOptions): Promise<void> {
   validateMainWorktree();
 
   const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join(projectDir, options.branch);
 
-  logger.info(`merge 命令执行，分支: ${options.branch}，提交信息: ${options.message ?? '(未提供)'}`);
+  logger.info(`merge 命令执行，分支: ${options.branch ?? '(未指定)'}，提交信息: ${options.message ?? '(未提供)'}`);
 
-  // 检查目标 worktree 是否存在
-  if (!existsSync(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
-  }
+  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, MERGE_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
 
   const projectName = getProjectName();
 
   // 步骤 3：主 worktree 状态检测
   if (!isWorkingDirClean(mainWorktreePath)) {
     // 如果存在 validate 快照状态，提示用户先清理
-    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);
   }
 
   // 步骤 3.5：检测是否需要 squash（sync 临时提交压缩）
-  const shouldExit = await handleSquashIfNeeded(targetWorktreePath, mainWorktreePath, options.branch, options.message);
+  const shouldExit = await handleSquashIfNeeded(targetWorktreePath, mainWorktreePath, branch, options.message);
   if (shouldExit) {
     return;
   }
@@ -165,7 +171,7 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     gitCommit(options.message, targetWorktreePath);
   } else {
     // 目标 worktree 干净，检查是否有本地提交
-    if (!hasLocalCommits(options.branch, mainWorktreePath)) {
+    if (!hasLocalCommits(branch, mainWorktreePath)) {
       throw new ClawtError(MESSAGES.TARGET_WORKTREE_NO_CHANGES);
     }
     // 有本地提交，跳过提交步骤，直接合并
@@ -173,7 +179,7 @@ async function handleMerge(options: MergeOptions): Promise<void> {
 
   // 步骤 5：回到主 worktree 进行合并
   try {
-    gitMerge(options.branch, mainWorktreePath);
+    gitMerge(branch, mainWorktreePath);
   } catch (error) {
     // 检查是否有冲突
     if (hasMergeConflict(mainWorktreePath)) {
@@ -198,19 +204,19 @@ async function handleMerge(options: MergeOptions): Promise<void> {
 
   // 步骤 8：输出成功提示（根据是否有 message 选择对应模板）
   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));
   }
 
   // 步骤 9：merge 成功后确认并清理 worktree 和分支
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
+  const shouldCleanup = await shouldCleanupAfterMerge(branch);
   if (shouldCleanup) {
-    cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
+    cleanupWorktreeAndBranch(targetWorktreePath, branch);
   }
 
   // 步骤 10：清理 validate 快照（merge 成功后快照已无意义）
-  if (hasSnapshot(projectName, options.branch)) {
-    removeSnapshot(projectName, options.branch);
+  if (hasSnapshot(projectName, branch)) {
+    removeSnapshot(projectName, branch);
   }
 }

package/src/commands/sync.ts

@@ -1,5 +1,3 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import type { Command } from 'commander';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
@@ -9,7 +7,7 @@ import {
   validateMainWorktree,
   getGitTopLevel,
   getProjectName,
-  getProjectWorktreeDir,
+  getProjectWorktrees,
   isWorkingDirClean,
   gitAddAll,
   gitCommit,
@@ -21,7 +19,9 @@ import {
   printSuccess,
   printInfo,
   printWarning,
+  resolveTargetWorktree,
 } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
 
 /**
  * 注册 sync 命令：将主分支最新代码同步到目标 worktree
@@ -31,12 +31,20 @@ export function registerSyncCommand(program: Command): void {
   program
     .command('sync')
     .description('将主分支最新代码同步到目标 worktree')
-    .requiredOption('-b, --branch <branchName>', '要同步的分支名')
+    .option('-b, --branch <branchName>', '要同步的分支名（支持模糊匹配，不传则列出所有分支）')
     .action(async (options: SyncOptions) => {
       await handleSync(options);
     });
 }
 
+/** sync 命令的分支解析消息配置 */
+const SYNC_RESOLVE_MESSAGES: WorktreeResolveMessages = {
+  noWorktrees: MESSAGES.SYNC_NO_WORKTREES,
+  selectBranch: MESSAGES.SYNC_SELECT_BRANCH,
+  multipleMatches: MESSAGES.SYNC_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.SYNC_NO_MATCH,
+};
+
 /**
  * 自动保存目标 worktree 中的未提交变更
  * @param {string} worktreePath - 目标 worktree 路径
@@ -77,16 +85,12 @@ function mergeMainBranch(worktreePath: string, mainBranch: string): boolean {
 async function handleSync(options: SyncOptions): Promise<void> {
   validateMainWorktree();
 
-  const { branch } = options;
-  logger.info(`sync 命令执行，分支: ${branch}`);
-
-  // 检查目标 worktree 是否存在
-  const projectWorktreeDir = getProjectWorktreeDir();
-  const targetWorktreePath = join(projectWorktreeDir, branch);
+  logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 
-  if (!existsSync(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
-  }
+  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
+  const { path: targetWorktreePath, branch } = worktree;
 
   // 获取主分支名（不硬编码 main/master）
   const mainWorktreePath = getGitTopLevel();

package/src/constants/messages.ts

@@ -128,4 +128,22 @@ export const MESSAGES = {
   VALIDATE_SELECT_BRANCH: '请选择要验证的分支',
   /** validate 模糊匹配到多个结果提示 */
   VALIDATE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** merge 无可用 worktree */
+  MERGE_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** merge 模糊匹配无结果，列出可用分支 */
+  MERGE_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** merge 交互选择提示 */
+  MERGE_SELECT_BRANCH: '请选择要合并的分支',
+  /** merge 模糊匹配到多个结果提示 */
+  MERGE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** sync 无可用 worktree */
+  SYNC_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** sync 模糊匹配无结果，列出可用分支 */
+  SYNC_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** sync 交互选择提示 */
+  SYNC_SELECT_BRANCH: '请选择要同步的分支',
+  /** sync 模糊匹配到多个结果提示 */
+  SYNC_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
 } as const;

package/src/types/command.ts

@@ -24,8 +24,8 @@ export interface ValidateOptions {
 
 /** merge 命令选项 */
 export interface MergeOptions {
-  /** 要合并的分支名 */
-  branch: string;
+  /** 要合并的分支名（可选，支持模糊匹配，不传则列出所有分支供选择） */
+  branch?: string;
   /** 提交信息（工作区有修改时必填） */
   message?: string;
 }
@@ -46,8 +46,8 @@ export interface ResumeOptions {
 
 /** sync 命令选项 */
 export interface SyncOptions {
-  /** 要同步的分支名 */
-  branch: string;
+  /** 要同步的分支名（可选，支持模糊匹配，不传则列出所有分支供选择） */
+  branch?: string;
 }
 
 /** list 命令选项 */