clawt 2.1.0 → 2.3.0

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

@@ -4,7 +4,7 @@
 
 ### docs/spec.md
 - 完整的软件规格说明，包含 7 大章节
-- 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.11）
+- 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.13）
 - run 命令对应 `5.2 批量创建 Worktree + 执行 Claude Code 任务`，流程按步骤编号描述
 - merge 命令对应 `5.6 合并验证过的分支`，流程按步骤编号描述
 - config 命令对应 `5.10 查看全局配置`，只读展示配置
@@ -60,24 +60,26 @@ run 命令有两种模式（自 claudeCodeCommand 特性后）：
 - 传 `--tasks`：并行任务模式（多 worktree + `executeClaudeTask` + spawnProcess）
 - CLAUDE.md 中的核心流程按模式分段描述
 
-## 命令清单（8 个）
+## 命令清单（10 个）
 
-`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`
+`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`、`reset`
 
 Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
 - `claudeCodeCommand` 配置项同时影响 run 交互式模式和 resume 命令
+- reset 命令与 validate --clean 的区别：reset 不删除快照文件，validate --clean 会删除快照
 
 ## validate 快照机制
 
 - validate 命令支持首次/增量两种模式，通过 `hasSnapshot()` 判断
-- 快照路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`
+- 快照路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree`（存储 git tree 对象 hash）
 - 常量 `VALIDATE_SNAPSHOTS_DIR` 定义在 `src/constants/paths.ts`
 - validate 新增 `--clean` 选项（`ValidateOptions.clean?: boolean`）
-- 增量模式核心：旧 patch 应用到暂存区 + 新全量变更在工作目录 → `git diff` 可查看增量差异
-- 增量 apply 失败时自动降级为全量模式
-- shell 层新增 `execCommandWithInput()`（`execFileSync` + stdin），用于 `gitApplyCachedFromStdin()`
-- git 层新增 `gitDiffCachedBinary()`（返回 Buffer）和 `gitApplyCachedFromStdin()`
+- 快照保存：`git add . → git write-tree → git restore --staged .`，将 tree hash 写入 `.tree` 文件
+- 增量模式核心：`git read-tree <旧 tree hash>` 将旧快照载入暂存区 + 新全量变更在工作目录 → `git diff` 可查看增量差异
+- tree 对象不依赖主分支 HEAD，无需一致性校验（旧方案需要 `.head` 文件校验 HEAD 一致性）
+- 增量 read-tree 失败时自动降级为全量模式（tree 对象可能被 git gc 回收）
+- git 层有 `gitWriteTree()`（返回 tree hash）和 `gitReadTree()`（载入暂存区）
 - merge 成功后自动清理对应快照；merge 时主 worktree 脏 + 存在快照会输出警告提示
 - docs/spec.md 中 validate 章节（5.4）按 `--clean 模式`、`首次 validate`、`增量 validate` 三段描述
 - CLAUDE.md 中在 validate + merge 工作流章节用缩进列表描述两种模式

package/CLAUDE.md

@@ -24,7 +24,7 @@ npm i -g .        # 本地全局安装进行测试
 
 每个命令为独立文件 `src/commands/<name>.ts`，导出 `registerXxxCommand(program)` 函数，在 `src/index.ts` 中统一注册到 Commander。命令内部逻辑封装在对应的 `handleXxx` 函数中。
 
-九个命令：`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`。
+十个命令：`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`、`reset`。
 
 ### 核心流程（run 命令）
 
@@ -56,10 +56,11 @@ run 命令有两种模式：
 ### validate + merge 工作流
 
 - `validate`：将目标分支的全量变更（已提交 + 未提交）通过 `git diff HEAD...branch --binary` 的 patch 方式迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
-  - **首次 validate**（无历史快照）：patch 迁移全量变更 → 保存纯净快照 patch + 主分支 HEAD hash → 结果：暂存区=空，工作目录=全量变更
-  - **增量 validate**（存在历史快照）：校验主分支 HEAD 一致性（不一致则清除旧快照降级为首次模式）→ 读取旧 patch → 确保主 worktree 干净 → patch 迁移最新变更 → 保存新快照 → 旧 patch 应用到暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
+  - **首次 validate**（无历史快照）：patch 迁移全量变更 → 通过 `git write-tree` 保存快照为 git tree 对象 → 结果：暂存区=空，工作目录=全量变更
+  - **增量 validate**（存在历史快照）：读取旧 tree hash → 确保主 worktree 干净 → patch 迁移最新变更 → 保存新 tree 对象快照 → `git read-tree` 将旧 tree 载入暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
   - `--clean` 选项：重置主 worktree + 删除对应快照文件
