clawt 2.9.1 → 2.10.1

package/src/commands/status.ts

@@ -0,0 +1,327 @@
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import { MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import type { StatusOptions, WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, StatusResult, WorktreeInfo } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getProjectName,
+  getCurrentBranch,
+  isWorkingDirClean,
+  getProjectWorktrees,
+  getCommitCountAhead,
+  getCommitCountBehind,
+  getDiffStat,
+  hasMergeConflict,
+  hasLocalCommits,
+  hasSnapshot,
+  getProjectSnapshotBranches,
+  printInfo,
+  printDoubleSeparator,
+  printSeparator,
+} from '../utils/index.js';
+
+/**
+ * 注册 status 命令：显示项目全局状态总览
+ * @param {Command} program - Commander 实例
+ */
+export function registerStatusCommand(program: Command): void {
+  program
+    .command('status')
+    .description('显示项目全局状态总览')
+    .option('--json', '以 JSON 格式输出')
+    .action((options: StatusOptions) => {
+      handleStatus(options);
+    });
+}
+
+/**
+ * 执行 status 命令的核心逻辑
+ * @param {StatusOptions} options - 命令选项
+ */
+function handleStatus(options: StatusOptions): void {
+  validateMainWorktree();
+
+  const statusResult = collectStatus();
+
+  logger.info(`status 命令执行，项目: ${statusResult.main.projectName}，共 ${statusResult.totalWorktrees} 个 worktree`);
+
+  if (options.json) {
+    printStatusAsJson(statusResult);
+    return;
+  }
+
+  printStatusAsText(statusResult);
+}
+
+/**
+ * 收集项目全局状态信息
+ * @returns {StatusResult} 完整的状态数据
+ */
+function collectStatus(): StatusResult {
+  const projectName = getProjectName();
+  const currentBranch = getCurrentBranch();
+  const isClean = isWorkingDirClean();
+
+  // 主 worktree 状态
+  const main: MainWorktreeStatus = {
+    branch: currentBranch,
+    isClean,
+    projectName,
+  };
+
+  // 各 worktree 详细状态
+  const worktrees = getProjectWorktrees();
+  const worktreeStatuses = worktrees.map((wt) => collectWorktreeDetailedStatus(wt, projectName));
+
+  // 未清理的 validate 快照
+  const snapshots = collectSnapshots(projectName, worktrees);
+
+  return {
+    main,
+    worktrees: worktreeStatuses,
+    snapshots,
+    totalWorktrees: worktrees.length,
+  };
+}
+
+/**
+ * 收集单个 worktree 的详细状态
+ * 变更状态判断优先级：冲突 > 未提交 > 已提交 > 干净
+ * @param {WorktreeInfo} worktree - worktree 信息
+ * @param {string} projectName - 项目名
+ * @returns {WorktreeDetailedStatus} 详细状态
+ */
+function collectWorktreeDetailedStatus(worktree: WorktreeInfo, projectName: string): WorktreeDetailedStatus {
+  const changeStatus = detectChangeStatus(worktree);
+  const { commitsAhead, commitsBehind } = countCommitDivergence(worktree.branch);
+  const { insertions, deletions } = countDiffStat(worktree.path);
+
+  return {
+    path: worktree.path,
+    branch: worktree.branch,
+    changeStatus,
+    commitsAhead,
+    commitsBehind,
+    hasSnapshot: hasSnapshot(projectName, worktree.branch),
+    insertions,
+    deletions,
+  };
+}
+
+/**
+ * 检测 worktree 的变更状态
+ * 优先级：冲突 > 未提交 > 已提交 > 干净
+ * @param {WorktreeInfo} worktree - worktree 信息
+ * @returns {WorktreeDetailedStatus['changeStatus']} 变更状态
+ */
+function detectChangeStatus(worktree: WorktreeInfo): WorktreeDetailedStatus['changeStatus'] {
+  try {
+    if (hasMergeConflict(worktree.path)) {
+      return 'conflict';
+    }
+    if (!isWorkingDirClean(worktree.path)) {
+      return 'uncommitted';
+    }
+    if (hasLocalCommits(worktree.branch)) {
+      return 'committed';
+    }
+    return 'clean';
+  } catch {
+    return 'clean';
+  }
+}
+
+/**
+ * 统计分支与主分支的提交差异（领先/落后数）
+ * @param {string} branchName - 分支名
+ * @returns {{ commitsAhead: number; commitsBehind: number }} 领先和落后的提交数
+ */
+function countCommitDivergence(branchName: string): { commitsAhead: number; commitsBehind: number } {
+  try {
+    return {
+      commitsAhead: getCommitCountAhead(branchName),
+      commitsBehind: getCommitCountBehind(branchName),
+    };
+  } catch {
+    return { commitsAhead: 0, commitsBehind: 0 };
+  }
+}
+
+/**
+ * 统计 worktree 的差异行数
+ * @param {string} worktreePath - worktree 路径
+ * @returns {{ insertions: number; deletions: number }} 新增和删除行数
+ */
+function countDiffStat(worktreePath: string): { insertions: number; deletions: number } {
+  try {
+    return getDiffStat(worktreePath);
+  } catch {
+    return { insertions: 0, deletions: 0 };
+  }
+}
+
+/**
+ * 收集未清理的 validate 快照信息
+ * 对比快照分支与现有 worktree 分支，标识孤立快照
+ * @param {string} projectName - 项目名
+ * @param {WorktreeInfo[]} worktrees - 当前有效的 worktree 列表
+ * @returns {SnapshotInfo[]} 快照信息列表
+ */
+function collectSnapshots(projectName: string, worktrees: WorktreeInfo[]): SnapshotInfo[] {
+  const snapshotBranches = getProjectSnapshotBranches(projectName);
+  const worktreeBranchSet = new Set(worktrees.map((wt) => wt.branch));
+
+  return snapshotBranches.map((branch) => ({
+    branch,
+    worktreeExists: worktreeBranchSet.has(branch),
+  }));
+}
+
+/**
+ * 以 JSON 格式输出状态信息
+ * @param {StatusResult} result - 状态数据
+ */
+function printStatusAsJson(result: StatusResult): void {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+/**
+ * 以文本格式输出状态信息
+ * @param {StatusResult} result - 状态数据
+ */
+function printStatusAsText(result: StatusResult): void {
+  // 标题区域
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  // 主 Worktree 区块
+  printMainSection(result.main);
+  printSeparator();
+  printInfo('');
+
+  // Worktree 列表区块
+  printWorktreesSection(result.worktrees, result.totalWorktrees);
+  printSeparator();
+  printInfo('');
+
+  // 未清理快照区块
+  printSnapshotsSection(result.snapshots);
+
+  printDoubleSeparator();
+}
+
+/**
+ * 输出主 Worktree 区块
+ * @param {MainWorktreeStatus} main - 主 worktree 状态
+ */
+function printMainSection(main: MainWorktreeStatus): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
+  printInfo(`    分支: ${chalk.bold(main.branch)}`);
+  if (main.isClean) {
+    printInfo(`    状态: ${chalk.green('✓ 干净')}`);
+  } else {
+    printInfo(`    状态: ${chalk.yellow('✗ 有未提交修改')}`);
+  }
+  printInfo('');
+}
+
+/**
+ * 输出 Worktree 列表区块
+ * @param {WorktreeDetailedStatus[]} worktrees - worktree 详细状态列表
+ * @param {number} total - worktree 总数
+ */
+function printWorktreesSection(worktrees: WorktreeDetailedStatus[], total: number): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} 个)`);
+  printInfo('');
+
+  if (worktrees.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_WORKTREES}`);
+    return;
+  }
+
+  for (const wt of worktrees) {
+    printWorktreeItem(wt);
+  }
+}
+
+/**
+ * 输出单个 worktree 状态项
+ * @param {WorktreeDetailedStatus} wt - worktree 详细状态
+ */
+function printWorktreeItem(wt: WorktreeDetailedStatus): void {
+  // 分支名 + 变更状态标签
+  const statusLabel = formatChangeStatusLabel(wt.changeStatus);
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(wt.branch)}   [${statusLabel}]`);
+
+  // 差异统计行
+  const parts: string[] = [];
+
+  // 行数变更（仅在有变更时展示）
+  if (wt.insertions > 0 || wt.deletions > 0) {
+    parts.push(`${chalk.green(`+${wt.insertions}`)} ${chalk.red(`-${wt.deletions}`)}`);
+  }
+
+  // 本地提交数
+  if (wt.commitsAhead > 0) {
+    parts.push(chalk.yellow(`${wt.commitsAhead} 个本地提交`));
+  }
+
+  // 与主分支的同步状态
+  if (wt.commitsBehind > 0) {
+    parts.push(chalk.yellow(`落后主分支 ${wt.commitsBehind} 个提交`));
+  } else {
+    parts.push(chalk.green('与主分支同步'));
+  }
+
+  printInfo(`    ${parts.join('   ')}`);
+
+  // 快照状态
+  if (wt.hasSnapshot) {
+    printInfo(`    ${chalk.blue('有 validate 快照')}`);
+  }
+
+  printInfo('');
+}
+
+/**
+ * 将变更状态枚举格式化为带颜色的标签文本
+ * @param {WorktreeDetailedStatus['changeStatus']} status - 变更状态
+ * @returns {string} 格式化后的标签
+ */
+function formatChangeStatusLabel(status: WorktreeDetailedStatus['changeStatus']): string {
+  switch (status) {
+    case 'committed':
+      return chalk.green(MESSAGES.STATUS_CHANGE_COMMITTED);
+    case 'uncommitted':
+      return chalk.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
+    case 'conflict':
+      return chalk.red(MESSAGES.STATUS_CHANGE_CONFLICT);
+    case 'clean':
+      return chalk.gray(MESSAGES.STATUS_CHANGE_CLEAN);
+  }
+}
+
+/**
+ * 输出未清理快照区块
+ * @param {SnapshotInfo[]} snapshots - 快照信息列表
+ */
+function printSnapshotsSection(snapshots: SnapshotInfo[]): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.length} 个)`);
+  printInfo('');
+
+  if (snapshots.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_SNAPSHOTS}`);
+    printInfo('');
+    return;
+  }
+
+  for (const snap of snapshots) {
+    const orphanLabel = snap.worktreeExists ? '' : `  ${chalk.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED)}`;
+    const icon = snap.worktreeExists ? chalk.blue('●') : chalk.yellow('⚠');
+    printInfo(`  ${icon} ${snap.branch}${orphanLabel}`);
+  }
+  printInfo('');
+}

package/src/constants/index.ts

@@ -1,6 +1,6 @@
 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 { MESSAGES } from './messages/index.js';
 export { EXIT_CODES } from './exitCodes.js';
 export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS } from './terminal.js';
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, APPEND_SYSTEM_PROMPT } from './config.js';

package/src/constants/messages/common.ts

@@ -0,0 +1,41 @@
+/** 通用/共享提示消息 */
+export const COMMON_MESSAGES = {
+  /** 不在主 worktree 根目录 */
+  NOT_MAIN_WORKTREE: '请在主 worktree 的根目录下执行 clawt',
+  /** Git 未安装 */
+  GIT_NOT_INSTALLED: 'Git 未安装或不在 PATH 中，请先安装 Git',
+  /** Claude Code CLI 未安装 */
+  CLAUDE_NOT_INSTALLED: 'Claude Code CLI 未安装，请先安装：npm install -g @anthropic-ai/claude-code',
+  /** 分支已存在 */
+  BRANCH_EXISTS: (name: string) => `分支 ${name} 已存在，无法创建`,
+  /** 分支名清理后为空 */
+  BRANCH_NAME_EMPTY: (original: string) =>
+    `分支名 "${original}" 中不包含合法字符，无法创建分支`,
+  /** 分支名被转换 */
+  BRANCH_SANITIZED: (original: string, sanitized: string) =>
+    `分支名已转换: ${original} → ${sanitized}`,
+  /** worktree 创建成功 */
+  WORKTREE_CREATED: (count: number) => `✓ 已创建 ${count} 个 worktree`,
+  /** worktree 移除成功 */
+  WORKTREE_REMOVED: (path: string) => `✓ 已移除 worktree: ${path}`,
+  /** 没有 worktree */
+  NO_WORKTREES: '(无 worktree)',
+  /** 目标 worktree 不存在 */
+  WORKTREE_NOT_FOUND: (name: string) => `worktree ${name} 不存在`,
+  /** 主 worktree 有未提交更改 */
+  MAIN_WORKTREE_DIRTY: '主 worktree 有未提交的更改，请先处理',
+  /** 目标 worktree 无更改 */
+  TARGET_WORKTREE_CLEAN: '该 worktree 的分支上没有任何更改，无需验证',
+  /** 用户取消破坏性操作 */
+  DESTRUCTIVE_OP_CANCELLED: '已取消操作',
+  /** 请提供提交信息 */
+  COMMIT_MESSAGE_REQUIRED: '请提供提交信息（-m 参数）',
+  /** 配置文件损坏，已重新生成默认配置 */
+  CONFIG_CORRUPTED: '配置文件损坏或无法解析，已重新生成默认配置',
+  /** worktree 状态获取失败 */
+  WORKTREE_STATUS_UNAVAILABLE: '(状态不可用)',
+  /** 分隔线 */
+  SEPARATOR: '────────────────────────────────────────',
+  /** 粗分隔线 */
+  DOUBLE_SEPARATOR: '════════════════════════════════════════',
+} as const;

package/src/constants/messages/config.ts

@@ -0,0 +1,5 @@
+/** config 命令专属提示消息 */
+export const CONFIG_CMD_MESSAGES = {
+  /** 配置已恢复为默认值 */
+  CONFIG_RESET_SUCCESS: '✓ 配置已恢复为默认值',
+} as const;

package/src/constants/messages/create.ts

@@ -0,0 +1,5 @@
+/** create 命令专属提示消息 */
+export const CREATE_MESSAGES = {
+  /** 创建数量参数无效 */
+  INVALID_COUNT: (value: string) => `无效的创建数量: "${value}"，请输入正整数`,
+} as const;

package/src/constants/messages/index.ts

@@ -0,0 +1,29 @@
+import { COMMON_MESSAGES } from './common.js';
+import { RUN_MESSAGES } from './run.js';
+import { CREATE_MESSAGES } from './create.js';
+import { MERGE_MESSAGES } from './merge.js';
+import { VALIDATE_MESSAGES } from './validate.js';
+import { SYNC_MESSAGES } from './sync.js';
+import { RESUME_MESSAGES } from './resume.js';
+import { REMOVE_MESSAGES } from './remove.js';
+import { RESET_MESSAGES } from './reset.js';
+import { CONFIG_CMD_MESSAGES } from './config.js';
+import { STATUS_MESSAGES } from './status.js';
+
+/**
+ * 提示消息模板
+ * 合并所有子模块的消息，保持扁平结构以兼容现有的 MESSAGES.XXX 访问方式
+ */
+export const MESSAGES = {
+  ...COMMON_MESSAGES,
+  ...RUN_MESSAGES,
+  ...CREATE_MESSAGES,
+  ...MERGE_MESSAGES,
+  ...VALIDATE_MESSAGES,
+  ...SYNC_MESSAGES,
+  ...RESUME_MESSAGES,
+  ...REMOVE_MESSAGES,
+  ...RESET_MESSAGES,
+  ...CONFIG_CMD_MESSAGES,
+  ...STATUS_MESSAGES,
+} as const;

package/src/constants/messages/merge.ts

@@ -0,0 +1,42 @@
+/** merge 命令专属提示消息 */
+export const MERGE_MESSAGES = {
+  /** merge 成功 */
+  MERGE_SUCCESS: (branch: string, message: string, pushed: boolean) =>
+    `✓ 分支 ${branch} 已成功合并到当前分支\n  提交信息: ${message}${pushed ? '\n  已推送到远程仓库' : ''}`,
+  /** merge 成功（无提交信息，目标 worktree 已提交过） */
+  MERGE_SUCCESS_NO_MESSAGE: (branch: string, pushed: boolean) =>
+    `✓ 分支 ${branch} 已成功合并到当前分支${pushed ? '\n  已推送到远程仓库' : ''}`,
+  /** merge 冲突 */
+  MERGE_CONFLICT: '合并存在冲突，请手动处理：\n  解决冲突后执行 git add . && git merge --continue',
+  /** merge 后清理 worktree 和分支成功 */
+  WORKTREE_CLEANED: (branch: string) => `✓ 已清理 worktree 和分支: ${branch}`,
+  /** 目标 worktree 有未提交修改但未指定 -m */
+  TARGET_WORKTREE_DIRTY_NO_MESSAGE: '目标 worktree 有未提交的修改，请通过 -m 参数提供提交信息',
+  /** 目标 worktree 既干净又无本地提交 */
+  TARGET_WORKTREE_NO_CHANGES: '目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）',
+  /** merge 命令检测到 validate 状态的提示 */
+  MERGE_VALIDATE_STATE_HINT: (branch: string) =>
+    `主 worktree 可能存在 validate 残留状态，可先执行 clawt validate -b ${branch} --clean 清理`,
+  /** merge 检测到 auto-save 提交，提示用户是否压缩 */
+  MERGE_SQUASH_PROMPT: '检测到 sync 产生的临时提交，是否将所有提交压缩为一个？\n  压缩后变更将保留在目标worktree的暂存区，需要重新提交（可使用 Claude Code Cli或其他工具生成提交信息）',
+  /** squash 完成且通过 -m 直接提交后的提示 */
+  MERGE_SQUASH_COMMITTED: (branch: string) =>
+    `✓ 已将分支 ${branch} 的所有提交压缩为一个`,
+  /** squash 完成但未提供 -m，提示用户自行提交 */
+  MERGE_SQUASH_PENDING: (worktreePath: string, branch: string) =>
+    `✓ 已将所有提交压缩到暂存区\n  请在目标 worktree 中提交后重新执行 merge：\n  cd ${worktreePath}\n  提交完成后执行：clawt merge -b ${branch}`,
+  /** merge 后 pull 冲突 */
+  PULL_CONFLICT:
+    '自动 pull 时发生冲突，merge 已完成但远程同步失败\n  请手动解决冲突：\n  解决冲突后执行 git add . && git commit\n  然后执行 git push 推送到远程',
+  /** push 失败 */
+  PUSH_FAILED: '自动 push 失败，merge 和 pull 已完成\n  请手动执行 git push',
+  /** merge 无可用 worktree */
+  MERGE_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** merge 模糊匹配无结果，列出可用分支 */
+  MERGE_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** merge 交互选择提示 */
+  MERGE_SELECT_BRANCH: '请选择要合并的分支',
+  /** merge 模糊匹配到多个结果提示 */
+  MERGE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+} as const;

package/src/constants/messages/remove.ts

@@ -0,0 +1,15 @@
+/** remove 命令专属提示消息 */
+export const REMOVE_MESSAGES = {
+  /** remove 无可用 worktree */
+  REMOVE_NO_WORKTREES: '当前项目没有可用的 worktree，无需移除',
+  /** remove 多选交互提示 */
+  REMOVE_SELECT_BRANCH: '请选择要移除的分支（空格选择，回车确认）',
+  /** remove 模糊匹配到多个结果提示 */
+  REMOVE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择要移除的（空格选择，回车确认）：`,
+  /** remove 模糊匹配无结果，列出可用分支 */
+  REMOVE_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** 批量移除部分失败 */
+  REMOVE_PARTIAL_FAILURE: (failures: Array<{ path: string; error: string }>) =>
+    `以下 worktree 移除失败：\n${failures.map((f) => `  ✗ ${f.path}: ${f.error}`).join('\n')}`,
+} as const;

