用途:把一串相互依赖的 GitHub PR 堆栈整体落地到主干,处理「某 PR 的 base 是另一开放 PR」的情形。
主要能力与要求:必须通过 GitHub 原生 stack 对象与 gh stack merge 完成,不得用 gh pr merge / gh pr edit 逐条合并和改 base 来模拟堆栈语义。允许的 merge-forward 与 rebase 历史由根 AGENTS.md 规定,评审修复传播由 stack review guide 规定。
使用方式:先用 gh stack --version 确认原生支持,扩展或服务端功能不可用时硬停,不支持跨 fork 链。使用干净的独立 worktree,拉取实时 PR 元数据和精确 head OID,并通过 GraphQL 查询 PullRequest.stack 与 stackEntry.position 确认堆栈成员资格与顺序。若依赖 PR 尚未入栈且作者一致,可用 gh stack link --base <trunk> <bottom-pr> ... <top-pr> 自底向上链接。需要刷新时可选择 gh stack checkout / sync / rebase / push 的原生级联 rebase,或 merge-forward 方式传播父更新。合并前重查堆栈,要求每个 PR 开放、非草稿、顺序正确且满足评审与检查要求。整体合并:gh stack merge <stack-number> --yes --merge;部分落地需指定边界 PR。
限制:不传 --delete-branch,不手动重定向依赖,不逐条发合并命令。原生合并报阻塞时应排查或停止报告,绝不退回 gh pr merge。任何历史重写都会使 commit OID 假设失效,需重新拉取精确 head 并重审评审线程、批准、可合并性与检查。合并后用 gh pr view 等待每个 PR 报告 MERGED,再重查剩余层是否仍按序链接;删除分支须在确认已合并且无开放 PR 以其为 base(gh pr list --state open --base <branch> --json number --jq length 返回 0)后单独执行。