-  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.patch`（patch 文件）+ `<branchName>.head`（主分支 HEAD hash）
+  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree`（存储 git tree 对象 hash）
+  - tree 对象不依赖主分支 HEAD，无需一致性校验
   - 变更检测：同时检测目标 worktree 的未提交修改和已提交 commit，两者均无则提示无需验证
   - 未提交修改处理：有未提交修改时先做临时 commit，diff 完成后通过 `git reset --soft` 撤销恢复原状
 - `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ **squash 检测**（检查目标分支是否存在 `AUTO_SAVE_COMMIT_MESSAGE` 前缀的 auto-save commit，如有则提示用户是否压缩所有提交：用户确认后通过 `gitMergeBase` 计算分叉点、`gitResetSoftTo` 将所有 commit reset 到暂存区；有 `-m` 则直接提交继续流程，无 `-m` 则提示用户自行提交后退出）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
@@ -75,11 +76,18 @@ run 命令有两种模式：
 6. 冲突处理：有冲突时提示用户手动解决，无冲突则输出成功
 7. 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
 
+### reset 命令流程
+
+1. `validateMainWorktree()` 确认在主 worktree 根目录
+2. 检测主 worktree 工作区和暂存区是否干净（`isWorkingDirClean()`）
+3. 不干净 → `gitResetHard()` + `gitCleanForce()` 重置工作区和暂存区（保留 validate 快照）
+4. 已干净 → 提示无需重置
+
 ### 目录层级
 
 - `src/commands/` — 各命令的注册与处理逻辑
-- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测、merge-base 计算、commit message 检测、soft reset 到指定 commit 等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理（含 HEAD hash 一致性校验））
-- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息）
+- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测、merge-base 计算、commit message 检测、soft reset 到指定 commit、write-tree/read-tree 等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理（基于 git tree 对象））
+- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息、reset 相关消息）
 - `src/types/` — TypeScript 类型定义
 - `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
 - `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）

package/README.md

@@ -103,7 +103,7 @@ clawt validate -b <branchName> [--clean]
 
 将目标 worktree 的变更通过 `git diff`（三点 diff）迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。同时检测未提交修改和已提交 commit，确保所有变更都能被捕获。
 
-支持增量模式：首次 validate 后会自动保存快照（patch + 主分支 HEAD hash），再次 validate 同一分支时会先校验主分支 HEAD 一致性（不一致则降级为首次模式），然后将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
+支持增量模式：首次 validate 后会自动保存快照（通过 `git write-tree` 将变更存储为 git tree 对象），再次 validate 同一分支时会通过 `git read-tree` 将上次快照载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
 
 > **提示：** 如果 validate 时 patch apply 失败（目标分支与主分支差异过大），可先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
@@ -187,6 +187,19 @@ clawt list
 
 列出当前项目在 `~/.clawt/worktrees/` 下的所有 worktree 及对应分支。
 
+### `clawt reset` — 重置主 worktree 工作区和暂存区
+
+```bash
+clawt reset
+```
+
+重置主 worktree 的工作区和暂存区（`git reset --hard` + `git clean -f`），恢复到干净状态。与 `clawt validate --clean` 不同，`reset` 不会删除 validate 快照文件，适用于只想清空变更而保留快照以便后续增量 validate 的场景。如果工作区和暂存区已是干净状态，会提示无需重置。
+
+```bash
+# 重置主 worktree 工作区和暂存区
+clawt reset
+```
+
 ### `clawt config` — 查看全局配置
 
 ```bash

package/dist/index.js

