clawt 3.10.4 → 3.10.6

package/docs/validate.md

@@ -158,9 +158,44 @@ git restore --staged .
 > 此步骤结束后，目标 worktree 的代码保持原样，主 worktree 工作目录包含目标分支的全量变更。
 > 如果 patch apply 失败（兜底场景），`migrateChangesViaPatch` 返回 `{ success: false }`，进入自动 sync 交互流程（见下文 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)）。
 
+###### 幽灵文件检测（patch apply 前置拦截）
+
+在执行昂贵的 `git diff --binary` 之前，`migrateChangesViaPatch` 会先进行轻量级的**幽灵文件检测**，提前拦截一类常见的 patch apply 失败场景。
+
+**背景：** AI Agent（如 Claude Code）在 worktree 中工作时，可能会创建被 `.gitignore` 忽略的文件（如 `node_modules/` 下的依赖、构建产物等）。这些文件不受 git 跟踪，但当目标分支的 patch 中包含同名文件时，`git apply` 会因为"文件已存在于工作区中"而失败。由于这些文件被 `.gitignore` 忽略，`git clean -fd` 无法清理它们（需要 `git clean -fdx`），用户往往难以自行发现和定位。
+
+**检测流程：**
+
+1. **获取 patch 涉及的文件列表**：通过 `git diff --name-only HEAD...<branchName>` 轻量获取目标分支变更涉及的所有文件路径（不含二进制内容，远比 `--binary` 便宜）
+2. **筛选被 `.gitignore` 忽略的文件**：调用 `gitCheckIgnored()`（`src/utils/git-core.ts`），通过 `git check-ignore` 批量检测哪些文件被忽略规则匹配
+3. **确认文件物理存在**：对被忽略的文件进一步检查其是否真实存在于主 worktree 文件系统中（`existsSync`），只有同时满足"被忽略"和"物理存在"两个条件的才是幽灵文件
+4. **拦截并提示**：如果检测到幽灵文件，生成针对性的 `git clean -fdx` 清理命令（按直接父目录去重，通过 `buildCleanCommands()` 生成），输出清晰的错误提示后返回 `{ success: false }`
+
+**错误提示示例：**
+
+```
+检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - dist/bundle.js
+  - node_modules/.cache/temp.json
+
+请手动清理后重试：
+  git clean -fdx dist/
+  git clean -fdx node_modules/.cache/
+```
+
+> 幽灵文件检测失败后，同样进入 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)（询问用户是否执行 sync），但用户通常应根据提示先手动清理幽灵文件再重试 validate。
+> 如果 `git diff --name-only` 执行失败（如分支不存在），检测会静默跳过（降级为原有行为，让后续 apply 自行报错）。
+
+**实现要点：**
+
+- `detectIgnoredFilesInPatch(branchName, mainWorktreePath)`（`src/utils/validate-core.ts`）：检测 patch 中的幽灵文件，返回幽灵文件的相对路径列表
+- `gitCheckIgnored(paths, cwd)`（`src/utils/git-core.ts`）：封装 `git check-ignore` 命令，批量检测文件是否被忽略，退出码 1（无匹配）视为正常情况返回空数组
+- `buildCleanCommands(files)`（`src/utils/validate-core.ts`）：根据冲突文件列表，按直接父目录去重生成 `git clean -fdx <dir>/` 命令
+- 消息常量：`MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT`（`src/constants/messages/validate.ts`）：双语提示，最多展示 10 个文件路径，超出部分显示总数
+
 ##### patch apply 失败后的自动 sync 流程
 
-当 patch apply 失败时，validate 不再直接退出，而是先通过 `ensureOnMainWorkBranch()` 确保主 worktree 切回主工作分支，然后通过 `handlePatchApplyFailure()` 函数进入交互流程：
+当 patch 迁移失败时（包括 patch apply 冲突和幽灵文件检测拦截两种情况），validate 不再直接退出，而是先通过 `ensureOnMainWorkBranch()` 确保主 worktree 切回主工作分支，然后通过 `handlePatchApplyFailure()` 函数进入交互流程：
 
 1. **询问用户**：提示 `是否立即执行 sync 同步主分支到 <branchName>？`
 2. **用户拒绝** → 输出提示 `请手动执行 clawt sync -b <branchName> 同步主分支后重试`，退出
