sillyspec 3.11.8 → 3.11.9

package/src/stages/execute.js

@@ -47,6 +47,24 @@ const fixedPrefix = [
     outputHint: '上下文摘要',
     optional: false
   },
+  {
+    name: '创建 worktree',
+    prompt: `为本次执行创建隔离的 git worktree。
+
+### 操作
+1. 运行 \`sillyspec worktree create <change-name>\`
+2. 记录输出的 worktree 路径
+3. 后续所有子代理的 cwd 设为该 worktree 路径
+4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+
+### 输出
+worktree 路径 + 分支名
+
+### 完成后执行
+sillyspec run execute --done --output "worktree 路径 + 分支名"`,
+    outputHint: 'worktree 路径 + 分支名',
+    optional: false
+  },
   {
     name: '确认执行范围',
     prompt: `解析任务，确认执行范围和确认模式。
@@ -149,7 +167,7 @@ const fixedSuffix = [
     prompt: `检查本轮执行产生的新知识。
 
 ### 操作
-1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
+1. 检查 \.sillyspec/knowledge/uncategorized.md\` 中待确认条目
 2. 如有 → 提示用户审阅
 3. 用户确认后改为 [已确认]，可归类到专题文件
 
@@ -162,18 +180,29 @@ const fixedSuffix = [
     name: '完成确认',
     prompt: `所有任务完成后的收尾。
 
-### 操作
-1. 建议下一步：
-   - 运行 \`sillyspec run verify\` 进行验证（验证通过后才能归档）
-   - 如果发现问题需要修复，先修复再验证
-   - 用户也可以选择继续开发（不验证）
+### 操作（有 worktree）
+1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
+2. 展示 diff 摘要（文件列表 + 变更统计）
+3. 检查结果说明（是否通过文件清单校验）
+4. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
+5. apply 成功 → 自动 cleanup
+6. apply 失败 → 展示错误详情，用户选择重试或手动处理
+7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <change-name>\` 丢弃
+8. 建议下一步：\`sillyspec run verify\`
+
+### 操作（无 worktree / --no-worktree 模式）
+1. 跳过 apply 和 cleanup 步骤（因为没有 worktree）
+2. 展示本次执行摘要
+3. 提示用户直接使用 \`git diff\` 查看变更
+4. 建议下一步：\`sillyspec run verify\`
 
 ### 输出
-用户选择 + 下一步命令
+apply 结果 + 下一步建议（或执行摘要）
 
 ### 注意
+- 如果用户不想 apply → 运行 cleanup 丢弃
 - 完成后运行 \`sillyspec run execute --done\` 即可自动推进阶段`,
-    outputHint: '用户选择',
+    outputHint: 'apply 结果',
     optional: false
   }
 ]
