clawt 1.2.0 → 1.4.0

package/src/commands/validate.ts

@@ -13,16 +13,24 @@ import {
   getProjectWorktreeDir,
   isWorkingDirClean,
   gitAddAll,
+  gitCommit,
   gitStashPush,
-  gitStashApply,
-  gitStashPop,
-  gitStashList,
   gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
-  getStatusPorcelain,
+  gitDiffCachedBinary,
+  gitApplyCachedFromStdin,
+  gitDiffBinaryAgainstBranch,
+  gitApplyFromStdin,
+  gitResetSoft,
+  getHeadCommitHash,
+  hasLocalCommits,
+  hasSnapshot,
+  readSnapshot,
+  readSnapshotHead,
+  writeSnapshot,
+  removeSnapshot,
   printSuccess,
-  printError,
   printWarning,
   printInfo,
 } from '../utils/index.js';
@@ -36,13 +44,14 @@ export function registerValidateCommand(program: Command): void {
     .command('validate')
     .description('在主 worktree 验证某个 worktree 分支的变更')
     .requiredOption('-b, --branch <branchName>', '要验证的分支名')
+    .option('--clean', '清理 validate 状态（重置主 worktree 并删除快照）')
     .action(async (options: ValidateOptions) => {
       await handleValidate(options);
     });
 }
 
 /**
- * 处理主 worktree 工作区有未提交更改的情况
+ * 处理主 worktree 工作区有未提交更改的情况（首次 validate 时使用）
  * @param {string} mainWorktreePath - 主 worktree 路径
  */
 async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void> {
@@ -86,11 +95,162 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
   }
 }
 
+/**
+ * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
+ * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ */
+function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): void {
+  let didTempCommit = false;
+
+  try {
+    // 如果有未提交修改，先做临时 commit 以便 diff 能捕获全部变更
+    if (hasUncommitted) {
+      gitAddAll(targetWorktreePath);
+      gitCommit('clawt:temp-commit-for-validate', targetWorktreePath);
+      didTempCommit = true;
+    }
+
+    // 在主 worktree 执行三点 diff，获取目标分支自分叉点以来的全量变更
+    const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
+
+    // 应用 patch 到主 worktree 工作目录
+    if (patch.length > 0) {
+      try {
+        gitApplyFromStdin(patch, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`patch apply 失败: ${error}`);
+        printWarning(MESSAGES.VALIDATE_PATCH_APPLY_FAILED(branchName));
+        throw error;
+      }
+    }
+  } finally {
+    // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
+    if (didTempCommit) {
+      gitResetSoft(1, targetWorktreePath);
+      gitRestoreStaged(targetWorktreePath);
+    }
+  }
+}
+
+/**
+ * 保存当前主 worktree 工作目录变更为纯净快照 patch
+ * 操作序列：git add . → git diff --cached --binary → git restore --staged .
+ * 同时记录主分支 HEAD hash，用于增量 validate 一致性校验
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {Buffer} 生成的 patch 内容
+ */
+function saveCurrentSnapshotPatch(mainWorktreePath: string, projectName: string, branchName: string): Buffer {
+  gitAddAll(mainWorktreePath);
+  const patch = gitDiffCachedBinary(mainWorktreePath);
+  gitRestoreStaged(mainWorktreePath);
+  const headHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, patch, headHash);
+  return patch;
+}
+
+/**
+ * 处理 --clean 选项：清理 validate 状态
+ * @param {ValidateOptions} options - 命令选项
+ */
+function handleValidateClean(options: ValidateOptions): void {
+  validateMainWorktree();
+
+  const projectName = getProjectName();
+  const mainWorktreePath = getGitTopLevel();
+
+  logger.info(`validate --clean 执行，分支: ${options.branch}`);
+
+  // 清空主 worktree
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(mainWorktreePath);
+  }
+
+  // 删除对应的 patch 文件
+  removeSnapshot(projectName, options.branch);
+
+  printSuccess(MESSAGES.VALIDATE_CLEANED(options.branch));
+}
+
+/**
+ * 首次 validate 逻辑（无历史快照）
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ */
+function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+  // 通过 patch 迁移目标分支全量变更到主 worktree
+  migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
+
+  // 保存纯净快照到 patch 文件
+  saveCurrentSnapshotPatch(mainWorktreePath, projectName, branchName);
+
+  // 结果：暂存区=空，工作目录=全量变更
+  printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+}
+
+/**
+ * 增量 validate 逻辑（存在历史快照）
+ * @param {string} targetWorktreePath - 目标 worktree 路径
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
+ */
+function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
+  // 步骤 1：读取旧 patch（在清空前读取）
+  const oldPatch = readSnapshot(projectName, branchName);
+
+  // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
+  // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
+  if (!isWorkingDirClean(mainWorktreePath)) {
+    gitResetHard(mainWorktreePath);
+    gitCleanForce(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;
+    }
+  }
+
+  // 结果：暂存区=上次快照，工作目录=最新全量变更
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
+}
+
 /**
  * 执行 validate 命令的核心逻辑
  * @param {ValidateOptions} options - 命令选项
  */
 async function handleValidate(options: ValidateOptions): Promise<void> {
+  // 处理 --clean 选项
+  if (options.clean) {
+    handleValidateClean(options);
+    return;
+  }
+
   validateMainWorktree();
 
   const projectName = getProjectName();
@@ -105,33 +265,41 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(options.branch));
   }
 