@@ -170,10 +205,12 @@ git restore --staged .
 
 **实现要点：**
 
-- `migrateChangesViaPatch()`（`src/utils/validate-core.ts`）返回 `{ success: boolean }`，patch apply 失败时返回 `{ success: false }` 而非抛出异常
+- `migrateChangesViaPatch()`（`src/utils/validate-core.ts`）返回 `{ success: boolean }`，patch apply 失败或幽灵文件检测拦截时返回 `{ success: false }` 而非抛出异常
+- `detectIgnoredFilesInPatch(branchName, mainWorktreePath)`（`src/utils/validate-core.ts`）：幽灵文件检测函数，在 patch apply 之前调用，返回被 `.gitignore` 忽略且物理存在的文件列表
+- `gitCheckIgnored(paths, cwd)`（`src/utils/git-core.ts`）：封装 `git check-ignore`，批量检测文件是否被忽略规则匹配
 - `handleFirstValidate()` 和 `handleIncrementalValidate()` 为 `async` 函数，支持交互式确认
-- `handlePatchApplyFailure()`（`src/commands/validate.ts`）为异步函数，负责 patch 失败后的交互逻辑
-- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`（`src/constants/messages/validate.ts`）
+- `handlePatchApplyFailure()`（`src/commands/validate.ts`）为异步函数，负责 patch 迁移失败后的交互逻辑（含幽灵文件冲突和 patch apply 冲突两种场景）
+- 消息常量：`MESSAGES.VALIDATE_CONFIRM_AUTO_SYNC`、`MESSAGES.VALIDATE_AUTO_SYNC_START`、`MESSAGES.VALIDATE_AUTO_SYNC_DECLINED`、`MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT`（`src/constants/messages/validate.ts`）
 
 ##### 步骤 5：保存快照为 git tree 对象
 
@@ -323,7 +360,7 @@ git checkout clawt-validate-<branchName>
 
 ##### 步骤 4：从目标分支获取最新全量变更
 
-通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 4）。如果 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
+通过 patch 方式从目标分支获取最新全量变更（流程同首次 validate 的步骤 4，包含幽灵文件前置检测）。如果幽灵文件检测拦截或 patch apply 失败，同样进入自动 sync 交互流程（见首次 validate 的 [patch apply 失败后的自动 sync 流程](#patch-apply-失败后的自动-sync-流程)），validate 流程提前结束。
 
 ##### 步骤 5：检测是否有新变更
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.10.4",
+  "version": "3.10.6",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/list.ts

@@ -11,9 +11,10 @@ import {
   formatWorktreeStatus,
   isWorktreeIdle,
   printInfo,
+  formatBaseBranchInline,
 } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
-// getWorktreeStatus 和 formatWorktreeStatus 仅在文本模式下使用
+// getWorktreeStatus、formatWorktreeStatus 和 formatBaseBranchInline 仅在文本模式下使用
 
 /**
  * 注册 list 命令：列出当前项目所有 worktree
@@ -50,7 +51,7 @@ async function handleList(options: ListOptions): Promise<void> {
 }
 
 /**
- * 以 JSON 格式输出 worktree 列表（仅包含 path 和 branch）
+ * 以 JSON 格式输出 worktree 列表（包含 path、branch 和 baseBranch）
  * @param {string} projectName - 项目名称
  * @param {import('../types/index.js').WorktreeInfo[]} worktrees - worktree 列表
  */
@@ -61,6 +62,7 @@ function printListAsJson(projectName: string, worktrees: import('../types/index.
     worktrees: worktrees.map((wt) => ({
       path: wt.path,
       branch: wt.branch,
+      baseBranch: wt.baseBranch,
     })),
   };
 
@@ -87,7 +89,7 @@ function printListAsText(projectName: string, worktrees: import('../types/index.
       const isIdle = status ? isWorktreeIdle(status) : false;
       const pathDisplay = isIdle ? chalk.hex('#FF8C00')(wt.path) : wt.path;
 
-      printInfo(`  ${pathDisplay}   [${wt.branch}]`);
+      printInfo(`  ${pathDisplay}   [${wt.branch}]   ${formatBaseBranchInline(wt.baseBranch)}`);
 
       if (status) {
         printInfo(`    ${formatWorktreeStatus(status)}`);

package/src/commands/merge.ts

@@ -155,7 +155,7 @@ async function shouldCleanupAfterMerge(branchName: string): Promise<boolean> {
  * @param {string} branchName - 分支名
  */
 function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): void {
-  cleanupWorktrees([{ path: worktreePath, branch: branchName }]);
+  cleanupWorktrees([{ path: worktreePath, branch: branchName, baseBranch: null }]);
   printSuccess(MESSAGES.WORKTREE_CLEANED(branchName));
 }
 

package/src/commands/remove.ts

@@ -24,6 +24,7 @@ import {
   getValidateBranchName,
   deleteValidateBranch,
   getCurrentBranch,
+  removeWorktreeMetadata,
 } from '../utils/index.js';
 import type { WorktreeMultiResolveMessages } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
@@ -120,6 +121,8 @@ async function handleRemove(options: RemoveOptions): Promise<void> {
       deleteValidateBranch(wt.branch);
       // 清理该分支对应的 validate 快照
       removeSnapshot(projectName, wt.branch);
+      // 清理该分支的来源分支元数据
+      removeWorktreeMetadata(projectName, wt.branch);
       printSuccess(MESSAGES.WORKTREE_REMOVED(wt.path));
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);

package/src/commands/status.ts

@@ -23,6 +23,7 @@ import {
   InteractivePanel,
   loadProjectConfig,
   checkBranchExists,
+  formatBaseBranchLine,
 } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
 
@@ -141,6 +142,7 @@ async function collectWorktreeDetailedStatusAsync(worktree: WorktreeInfo, projec
     insertions: diffStat.insertions,
     deletions: diffStat.deletions,
     createdAt,
+    baseBranch: worktree.baseBranch,
   };
 }
 
@@ -362,6 +364,9 @@ function printWorktreeItem(wt: WorktreeDetailedStatus): void {
     printInfo(`    ${chalk.green(lang === 'en' ? 'In sync with main' : '与主分支同步')}`);
   }
 
+  // 来源分支
+  printInfo(`    ${chalk.gray(formatBaseBranchLine(wt.baseBranch))}`);
+
   // 分支创建时间
   if (wt.createdAt) {
     const relativeTime = formatRelativeTime(wt.createdAt);

package/src/constants/messages/validate.ts

@@ -40,6 +40,23 @@ const VALIDATE_MESSAGES_I18N = {
     'zh-CN': (branch: string) =>
       `变更迁移失败：目标分支与主分支差异过大\n  请先执行 clawt sync -b ${branch} 同步主分支后重试`,
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...(${files.length} files total)` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `Ignored files left in main worktree are blocking patch apply:\n${displayed}${more}\n\nPlease clean up manually and retry:\n${cmds}`;
+    },
+    'zh-CN': (files: string[], cleanCommands: string[]) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map(f => `  - ${f}`).join('\n');
+      const more = files.length > maxDisplay ? `\n  ...（共 ${files.length} 个文件）` : '';
+      const cmds = cleanCommands.map(c => `  ${c}`).join('\n');
+      return `检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：\n${displayed}${more}\n\n请手动清理后重试：\n${cmds}`;
+    },
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: 'No worktrees available, please create one with clawt run or clawt create first',

