ce-worktree

Worktree 隔离

确保当前工作在独立的 workspace 中进行，不干扰用户的主检出目录（main checkout）。大多数 AI 编码 Harness（开发框架/宿主）现在默认会在 Session 启动时自动创建 worktree，因此常见情况是隔离环境已经存在——务必优先检测，切勿重复创建。

操作顺序：检测现有隔离 -> 优先使用原生 Worktree 工具 -> 退而使用原生 Git 命令。 绝不要创建 Harness 无法识别的 worktree。

两种模式（根据调用方需求决定）：

• 新任务模式（默认）。 未指定具体的 ref——从基线分支（trunk）拉出一个全新的分支。这也是 ce-work 所使用的模式。
• 隔离现有 Ref 模式。 调用方指定了需要隔离工作的 ref——例如 PR head、已有分支或某个 commit。直接将 worktree 挂载到该 ref 上，而不是创建新分支。此模式受一条硬性 Git 规则限制：同一个分支在同一时间只能被检出到一个 worktree 中。 如果指定的 ref 已经在别处被检出了（最常见的情况是它刚好是主 checkout 的当前分支），切勿为其创建第二个 worktree——直接提示该分支已在 <path> 检出，由调用方决定后续操作（如直接在原位置工作；或者仅在必须要求干净独立目录时，在同一个 commit 上创建一个 detached 游离态 worktree）。绝不能把同一个分支放到两个 worktree 中。

以下步骤（检测 -> 原生工具 -> Git 退回方案）同时适用于这两种模式；不同模式仅影响检出的内容以及返回给调用方的报告信息。

步骤 0：检测现有隔离状态

在创建任何内容之前，先检查当前目录是否已经是一个关联的 worktree。将解析后的绝对 git 目录与解析后的绝对公共 git 目录进行对比——必须先将两者均转换为绝对路径再对比，而不能直接对比 git rev-parse 的原始输出。Git 会根据当前目录混合使用绝对路径和相对路径（在普通 checkout 的子目录中执行时，--git-dir 返回绝对路径，而 --git-common-dir 可能会返回相对路径），直接进行字符串对比会导致误判为“已隔离”：

git rev-parse --absolute-git-dir                     # 当前 worktree 的绝对 git 目录
(cd "$(git rev-parse --git-common-dir)" && pwd -P)   # 共享（公共）git 目录的绝对路径

如果这两个绝对路径相同，说明当前是普通的 checkout 目录——继续执行步骤 1。

如果路径不同，说明你当前处于关联的 worktree 或 子模块（submodule）中。需要区分它们：

git rev-parse --show-superproject-working-tree

• 输出非空 -> 当前处于子模块中；将其视作普通 checkout，继续执行步骤 1。
• 输出为空 -> 你已经处于独立的 worktree 中。报告当前 worktree 的路径（git rev-parse --show-toplevel）和当前分支。切勿再次创建 worktree——在 worktree 中再建 worktree 会落入错误的目录，且对创建当前 worktree 的 Harness 不可见。随后就地开展工作：在新任务模式下，直接在此处继续；在隔离现有 ref 模式下，将该 ref 检出到当前目录（除非它已经是当前分支），而不是嵌套创建新的 worktree。

步骤 1：优先使用 Harness 原生 Worktree 工具

如果 Harness 提供了原生的 worktree 基础能力——例如 EnterWorktree / WorktreeCreate 工具、/worktree 命令或 --worktree 标志——直接使用它并结束流程。原生工具可以正确放置、追踪和清理 worktree，以便 Harness 进行管理。背着 Harness 私下执行 git worktree add 会产生 Harness 无法感知、无法跳转也无法清理的幽灵状态。

步骤 2：Git 命令备选方案（Fallback）

仅当没有原生工具且步骤 0 未检测到现有隔离时才执行此步骤。

