前言¶
Stacked Pull Requests（堆叠 PR）并不是新概念——在 Meta、Google 等公司内部，用 Graphite、Sapling 等工具把大改动拆成一串有依赖关系的小 PR，早就是成熟实践。但长期以来，GitHub 官方并没有一等公民级别的支持：你要么忍受一个几千行的巨型 PR，要么自己手动维护多条分支、反复 rebase、在冲突里打转。
2026 年 7 月 30 日，GitHub 在 Changelog 宣布 Stacked Pull Requests 进入 Public Preview；8 月 4 日，官方工程博客又发布了一篇长文，专门讲如何把 Agent 一次性吐出来的「巨型 AI PR」拆成可审查的堆叠链。配合 gh stack CLI 扩展和 PR 页面上的 Stack Map，这套能力终于从「社区插件」变成了 GitHub 原生工作流。
对正在大量使用 Copilot、Cursor、Claude Code 等编程 Agent 的团队来说，这条新闻的分量不小：Agent 越能干，单次 PR 的 diff 往往越大；审查成了新的瓶颈。Stacked PR 是 GitHub 给出的官方解法——不是让你少写代码，而是让代码以「小步、可并行审查、可一键合并」的方式落地。
本文基于 GitHub 官方博客与文档核实后的信息，梳理堆叠 PR 要解决什么问题、怎么上手，以及和 AI Agent 协作时有哪些值得注意的细节。
巨型 PR 为什么成了 AI 时代的痛点¶
GitHub 工程博客里举了一个很典型的场景：给购物助手加「商品搜索」功能。你丢给 Agent 一个 prompt，几分钟后回来，PR 里可能已经塞进了：
- 新的数据模型和种子数据
- API 路由与校验逻辑
- 客户端接线、UI、空态/错误态处理
一个 PR，1700+ 行 diff，描述还是 AI 生成的「又长又浅」。Reviewer 的真实反应往往是：「改天再看。」
博客里引用了 Gartner 的预测：到 2028 年，编码 Agent 有望在每个 SDLC 阶段带来约 50% 的生产力提升。生产力上去了，PR 体积也跟着膨胀——审查速度却没有同步变快。Changelog 里 TED 的 CTO Andy Merryman 也提到类似困境：「AI 让开发者效率大增，但 PR 大到 Reviewer 吃不消。」
传统二选一很尴尬：
- 一个大 PR：审查难、反馈质量差、合入慢，最后常常是 under-reviewed 地强行合并。
- 多个小 PR 手动拆：逻辑上更清晰，但要自己维护分支依赖、手动 rebase、处理冲突，运维成本不低。
Stacked PR 试图在两者之间找平衡：结构上拆小，工具上自动管依赖。
堆叠 PR 的核心思路：按依赖分层¶
原则就四个字：decomposition（分解）。
不是用一个 PR 解决整个 Issue，而是把功能拆成有逻辑依赖的若干层，每层只关注单一职责，体积小到 Reviewer 能「装在脑子里」。上一层 PR 的 base 是下一层（更底层）的分支，而不是直接指向 main。
官方示例里，「商品搜索」被拆成四层：
| 层级 / 分支 | 交付内容 | 依赖 |
|---|---|---|
L1 feat/catalog-data |
类型化商品目录、种子数据、数据访问模块 | main（stack base） |
L2 feat/search-api |
带校验的 /api/products/search 接口 |
L1 |
L3 feat/chat-grounding |
Chat 调用 API，基于真实商品数据回答 | L2 |
L4 feat/grounded-ui |
商品引用卡片与 UI 状态 | L3 |
好处是审查可以按专长分工：数据层给数据 Owner，UI 给前端 Owner，互不阻塞。Next.js 负责人 Tim Neutkens 在 Changelog 的引述里也提到，Vercel 团队用堆叠 PR 后，「大功能拆成小改动，Review 轻松很多」。
上手：gh stack CLI 与 Agent Skill¶
安装 CLI 扩展¶
Stacked PR 的管理入口是 GitHub CLI 扩展 github/gh-stack。官方文档要求 GitHub CLI 2.90.0+、Git 2.20+，并完成 gh auth login 认证。
gh extension install github/gh-stack
让 Agent 学会堆叠工作流¶
如果你用 Copilot 或其他支持 Skill 的 Agent，还需要安装 gh-stack skill，让 Agent 知道如何创建和管理 stack：
gh skill install github/gh-stack
或者：
npx skills add github/gh-stack
Changelog 明确提到：堆叠 PR 可以在 github.com、GitHub CLI、GitHub 移动 App，以及 GitHub Copilot 等编码 Agent 上使用。
创建第一个 Stack¶
典型流程如下（命令以官方 Quickstart 为准）：
1. 初始化 stack，创建第一层分支：
gh stack init
会提示你命名第一个分支；默认以仓库的默认分支（通常是 main）作为 trunk（stack base）。这一点很重要：整个 stack 生命周期里的 CI 和合并规则，都是相对 stack base 来评估的。
2. 在当前层之上追加下一层：
gh stack add -Am "描述本层改动的 commit message"
如果当前分支还没有 commit，改动会落在当前层；如果已有 commit，则会自动创建新分支作为上一层。
3. 推送到远端：
gh stack push
4. 创建 PR 并在 GitHub 上链接成 stack：
gh stack submit
每个 PR 的 base 会自动设对：第一层指向 main，后续层指向前一层分支。Reviewer 打开某个 PR 时，只能看到该层的 diff，不会被上下层的改动淹没。
5. 随时查看 stack 全貌：
gh stack view
其他常用命令包括 gh stack rebase（级联 rebase）、gh stack sync（fetch + rebase + push + 同步 PR 状态）、gh stack merge（合并 stack 中的一层或多层）。完整命令表见 官方 CLI 参考文档。
PR 页面：Stack Map 与审查策略¶
Stack 提交到 GitHub 后，每个 PR 顶部会出现 Stack Map——一张可点击的导航图，让你在 stack 各层之间快速跳转。
官方推荐的审查顺序值得记一下：
- 自上而下读（Read top-down）：先看 stack 最顶层，了解最终目标是什么——「哦，原来是要在聊天界面展示商品卡片。」
- 自下而上审（Review bottom-up）：从 stack 底部（最接近
main的那层）开始逐层审查，每一层的实现都建立在前一层已通过的理解之上。
这样，1700 行的 monolith diff 被拆成四个各自独立的审查单元，不同 Reviewer 甚至可以并行审不同层，互不挡路。
改底层后的 rebase：别踩签名提交的坑¶
Stack 并不是「拆完就万事大吉」。工程博客专门讲了一个常见场景：Reviewer 在 stack 最底层（L1）提了修改意见，Agent 或开发者修完 push 之后，上层分支会与底层产生 divergence。GitHub 会明确提示：「Some branches in this stack have diverged and must be rebased」，并显示 Unable to merge as a stack。
此时 PR 页面上会出现 Rebase stack 一键按钮。但官方特别提醒：在网页上点这个按钮，rebase 是在 GitHub 服务器上执行的，产生的 commit 的 committer 会变成点按钮的人，且不会签名。如果你的分支保护规则要求 signed commits，这个一键操作可能悄悄导致合入失败。
更稳妥的做法是在本地执行：
gh stack rebase
gh stack push
如果需要一口气同步整个 stack 的状态，可以用：
gh stack sync
这条命令会 fetch、对 stack 做级联 rebase、push，并同步 GitHub 上的 PR 状态——底层改动可以「ripple upward」，不用手改 L2、L3、L4。
合并：一键落地整条 stack¶
Public Preview 的一大卖点是合并体验。你可以：
- 合并 stack 顶端：一次性落地从 stack base 到顶层的所有未合并层（Changelog 称「one click merge everything」）。
- 只合并部分层：合并下方若干层后，上方 PR 保持打开，并自动 rebase、retarget。
现有的 branch protection、required checks、Review 规则照旧生效——Stacked PR 是 built into GitHub，不是旁路工具。jQuery 作者 John Resig 在 Changelog 里提到，用 gh CLI + agent skill 配合 stack，「5 个 stacked PR 直接进 merge queue 一次性合入」。
需要注意的是：Merge queue 对 stacked PR 的支持仍在逐步 rollout 中（Changelog 原文：rolling out progressively over the coming weeks），如果你的团队重度依赖 merge queue，上线前最好先在自己仓库验证一下。
和 AI Agent 协作时的实践建议¶
结合官方博客的示例，几条可操作的结论：
1. 在 prompt 里约束「一层一职责」。 不要让 Agent 在一个分支里同时改数据层、API 和 UI；按 L1→L4 的顺序分派给不同专长的 Agent（数据建模、后端、前端），每层 commit 前先跑 CI。
2. 每层合入前先问三个 Reviewer 问题（博客里的 Reviewer’s note 模板）：
- L1：类型对不对？数据校验了吗？查询 helper 安全吗？
- L2：输入校验了吗？响应契约稳定吗？错误/空态在这里处理还是下游？
- L3：每个回答是否都能追溯到真实 API 响应？API 失败或无结果时怎么办？
- L4：引用是否链回真实商品？loading/empty/error 状态齐了吗？
3. 同一作者（或同一 Frontend Agent）也可以拆多层。 博客刻意把 L3（接线）和 L4（UI）分开——UI Owner 不必重复审查数据流，审查边界更清晰。
4. 优先本地 rebase，慎用网页一键 rebase。 尤其是有 signed commits 或严格 audit 要求的团队。
5. 利用 stack 并行审查，但保持 stack base 稳定。 stack base 一旦变动，整条链的 CI 评估基准都会跟着变；大功能开发期间尽量别让 main 上有破坏性变更插队。
写在最后¶
Stacked PR 不是替代码审查「减负」的魔法——Reviewer 仍然要读 diff、提意见、把关质量。它改变的是审查的粒度与协作方式：把「一个没人想开的巨型 PR」变成「一串可以分配、可以并行、可以逐层合并的小 PR」，并且 rebase、链接、合并这些原本要手搓的脏活，由 GitHub 原生工具接管。
对 AI 编程 Agent 来说，这套能力尤其对口：Agent 天然倾向于「一次写完整个功能」；gh stack + gh-stack skill 则给了 Agent（和人）一个结构化的交付模板。Public Preview 已向所有仓库逐步开放，不妨在下一个 Agent 生成的大 diff 上试一次——先 gh stack init，再按依赖一层层 add，最后用 Stack Map 邀请同事并行审查。
参考来源：
