clawt 2.20.0 → 3.1.0

package/src/commands/run.ts

@@ -19,21 +19,22 @@ import {
   parseTasksFromOptions,
   executeBatchTasks,
   printDryRunPreview,
+  ensureOnMainWorkBranch,
 } from '../utils/index.js';
 
 /**
- * 注册 run 命令：批量创建 worktree 并执行 Claude Code 任务
+ * 注册 run 命令：批量创建 worktree + 启动 Claude Code 执行任务（支持任务文件）
  * @param {Command} program - Commander 实例
  */
 export function registerRunCommand(program: Command): void {
   program
     .command('run')
-    .description('批量创建 worktree 并启动 Claude Code 执行任务')
+    .description('批量创建 worktree + 启动 Claude Code 执行任务（支持任务文件）')
     .option('-b, --branch <branchName>', '分支名')
     .option('--tasks <task...>', '任务列表（可多次指定），不传则在 worktree 中打开 Claude Code 交互式界面')
     .option('-c, --concurrency <n>', '最大并发数，0 表示不限制')
     .option('-f, --file <path>', '从任务文件读取任务列表（与 --tasks 互斥）')
-    .option('-d, --dry-run', '预览模式，仅展示任务计划不实际执行')
+    .option('--dry-run', '预览模式，仅展示任务计划不实际执行')
     .action(async (options: RunOptions) => {
       await handleRun(options);
     });
@@ -120,6 +121,11 @@ function handleDryRunFromFile(options: RunOptions): void {
 async function handleRun(options: RunOptions): Promise<void> {
   validateMainWorktree();
 
+  // dry-run 模式跳过项目配置前置校验
+  if (!options.dryRun) {
+    await ensureOnMainWorkBranch();
+  }
+
   // 互斥校验：--file 和 --tasks 不能同时使用
   if (options.file && options.tasks) {
     throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);

package/src/commands/status.ts

@@ -21,6 +21,7 @@ import {
   printInfo,
   printDoubleSeparator,
   printSeparator,
+  InteractivePanel,
 } from '../utils/index.js';
 
 /**
@@ -30,10 +31,11 @@ import {
 export function registerStatusCommand(program: Command): void {
   program
     .command('status')
-    .description('显示项目全局状态总览')
+    .description('显示项目全局状态总览（支持 --json 格式输出）')
     .option('--json', '以 JSON 格式输出')
-    .action((options: StatusOptions) => {
-      handleStatus(options);
+    .option('-i, --interactive', '交互式面板模式')
+    .action(async (options: StatusOptions) => {
+      await handleStatus(options);
     });
 }
 
@@ -41,9 +43,16 @@ export function registerStatusCommand(program: Command): void {
  * 执行 status 命令的核心逻辑
  * @param {StatusOptions} options - 命令选项
  */
-function handleStatus(options: StatusOptions): void {
+async function handleStatus(options: StatusOptions): Promise<void> {
   validateMainWorktree();
 
+  // 交互式面板模式
+  if (options.interactive) {
+    const panel = new InteractivePanel(collectStatus);
+    await panel.start();
+    return;
+  }
+
   const statusResult = collectStatus();
 
   logger.info(`status 命令执行，项目: ${statusResult.main.projectName}，共 ${statusResult.totalWorktrees} 个 worktree`);
@@ -60,7 +69,7 @@ function handleStatus(options: StatusOptions): void {
  * 收集项目全局状态信息
  * @returns {StatusResult} 完整的状态数据
  */
-function collectStatus(): StatusResult {
+export function collectStatus(): StatusResult {
   const projectName = getProjectName();
   const currentBranch = getCurrentBranch();
   const isClean = isWorkingDirClean();

package/src/commands/sync.ts

@@ -13,18 +13,22 @@ import {
   gitCommit,
   gitMerge,
   hasMergeConflict,
-  getCurrentBranch,
   hasSnapshot,
   removeSnapshot,
   printSuccess,
   printInfo,
   printWarning,
   resolveTargetWorktree,
+  requireProjectConfig,
+  getMainWorkBranch,
+  rebuildValidateBranch,
+  getValidateBranchName,
+  ensureOnMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
 /**
- * 注册 sync 命令：将主分支最新代码同步到目标 worktree
+ * 注册 sync 命令：将主分支最新代码同步到目标 worktree（含验证分支重建）
  * @param {Command} program - Commander 实例
  */
 export function registerSyncCommand(program: Command): void {
@@ -92,10 +96,10 @@ export interface SyncResult {
  * @param {string} branch - 分支名
  * @returns {SyncResult} sync 执行结果
  */
-export function executeSyncForBranch(targetWorktreePath: string, branch: string): SyncResult {
-  // 获取主分支名（不硬编码 main/master）
+export async function executeSyncForBranch(targetWorktreePath: string, branch: string): Promise<SyncResult> {
+  // 从项目配置获取主工作分支名
   const mainWorktreePath = getGitTopLevel();
-  const mainBranch = getCurrentBranch(mainWorktreePath);
+  const mainBranch = getMainWorkBranch();
 
   // 检查目标 worktree 是否有未提交变更，有则自动保存
   if (!isWorkingDirClean(targetWorktreePath)) {
@@ -119,6 +123,12 @@ export function executeSyncForBranch(targetWorktreePath: string, branch: string)
   }
 
   printSuccess(MESSAGES.SYNC_SUCCESS(branch, mainBranch));
+
+  // 合并成功后重建验证分支（基于最新的主分支 HEAD）
+  await rebuildValidateBranch(branch, mainWorktreePath);
+  const validateBranchName = getValidateBranchName(branch);
+  printInfo(MESSAGES.SYNC_VALIDATE_BRANCH_REBUILT(validateBranchName));
+
   return { success: true, hasConflict: false };
 }
 
@@ -129,6 +139,8 @@ export function executeSyncForBranch(targetWorktreePath: string, branch: string)
  */
 async function handleSync(options: SyncOptions): Promise<void> {
   validateMainWorktree();
+  requireProjectConfig();
+  await ensureOnMainWorkBranch();
 
   logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 
@@ -137,5 +149,5 @@ async function handleSync(options: SyncOptions): Promise<void> {
   const worktree = await resolveTargetWorktree(worktrees, SYNC_RESOLVE_MESSAGES, options.branch);
   const { path: targetWorktreePath, branch } = worktree;
 
-  executeSyncForBranch(targetWorktreePath, branch);
+  await executeSyncForBranch(targetWorktreePath, branch);
 }

package/src/commands/validate.ts

@@ -1,5 +1,4 @@
 import type { Command } from 'commander';
-import Enquirer from 'enquirer';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
@@ -14,7 +13,6 @@ import {
   isWorkingDirClean,
   gitAddAll,
   gitCommit,
-  gitStashPush,
   gitRestoreStaged,
   gitResetHard,
   gitCleanForce,
@@ -44,6 +42,13 @@ import {
   runCommandInherited,
   parseParallelCommands,
   runParallelCommands,
+  requireProjectConfig,
+  getValidateBranchName,
+  gitCheckout,
+  ensureOnMainWorkBranch,
+  checkBranchExists,
+  getCurrentBranch,
+  handleDirtyWorkingDir,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages, ParallelCommandResult } from '../utils/index.js';
 
@@ -56,13 +61,13 @@ const VALIDATE_RESOLVE_MESSAGES: WorktreeResolveMessages = {
 };
 
 /**
- * 注册 validate 命令：在主 worktree 验证其他分支的变更
+ * 注册 validate 命令：在主 worktree 验证其他分支的变更（通过验证分支）
  * @param {Command} program - Commander 实例
  */
 export function registerValidateCommand(program: Command): void {
   program
     .command('validate')
-    .description('在主 worktree 验证某个 worktree 分支的变更')
+    .description('在主 worktree 验证某个 worktree 分支的变更（通过验证分支）')
     .option('-b, --branch <branchName>', '要验证的分支名（支持模糊匹配，不传则列出所有分支）')
     .option('--clean', '清理 validate 状态（重置主 worktree 并删除快照）')
     .option('-r, --run <command>', 'validate 成功后在主 worktree 中执行的命令')
@@ -73,47 +78,11 @@ export function registerValidateCommand(program: Command): void {
 
 /**
  * 处理主 worktree 工作区有未提交更改的情况（首次 validate 时使用）
+ * 委托给通用的 handleDirtyWorkingDir 函数处理
  * @param {string} mainWorktreePath - 主 worktree 路径
  */
 async function handleDirtyMainWorktree(mainWorktreePath: string): Promise<void> {
-  printWarning('主 worktree 当前分支有未提交的更改，请选择处理方式：\n');
-
-  // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
-  const choice = await new Enquirer.Select({
-    message: '选择处理方式',
-    choices: [
-      {
-        name: 'reset',
-        message: 'reset (推荐) - 丢弃所有更改 (git reset --hard HEAD && git clean -fd)',
-      },
-      {
-        name: 'stash',
-        message: 'stash        - 暂存更改 (git add . && git stash)',
-      },
-      {
-        name: 'exit',
-        message: 'exit         - 退出，手动处理',
-      },
-    ],
-    initial: 0,
-  }).run();
-
-  if (choice === 'exit') {
-    throw new ClawtError('用户选择退出');
-  }
-
-  if (choice === 'reset') {
-    gitResetHard(mainWorktreePath);
-    gitCleanForce(mainWorktreePath);
-  } else if (choice === 'stash') {
-    gitAddAll(mainWorktreePath);
-    gitStashPush('clawt:auto-stash', mainWorktreePath);
-  }
-
-  // 再次检查是否干净
-  if (!isWorkingDirClean(mainWorktreePath)) {
-    throw new ClawtError('工作区仍然不干净，请手动处理');
-  }
+  await handleDirtyWorkingDir(mainWorktreePath);
 }
 
 /**
@@ -186,7 +155,7 @@ async function handlePatchApplyFailure(targetWorktreePath: string, branchName: s
 
   // 用户确认，执行 sync
   printInfo(MESSAGES.VALIDATE_AUTO_SYNC_START(branchName));
-  const syncResult = executeSyncForBranch(targetWorktreePath, branchName);
+  const syncResult = await executeSyncForBranch(targetWorktreePath, branchName);
 
   // sync 冲突提示已在 executeSyncForBranch 内部输出（SYNC_CONFLICT），此处无需重复提示
 }
@@ -215,6 +184,8 @@ function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string,
  */
 async function handleValidateClean(options: ValidateOptions): Promise<void> {
   validateMainWorktree();
+  // 显式前置校验：确保项目已初始化
+  requireProjectConfig();
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
@@ -244,6 +215,9 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
     gitCleanForce(mainWorktreePath);
   }
 
+  // 确保当前在主工作分支上
+  await ensureOnMainWorkBranch(mainWorktreePath);
+
   // 删除对应的快照文件
   removeSnapshot(projectName, branchName);
 
@@ -259,11 +233,19 @@ async function handleValidateClean(options: ValidateOptions): Promise<void> {
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
 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);
+
   // 通过 patch 迁移目标分支全量变更到主 worktree
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
   if (!result.success) {
-    // patch 失败，询问用户是否自动 sync
+    // patch 失败，确保在主工作分支上后询问用户是否自动 sync
+    await ensureOnMainWorkBranch(mainWorktreePath);
     await handlePatchApplyFailure(targetWorktreePath, branchName);
     return;
   }
@@ -272,7 +254,7 @@ async function handleFirstValidate(targetWorktreePath: string, mainWorktreePath:
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
 
   // 结果：暂存区=空，工作目录=全量变更
-  printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+  printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
 }
 
 /**
@@ -294,24 +276,35 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
     gitCleanForce(mainWorktreePath);
   }
 
-  // 步骤 3：通过 patch 从目标分支获取最新全量变更
+  // 步骤 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);
+  }
+
+  // 步骤 4：通过 patch 从目标分支获取最新全量变更
   const result = migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
   if (!result.success) {
-    // patch 失败，询问用户是否自动 sync
+    // patch 失败，确保在主工作分支上后询问用户是否自动 sync
+    await ensureOnMainWorkBranch(mainWorktreePath);
     await handlePatchApplyFailure(targetWorktreePath, branchName);
     return;
   }
 
-  // 步骤 4：保存最新快照为 git tree 对象（同时记录当前 HEAD）
+  // 步骤 5：保存最新快照为 git tree 对象（同时记录当前 HEAD）
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
 
-  // 步骤 5：将旧变更状态载入暂存区
+  // 步骤 6：将旧变更状态载入暂存区
   try {
     const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
 
     if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
-      // HEAD 发生了变化（如主分支合并了其他分支）：
+      // HEAD 发生了变化：
       // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
       // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
       const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
@@ -324,7 +317,7 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
         // 有冲突：降级为全量模式（暂存区保持为空）
         logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
         printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
-        printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+        printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
         return;
       }
       // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
@@ -337,7 +330,7 @@ async function handleIncrementalValidate(targetWorktreePath: string, mainWorktre
     logger.warn(`增量 read-tree 失败: ${error}`);
     printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
     // 降级后暂存区保持为空，工作目录为最新全量变更，与首次 validate 一致
-    printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+    printSuccess(MESSAGES.VALIDATE_SUCCESS_WITH_BRANCH(branchName, validateBranchName));
     return;
   }
 
@@ -451,6 +444,7 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
   }
 
   validateMainWorktree();
+  requireProjectConfig();
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();

package/src/constants/branch.ts

@@ -4,3 +4,6 @@
  * 以及连续的 ..（目录遍历）
  */
 export const INVALID_BRANCH_CHARS = /[\/\\.\s~:*?[\]^]+/g;
+
+/** 验证分支名前缀 */
+export const VALIDATE_BRANCH_PREFIX = 'clawt-validate-';

package/src/constants/config.ts

@@ -1,7 +1,7 @@
 import type { ClawtConfig, ConfigDefinitions } from '../types/index.js';
 import { VALID_TERMINAL_APPS } from './terminal.js';
 
-/** Claude Code 系统约束提示，禁止代码执行完成后构建项目验证 */
+/** Claude Code 系统约束提示 */
 export const APPEND_SYSTEM_PROMPT =
   'After the code execution is completed, it is prohibited to build the project for verification.';
 

package/src/constants/index.ts

@@ -1,5 +1,5 @@
-export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR, CLAUDE_PROJECTS_DIR, UPDATE_CHECK_PATH } from './paths.js';
-export { INVALID_BRANCH_CHARS } from './branch.js';
+export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR, CLAUDE_PROJECTS_DIR, UPDATE_CHECK_PATH, PROJECTS_CONFIG_DIR } from './paths.js';
+export { INVALID_BRANCH_CHARS, VALIDATE_BRANCH_PREFIX } from './branch.js';
 export { MESSAGES } from './messages/index.js';
 export { CONFIG_ALIAS_DISABLED_HINT } from './messages/index.js';
 export { UPDATE_MESSAGES, UPDATE_COMMANDS } from './messages/update.js';
@@ -30,3 +30,15 @@ export {
   CURSOR_HOME,
 } from './progress.js';
 export { SELECT_ALL_NAME, SELECT_ALL_LABEL, GROUP_SELECT_ALL_PREFIX, GROUP_SELECT_ALL_LABEL, GROUP_SEPARATOR_LABEL, UNKNOWN_DATE_GROUP, UNKNOWN_DATE_SEPARATOR_LABEL } from './prompt.js';
+export {
+  PANEL_REFRESH_INTERVAL_MS,
+  PANEL_COUNTDOWN_INTERVAL_MS,
+  SELECTED_INDICATOR,
+  UNSELECTED_INDICATOR,
+  KEY_ARROW_UP,
+  KEY_ARROW_DOWN,
+  KEY_CTRL_C,
+  PANEL_SHORTCUT_KEYS,
+  PANEL_DATE_SEPARATOR_PREFIX,
+  PANEL_FIXED_ROWS,
+} from './interactive-panel.js';

package/src/constants/interactive-panel.ts

@@ -0,0 +1,44 @@
+/** 自动刷新间隔（毫秒） */
+export const PANEL_REFRESH_INTERVAL_MS = 5000;
+
+/** 倒计时更新间隔（毫秒） */
+export const PANEL_COUNTDOWN_INTERVAL_MS = 1000;
+
+/** 选中指示器 */
+export const SELECTED_INDICATOR = '▶';
+
+/** 未选中占位（与选中指示器等宽） */
+export const UNSELECTED_INDICATOR = ' ';
+
+/** 方向键上的字节序列 */
+export const KEY_ARROW_UP = '\x1b[A';
+
+/** 方向键下的字节序列 */
+export const KEY_ARROW_DOWN = '\x1b[B';
+
+/** Ctrl+C 的字节值 */
+export const KEY_CTRL_C = 0x03;
+
+/** 面板快捷键映射 */
+export const PANEL_SHORTCUT_KEYS = {
+  /** 验证 */
+  VALIDATE: 'v',
+  /** 合并 */
+  MERGE: 'm',
+  /** 删除 */
+  DELETE: 'd',
+  /** 恢复 */
+  RESUME: 'r',
+  /** 同步 */
+  SYNC: 's',
+  /** 手动刷新 */
+  REFRESH: 'f',
+  /** 退出 */
+  QUIT: 'q',
+} as const;
+
+/** 日期分隔线前缀 */
+export const PANEL_DATE_SEPARATOR_PREFIX = '════';
+
+/** 固定占用行数（顶部分隔线 + 快照摘要 + 底部分隔线 + 底栏） */
+export const PANEL_FIXED_ROWS = 4;

package/src/constants/messages/completion.ts

@@ -3,7 +3,7 @@
  */
 export const COMPLETION_MESSAGES = {
   /** completion 命令的主描述 */
-  COMPLETION_COMMAND_DESC: '生成和安装 shell 自动补全脚本',
+  COMPLETION_COMMAND_DESC: '为终端提供 shell 自动补全功能（bash/zsh）',
   /** bash 子命令描述 */
   COMPLETION_BASH_DESC: '输出 bash 自动补全脚本',
   /** zsh 子命令描述 */

package/src/constants/messages/create.ts

@@ -2,4 +2,7 @@
 export const CREATE_MESSAGES = {
   /** 创建数量参数无效 */
   INVALID_COUNT: (value: string) => `无效的创建数量: "${value}"，请输入正整数`,
+  /** 当前不在主工作分支上的警告 */
+  CREATE_WARN_NOT_ON_MAIN_BRANCH: (mainBranch: string, currentBranch: string) =>
+    `当前不在主工作分支 ${mainBranch} 上（当前: ${currentBranch}）`,
 } as const;

package/src/constants/messages/index.ts

@@ -13,9 +13,12 @@ import { ALIAS_MESSAGES } from './alias.js';
 import { PROJECTS_MESSAGES } from './projects.js';
 import { COMPLETION_MESSAGES } from './completion.js';
 import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
+import { INIT_MESSAGES } from './init.js';
+import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
 export { UPDATE_MESSAGES, UPDATE_COMMANDS };
+export { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE };
 
 /**
  * 提示消息模板
@@ -36,4 +39,5 @@ export const MESSAGES = {
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
+  ...INIT_MESSAGES,
 } as const;

package/src/constants/messages/init.ts

@@ -0,0 +1,18 @@
+/** init 命令专属提示消息 */
+export const INIT_MESSAGES = {
+  /** init 成功 */
+  INIT_SUCCESS: (branch: string) =>
+    `✓ 项目初始化成功，主工作分支设置为: ${branch}`,
+  /** init 更新 */
+  INIT_UPDATED: (oldBranch: string, newBranch: string) =>
+    `✓ 已将主工作分支从 ${oldBranch} 更新为 ${newBranch}`,
+  /** init show 查看当前项目完整配置（JSON 格式） */
+  INIT_SHOW: (configJson: string) =>
+    `${configJson}`,
+  /** init 未初始化 */
+  INIT_NOT_INITIALIZED: '项目尚未初始化，请先执行 clawt init 设置主工作分支',
+  /** 项目未初始化（requireProjectConfig 使用） */
+  PROJECT_NOT_INITIALIZED: '项目尚未初始化，请先执行 clawt init 设置主工作分支',
+  /** 项目配置缺少 clawtMainWorkBranch 字段 */
+  PROJECT_CONFIG_MISSING_BRANCH: '项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支',
+} as const;

package/src/constants/messages/interactive-panel.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+import { PANEL_SHORTCUT_KEYS } from '../interactive-panel.js';
+
+/** 快捷键标签映射（键名 → 中文标签） */
+const SHORTCUT_LABELS: Record<keyof typeof PANEL_SHORTCUT_KEYS, string> = {
+  VALIDATE: '验证',
+  MERGE: '合并',
+  DELETE: '删除',
+  RESUME: '恢复',
+  SYNC: '同步',
+  REFRESH: '刷新',
+  QUIT: '退出',
+};
+
+/** 底栏快捷键提示文本（从 PANEL_SHORTCUT_KEYS 自动生成） */
+export const PANEL_FOOTER_SHORTCUTS = Object.entries(SHORTCUT_LABELS)
+  .map(([key, label]) => `[${chalk.cyan(PANEL_SHORTCUT_KEYS[key as keyof typeof PANEL_SHORTCUT_KEYS])}]${label}`)
+  .join('  ');
+
+/**
+ * 底栏倒计时文本
+ * @param {number} seconds - 剩余秒数
+ * @returns {string} 格式化的倒计时文本
+ */
+export const PANEL_FOOTER_COUNTDOWN = (seconds: number): string => chalk.gray(`(${seconds}s 后刷新)`);
+
+/** 向下溢出提示 */
+export const PANEL_OVERFLOW_DOWN_HINT = chalk.gray('↓ 更多 worktree...');
+
+/** 向上溢出提示 */
+export const PANEL_OVERFLOW_UP_HINT = chalk.gray('↑ 更多 worktree...');
+
+/**
+ * 快照摘要文本
+ * @param {number} total - 快照总数
+ * @param {number} orphaned - 孤立快照数
+ * @returns {string} 格式化的快照摘要
+ */
+export const PANEL_SNAPSHOT_SUMMARY = (total: number, orphaned: number): string => {
+  const base = `快照: ${total} 个`;
+  if (orphaned > 0) {
+    return `${base}（${chalk.yellow(`${orphaned} 个孤立`)}）`;
+  }
+  return base;
+};
+
+/** 无 worktree 提示 */
+export const PANEL_NO_WORKTREES = '(无活跃 worktree)';
+
+/** 操作后返回提示 */
+export const PANEL_PRESS_ENTER_TO_RETURN = chalk.gray('\n按 Enter 返回面板...');
+
+/** 非 TTY 降级提示 */
+export const PANEL_NOT_TTY = '交互式面板需要 TTY 终端环境，请直接在终端中运行 clawt status -i';
+
+/**
+ * 面板标题
+ * @param {string} projectName - 项目名
+ * @returns {string} 格式化的标题
+ */
+export const PANEL_TITLE = (projectName: string): string => chalk.bold.cyan(`项目状态总览: ${projectName}`);

package/src/constants/messages/remove.ts

@@ -14,4 +14,6 @@ export const REMOVE_MESSAGES = {
     `以下 worktree 移除失败：\n${failures.map((f) => `  ✗ ${f.path}: ${f.error}`).join('\n')}`,
   /** 用户选择保留本地分支 */
   REMOVE_BRANCHES_KEPT: '已保留本地分支，可稍后使用 git branch -D <分支名> 手动删除',
+  /** 确认删除本地分支和验证分支 */
+  REMOVE_CONFIRM_DELETE_BRANCHES: '是否同时删除对应的本地分支和验证分支？',
 } as const;

package/src/constants/messages/sync.ts

@@ -21,4 +21,7 @@ export const SYNC_MESSAGES = {
   SYNC_SELECT_BRANCH: '请选择要同步的分支',
   /** sync 模糊匹配到多个结果提示 */
   SYNC_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** sync 后验证分支已重建提示 */
+  SYNC_VALIDATE_BRANCH_REBUILT: (validateBranch: string) =>
+    `验证分支 ${validateBranch} 已重建`,
 } as const;

package/src/constants/messages/validate.ts

@@ -62,4 +62,10 @@ export const VALIDATE_MESSAGES = {
   /** 用户拒绝自动 sync */
   VALIDATE_AUTO_SYNC_DECLINED: (branch: string) =>
     `请手动执行 clawt sync -b ${branch} 同步主分支后重试`,
+  /** 验证分支不存在 */
+  VALIDATE_BRANCH_NOT_FOUND: (validateBranch: string, branch: string) =>
+    `验证分支 ${validateBranch} 不存在，请先执行 clawt create 或 clawt run 创建分支 ${branch}`,
+  /** validate 成功（含验证分支信息） */
+  VALIDATE_SUCCESS_WITH_BRANCH: (branch: string, validateBranch: string) =>
+    `✓ 已切换到验证分支 ${validateBranch} 并应用分支 ${branch} 的变更\n  可以开始验证了`,
 } as const;

package/src/constants/paths.ts

@@ -21,3 +21,6 @@ export const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
 
 /** 更新检查缓存文件路径 ~/.clawt/update-check.json */
 export const UPDATE_CHECK_PATH = join(CLAWT_HOME, 'update-check.json');
+
+/** 项目配置目录 ~/.clawt/projects/ */
+export const PROJECTS_CONFIG_DIR = join(CLAWT_HOME, 'projects');

package/src/index.ts

@@ -18,6 +18,7 @@ import { registerStatusCommand } from './commands/status.js';
 import { registerAliasCommand } from './commands/alias.js';
 import { registerProjectsCommand } from './commands/projects.js';
 import { registerCompletionCommand } from './commands/completion.js';
+import { registerInitCommand } from './commands/init.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -56,6 +57,7 @@ registerStatusCommand(program);
 registerAliasCommand(program);
 registerProjectsCommand(program);
 registerCompletionCommand(program);
+registerInitCommand(program);
 
 // 加载配置并应用命令别名
 const config = loadConfig();

package/src/types/command.ts

@@ -34,7 +34,7 @@ export interface ValidateOptions {
 export interface MergeOptions {
   /** 要合并的分支名（可选，支持模糊匹配，不传则列出所有分支供选择） */
   branch?: string;
-  /** 提交信息（工作区有修改时必填） */
+  /** 提交信息（目标 worktree 工作区有修改时必填） */
   message?: string;
 }
 
@@ -68,6 +68,8 @@ export interface ListOptions {
 export interface StatusOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
+  /** 交互式面板模式 */
+  interactive?: boolean;
 }
 
 /** projects 命令选项 */
@@ -77,3 +79,9 @@ export interface ProjectsOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** init 命令选项 */
+export interface InitOptions {
+  /** 指定主工作分支名（可选，默认使用当前分支） */
+  branch?: string;
+}