clawt 2.1.0 → 2.2.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,13 +60,14 @@ 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 快照机制
 

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 命令）
 
@@ -75,11 +75,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/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息、reset 相关消息）
 - `src/types/` — TypeScript 类型定义
 - `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
 - `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）

package/README.md

@@ -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
@@ -1329,6 +1333,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 +1367,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-非功能性需求)
 
@@ -168,6 +169,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-的定义与定位规则)）。
 
@@ -889,6 +891,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.2.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/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) => {