@@ -242,7 +271,7 @@ function parseWavesFromPlan(planContent) {
 /**
  * 为 Wave 生成 prompt（强制子代理执行）
  */
-function buildWavePrompt(wave, waveIndex, changeDir) {
+function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
@@ -260,6 +289,17 @@ function buildWavePrompt(wave, waveIndex, changeDir) {
     return s
   }).join('\n')
 
+  const worktreeSection = (worktreePath)
+    ? `
+### 工作目录
+你必须在以下 worktree 中工作（子代理的 cwd 设为此路径）：
+\`${worktreePath}\`
+
+不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+子代理的 cwd 参数设为 \`${worktreePath}\`。
+`
+    : ''
+
   return `## Wave ${waveIndex}: 执行以下任务
 
 ## 执行方式（必须严格遵守）
@@ -272,6 +312,7 @@ function buildWavePrompt(wave, waveIndex, changeDir) {
 3. 勾选 plan.md 中的 checkbox
 4. 记录改动文件和测试结果
 
+${worktreeSection}
 ### 任务摘要（按需读取完整蓝图）
 为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
 
@@ -315,9 +356,11 @@ ${taskList}
 /**
  * 动态构建 execute 步骤列表
  * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave
+ * @param {{ worktreePath?: string, noWorktree?: boolean }} options
  * @returns {Array} 步骤列表
  */
-export function buildExecuteSteps(planFilePath = null) {
+export function buildExecuteSteps(planFilePath = null, options = {}) {
+  const noWorktree = !!options.noWorktree
   let waves
   let changeDir = null
 
@@ -336,10 +379,13 @@ export function buildExecuteSteps(planFilePath = null) {
     }
   }
 
+  // 尝试获取 worktree 路径（可能由前缀步骤创建）
+  const worktreePath = options.worktreePath || null
+
   const waveSteps = waves.map((wave, i) => ({
     name: `Wave ${i + 1} 执行`,
     mode: 'implementation',
-    prompt: buildWavePrompt(wave, i + 1, changeDir),
+    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath),
     outputHint: `Wave ${i + 1} 执行结果`,
     optional: false
   }))

package/src/stages/quick.js

@@ -20,7 +20,7 @@ export const definition = {
 ### 创建任务记录（必须执行）
 理解完任务后，立即创建记录文件：
 1. \`git config user.name\` 获取用户名
-2. 无 \`--change\`：创建 \.sillyspec/quicklog/QUICKLOG-<git用户名>.md\`（已存在则追加），写入：
+2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-<git用户名>.md\`（已存在则追加），写入：
    \`\`\`
    ## YYYY-MM-DD HH:mm:ss — <一句话任务描述>
    状态：进行中
@@ -28,19 +28,40 @@ export const definition = {
    \`\`\`
 3. 有 \`--change\`：在 \`.sillyspec/changes/<change-name>/tasks.md\` 追加未勾选的 task
 
-这样 Gate 检测到 \.sillyspec/\` 下有变更，就不会拦截后续的代码修改。
+这样 Gate 检测到 .sillyspec/\` 下有变更，就不会拦截后续的代码修改。
 
 ### 输出
 任务理解 + 上下文摘要 + quicklog 已创建`,
       outputHint: '任务理解',
       optional: false
     },