package/src/types/status.ts

@@ -18,6 +18,8 @@ export interface WorktreeDetailedStatus {
   deletions: number;
   /** 分支创建时间（首次分叉提交的 ISO 8601 时间字符串），无分叉提交时为 null */
   createdAt: string | null;
+  /** 创建 worktree 时所在的来源分支，无元数据时为 null */
+  baseBranch: string | null;
 }
 
 /** 主 worktree 状态信息 */

package/src/types/worktree.ts

@@ -1,9 +1,21 @@
+/** worktree 来源分支元数据 */
+export interface WorktreeMetadata {
+  /** worktree 分支名 */
+  branch: string;
+  /** 创建 worktree 时所在的真实当前分支 */
+  baseBranch: string;
+  /** 元数据创建时间 */
+  createdAt: string;
+}
+
 /** worktree 信息 */
 export interface WorktreeInfo {
   /** worktree 路径 */
   path: string;
   /** 分支名 */
   branch: string;
+  /** 创建 worktree 时所在的来源分支，无元数据时为 undefined 或 null */
+  baseBranch?: string | null;
 }
 
 /** worktree 变更统计信息 */

package/src/utils/formatter.ts

@@ -245,6 +245,28 @@ export function formatLocalISOString(date: Date): string {
   return `${iso}${sign}${hours}:${minutes}`;
 }
 