package/src/constants/messages/reset.ts

@@ -0,0 +1,7 @@
+/** reset 命令专属提示消息 */
+export const RESET_MESSAGES = {
+  /** reset 成功 */
+  RESET_SUCCESS: '✓ 主 worktree 工作区和暂存区已重置',
+  /** reset 时工作区和暂存区已干净 */
+  RESET_ALREADY_CLEAN: '主 worktree 工作区和暂存区已是干净状态，无需重置',
+} as const;

package/src/constants/messages/resume.ts

@@ -0,0 +1,12 @@
+/** resume 命令专属提示消息 */
+export const RESUME_MESSAGES = {
+  /** resume 无可用 worktree */
+  RESUME_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** resume 模糊匹配无结果，列出可用分支 */
+  RESUME_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** resume 交互选择提示 */
+  RESUME_SELECT_BRANCH: '请选择要恢复的分支',
+  /** resume 模糊匹配到多个结果提示 */
+  RESUME_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+} as const;

package/src/constants/messages/run.ts

@@ -0,0 +1,16 @@
+/** run 命令专属提示消息 */
+export const RUN_MESSAGES = {
+  /** 分支已存在时提示使用 resume */
+  BRANCH_EXISTS_USE_RESUME: (name: string) =>
+    `分支 ${name} 已存在，请使用 clawt resume -b ${name} 恢复会话`,
+  /** 检测到用户中断 */
+  INTERRUPTED: '检测到退出指令，已停止 Claude Code 任务',
+  /** 中断后自动清理完成 */
+  INTERRUPT_AUTO_CLEANED: (count: number) => `✓ 已自动清理 ${count} 个 worktree 和对应分支`,
+  /** 中断后手动确认清理 */
+  INTERRUPT_CONFIRM_CLEANUP: '是否移除刚刚创建的 worktree 和对应分支？',
+  /** 中断后清理完成 */
+  INTERRUPT_CLEANED: (count: number) => `✓ 已清理 ${count} 个 worktree 和对应分支`,
+  /** 中断后保留 worktree */
+  INTERRUPT_KEPT: '已保留 worktree，可稍后使用 clawt remove 手动清理',
+} as const;