+    {
+      name: '创建 worktree',
+      prompt: `为本次 quick 任务创建隔离的 git worktree。
+
+### 操作
+1. 确定变更名（change name）：
+   - 如携带 \`--change <变更名>\`，使用该变更名
+   - 否则，生成临时变更名：\`quick-<当前时间戳 YYYYMMDD-HHmmss>\`
+2. 运行 \`sillyspec worktree create <变更名>\`
+3. 记录输出的 worktree 路径（后续步骤需要使用）
+4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+
+### 输出
+worktree 路径 + 变更名 + 分支名`,
+      outputHint: 'worktree 路径',
+      optional: false
+    },
     {
       name: '实现并验证',
       prompt: `实现任务。
 
+### 工作目录
+你必须在 worktree 中工作（将子代理的 cwd 设为上一步记录的 worktree 路径）。
+不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+
 ### 操作
-1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在
+1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在（在 worktree 中读取）
 2. 写代码完成任务
 3. 如涉及逻辑变更，建议写单元测试验证（不强制，纯配置/文档/小改动可跳过）
 4. **不要编译！** 除非用户明确要求或改动量很大
@@ -55,6 +76,24 @@ export const definition = {
       outputHint: '实现摘要',
       optional: false
     },
+    {
+      name: 'apply 并 cleanup',
+      prompt: `将 worktree 中的变更应用到主工作区并清理。
+
+### 操作
+1. 运行 \`sillyspec worktree apply --check-only <变更名>\`
+2. 展示 diff 摘要（文件列表 + 变更统计）
+3. 展示检查结果（是否通过文件清单校验）
+4. 用户确认后运行 \`sillyspec worktree apply <变更名>\`
+5. apply 成功 → 自动 cleanup，进入下一步
+6. apply 失败 → 展示错误详情，用户选择重试或手动处理
+7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <变更名>\` 丢弃变更
+
+### 输出
+apply 结果 + 下一步建议`,
+      outputHint: 'apply 结果',
+      optional: false
+    },
     {
       name: '暂存和更新记录',
       prompt: `Git 暂存并更新任务记录。

package/src/worktree-apply.js

@@ -0,0 +1,266 @@
+/**
+ * SillySpec applyWorktree — 将 worktree 中的变更应用到主工作区
+ *
+ * 流程：
+ * 1. 读取 meta.json 获取 baseHash
+ * 2. git diff --name-only baseHash 获取 worktree 中所有变更文件
+ * 3. 从 design.md 解析文件变更清单（无清单 = 允许所有）
+ * 4. 校验：变更文件 ⊆ 清单
+ * 5. 校验：主工作区文件 base hash 一致
+ * 6. --check-only 模式只输出检查结果
+ * 7. 非 checkOnly：生成 patch → apply --check → apply --3way
+ * 8. 成功后自动 cleanup
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { WorktreeManager } from './worktree.js';
+import { parseFileChangeList } from './change-list.js';
+
+const CHANGES_REL = '.sillyspec/changes';
+
+function git(cwd, args) {
+  return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function gitQuiet(cwd, args) {
+  try {
+    return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 获取文件在 git 中的 blob hash（基于某个 commit/tree）
+ * @param {string} cwd - git 工作区路径
+ * @param {string} treeish - commit hash、分支等
+ * @param {string} filePath - 相对路径
+ * @returns {string|null} blob hash，文件不存在返回 null
+ */
+function getFileBlobHash(cwd, treeish, filePath) {
+  return gitQuiet(cwd, `rev-parse ${treeish}:${filePath}`);
+}
+
+/**
+ * apply worktree 变更到主工作区
+ *
+ * @param {string} changeName - 变更名
+ * @param {{ cwd?: string, checkOnly?: boolean }} opts
+ * @returns {{
+ *   ok: boolean,
+ *   changedFiles: string[],
+ *   extraFiles: string[],
+ *   hashMismatchFiles: string[],
+ *   patchPath: string|null,
+ *   errors: string[]
+ * }}
+ */
+export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
+  const projectRoot = cwd || process.cwd();
+  const wm = new WorktreeManager({ cwd: projectRoot });
+  const meta = wm.getMeta(changeName);
+  const result = {
+    ok: false,
+    changedFiles: [],
+    extraFiles: [],
+    hashMismatchFiles: [],
+    patchPath: null,
+    errors: [],
+  };
+
+  // --- 1. 校验 worktree 存在 + meta.json 有效 ---
+  if (!meta) {
+    result.errors.push(`worktree not found: ${changeName}。meta.json 不存在或已损坏。`);
+    return result;
+  }
+
+  const { worktreePath, baseHash } = meta;
+
+  if (!existsSync(worktreePath)) {
+    result.errors.push(`worktree 目录不存在: ${worktreePath}`);
+    return result;
+  }
+
+  // --- 2. 获取变更文件列表 ---
+  // worktree 内修改可能没有 commit，用 git diff <baseHash>（比较 baseHash 到工作区内容）
+  // 同时检测 untracked 新文件（git diff 不包含 untracked）
+  let changedFiles;
+  try {
+    // tracked 文件的变更（modified/deleted）
+    const trackedRaw = git(worktreePath, `diff --name-only ${baseHash}`);
+    const trackedFiles = trackedRaw ? trackedRaw.split('\n').filter(Boolean) : [];
+
+    // untracked 新文件（baseHash 中不存在的文件）
+    const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`);
+    const untrackedFiles = untrackedRaw
+      ? untrackedRaw.split('\n').filter(Boolean).filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json')
+      : [];
+
+    changedFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+  } catch (e) {
+    result.errors.push(`获取变更文件列表失败: ${e.message}`);
+    return result;
+  }
+
+  result.changedFiles = changedFiles;
+
+  if (changedFiles.length === 0) {
+    // 没有变更
+    if (!checkOnly) {
+      wm.cleanup(changeName);
+    }
+    result.ok = true;
+    return result;
+  }
+
+  // --- 3. 解析 design.md 文件变更清单 ---
+  const designPath = join(projectRoot, CHANGES_REL, changeName, 'design.md');
+  const allowSet = parseFileChangeList(designPath);
+  const hasAllowList = allowSet.size > 0;
+
+  // --- 4. 校验：变更文件 ⊆ 清单（无清单则跳过）---
+  if (hasAllowList) {
+    for (const f of changedFiles) {
+      if (!allowSet.has(f)) {
+        result.extraFiles.push(f);
+      }
+    }
+    if (result.extraFiles.length > 0) {
+      result.errors.push(
+        `文件清单校验失败：以下变更文件不在 design.md 清单中：\n  ${result.extraFiles.join('\n  ')}`
+      );
+      return result;
+    }
+  }
+
+  // --- 5. 校验：主工作区文件 base hash 一致 ---
+  // 5a. 检查主工作区是否有未 commit 的脏文件（会影响 apply）
+  const mainDirtyRaw = gitQuiet(projectRoot, 'diff --name-only HEAD');
+  const mainDirtyFiles = mainDirtyRaw ? mainDirtyRaw.split('\n').filter(Boolean) : [];
+  if (mainDirtyFiles.length > 0) {
+    // 如果脏文件和本次 apply 的文件有交集 → 报错
+    const conflictDirty = mainDirtyFiles.filter(f => changedFiles.includes(f));
+    if (conflictDirty.length > 0) {
+      result.errors.push(
+        `主工作区有以下未 commit 的变更，会影响 apply：\n  ${conflictDirty.join('\n  ')}\n请先 commit 或 stash 这些变更。`
+      );
+      return result;
+    }
+  }
+
+  // 5b. 对比 worktree 的 baseHash 和主工作区 HEAD 中每个清单文件的 blob hash
+  const targetFiles = hasAllowList ? [...allowSet] : changedFiles;
+  for (const f of targetFiles) {
+    const wtBlob = getFileBlobHash(worktreePath, baseHash, f);
+    const mainBlob = getFileBlobHash(projectRoot, 'HEAD', f);
+
+    // 两者都为 null（文件在 base 时不存在）→ OK
+    if (wtBlob === null && mainBlob === null) continue;
+    // 两者一致 → OK
+    if (wtBlob === mainBlob) continue;
+    // 不一致 → 主工作区已被修改
+    result.hashMismatchFiles.push(f);
+  }
+
+  if (result.hashMismatchFiles.length > 0) {
+    result.errors.push(
+      `base hash 不一致：以下文件在主工作区已被修改：\n  ${result.hashMismatchFiles.join('\n  ')}`
+    );
+    return result;
+  }
+
+  // --- 6. checkOnly 模式：到此返回 ---
+  if (checkOnly) {
+    result.ok = true;
+    return result;
+  }
+
+  // --- 7. 生成 patch 并 apply ---
+  // 确定要包含在 patch 中的文件：有清单用清单交集，无清单用全部变更
+  const patchFiles = hasAllowList
+    ? [...allowSet].filter(f => changedFiles.includes(f))
+    : changedFiles;
+  const fileArgs = patchFiles.map(f => `-- ${f}`).join(' ');
+
+  // 创建临时文件
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-patch-'));
+  const patchPath = join(tmpDir, 'apply.patch');
+  result.patchPath = patchPath;
+
+  try {
+    let patchContent = '';
+
+    // 分 tracked 变更和 untracked 新文件生成 patch
+    const trackedFiles = patchFiles.filter(f => {
+      // untracked 文件在 baseHash 的 tree 中不存在
+      return gitQuiet(worktreePath, `cat-file -e ${baseHash}:${f}`) !== null;
+    });
+    const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+
+    // tracked 文件：git diff baseHash
+    if (trackedFiles.length > 0) {
+      const trackedArgs = trackedFiles.map(f => `-- ${f}`).join(' ');
+      patchContent += execSync(
+        `git diff --binary ${baseHash} ${trackedArgs}`,
+        { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+    }
+
+    // untracked 新文件：git add 到 index，git diff --cached，然后 reset
+    if (untrackedPatchFiles.length > 0) {
+      const addArgs = untrackedPatchFiles.map(f => `-- ${f}`).join(' ');
+      git(worktreePath, `add ${addArgs}`);
+      try {
+        patchContent += execSync(
+          `git diff --binary --cached ${untrackedPatchFiles.map(f => `-- ${f}`).join(' ')}`,
+          { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+      } finally {
+        // 重置 index（不保留 staged 状态）
+        gitQuiet(worktreePath, `reset HEAD -- ${addArgs}`);
+      }
+    }
+
+    if (!patchContent.trim()) {
+      // patch 为空（清单中部分文件可能没实际变更）
+      result.ok = true;
+      rmSync(tmpDir, { recursive: true, force: true });
+      return result;
+    }
+
+    writeFileSync(patchPath, patchContent);
+
+    // apply --check 预检
+    try {
+      git(projectRoot, `apply --check ${patchPath}`);
+    } catch (e) {
+      result.errors.push(`patch 预检失败: ${e.message}`);
+      return result;
+    }
+
+    // apply --3way 正式应用
+    try {
+      git(projectRoot, `apply --3way ${patchPath}`);
+    } catch (e) {
+      result.errors.push(`patch apply 失败: ${e.message}`);
+      return result;
+    }
+
+    result.ok = true;
+
+    // --- 8. 成功后自动 cleanup ---
+    wm.cleanup(changeName);
+
+  } catch (e) {
+    result.errors.push(`patch 生成/应用异常: ${e.message}`);
+    return result;
+  } finally {
+    // 清理临时目录
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  }
+
+  return result;
+}

package/src/worktree.js

@@ -0,0 +1,226 @@
+/**
+ * SillySpec WorktreeManager — git worktree 生命周期管理
+ *
+ * 封装 git worktree 的 create/list/cleanup/getMeta 操作，
+ * 为 execute 阶段提供代码隔离环境。
+ *
+ * worktree 存储目录：.sillyspec/.runtime/worktrees/<change-name>/
+ * 分支命名：sillyspec/<change-name>
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+
+const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
+const BRANCH_PREFIX = 'sillyspec/';
+const META_FILE = 'meta.json';
+
+function git(cwd, args) {
+  return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function gitQuiet(cwd, args) {
+  try {
+    return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function parseJSON(raw) {
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function validateChangeName(changeName) {
+  if (!changeName || typeof changeName !== 'string' || changeName.trim() === '') {
+    throw new Error('changeName 不能为空');
+  }
+  const trimmed = changeName.trim();
+  // 禁止路径穿越
+  if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+    throw new Error(`changeName 不合法: "${changeName}"，不能包含 ..、/ 或 \\`);
+  }
+  return trimmed;
+}
+
+/**
+ * 检测 git worktree 是否可用
+ * @param {string} cwd
+ * @returns {{ supported: boolean, version: string|null, reason?: string }}
+ */
+export function isGitWorktreeSupported(cwd = process.cwd()) {
+  try {
+    const raw = execSync('git --version', { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const match = raw.match(/git version (\d+)\.(\d+)/);
+    if (!match) return { supported: false, version: raw, reason: 'cannot parse version' };
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    if (major > 2 || (major === 2 && minor >= 15)) {
+      return { supported: true, version: raw };
+    }
+    return { supported: false, version: raw, reason: 'git version < 2.15' };
+  } catch {
+    return { supported: false, version: null, reason: 'git not found' };
+  }
+}
+
+export class WorktreeManager {
+  constructor({ cwd, worktreeDir } = {}) {
+    this.cwd = cwd || process.cwd();
+    this.worktreeBase = worktreeDir || resolve(this.cwd, WORKTREES_REL);
+  }
+
+  /**
+   * 获取 worktree 目录绝对路径
+   * @param {string} changeName
+   * @returns {string}
+   */
+  getWorktreePath(changeName) {
+    return resolve(this.worktreeBase, changeName);
+  }
+
+  /**
+   * 读取 worktree 元数据
+   * @param {string} changeName
+   * @returns {object|null} meta.json 内容，不存在或损坏返回 null
+   */
+  getMeta(changeName) {
+    const name = validateChangeName(changeName);
+    const metaPath = join(this.getWorktreePath(name), META_FILE);
+    if (!existsSync(metaPath)) return null;
+    return parseJSON(readFileSync(metaPath, 'utf8'));
+  }
+
+  /**
+   * 创建 worktree
+   * @param {string} changeName - 变更名
+   * @param {{ base?: string }} opts - base: 基础分支，默认当前 HEAD
+   * @returns {{ branch: string, worktreePath: string, baseHash: string }}
+   * @throws {Error} worktree 已存在、git 不可用、changeName 为空
+   */
+  create(changeName, { base } = {}) {
+    const name = validateChangeName(changeName);
+    const worktreePath = this.getWorktreePath(name);
+    const branch = BRANCH_PREFIX + name;
+
+    // 1. 检查 worktree 是否已存在
+    if (existsSync(worktreePath)) {
+      throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
+    }
+
+    // 2. 检查分支是否已存在
+    if (gitQuiet(this.cwd, `rev-parse --verify refs/heads/${branch}`)) {
+      throw new Error(`branch already exists: ${branch}. Run cleanup first.`);
+    }
+
+    // 3. 解析 base 分支
+    let baseBranch = base;
+    let baseHash;
+    if (baseBranch) {
+      baseHash = git(this.cwd, `rev-parse ${baseBranch}`);
+    } else {
+      // 默认用当前 HEAD
+      baseBranch = gitQuiet(this.cwd, `symbolic-ref --short HEAD`) || git(this.cwd, `rev-parse HEAD`);
+      baseHash = git(this.cwd, `rev-parse HEAD`);
+    }
+
+    // 4. 创建 worktree 根目录
+    if (!existsSync(this.worktreeBase)) {
+      mkdirSync(this.worktreeBase, { recursive: true });
+    }
+
+    // 5. 创建 worktree（含版本检测）
+    try {
+      git(this.cwd, `worktree add ${worktreePath} -b ${branch} ${baseHash}`);
+    } catch (e) {
+      const check = isGitWorktreeSupported(this.cwd);
+      if (!check.supported) {
+        throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 使用 --no-worktree 标志跳过隔离，或升级 git 到 >= 2.15`);
+      }
+      throw new Error(`git worktree add 失败: ${e.stderr || e.message}`);
+    }
+
+    // 6. 写入 meta.json
+    const meta = {
+      changeName: name,
+      branch,
+      baseBranch,
+      baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+    };
+
+    const metaPath = join(worktreePath, META_FILE);
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+    return { branch, worktreePath, baseHash };
+  }
+
+  /**
+   * 列出所有活跃 worktree
+   * @returns {Array<{ changeName: string, branch: string, baseHash: string, createdAt: string, worktreePath: string }>}
+   */
+  list() {
+    const results = [];
+    if (!existsSync(this.worktreeBase)) return results;
+
+    const entries = readdirSync(this.worktreeBase, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const metaPath = join(this.worktreeBase, entry.name, META_FILE);
+      if (!existsSync(metaPath)) continue;
+      const meta = parseJSON(readFileSync(metaPath, 'utf8'));
+      if (!meta) continue;
+      results.push({
+        changeName: meta.changeName,
+        branch: meta.branch,
+        baseHash: meta.baseHash,
+        baseBranch: meta.baseBranch,
+        createdAt: meta.createdAt,
+        worktreePath: meta.worktreePath,
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * 清理 worktree（强制删除，不 apply）
+   * @param {string} changeName
+   * @throws {Error} worktree 不存在
+   */
+  cleanup(changeName) {
+    const name = validateChangeName(changeName);
+    const meta = this.getMeta(name);
+
+    if (!meta) {
+      throw new Error(`worktree not found: ${name}。meta.json 不存在，可能已被清理或从未创建。`);
+    }
+
+    const worktreePath = meta.worktreePath || this.getWorktreePath(name);
+    const branch = meta.branch || BRANCH_PREFIX + name;
+
+    // 2. 移除 git worktree
+    try {
+      git(this.cwd, `worktree remove ${worktreePath} --force`);
+    } catch {
+      // git worktree remove 失败，尝试直接删除目录
+      try {
+        if (existsSync(worktreePath)) {
+          rmSync(worktreePath, { recursive: true, force: true });
+        }
+      } catch (e) {
+        throw new Error(`清理 worktree 目录失败: ${e.message}`);
+      }
+    }
+
+    // 3. 删除分支（忽略分支不存在的错误）
+    gitQuiet(this.cwd, `branch -D ${branch}`);
+
+    // 4. 确保目录已删除
+    if (existsSync(worktreePath)) {
+      rmSync(worktreePath, { recursive: true, force: true });
+    }
+  }
+}