SuperAPI AI 工具集

git-worktree

编程与开发

查看项目

更新于 10-31 13:16

技能介绍

用途

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 分支上的提交,主分支在显式合并前始终不受影响。

限制方面:资料未提供具体平台、收费、价格或效果信息;快速修复、配置变更和单文件编辑建议跳过该技能。