package/src/constants/messages/status.ts

@@ -0,0 +1,25 @@
+/** status 命令专属提示消息 */
+export const STATUS_MESSAGES = {
+  /** status 命令标题 */
+  STATUS_TITLE: (projectName: string) => `项目状态总览: ${projectName}`,
+  /** status 主 worktree 区块标题 */
+  STATUS_MAIN_SECTION: '主 Worktree',
+  /** status worktrees 区块标题 */
+  STATUS_WORKTREES_SECTION: 'Worktree 列表',
+  /** status 快照区块标题 */
+  STATUS_SNAPSHOTS_SECTION: '未清理的 Validate 快照',
+  /** status 无 worktree */
+  STATUS_NO_WORKTREES: '(无活跃 worktree)',
+  /** status 无未清理快照 */
+  STATUS_NO_SNAPSHOTS: '(无未清理的快照)',
+  /** status 变更状态：已提交 */
+  STATUS_CHANGE_COMMITTED: '已提交',
+  /** status 变更状态：未提交修改 */
+  STATUS_CHANGE_UNCOMMITTED: '未提交修改',
+  /** status 变更状态：合并冲突 */
+  STATUS_CHANGE_CONFLICT: '合并冲突',
+  /** status 变更状态：无变更 */
+  STATUS_CHANGE_CLEAN: '无变更',
+  /** status 快照对应 worktree 已不存在 */
+  STATUS_SNAPSHOT_ORPHANED: '(对应 worktree 已不存在)',
+} as const;