+/**
+ * 格式化来源分支展示行（用于 status 文本输出和交互面板）
+ * @param {string | null | undefined} baseBranch - 来源分支
+ * @returns {string} 格式化的来源分支文本，如 "来源分支: test" 或 "来源分支: 未记录"
+ */
+export function formatBaseBranchLine(baseBranch: string | null | undefined): string {
+  const lang = getCurrentLanguage();
+  const label = lang === 'en' ? 'Base branch' : '来源分支';
+  const fallback = lang === 'en' ? 'Not recorded' : '未记录';
+  return `${label}: ${baseBranch ?? fallback}`;
+}
+
+/**
+ * 格式化来源分支内联展示（用于 list 文本输出）
+ * @param {string | null | undefined} baseBranch - 来源分支
+ * @returns {string} 格式化的来源分支内联文本，如 "<- test" 或 "<- 未记录"
+ */
+export function formatBaseBranchInline(baseBranch: string | null | undefined): string {
+  const fallback = getCurrentLanguage() === 'en' ? 'Not recorded' : '未记录';
+  return `<- ${baseBranch ?? fallback}`;
+}
+
 /**
  * 生成任务模板文件名，格式：clawt-tasks-YYYY-MM-DD-HH-mm-ss.md
  * @param {string} prefix - 文件名前缀

package/src/utils/git-core.ts

@@ -498,3 +498,26 @@ export function gitMergeAbort(cwd?: string): void {
 export function buildAutoSaveCommitMessage(mainBranch: string, branch: string): string {
   return `${AUTO_SAVE_COMMIT_MESSAGE_PREFIX} ${mainBranch} into ${branch}`;
 }
+
+/**
+ * 批量检测文件是否被 .gitignore 忽略
+ * 使用 git check-ignore 命令，退出码 1 表示无匹配（非错误）
+ * @param {string[]} paths - 要检测的文件路径列表
+ * @param {string} [cwd] - 工作目录
+ * @returns {string[]} 被忽略的文件路径列表
+ */
+export function gitCheckIgnored(paths: string[], cwd?: string): string[] {
+  if (paths.length === 0) return [];
+
+  try {
+    const output = execFileSync('git', ['check-ignore', '--', ...paths], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    // git check-ignore 退出码 1 表示无匹配文件，属于正常情况
+    return [];
+  }
+}

package/src/utils/index.ts

@@ -63,18 +63,20 @@ export {
   gitMergeAbort,
   buildAutoSaveCommitMessage,
   throwIfGitIndexLockError,
+  gitCheckIgnored,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, validateWorkingDirClean, runPreChecks } from './validation.js';
 export type { PreCheckOptions } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
-export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString, generateTaskFilename } from './formatter.js';
+export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString, generateTaskFilename, formatBaseBranchLine, formatBaseBranchInline } from './formatter.js';
 export { ensureDir, removeEmptyDir, calculateDirSize } from './fs.js';
 export { removeExternalSymlinks } from './symlink-guard.js';
 export { multilineInput, promptCommitMessage } 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 { removeWorktreeMetadata } from './worktree-metadata.js';
 export { findExactMatch, findFuzzyMatches, promptGroupedMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees, groupWorktreesByDate, buildGroupedChoices, buildGroupMembershipMap, formatRelativeDate, getWorktreeCreatedDate, getWorktreeCreatedTime } from './worktree-matcher.js';
 export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './worktree-matcher.js';
 export { ProgressRenderer } from './progress.js';
@@ -92,7 +94,7 @@ export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebu
 export { safeStringify } from './json.js';
 export { isNonInteractive, setNonInteractive } from './interactive.js';
 export { executeRunCommand } from './validate-runner.js';
-export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch } from './validate-core.js';
+export { migrateChangesViaPatch, computeCurrentTreeHash, saveCurrentSnapshotTree, loadOldSnapshotToStage, switchToValidateBranch, detectIgnoredFilesInPatch } 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/interactive-panel-render.ts

@@ -30,7 +30,7 @@ import {
   PANEL_COMMITS_BEHIND,
 } from '../constants/messages/index.js';
 import type { StatusResult, WorktreeDetailedStatus, MainWorktreeStatus } from '../types/index.js';
