ce-worktree

工作树隔离

确保当前工作在隔离的工作区中进行，不要影响用户的主检出目录。如今大多数编码工具链都会在会话开始时默认创建工作树，因此常见情况下，隔离已经存在。

完成条件： 调用方正在隔离的工作树中工作（该工作树可以是已有的，也可以是新建的），并且已报告其路径和分支；或者已报告阻碍。

操作顺序：检测现有隔离 -> 优先使用原生工作树工具 -> 回退到普通 git。 绝不要创建工具链无法识别的工作树。

两种模式，由调用方的需求决定：

• 新工作（默认）。 未指定引用名称——从基准分支（主干）创建一个新分支。这是用户选择工作树选项时 ce-work 和 ce-code-review 使用的方式。
• 隔离已有引用。 调用方指定了 PR 头分支、分支或提交——将工作树关联到该引用，而不是创建新分支。一个分支一次只能在一个工作树中检出。 如果指定的引用已在任何位置检出（最常见的情况是它就是主检出目录的当前分支），则不要创建第二个工作树——报告它已在 <path> 处检出，并让调用方决定如何处理（直接在该位置工作；或者仅当必须使用独立且干净的工作树时，在同一提交处创建一个分离头指针工作树）。

步骤 0：检测现有隔离

比较已解析的绝对 git 目录与已解析的绝对共用 git 目录。Git 会根据当前目录混用绝对路径和相对路径（从普通检出目录的子目录运行时，--git-dir 返回绝对路径，而 --git-common-dir 可能返回相对路径），因此直接比较原始字符串会错误地判定为“已隔离”：

git rev-parse --absolute-git-dir                     # absolute git dir for this worktree
(cd "$(git rev-parse --git-common-dir)" && pwd -P)   # absolute shared (common) git dir

相同 -> 普通检出目录；继续步骤 1。

不同 -> 已链接的工作树或子模块。使用 git rev-parse --show-superproject-working-tree 区分：

• 非空 -> 子模块；将其视为普通检出目录并继续步骤 1。
• 空 -> 已隔离。报告工作树路径（git rev-parse --show-toplevel）和当前分支，然后在当前目录中工作——从工作树创建工作树会落入错误的工作树，而且创建当前工作树的工具链无法识别它。在隔离已有引用模式下，应在此处检出该引用（除非它已经是当前引用），不要嵌套创建工作树。

步骤 1：优先使用工具链的原生工作树工具

如果工具链提供原生工作树功能——例如 EnterWorktree / WorktreeCreate 工具、/worktree 命令或 --worktree 标志——请使用它并停止。原生工具会放置、跟踪并清理工作树，以便工具链管理。背着工具链运行 git worktree add 会创建工具链无法识别、无法切换到或无法清理的幽灵状态。

步骤 2：Git 回退方案

仅当没有原生工具，且步骤 0 未发现现有隔离环境时，才执行此步骤。

1. 从仓库根目录运行： cd "$(git rev-parse --show-toplevel)"。以下路径均相对于仓库根目录，但该技能从用户当前目录运行——如果不这样做，.worktrees/<branch> 和对 .gitignore 的修改会落在子目录中（例如 src/.worktrees/...）。
2. 根据工作描述选择有意义的分支名（例如 feat/login、fix/email-validation），不要使用不透明的自动生成名称。基准分支：优先使用 origin 的默认分支，否则使用 main。
3. 创建任何内容之前，确保 .worktrees/ 已加入 Git 忽略规则： git check-ignore -q .worktrees/——末尾要带斜杠，这样即使目录尚不存在，也能匹配已有的仅针对目录的 .worktrees/ 规则（不带斜杠时，检查会漏掉该规则，导致配置正确的仓库也出现未提交改动）。如果未被忽略，则在 .gitignore 中添加一行 .worktrees/。
4. 使用 git fetch origin <from-branch> 更新基准分支。此操作失败不影响后续步骤——没有 origin 远程、远程名称不同，或只有本地分支，都不应中止；继续使用本地引用。
5. 根据模式创建工作树：
   • 新工作： git worktree add -b <branch-name> .worktrees/<branch-name> origin/<from-branch>（如果 origin/<from-branch> 不存在，则使用本地 <from-branch> 引用）。
   • 已有分支或标签： git worktree add .worktrees/<slug> <target-ref>。
   • PR： 在本地分支上检出——git fetch origin pull/<n>/head:pr-<n>，然后运行 git worktree add .worktrees/pr-<n> pr-<n>。绝不要使用分离的 FETCH_HEAD：否则修复循环的提交会成为孤立提交，而不会更新 PR。（若要将提交推送回 PR，请先以分离状态创建工作树——git worktree add --detach .worktrees/pr-<n>——然后进入该目录并运行 gh pr checkout <n>，这样可兼容 fork。）
   • 如果 Git 提示该引用已在其他位置检出，请遵循上述一分支一工作树规则——不要强行创建第二个工作树。
6. 进入该目录，然后报告路径和分支。

如果 git worktree add 因沙盒或权限错误而失败，则所请求的隔离环境并不存在。不要在当前检出中继续操作——用户选择隔离正是为了避免这种情况。报告失败并询问用户，提供诸如“在当前检出中工作”或“停止并解决权限问题”等选项；使用当前工具列表中已有的宿主阻塞式提问工具（按能力匹配，不要按宿主特定名称匹配）。工具出现在当前工具列表中，即可证明其存在；绝不要调用面向用户的提问工具来确认它是否存在。如果列表中有匹配的工具但尚未加载，请使用宿主的工具发现原语加载该能力——不要搜索其他宿主的工具名称。仅当列表中没有此类工具，或实际提问调用出错时，才在聊天中列出编号选项并等待回复。绝不要跳过确认，也不要自动重试其他路径。