package/src/constants/messages/sync.ts

@@ -0,0 +1,24 @@
+/** sync 命令专属提示消息 */
+export const SYNC_MESSAGES = {
+  /** 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\n  clawt validate -b <branch> 验证变更`,
+  /** sync 无可用 worktree */
+  SYNC_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** sync 模糊匹配无结果，列出可用分支 */
+  SYNC_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** sync 交互选择提示 */
+  SYNC_SELECT_BRANCH: '请选择要同步的分支',
+  /** sync 模糊匹配到多个结果提示 */
+  SYNC_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+} as const;

package/src/constants/messages/validate.ts

@@ -0,0 +1,25 @@
+/** validate 命令专属提示消息 */
+export const VALIDATE_MESSAGES = {
+  /** validate 成功 */
+  VALIDATE_SUCCESS: (branch: string) =>
+    `✓ 已将分支 ${branch} 的变更应用到主 worktree\n  可以开始验证了`,
+  /** 增量 validate 成功提示 */
+  INCREMENTAL_VALIDATE_SUCCESS: (branch: string) =>
+    `✓ 已将分支 ${branch} 的最新变更应用到主 worktree（增量模式）\n  暂存区 = 上次快照，工作目录 = 最新变更`,
+  /** 增量 validate 降级为全量模式提示 */
+  INCREMENTAL_VALIDATE_FALLBACK: '增量对比失败，已降级为全量模式',
+  /** validate 状态已清理 */
+  VALIDATE_CLEANED: (branch: string) => `✓ 分支 ${branch} 的 validate 状态已清理`,
+  /** validate patch apply 失败，提示用户同步主分支 */
+  VALIDATE_PATCH_APPLY_FAILED: (branch: string) =>
+    `变更迁移失败：目标分支与主分支差异过大\n  请先执行 clawt sync -b ${branch} 同步主分支后重试`,
+  /** validate 无可用 worktree */
+  VALIDATE_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** validate 模糊匹配无结果，列出可用分支 */
+  VALIDATE_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** validate 交互选择提示 */
+  VALIDATE_SELECT_BRANCH: '请选择要验证的分支',
+  /** validate 模糊匹配到多个结果提示 */
+  VALIDATE_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+} as const;

