SuperAPI AI 工具集

to-stack

编程与开发

查看项目

更新于 11-05 03:47

技能介绍

用途

to-stack 用于把一次大型改动转成一个 PR 栈:PR 1 基于目标分支,后续每个 PR 都基于它下面的一层。这样审查者可以一次只关注一个关注点,而栈顶与已经测试过的代码树逐字节一致。

参数与调用

参数为 $ARGUMENTS,可以是 PR 编号或 URL,也可以是分支;不提供时使用当前分支及其 PR。

--each 选项:让每个 PR 按顺序各自落到目标分支,各自带版本号变更和 CHANGELOG 段落。默认做法是从栈顶向下合并到 PR 1,最终以一个 squash 和一个发布落地。

工作流程

解析:工作区有未提交改动时停止,询问提交或暂存。对 PR 使用 gh pr view 获取 headRefName、baseRefName 后检出;对分支直接检出。确定 tip 与 base 后,先 git fetch origin <base>,再与远程 base 比较,避免过期的本地 base 夸大差异。若 tip 与 base 冲突,或 base 已发布计划中的版本,先合并 base 并升版。若不含锁文件的改动少于约 600 行,会说明拆分不值得,除非用户坚持。范围确定后给出类似“Splitting feat/x (#42) vs main: 49 files, +3432”的说明。

映射:记录每个改动文件所需内容,包括导入,以及每个测试用例涉及的 mock、全局变量、辅助函数和选项;把改动按关注点分组。共享文件(清单、入口 barrel、类型索引、核心模块、README、CHANGELOG)需把每一行改动分配到某个关注点,确保每行都有归属。

计划:按依赖顺序排列关注点,清单和配置在前,然后是核心、功能,最后是废弃或兼容代码。每层应只含一个关注点、不含锁文件时少于约 600 行改动、自身可运行通过,且不依赖后续层才被使用。随后给出层、分支、内容、大致行数、基础分支和合并策略的表格,等待用户明确同意后才构建、推送并创建 PR。已有 PR 会成为 PR 1,其分支会被重写。

备份:运行 git branch <branch>-full <tip> 备份,后续检查均与它比较。

自底向上构建:每层从下一层新建分支。整文件落地的用 git restore 从备份恢复指定路径;共享文件只写本层片段;测试保留本层可运行的最终用例,必要时写最小替代用例。清单只保留本层字段并重新生成锁文件,版本变更放在第 1 层;使用 --each 时每层按自身变更类型相对下层升版。文档只写本层的 README 和 CHANGELOG 行。暂存明确路径,删除 base 尚未忽略的生成产物,然后调用 check 技能检查,只有通过才提交,每层一个常规提交。

验证栈:git diff --quiet <backup> <top> 必须通过,因为顶层就是原始代码树;使用 --each 时排除清单、锁文件和 CHANGELOG 后再验证,并确认这些文件的差异只有版本行和版本标题。若失败,定位丢失或多出行的那一层修复并重新堆叠。

并入修复(仅当用户要求拆分同时修改):在每个修复所属层提交,用 git rebase --update-refs --onto <layer> <layer>@{1} <top> 重排上方各层,冲突时保留双方意图,并确认各层修复路径之外的代码仍与通过检查的代码树一致,最终栈顶与备份的差异应恰好是这些修复。

打开草稿 PR:推送每层分支(重写过的 PR 1 分支用 --force-with-lease),自底向上跳过已有 PR 的层,其余用 gh pr create --draft 指定下层为 base,标题与正文写“Part N of M”,记录每个 PR 编号。每个 PR 正文按仓库 PR 模板编写,包含 Part N of M、一句话摘要、整个栈的 PR 编号列表并标出“← this PR”、本层新增内容、对后续层才到达内容的审查说明和检查证据。默认 PR 1 保留整体改动描述;使用 --each 时 PR 1 只描述自身层。最后用 gh pr edit 应用正文。

报告与落地:输出 #、PR、分支、行数、测试的表格,并说明如何落地:从 PR 1 向上审查;默认从栈顶向下逐层 squash 合并,PR 1 最后合入 base;--each 时先合 PR 1 到 base,再把 PR 2 rebase 到 squash 后的提交并重定向目标,依次向上。下层修复需在该层提交、用 --update-refs 重排并强制推送上方各层。PR 1 合并前保留备份分支。审查意见到达后可继续使用 /hb:feedback <PR 1>。

适用场景与限制

适用于已有较大分支或 PR、希望拆成便于逐层审查的小 PR 的情形。需要对 Git 与 GitHub CLI 有一定了解,操作涉及分支重写和强制推送;改动较小时工具会建议不拆分。其他平台支持情况暂未提供。