clawt 2.5.1 → 2.7.0

package/docs/spec.md

@@ -143,6 +143,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ├── validate-snapshots/                  # validate 快照目录
 │   └── <project-name>/                  # 以项目名分组
 │       ├── <branchName>.tree            # 每个分支一个 tree hash 快照文件（存储 git tree 对象的 hash）
+│       ├── <branchName>.head            # 每个分支一个 HEAD commit hash 快照文件（存储快照时主 worktree 的 HEAD commit hash）
 │       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
@@ -345,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 并删除快照）                            |
 
 > **限制：** 单次只能验证一个分支，不支持批量验证。
@@ -363,7 +368,7 @@ Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安
 
 **快照机制：**
 
-validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`）。当再次执行 validate 时，通过 `git read-tree` 将上次快照的 tree 对象载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。由于 tree 对象存储在 git 对象库中，不依赖主分支 HEAD，无需一致性校验。
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），同时将主 worktree 的 HEAD commit hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.head`），用于增量 validate 时对齐基准。当再次执行 validate 时，如果主分支 HEAD 未变化，通过 `git read-tree` 将上次快照的 tree 对象载入暂存区；如果主分支 HEAD 已变化（如合并了其他分支），则将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容。最终用户可通过 `git diff` 查看两次 validate 之间的增量差异。
 
 **运行流程：**
 
@@ -372,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 是否有未提交的更改。
@@ -444,11 +466,12 @@ git restore --staged .
 
 ##### 步骤 4：保存快照为 git tree 对象
 
-将主 worktree 工作目录的全量变更保存为 git tree 对象：
+将主 worktree 工作目录的全量变更保存为 git tree 对象，同时记录当前 HEAD commit hash：
 
 ```bash
 git add .
 git write-tree  # → 返回 tree hash，写入 ~/.clawt/validate-snapshots/<project>/<branchName>.tree
+git rev-parse HEAD  # → 返回 HEAD commit hash，写入 ~/.clawt/validate-snapshots/<project>/<branchName>.head
 git restore --staged .
 ```
 
@@ -465,9 +488,9 @@ git restore --staged .
 
 当 `~/.clawt/validate-snapshots/<project>/<branchName>.tree` 存在时，自动进入增量模式：
 
-##### 步骤 1：读取旧 tree hash
+##### 步骤 1：读取旧快照
 
-在清空主 worktree 之前，读取上次保存的快照 tree hash。
+在清空主 worktree 之前，读取上次保存的快照 tree hash 及当时的 HEAD commit hash。
 
 ##### 步骤 2：确保主 worktree 干净
 
@@ -479,9 +502,15 @@ git restore --staged .
 
 ##### 步骤 4：保存最新快照为 git tree 对象
 
-将最新全量变更保存为新的 tree 对象（覆盖旧快照，流程同首次 validate 的步骤 4）。
+将最新全量变更保存为新的 tree 对象（覆盖旧快照），同时记录当前 HEAD commit hash（流程同首次 validate 的步骤 4）。
+
+##### 步骤 5：将旧变更状态载入暂存区
+
+根据主分支 HEAD 是否发生变化，选择不同的策略将旧变更载入暂存区：
+
+**情况 A：HEAD 未变化（或旧版快照无 HEAD 信息）**
 
-##### 步骤 5：将旧 tree 对象载入暂存区
+直接通过 `git read-tree` 将旧 tree 对象载入暂存区：
 
 ```bash
 git read-tree <旧 tree hash>
@@ -490,6 +519,28 @@ git read-tree <旧 tree hash>
 - **读取成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
 - **读取失败**（tree 对象可能被 git gc 回收）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
 
+**情况 B：HEAD 发生了变化（如主分支合并了其他分支）**
+
+此时旧 tree 对象基于旧 HEAD，直接 read-tree 会导致 diff 混入 HEAD 变化的内容。需要将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上：
+
+```bash
+# 获取旧 HEAD 对应的 tree hash
+git rev-parse <旧 HEAD commit hash>^{tree}  # → 旧 HEAD tree hash
+
+# 提取旧变更 patch（旧 HEAD tree → 旧快照 tree 的差异）
+git diff-tree -p --binary <旧 HEAD tree hash> <旧快照 tree hash>
+
+# 检测 patch 能否无冲突地应用到暂存区
+git apply --cached --check < patch
+
+# 无冲突：apply --cached 到当前 HEAD 暂存区
+git apply --cached < patch
+```
+
+- **patch 为空**（旧变更为空）→ 暂存区保持干净
+- **无冲突** → apply --cached 到当前 HEAD 暂存区，结果与情况 A 一致
+- **有冲突** → 降级为全量模式（暂存区保持为空），等同于首次 validate 的结果
+
 ##### 步骤 6：输出成功提示
 
 ```
@@ -670,7 +721,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
 10. **清理 validate 快照**