@@ -111,7 +111,11 @@ var MESSAGES = {
   MERGE_SQUASH_PENDING: (worktreePath, branch) => `\u2713 \u5DF2\u5C06\u6240\u6709\u63D0\u4EA4\u538B\u7F29\u5230\u6682\u5B58\u533A
   \u8BF7\u5728\u76EE\u6807 worktree \u4E2D\u63D0\u4EA4\u540E\u91CD\u65B0\u6267\u884C merge\uFF1A
   cd ${worktreePath}
-  \u63D0\u4EA4\u5B8C\u6210\u540E\u6267\u884C\uFF1Aclawt merge -b ${branch}`
+  \u63D0\u4EA4\u5B8C\u6210\u540E\u6267\u884C\uFF1Aclawt merge -b ${branch}`,
+  /** reset 成功 */
+  RESET_SUCCESS: "\u2713 \u4E3B worktree \u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\u5DF2\u91CD\u7F6E",
+  /** reset 时工作区和暂存区已干净 */
+  RESET_ALREADY_CLEAN: "\u4E3B worktree \u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\u5DF2\u662F\u5E72\u51C0\u72B6\u6001\uFF0C\u65E0\u9700\u91CD\u7F6E"
 };
 
 // src/constants/exitCodes.ts
@@ -341,22 +345,9 @@ function getDiffStat(worktreePath) {
   const output = execCommand("git diff --shortstat HEAD", { cwd: worktreePath });
   return parseShortStat(output);
 }
-function gitDiffCachedBinary(cwd) {
-  logger.debug(`\u6267\u884C\u547D\u4EE4: git diff --cached --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
-  return execSync2("git diff --cached --binary", {
-    cwd,
-    stdio: ["pipe", "pipe", "pipe"]
-  });
-}
-function gitApplyCachedFromStdin(patchContent, cwd) {
-  execCommandWithInput("git", ["apply", "--cached"], { input: patchContent, cwd });
-}
 function getCurrentBranch(cwd) {
   return execCommand("git rev-parse --abbrev-ref HEAD", { cwd });
 }