-  // 步骤 1：检测主 worktree 工作区状态
-  if (!isWorkingDirClean(mainWorktreePath)) {
-    await handleDirtyMainWorktree(mainWorktreePath);
-  }
+  // 统一检测未提交修改 + 已提交 commit
+  const hasUncommitted = !isWorkingDirClean(targetWorktreePath);
+  const hasCommitted = hasLocalCommits(options.branch, mainWorktreePath);
 
-  // 步骤 2：在目标 worktree 中创建 stash
-  if (isWorkingDirClean(targetWorktreePath)) {
+  if (!hasUncommitted && !hasCommitted) {
     printInfo(MESSAGES.TARGET_WORKTREE_CLEAN);
     return;
   }
 
-  const stashMessage = `clawt:validate:${options.branch}`;
-  gitAddAll(targetWorktreePath);
-  gitStashPush(stashMessage, targetWorktreePath);
-  gitStashApply(targetWorktreePath);
-  gitRestoreStaged(targetWorktreePath);
-
-  // 步骤 3：在主 worktree 应用 stash
-  const stashList = gitStashList(mainWorktreePath);
-  const firstLine = stashList.split('\n')[0] || '';
+  // 判断是否为增量 validate
+  let isIncremental = hasSnapshot(projectName, options.branch);
 
-  if (!firstLine.includes(stashMessage)) {
-    throw new ClawtError(MESSAGES.STASH_CHANGED);
+  // 主分支 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;
+    }
   }
 
-  gitStashPop(0, mainWorktreePath);
+  if (isIncremental) {
+    // 增量模式：主 worktree 有残留状态时让用户选择处理方式
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
+    }
+    handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+  } else {
+    // 首次模式：先确保主 worktree 干净
+    if (!isWorkingDirClean(mainWorktreePath)) {
+      await handleDirtyMainWorktree(mainWorktreePath);
+    }
 
-  // 步骤 4：输出成功提示
-  printSuccess(MESSAGES.VALIDATE_SUCCESS(options.branch));
+    handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, options.branch, hasUncommitted);
+  }
 }

package/src/constants/index.ts

@@ -1,4 +1,4 @@
-export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR } from './paths.js';
+export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR } from './paths.js';
 export { INVALID_BRANCH_CHARS } from './branch.js';
 export { MESSAGES } from './messages.js';
 export { EXIT_CODES } from './exitCodes.js';

package/src/constants/messages.ts