-import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate } from './index.js';
+import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate, formatBaseBranchLine } from './index.js';
 
 /** 面板行类型 */
 export interface PanelLine {
@@ -136,7 +136,7 @@ export function buildPanelFrame(
  * @returns {number[]} 按显示顺序排列的原始索引数组
  */
 export function buildDisplayOrder(worktrees: WorktreeDetailedStatus[]): number[] {
-  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch }));
+  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch, baseBranch: wt.baseBranch }));
   const groups = groupWorktreesByDate(worktreeInfos);
 
   // 构建分支名到原始索引的映射
@@ -164,7 +164,7 @@ export function buildGroupedWorktreeLines(worktrees: WorktreeDetailedStatus[], s
   const panelLines: PanelLine[] = [];
 
   // 构建临时 WorktreeInfo 兼容结构用于分组（groupWorktreesByDate 需要 path 字段）
-  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch }));
+  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch, baseBranch: wt.baseBranch }));
   const groups = groupWorktreesByDate(worktreeInfos);
 
   // 构建分支名到原始索引的映射
@@ -259,6 +259,9 @@ export function renderWorktreeBlock(wt: WorktreeDetailedStatus, isSelected: bool
     lines.push(`${indent}${chalk.green(PANEL_SYNCED_WITH_MAIN)}`);
   }
 
+  // 来源分支
+  lines.push(`${indent}${chalk.gray(formatBaseBranchLine(wt.baseBranch))}`);
+
   // 分支创建时间
   if (wt.createdAt) {
     const relativeTime = formatRelativeTime(wt.createdAt);

package/src/utils/validate-core.ts

@@ -2,6 +2,8 @@ import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import { getCurrentLanguage } from './i18n.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   gitAddAll,
   gitCommit,
@@ -22,8 +24,26 @@ import {
   getHeadCommitHash,
   writeSnapshot,
   printWarning,
+  gitCheckIgnored,
+  execCommand,
 } from './index.js';
 
+/**
+ * 根据冲突文件列表生成 git clean 清理命令
+ * 按直接父目录去重，生成针对性的清理命令
+ * @param {string[]} files - 冲突文件的相对路径列表
+ * @returns {string[]} 清理命令列表
+ */
+function buildCleanCommands(files: string[]): string[] {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    const lastSlash = file.lastIndexOf('/');
+    const dir = lastSlash > 0 ? file.substring(0, lastSlash) : '.';
+    dirs.add(dir);
+  }
+  return Array.from(dirs).map(dir => `git clean -fdx ${dir}/`);
+}
+
 /**
  * 通过 patch 将目标分支的全量变更（已提交 + 未提交）迁移到主 worktree
  * 使用 git diff HEAD...branch --binary 获取变更，避免 stash 方式无法检测已提交 commit 的问题
@@ -44,6 +64,16 @@ export function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreeP
       didTempCommit = true;
     }
 
+    // 先执行轻量检测：检测被 .gitignore 忽略的残留文件（幽灵文件），在 apply 之前拦截
+    // 使用 --name-only 远比 --binary 便宜，检测到冲突时可跳过昂贵的 binary diff
+    const ignoredFiles = detectIgnoredFilesInPatch(branchName, mainWorktreePath);
+    if (ignoredFiles.length > 0) {
+      const cleanCommands = buildCleanCommands(ignoredFiles);
+      logger.warn(`检测到 ${ignoredFiles.length} 个被忽略的残留文件冲突`);
+      printWarning(MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT(ignoredFiles, cleanCommands));
+      return { success: false };
+    }
+
     // 在主 worktree 执行三点 diff，获取目标分支自分叉点以来的全量变更
     const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
 
@@ -173,3 +203,25 @@ export function switchToValidateBranch(branchName: string, mainWorktreePath: str
   }
   return validateBranchName;
 }
+
+/**
+ * 检测 patch 中被 .gitignore 忽略且物理存在于主 worktree 的文件（幽灵文件）
+ * 这些文件会导致 git apply 失败（"已经存在于工作区中"）
+ * @param {string} branchName - 目标分支名
+ * @param {string} mainWorktreePath - 主 worktree 路径
+ * @returns {string[]} 幽灵文件的相对路径列表
+ */
+export function detectIgnoredFilesInPatch(branchName: string, mainWorktreePath: string): string[] {
+  try {
+    const output = execCommand(`git diff --name-only HEAD...${branchName}`, { cwd: mainWorktreePath });
+    const patchFiles = output.split('\n').filter(Boolean);
+    if (patchFiles.length === 0) return [];
+
+    // 筛选被 .gitignore 忽略且物理存在的文件（幽灵文件）
+    return gitCheckIgnored(patchFiles, mainWorktreePath)
+      .filter(file => existsSync(join(mainWorktreePath, file)));
+  } catch {
+    // diff 失败时跳过检测，降级为当前行为（让 apply 自行报错）
+    return [];
+  }
+}