-function getHeadCommitHash(cwd) {
-  return execCommand("git rev-parse HEAD", { cwd });
-}
 function gitDiffBinaryAgainstBranch(branchName, cwd) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
   return execSync2(`git diff HEAD...${branchName} --binary`, {
@@ -385,6 +376,12 @@ function hasCommitWithMessage(branchName, messagePrefix, cwd) {
 function gitResetSoftTo(commitHash, cwd) {
   execCommand(`git reset --soft ${commitHash}`, { cwd });
 }
+function gitWriteTree(cwd) {
+  return execCommand("git write-tree", { cwd });
+}
+function gitReadTree(treeHash, cwd) {
+  execCommand(`git read-tree ${treeHash}`, { cwd });
+}
 
 // src/utils/formatter.ts
 import chalk from "chalk";
@@ -638,27 +635,21 @@ function launchInteractiveClaude(worktree) {
 import { join as join3 } from "path";
 import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync, readdirSync as readdirSync3, rmdirSync as rmdirSync2 } from "fs";
 function getSnapshotPath(projectName, branchName) {
-  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
-}
-function getSnapshotHeadPath(projectName, branchName) {
-  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
 }
 function hasSnapshot(projectName, branchName) {
   return existsSync5(getSnapshotPath(projectName, branchName));
 }
-function readSnapshot(projectName, branchName) {
+function readSnapshotTreeHash(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   logger.debug(`\u8BFB\u53D6 validate \u5FEB\u7167: ${snapshotPath}`);
-  return readFileSync2(snapshotPath);
+  return readFileSync2(snapshotPath, "utf-8").trim();
 }
-function writeSnapshot(projectName, branchName, patch, headHash) {
+function writeSnapshot(projectName, branchName, treeHash) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const snapshotDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
-  writeFileSync2(snapshotPath, patch);
-  if (headHash) {
-    writeFileSync2(getSnapshotHeadPath(projectName, branchName), headHash, "utf-8");
-  }
+  writeFileSync2(snapshotPath, treeHash, "utf-8");
   logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}`);
 }
 function removeSnapshot(projectName, branchName) {
@@ -667,17 +658,6 @@ function removeSnapshot(projectName, branchName) {
     unlinkSync(snapshotPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
   }
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  if (existsSync5(headPath)) {
-    unlinkSync(headPath);
-  }
-}
-function readSnapshotHead(projectName, branchName) {
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  if (!existsSync5(headPath)) {
-    return null;
-  }
-  return readFileSync2(headPath, "utf-8").trim();
 }
 
 // src/commands/list.ts
@@ -1052,13 +1032,12 @@ function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName
     }
   }
 }
-function saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName) {
+function saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName) {
   gitAddAll(mainWorktreePath);
-  const patch = gitDiffCachedBinary(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  const headHash = getHeadCommitHash(mainWorktreePath);
-  writeSnapshot(projectName, branchName, patch, headHash);
-  return patch;
+  writeSnapshot(projectName, branchName, treeHash);
+  return treeHash;
 }
 function handleValidateClean(options) {
   validateMainWorktree();
@@ -1074,26 +1053,24 @@ function handleValidateClean(options) {
 }
 function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
-  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
   printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
 }
 function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
-  const oldPatch = readSnapshot(projectName, branchName);
+  const oldTreeHash = readSnapshotTreeHash(projectName, branchName);
   if (!isWorkingDirClean(mainWorktreePath)) {
     gitResetHard(mainWorktreePath);
     gitCleanForce(mainWorktreePath);
   }
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
-  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
-  if (oldPatch.length > 0) {
-    try {
-      gitApplyCachedFromStdin(oldPatch, mainWorktreePath);
-    } catch (error) {
-      logger.warn(`\u589E\u91CF apply \u5931\u8D25: ${error}`);
-      printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-      printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
-      return;
-    }
+  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
+  try {
+    gitReadTree(oldTreeHash, mainWorktreePath);
+  } catch (error) {
+    logger.warn(`\u589E\u91CF read-tree \u5931\u8D25: ${error}`);
+    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+    return;
   }
   printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
@@ -1117,16 +1094,7 @@ async function handleValidate(options) {
     printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
     return;
   }
-  let isIncremental = hasSnapshot(projectName, options.branch);
-  if (isIncremental) {
-    const savedHead = readSnapshotHead(projectName, options.branch);
-    const currentHead = getHeadCommitHash(mainWorktreePath);
-    if (!savedHead || savedHead !== currentHead) {
-      logger.info(`\u4E3B\u5206\u652F HEAD \u4E0D\u5339\u914D (${savedHead ?? "null"} \u2192 ${currentHead})\uFF0C\u6E05\u9664\u65E7\u5FEB\u7167`);
-      removeSnapshot(projectName, options.branch);
-      isIncremental = false;
-    }
-  }
+  const isIncremental = hasSnapshot(projectName, options.branch);
   if (isIncremental) {
     if (!isWorkingDirClean(mainWorktreePath)) {
       await handleDirtyMainWorktree(mainWorktreePath);
@@ -1329,6 +1297,25 @@ async function handleSync(options) {
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
 }
 
+// src/commands/reset.ts
+function registerResetCommand(program2) {
+  program2.command("reset").description("\u91CD\u7F6E\u4E3B worktree \u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\uFF08\u4FDD\u7559 validate \u5FEB\u7167\uFF09").action(() => {
+    handleReset();
+  });
+}
+function handleReset() {
+  validateMainWorktree();
+  const mainWorktreePath = getGitTopLevel();
+  logger.info("reset \u547D\u4EE4\u6267\u884C");
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+    printSuccess(MESSAGES.RESET_SUCCESS);
+  } else {
+    printInfo(MESSAGES.RESET_ALREADY_CLEAN);
+  }
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1344,6 +1331,7 @@ registerValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
+registerResetCommand(program);
 process.on("uncaughtException", (error) => {
   if (error instanceof ClawtError) {
     printError(error.message);

package/docs/spec.md

@@ -24,6 +24,7 @@
   - [5.10 查看全局配置](#510-查看全局配置)
   - [5.11 在已有 Worktree 中恢复会话](#511-在已有-worktree-中恢复会话)
   - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
+  - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
 
@@ -140,8 +141,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 │   └── ...
 ├── validate-snapshots/                  # validate 快照目录
 │   └── <project-name>/                  # 以项目名分组
-│       ├── <branchName>.patch           # 每个分支一个 patch 快照文件
-│       ├── <branchName>.head            # 对应的主分支 HEAD commit hash（用于增量 validate 一致性校验）
+│       ├── <branchName>.tree            # 每个分支一个 tree hash 快照文件（存储 git tree 对象的 hash）
 │       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
@@ -168,6 +168,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt config`        | 查看全局配置                                     | 5.10     |
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 交互式会话      | 5.11     |
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
+| `clawt reset`         | 重置主 worktree 工作区和暂存区                       | 5.13     |
 
 所有命令执行前，都必须先执行**主 worktree 校验**（见 [2.1](#21-主-worktree-的定义与定位规则)）。
 
@@ -361,7 +362,7 @@ Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安
 
 **快照机制：**
 
-validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更保存为 patch 文件（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），同时保存主分支 HEAD commit hash 到 `.head` 文件（用于一致性校验）。当再次执行 validate 时，先校验主分支 HEAD 是否与快照记录一致（不一致则清除旧快照降级为首次模式），然后通过对比新旧快照，将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。
+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，无需一致性校验。
 
 **运行流程：**
 
@@ -371,7 +372,7 @@ validate 命令引入了**快照（snapshot）机制**来支持增量对比。
 
 1. **主 worktree 校验** (2.1)
 2. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
-3. 删除对应分支的 patch 快照文件
+3. 删除对应分支的快照文件
 4. 输出清理成功提示
 
 #### 首次 validate（无历史快照）
@@ -439,14 +440,13 @@ git restore --staged .
 > 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
 > 如果 patch apply 失败（目标分支与主分支差异过大），会提示用户先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
-##### 步骤 4：保存纯净快照
+##### 步骤 4：保存快照为 git tree 对象
 
-将主 worktree 工作目录的全量变更保存为 patch 文件，同时记录主分支 HEAD commit hash：
+将主 worktree 工作目录的全量变更保存为 git tree 对象：
 
 ```bash
 git add .
-git diff --cached --binary > ~/.clawt/validate-snapshots/<project>/<branchName>.patch
-git rev-parse HEAD > ~/.clawt/validate-snapshots/<project>/<branchName>.head
+git write-tree  # → 返回 tree hash，写入 ~/.clawt/validate-snapshots/<project>/<branchName>.tree
 git restore --staged .
 ```
 
@@ -461,41 +461,34 @@ git restore --staged .
 
 #### 增量 validate（存在历史快照）
 
-当 `~/.clawt/validate-snapshots/<project>/<branchName>.patch` 存在时，自动进入增量模式：
+当 `~/.clawt/validate-snapshots/<project>/<branchName>.tree` 存在时，自动进入增量模式：
 
-##### 步骤 1：校验主分支 HEAD 一致性
+##### 步骤 1：读取旧 tree hash
 
-读取 `.head` 文件中保存的主分支 HEAD hash，与当前主分支 HEAD 对比：
+在清空主 worktree 之前，读取上次保存的快照 tree hash。
 
-- **不一致或 `.head` 文件不存在** → 清除旧快照（`.patch` + `.head`），降级为首次 validate 模式
-- **一致** → 继续增量流程
-
-##### 步骤 2：读取旧 patch
-
-在清空主 worktree 之前，读取上次保存的快照 patch 内容。
-
-##### 步骤 3：确保主 worktree 干净
+##### 步骤 2：确保主 worktree 干净
 
 如果主 worktree 有残留状态，让用户选择处理方式（同首次 validate 步骤 1 的交互），做兜底清理。
 
-##### 步骤 4：从目标分支获取最新全量变更
+##### 步骤 3：从目标分支获取最新全量变更
 
 通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。
 
-##### 步骤 5：保存最新快照
+##### 步骤 4：保存最新快照为 git tree 对象
 
-将最新全量变更保存为新的 patch 文件 + HEAD hash（覆盖旧快照，流程同首次 validate 的步骤 4）。
+将最新全量变更保存为新的 tree 对象（覆盖旧快照，流程同首次 validate 的步骤 4）。
 
-##### 步骤 6：将旧 patch 应用到暂存区
+##### 步骤 5：将旧 tree 对象载入暂存区
 
 ```bash
-git apply --cached < <旧 patch 内容>
+git read-tree <旧 tree hash>
 ```
 
-- **应用成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
-- **应用失败**（文件结构变化过大）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
+- **读取成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
+- **读取失败**（tree 对象可能被 git gc 回收）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
 
-##### 步骤 7：输出成功提示
+##### 步骤 6：输出成功提示
 
 ```
 # 增量模式成功
@@ -586,7 +579,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 2. **主 worktree 状态检测**
    - 执行 `git status --porcelain`
    - 如果有更改：
-     - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），额外输出警告提示用户可先执行 `clawt validate -b <branchName> --clean` 清理
+     - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），额外输出警告提示用户可先执行 `clawt validate -b <branchName> --clean` 清理
      - 提示 `主 worktree 有未提交的更改，请先处理`，退出
    - 无更改 → 继续
 3. **Squash 检测与执行（auto-save 临时提交压缩）**
@@ -661,7 +654,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
 10. **清理 validate 快照**
-    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），自动删除该快照文件（merge 成功后快照已无意义）
+    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），自动删除该快照文件（merge 成功后快照已无意义）
 
 > **注意：** 清理确认在 merge 操作之前询问（避免 merge 成功后因交互中断而遗留未清理的 worktree），但清理操作在 merge 成功后才执行。
 
@@ -881,7 +874,7 @@ clawt sync -b <branchName>
        解决冲突后执行 git add . && git merge --continue
      ```
    - **无冲突** → 继续
-7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.patch` + `.head`），自动删除（代码基础已变化，旧快照无效）
+7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 文件），自动删除（代码基础已变化，旧快照无效）
 8. **输出成功提示**：
    ```
    ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
@@ -889,6 +882,38 @@ clawt sync -b <branchName>
 
 ---
 
+### 5.13 重置主 Worktree 工作区和暂存区
+
+**命令：**
+
+```bash
+clawt reset
+```
+
+**无参数。**
+
+**使用场景：**
+
+当用户通过 `clawt validate` 将分支变更迁移到主 worktree 后，希望快速清除工作区和暂存区的所有修改，恢复到干净状态。与 `clawt validate --clean` 的区别在于：`reset` 仅重置工作区和暂存区，**不删除** validate 快照文件，适用于只想清空变更而保留快照以便后续增量 validate 的场景。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **检测工作区状态**：通过 `git status --porcelain` 检测主 worktree 是否有未提交的更改
+   - **工作区干净** → 输出提示 `主 worktree 工作区和暂存区已是干净状态，无需重置`，退出
+   - **工作区不干净** → 继续
+3. **重置工作区和暂存区**：
+   ```bash
+   git reset --hard
+   git clean -f
+   ```
+4. **输出成功提示**：
+   ```
+   ✓ 主 worktree 工作区和暂存区已重置
+   ```
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/reset.ts

@@ -0,0 +1,42 @@
+import type { Command } from 'commander';
+import { logger } from '../logger/index.js';
+import { MESSAGES } from '../constants/index.js';
+import {
+  validateMainWorktree,
+  getGitTopLevel,
+  isWorkingDirClean,
+  gitResetHard,
+  gitCleanForce,
+  printSuccess,
+  printInfo,
+} from '../utils/index.js';
+
+/**
+ * 注册 reset 命令：重置主 worktree 工作区和暂存区
+ * @param {Command} program - Commander 实例
+ */
+export function registerResetCommand(program: Command): void {
+  program
+    .command('reset')
+    .description('重置主 worktree 工作区和暂存区（保留 validate 快照）')
+    .action(() => {
+      handleReset();
+    });
+}
+
+/**
+ * 执行 reset 命令：重置主 worktree 工作区和暂存区
+ */
+function handleReset(): void {
+  validateMainWorktree();
+  const mainWorktreePath = getGitTopLevel();
+  logger.info('reset 命令执行');
+
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+    printSuccess(MESSAGES.RESET_SUCCESS);
+  } else {
+    printInfo(MESSAGES.RESET_ALREADY_CLEAN);
+  }
+}

package/src/commands/validate.ts

@@ -18,16 +18,14 @@ import {
   gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
-  gitDiffCachedBinary,
-  gitApplyCachedFromStdin,
   gitDiffBinaryAgainstBranch,
   gitApplyFromStdin,
   gitResetSoft,
-  getHeadCommitHash,
+  gitWriteTree,
+  gitReadTree,
   hasLocalCommits,
   hasSnapshot,
-  readSnapshot,
-  readSnapshotHead,
+  readSnapshotTreeHash,
   writeSnapshot,
   removeSnapshot,
   printSuccess,
@@ -137,21 +135,19 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
 }
 
 /**
- * 保存当前主 worktree 工作目录变更为纯净快照 patch
- * 操作序列：git add . → git diff --cached --binary → git restore --staged .
- * 同时记录主分支 HEAD hash，用于增量 validate 一致性校验
+ * 保存当前主 worktree 工作目录变更为 git tree 对象快照
+ * 操作序列：git add . → git write-tree → git restore --staged .
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
- * @returns {Buffer} 生成的 patch 内容
+ * @returns {string} 生成的 tree hash
  */
-function saveCurrentSnapshotPatch(mainWorktreePath: string, projectName: string, branchName: string): Buffer {
+function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string, branchName: string): string {
   gitAddAll(mainWorktreePath);
-  const patch = gitDiffCachedBinary(mainWorktreePath);
+  const treeHash = gitWriteTree(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  const headHash = getHeadCommitHash(mainWorktreePath);
-  writeSnapshot(projectName, branchName, patch, headHash);
-  return patch;
+  writeSnapshot(projectName, branchName, treeHash);
+  return treeHash;
 }
 
 /**
@@ -172,7 +168,7 @@ function handleValidateClean(options: ValidateOptions): void {
     gitCleanForce(mainWorktreePath);
   }
 
-  // 删除对应的 patch 文件
+  // 删除对应的快照文件
   removeSnapshot(projectName, options.branch);
 
   printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
@@ -190,8 +186,8 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
   // 通过 patch 迁移目标分支全量变更到主 worktree
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
-  // 保存纯净快照到 patch 文件
-  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+  // 保存快照为 git tree 对象
+  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
 
   // 结果：暂存区=空，工作目录=全量变更
   printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
@@ -206,8 +202,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：读取旧 patch（在清空前读取）
-  const oldPatch = readSnapshot(projectName, branchName);
+  // 步骤 1：读取旧 tree hash（在清空前读取）
+  const oldTreeHash = readSnapshotTreeHash(projectName, branchName);
 
   // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
   // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
@@ -219,21 +215,19 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   // 步骤 3：通过 patch 从目标分支获取最新全量变更
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
-  // 步骤 4：保存最新快照
-  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
-
-  // 步骤 5：将旧 patch 应用到暂存区
-  if (oldPatch.length > 0) {
-    try {
-      gitApplyCachedFromStdin(oldPatch, mainWorktreePath);
-    } catch (error) {
-      // 旧 patch 无法应用（可能文件结构变化太大），降级为全量模式
-      logger.warn(`增量 apply 失败: ${error}`);
-      printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-      // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
-      printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
-      return;
-    }
+  // 步骤 4：保存最新快照为 git tree 对象
+  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
+
+  // 步骤 5：将旧 tree 对象载入暂存区（恢复上次快照状态）
+  try {
+    gitReadTree(oldTreeHash, mainWorktreePath);
+  } catch (error) {
+    // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
+    logger.warn(`增量 read-tree 失败: ${error}`);
+    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+    printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+    return;
   }
 
   // 结果：暂存区=上次快照，工作目录=最新全量变更
@@ -274,19 +268,8 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     return;
   }
 
-  // 判断是否为增量 validate
-  let isIncremental = hasSnapshot(projectName, options.branch);
-
-  // 主分支 HEAD 发生变化或旧快照无 .head 记录时，清除后走首次全量模式
-  if (isIncremental) {
-    const savedHead = readSnapshotHead(projectName, options.branch);
-    const currentHead = getHeadCommitHash(mainWorktreePath);
-    if (!savedHead || savedHead !== currentHead) {
-      logger.info(`主分支 HEAD 不匹配 (${savedHead ?? 'null'} → ${currentHead})，清除旧快照`);
-      removeSnapshot(projectName, options.branch);
-      isIncremental = false;
-    }
-  }
+  // 判断是否为增量 validate（tree 对象不依赖主分支 HEAD，无需一致性校验）
+  const isIncremental = hasSnapshot(projectName, options.branch);
 
   if (isIncremental) {
     // 增量模式：主 worktree 有残留状态时让用户选择处理方式

package/src/constants/messages.ts

@@ -95,4 +95,8 @@ export const MESSAGES = {
   /** squash 完成但未提供 -m，提示用户自行提交 */
   MERGE_SQUASH_PENDING: (worktreePath: string, branch: string) =>
     `✓ 已将所有提交压缩到暂存区\n  请在目标 worktree 中提交后重新执行 merge：\n  cd ${worktreePath}\n  提交完成后执行：clawt merge -b ${branch}`,
+  /** reset 成功 */
+  RESET_SUCCESS: '✓ 主 worktree 工作区和暂存区已重置',
+  /** reset 时工作区和暂存区已干净 */
+  RESET_ALREADY_CLEAN: '主 worktree 工作区和暂存区已是干净状态，无需重置',
 } as const;

package/src/index.ts

@@ -13,6 +13,7 @@ import { registerValidateCommand } from './commands/validate.js';
 import { registerMergeCommand } from './commands/merge.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerSyncCommand } from './commands/sync.js';
+import { registerResetCommand } from './commands/reset.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -38,6 +39,7 @@ registerValidateCommand(program);
 registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
+registerResetCommand(program);
 
 // 全局未捕获异常处理
 process.on('uncaughtException', (error) => {

package/src/utils/git.ts

@@ -407,3 +407,21 @@ export function hasCommitWithMessage(branchName: string, messagePrefix: string,
 export function gitResetSoftTo(commitHash: string, cwd?: string): void {
   execCommand(`git reset --soft ${commitHash}`, { cwd });
 }
+
+/**
+ * 将当前暂存区内容写入 git tree 对象并返回其 hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} tree 对象的 hash
+ */
+export function gitWriteTree(cwd?: string): string {
+  return execCommand('git write-tree', { cwd });
+}
+
+/**
+ * 将指定 tree 对象的内容载入暂存区（不影响工作目录）
+ * @param {string} treeHash - tree 对象的 hash
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitReadTree(treeHash: string, cwd?: string): void {
+  execCommand(`git read-tree ${treeHash}`, { cwd });
+}

package/src/utils/index.ts

@@ -38,6 +38,8 @@ export {
   gitMergeBase,
   hasCommitWithMessage,
   gitResetSoftTo,
+  gitWriteTree,
+  gitReadTree,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -47,4 +49,4 @@ 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, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, readSnapshotHead } from './validate-snapshot.js';
+export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';

package/src/utils/validate-snapshot.ts

@@ -8,20 +8,10 @@ import { logger } from '../logger/index.js';
  * 获取指定项目和分支的 validate 快照文件路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
- * @returns {string} patch 文件的绝对路径
+ * @returns {string} tree hash 文件的绝对路径
  */
 export function getSnapshotPath(projectName: string, branchName: string): string {
-  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.patch`);
-}
-
-/**
- * 获取指定项目和分支的快照 HEAD hash 文件路径
- * @param {string} projectName - 项目名
- * @param {string} branchName - 分支名
- * @returns {string} head 文件的绝对路径
- */
-function getSnapshotHeadPath(projectName: string, branchName: string): string {
-  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
 }
 
 /**
@@ -35,33 +25,28 @@ export function hasSnapshot(projectName: string, branchName: string): boolean {
 }
 
 /**
- * 读取指定项目和分支的 validate 快照内容
+ * 读取指定项目和分支的 validate 快照中存储的 tree hash
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
- * @returns {Buffer} patch 文件内容（Buffer 格式，保留二进制完整性）
+ * @returns {string} tree 对象的 hash
  */
-export function readSnapshot(projectName: string, branchName: string): Buffer {
+export function readSnapshotTreeHash(projectName: string, branchName: string): string {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   logger.debug(`读取 validate 快照: ${snapshotPath}`);
-  return readFileSync(snapshotPath);
+  return readFileSync(snapshotPath, 'utf-8').trim();
 }
 
 /**
  * 写入 validate 快照内容（自动创建目录）
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
- * @param {Buffer} patch - patch 内容（Buffer 格式）
- * @param {string} [headHash] - 主分支 HEAD commit hash（用于增量 validate 一致性校验）
+ * @param {string} treeHash - git tree 对象的 hash
  */
-export function writeSnapshot(projectName: string, branchName: string, patch: Buffer, headHash?: string): void {
+export function writeSnapshot(projectName: string, branchName: string, treeHash: string): void {
   const snapshotPath = getSnapshotPath(projectName, branchName);
   const snapshotDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
-  writeFileSync(snapshotPath, patch);
-  // 保存主分支 HEAD hash，用于下次增量 validate 时校验一致性
-  if (headHash) {
-    writeFileSync(getSnapshotHeadPath(projectName, branchName), headHash, 'utf-8');
-  }
+  writeFileSync(snapshotPath, treeHash, 'utf-8');
   logger.info(`已保存 validate 快照: ${snapshotPath}`);
 }
 
@@ -76,25 +61,6 @@ export function removeSnapshot(projectName: string, branchName: string): void {
     unlinkSync(snapshotPath);
     logger.info(`已删除 validate 快照: ${snapshotPath}`);
   }
-  // 同时删除对应的 .head 文件
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  if (existsSync(headPath)) {
-    unlinkSync(headPath);
-  }
-}
-
-/**
- * 读取快照保存时的主分支 HEAD commit hash
- * @param {string} projectName - 项目名
- * @param {string} branchName - 分支名
- * @returns {string | null} HEAD hash，不存在则返回 null
- */
-export function readSnapshotHead(projectName: string, branchName: string): string | null {
-  const headPath = getSnapshotHeadPath(projectName, branchName);
-  if (!existsSync(headPath)) {
-    return null;
-  }
-  return readFileSync(headPath, 'utf-8').trim();
 }
 
 /**