clawt 3.1.2 → 3.2.0

package/src/commands/validate.ts

@@ -1,6 +1,5 @@
 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 { ValidateOptions } from '../types/index.js';
 import { executeSyncForBranch } from './sync.js';
@@ -11,21 +10,10 @@ import {
   getProjectWorktrees,
   getConfigValue,
   isWorkingDirClean,
-  gitAddAll,
-  gitCommit,
-  gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
-  gitDiffBinaryAgainstBranch,
-  gitApplyFromStdin,
-  gitApplyCachedFromStdin,
-  gitResetSoft,
-  gitWriteTree,
   gitReadTree,
   getHeadCommitHash,
-  getCommitTreeHash,
-  gitDiffTree,
-  gitApplyCachedCheck,
   hasLocalCommits,
   hasSnapshot,
   readSnapshot,
@@ -34,23 +22,21 @@ import {
   confirmDestructiveAction,
   confirmAction,
   printSuccess,
-  printError,
   printWarning,
   printInfo,
-  printSeparator,
   resolveTargetWorktree,
-  runCommandInherited,
-  parseParallelCommands,
-  runParallelCommands,
   requireProjectConfig,
-  getValidateBranchName,
-  gitCheckout,
   ensureOnMainWorkBranch,
-  checkBranchExists,
-  getCurrentBranch,
   handleDirtyWorkingDir,
+  getValidateRunCommand,
+  executeRunCommand,
+  migrateChangesViaPatch,
+  computeCurrentTreeHash,
+  saveCurrentSnapshotTree,
+  loadOldSnapshotToStage,
+  switchToValidateBranch,
 } from '../utils/index.js';
-import type { WorktreeResolveMessages, ParallelCommandResult } from '../utils/index.js';
+import type { WorktreeResolveMessages } from '../utils/index.js';
 
 /** validate 命令的分支解析消息配置 */
 const VALIDATE_RESOLVE_MESSAGES: WorktreeResolveMessages = {
@@ -85,59 +71,6 @@ async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void>
   await handleDirtyWorkingDir(mainWorktreePath);
 }
 
-/**
- * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
- * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
- * @param {string} targetWorktreePath - 目标 worktree 路径
- * @param {string} mainWorktreePath - 主 worktree 路径
- * @param {string} branchName - 分支名
- * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
- * @returns {{ success: boolean }} patch 迁移结果
- */
-function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: string, branchName: string, hasUncommitted: boolean): { success: boolean } {
-  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));
-        return { success: false };
-      }
-    }
-
-    return { success: true };
-  } finally {
-    // 确保临时 commit 一定会被撤销，恢复目标 worktree 原状
-    // 每个操作独立 try-catch，避免前一个失败导致后续操作不执行
-    if (didTempCommit) {
-      try {
-        gitResetSoft(1, targetWorktreePath);
-      } catch (error) {
-        logger.error(`撤销临时 commit 失败: ${error}`);
-      }
-      try {
-        gitRestoreStaged(targetWorktreePath);
-      } catch (error) {
-        logger.error(`恢复暂存区失败: ${error}`);
-      }
-    }
-  }
-}
-
 /**
  * patch apply 失败后的交互处理：询问用户是否自动执行 sync
  * @param {string} targetWorktreePath - 目标 worktree 路径
@@ -160,24 +93,6 @@ async function handlePatchApplyFailure(targetWorktreePath: string, branchName: s
   // sync 冲突提示已在 executeSyncForBranch 内部输出（SYNC_CONFLICT），此处无需重复提示
 }
 
-/**
- * 保存当前主 worktree 工作目录变更为 git tree 对象快照
- * 操作序列：git add . → git write-tree → git restore --staged .
- * 同时保存当前 HEAD commit hash，用于增量 validate 时对齐基准
- * @param {string} mainWorktreePath - 主 worktree 路径
- * @param {string} projectName - 项目名
- * @param {string} branchName - 分支名
- * @returns {string} 生成的 tree hash
- */
-function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string, branchName: string): string {
-  gitAddAll(mainWorktreePath);
-  const treeHash = gitWriteTree(mainWorktreePath);
-  gitRestoreStaged(mainWorktreePath);
-  const headCommitHash = getHeadCommitHash(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
-  return treeHash;
-}
-
 /**
  * 处理 --clean 选项：清理 validate 状态
  * @param {ValidateOptions} options - 命令选项
@@ -234,11 +149,7 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
  */
 async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
   // 切换主 worktree 到验证分支
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  gitCheckout(validateBranchName, mainWorktreePath);
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
 
   // 通过 patch 迁移目标分支全量变更到主 worktree
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
@@ -266,8 +177,8 @@ async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath:
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
 async function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): Promise<void> {
-  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
-  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
+  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash + 暂存区 tree hash）
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash, stagedTreeHash: oldStagedTreeHash } = readSnapshot(projectName, branchName);
 
   // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
   // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
