clawt 2.19.0 → 3.0.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

@@ -30,7 +30,7 @@ import {
 export function registerStatusCommand(program: Command): void {
   program
     .command('status')
-    .description('显示项目全局状态总览')
+    .description('显示项目全局状态总览（支持 --json 格式输出）')
     .option('--json', '以 JSON 格式输出')
     .action((options: StatusOptions) => {
       handleStatus(options);

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';
@@ -29,4 +29,4 @@ export {
   CLEAR_SCREEN,
   CURSOR_HOME,
 } from './progress.js';
-export { SELECT_ALL_NAME, SELECT_ALL_LABEL } from './prompt.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';

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,6 +13,7 @@ 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';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
 export { UPDATE_MESSAGES, UPDATE_COMMANDS };
@@ -36,4 +37,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/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/constants/prompt.ts

@@ -1,5 +1,33 @@
+import chalk from 'chalk';
+
 /** 多选列表中全选选项的标识名称 */
 export const SELECT_ALL_NAME = '__select_all__';
 
 /** 多选列表中全选选项的显示文本 */
 export const SELECT_ALL_LABEL = '[select-all]';
+
+/** 组级全选选项的 name 前缀 */
+export const GROUP_SELECT_ALL_PREFIX = '__group_select_all_';
+
+/**
+ * 生成组级全选选项的显示文本
+ * @param {string} dateLabel - 日期标签
+ * @returns {string} 格式化的组全选显示文本
+ */
+export const GROUP_SELECT_ALL_LABEL = (dateLabel: string): string => `[select-all: ${dateLabel}]`;
+
+/**
+ * 生成日期分组分隔线的显示文本
+ * 日期部分高亮显示，两侧使用 === 分隔线增强视觉区分
+ * @param {string} dateLabel - 日期标签
+ * @param {string} relativeTime - 相对时间描述
+ * @returns {string} 格式化的分隔线文本
+ */
+export const GROUP_SEPARATOR_LABEL = (dateLabel: string, relativeTime: string): string =>
+  `════ ${chalk.bold.hex('#FF8C00')(dateLabel)}（${chalk.hex('#FF8C00')(relativeTime)}） ════`;
+
+/** 无法获取创建日期时的默认分组名称 */
+export const UNKNOWN_DATE_GROUP = '未知日期';
+
+/** 未知日期分组的分隔线显示文本 */
+export const UNKNOWN_DATE_SEPARATOR_LABEL = `════ ${chalk.bold.hex('#FF8C00')('未知日期')} ════`;

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;
 }
 
@@ -77,3 +77,9 @@ export interface ProjectsOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** init 命令选项 */
+export interface InitOptions {
+  /** 指定主工作分支名（可选，默认使用当前分支） */
+  branch?: string;
+}

package/src/types/index.ts

@@ -1,8 +1,9 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions, ProjectsOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions, ProjectsOptions, InitOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 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';

package/src/types/projectConfig.ts

@@ -0,0 +1,5 @@
+/** 项目级配置（存储在 ~/.clawt/projects/<projectName>.json） */
+export interface ProjectConfig {
+  /** 主 worktree 的工作分支名 */
+  clawtMainWorkBranch: string;
+}

package/src/utils/config.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { CONFIG_PATH, CLAWT_HOME, LOGS_DIR, WORKTREES_DIR, DEFAULT_CONFIG, MESSAGES } from '../constants/index.js';
+import { CONFIG_PATH, CLAWT_HOME, LOGS_DIR, WORKTREES_DIR, DEFAULT_CONFIG, MESSAGES, PROJECTS_CONFIG_DIR } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { ensureDir } from './fs.js';
 import { logger } from '../logger/index.js';
@@ -65,6 +65,7 @@ export function ensureClawtDirs(): void {
   ensureDir(CLAWT_HOME);
   ensureDir(LOGS_DIR);
   ensureDir(WORKTREES_DIR);
+  ensureDir(PROJECTS_CONFIG_DIR);
 }
 
 /**

package/src/utils/git.ts

@@ -501,3 +501,21 @@ export function getBranchCreatedAt(branchName: string, cwd?: string): string | n
     return null;
   }
 }
+
+/**
+ * 切换到指定分支
+ * @param {string} branchName - 目标分支名
+ * @param {string} [cwd] - 工作目录
+ */
+export function gitCheckout(branchName: string, cwd?: string): void {
+  execCommand(`git checkout ${branchName}`, { cwd });
+}
+
+/**
+ * 创建本地分支（不切换）
+ * @param {string} branchName - 新分支名
+ * @param {string} [cwd] - 工作目录
+ */
+export function createBranch(branchName: string, cwd?: string): void {
+  execCommand(`git branch ${branchName}`, { cwd });
+}

package/src/utils/index.ts

@@ -46,6 +46,8 @@ export {
   gitDiffTree,
   gitApplyCachedCheck,
   getBranchCreatedAt,
+  gitCheckout,
+  createBranch,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -56,7 +58,7 @@ export { ensureDir, removeEmptyDir, calculateDirSize } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude, hasClaudeSessionHistory, launchInteractiveClaudeInNewTerminal } from './claude.js';
 export { getSnapshotPath, hasSnapshot, getSnapshotModifiedTime, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';
-export { findExactMatch, findFuzzyMatches, promptSelectBranch, promptMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees } from './worktree-matcher.js';
+export { findExactMatch, findFuzzyMatches, promptSelectBranch, promptMultiSelectBranches, promptGroupedMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees, groupWorktreesByDate, buildGroupedChoices, buildGroupMembershipMap } from './worktree-matcher.js';
 export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './worktree-matcher.js';
 export { ProgressRenderer } from './progress.js';
 export { parseTaskFile, loadTaskFile, parseTasksFromOptions } from './task-file.js';
@@ -68,4 +70,7 @@ export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
 export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue } from './config-strategy.js';
 export { checkForUpdates } from './update-checker.js';
+export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch } from './project-config.js';
+export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebuildValidateBranch, ensureOnMainWorkBranch, handleDirtyWorkingDir } from './validate-branch.js';
+export { safeStringify } from './json.js';