用途：gh-stack 是 GitHub CLI 扩展，用于堆叠分支和堆叠 PR。堆叠是以主干为根的有序分支链，每个分支基于其下一层分支并对应一个 PR，评审者只看到该层差异。输出按主干优先、从左到右显示，如 (main) <- auth <- api <- frontend；左为底、右为顶，auth 先合并，frontend 最后合并。up 向顶部移动，down 向主干移动。基础性工作放底部，依赖它的代码放上方。
安装与配置：需要 Git 2.36+ 和已认证的 GitHub CLI。安装命令：gh extension install github/gh-stack。建议配置：git config rerere.enabled true；若仓库有多个远程，需 git config remote.pushDefault origin。
非交互使用：gh stack 依据 stdout 是否为 TTY 决定行为，管道下多数命令报错或输出静态文本，PTY 下会打开提示或全屏 TUI 并阻塞。应显式传参：gh stack view --json、gh stack submit --auto、gh stack merge <target> --yes、gh stack init <branch>...、gh stack add <branch>、gh stack checkout <target>、gh stack up/down/top/bottom。不要裸跑 view、submit、init、add、checkout、switch、modify。多远程时，push、submit、sync、rebase、link 需加 --remote <name>，除非已配置 remote.pushDefault；checkout 和 trunk 无 --remote 参数。
核心流程：gh stack init auth 创建堆叠并检出分支；提交后 gh stack add api 添加下一层；gh stack submit --auto 推送所有分支并创建草稿 PR（加 --open 创建待评审 PR）；gh stack view --json 确认。同步用 gh stack sync，加 --prune 删除已合并 PR 的本地分支。合并用 gh stack merge 42 --yes（PR 42 及其下方所有未合并 PR）或 gh stack merge 7 --yes（堆叠 7 中所有未合并 PR），可加 --squash、--merge、--rebase 或 --merge-method。合并是全有或全无。
读取状态：gh stack view --json 向 stdout 输出 JSON，状态消息走 stderr，不要解析状态消息，应依据退出码判断。退出码：0 成功；1 通用错误；2 不在堆叠中；3 变基冲突；4 GitHub API 失败；5 参数无效；6 需要消歧；7 变基已在进行；8 堆叠文件锁定；9 堆叠 PR 不可用；10 需要 modify 恢复。退出码 3 时，rebase 后解决文件、git add，再 gh stack rebase --continue，或 --abort 恢复；sync 后堆叠已恢复，运行 gh stack rebase 重现冲突再处理。
限制：堆叠严格线性，一个父分支最多一个子分支，并行工作用独立堆叠。rebase 和 sync 自动更新受影响的干净工作树，不会自动 stash 或创建/删除工作树。modify 仅支持 TUI，没有非交互式重排或删除；错误可能建议 gh stack modify，但需改用 unstack 再 init 重构。PR 标题和正文自动生成，之后用 gh pr edit 修改。gh stack <command> --help 是权威帮助，gh stack help <command> 无效。更多细节见 references/stack-design.md、references/commands.md、references/troubleshooting.md。