@@ -277,14 +188,7 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
   }
 
   // 步骤 3：切换到验证分支（如果已在该分支上则跳过）
-  const validateBranchName = getValidateBranchName(branchName);
-  if (!checkBranchExists(validateBranchName)) {
-    throw new ClawtError(MESSAGES.VALIDATE_BRANCH_NOT_FOUND(validateBranchName, branchName));
-  }
-  const currentBranch = getCurrentBranch(mainWorktreePath);
-  if (currentBranch !== validateBranchName) {
-    gitCheckout(validateBranchName, mainWorktreePath);
-  }
+  const validateBranchName = switchToValidateBranch(branchName, mainWorktreePath);
 
   // 步骤 4：通过 patch 从目标分支获取最新全量变更
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
@@ -296,140 +200,57 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
     return;
   }
 
-  // 步骤 5：保存最新快照为 git tree 对象（同时记录当前 HEAD）
-  saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
+  // 步骤 5：计算当前变更的 tree hash，检测是否有新变更
+  const newTreeHash = computeCurrentTreeHash(mainWorktreePath);
+  const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
 
-  // 步骤 6：将旧变更状态载入暂存区
-  try {
-    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
-
-    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
-      // HEAD 发生了变化：
-      // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
-      // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
-      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
-      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
-
-      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
-        // 无冲突：apply --cached 到当前 HEAD 暂存区
-        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
-      } else if (oldChangePatch.length > 0) {
-        // 有冲突：降级为全量模式（暂存区保持为空）
-        logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
-        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-        printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
-        return;
+  // 检测目标 worktree 自上次 validate 以来是否有新变更
+  const hasNewChanges = newTreeHash !== oldTreeHash
+    || (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash);
+
+  if (!hasNewChanges) {
+    // 无新变更：不更新快照，恢复到上次 validate 结束时的完整状态
+    if (oldStagedTreeHash) {
+      try {
+        gitReadTree(oldStagedTreeHash, mainWorktreePath);
+      } catch (error) {
+        logger.warn(`恢复暂存区失败: ${error}`);
       }
-      // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
-    } else {
-      // HEAD 未变化（或旧版快照无 HEAD 信息）：直接 read-tree 旧快照
-      gitReadTree(oldTreeHash, mainWorktreePath);
     }
-  } catch (error) {
-    // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
-    logger.warn(`增量 read-tree 失败: ${error}`);
-    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-    // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+    printInfo(MESSAGES.INCREMENTAL_VALIDATE_NO_CHANGES(branchName));
     printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
 
-  // 结果：暂存区=上次快照，工作目录=最新全量变更
-  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
-}
-
-/**
- * 执行单个命令（同步方式，保持原有行为不变）
- * @param {string} command - 要执行的命令字符串
- * @param {string} mainWorktreePath - 主 worktree 路径
- */
-function executeSingleCommand(command: string, mainWorktreePath: string): void {
-  printInfo(MESSAGES.VALIDATE_RUN_START(command));
-  printSeparator();
-
-  const result = runCommandInherited(command, { cwd: mainWorktreePath });
-
-  printSeparator();
+  // 有新变更：执行暂存区载入并记录 stagedTreeHash
 
-  if (result.error) {
-    // 进程启动失败（如命令不存在）
-    printError(MESSAGES.VALIDATE_RUN_ERROR(command, result.error.message));
+  // 步骤 6：将旧变更状态载入暂存区
+  const stageResult = loadOldSnapshotToStage(oldTreeHash, oldHeadCommitHash, currentHeadCommitHash, mainWorktreePath);
+  if (!stageResult.success) {
+    printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+    // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
+    writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, '');
+    printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
 
-  const exitCode = result.status ?? 1;
-  if (exitCode === 0) {
-    printSuccess(MESSAGES.VALIDATE_RUN_SUCCESS(command));
-  } else {
-    printError(MESSAGES.VALIDATE_RUN_FAILED(command, exitCode));
-  }
-}
-
-/**
- * 汇总输出并行命令的执行结果
- * @param {ParallelCommandResult[]} results - 各命令的执行结果数组
- */
-function reportParallelResults(results: ParallelCommandResult[]): void {
-  printSeparator();
-
-  const successCount = results.filter((r) => r.exitCode === 0 && !r.error).length;
-  const failedCount = results.length - successCount;
-
-  for (const result of results) {
-    if (result.error) {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_ERROR(result.command, result.error));
-    } else if (result.exitCode === 0) {
-      printSuccess(MESSAGES.VALIDATE_PARALLEL_CMD_SUCCESS(result.command));
-    } else {
-      printError(MESSAGES.VALIDATE_PARALLEL_CMD_FAILED(result.command, result.exitCode));
-    }
-  }
-
-  if (failedCount === 0) {
-    printSuccess(MESSAGES.VALIDATE_PARALLEL_RUN_ALL_SUCCESS(results.length));
-  } else {
-    printError(MESSAGES.VALIDATE_PARALLEL_RUN_SUMMARY(successCount, failedCount));
-  }
-}
-
-/**
- * 并行执行多个命令并汇总结果
- * @param {string[]} commands - 要并行执行的命令数组
- * @param {string} mainWorktreePath - 主 worktree 路径
- */
-async function executeParallelCommands(commands: string[], mainWorktreePath: string): Promise<void> {
-  printInfo(MESSAGES.VALIDATE_PARALLEL_RUN_START(commands.length));
-
-  for (let i = 0; i < commands.length; i++) {
-    printInfo(MESSAGES.VALIDATE_PARALLEL_CMD_START(i + 1, commands.length, commands[i]));
-  }
-
-  printSeparator();
+  // 步骤 7：写入新快照（包含 stagedTreeHash 供下次无变更时恢复用）
+  writeSnapshot(projectName, branchName, newTreeHash, currentHeadCommitHash, stageResult.stagedTreeHash);
 
-  const results = await runParallelCommands(commands, { cwd: mainWorktreePath });
-
-  reportParallelResults(results);
+  // 结果：暂存区=上次快照，工作目录=最新全量变更
+  printSuccess(MESSAGES.INCREMENTAL_VALIDATE_SUCCESS(branchName));
 }
 
 /**
- * 在主 worktree 中执行用户指定的命令
- * 根据命令字符串中的 & 分隔符决定是单命令执行还是并行执行
- * 命令执行失败不影响 validate 本身的结果，仅输出提示
- * @param {string} command - 要执行的命令字符串
- * @param {string} mainWorktreePath - 主 worktree 路径
+ * 解析最终要执行的 run 命令：优先使用 -r 参数，否则从项目配置读取
+ * @param {string} [optionRun] - 用户通过 -r 传入的命令
+ * @returns {string | undefined} 最终要执行的命令，无配置时返回 undefined
  */
-async function executeRunCommand(command: string, mainWorktreePath: string): Promise<void> {
-  printInfo('');
-
-  const commands = parseParallelCommands(command);
-
-  if (commands.length <= 1) {
-    // 单命令（包括含 && 的串行命令），走原有同步路径
-    executeSingleCommand(commands[0] || command, mainWorktreePath);
-  } else {
-    // 多命令，并行执行
-    await executeParallelCommands(commands, mainWorktreePath);
+function resolveRunCommand(optionRun?: string): string | undefined {
+  if (optionRun) {
+    return optionRun;
   }
+  return getValidateRunCommand();
 }
 
 /**
@@ -484,8 +305,9 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     await handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted);
   }
 
-  // validate 成功后执行用户指定的命令
-  if (options.run) {
-    await executeRunCommand(options.run, mainWorktreePath);
+  // validate 成功后执行用户指定的命令（优先 -r 参数，否则从项目配置读取）
+  const runCommand = resolveRunCommand(options.run);
+  if (runCommand) {
+    await executeRunCommand(runCommand, mainWorktreePath);
   }
 }

package/src/constants/index.ts

@@ -6,6 +6,7 @@ export { UPDATE_MESSAGES, UPDATE_COMMANDS } from './messages/update.js';
 export { EXIT_CODES } from './exitCodes.js';
 export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS, VALID_TERMINAL_APPS, ITERM2_APP_PATH } from './terminal.js';
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, CONFIG_DEFINITIONS, APPEND_SYSTEM_PROMPT } from './config.js';
+export { PROJECT_CONFIG_DEFINITIONS, PROJECT_DEFAULT_CONFIG, PROJECT_CONFIG_DESCRIPTIONS } from './project-config.js';
 export { AUTO_SAVE_COMMIT_MESSAGE } from './git.js';
 export { DEBUG_LOG_PREFIX, DEBUG_TIMESTAMP_FORMAT } from './logger.js';
 export { UPDATE_CHECK_INTERVAL_MS, NPM_REGISTRY_URL, NPM_REGISTRY_TIMEOUT_MS, PACKAGE_NAME } from './update.js';

package/src/constants/messages/init.ts

@@ -15,4 +15,8 @@ export const INIT_MESSAGES = {
   PROJECT_NOT_INITIALIZED: '项目尚未初始化，请先执行 clawt init 设置主工作分支',
   /** 项目配置缺少 clawtMainWorkBranch 字段 */
   PROJECT_CONFIG_MISSING_BRANCH: '项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支',
+  /** init show 交互式面板选择配置项提示 */
+  INIT_SELECT_PROMPT: '选择要修改的项目配置项',
+  /** init show 交互式面板配置项修改成功 */
+  INIT_SET_SUCCESS: (key: string, value: string) => `✓ 项目配置 ${key} 已设置为 ${value}`,
 } as const;

package/src/constants/messages/validate.ts

@@ -8,6 +8,9 @@ export const VALIDATE_MESSAGES = {
     `✓ 已将分支 ${branch} 的最新变更应用到主 worktree（增量模式）\n  暂存区 = 上次快照，工作目录 = 最新变更`,
   /** 增量 validate 降级为全量模式提示 */
   INCREMENTAL_VALIDATE_FALLBACK: '增量对比失败，已降级为全量模式',
+  /** 增量 validate 检测到目标 worktree 无新变更 */
+  INCREMENTAL_VALIDATE_NO_CHANGES: (branch: string) =>
+    `分支 ${branch} 自上次 validate 以来没有新的变更，已恢复到上次验证状态`,
   /** validate 状态已清理 */
   VALIDATE_CLEANED: (branch: string) => `✓ 分支 ${branch} 的 validate 状态已清理`,
   /** validate patch apply 失败，提示用户同步主分支 */

package/src/constants/project-config.ts

@@ -0,0 +1,46 @@
+import type { ProjectConfig, ProjectConfigDefinitions } from '../types/index.js';
+
+/**
+ * 项目级配置项完整定义（单一数据源）
+ * 新增项目配置项时只需在此处维护，PROJECT_DEFAULT_CONFIG 和 PROJECT_CONFIG_DESCRIPTIONS 会自动同步
+ */
+export const PROJECT_CONFIG_DEFINITIONS: ProjectConfigDefinitions = {
+  clawtMainWorkBranch: {
+    defaultValue: '',
+    description: '主 worktree 的工作分支名',
+  },
+  validateRunCommand: {
+    defaultValue: undefined as unknown as string | undefined,
+    description: 'validate 成功后自动执行的命令（-r 的默认值）',
+  },
+};
+
+/**
+ * 从 PROJECT_CONFIG_DEFINITIONS 派生默认配置
+ * @param {ProjectConfigDefinitions} definitions - 项目配置项完整定义
+ * @returns {Required<ProjectConfig>} 默认项目配置对象
+ */
+function deriveDefaultConfig(definitions: ProjectConfigDefinitions): Required<ProjectConfig> {
+  const entries = Object.entries(definitions).map(
+    ([key, def]) => [key, def.defaultValue],
+  );
+  return Object.fromEntries(entries) as Required<ProjectConfig>;
+}
+
+/**
+ * 从 PROJECT_CONFIG_DEFINITIONS 派生配置项描述映射
+ * @param {ProjectConfigDefinitions} definitions - 项目配置项完整定义
+ * @returns {Record<keyof Required<ProjectConfig>, string>} 配置项描述映射
+ */
+function deriveConfigDescriptions(definitions: ProjectConfigDefinitions): Record<keyof Required<ProjectConfig>, string> {
+  const entries = Object.entries(definitions).map(
+    ([key, def]) => [key, def.description],
+  );
+  return Object.fromEntries(entries) as Record<keyof Required<ProjectConfig>, string>;
+}
+
+/** 项目默认配置 */
+export const PROJECT_DEFAULT_CONFIG: Required<ProjectConfig> = deriveDefaultConfig(PROJECT_CONFIG_DEFINITIONS);
+
+/** 项目配置项描述映射 */
+export const PROJECT_CONFIG_DESCRIPTIONS: Record<keyof Required<ProjectConfig>, string> = deriveConfigDescriptions(PROJECT_CONFIG_DEFINITIONS);

package/src/types/index.ts

@@ -6,4 +6,4 @@ export type { TaskResult, TaskSummary } from './taskResult.js';
 export type { WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, SnapshotSummary, StatusResult } from './status.js';
 export type { TaskFileEntry, ParseTaskFileOptions } from './taskFile.js';
 export type { ProjectOverview, ProjectWorktreeDetail, ProjectDetailResult, ProjectsOverviewResult } from './project.js';
-export type { ProjectConfig } from './projectConfig.js';
+export type { ProjectConfig, ProjectConfigItemDefinition, ProjectConfigDefinitions } from './projectConfig.js';

package/src/types/projectConfig.ts

@@ -2,4 +2,21 @@
 export interface ProjectConfig {
   /** 主 worktree 的工作分支名 */
   clawtMainWorkBranch: string;
+  /** validate 成功后自动执行的命令（-r 的默认值） */
+  validateRunCommand?: string;
 }
+
+/** 单个项目配置项的完整定义（默认值 + 描述） */
+export interface ProjectConfigItemDefinition<T> {
+  /** 默认值 */
+  defaultValue: T;
+  /** 配置项描述，用于交互式面板展示 */
+  description: string;
+  /** 可选：允许的枚举值列表，仅对 string 类型有效 */
+  allowedValues?: T extends string ? readonly string[] : never;
+}
+
+/** 所有项目配置项的完整定义映射 */
+export type ProjectConfigDefinitions = {
+  [K in keyof Required<ProjectConfig>]: ProjectConfigItemDefinition<ProjectConfig[K]>;
+};

package/src/utils/config-strategy.ts

@@ -73,14 +73,16 @@ export function parseConfigValue(
  * - string + 有 allowedValues → Select(枚举列表)
  * - string + 无 allowedValues → Input(自由输入)
  *
- * @param {keyof ClawtConfig} key - 配置项名称
- * @param {ClawtConfig[keyof ClawtConfig]} currentValue - 当前值
- * @returns {Promise<ClawtConfig[keyof ClawtConfig]>} 用户输入/选择的新值
+ * @param {string} key - 配置项名称
+ * @param {unknown} currentValue - 当前值
+ * @param {readonly string[]} [allowedValues] - 可选的枚举值列表
+ * @returns {Promise<unknown>} 用户输入/选择的新值
  */
 export async function promptConfigValue(
-  key: keyof ClawtConfig,
-  currentValue: ClawtConfig[keyof ClawtConfig],
-): Promise<ClawtConfig[keyof ClawtConfig]> {
+  key: string,
+  currentValue: unknown,
+  allowedValues?: readonly string[],
+): Promise<unknown> {
   const expectedType = typeof currentValue;
 
   // 布尔类型策略
@@ -94,9 +96,8 @@ export async function promptConfigValue(
   }
 
   // 字符串类型：根据 allowedValues 自动选择提示策略
-  const definition = CONFIG_DEFINITIONS[key];
-  if (definition.allowedValues) {
-    return promptEnumValue(key, currentValue as string, definition.allowedValues);
+  if (allowedValues) {
+    return promptEnumValue(key, currentValue as string, allowedValues);
   }
 
   return promptStringValue(key, currentValue as string);
@@ -104,23 +105,70 @@ export async function promptConfigValue(
 
 /**
  * 格式化配置值的显示样式
- * @param {ClawtConfig[keyof ClawtConfig]} value - 配置值
+ * @param {unknown} value - 配置值
  * @returns {string} 格式化后的字符串
  */
-export function formatConfigValue(value: ClawtConfig[keyof ClawtConfig]): string {
+export function formatConfigValue(value: unknown): string {
+  if (value === undefined || value === null) {
+    return chalk.dim('(未设置)');
+  }
   if (typeof value === 'boolean') {
     return value ? chalk.green('true') : chalk.yellow('false');
   }
   return chalk.cyan(String(value));
 }
 
+/**
+ * 通用交互式配置编辑器
+ * @param {T} config - 当前配置对象
+ * @param {Record<string, { description: string; allowedValues?: readonly string[] }>} definitions - 配置项定义（含 description、allowedValues）
+ * @param {object} [options] - 可选配置
+ * @param {string} [options.selectPrompt] - 选择配置项的提示语
+ * @param {Record<string, string>} [options.disabledKeys] - 不可编辑的键及其禁用提示
+ * @returns {Promise<{ key: string; newValue: unknown }>} 修改后的 key 和 newValue
+ */
+export async function interactiveConfigEditor<T extends object>(
+  config: T,
+  definitions: Record<string, { description: string; allowedValues?: readonly string[] }>,
+  options?: { selectPrompt?: string; disabledKeys?: Record<string, string> },
+): Promise<{ key: keyof T; newValue: unknown }> {
+  const keys = Object.keys(definitions);
+  const disabledKeys = options?.disabledKeys ?? {};
+  const configRecord = config as Record<string, unknown>;
+
+  // 构建选择列表，显示配置项名称、当前值和描述
+  const choices = keys.map((k) => {
+    const isDisabled = k in disabledKeys;
+    const value = configRecord[k];
+    const isObject = typeof value === 'object' && value !== null;
+    return {
+      name: k,
+      message: `${k}: ${isObject || isDisabled ? chalk.dim(isObject ? JSON.stringify(value) : String(value ?? '')) : formatConfigValue(value)}  ${chalk.dim(`— ${definitions[k].description}`)}`,
+      ...(isDisabled && { disabled: disabledKeys[k] }),
+    };
+  });
+
+  // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
+  const selectedKey: string = await new Enquirer.Select({
+    message: options?.selectPrompt ?? MESSAGES.CONFIG_SELECT_PROMPT,
+    choices,
+  }).run();
+
+  // 根据类型和 allowedValues 自动选择提示策略
+  const currentValue = configRecord[selectedKey];
+  const definition = definitions[selectedKey];
+  const newValue = await promptConfigValue(selectedKey, currentValue, definition.allowedValues);
+
+  return { key: selectedKey as keyof T, newValue };
+}
+
 /**
  * 交互式布尔值选择（内部辅助函数）
- * @param {keyof ClawtConfig} key - 配置项名称
+ * @param {string} key - 配置项名称
  * @param {boolean} currentValue - 当前值
  * @returns {Promise<boolean>} 用户选择的布尔值
  */
-async function promptBooleanValue(key: keyof ClawtConfig, currentValue: boolean): Promise<boolean> {
+async function promptBooleanValue(key: string, currentValue: boolean): Promise<boolean> {
   const choices = [
     { name: 'true', message: 'true' },
     { name: 'false', message: 'false' },
@@ -138,11 +186,11 @@ async function promptBooleanValue(key: keyof ClawtConfig, currentValue: boolean)
 
 /**
  * 交互式数字输入（内部辅助函数）
- * @param {keyof ClawtConfig} key - 配置项名称
+ * @param {string} key - 配置项名称
  * @param {number} currentValue - 当前值
  * @returns {Promise<number>} 用户输入的数字值
  */
-async function promptNumberValue(key: keyof ClawtConfig, currentValue: number): Promise<number> {
+async function promptNumberValue(key: string, currentValue: number): Promise<number> {
   // @ts-expect-error enquirer 类型声明未导出 Input 类，但运行时存在
   const input: string = await new Enquirer.Input({
     message: MESSAGES.CONFIG_INPUT_PROMPT(key),
@@ -158,13 +206,13 @@ async function promptNumberValue(key: keyof ClawtConfig, currentValue: number):
 
 /**
  * 交互式枚举值选择（内部辅助函数，用于有 allowedValues 的 string 配置项）
- * @param {keyof ClawtConfig} key - 配置项名称
+ * @param {string} key - 配置项名称
  * @param {string} currentValue - 当前值
  * @param {readonly string[]} allowedValues - 允许的枚举值列表
  * @returns {Promise<string>} 用户选择的枚举值
  */
 async function promptEnumValue(
-  key: keyof ClawtConfig,
+  key: string,
   currentValue: string,
   allowedValues: readonly string[],
 ): Promise<string> {
@@ -183,14 +231,14 @@ async function promptEnumValue(
 
 /**
  * 交互式字符串自由输入（内部辅助函数，用于无 allowedValues 的 string 配置项）
- * @param {keyof ClawtConfig} key - 配置项名称
+ * @param {string} key - 配置项名称
  * @param {string} currentValue - 当前值
  * @returns {Promise<string>} 用户输入的字符串值
  */
-async function promptStringValue(key: keyof ClawtConfig, currentValue: string): Promise<string> {
+async function promptStringValue(key: string, currentValue: string): Promise<string> {
   // @ts-expect-error enquirer 类型声明未导出 Input 类，但运行时存在
   return await new Enquirer.Input({
     message: MESSAGES.CONFIG_INPUT_PROMPT(key),
-    initial: currentValue,
+    initial: currentValue || '',
   }).run();
 }

package/src/utils/index.ts

@@ -68,11 +68,13 @@ export type { ParsedActivity, StreamEvent, LineBuffer } from './stream-parser.js
 export { detectTerminalApp, openCommandInNewTerminalTab } from './terminal.js';
 export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
-export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue } from './config-strategy.js';
+export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue, interactiveConfigEditor } from './config-strategy.js';
 export { checkForUpdates } from './update-checker.js';
-export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch } from './project-config.js';
+export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, getValidateRunCommand } from './project-config.js';
 export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebuildValidateBranch, ensureOnMainWorkBranch, handleDirtyWorkingDir } from './validate-branch.js';
 export { safeStringify } from './json.js';
+export { executeRunCommand } from './validate-runner.js';
+export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch } from './validate-core.js';
 export { InteractivePanel } from './interactive-panel.js';
 export { buildPanelFrame, buildGroupedWorktreeLines, buildDisplayOrder, renderDateSeparator, renderWorktreeBlock, renderSnapshotSummary, renderFooter, calculateVisibleRows } from './interactive-panel-render.js';
 export type { PanelLine } from './interactive-panel-render.js';

package/src/utils/project-config.ts

@@ -75,3 +75,12 @@ export function getMainWorkBranch(): string {
   const config = requireProjectConfig();
   return config.clawtMainWorkBranch;
 }
+
+/**
+ * 从项目配置中获取 validate 成功后自动执行的命令
+ * @returns {string | undefined} 配置的命令字符串，未配置时返回 undefined
+ */
+export function getValidateRunCommand(): string | undefined {
+  const config = loadProjectConfig();
+  return config?.validateRunCommand || undefined;
+}