SuperAPI AI 工具集

worktree

编程与开发

查看项目

更新于 10-15 21:34

技能介绍

用途:并行运行多个 Claude/Codex 会话时,若共享同一主检出,会悄悄覆盖彼此的未提交改动与 .next 构建缓存。该技能为每个会话提供隔离的 worktree,使源码、构建产物和状态物理分离,从源头避免冲突。

主要能力:提供 wt-new、wt-ls、wt-done 三个脚本。wt-new 在仓库外的同级 <repo>-worktrees/<slug> 创建 worktree,从 origin/<base> 分出新分支(已存在分支则检出),并把根目录及各工作区的 node_modules、.env 从主检出符号链接过来。wt-ls 显示全部 worktree 状态,包括 clean、DIRTY(有未提交)、↑N(未推送)、PRUNABLE(目录已消失),--mine 只显示该技能创建的,--prune 清理僵尸条目。wt-done 在通过未提交、未推送检查后才移除,--force 可强制;只删除工作目录,分支引用和提交保留在 .git 中。

使用方式:Claude Code 下脚本位于 ~/.claude/skills/worktree/scripts/,Codex 下位于 ~/.codex/skills/worktree/scripts/。典型流程为:运行 wt-new.sh fix/foo 创建 worktree;进入生成的目录启动新会话;在 worktree 内 git add、commit、push 并创建 PR;合并后用 wt-done.sh fix/foo 清理。脚本通过 git rev-parse --show-toplevel 定位仓库根,因此在任意 git 仓库的当前目录下都按该仓库工作。

适用场景:需要多个代理会话并行开发、彼此隔离分支与构建环境的仓库开发工作流。

限制与注意:不要在 worktree 中执行 npm install,因为 node_modules 是符号链接,会污染主检出。部署仅走 git push,不使用 vercel --prod CLI,符号链接的 node_modules 会导致 ENOTDIR 等上传问题。符号链接的 node_modules 在 git status 中显示为 ?? node_modules,切勿 git add。更多细节参见仓库 docs/git-worktree-parallel.md。