clawt 2.6.0 → 2.7.0

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

@@ -9,6 +9,7 @@
 - merge 命令对应 `5.6 合并验证过的分支`，流程按步骤编号描述
 - config 命令对应 `5.10 查看全局配置`，只读展示配置
 - resume 命令对应 `5.11 在已有 Worktree 中恢复会话`，支持模糊匹配和交互式分支选择（-b 可选）
+- validate 命令对应 `5.4 在主 Worktree 验证其他分支`，-b 可选，支持模糊匹配（与 resume 共享匹配逻辑）
 - 配置项说明在 `5.7 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
@@ -65,8 +66,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 共用的分支匹配函数（在 src/utils/worktree-matcher.ts）
+- `WorktreeResolveMessages` 接口实现命令间消息解耦，每个命令传入各自的提示文案
+- resume 的消息常量在 `MESSAGES.RESUME_*`，validate 的消息常量在 `MESSAGES.VALIDATE_*`
+- resume 和 validate 的 `-b` 参数均为可选，匹配策略一致：精确→模糊（子串，大小写不敏感）→交互选择
+- validate 的交互式选择和 resume 使用同一个 `promptSelectBranch()`（Enquirer.Select）
 
 ## validate 快照机制
 

package/README.md

@@ -107,29 +107,44 @@ 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

package/dist/index.js

@@ -134,7 +134,17 @@ ${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`
 };
 
 // src/constants/exitCodes.ts