1. 从仓库根目录执行。 下文提到的 .worktrees/ 和 .gitignore 路径都是相对于仓库根目录的，但 Skill 的运行上下文是用户的当前目录（可能是一个子目录）——因此先切到根目录：cd "$(git rev-parse --show-toplevel)"。若不这么做，.worktrees/<branch> 和 .gitignore 的修改就会落在子目录里（例如 src/.worktrees/...、src/.gitignore），而不是仓库根目录。
2. 根据任务描述选择一个有意义的分支名称（例如 feat/login``fix/email-validation）——避免使用含义不明的自动生成名称。选择一个基线分支（默认使用 origin 的默认分支，否则使用 main）。
3. 在创建任何内容之前，确保 .worktrees/ 已被 gitignore，防止 worktree 内容被意外提交：检查 git check-ignore -q .worktrees/——注意带上末尾的斜杠，这样即使目录尚未创建，也能匹配已有的仅针对目录的 .worktrees/ 规则（如果不带斜杠执行 git check-ignore .worktrees 会漏掉这种情况，导致配置正确的仓库变脏）。如果尚未被忽略，则在 .gitignore 中添加一行 .worktrees/。
4. 尽力更新基线分支，同时不干扰当前的 checkout：git fetch origin <from-branch>。此操作为非致命性的——如果报错（没有 origin 远程库、远程库名称不同或仅为本地分支），无需中止；继续执行下一步并使用本地 ref 即可。
5. 创建 worktree——命令取决于所处的模式：
   • 新任务模式： git worktree add -b <branch-name> .worktrees/<branch-name> origin/<from-branch>（如果 origin/<from-branch> 不存在，则使用本地的 <from-branch> ref）。这会基于基线分支创建一个新分支。
   • 隔离现有 Ref 模式： 挂载到现有 ref 而不是创建新分支——对于已有的分支或 tag，执行 git worktree add .worktrees/<slug> <target-ref>。对于 PR，必须将其检出到本地分支上（绝不要检出为游离态 FETCH_HEAD——那会让修复循环中的 commit 成为孤立 commit，而无法更新 PR）：执行 git fetch origin pull/<n>/head:pr-<n>，然后执行 git worktree add .worktrees/pr-<n> pr-<n>。（如果希望恢复针对 PR 的推送追踪，可以先创建游离态 worktree——git worktree add --detach .worktrees/pr-<n>——然后 cd 进去运行 gh pr checkout <n>，这种做法支持 fork 跨仓库 PR）。如果 Git 提示该 ref 已在别处检出，请遵守两种模式中的“已检出”规则——不要强行创建第二个 worktree。
6. 切换进入该目录：cd .worktrees/<branch-name>（或 .worktrees/<slug>）。

如果 git worktree add 因沙盒或权限错误而失败，说明无法创建请求的隔离环境。在触碰当前 checkout 之前，这需要用户做出阻塞式的决策——切勿静默地在当前 checkout 中继续操作（用户专门选择隔离就是为了避免干扰当前环境，特别是当 ce-work / ce-code-review 路由到此处选择 worktree 选项时）。报告失败信息，并通过平台提供的阻塞式提问工具向用户询问：Claude Code 中使用 AskUserQuestion（如果未加载其 schema，先调用 ToolSearch 传入 select:AskUserQuestion）、Codex 中使用 request_user_input、Antigravity CLI (agy) 中使用 ask_question、Pi 中使用 ask_user（通过 pi-ask-user 扩展）——提供诸如“在当前 checkout 中继续工作”与“停止并解决权限问题”等选项。如果 Harness 中不存在阻塞式工具或调用报错，请在 Chat 中列出编号选项并等待回复；绝不能跳过确认步骤。只有在获得明确确认后，才能在当前 checkout 中工作，且不要自动重试其他替代路径。

其他 Worktree 操作

直接使用 git 命令即可——无需封装脚本：

git worktree list                          # 列出所有 worktree
git worktree remove .worktrees/<branch>    # 删除指定的 worktree
cd .worktrees/<branch>                     # 切换到指定的 worktree
cd "$(git rev-parse --show-toplevel)"      # 返回当前 checkout 的根目录

何时创建 Worktree

只有当当前未处于隔离状态，且确实需要一个独立的开发空间时，才需要创建 worktree（步骤 1/2）：

• 在评审 PR 的同时，保持当前 checkout 不受影响以便进行其他工作
• 并行开发多个需求，无需频繁切换分支

如果单任务工作可以直接在当前 checkout 的分支上完成，则不要创建 worktree——当步骤 0 显示你已经处于 worktree 中时，也绝不要再创建。

继承集成

ce-work 和 ce-code-review 将本 Skill 作为可选项提供。当用户在这些流程中选择“worktree”时，先执行步骤 0：如果工作已经隔离，则就地继续；否则创建一个新的 worktree（优先使用原生工具），并根据任务描述生成有意义的分支名称。

常见问题排查（Troubleshooting）

"Worktree already exists"：该路径已被占用。在重新创建之前，先切换进去（cd .worktrees/<branch>）或将其删除（git worktree remove .worktrees/<branch>）。

"Cannot remove worktree: it is the current worktree"：先 cd 离开该 worktree，然后再执行 git worktree remove。