SuperAPI AI 工具集

create-pr

编程与开发

查看项目

更新于 10-17 00:15

技能介绍

用途

create-pr 技能用于为当前分支创建 GitHub pull request,并自动生成标题与摘要。适用于用户想要创建 PR、打开 pull request、提交变更以供审查,或推送分支等待审查的场景——即使用户没有明确说出“PR”。

前置条件

需要验证 gh 已安装并认证,运行 gh auth status 检查。如果失败,告知用户运行 gh auth login。

工作流程

1. 了解当前状态

并行运行以下命令:

  • git status - 检查未提交的变更
  • git log --oneline -20 - 近期提交历史
  • git rev-parse --abbrev-ref HEAD - 当前分支名
  • git remote show origin | grep 'HEAD branch' - 检测默认基础分支(通常为 main 或 master)

2. 处理未提交变更

如果存在已暂存或未暂存的变更,询问用户是否希望在创建 PR 前提交它们。未经明确批准不要提交或推送。

3. 处理推送

检查当前分支是否有远程跟踪分支且是否为最新:

git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null

如果分支尚未推送或领先于远程,推送前需询问用户。使用 -u 推送以设置跟踪。

4. 分析变更

该仓库中大部分代码由 LLM 生成,因此审查者更依赖 PR 描述而非差异本身。此步骤的目标是收集足够材料以填充第 5 步模板中的每一个章节——而不仅仅是罗列变更内容。

查看分支上的所有提交,而不仅仅是最新提交:

git log <base-branch>..HEAD                 # 完整消息,不只是 --oneline
git diff <base-branch>...HEAD
git rev-parse --abbrev-ref HEAD             # 分支名通常包含工单 ID

阅读时,有意收集:

  • Why 变更存在的原因(提交消息、分支名、关联工单)
  • How 高层面上如何工作(涉及哪些模块/层,数据/控制流)
  • Non-obvious decisions 非显而易见的决策(审查者可能质疑的任何内容)
  • Behavioral / interface / schema changes 行为/接口/schema 变化(合并后系统的不同之处)
  • What was actually tested 实际测试的内容(查找新增的测试文件,但通过用户/运行历史进行核实)
  • Risks 风险(破坏性变更、迁移、影响范围)

如果没有某个章节的材料,不要编造——该章节在第 5 步中变为 N/A — <one-line reason>。

5. 创建 PR

生成简洁的标题(<70 字符),在高层面上描述变更。

正文必须严格遵循以下模板。所有 8 个章节标题必须按顺序出现。如果某章节确实不适用,在该标题下写 N/A — <one-line reason>——绝不省略标题,绝不让章节为空。

模板(在每个标题下填写):

## Context
Why this change exists. What problem it solves or capability it adds.
Reference the trigger (bug, feature request, incident, refactor goal).
One short paragraph — not a changelog.

## Linked Issues
Linear tickets, GitHub issues, incident IDs, or prior PRs this builds on.
`N/A — <reason>` if none.

## Design
The high-level shape of the implementation. How the pieces fit together,
which modules/layers are touched and in what role, and the data/control
flow for the main path. Aim for what a reviewer would draw on a
whiteboard. Avoid restating the diff line-by-line.

## Key Decisions
Non-obvious choices and the trade-offs behind them. Alternatives
considered and why they were rejected. Anything a reviewer might
otherwise flag as "why did you do it this way?" — answer it here
pre-emptively. `N/A — <reason>` only for trivial/mechanical changes.

## Changes
Logical/semantic changes — not a file-by-file inventory. Focus on:
- Interface changes (new/changed/removed commands, flags, public APIs)
- Schema changes (config, data model, API request/response shapes)
- Behavioral changes (what `cx` does differently now)
Skip mechanical detail (which files moved, which libs bumped) unless
it materially affects reviewers. Rollout concerns (migrations,
breaking-change handling) belong in Risks & Rollout, not here.
Bullet list.

## Testing
How the change was verified. List the exact commands run (unit,
integration, e2e, manual `cx` invocations). If a layer was skipped,
say why. Aspirational tests don't count — only what was actually
executed.

## Risks & Rollout
Backwards compatibility, breaking changes, migrations, feature flags,
performance impact, blast radius if this goes wrong. How to roll back.
`N/A — <reason>` for low-risk changes (e.g. pure docs, isolated
refactor).

## Out of Scope / Follow-ups
What this PR deliberately does *not* do, and any follow-up work that
should land separately. `N/A — <reason>` if the PR is fully
self-contained.

调用方式:

gh pr create --title "the title" --body "$(cat <<'EOF'
## Context
...

## Linked Issues
...

## Design
...

## Key Decisions
...

## Changes
- ...

## Testing
- ...

## Risks & Rollout
...

## Out of Scope / Follow-ups
...
EOF
)"

如果基础分支不是默认分支,传入 --base <branch>。

6. 提交前检查清单

在运行 gh pr create 之前,验证你组装的正文:

  • [ ] 所有 8 个章节标题均按顺序出现:Context、Linked Issues、Design、Key Decisions、Changes、Testing、Risks & Rollout、Out of Scope / Follow-ups
  • [ ] 没有章节为空——每个章节要么有真实内容,要么有 N/A — <reason>
  • [ ] Testing 列出的是实际为此分支运行过的命令,而非通用建议
  • [ ] Changes 描述的是逻辑/语义差异,而非文件清单
  • [ ] Design 在高于差异的层面上说明变更如何工作

如果有任何不通过,在提交前修复正文。

7. 反馈

打印 PR URL,以便用户点击查看。