@@ -23,8 +23,6 @@ export const MESSAGES = {
   MAIN_WORKTREE_DIRTY: '主 worktree 有未提交的更改，请先处理',
   /** 目标 worktree 无更改 */
   TARGET_WORKTREE_CLEAN: '该 worktree 的分支上没有任何更改，无需验证',
-  /** stash 已变更 */
-  STASH_CHANGED: 'git stash list 已变更，请重新执行',
   /** validate 成功 */
   VALIDATE_SUCCESS: (branch: string) =>
     `✓ 已将分支 ${branch} 的变更应用到主 worktree\n  可以开始验证了`,
@@ -64,4 +62,29 @@ export const MESSAGES = {
   INVALID_COUNT: (value: string) => `无效的创建数量: "${value}"，请输入正整数`,
   /** worktree 状态获取失败 */
   WORKTREE_STATUS_UNAVAILABLE: '(状态不可用)',
+  /** 增量 validate 成功提示 */
+  INCREMENTAL_VALIDATE_SUCCESS: (branch: string) =>
+    `✓ 已将分支 ${branch} 的最新变更应用到主 worktree（增量模式）\n  暂存区 = 上次快照，工作目录 = 最新变更`,
+  /** 增量 validate 降级为全量模式提示 */
+  INCREMENTAL_VALIDATE_FALLBACK: '增量对比失败，已降级为全量模式',
+  /** validate 状态已清理 */
+  VALIDATE_CLEANED: (branch: string) => `✓ 分支 ${branch} 的 validate 状态已清理`,
+  /** merge 命令检测到 validate 状态的提示 */
+  MERGE_VALIDATE_STATE_HINT: (branch: string) =>
+    `主 worktree 可能存在 validate 残留状态，可先执行 clawt validate -b ${branch} --clean 清理`,
+  /** sync 自动保存未提交变更 */
+  SYNC_AUTO_COMMITTED: (branch: string) =>
+    `已自动保存 ${branch} 分支的未提交变更`,
+  /** sync 开始合并 */
+  SYNC_MERGING: (targetBranch: string, mainBranch: string) =>
+    `正在将 ${mainBranch} 合并到 ${targetBranch} ...`,
+  /** sync 成功 */
+  SYNC_SUCCESS: (targetBranch: string, mainBranch: string) =>
+    `✓ 已将 ${mainBranch} 的最新代码同步到 ${targetBranch}`,
+  /** sync 冲突 */
+  SYNC_CONFLICT: (worktreePath: string) =>
+    `合并存在冲突，请进入目标 worktree 手动解决：\n  cd ${worktreePath}\n  解决冲突后执行 git add . && git merge --continue`,
+  /** validate patch apply 失败，提示用户同步主分支 */
+  VALIDATE_PATCH_APPLY_FAILED: (branch: string) =>
+    `变更迁移失败：目标分支与主分支差异过大\n  请先执行 clawt sync -b ${branch} 同步主分支后重试`,
 } as const;

package/src/constants/paths.ts

@@ -12,3 +12,6 @@ export const LOGS_DIR = join(CLAWT_HOME, 'logs');
 
 /** worktree 统一存放目录 ~/.clawt/worktrees/ */
 export const WORKTREES_DIR = join(CLAWT_HOME, 'worktrees');
+
+/** validate 快照目录 ~/.clawt/validate-snapshots/ */
+export const VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, 'validate-snapshots');

package/src/index.ts

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

package/src/types/command.ts