@@ -742,6 +752,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 +1113,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 +1225,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 +1243,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,35 +1291,34 @@ 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";
+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) => {
     await handleMerge(options);
@@ -1336,9 +1360,9 @@ async function handleMerge(options) {
   validateMainWorktree();
   const mainWorktreePath = getGitTopLevel();
   const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join5(projectDir, options.branch);
+  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 (!existsSync7(targetWorktreePath)) {
+  if (!existsSync6(targetWorktreePath)) {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
   const projectName = getProjectName();
@@ -1431,8 +1455,8 @@ function formatConfigValue(value) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync8 } from "fs";
-import { join as join6 } from "path";
+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) => {
     await handleSync(options);
@@ -1460,8 +1484,8 @@ async function handleSync(options) {
   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)) {
+  const targetWorktreePath = join5(projectWorktreeDir, branch);
+  if (!existsSync7(targetWorktreePath)) {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
   }
   const mainWorktreePath = getGitTopLevel();

package/docs/spec.md

@@ -346,14 +346,18 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 **命令：**
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt validate -b <branchName> [--clean]
+
+# 不指定分支名（列出所有分支供选择）
+clawt validate [--clean]
 ```
 
 **参数：**
 
 | 参数      | 必填 | 说明                                                                     |
 | --------- | ---- | ------------------------------------------------------------------------ |
-| `-b`      | 是   | 要验证的 worktree 分支名（例如 `feature-scheme-1`）                        |
+| `-b`      | 否   | 要验证的 worktree 分支名（支持模糊匹配，不传则列出所有分支供选择）           |
 | `--clean` | 否   | 清理 validate 状态（重置主 worktree 并删除快照）                            |
 
 > **限制：** 单次只能验证一个分支，不支持批量验证。
@@ -373,13 +377,30 @@ validate 命令引入了**快照（snapshot）机制**来支持增量对比。
 当指定 `--clean` 选项时，执行清理逻辑后直接返回，不进入常规 validate 流程：
 
 1. **主 worktree 校验** (2.1)
-2. 如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
-3. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
-4. 删除对应分支的快照文件
-5. 输出清理成功提示
+2. **解析目标 worktree**：通过模糊匹配解析目标分支（匹配策略同下文常规 validate 流程中的描述）
+3. 如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
+4. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
+5. 删除对应分支的快照文件
+6. 输出清理成功提示
 
 #### 首次 validate（无历史快照）
 
+##### 步骤 0：解析目标 worktree
+
+根据 `-b` 参数解析目标 worktree，匹配策略如下：
+
+- **未传 `-b` 参数**：
+  - 获取当前项目所有 worktree
+  - 无可用 worktree → 报错退出
+  - 仅 1 个 worktree → 直接使用，无需选择
+  - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
+- **传了 `-b` 参数**：
+  1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+  2. **模糊匹配**（子串匹配，大小写不敏感）：
+     - 唯一匹配 → 直接使用
+     - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
+  3. **无匹配** → 报错退出，并列出所有可用分支名
+
 ##### 步骤 1：检测主 worktree 工作区状态
 
 执行 `git status --porcelain`，判断主 worktree 是否有未提交的更改。

package/package.json

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

package/src/commands/resume.ts

@@ -1,15 +1,23 @@
 import type { Command } from 'commander';
-import Enquirer from 'enquirer';
 import { logger } from '../logger/index.js';
-import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
-import type { ResumeOptions, WorktreeInfo } from '../types/index.js';
+import type { ResumeOptions } from '../types/index.js';
 import {
   validateMainWorktree,
   validateClaudeCodeInstalled,
   getProjectWorktrees,
   launchInteractiveClaude,
+  resolveTargetWorktree,
 } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
+
+/** resume 命令的分支解析消息配置 */
+const RESUME_RESOLVE_MESSAGES: WorktreeResolveMessages = {
+  noWorktrees: MESSAGES.RESUME_NO_WORKTREES,
+  selectBranch: MESSAGES.RESUME_SELECT_BRANCH,
+  multipleMatches: MESSAGES.RESUME_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.RESUME_NO_MATCH,
+};
 
 /**
  * 注册 resume 命令：在已有 worktree 中恢复 Claude Code 会话
@@ -25,95 +33,6 @@ export function registerResumeCommand(program: Command): void {
     });
 }
 
-/**
- * 在 worktree 列表中精确匹配分支名
- * @param {WorktreeInfo[]} worktrees - worktree 列表
- * @param {string} branchName - 目标分支名
- * @returns {WorktreeInfo | undefined} 匹配的 worktree，未找到返回 undefined
- */
-function findExactMatch(worktrees: WorktreeInfo[], branchName: string): WorktreeInfo | undefined {
-  return worktrees.find((wt) => wt.branch === branchName);
-}
-
-/**
- * 在 worktree 列表中进行模糊匹配（子串匹配，大小写不敏感）
- * @param {WorktreeInfo[]} worktrees - worktree 列表
- * @param {string} keyword - 匹配关键词
- * @returns {WorktreeInfo[]} 匹配到的 worktree 列表
- */
-function findFuzzyMatches(worktrees: WorktreeInfo[], keyword: string): WorktreeInfo[] {
-  const lowerKeyword = keyword.toLowerCase();
-  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
-}
-
-/**
- * 通过交互式列表让用户从 worktree 列表中选择一个分支
- * @param {WorktreeInfo[]} worktrees - 可供选择的 worktree 列表
- * @param {string} message - 选择提示信息
- * @returns {Promise<WorktreeInfo>} 用户选择的 worktree
- */
-async function promptSelectBranch(worktrees: WorktreeInfo[], message: string): Promise<WorktreeInfo> {
-  // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
-  const selectedBranch: string = await new Enquirer.Select({
-    message,
-    choices: worktrees.map((wt) => ({
-      name: wt.branch,
-      message: wt.branch,
-    })),
-  }).run();
-
-  return worktrees.find((wt) => wt.branch === selectedBranch)!;
-}
-
-/**
- * 根据用户输入解析目标 worktree
- * 匹配策略：精确匹配 → 模糊匹配（唯一直接使用，多个交互选择） → 无匹配报错
- * 不传分支名时列出所有可用分支供选择
- * @param {string} [branchName] - 用户输入的分支名（可选）
- * @returns {Promise<WorktreeInfo>} 解析后的目标 worktree
- * @throws {ClawtError} 无可用 worktree 或无匹配结果时抛出
- */
-async function resolveTargetWorktree(branchName?: string): Promise<WorktreeInfo> {
-  const worktrees = getProjectWorktrees();
-
-  // 无可用 worktree，直接报错
-  if (worktrees.length === 0) {
-    throw new ClawtError(MESSAGES.RESUME_NO_WORKTREES);
-  }
-
-  // 未传 -b 参数：列出所有分支供选择
-  if (!branchName) {
-    // 只有一个 worktree 时直接使用，无需选择
-    if (worktrees.length === 1) {
-      return worktrees[0];
-    }
-    return promptSelectBranch(worktrees, MESSAGES.RESUME_SELECT_BRANCH);
-  }
-
-  // 1. 精确匹配优先
-  const exactMatch = findExactMatch(worktrees, branchName);
-  if (exactMatch) {
-    return exactMatch;
-  }
-
-  // 2. 模糊匹配
-  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
-
-  // 2a. 唯一匹配，直接使用
-  if (fuzzyMatches.length === 1) {
-    return fuzzyMatches[0];
-  }
-
-  // 2b. 多个匹配，交互选择
-  if (fuzzyMatches.length > 1) {
-    return promptSelectBranch(fuzzyMatches, MESSAGES.RESUME_MULTIPLE_MATCHES(branchName));
-  }
-
-  // 3. 无匹配，抛出错误并列出所有可用分支
-  const allBranches = worktrees.map((wt) => wt.branch);
-  throw new ClawtError(MESSAGES.RESUME_NO_MATCH(branchName, allBranches));
-}
-
 /**
  * 执行 resume 命令的核心逻辑
  * 解析目标 worktree 并恢复 Claude Code 会话
@@ -126,7 +45,8 @@ async function handleResume(options: ResumeOptions): Promise<void> {
   logger.info(`resume 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 
   // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
-  const worktree = await resolveTargetWorktree(options.branch);
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, RESUME_RESOLVE_MESSAGES, options.branch);
 
   // 启动 Claude Code 交互式界面
   launchInteractiveClaude(worktree);

package/src/commands/validate.ts

@@ -1,6 +1,4 @@
 import type { Command } from 'commander';
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
 import Enquirer from 'enquirer';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
@@ -10,7 +8,7 @@ import {
   validateMainWorktree,
   getProjectName,
   getGitTopLevel,
-  getProjectWorktreeDir,
+  getProjectWorktrees,
   getConfigValue,
   isWorkingDirClean,
   gitAddAll,
@@ -38,7 +36,17 @@ import {
   printSuccess,
   printWarning,
   printInfo,
+  resolveTargetWorktree,
 } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
+
+/** validate 命令的分支解析消息配置 */
+const VALIDATE_RESOLVE_MESSAGES: WorktreeResolveMessages = {
+  noWorktrees: MESSAGES.VALIDATE_NO_WORKTREES,
+  selectBranch: MESSAGES.VALIDATE_SELECT_BRANCH,
+  multipleMatches: MESSAGES.VALIDATE_MULTIPLE_MATCHES,
+  noMatch: MESSAGES.VALIDATE_NO_MATCH,
+};
 
 /**
  * 注册 validate 命令：在主 worktree 验证其他分支的变更
@@ -48,7 +56,7 @@ export function registerValidateCommand(program: Command): void {
   program
     .command('validate')
     .description('在主 worktree 验证某个 worktree 分支的变更')
-    .requiredOption('-b, --branch <branchName>', '要验证的分支名')
+    .option('-b, --branch <branchName>', '要验证的分支名（支持模糊匹配，不传则列出所有分支）')
     .option('--clean', '清理 validate 状态（重置主 worktree 并删除快照）')
     .action(async (options: ValidateOptions) => {
       await handleValidate(options);
@@ -178,13 +186,18 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
 
-  logger.info(`validate --clean 执行，分支: ${options.branch}`);
+  // 通过模糊匹配解析目标 worktree
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, VALIDATE_RESOLVE_MESSAGES, options.branch);
+  const branchName = worktree.branch;
+
+  logger.info(`validate --clean 执行，分支: ${branchName}`);
 
   // 根据配置决定是否需要确认
   if (getConfigValue('confirmDestructiveOps')) {
     const confirmed = await confirmDestructiveAction(
       'git reset --hard + git clean -fd',
-      `重置主 worktree 并删除分支 ${options.branch} 的 validate 快照`,
+      `重置主 worktree 并删除分支 ${branchName} 的 validate 快照`,
     );
     if (!confirmed) {
       printInfo(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
@@ -199,9 +212,9 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
   }
 
   // 删除对应的快照文件
-  removeSnapshot(projectName, options.branch);
+  removeSnapshot(projectName, branchName);
 
-  printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
+  printSuccess(MESSAGES.VALIDATE_CLEANED(branchName));
 }
 
 /**
@@ -302,19 +315,18 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
-  const projectDir = getProjectWorktreeDir();
-  const targetWorktreePath = join(projectDir, options.branch);
 
-  logger.info(`validate 命令执行，分支: ${options.branch}`);
+  // 通过模糊匹配解析目标 worktree
+  const worktrees = getProjectWorktrees();
+  const worktree = await resolveTargetWorktree(worktrees, VALIDATE_RESOLVE_MESSAGES, options.branch);
+  const branchName = worktree.branch;
+  const targetWorktreePath = worktree.path;
 
-  // 检查目标 worktree 是否存在
-  if (!existsSync(targetWorktreePath)) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
-  }
+  logger.info(`validate 命令执行，分支: ${branchName}`);
 
   // 统一检测未提交修改 + 已提交 commit
   const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
-  const hasCommitted = hasLocalCommits(options.branch, mainWorktreePath);
+  const hasCommitted = hasLocalCommits(branchName, mainWorktreePath);
 
   if (!hasUncommitted && !hasCommitted) {
     printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
@@ -322,20 +334,20 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
   }
 
   // 判断是否为增量 validate（tree 对象不依赖主分支 HEAD，无需一致性校验）
-  const isIncremental = hasSnapshot(projectName, options.branch);
+  const isIncremental = hasSnapshot(projectName, branchName);
 
   if (isIncremental) {
     // 增量模式：主 worktree 有残留状态时让用户选择处理方式
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
-    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   } else {
     // 首次模式：先确保主 worktree 干净
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
     }
 
-    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
 }

package/src/constants/messages.ts

@@ -119,4 +119,13 @@ export const MESSAGES = {
   RESUME_SELECT_BRANCH: '请选择要恢复的分支',
   /** resume 模糊匹配到多个结果提示 */
   RESUME_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** validate 无可用 worktree */
+  VALIDATE_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** validate 模糊匹配无结果，列出可用分支 */
+  VALIDATE_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** validate 交互选择提示 */
+  VALIDATE_SELECT_BRANCH: '请选择要验证的分支',
+  /** validate 模糊匹配到多个结果提示 */
+  VALIDATE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
 } as const;

package/src/types/command.ts

@@ -16,8 +16,8 @@ export interface RunOptions {
 
 /** validate 命令选项 */
 export interface ValidateOptions {
-  /** 要验证的分支名 */
-  branch: string;
+  /** 要验证的分支名（可选，支持模糊匹配，不传则列出所有分支供选择） */
+  branch?: string;
   /** 清理 validate 状态 */
   clean?: boolean;
 }

package/src/utils/index.ts

@@ -53,3 +53,5 @@ export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
 export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';
+export { findExactMatch, findFuzzyMatches, promptSelectBranch, resolveTargetWorktree } from './worktree-matcher.js';
+export type { WorktreeResolveMessages } from './worktree-matcher.js';

package/src/utils/worktree-matcher.ts

@@ -0,0 +1,111 @@
+import Enquirer from 'enquirer';
+import { ClawtError } from '../errors/index.js';
+import type { WorktreeInfo } from '../types/index.js';
+
+/**
+ * 分支解析时使用的消息文案配置
+ * 通过此接口实现命令间的消息解耦，不同命令可传入各自的提示文案
+ */
+export interface WorktreeResolveMessages {
+  /** 无可用 worktree 时的错误消息 */
+  noWorktrees: string;
+  /** 未传分支名时的交互选择提示 */
+  selectBranch: string;
+  /** 模糊匹配到多个结果时的交互选择提示 */
+  multipleMatches: (keyword: string) => string;
+  /** 无匹配结果时的错误消息 */
+  noMatch: (keyword: string, branches: string[]) => string;
+}
+
+/**
+ * 在 worktree 列表中精确匹配分支名
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
+ * @param {string} branchName - 目标分支名
+ * @returns {WorktreeInfo | undefined} 匹配的 worktree，未找到返回 undefined
+ */
+export function findExactMatch(worktrees: WorktreeInfo[], branchName: string): WorktreeInfo | undefined {
+  return worktrees.find((wt) => wt.branch === branchName);
+}
+
+/**
+ * 在 worktree 列表中进行模糊匹配（子串匹配，大小写不敏感）
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
+ * @param {string} keyword - 匹配关键词
+ * @returns {WorktreeInfo[]} 匹配到的 worktree 列表
+ */
+export function findFuzzyMatches(worktrees: WorktreeInfo[], keyword: string): WorktreeInfo[] {
+  const lowerKeyword = keyword.toLowerCase();
+  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
+}
+
+/**
+ * 通过交互式列表让用户从 worktree 列表中选择一个分支
+ * @param {WorktreeInfo[]} worktrees - 可供选择的 worktree 列表
+ * @param {string} message - 选择提示信息
+ * @returns {Promise<WorktreeInfo>} 用户选择的 worktree
+ */
+export async function promptSelectBranch(worktrees: WorktreeInfo[], message: string): Promise<WorktreeInfo> {
+  // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
+  const selectedBranch: string = await new Enquirer.Select({
+    message,
+    choices: worktrees.map((wt) => ({
+      name: wt.branch,
+      message: wt.branch,
+    })),
+  }).run();
+
+  return worktrees.find((wt) => wt.branch === selectedBranch)!;
+}
+
+/**
+ * 根据用户输入解析目标 worktree
+ * 匹配策略：精确匹配 → 模糊匹配（唯一直接使用，多个交互选择） → 无匹配报错
+ * 不传分支名时列出所有可用分支供选择
+ * @param {WorktreeInfo[]} worktrees - 可用的 worktree 列表
+ * @param {WorktreeResolveMessages} messages - 命令专属的消息文案
+ * @param {string} [branchName] - 用户输入的分支名（可选）
+ * @returns {Promise<WorktreeInfo>} 解析后的目标 worktree
+ * @throws {ClawtError} 无可用 worktree 或无匹配结果时抛出
+ */
+export async function resolveTargetWorktree(
+  worktrees: WorktreeInfo[],
+  messages: WorktreeResolveMessages,
+  branchName?: string,
+): Promise<WorktreeInfo> {
+  // 无可用 worktree，直接报错
+  if (worktrees.length === 0) {
+    throw new ClawtError(messages.noWorktrees);
+  }
+
+  // 未传 -b 参数：列出所有分支供选择
+  if (!branchName) {
+    // 只有一个 worktree 时直接使用，无需选择
+    if (worktrees.length === 1) {
+      return worktrees[0];
+    }
+    return promptSelectBranch(worktrees, messages.selectBranch);
+  }
+
+  // 1. 精确匹配优先
+  const exactMatch = findExactMatch(worktrees, branchName);
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  // 2. 模糊匹配
+  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
+
+  // 2a. 唯一匹配，直接使用
+  if (fuzzyMatches.length === 1) {
+    return fuzzyMatches[0];
+  }
+
+  // 2b. 多个匹配，交互选择
+  if (fuzzyMatches.length > 1) {
+    return promptSelectBranch(fuzzyMatches, messages.multipleMatches(branchName));
+  }
+
+  // 3. 无匹配，抛出错误并列出所有可用分支
+  const allBranches = worktrees.map((wt) => wt.branch);
+  throw new ClawtError(messages.noMatch(branchName, allBranches));
+}