clawt 3.2.1 → 3.4.0

package/README.md

@@ -148,6 +148,14 @@ clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命
 | `-r "npm lint && npm test"` | `&&` 不拆分，同步执行 |
 | `-r "pnpm test & pnpm build"` | 并行执行，等全部完成后汇总结果 |
 
+### `clawt cover` — 将验证分支修改覆盖回目标 worktree
+
+```bash
+clawt cover    # 在验证分支上执行，自动推导目标分支
+```
+
+在 validate 验证过程中，如果在主 worktree（验证分支上）修改了代码，可通过 `cover` 将修改覆盖回目标 worktree。当工作区无修改时会提示确认，避免误操作。
+
 ### `clawt sync` — 同步主分支代码到目标 worktree
 
 ```bash
@@ -203,6 +211,14 @@ clawt status -i       # 交互式面板模式（实时刷新，支持键盘导
 clawt reset
 ```
 
+### `clawt home` — 切换回主工作分支
+
+```bash
+clawt home
+```
+
+如果当前已在主工作分支上，会提示无需切换。
+
 ### `clawt projects` — 跨项目 worktree 概览
 
 ```bash

package/dist/index.js

@@ -473,6 +473,34 @@ var INIT_MESSAGES = {
   INIT_SET_SUCCESS: (key, value) => `\u2713 \u9879\u76EE\u914D\u7F6E ${key} \u5DF2\u8BBE\u7F6E\u4E3A ${value}`
 };
 
+// src/constants/messages/cover-validate.ts
+var COVER_VALIDATE_MESSAGES = {
+  /** 当前不在验证分支上 */
+  COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH: "\u5F53\u524D\u5206\u652F\u4E0D\u662F\u9A8C\u8BC1\u5206\u652F\uFF08\u9700\u4EE5 clawt-validate- \u5F00\u5934\uFF09\n  \u8BF7\u5148\u901A\u8FC7 clawt validate \u5207\u6362\u5230\u9A8C\u8BC1\u5206\u652F",
+  /** 无增量修改 */
+  COVER_VALIDATE_NO_CHANGES: "\u9A8C\u8BC1\u5206\u652F\u4E0A\u6CA1\u6709\u76F8\u5BF9\u4E8E\u5FEB\u7167\u7684\u589E\u91CF\u4FEE\u6539\uFF0C\u65E0\u9700\u8986\u76D6",
+  /** 目标 worktree 不存在 */
+  COVER_VALIDATE_TARGET_NOT_FOUND: (branch) => `\u672A\u627E\u5230\u5206\u652F ${branch} \u5BF9\u5E94\u7684 worktree\uFF0C\u8BF7\u786E\u8BA4\u8BE5 worktree \u5C1A\u672A\u88AB\u79FB\u9664`,
+  /** 无快照，提示先执行 validate */
+  COVER_VALIDATE_NO_SNAPSHOT: (branch) => `\u672A\u627E\u5230\u5206\u652F ${branch} \u7684 validate \u5FEB\u7167
+  \u8BF7\u5148\u6267\u884C clawt validate -b ${branch} \u521B\u5EFA\u5FEB\u7167`,
+  /** patch 应用失败 */
+  COVER_VALIDATE_APPLY_FAILED: (branch) => `\u8986\u76D6\u53D8\u66F4\u5230 worktree ${branch} \u5931\u8D25\uFF1Apatch \u5E94\u7528\u51FA\u9519
+  \u8BF7\u68C0\u67E5\u76EE\u6807 worktree \u5DE5\u4F5C\u533A\u72B6\u6001\u540E\u91CD\u8BD5`,
+  /** 工作区和暂存区无修改，可能为误操作 */
+  COVER_VALIDATE_WORKING_DIR_CLEAN: "\u5F53\u524D\u9A8C\u8BC1\u5206\u652F\u7684\u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\u6CA1\u6709\u4EFB\u4F55\u4FEE\u6539\uFF0C\u53EF\u80FD\u4E3A\u8BEF\u64CD\u4F5C",
+  /** 覆盖成功 */
+  COVER_VALIDATE_SUCCESS: (branch) => `\u2713 \u5DF2\u5C06\u9A8C\u8BC1\u5206\u652F\u4E0A\u7684\u4FEE\u6539\u8986\u76D6\u5230 worktree => ${branch}`
+};
+
+// src/constants/messages/home.ts
+var HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch) => `\u5DF2\u5728\u4E3B\u5DE5\u4F5C\u5206\u652F ${branch} \u4E0A\uFF0C\u65E0\u9700\u5207\u6362`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from, to) => `\u2713 \u5DF2\u4ECE ${from} \u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${to}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -545,7 +573,9 @@ var MESSAGES = {
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
-  ...INIT_MESSAGES
+  ...INIT_MESSAGES,
+  ...COVER_VALIDATE_MESSAGES,
+  ...HOME_MESSAGES
 };
 
 // src/constants/exitCodes.ts
@@ -1700,16 +1730,19 @@ function readSnapshot(projectName, branchName) {
   const stagedTreeHash = existsSync8(stagedPath) ? readFileSync3(stagedPath, "utf-8").trim() : "";
   return { treeHash, headCommitHash, stagedTreeHash };
 }