package/src/utils/worktree-metadata.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PROJECTS_CONFIG_DIR } from '../constants/index.js';
+import { safeStringify } from './json.js';
+import { ensureDir } from './fs.js';
+import { logger } from '../logger/index.js';
+import type { WorktreeMetadata } from '../types/worktree.js';
+
+/**
+ * 获取 worktree 元数据文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} 元数据文件路径
+ */
+export function getWorktreeMetadataPath(projectName: string, branchName: string): string {
+  return join(PROJECTS_CONFIG_DIR, projectName, 'worktrees', `${branchName}.json`);
+}
+
+/**
+ * 保存 worktree 来源分支元数据
+ * @param {string} projectName - 项目名
+ * @param {WorktreeMetadata} metadata - 元数据
+ */
+export function saveWorktreeMetadata(projectName: string, metadata: WorktreeMetadata): void {
+  const metadataPath = getWorktreeMetadataPath(projectName, metadata.branch);
+  const metadataDir = dirname(metadataPath);
+
+  try {
+    ensureDir(metadataDir);
+    writeFileSync(metadataPath, safeStringify(metadata), 'utf-8');
+  } catch (error) {
+    logger.error(`保存 worktree 元数据失败: ${metadataPath}`, error);
+    throw error;
+  }
+}
+
+/**
+ * 读取 worktree 来源分支元数据
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {WorktreeMetadata | null} 元数据，不存在或解析失败时返回 null
+ */
+export function loadWorktreeMetadata(projectName: string, branchName: string): WorktreeMetadata | null {
+  const metadataPath = getWorktreeMetadataPath(projectName, branchName);
+
+  if (!existsSync(metadataPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(metadataPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    // 校验必要字段，防止不安全的类型断言
+    if (!parsed || typeof parsed !== 'object' || !parsed.branch || !parsed.baseBranch) {
+      logger.warn(`worktree 元数据格式无效: ${metadataPath}`);
+      return null;
+    }
+    return parsed as WorktreeMetadata;
+  } catch (error) {
+    logger.warn(`解析 worktree 元数据失败: ${metadataPath}`, error);
+    return null;
+  }
+}
+
+/**
+ * 删除 worktree 来源分支元数据
+ *
+ * 删除失败时仅记录日志，不抛出异常（best-effort 语义）。
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+export function removeWorktreeMetadata(projectName: string, branchName: string): void {
+  const metadataPath = getWorktreeMetadataPath(projectName, branchName);
+
+  try {
+    if (existsSync(metadataPath)) {
+      rmSync(metadataPath);
+    }
+  } catch (error) {
+    logger.error(`删除 worktree 元数据失败: ${metadataPath}`, error);
+  }
+}

package/src/utils/worktree.ts

@@ -6,6 +6,8 @@ import { createWorktree as gitCreateWorktree, getProjectName, gitWorktreeList, r
 import { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 import { ensureDir, removeEmptyDir } from './fs.js';
 import { createValidateBranch, deleteValidateBranch } from './validate-branch.js';
+import { getCurrentBranch } from './git-branch.js';
+import { saveWorktreeMetadata, loadWorktreeMetadata, removeWorktreeMetadata } from './worktree-metadata.js';
 import type { WorktreeInfo, WorktreeStatus } from '../types/index.js';
 
 /**
@@ -34,17 +36,22 @@ export function createWorktrees(branchName: string, count: number): WorktreeInfo
   // 3. 校验所有分支是否都不存在（在创建任何 worktree 之前）
   validateBranchesNotExist(branchNames);
 
-  // 4. 确保项目 worktree 目录存在
-  const projectDir = getProjectWorktreeDir();
+  // 4. 获取项目名并确保 worktree 目录存在
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
   ensureDir(projectDir);
 
-  // 5. 串行创建 worktree 及对应验证分支
+  // 5. 记录当前分支作为来源分支
+  const baseBranch = getCurrentBranch();
+
+  // 6. 串行创建 worktree 及对应验证分支，并保存元数据
   const results: WorktreeInfo[] = [];
   for (const name of branchNames) {
     const worktreePath = join(projectDir, name);
     gitCreateWorktree(name, worktreePath);
     createValidateBranch(name);
-    results.push({ path: worktreePath, branch: name });
+    saveWorktreeMetadata(projectName, { branch: name, baseBranch, createdAt: new Date().toISOString() });
+    results.push({ path: worktreePath, branch: name, baseBranch });
     logger.info(`worktree 创建完成: ${worktreePath} (分支: ${name})`);
   }
 
@@ -62,17 +69,22 @@ export function createWorktreesByBranches(branchNames: string[]): WorktreeInfo[]
   // 1. 校验所有分支是否都不存在
   validateBranchesNotExist(branchNames);
 
-  // 2. 确保项目 worktree 目录存在
-  const projectDir = getProjectWorktreeDir();
+  // 2. 获取项目名并确保 worktree 目录存在
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
   ensureDir(projectDir);
 
-  // 3. 串行创建 worktree 及对应验证分支
+  // 3. 记录当前分支作为来源分支
+  const baseBranch = getCurrentBranch();
+
+  // 4. 串行创建 worktree 及对应验证分支，并保存元数据
   const results: WorktreeInfo[] = [];
   for (const name of branchNames) {
     const worktreePath = join(projectDir, name);
     gitCreateWorktree(name, worktreePath);
     createValidateBranch(name);
-    results.push({ path: worktreePath, branch: name });
+    saveWorktreeMetadata(projectName, { branch: name, baseBranch, createdAt: new Date().toISOString() });
+    results.push({ path: worktreePath, branch: name, baseBranch });
     logger.info(`worktree 创建完成: ${worktreePath} (分支: ${name})`);
   }
 
@@ -85,7 +97,8 @@ export function createWorktreesByBranches(branchNames: string[]): WorktreeInfo[]
  * @returns {WorktreeInfo[]} 有效的 worktree 列表
  */
 export function getProjectWorktrees(): WorktreeInfo[] {
-  const projectDir = getProjectWorktreeDir();
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
 
   if (!existsSync(projectDir)) {
     return [];
@@ -107,9 +120,12 @@ export function getProjectWorktrees(): WorktreeInfo[] {
     const fullPath = join(projectDir, entry.name);
     // 交叉验证：路径必须在 git worktree list 中
     if (registeredPaths.has(fullPath)) {
+      // 读取来源分支元数据，无元数据时 baseBranch 为 null
+      const metadata = loadWorktreeMetadata(projectName, entry.name);
       worktrees.push({
         path: fullPath,
         branch: entry.name,
+        baseBranch: metadata?.baseBranch ?? null,
       });
     }
   }
@@ -122,18 +138,21 @@ export function getProjectWorktrees(): WorktreeInfo[] {
  * @param {WorktreeInfo[]} worktrees - 待清理的 worktree 列表
  */
 export function cleanupWorktrees(worktrees: WorktreeInfo[]): void {
+  const projectName = getProjectName();
   for (const wt of worktrees) {
     try {
       removeWorktreeByPath(wt.path);
       deleteBranch(wt.branch);
       deleteValidateBranch(wt.branch);
+      // 删除来源分支元数据
+      removeWorktreeMetadata(projectName, wt.branch);
       logger.info(`已清理 worktree 和分支: ${wt.branch}`);
     } catch (error) {
       logger.error(`清理 worktree 失败: ${wt.path} - ${error}`);
     }
   }
   gitWorktreePrune();
-  const projectDir = getProjectWorktreeDir();
+  const projectDir = join(WORKTREES_DIR, projectName);
   removeEmptyDir(projectDir);
 }
 

package/tests/helpers/fixtures.ts

@@ -9,6 +9,7 @@ export function createWorktreeInfo(overrides: Partial<WorktreeInfo> = {}): Workt
   return {
     path: '/Users/test/.clawt/worktrees/my-project/feature-branch',
     branch: 'feature-branch',
+    baseBranch: null,
     ...overrides,
   };
 }