SuperAPI AI 工具集

using-git-worktrees

编程与开发

查看项目

更新于 10-14 20:22

技能介绍

用途

该技能用于确保开发工作发生在隔离的工作区中。适用于两种场景:需要开始与当前工作区隔离的功能开发,或在执行实现计划之前准备独立环境。目标是保护当前分支不被改动。

核心原则

  • 先检测现有隔离;
  • 然后用原生工具;
  • 再回退到 git;
  • 绝不与 harness 对抗。

开始时需宣布:正在使用 using-git-worktrees 技能来建立一个隔离的工作区。

步骤 0:检测现有隔离

创建任何东西之前,先检查是否已经处于隔离工作区。通过对比 GIT_DIR 与 GIT_COMMON 判断。如果二者不同(且不在 submodule 内),说明已经在 linked worktree 中,跳到步骤 2,不再创建新 worktree。若在分支上,报告已在隔离工作区及其路径与分支名;若为分离 HEAD,则报告为外部管理,完成时需要创建分支。

需注意 submodule 守卫:在 git submodule 内 GIT_DIR != GIT_COMMON 也为真,需先用 git rev-parse --show-superproject-working-tree 确认不在 submodule 内,再判定是否已在 worktree。

如果处于普通仓库检出,且用户未在 instructions 中表明 worktree 偏好,创建前先征求同意;若用户已声明偏好则直接遵循;若拒绝同意,则原地工作并跳到步骤 2。

步骤 1:创建隔离工作区

1a. 原生 Worktree 工具(首选):若已有创建 worktree 的方法(如 EnterWorktree、WorktreeCreate、/worktree 命令或 --worktree 标志),直接使用并跳到步骤 2。原生工具会自动处理目录放置、分支创建和清理;在有原生工具时使用 git worktree add 会产生 harness 看不到也无法管理的幻影状态。

1b. Git Worktree 回退:仅在无可用的原生 worktree 工具时使用。目录选择优先级为:明确的用户偏好 > 已存在的项目本地目录(.worktrees 优先于 worktrees)> 默认 .worktrees/。创建前必须用 git check-ignore 验证目录已被忽略,若未忽略则添加到 .gitignore 并提交。随后执行 git worktree add "$path" -b "$BRANCH_NAME" 并进入该目录。若因权限错误(沙盒拒绝)失败,告知用户并原地工作。

步骤 2:项目设置

自动检测并运行相应设置命令:package.json 用 npm install;Cargo.toml 用 cargo build;requirements.txt 用 pip install -r;pyproject.toml 用 poetry install;go.mod 用 go mod download。无对应文件则跳过依赖安装。

步骤 3:验证基线干净

运行项目对应测试命令(npm test / cargo test / pytest / go test ./...)。若测试失败,报告失败并询问是继续还是排查;若通过,报告就绪,包含完整路径、测试通过数量与准备实现的功能名。

使用方式与限制

该技能以步骤化流程引导执行,强调先检测、再原生、后回退的顺序。限制包括:沙盒可能阻止 worktree 创建而需原地工作;基线测试失败时是否继续由人类伙伴决定;worktree 目录必须已被 git 忽略,否则会误提交整棵树。