用途
git-worktree 是一个供 AI 在执行工作流时读取的参考技能,核心目标是在启动工作流时自动创建 Git worktree,把全部改动隔离到独立分支上。这样即使工作流失败,也可以直接丢弃 worktree,主分支不会受到任何影响。
主要能力
- 自动创建 worktree:在运行开始时执行
git worktree add .worktrees/[id] -b af/[id]。 - 隔离改动:所有编辑都发生在 worktree 目录中,主分支不受影响。
- 成功处理:在 Phase 5 完成后,提供合并、创建 PR、保留分支或丢弃等选项。
- 失败处理:运行失败时丢弃 worktree,主分支保持原样。
- 取消处理:运行取消时执行
git worktree remove .worktrees/[id]。
使用方式
自动触发:当 AF_WORKTREE=true 时,/run 会自动使用 worktree。
手动触发:用户明确说“use a worktree”时启用。
跳过场景:快速修复、配置变更、单文件编辑。
配置方式:
export AF_WORKTREE=true
export AF_WORKTREE_DIR=".worktrees" # default
同时需要把 .worktrees/ 加入 .gitignore。
生命周期
worktree_lifecycle[5]{event,action}:
- run:start:
git worktree add .worktrees/[id] -b af/[id] - Phase 1 approved:所有编辑在 worktree 目录中进行
- Phase 5 complete:提供 merge / create PR / keep branch / discard 选项
- run:cancel:
git worktree remove .worktrees/[id] - run failed:丢弃 worktree,主分支不受影响
安全规则
safety[4]{rule,reason}:
- 绝不在有未提交改动时强制删除:用户可能丢失工作。
- 始终提供 merge/PR/keep/discard 选项:由用户决定。
- 仅在明确取消或失败时自动丢弃:不要自行假设。
- 丢弃前进行 checkpoint 提交:最后一次恢复机会。
适用场景与限制
适用于需要隔离改动、避免污染主分支的 AI 工作流,尤其是多阶段执行、可能失败或需要人工决定合并策略的任务。与 phase-checkpoint.cjs 配合使用时,检查点是 worktree 分支上的提交,主分支在显式合并前始终不受影响。
限制方面:资料未提供具体平台、收费、价格或效果信息;快速修复、配置变更和单文件编辑建议跳过该技能。