-    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），自动删除该快照文件（merge 成功后快照已无意义）
+    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree` 和 `<branchName>.head`），自动删除这些快照文件（merge 成功后快照已无意义）
 
 > **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。
 
@@ -936,7 +987,7 @@ clawt sync -b <branchName>
        clawt validate -b <branch> 验证变更
      ```
    - **无冲突** → 继续
-7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 文件），自动删除（代码基础已变化，旧快照无效）
+7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
 8. **输出成功提示**：
    ```
    ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.5.1",
+  "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,
@@ -21,19 +19,34 @@ import {
   gitCleanForce,
   gitDiffBinaryAgainstBranch,
   gitApplyFromStdin,
+  gitApplyCachedFromStdin,
   gitResetSoft,
   gitWriteTree,
   gitReadTree,
+  getHeadCommitHash,
+  getCommitTreeHash,
+  gitDiffTree,
+  gitApplyCachedCheck,
   hasLocalCommits,
   hasSnapshot,
-  readSnapshotTreeHash,
+  readSnapshot,
   writeSnapshot,
   removeSnapshot,
   confirmDestructiveAction,
   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 验证其他分支的变更
@@ -43,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);
@@ -148,6 +161,7 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
 /**
  * 保存当前主 worktree 工作目录变更为 git tree 对象快照
  * 操作序列：git add . → git write-tree → git restore --staged .
+ * 同时保存当前 HEAD commit hash，用于增量 validate 时对齐基准
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
@@ -157,7 +171,8 @@ function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string,
   gitAddAll(mainWorktreePath);
   const treeHash = gitWriteTree(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash);
+  const headCommitHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
   return treeHash;
 }
 
@@ -171,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);
@@ -192,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));
 }
 
 /**
@@ -225,8 +245,8 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
 function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
-  // 步骤 1：读取旧 tree hash（在清空前读取）
-  const oldTreeHash = readSnapshotTreeHash(projectName, branchName);
+  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
 
   // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
   // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
@@ -238,12 +258,35 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   // 步骤 3：通过 patch 从目标分支获取最新全量变更
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
-  // 步骤 4：保存最新快照为 git tree 对象
+  // 步骤 4：保存最新快照为 git tree 对象（同时记录当前 HEAD）
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
 
-  // 步骤 5：将旧 tree 对象载入暂存区（恢复上次快照状态）
+  // 步骤 5：将旧变更状态载入暂存区
   try {
-    gitReadTree(oldTreeHash, mainWorktreePath);
+    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
+
+    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
+      // HEAD 发生了变化（如主分支合并了其他分支）：
+      // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
+      // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
+      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
+      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
+
+      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
+        // 无冲突：apply --cached 到当前 HEAD 暂存区
+        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
+      } else if (oldChangePatch.length > 0) {
+        // 有冲突：降级为全量模式（暂存区保持为空）
+        logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
+        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+        printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+        return;
+      }
+      // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
+    } else {
+      // HEAD 未变化（或旧版快照无 HEAD 信息）：直接 read-tree 旧快照
+      gitReadTree(oldTreeHash, mainWorktreePath);
+    }
   } catch (error) {
     // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
     logger.warn(`增量 read-tree 失败: ${error}`);
@@ -272,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);
@@ -292,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/git.ts

@@ -425,3 +425,43 @@ export function gitWriteTree(cwd?: string): string {
 export function gitReadTree(treeHash: string, cwd?: string): void {
   execCommand(`git read-tree ${treeHash}`, { cwd });
 }
+
+/**
+ * 获取指定 commit 对应的 tree 对象 hash
+ * @param {string} commitHash - commit hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} tree 对象的 hash
+ */
+export function getCommitTreeHash(commitHash: string, cwd?: string): string {
+  return execCommand(`git rev-parse ${commitHash}^{tree}`, { cwd });
+}
+
+/**
+ * 获取两个 tree 对象之间的 diff（patch 格式，含二进制）
+ * @param {string} baseTreeHash - 基准 tree hash
+ * @param {string} targetTreeHash - 目标 tree hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {Buffer} diff patch 内容
+ */
+export function gitDiffTree(baseTreeHash: string, targetTreeHash: string, cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync(`git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}`, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 检测 patch 能否无冲突地应用到暂存区（干运行，不实际修改）
+ * @param {Buffer} patchContent - patch 内容（Buffer 格式）
+ * @param {string} [cwd] - 工作目录
+ * @returns {boolean} patch 能否成功应用
+ */
+export function gitApplyCachedCheck(patchContent: Buffer, cwd?: string): boolean {
+  try {
+    execCommandWithInput('git', ['apply', '--cached', '--check'], { input: patchContent, cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/index.ts

@@ -40,6 +40,9 @@ export {
   gitResetSoftTo,
   gitWriteTree,
   gitReadTree,
+  getCommitTreeHash,
+  gitDiffTree,
+  gitApplyCachedCheck,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -49,4 +52,6 @@ export { printSuccess, printError, printWarning, printInfo, printSeparator, prin
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
-export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.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';