@@ -18,6 +18,8 @@ export interface RunOptions {
 export interface ValidateOptions {
   /** 要验证的分支名 */
   branch: string;
+  /** 清理 validate 状态 */
+  clean?: boolean;
 }
 
 /** merge 命令选项 */
@@ -43,3 +45,9 @@ export interface ResumeOptions {
   /** 要恢复的分支名 */
   branch: string;
 }
+
+/** sync 命令选项 */
+export interface SyncOptions {
+  /** 要同步的分支名 */
+  branch: string;
+}

package/src/types/index.ts

@@ -1,5 +1,5 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';

package/src/utils/git.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path';
-import { execCommand } from './shell.js';
+import { execSync } from 'node:child_process';
+import { execCommand, execCommandWithInput } from './shell.js';
 import { logger } from '../logger/index.js';
 
 /**
@@ -189,6 +190,15 @@ export function gitStashPop(index: number = 0, cwd?: string): void {
   execCommand(`git stash pop stash@{${index}}`, { cwd });
 }
 
+/**
+ * git stash drop stash@{index}
+ * @param {number} index - stash 索引
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitStashDrop(index: number = 0, cwd?: string): void {
+  execCommand(`git stash drop stash@{${index}}`, { cwd });
+}
+
 /**
  * git stash list
  * @param {string} cwd - 工作目录
@@ -296,3 +306,77 @@ export function getDiffStat(branchName: string, worktreePath: string, cwd?: stri
     deletions: committed.deletions + uncommitted.deletions,
   };
 }
+
+/**
+ * 获取暂存区相对于 HEAD 的完整 diff（含二进制文件）
+ * 注意：返回原始输出不做 trim，保留 patch 格式完整性
+ * @param {string} [cwd] - 工作目录
+ * @returns {Buffer} diff 原始输出（Buffer 格式，保留二进制数据完整性）
+ */
+export function gitDiffCachedBinary(cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff --cached --binary${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync('git diff --cached --binary', {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 将 patch 内容通过 stdin 应用到暂存区
+ * @param {Buffer} patchContent - patch 内容（Buffer 格式）
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitApplyCachedFromStdin(patchContent: Buffer, cwd?: string): void {
+  execCommandWithInput('git', ['apply', '--cached'], { input: patchContent, cwd });
+}
+
+/**
+ * 获取当前分支名
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} 当前分支名
+ */
+export function getCurrentBranch(cwd?: string): string {
+  return execCommand('git rev-parse --abbrev-ref HEAD', { cwd });
+}
+
+/**
+ * 获取当前 HEAD 的 commit hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} commit hash
+ */
+export function getHeadCommitHash(cwd?: string): string {
+  return execCommand('git rev-parse HEAD', { cwd });
+}
+
+/**
+ * 获取目标分支相对于当前分支的已提交变更（含二进制文件）
+ * 使用三点 diff（HEAD...branchName）获取自分叉点以来的变更
+ * @param {string} branchName - 目标分支名
+ * @param {string} [cwd] - 工作目录（应在主 worktree 中执行）
+ * @returns {Buffer} diff 原始输出
+ */
+export function gitDiffBinaryAgainstBranch(branchName: string, cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync(`git diff HEAD...${branchName} --binary`, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 将 patch 内容通过 stdin 应用到工作目录（不带 --cached）
+ * @param {Buffer} patchContent - patch 内容
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitApplyFromStdin(patchContent: Buffer, cwd?: string): void {
+  execCommandWithInput('git', ['apply'], { input: patchContent, cwd });
+}
+
+/**
+ * git reset --soft HEAD~<count>，撤销 commit 但保留变更在暂存区
+ * @param {number} count - 撤销的 commit 数量
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitResetSoft(count: number = 1, cwd?: string): void {
+  execCommand(`git reset --soft HEAD~${count}`, { cwd });
+}

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { execCommand, spawnProcess, killAllChildProcesses } from './shell.js';
+export { execCommand, spawnProcess, killAllChildProcesses, execCommandWithInput } from './shell.js';
 export {
   getGitCommonDir,
   getGitTopLevel,
@@ -20,6 +20,7 @@ export {
   gitStashPush,
   gitStashApply,
   gitStashPop,
+  gitStashDrop,
   gitStashList,
   gitRestoreStaged,
   gitWorktreeList,
@@ -27,6 +28,13 @@ export {
   hasLocalCommits,
   getCommitCountAhead,
   getDiffStat,
+  gitDiffCachedBinary,
+  gitApplyCachedFromStdin,
+  getCurrentBranch,
+  getHeadCommitHash,
+  gitDiffBinaryAgainstBranch,
+  gitApplyFromStdin,
+  gitResetSoft,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -36,3 +44,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';

package/src/utils/shell.ts

@@ -1,4 +1,4 @@
-import { execSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
+import { execSync, execFileSync, spawn, type ChildProcess, type StdioOptions } from 'node:child_process';
 import { logger } from '../logger/index.js';
 
 /**
@@ -51,3 +51,24 @@ export function killAllChildProcesses(children: ChildProcess[]): void {
     }
   }
 }
+
+/**
+ * 同步执行命令，通过 stdin 传入数据
+ * @param {string} command - 要执行的命令
+ * @param {string[]} args - 命令参数
+ * @param {object} options - 配置
+ * @param {Buffer} options.input - 通过 stdin 传入的数据（Buffer 格式，保留二进制完整性）
+ * @param {string} [options.cwd] - 工作目录
+ * @returns {string} 命令的标准输出（已 trim）
+ * @throws {Error} 命令执行失败时抛出
+ */
+export function execCommandWithInput(command: string, args: string[], options: { input: Buffer; cwd?: string }): string {
+  logger.debug(`执行命令(stdin): ${command} ${args.join(' ')}${options.cwd ? ` (cwd: ${options.cwd})` : ''}`);
+  const result = execFileSync(command, args, {
+    cwd: options.cwd,
+    input: options.input,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.trim();
+}

package/src/utils/validate-snapshot.ts

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from 'node:fs';
+import { VALIDATE_SNAPSHOTS_DIR } from '../constants/index.js';
+import { ensureDir } from './fs.js';
+import { logger } from '../logger/index.js';
+
+/**
+ * 获取指定项目和分支的 validate 快照文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} patch 文件的绝对路径
+ */
+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`);
+}
+
+/**
+ * 判断指定项目和分支是否存在 validate 快照
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {boolean} 快照是否存在
+ */
+export function hasSnapshot(projectName: string, branchName: string): boolean {
+  return existsSync(getSnapshotPath(projectName, branchName));
+}
+
+/**
+ * 读取指定项目和分支的 validate 快照内容
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {Buffer} patch 文件内容（Buffer 格式，保留二进制完整性）
+ */
+export function readSnapshot(projectName: string, branchName: string): Buffer {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  logger.debug(`读取 validate 快照: ${snapshotPath}`);
+  return readFileSync(snapshotPath);
+}
+
+/**
+ * 写入 validate 快照内容（自动创建目录）
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @param {Buffer} patch - patch 内容（Buffer 格式）
+ * @param {string} [headHash] - 主分支 HEAD commit hash（用于增量 validate 一致性校验）
+ */
+export function writeSnapshot(projectName: string, branchName: string, patch: Buffer, headHash?: 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');
+  }
+  logger.info(`已保存 validate 快照: ${snapshotPath}`);
+}
+
+/**
+ * 删除指定项目和分支的 validate 快照
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+export function removeSnapshot(projectName: string, branchName: string): void {
+  const snapshotPath = getSnapshotPath(projectName, branchName);
+  if (existsSync(snapshotPath)) {
+    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();
+}
+
+/**
+ * 删除指定项目的所有 validate 快照
+ * @param {string} projectName - 项目名
+ */
+export function removeProjectSnapshots(projectName: string): void {
+  const projectDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
+  if (!existsSync(projectDir)) {
+    return;
+  }
+
+  const files = readdirSync(projectDir);
+  for (const file of files) {
+    unlinkSync(join(projectDir, file));
+  }
+
+  // 尝试删除空目录
+  try {
+    rmdirSync(projectDir);
+  } catch {
+    // 目录非空或其他原因，忽略
+  }
+
+  logger.info(`已删除项目 ${projectName} 的所有 validate 快照`);
+}