SuperAPI AI 工具集

backport

编程与开发

查看项目

更新于 10-16 12:51

技能介绍

backport 技能用于在本地工作区交互式地创建一个向后移植拉取请求:将一个来源(当前分支、某个 PR、另一个分支或特定提交)的改动应用到目标分支上。目标分支通常是发布分支(例如 rel/0.32),但除来源自身的基分支以外的任何已存在分支都允许(把改动 backport 到同一基分支是空操作)。

用途 该技能面向需要把改动移入旧发布分支的场景,例如把 main 上的修复移植到发布分支。在执行任何 git 命令之前,它会先确定输入:来源可以是当前分支(用户说“backport this”且未指定时的默认值)、PR 编号、分支名、提交 SHA 或范围;目标分支必须是 origin 上已存在的分支,若未指定会先列出候选并询问,来源自身的基分支会被拒绝;squash 仅在用户明确说“squash”时启用,默认不 squash。任何含糊之处都会在工作区被改动前先询问一次。

主要能力 技能按阶段顺序执行,任何错误都会停止并报告:

阶段 A 预检与安全:校验 git 版本、gh 版本与 gh 认证状态(本地运行时若缺失或未认证则中止);捕获原始分支、git status、未推送提交;当来源不是当前分支且工作区脏时执行带 -u 的 stash 并记录 stash ref(来源为当前分支时不 stash,仅警告并确认);git fetch 目标分支,若目标在 origin 不存在则中止。

阶段 B 解析提交列表:PR 来源通过 gh pr view 获取信息,并按状态区分——MERGED 优先使用 squash-merge 提交,OPEN 会警告可能包含不完整工作并确认,CLOSED(未合并)会警告并确认;分支来源用 git log 反向列出;SHA/范围原样使用并校验。解析结果会展示给用户确认。

阶段 C 创建 backport 分支:命名规则为 backport/<id>-to-<target-slug>,本地运行使用 backport/ 前缀,云代理使用 copilot/ 前缀;<target-slug> 是将目标分支中的 / 全部替换为 - 计算得出,分支名要求恰好包含一个 /;若分支已存在(本地或远端)会询问覆盖或使用数字后缀,绝不静默覆盖;然后 git checkout -b <name> origin/<target>。

阶段 D cherry-pick:squash 时用 git merge --squash 并提交,否则按顺序 git cherry-pick。冲突策略较宽松但安全:仅自动解决 import 顺序、纯格式差异、非重叠新增、单侧纯删除等简单情况,并在暂存前用 git diff --check 与 grep 校验;遇到语义重叠、双方实质性修改同 hunk、版本/锁文件变更、生成文件等模糊情况会停下让用户在手动解决、放弃、squash 重试之间选择,并记录每个冲突及其解决方式。

阶段 E 本地校验(推荐):询问用户是否运行校验,默认是。按仓库标准依次执行 npm install、npm run build、npm run l10n、npm run prettier-fix、npm run lint,并将重新生成的 bundle 作为单独的 chore 提交。当 cherry-pick 改动了英文 l10n bundle 且源 PR 已合并时,从来源基分支仅拉取受影响键的翻译,不整体替换语言文件,保留原有行尾与键顺序,再以 chore 提交。校验失败会展现错误并停止,修复视为新一轮冲突解决。若跳过校验,会在 PR 正文中注明 CI 为第一道校验关卡。

阶段 F 推送并创建 PR:git push -u origin <branch>,绝不使用 --force 或 --force-with-lease;PR 正文先写入文件再用 --body-file 传入,标题以目标分支方括号开头,正文包含 Backport of、原 PR 描述和 Conflicts resolved 小节,且要求真实换行、不硬折行、不使用任务清单复选框。

阶段 G 清理:成功时切回原分支并按需恢复 stash,打印新 PR URL;失败或用户中止时保留分支与 stash 并打印恢复命令。

约束与限制 来源自身的基分支不能作为目标;绝不使用 force 推送;cherry-pick 时保留原始提交信息;不修改冲突解决或修复校验失败所需之外的文件;不静默覆盖已存在分支;不自动解决模糊冲突;失败时不恢复 autostash;本地运行使用 backport/ 前缀,仅在云代理使用 copilot/。在 GitHub Copilot 云代理中运行时会禁用交互提示,无法暂停询问用户,缺失或含糊的必需输入会停止并报告;同时 gh auth status 失败不会中止 backport,因为云端 git 推送认证来自平台凭据助手而非 gh。