-function writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash = "") {
-  const snapshotPath = getSnapshotPath(projectName, branchName);
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  const stagedPath = getSnapshotStagedPath(projectName, branchName);
+function writeSnapshot(projectName, branchName, treeHash, headCommitHash, stagedTreeHash) {
   const snapshotDir = join6(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
-  writeFileSync3(snapshotPath, treeHash, "utf-8");
-  writeFileSync3(headPath, headCommitHash, "utf-8");
-  writeFileSync3(stagedPath, stagedTreeHash, "utf-8");
-  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}, ${headPath}, ${stagedPath}`);
+  if (treeHash !== void 0) {
+    writeFileSync3(getSnapshotPath(projectName, branchName), treeHash, "utf-8");
+  }
+  if (headCommitHash !== void 0) {
+    writeFileSync3(getSnapshotHeadPath(projectName, branchName), headCommitHash, "utf-8");
+  }
+  if (stagedTreeHash !== void 0) {
+    writeFileSync3(getSnapshotStagedPath(projectName, branchName), stagedTreeHash, "utf-8");
+  }
+  logger.info(`\u5DF2\u5199\u5165 validate \u5FEB\u7167 (project=${projectName}, branch=${branchName})`);
 }
 function removeSnapshot(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
@@ -4065,11 +4098,6 @@ async function executeSyncForBranch(targetWorktreePath, branch) {
     printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
     return { success: false, hasConflict: true };
   }
-  const projectName = getProjectName();
-  if (hasSnapshot(projectName, branch)) {
-    removeSnapshot(projectName, branch);
-    logger.info(`\u5DF2\u6E05\u9664\u5206\u652F ${branch} \u7684 validate \u5FEB\u7167`);
-  }
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
   await rebuildValidateBranch(branch, mainWorktreePath);
   const validateBranchName = getValidateBranchName(branch);
@@ -4230,6 +4258,74 @@ async function handleValidate(options) {
   }
 }
 
+// src/commands/cover-validate.ts
+function registerCoverValidateCommand(program2) {
+  program2.command("cover").description("\u5C06\u9A8C\u8BC1\u5206\u652F\u4E0A\u7684\u4FEE\u6539\u8986\u76D6\u56DE\u76EE\u6807 worktree\uFF08\u81EA\u52A8\u63A8\u5BFC\u76EE\u6807\u5206\u652F\uFF09").action(async () => {
+    await handleCoverValidate();
+  });
+}
+function extractTargetBranchName(currentBranch) {
+  return currentBranch.slice(VALIDATE_BRANCH_PREFIX.length);
+}
+function findTargetWorktreePath(branchName) {
+  const worktrees = getProjectWorktrees();
+  const match = findExactMatch(worktrees, branchName);
+  if (!match) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_TARGET_NOT_FOUND(branchName));
+  }
+  return match.path;
+}
+function computeIncrementalPatch(snapshotTreeHash, mainWorktreePath) {
+  const savedIndexTreeHash = gitWriteTree(mainWorktreePath);
+  let currentTreeHash;
+  try {
+    gitAddAll(mainWorktreePath);
+    currentTreeHash = gitWriteTree(mainWorktreePath);
+  } finally {
+    gitReadTree(savedIndexTreeHash, mainWorktreePath);
+  }
+  if (snapshotTreeHash === currentTreeHash) {
+    return null;
+  }
+  const patch = gitDiffTree(snapshotTreeHash, currentTreeHash, mainWorktreePath);
+  return { patch, currentTreeHash };
+}
+async function handleCoverValidate() {
+  validateMainWorktree();
+  requireProjectConfig();
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+  const currentBranch = getCurrentBranch(mainWorktreePath);
+  if (!currentBranch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH);
+  }
+  const targetBranchName = extractTargetBranchName(currentBranch);
+  logger.info(`cover-validate \u547D\u4EE4\u6267\u884C\uFF0C\u76EE\u6807\u5206\u652F: ${targetBranchName}`);
+  const targetWorktreePath = findTargetWorktreePath(targetBranchName);
+  if (!hasSnapshot(projectName, targetBranchName)) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_NO_SNAPSHOT(targetBranchName));
+  }
+  const { treeHash: snapshotTreeHash } = readSnapshot(projectName, targetBranchName);
+  if (isWorkingDirClean(mainWorktreePath)) {
+    printInfo(MESSAGES.COVER_VALIDATE_WORKING_DIR_CLEAN);
+    const confirmed = await confirmAction("\u662F\u5426\u7EE7\u7EED\u6267\u884C\u8986\u76D6\uFF1F");
+    if (!confirmed) return;
+  }
+  const result = computeIncrementalPatch(snapshotTreeHash, mainWorktreePath);
+  if (!result) {
+    printInfo(MESSAGES.COVER_VALIDATE_NO_CHANGES);
+    return;
+  }
+  try {
+    gitApplyFromStdin(result.patch, targetWorktreePath);
+  } catch (error) {
+    logger.error(`cover-validate patch apply \u5931\u8D25: ${error}`);
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_APPLY_FAILED(targetBranchName));
+  }
+  writeSnapshot(projectName, targetBranchName, result.currentTreeHash);
+  printSuccess(MESSAGES.COVER_VALIDATE_SUCCESS(targetBranchName));
+}
+
 // src/commands/merge.ts
 function registerMergeCommand(program2) {
   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\u4F9B\u9009\u62E9\uFF09").option("-m, --message <commitMessage>", "\u63D0\u4EA4\u4FE1\u606F\uFF08\u76EE\u6807 worktree \u5DE5\u4F5C\u533A\u6709\u4FEE\u6539\u65F6\u5FC5\u586B\uFF09").action(async (options) => {
@@ -5158,6 +5254,25 @@ async function handleInit(options) {
   }
 }
 
+// src/commands/home.ts
+function registerHomeCommand(program2) {
+  program2.command("home").description("\u5207\u6362\u56DE\u4E3B\u5DE5\u4F5C\u5206\u652F").action(async () => {
+    await handleHome();
+  });
+}
+async function handleHome() {
+  validateMainWorktree();
+  requireProjectConfig();
+  const mainBranch = getMainWorkBranch();
+  const currentBranch = getCurrentBranch();
+  if (currentBranch === mainBranch) {
+    printInfo(MESSAGES.HOME_ALREADY_ON_MAIN(mainBranch));
+    return;
+  }
+  await ensureOnMainWorkBranch();
+  printSuccess(MESSAGES.HOME_SWITCH_SUCCESS(currentBranch, mainBranch));
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -5175,6 +5290,7 @@ registerRemoveCommand(program);
 registerRunCommand(program);
 registerResumeCommand(program);
 registerValidateCommand(program);
+registerCoverValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
@@ -5184,6 +5300,7 @@ registerAliasCommand(program);
 registerProjectsCommand(program);
 registerCompletionCommand(program);
 registerInitCommand(program);
+registerHomeCommand(program);
 var config = loadConfig();
 applyAliases(program, config.aliases);
 process.on("uncaughtException", (error) => {

package/dist/postinstall.js

@@ -450,6 +450,34 @@ var INIT_MESSAGES = {
   INIT_SET_SUCCESS: (key, value) => `\u2713 \u9879\u76EE\u914D\u7F6E ${key} \u5DF2\u8BBE\u7F6E\u4E3A ${value}`
 };
 
+// src/constants/messages/cover-validate.ts
+var COVER_VALIDATE_MESSAGES = {
+  /** 当前不在验证分支上 */
+  COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH: "\u5F53\u524D\u5206\u652F\u4E0D\u662F\u9A8C\u8BC1\u5206\u652F\uFF08\u9700\u4EE5 clawt-validate- \u5F00\u5934\uFF09\n  \u8BF7\u5148\u901A\u8FC7 clawt validate \u5207\u6362\u5230\u9A8C\u8BC1\u5206\u652F",
+  /** 无增量修改 */
+  COVER_VALIDATE_NO_CHANGES: "\u9A8C\u8BC1\u5206\u652F\u4E0A\u6CA1\u6709\u76F8\u5BF9\u4E8E\u5FEB\u7167\u7684\u589E\u91CF\u4FEE\u6539\uFF0C\u65E0\u9700\u8986\u76D6",
+  /** 目标 worktree 不存在 */
+  COVER_VALIDATE_TARGET_NOT_FOUND: (branch) => `\u672A\u627E\u5230\u5206\u652F ${branch} \u5BF9\u5E94\u7684 worktree\uFF0C\u8BF7\u786E\u8BA4\u8BE5 worktree \u5C1A\u672A\u88AB\u79FB\u9664`,
+  /** 无快照，提示先执行 validate */
+  COVER_VALIDATE_NO_SNAPSHOT: (branch) => `\u672A\u627E\u5230\u5206\u652F ${branch} \u7684 validate \u5FEB\u7167
+  \u8BF7\u5148\u6267\u884C clawt validate -b ${branch} \u521B\u5EFA\u5FEB\u7167`,
+  /** patch 应用失败 */
+  COVER_VALIDATE_APPLY_FAILED: (branch) => `\u8986\u76D6\u53D8\u66F4\u5230 worktree ${branch} \u5931\u8D25\uFF1Apatch \u5E94\u7528\u51FA\u9519
+  \u8BF7\u68C0\u67E5\u76EE\u6807 worktree \u5DE5\u4F5C\u533A\u72B6\u6001\u540E\u91CD\u8BD5`,
+  /** 工作区和暂存区无修改，可能为误操作 */
+  COVER_VALIDATE_WORKING_DIR_CLEAN: "\u5F53\u524D\u9A8C\u8BC1\u5206\u652F\u7684\u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\u6CA1\u6709\u4EFB\u4F55\u4FEE\u6539\uFF0C\u53EF\u80FD\u4E3A\u8BEF\u64CD\u4F5C",
+  /** 覆盖成功 */
+  COVER_VALIDATE_SUCCESS: (branch) => `\u2713 \u5DF2\u5C06\u9A8C\u8BC1\u5206\u652F\u4E0A\u7684\u4FEE\u6539\u8986\u76D6\u5230 worktree => ${branch}`
+};
+
+// src/constants/messages/home.ts
+var HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch) => `\u5DF2\u5728\u4E3B\u5DE5\u4F5C\u5206\u652F ${branch} \u4E0A\uFF0C\u65E0\u9700\u5207\u6362`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from, to) => `\u2713 \u5DF2\u4ECE ${from} \u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${to}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -502,7 +530,9 @@ var MESSAGES = {
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
-  ...INIT_MESSAGES
+  ...INIT_MESSAGES,
+  ...COVER_VALIDATE_MESSAGES,
+  ...HOME_MESSAGES
 };
 
 // src/constants/terminal.ts

package/docs/cover-validate.md

@@ -0,0 +1,93 @@
+### 5.21 将验证分支修改覆盖回目标 Worktree
+
+**命令：**
+
+```bash
+clawt cover
+```
+
+> 无需指定分支名，自动从当前验证分支名（`clawt-validate-<branchName>`）中推导目标分支。
+
+**参数：**
+
+无额外参数。必须在验证分支上执行。
+
+**使用场景：**
+
+在 `validate` 验证过程中，用户可能会在主 worktree（验证分支上）对代码进行修改（如修复测试失败、调整逻辑等）。`cover` 命令用于将这些修改覆盖回目标 worktree，使目标 worktree 的代码与验证分支上的最新状态同步。
+
+**运行流程：**
+
+##### 步骤 1：前置校验
+
+1. **主 worktree 校验**（2.1）
+2. **项目级配置校验**（`requireProjectConfig`）
+3. **验证分支校验**：当前分支必须以 `clawt-validate-` 开头，否则报错退出
+
+##### 步骤 2：查找目标 worktree
+
+从验证分支名中提取目标分支名（去掉 `clawt-validate-` 前缀），然后在项目的 worktree 列表中精确匹配目标分支对应的 worktree。如果目标 worktree 不存在（可能已被移除），报错退出。
+
+##### 步骤 3：校验快照存在并读取
+
+校验目标分支的 validate 快照是否存在。如果快照不存在，提示用户先执行 `clawt validate -b <branch>` 创建快照。读取快照中的 tree hash（`snapshotTreeHash`），作为增量计算的基准。
+
+##### 步骤 3.5：工作区干净检查
+
+检测主 worktree（验证分支上）的工作区和暂存区是否干净（`isWorkingDirClean`）：
+
+- **不干净**（有修改）→ 正常继续，这是 cover 的典型使用场景
+- **干净**（无修改）→ 输出提示信息 `当前验证分支的工作区和暂存区没有任何修改，可能为误操作`，并通过 `confirmAction` 询问用户 `是否继续执行覆盖？`：
+  - 用户确认 → 继续执行
+  - 用户取消 → 直接返回，不执行后续步骤
+
+> 工作区干净时通常意味着用户没有在验证分支上做任何修改就执行了 cover，这大概率是误操作。增加确认提示可以避免不必要的覆盖操作。
+
+##### 步骤 4：计算增量 patch
+
+通过 `computeIncrementalPatch()` 计算验证分支上相对于快照的增量变更：
+
+1. 保存当前暂存区的 tree hash（`savedIndexTreeHash`），用于后续恢复
+2. `git add .` + `git write-tree` 获取当前工作区的完整 tree hash（`currentTreeHash`）
+3. 通过 `git read-tree` 恢复原始暂存区状态（无论成功失败都执行，在 `finally` 块中）
+4. 比较 `snapshotTreeHash` 与 `currentTreeHash`：
+   - **相同** → 无增量变更，输出提示后返回
+   - **不同** → 通过 `git diff-tree` 生成 patch
+
+##### 步骤 5：应用 patch 到目标 worktree
+
+将增量 patch 通过 `git apply --binary` 应用到目标 worktree 的工作区。如果 patch apply 失败，报错退出并提示用户检查目标 worktree 工作区状态。
+
+##### 步骤 6：更新快照
+
+将 `currentTreeHash` 写入快照的 `.tree` 文件，使后续再次 cover 时的基准正确。**只更新 `treeHash`，不更新 `headCommitHash` 和 `stagedTreeHash`**（保留 validate 时写入的原值）。
+
+##### 步骤 7：输出成功提示
+
+```
+✓ 已将验证分支上的修改覆盖到 worktree => <branchName>
+```
+
+**错误消息：**
+
+| 消息常量 | 触发条件 | 提示内容 |
+| -------- | -------- | -------- |
+| `COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH` | 当前分支不是验证分支 | 提示先通过 `clawt validate` 切换到验证分支 |
+| `COVER_VALIDATE_TARGET_NOT_FOUND` | 目标 worktree 不存在 | 提示确认该 worktree 尚未被移除 |
+| `COVER_VALIDATE_NO_SNAPSHOT` | 无快照 | 提示先执行 `clawt validate -b <branch>` 创建快照 |
+| `COVER_VALIDATE_NO_CHANGES` | 无增量变更 | 提示无需覆盖 |
+| `COVER_VALIDATE_WORKING_DIR_CLEAN` | 工作区干净 | 提示可能为误操作，需确认是否继续 |
+| `COVER_VALIDATE_APPLY_FAILED` | patch 应用失败 | 提示检查目标 worktree 工作区状态后重试 |
+
+**实现要点：**
+
+- 命令注册名为 `cover`（非 `cover-validate`），用户通过 `clawt cover` 调用
+- 核心函数：`handleCoverValidate()`（`src/commands/cover-validate.ts`）
+- 辅助函数：
+  - `extractTargetBranchName()`：从验证分支名提取目标分支名
+  - `findTargetWorktreePath()`：查找目标 worktree 路径
+  - `computeIncrementalPatch()`：计算增量 patch
+- 消息常量：`COVER_VALIDATE_MESSAGES`（`src/constants/messages/cover-validate.ts`）
+- `writeSnapshot` 调用时只传 `treeHash`，利用其可选参数特性保留磁盘上的 `headCommitHash` 和 `stagedTreeHash` 原值
+
+---

package/docs/home.md

@@ -0,0 +1,54 @@
+### 5.20 切换回主工作分支
+
+**命令：**
+
+```bash
+clawt home
+```
+
+**参数：**
+
+无参数。
+
+**功能说明：**
+
+快速切换回项目的主工作分支。当用户在主 worktree 中处于验证分支或其他分支时，可通过 `clawt home` 一键切换回 `clawtMainWorkBranch` 所记录的主工作分支。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **项目级配置校验**：调用 `requireProjectConfig()` 检查项目是否已初始化
+3. **获取分支信息**：
+   - 通过 `getMainWorkBranch()` 获取主工作分支名
+   - 通过 `getCurrentBranch()` 获取当前所在分支名
+4. **判断是否需要切换**：
+   - 当前分支 === 主工作分支 → 输出提示信息，无需切换
+   - 当前分支 !== 主工作分支 → 调用 `ensureOnMainWorkBranch()` 执行切换
+5. **输出结果**
+
+**输出格式：**
+
+```
+# 已在主工作分支上
+ℹ 已在主工作分支 main 上，无需切换
+
+# 切换成功
+✓ 已从 clawt-validate-feat-login 切换到主工作分支 main
+```
+
+**消息常量：**
+
+定义在 `src/constants/messages/home.ts`：
+
+| 常量 | 说明 |
+| --- | --- |
+| `HOME_ALREADY_ON_MAIN(branch)` | 已在主工作分支上，无需切换 |
+| `HOME_SWITCH_SUCCESS(from, to)` | 切换成功提示，显示原分支和目标分支 |
+
+**实现要点：**
+
+- 命令注册函数 `registerHomeCommand` 位于 `src/commands/home.ts`
+- 依赖 `validateMainWorktree`、`requireProjectConfig`、`ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch` 等工具函数
+- `requireProjectConfig()` 为显式调用，因为 home 命令不经过 `ensureOnMainWorkBranch()` 的隐式校验路径（仅在需要切换时才调用 `ensureOnMainWorkBranch()`）
+
+---

package/docs/spec.md

@@ -34,6 +34,8 @@
   - [5.17 自动更新检查](./update-check.md)
   - [5.18 跨项目 Worktree 概览](./projects.md)
   - [5.19 初始化项目级配置](./init.md)
+  - [5.20 切换回主工作分支](./home.md)
+  - [5.21 将验证分支修改覆盖回目标 Worktree](./cover-validate.md)
 - [6. 验证架构规则](#6-验证架构规则)
 - [7. 错误处理规范](#7-错误处理规范)
 - [8. 非功能性需求](#8-非功能性需求)
@@ -292,6 +294,8 @@ async function interactiveConfigEditor<T extends object>(
 | `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
 | `clawt completion`    | 为终端提供 shell 自动补全功能（bash/zsh）              | 5.16     |
 | `clawt projects`      | 展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情 | 5.17     |
+| `clawt home`          | 快速切换回主工作分支                                      | 5.20     |
+| `clawt cover`         | 将验证分支上的修改覆盖回目标 worktree（自动推导目标分支）     | 5.21     |
 
 **全局选项：**
 
@@ -325,6 +329,8 @@ async function interactiveConfigEditor<T extends object>(
 - [5.17 自动更新检查](./update-check.md)
 - [5.18 跨项目 Worktree 概览](./projects.md)
 - [5.19 初始化项目级配置](./init.md)
+- [5.20 切换回主工作分支](./home.md)
+- [5.21 将验证分支修改覆盖回目标 Worktree](./cover-validate.md)
 
 ---
 
@@ -333,12 +339,12 @@ async function interactiveConfigEditor<T extends object>(
 以下规则适用于验证分支架构的所有实现工作：
 
 1. **不兼容旧版本**：本次重构不考虑旧版本数据、旧版本创建的 worktree 或旧版本配置的兼容性。所有命令均假定验证分支和项目级配置已按新架构存在。用户需删除旧 worktree 后重新创建。
-2. **项目级配置前置校验**：仅对 create、run、validate、sync、remove、merge、reset 这 7 个核心命令添加检测，执行时必须先检查项目级配置（`~/.clawt/projects/<projectName>/config.json`）是否存在且包含 `clawtMainWorkBranch`。如果不存在，直接报错退出并提示用户先执行 `clawt init`：
+2. **项目级配置前置校验**：仅对 create、run、validate、cover、sync、remove、merge、reset、home 这 9 个核心命令添加检测，执行时必须先检查项目级配置（`~/.clawt/projects/<projectName>/config.json`）是否存在且包含 `clawtMainWorkBranch`。如果不存在，直接报错退出并提示用户先执行 `clawt init`：
    ```
    ✗ 该项目尚未初始化，请先执行 clawt init -b<branchName>设置主工作分支
    ```
    其他命令（list、resume、config、status、alias、projects、completion）不受影响，无需添加该校验。
-   > **实现细节**：`ensureOnMainWorkBranch()` 内部已通过 `getMainWorkBranch()` → `requireProjectConfig()` 完成了项目配置校验，因此调用了 `ensureOnMainWorkBranch` 的命令（create、run、validate、merge）**无需再显式调用 `requireProjectConfig()`**，避免重复校验。sync 和 remove 命令因不依赖主 worktree 的分支状态而不调用 `ensureOnMainWorkBranch`，需自行显式调用 `requireProjectConfig()`。reset 命令同理，也需自行调用 `requireProjectConfig()`。
+   > **实现细节**：`ensureOnMainWorkBranch()` 内部已通过 `getMainWorkBranch()` → `requireProjectConfig()` 完成了项目配置校验，因此调用了 `ensureOnMainWorkBranch` 的命令（create、run、validate、merge）**无需再显式调用 `requireProjectConfig()`**，避免重复校验。sync、remove 和 cover 命令因不依赖主 worktree 的分支状态而不调用 `ensureOnMainWorkBranch`，需自行显式调用 `requireProjectConfig()`。reset 和 home 命令同理，也需自行调用 `requireProjectConfig()`。
 3. **主分支名统一从项目级配置获取**：所有需要获取主分支名的场景（sync 中合并主分支、merge 中计算 merge-base、切回主分支等），统一使用项目级配置中的 `clawtMainWorkBranch`，不再通过 `getCurrentBranch(mainWorktreePath)` 动态获取。因为在新架构下，主 worktree 可能处于验证分支上，`getCurrentBranch` 会返回验证分支名而非真正的主工作分支名。
 4. **测试文件全量更新**：本次重构涉及的所有命令（init、create、run、validate、sync、remove、merge、reset），其对应的测试文件必须同步更新，确保覆盖新增的验证分支逻辑、项目级配置逻辑和变更后的流程。
 

package/docs/sync.md

@@ -76,7 +76,21 @@ export interface SyncResult {
      ```
    - 返回 `{ success: false, hasConflict: true }`
    - **无冲突** → 继续
-5. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
+5. **保留 validate 快照**：sync 合并成功后，不清除该分支的 validate 快照。因为 validate 使用三点 diff（`main...feature`），sync 后 merge-base 更新为合并提交，三点 diff 仍然只包含 feature 分支自身的修改，旧快照依然有效。增量 validate 时若检测到 HEAD 变化，会自动通过 diff-tree + apply 路径正确恢复暂存区状态。  
+示意图：  
+  场景：将 HEAD(master) 合并到 branchName
+
+  执行 git checkout branchName && git merge master 后：
+
+        A -- B -- C  (HEAD/master)
+       /            \
+      *              M  (branchName, merge commit)
+       \            /
+        D -- E ----
+
+  此时执行 git diff HEAD...branchName：
+
+  - merge-base 变成了 C（因为合并后，HEAD 和 branchName 的最近共同祖先就是 C）
 6. **重建验证分支**（`rebuildValidateBranch`，async 函数）：sync 将主分支合并到目标 worktree 后，目标分支的代码基点发生变化。为保持验证分支与目标分支基点一致，需要重建验证分支。
    - 确保在主工作分支上创建验证分支，处理三种情况：
      - **已在主工作分支上** → 直接重建

package/package.json

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

package/src/commands/cover-validate.ts

@@ -0,0 +1,151 @@
+import type { Command } from 'commander';
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
+import {
+  validateMainWorktree,
+  requireProjectConfig,
+  getProjectName,
+  getGitTopLevel,
+  getCurrentBranch,
+  getProjectWorktrees,
+  findExactMatch,
+  hasSnapshot,
+  readSnapshot,
+  writeSnapshot,
+  gitAddAll,
+  gitWriteTree,
+  gitReadTree,
+  gitDiffTree,
+  gitApplyFromStdin,
+  printSuccess,
+  printInfo,
+  isWorkingDirClean,
+  confirmAction,
+} from '../utils/index.js';
+
+/**
+ * 注册 cover-validate 命令：将验证分支上的修改覆盖回目标 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerCoverValidateCommand(program: Command): void {
+  program
+    .command('cover')
+    .description('将验证分支上的修改覆盖回目标 worktree（自动推导目标分支）')
+    .action(async () => {
+      await handleCoverValidate();
+    });
+}
+
+/**
+ * 从验证分支名中提取目标分支名
+ * 验证分支名格式为 clawt-validate-<targetBranch>，去掉前缀即为目标分支名
+ * @param {string} currentBranch - 当前分支名
+ * @returns {string} 目标分支名
+ */
+export function extractTargetBranchName(currentBranch: string): string {
+  return currentBranch.slice(VALIDATE_BRANCH_PREFIX.length);
+}
+
+/**
+ * 在项目 worktree 列表中查找目标分支对应的 worktree 路径
+ * @param {string} branchName - 目标分支名
+ * @returns {string} 目标 worktree 的绝对路径
+ * @throws {ClawtError} 目标 worktree 不存在时抛出
+ */
+export function findTargetWorktreePath(branchName: string): string {
+  const worktrees = getProjectWorktrees();
+  const match = findExactMatch(worktrees, branchName);
+  if (!match) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_TARGET_NOT_FOUND(branchName));
+  }
+  return match.path;
+}
+
+/**
+ * 计算验证分支上相对于快照的增量 patch
+ * 操作序列：git write-tree（保存暂存区）→ git add . → git write-tree（获取工作区 tree）→ git read-tree（恢复暂存区）
+ * 当 snapshotTreeHash 与当前 tree hash 相同时返回 null 表示无变更
+ * @param {string} snapshotTreeHash - 快照中记录的 tree hash
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {{ patch: Buffer; currentTreeHash: string } | null} 增量 patch 和当前 tree hash，无变更时返回 null
+ */
+export function computeIncrementalPatch(snapshotTreeHash: string, mainWorktreePath: string): { patch: Buffer; currentTreeHash: string } | null {
+  // 先保存当前暂存区的 tree hash，用于后续恢复
+  const savedIndexTreeHash = gitWriteTree(mainWorktreePath);
+  let currentTreeHash: string;
+
+  try {
+    gitAddAll(mainWorktreePath);
+    currentTreeHash = gitWriteTree(mainWorktreePath);
+  } finally {
+    // 无论成功或失败，都通过 git read-tree 恢复原始暂存区状态
+    gitReadTree(savedIndexTreeHash, mainWorktreePath);
+  }
+
+  // 快照 tree 与当前 tree 相同，无增量变更
+  if (snapshotTreeHash === currentTreeHash) {
+    return null;
+  }
+
+  const patch = gitDiffTree(snapshotTreeHash, currentTreeHash, mainWorktreePath);
+  return { patch, currentTreeHash };
+}
+
+/**
+ * 执行 cover-validate 命令的核心逻辑
+ * 将验证分支上的增量修改（相对于 validate 快照）覆盖到目标 worktree 工作区
+ */
+async function handleCoverValidate(): Promise<void> {
+  // 步骤 1：前置校验
+  validateMainWorktree();
+  requireProjectConfig();
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+  const currentBranch = getCurrentBranch(mainWorktreePath);
+
+  // 校验当前分支是验证分支
+  if (!currentBranch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH);
+  }
+
+  // 从验证分支名推导目标分支名
+  const targetBranchName = extractTargetBranchName(currentBranch);
+  logger.info(`cover-validate 命令执行，目标分支: ${targetBranchName}`);
+
+  // 步骤 2：查找目标 worktree
+  const targetWorktreePath = findTargetWorktreePath(targetBranchName);
+
+  // 步骤 3：校验快照存在并读取
+  if (!hasSnapshot(projectName, targetBranchName)) {
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_NO_SNAPSHOT(targetBranchName));
+  }
+  const { treeHash: snapshotTreeHash } = readSnapshot(projectName, targetBranchName);
+
+  // 步骤 3.5：工作区干净时提示确认，避免误操作
+  if (isWorkingDirClean(mainWorktreePath)) {
+    printInfo(MESSAGES.COVER_VALIDATE_WORKING_DIR_CLEAN);
+    const confirmed = await confirmAction('是否继续执行覆盖？');
+    if (!confirmed) return;
+  }
+
+  // 步骤 4：计算增量 patch
+  const result = computeIncrementalPatch(snapshotTreeHash, mainWorktreePath);
+  if (!result) {
+    printInfo(MESSAGES.COVER_VALIDATE_NO_CHANGES);
+    return;
+  }
+
+  // 步骤 5：应用 patch 到目标 worktree
+  try {
+    gitApplyFromStdin(result.patch, targetWorktreePath);
+  } catch (error) {
+    logger.error(`cover-validate patch apply 失败: ${error}`);
+    throw new ClawtError(MESSAGES.COVER_VALIDATE_APPLY_FAILED(targetBranchName));
+  }
+
+  // 步骤 6：更新快照 treeHash（使后续再次 cover 的基准正确），HEAD 和 stagedTreeHash 不变
+  writeSnapshot(projectName, targetBranchName, result.currentTreeHash);
+
+  printSuccess(MESSAGES.COVER_VALIDATE_SUCCESS(targetBranchName));
+}

package/src/commands/home.ts

@@ -0,0 +1,43 @@
+import type { Command } from 'commander';
+import { MESSAGES } from '../constants/index.js';
+import {
+  validateMainWorktree,
+  requireProjectConfig,
+  ensureOnMainWorkBranch,
+  getCurrentBranch,
+  getMainWorkBranch,
+  printSuccess,
+  printInfo,
+} from '../utils/index.js';
+
+/**
+ * 注册 home 命令：快速切换回主工作分支
+ * @param {Command} program - Commander 实例
+ */
+export function registerHomeCommand(program: Command): void {
+  program
+    .command('home')
+    .description('切换回主工作分支')
+    .action(async () => {
+      await handleHome();
+    });
+}
+
+/**
+ * 执行 home 命令：切换回主工作分支
+ */
+async function handleHome(): Promise<void> {
+  validateMainWorktree();
+  requireProjectConfig();
+
+  const mainBranch = getMainWorkBranch();
+  const currentBranch = getCurrentBranch();
+
+  if (currentBranch === mainBranch) {
+    printInfo(MESSAGES.HOME_ALREADY_ON_MAIN(mainBranch));
+    return;
+  }
+
+  await ensureOnMainWorkBranch();
+  printSuccess(MESSAGES.HOME_SWITCH_SUCCESS(currentBranch, mainBranch));
+}

package/src/commands/sync.ts

@@ -6,15 +6,12 @@ import type { SyncOptions } from '../types/index.js';
 import {
   validateMainWorktree,
   getGitTopLevel,
-  getProjectName,
   getProjectWorktrees,
   isWorkingDirClean,
   gitAddAll,
   gitCommit,
   gitMerge,
   hasMergeConflict,
-  hasSnapshot,
-  removeSnapshot,
   printSuccess,
   printInfo,
   printWarning,
@@ -89,7 +86,7 @@ export interface SyncResult {
 }
 
 /**
- * 执行 sync 核心操作（检查未提交→自动保存→merge 主分支→清除快照）
+ * 执行 sync 核心操作（检查未提交→自动保存→merge 主分支）
  * 不包含 worktree 解析交互，供 validate 等命令复用
  * @param {string} targetWorktreePath - 目标 worktree 路径
  * @param {string} branch - 分支名
@@ -114,13 +111,6 @@ export async function executeSyncForBranch(targetWorktreePath: string, branch: s
     return { success: false, hasConflict: true };
   }
 
-  // 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
-  const projectName = getProjectName();
-  if (hasSnapshot(projectName, branch)) {
-    removeSnapshot(projectName, branch);
-    logger.info(`已清除分支 ${branch} 的 validate 快照`);
-  }
-
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
 
   // 合并成功后重建验证分支（基于最新的主分支 HEAD）

package/src/constants/messages/cover-validate.ts

@@ -0,0 +1,21 @@
+/** cover-validate 命令专属提示消息 */
+export const COVER_VALIDATE_MESSAGES = {
+  /** 当前不在验证分支上 */
+  COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH: '当前分支不是验证分支（需以 clawt-validate- 开头）\n  请先通过 clawt validate 切换到验证分支',
+  /** 无增量修改 */
+  COVER_VALIDATE_NO_CHANGES: '验证分支上没有相对于快照的增量修改，无需覆盖',
+  /** 目标 worktree 不存在 */
+  COVER_VALIDATE_TARGET_NOT_FOUND: (branch: string) =>
+    `未找到分支 ${branch} 对应的 worktree，请确认该 worktree 尚未被移除`,
+  /** 无快照，提示先执行 validate */
+  COVER_VALIDATE_NO_SNAPSHOT: (branch: string) =>
+    `未找到分支 ${branch} 的 validate 快照\n  请先执行 clawt validate -b ${branch} 创建快照`,
+  /** patch 应用失败 */
+  COVER_VALIDATE_APPLY_FAILED: (branch: string) =>
+    `覆盖变更到 worktree ${branch} 失败：patch 应用出错\n  请检查目标 worktree 工作区状态后重试`,
+  /** 工作区和暂存区无修改，可能为误操作 */
+  COVER_VALIDATE_WORKING_DIR_CLEAN: '当前验证分支的工作区和暂存区没有任何修改，可能为误操作',
+  /** 覆盖成功 */
+  COVER_VALIDATE_SUCCESS: (branch: string) =>
+    `✓ 已将验证分支上的修改覆盖到 worktree => ${branch}`,
+} as const;

package/src/constants/messages/home.ts

@@ -0,0 +1,7 @@
+/** home 命令专属提示消息 */
+export const HOME_MESSAGES = {
+  /** 已在主工作分支上 */
+  HOME_ALREADY_ON_MAIN: (branch: string) => `已在主工作分支 ${branch} 上，无需切换`,
+  /** 切换成功 */
+  HOME_SWITCH_SUCCESS: (from: string, to: string) => `✓ 已从 ${from} 切换到主工作分支 ${to}`,
+} as const;

package/src/constants/messages/index.ts

@@ -14,6 +14,8 @@ import { PROJECTS_MESSAGES } from './projects.js';
 import { COMPLETION_MESSAGES } from './completion.js';
 import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
 import { INIT_MESSAGES } from './init.js';
+import { COVER_VALIDATE_MESSAGES } from './cover-validate.js';
+import { HOME_MESSAGES } from './home.js';
 import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
@@ -40,4 +42,6 @@ export const MESSAGES = {
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
   ...INIT_MESSAGES,
+  ...COVER_VALIDATE_MESSAGES,
+  ...HOME_MESSAGES,
 } as const;

package/src/index.ts

@@ -10,6 +10,7 @@ import { registerRemoveCommand } from './commands/remove.js';
 import { registerRunCommand } from './commands/run.js';
 import { registerResumeCommand } from './commands/resume.js';
 import { registerValidateCommand } from './commands/validate.js';
+import { registerCoverValidateCommand } from './commands/cover-validate.js';
 import { registerMergeCommand } from './commands/merge.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerSyncCommand } from './commands/sync.js';
@@ -19,6 +20,7 @@ import { registerAliasCommand } from './commands/alias.js';
 import { registerProjectsCommand } from './commands/projects.js';
 import { registerCompletionCommand } from './commands/completion.js';
 import { registerInitCommand } from './commands/init.js';
+import { registerHomeCommand } from './commands/home.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -49,6 +51,7 @@ registerRemoveCommand(program);
 registerRunCommand(program);
 registerResumeCommand(program);
 registerValidateCommand(program);
+registerCoverValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
@@ -58,6 +61,7 @@ registerAliasCommand(program);
 registerProjectsCommand(program);
 registerCompletionCommand(program);
 registerInitCommand(program);
+registerHomeCommand(program);
 
 // 加载配置并应用命令别名
 const config = loadConfig();

package/src/utils/validate-snapshot.ts

@@ -90,22 +90,26 @@ export function readSnapshot(projectName: string, branchName: string): { treeHas
 /**
  * 写入 validate 快照内容（自动创建目录）
  * tree hash 写入 .tree 文件，HEAD commit hash 写入 .head 文件，staged tree hash 写入 .staged 文件
+ * 未提供的可选字段（值为 undefined）不会覆盖，保留磁盘上的原值
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
- * @param {string} treeHash - git tree 对象的 hash
- * @param {string} headCommitHash - 快照时主 worktree 的 HEAD commit hash
- * @param {string} [stagedTreeHash=''] - validate 结束时暂存区对应的 tree hash
+ * @param {string} [treeHash] - git tree 对象的 hash，不传则保留原值
+ * @param {string} [headCommitHash] - 快照时主 worktree 的 HEAD commit hash，不传则保留原值
+ * @param {string} [stagedTreeHash] - validate 结束时暂存区对应的 tree hash，不传则保留原值
  */
-export function writeSnapshot(projectName: string, branchName: string, treeHash: string, headCommitHash: string, stagedTreeHash = ''): void {
-  const snapshotPath = getSnapshotPath(projectName, branchName);
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  const stagedPath = getSnapshotStagedPath(projectName, branchName);
+export function writeSnapshot(projectName: string, branchName: string, treeHash?: string, headCommitHash?: string, stagedTreeHash?: string): void {
   const snapshotDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
-  writeFileSync(snapshotPath, treeHash, 'utf-8');
-  writeFileSync(headPath, headCommitHash, 'utf-8');
-  writeFileSync(stagedPath, stagedTreeHash, 'utf-8');
-  logger.info(`已保存 validate 快照: ${snapshotPath}, ${headPath}, ${stagedPath}`);
+  if (treeHash !== undefined) {
+    writeFileSync(getSnapshotPath(projectName, branchName), treeHash, 'utf-8');
+  }
+  if (headCommitHash !== undefined) {
+    writeFileSync(getSnapshotHeadPath(projectName, branchName), headCommitHash, 'utf-8');
+  }
+  if (stagedTreeHash !== undefined) {
+    writeFileSync(getSnapshotStagedPath(projectName, branchName), stagedTreeHash, 'utf-8');
+  }
+  logger.info(`已写入 validate 快照 (project=${projectName}, branch=${branchName})`);
 }
 
 /**

package/tests/unit/commands/cover-validate.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('../../../src/errors/index.js', () => ({
+  ClawtError: class ClawtError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode = 1) {
+      super(message);
+      this.exitCode = exitCode;
+    }
+  },
+}));
+
+vi.mock('../../../src/constants/index.js', () => ({
+  MESSAGES: {
+    COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH: '当前分支不是验证分支',
+    COVER_VALIDATE_NO_CHANGES: '验证分支上没有相对于快照的增量修改，无需覆盖',
+    COVER_VALIDATE_TARGET_NOT_FOUND: (branch: string) => `未找到分支 ${branch} 对应的 worktree`,
+    COVER_VALIDATE_NO_SNAPSHOT: (branch: string) => `未找到分支 ${branch} 的 validate 快照`,
+    COVER_VALIDATE_APPLY_FAILED: (branch: string) => `覆盖变更到 worktree ${branch} 失败`,
+    COVER_VALIDATE_SUCCESS: (branch: string) => `✓ 已将验证分支上的修改覆盖到 worktree => ${branch}`,
+    COVER_VALIDATE_WORKING_DIR_CLEAN: '当前验证分支的工作区和暂存区没有任何修改，可能为误操作',
+  },
+  VALIDATE_BRANCH_PREFIX: 'clawt-validate-',
+}));
+
+vi.mock('../../../src/utils/index.js', () => ({
+  validateMainWorktree: vi.fn(),
+  requireProjectConfig: vi.fn(),
+  getProjectName: vi.fn().mockReturnValue('test-project'),
+  getGitTopLevel: vi.fn().mockReturnValue('/repo'),
+  getCurrentBranch: vi.fn().mockReturnValue('clawt-validate-feature'),
+  getProjectWorktrees: vi.fn().mockReturnValue([{ path: '/path/feature', branch: 'feature' }]),
+  findExactMatch: vi.fn().mockReturnValue({ path: '/path/feature', branch: 'feature' }),
+  hasSnapshot: vi.fn().mockReturnValue(true),
+  readSnapshot: vi.fn().mockReturnValue({ treeHash: 'snapshot-tree-hash' }),
+  writeSnapshot: vi.fn(),
+  gitAddAll: vi.fn(),
+  gitWriteTree: vi.fn().mockReturnValue('current-tree-hash'),
+  gitReadTree: vi.fn(),
+  gitDiffTree: vi.fn().mockReturnValue(Buffer.from('fake-patch')),
+  gitApplyFromStdin: vi.fn(),
+  printSuccess: vi.fn(),
+  printInfo: vi.fn(),
+  isWorkingDirClean: vi.fn().mockReturnValue(false),
+  confirmAction: vi.fn().mockResolvedValue(true),
+}));
+
+import { registerCoverValidateCommand, extractTargetBranchName, findTargetWorktreePath, computeIncrementalPatch } from '../../../src/commands/cover-validate.js';
+import {
+  getCurrentBranch,
+  getProjectWorktrees,
+  findExactMatch,
+  hasSnapshot,
+  readSnapshot,
+  writeSnapshot,
+  gitAddAll,
+  gitWriteTree,
+  gitReadTree,
+  gitDiffTree,
+  gitApplyFromStdin,
+  printSuccess,
+  printInfo,
+  isWorkingDirClean,
+  confirmAction,
+} from '../../../src/utils/index.js';
+
+const mockedGetCurrentBranch = vi.mocked(getCurrentBranch);
+const mockedGetProjectWorktrees = vi.mocked(getProjectWorktrees);
+const mockedFindExactMatch = vi.mocked(findExactMatch);
+const mockedHasSnapshot = vi.mocked(hasSnapshot);
+const mockedReadSnapshot = vi.mocked(readSnapshot);
+const mockedWriteSnapshot = vi.mocked(writeSnapshot);
+const mockedGitAddAll = vi.mocked(gitAddAll);
+const mockedGitWriteTree = vi.mocked(gitWriteTree);
+const mockedGitReadTree = vi.mocked(gitReadTree);
+const mockedGitDiffTree = vi.mocked(gitDiffTree);
+const mockedGitApplyFromStdin = vi.mocked(gitApplyFromStdin);
+const mockedPrintSuccess = vi.mocked(printSuccess);
+const mockedPrintInfo = vi.mocked(printInfo);
+const mockedIsWorkingDirClean = vi.mocked(isWorkingDirClean);
+const mockedConfirmAction = vi.mocked(confirmAction);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // 恢复默认 mock 值
+  mockedGetCurrentBranch.mockReturnValue('clawt-validate-feature');
+  mockedGetProjectWorktrees.mockReturnValue([{ path: '/path/feature', branch: 'feature' }]);
+  mockedFindExactMatch.mockReturnValue({ path: '/path/feature', branch: 'feature' });
+  mockedHasSnapshot.mockReturnValue(true);
+  mockedReadSnapshot.mockReturnValue({ treeHash: 'snapshot-tree-hash' });
+  mockedIsWorkingDirClean.mockReturnValue(false);
+  mockedConfirmAction.mockResolvedValue(true);
+  mockedGitWriteTree.mockReturnValue('current-tree-hash');
+  mockedGitDiffTree.mockReturnValue(Buffer.from('fake-patch'));
+});
+
+describe('registerCoverValidateCommand', () => {
+  it('注册 cover 命令', () => {
+    const program = new Command();
+    registerCoverValidateCommand(program);
+    const cmd = program.commands.find((c) => c.name() === 'cover');
+    expect(cmd).toBeDefined();
+  });
+});
+
+describe('extractTargetBranchName', () => {
+  it('从验证分支名中提取目标分支名', () => {
+    expect(extractTargetBranchName('clawt-validate-feature')).toBe('feature');
+    expect(extractTargetBranchName('clawt-validate-fix/bug-123')).toBe('fix/bug-123');
+  });
+});
+
+describe('findTargetWorktreePath', () => {
+  it('找到目标 worktree 时返回路径', () => {
+    const path = findTargetWorktreePath('feature');
+    expect(path).toBe('/path/feature');
+  });
+
+  it('未找到目标 worktree 时抛出错误', () => {
+    mockedFindExactMatch.mockReturnValue(undefined);
+    expect(() => findTargetWorktreePath('nonexistent')).toThrow();
+  });
+});
+
+describe('computeIncrementalPatch', () => {
+  it('有增量变更时返回 patch 和 currentTreeHash', () => {
+    mockedGitWriteTree
+      .mockReturnValueOnce('saved-index-tree')  // 保存暂存区
+      .mockReturnValueOnce('new-tree-hash');     // git add . 后的 tree
+
+    const result = computeIncrementalPatch('snapshot-tree-hash', '/repo');
+    expect(result).not.toBeNull();
+    expect(result!.currentTreeHash).toBe('new-tree-hash');
+    expect(mockedGitAddAll).toHaveBeenCalledWith('/repo');
+    expect(mockedGitReadTree).toHaveBeenCalledWith('saved-index-tree', '/repo');
+    expect(mockedGitDiffTree).toHaveBeenCalledWith('snapshot-tree-hash', 'new-tree-hash', '/repo');
+  });
+
+  it('无增量变更时返回 null', () => {
+    mockedGitWriteTree
+      .mockReturnValueOnce('saved-index-tree')
+      .mockReturnValueOnce('snapshot-tree-hash'); // 与快照相同
+
+    const result = computeIncrementalPatch('snapshot-tree-hash', '/repo');
+    expect(result).toBeNull();
+  });
+});
+
+describe('handleCoverValidate - 工作区干净检查', () => {
+  /** 辅助函数：执行 cover 命令 */
+  async function runCover(): Promise<void> {
+    const program = new Command();
+    program.exitOverride();
+    registerCoverValidateCommand(program);
+    await program.parseAsync(['cover'], { from: 'user' });
+  }
+
+  it('工作区干净且用户取消时不执行 patch', async () => {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedConfirmAction.mockResolvedValue(false);
+
+    await runCover();
+
+    expect(mockedPrintInfo).toHaveBeenCalled();
+    expect(mockedConfirmAction).toHaveBeenCalledWith('是否继续执行覆盖？');
+    // 用户取消后不应继续执行后续逻辑
+    expect(mockedGitAddAll).not.toHaveBeenCalled();
+    expect(mockedGitApplyFromStdin).not.toHaveBeenCalled();
+    expect(mockedPrintSuccess).not.toHaveBeenCalled();
+  });
+
+  it('工作区干净且用户确认继续时正常执行', async () => {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedConfirmAction.mockResolvedValue(true);
+    // computeIncrementalPatch 返回有 patch 的结果
+    mockedGitWriteTree
+      .mockReturnValueOnce('saved-index-tree')
+      .mockReturnValueOnce('new-tree-hash');
+
+    await runCover();
+
+    expect(mockedConfirmAction).toHaveBeenCalledWith('是否继续执行覆盖？');
+    expect(mockedGitApplyFromStdin).toHaveBeenCalled();
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+
+  it('工作区不干净时跳过确认直接执行', async () => {
+    mockedIsWorkingDirClean.mockReturnValue(false);
+    mockedGitWriteTree
+      .mockReturnValueOnce('saved-index-tree')
+      .mockReturnValueOnce('new-tree-hash');
+
+    await runCover();
+
+    expect(mockedConfirmAction).not.toHaveBeenCalled();
+    expect(mockedGitApplyFromStdin).toHaveBeenCalled();
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+});

package/tests/unit/commands/sync.test.ts

@@ -33,7 +33,6 @@ vi.mock('../../../src/constants/index.js', () => ({
 vi.mock('../../../src/utils/index.js', () => ({
   validateMainWorktree: vi.fn(),
   getGitTopLevel: vi.fn(),
-  getProjectName: vi.fn(),
   getProjectWorktrees: vi.fn(),
   isWorkingDirClean: vi.fn(),
   gitAddAll: vi.fn(),
@@ -41,8 +40,6 @@ vi.mock('../../../src/utils/index.js', () => ({
   gitMerge: vi.fn(),
   hasMergeConflict: vi.fn(),
   getCurrentBranch: vi.fn(),
-  hasSnapshot: vi.fn(),
-  removeSnapshot: vi.fn(),
   printSuccess: vi.fn(),
   printInfo: vi.fn(),
   printWarning: vi.fn(),
@@ -56,7 +53,6 @@ vi.mock('../../../src/utils/index.js', () => ({
 import { registerSyncCommand } from '../../../src/commands/sync.js';
 import {
   getGitTopLevel,
-  getProjectName,
   getProjectWorktrees,
   isWorkingDirClean,
   gitAddAll,
@@ -64,15 +60,12 @@ import {
   gitMerge,
   hasMergeConflict,
   getCurrentBranch,
-  hasSnapshot,
-  removeSnapshot,
   printSuccess,
   printWarning,
   resolveTargetWorktree,
 } from '../../../src/utils/index.js';
 
 const mockedGetGitTopLevel = vi.mocked(getGitTopLevel);
-const mockedGetProjectName = vi.mocked(getProjectName);
 const mockedGetProjectWorktrees = vi.mocked(getProjectWorktrees);
 const mockedIsWorkingDirClean = vi.mocked(isWorkingDirClean);
 const mockedGitAddAll = vi.mocked(gitAddAll);
@@ -80,15 +73,12 @@ const mockedGitCommit = vi.mocked(gitCommit);
 const mockedGitMerge = vi.mocked(gitMerge);
 const mockedHasMergeConflict = vi.mocked(hasMergeConflict);
 const mockedGetCurrentBranch = vi.mocked(getCurrentBranch);
-const mockedHasSnapshot = vi.mocked(hasSnapshot);
-const mockedRemoveSnapshot = vi.mocked(removeSnapshot);
 const mockedPrintSuccess = vi.mocked(printSuccess);
 const mockedPrintWarning = vi.mocked(printWarning);
 const mockedResolveTargetWorktree = vi.mocked(resolveTargetWorktree);
 
 beforeEach(() => {
   mockedGetGitTopLevel.mockReturnValue('/repo');
-  mockedGetProjectName.mockReturnValue('test-project');
   mockedGetCurrentBranch.mockReturnValue('main');
   mockedGetProjectWorktrees.mockReset();
   mockedIsWorkingDirClean.mockReset();
@@ -96,8 +86,6 @@ beforeEach(() => {
   mockedGitCommit.mockReset();
   mockedGitMerge.mockReset();
   mockedHasMergeConflict.mockReset();
-  mockedHasSnapshot.mockReset();
-  mockedRemoveSnapshot.mockReset();
   mockedPrintSuccess.mockReset();
   mockedPrintWarning.mockReset();
   mockedResolveTargetWorktree.mockReset();
@@ -118,7 +106,6 @@ describe('handleSync', () => {
     mockedGetProjectWorktrees.mockReturnValue([worktree]);
     mockedResolveTargetWorktree.mockResolvedValue(worktree);
     mockedIsWorkingDirClean.mockReturnValue(true);
-    mockedHasSnapshot.mockReturnValue(false);
 
     const program = new Command();
     program.exitOverride();
@@ -135,7 +122,6 @@ describe('handleSync', () => {
     mockedGetProjectWorktrees.mockReturnValue([worktree]);
     mockedResolveTargetWorktree.mockResolvedValue(worktree);
     mockedIsWorkingDirClean.mockReturnValue(false);
-    mockedHasSnapshot.mockReturnValue(false);
 
     const program = new Command();
     program.exitOverride();
@@ -164,36 +150,6 @@ describe('handleSync', () => {
     expect(mockedPrintSuccess).not.toHaveBeenCalled();
   });
 
-  it('合并成功后清理 validate 快照', async () => {
-    const worktree = { path: '/path/feature', branch: 'feature' };
-    mockedGetProjectWorktrees.mockReturnValue([worktree]);
-    mockedResolveTargetWorktree.mockResolvedValue(worktree);
-    mockedIsWorkingDirClean.mockReturnValue(true);
-    mockedHasSnapshot.mockReturnValue(true);
-
-    const program = new Command();
-    program.exitOverride();
-    registerSyncCommand(program);
-    await program.parseAsync(['sync', '-b', 'feature'], { from: 'user' });
-
-    expect(mockedRemoveSnapshot).toHaveBeenCalledWith('test-project', 'feature');
-  });
-
-  it('合并成功且无快照时不调用 removeSnapshot', async () => {
-    const worktree = { path: '/path/feature', branch: 'feature' };
-    mockedGetProjectWorktrees.mockReturnValue([worktree]);
-    mockedResolveTargetWorktree.mockResolvedValue(worktree);
-    mockedIsWorkingDirClean.mockReturnValue(true);
-    mockedHasSnapshot.mockReturnValue(false);
-
-    const program = new Command();
-    program.exitOverride();
-    registerSyncCommand(program);
-    await program.parseAsync(['sync', '-b', 'feature'], { from: 'user' });
-
-    expect(mockedRemoveSnapshot).not.toHaveBeenCalled();
-  });
-
   it('合并失败（非冲突错误）时向上抛出', async () => {
     const worktree = { path: '/path/feature', branch: 'feature' };
     mockedGetProjectWorktrees.mockReturnValue([worktree]);

package/tests/unit/utils/validate-snapshot.test.ts

@@ -107,7 +107,7 @@ describe('readSnapshotTreeHash', () => {
 
 describe('writeSnapshot', () => {
   it('正确写入三个文件', () => {
-    writeSnapshot('proj', 'branch', 'tree123', 'head456');
+    writeSnapshot('proj', 'branch', 'tree123', 'head456', 'staged789');
     expect(mockedEnsureDir).toHaveBeenCalledWith('/tmp/test-snapshots/proj');
     expect(mockedWriteFileSync).toHaveBeenCalledTimes(3);
     expect(mockedWriteFileSync).toHaveBeenCalledWith(
@@ -122,10 +122,26 @@ describe('writeSnapshot', () => {
     );
     expect(mockedWriteFileSync).toHaveBeenCalledWith(
       '/tmp/test-snapshots/proj/branch.staged',
-      '',
+      'staged789',
       'utf-8',
     );
   });
+
+  it('未传 headCommitHash 和 stagedTreeHash 时只写入 treeHash', () => {
+    writeSnapshot('proj', 'branch', 'tree123');
+    expect(mockedWriteFileSync).toHaveBeenCalledTimes(1);
+    expect(mockedWriteFileSync).toHaveBeenCalledWith(
+      '/tmp/test-snapshots/proj/branch.tree',
+      'tree123',
+      'utf-8',
+    );
+  });
+
+  it('所有字段都未传时不写入任何文件', () => {
+    writeSnapshot('proj', 'branch');
+    expect(mockedEnsureDir).toHaveBeenCalledWith('/tmp/test-snapshots/proj');
+    expect(mockedWriteFileSync).not.toHaveBeenCalled();
+  });
 });
 
 describe('removeSnapshot', () => {