前言¶
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 邀請同事並行審查。
參考來源：
