clawt 1.2.0 → 1.4.0

package/docs/spec.md

@@ -23,6 +23,7 @@
   - [5.9 日志系统](#59-日志系统)
   - [5.10 查看全局配置](#510-查看全局配置)
   - [5.11 在已有 Worktree 中恢复会话](#511-在已有-worktree-中恢复会话)
+  - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
 
@@ -137,6 +138,11 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ├── logs/                                # 日志目录
 │   ├── clawt-2025-02-06.log
 │   └── ...
+├── validate-snapshots/                  # validate 快照目录
+│   └── <project-name>/                  # 以项目名分组
+│       ├── <branchName>.patch           # 每个分支一个 patch 快照文件
+│       ├── <branchName>.head            # 对应的主分支 HEAD commit hash（用于增量 validate 一致性校验）
+│       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
         ├── <branchName>/                # n=1 时直接使用分支名
@@ -161,6 +167,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt list`          | 列出当前项目所有 worktree                        | 5.8      |
 | `clawt config`        | 查看全局配置                                     | 5.10     |
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 交互式会话      | 5.11     |
+| `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
 
 所有命令执行前，都必须先执行**主 worktree 校验**（见 [2.1](#21-主-worktree-的定义与定位规则)）。
 
@@ -336,24 +343,40 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 **命令：**
 
 ```bash
-clawt validate -b <branchName>
+clawt validate -b <branchName> [--clean]
 ```
 
 **参数：**
 
-| 参数 | 必填 | 说明                                                                     |
-| ---- | ---- | ------------------------------------------------------------------------ |
-| `-b` | 是   | 要验证的 worktree 分支名（例如 `feature-scheme-1`）                        |
+| 参数      | 必填 | 说明                                                                     |
+| --------- | ---- | ------------------------------------------------------------------------ |
+| `-b`      | 是   | 要验证的 worktree 分支名（例如 `feature-scheme-1`）                        |
+| `--clean` | 否   | 清理 validate 状态（重置主 worktree 并删除快照）                            |
 
 > **限制：** 单次只能验证一个分支，不支持批量验证。
 
 **背景说明：**
 
-Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安装依赖耗时较长。利用 `git stash` 可以在所有 worktree 间共享的特性，将目标 worktree 的变更迁移到主 worktree 进行测试，无需重新安装依赖。
+Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安装依赖耗时较长。利用 `git diff HEAD...branch --binary`（三点 diff）可以获取目标分支自分叉点以来的全量变更（包含已提交和未提交的修改），将其作为 patch 应用到主 worktree 中进行测试，无需重新安装依赖。
+
+**快照机制：**
+
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更保存为 patch 文件（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），同时保存主分支 HEAD commit hash 到 `.head` 文件（用于一致性校验）。当再次执行 validate 时，先校验主分支 HEAD 是否与快照记录一致（不一致则清除旧快照降级为首次模式），然后通过对比新旧快照，将上次快照应用到暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。
 
 **运行流程：**
 
-#### 步骤 1：检测主 worktree 工作区状态
+#### `--clean` 模式
+
+当指定 `--clean` 选项时，执行清理逻辑后直接返回，不进入常规 validate 流程：
+
+1. **主 worktree 校验** (2.1)
+2. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
+3. 删除对应分支的 patch 快照文件
+4. 输出清理成功提示
+
+#### 首次 validate（无历史快照）
+
+##### 步骤 1：检测主 worktree 工作区状态
 
 执行 `git status --porcelain`，判断主 worktree 是否有未提交的更改。
 
@@ -376,50 +399,110 @@ Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安
 
 执行完毕后，通过 `git status --porcelain` 再次检测状态，确保工作区干净。如果仍然不干净，报错退出。
 
-#### 步骤 2：在目标 worktree 中创建 stash
+##### 步骤 2：检测目标分支变更
+
+统一检测目标 worktree 的未提交修改和已提交 commit：
 
 ```bash
-# 定位目标 worktree
+# 检测未提交修改
 cd ~/.clawt/worktrees/<project>/<branchName>
-
-# 校验目标 worktree 是否有更改
 git status --porcelain
+
+# 检测已提交 commit（在主 worktree 中执行）
+cd <主 worktree 路径>
+git log HEAD..<branchName> --oneline
 ```
 
-- **无更改** → 输出提示 `该 worktree 的分支上没有任何更改，无需验证`，退出
-- **有更改** → 继续
+- **两者均无** → 输出提示 `该 worktree 的分支上没有任何更改，无需验证`，退出
+- **至少有一项** → 继续
+
+##### 步骤 3：通过 patch 迁移目标分支全量变更
+
+使用三点 diff（`git diff HEAD...branchName --binary`）获取目标分支自分叉点以来的全量变更。如果目标 worktree 有未提交修改，先做临时 commit 以便 diff 能捕获全部变更，diff 完成后撤销临时 commit 恢复原状。
 
 ```bash
+# 如果有未提交修改，先临时提交
+cd ~/.clawt/worktrees/<project>/<branchName>
 git add .
-git stash push -m "clawt:validate:<branchName>"
-git stash apply
+git commit -m "clawt:temp-commit-for-validate"
+
+# 在主 worktree 中执行三点 diff
+cd <主 worktree 路径>
+git diff HEAD...<branchName> --binary | git apply
+
+# 撤销临时 commit，恢复目标 worktree 原状
+cd ~/.clawt/worktrees/<project>/<branchName>
+git reset --soft HEAD~1
 git restore --staged .
 ```
 
-> 此步骤结束后，目标 worktree 的代码保持原样（变更仍然存在于工作区），同时变更已被记录到共享的 stash 中。
+> 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
+> 如果 patch apply 失败（目标分支与主分支差异过大），会提示用户先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 
-#### 步骤 3：在主 worktree 应用 stash
+##### 步骤 4：保存纯净快照
+
+将主 worktree 工作目录的全量变更保存为 patch 文件，同时记录主分支 HEAD commit hash：
 
 ```bash
-# 回到主 worktree
-cd <主 worktree 路径>
+git add .
+git diff --cached --binary > ~/.clawt/validate-snapshots/<project>/<branchName>.patch
+git rev-parse HEAD > ~/.clawt/validate-snapshots/<project>/<branchName>.head
+git restore --staged .
+```
 
-# 校验 stash@{0} 是否为我们创建的
-git stash list
+> 结果：暂存区=空，工作目录=全量变更。
+
+##### 步骤 5：输出成功提示
+
+```
+✓ 已将分支 feature-scheme-1 的变更应用到主 worktree
+  可以开始验证了
 ```
 
-检查 `stash@{0}` 的消息是否包含 `clawt:validate:<branchName>`：
+#### 增量 validate（存在历史快照）
+
+当 `~/.clawt/validate-snapshots/<project>/<branchName>.patch` 存在时，自动进入增量模式：
+
+##### 步骤 1：校验主分支 HEAD 一致性
+
+读取 `.head` 文件中保存的主分支 HEAD hash，与当前主分支 HEAD 对比：
+
+- **不一致或 `.head` 文件不存在** → 清除旧快照（`.patch` + `.head`），降级为首次 validate 模式
+- **一致** → 继续增量流程
+
+##### 步骤 2：读取旧 patch
+
+在清空主 worktree 之前，读取上次保存的快照 patch 内容。
+
+##### 步骤 3：确保主 worktree 干净
+
+如果主 worktree 有残留状态，让用户选择处理方式（同首次 validate 步骤 1 的交互），做兜底清理。
 
-- **不包含** → 报错：`git stash list 已变更，请重新执行`，退出
-- **包含** → 继续
+##### 步骤 4：从目标分支获取最新全量变更
+
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 3）。
+
+##### 步骤 5：保存最新快照
+
+将最新全量变更保存为新的 patch 文件 + HEAD hash（覆盖旧快照，流程同首次 validate 的步骤 4）。
+
+##### 步骤 6：将旧 patch 应用到暂存区
 
 ```bash
-git stash pop stash@{0}
+git apply --cached < <旧 patch 内容>
 ```
 
-#### 步骤 4：输出成功提示
+- **应用成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
+- **应用失败**（文件结构变化过大）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
+
+##### 步骤 7：输出成功提示
 
 ```
+# 增量模式成功
+✓ 已将分支 feature-scheme-1 的最新变更应用到主 worktree（增量模式）
+  暂存区 = 上次快照，工作目录 = 最新变更
+
+# 增量降级为全量
 ✓ 已将分支 feature-scheme-1 的变更应用到主 worktree
   可以开始验证了
 ```
@@ -503,7 +586,9 @@ clawt merge -b <branchName> [-m <commitMessage>]
 1. **主 worktree 校验** (2.1)
 2. **主 worktree 状态检测**
    - 执行 `git status --porcelain`
-   - 如果有更改 → 提示 `主 worktree 有未提交的更改，请先处理`，退出
+   - 如果有更改：
+     - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），额外输出警告提示用户可先执行 `clawt validate -b <branchName> --clean` 清理
+     - 提示 `主 worktree 有未提交的更改，请先处理`，退出
    - 无更改 → 继续
 3. **根据目标 worktree 状态决定是否需要提交**
    - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
@@ -561,6 +646,9 @@ clawt merge -b <branchName> [-m <commitMessage>]
      ```
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
+9. **清理 validate 快照**
+   - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.patch`），自动删除该快照文件（merge 成功后快照已无意义）
+
 > **注意：** 清理确认在 merge 操作之前询问（避免 merge 成功后因交互中断而遗留未清理的 worktree），但清理操作在 merge 成功后才执行。
 
 ---
@@ -739,6 +827,54 @@ clawt resume -b <branchName>
 
 ---
 
+### 5.12 将主分支代码同步到目标 Worktree
+
+**命令：**
+
+```bash
+clawt sync -b <branchName>
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                  |
+| ---- | ---- | ----------------------------------------------------- |
+| `-b` | 是   | 要同步的分支名（对应已有 worktree 的分支）               |
+
+**使用场景：**
+
+当目标 worktree 的分支与主分支差异过大（例如主分支有了新的提交），导致 `clawt validate` 的 patch apply 失败时，可以通过 `clawt sync` 将主分支最新代码合并到目标 worktree，使其保持与主分支同步。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **检查目标 worktree 是否存在**：确认 `~/.clawt/worktrees/<project>/<branchName>` 目录存在
+   - 不存在 → 报错退出
+3. **获取主分支名**：通过 `git rev-parse --abbrev-ref HEAD` 获取主 worktree 当前分支名（不硬编码 main/master）
+4. **自动保存未提交变更**：检查目标 worktree 是否有未提交修改
+   - 有修改 → 自动执行 `git add . && git commit -m "chore: auto-save before sync"` 保存变更
+   - 无修改 → 跳过
+5. **在目标 worktree 中合并主分支**：
+   ```bash
+   cd ~/.clawt/worktrees/<project>/<branchName>
+   git merge <mainBranch>
+   ```
+6. **冲突处理**：
+   - **有冲突** → 输出警告，提示用户进入目标 worktree 手动解决：
+     ```
+     合并存在冲突，请进入目标 worktree 手动解决：
+       cd ~/.clawt/worktrees/<project>/<branchName>
+       解决冲突后执行 git add . && git merge --continue
+     ```
+   - **无冲突** → 继续
+7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.patch` + `.head`），自动删除（代码基础已变化，旧快照无效）
+8. **输出成功提示**：
+   ```
+   ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>
+   ```
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/merge.ts

@@ -7,6 +7,7 @@ import { MESSAGES } from '../constants/index.js';
 import type { MergeOptions } from '../types/index.js';
 import {
   validateMainWorktree,
+  getProjectName,
   getGitTopLevel,
   getProjectWorktreeDir,
   isWorkingDirClean,
@@ -17,8 +18,11 @@ import {
   gitPull,
   gitPush,
   hasLocalCommits,
+  hasSnapshot,
+  removeSnapshot,
   printSuccess,
   printInfo,
+  printWarning,
   getConfigValue,
   confirmAction,
   cleanupWorktrees,
@@ -82,8 +86,14 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
 
+  const projectName = getProjectName();
+
   // 步骤 3：主 worktree 状态检测
   if (!isWorkingDirClean(mainWorktreePath)) {
+    // 如果存在 validate 快照状态，提示用户先清理
+    if (hasSnapshot(projectName, options.branch)) {
+      printWarning(MESSAGES.MERGE_VALIDATE_STATE_HINT(options.branch));
+    }
     throw new ClawtError(MESSAGES.MAIN_WORKTREE_DIRTY);
   }
 
@@ -143,4 +153,9 @@ async function handleMerge(options: MergeOptions): Promise<void> {
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }
+
+  // 步骤 10：清理 validate 快照（merge 成功后快照已无意义）
+  if (hasSnapshot(projectName, options.branch)) {
+    removeSnapshot(projectName, options.branch);
+  }
 }

package/src/commands/sync.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import type { Command } from 'commander';
+import { logger } from '../logger/index.js';
+import { ClawtError } from '../errors/index.js';
+import { MESSAGES } from '../constants/index.js';
+import type { SyncOptions } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getGitTopLevel,
+  getProjectName,
+  getProjectWorktreeDir,
+  isWorkingDirClean,
+  gitAddAll,
+  gitCommit,
+  gitMerge,
+  hasMergeConflict,
+  getCurrentBranch,
+  hasSnapshot,
+  removeSnapshot,
+  printSuccess,
+  printInfo,
+  printWarning,
+} from '../utils/index.js';
+
+/**
+ * 注册 sync 命令：将主分支最新代码同步到目标 worktree
+ * @param {Command} program - Commander 实例
+ */
+export function registerSyncCommand(program: Command): void {
+  program
+    .command('sync')
+    .description('将主分支最新代码同步到目标 worktree')
+    .requiredOption('-b, --branch <branchName>', '要同步的分支名')
+    .action(async (options: SyncOptions) => {
+      await handleSync(options);
+    });
+}
+
+/**
+ * 自动保存目标 worktree 中的未提交变更
+ * @param {string} worktreePath - 目标 worktree 路径
+ * @param {string} branch - 分支名
+ */
+function autoSaveChanges(worktreePath: string, branch: string): void {
+  gitAddAll(worktreePath);
+  gitCommit('chore: auto-save before sync', worktreePath);
+  printInfo(MESSAGES.SYNC_AUTO_COMMITTED(branch));
+  logger.info(`已自动保存 ${branch} 分支的未提交变更`);
+}
+
+/**
+ * 在目标 worktree 中合并主分支
+ * @param {string} worktreePath - 目标 worktree 路径
+ * @param {string} mainBranch - 主分支名
+ * @returns {boolean} 是否存在冲突（true 表示有冲突）
+ */
+function mergeMainBranch(worktreePath: string, mainBranch: string): boolean {
+  try {
+    gitMerge(mainBranch, worktreePath);
+    return false;
+  } catch {
+    // 合并失败时检查是否为冲突
+    if (hasMergeConflict(worktreePath)) {
+      return true;
+    }
+    // 非冲突错误则向上抛出
+    throw new ClawtError(`合并 ${mainBranch} 失败`);
+  }
+}
+
+/**
+ * 执行 sync 命令的核心逻辑
+ * 将主分支最新代码同步到目标 worktree
+ * @param {SyncOptions} options - 命令选项
+ */
+async function handleSync(options: SyncOptions): Promise<void> {
+  validateMainWorktree();
+
+  const { branch } = options;
+  logger.info(`sync 命令执行，分支: ${branch}`);
+
+  // 检查目标 worktree 是否存在
+  const projectWorktreeDir = getProjectWorktreeDir();
+  const targetWorktreePath = `${projectWorktreeDir}/${branch}`;
+
+  if (!existsSync(targetWorktreePath)) {
+    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branch));
+  }
+
+  // 获取主分支名（不硬编码 main/master）
+  const mainWorktreePath = getGitTopLevel();
+  const mainBranch = getCurrentBranch(mainWorktreePath);
+
+  // 检查目标 worktree 是否有未提交变更，有则自动保存
+  if (!isWorkingDirClean(targetWorktreePath)) {
+    autoSaveChanges(targetWorktreePath, branch);
+  }
+
+  // 在目标 worktree 中合并主分支
+  printInfo(MESSAGES.SYNC_MERGING(branch, mainBranch));
+  const hasConflict = mergeMainBranch(targetWorktreePath, mainBranch);
+
+  if (hasConflict) {
+    printWarning(MESSAGES.SYNC_CONFLICT(targetWorktreePath));
+    return;
+  }
+
+  // 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
+  const projectName = getProjectName();
+  if (hasSnapshot(projectName, branch)) {
+    removeSnapshot(projectName, branch);
+    logger.info(`已清除分支 ${branch} 的 validate 快照`);
+  }
+
+  printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+}