package/src/constants/messages.ts

@@ -148,6 +148,28 @@ export const MESSAGES = {
   SYNC_SELECT_BRANCH: '请选择要同步的分支',
   /** sync 模糊匹配到多个结果提示 */
   SYNC_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** status 命令标题 */
+  STATUS_TITLE: (projectName: string) => `项目状态总览: ${projectName}`,
+  /** status 主 worktree 区块标题 */
+  STATUS_MAIN_SECTION: '主 Worktree',
+  /** status worktrees 区块标题 */
+  STATUS_WORKTREES_SECTION: 'Worktree 列表',
+  /** status 快照区块标题 */
+  STATUS_SNAPSHOTS_SECTION: '未清理的 Validate 快照',
+  /** status 无 worktree */
+  STATUS_NO_WORKTREES: '(无活跃 worktree)',
+  /** status 无未清理快照 */
+  STATUS_NO_SNAPSHOTS: '(无未清理的快照)',
+  /** status 变更状态：已提交 */
+  STATUS_CHANGE_COMMITTED: '已提交',
+  /** status 变更状态：未提交修改 */
+  STATUS_CHANGE_UNCOMMITTED: '未提交修改',
+  /** status 变更状态：合并冲突 */
+  STATUS_CHANGE_CONFLICT: '合并冲突',
+  /** status 变更状态：无变更 */
+  STATUS_CHANGE_CLEAN: '无变更',
+  /** status 快照对应 worktree 已不存在 */
+  STATUS_SNAPSHOT_ORPHANED: '(对应 worktree 已不存在)',
   /** merge 后 pull 冲突 */
   PULL_CONFLICT:
     '自动 pull 时发生冲突，merge 已完成但远程同步失败\n  请手动解决冲突：\n  解决冲突后执行 git add . && git commit\n  然后执行 git push 推送到远程',

package/src/index.ts

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

package/src/types/command.ts

@@ -55,3 +55,9 @@ export interface ListOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** status 命令选项 */
+export interface StatusOptions {
+  /** 以 JSON 格式输出 */
+  json?: boolean;
+}

package/src/types/index.ts

@@ -1,5 +1,6 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions } 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, StatusResult } from './status.js';