create-pull-request

用途

create-pull-request 用于在符合项目规范的前提下创建结构良好的 GitHub Pull Request（PR）。当用户要求创建 PR、提交变更以供审阅，或打开 pull request 时使用该技能。它会引导用户完成从环境检查到 PR 创建、再到创建后处理的完整流程。

使用前提检查

技能开始前会进行以下验证：

检查是否安装 gh CLI：

gh --version

若未安装，会提示用户安装。macOS 可使用 brew install gh，其它平台参考 https://cli.github.com/ 。

检查是否已通过 GitHub 身份认证：

gh auth status

若未认证，会引导用户运行 gh auth login。

git status

若存在未提交的变更，会询问用户是将其作为本次 PR 的一部分提交、临时 stash，还是丢弃（需谨慎）。

收集上下文

识别当前分支：

git branch --show-current

确保不在 main 或 master 分支上；若是，会请用户创建或切换到功能分支。

查找基础分支：

git remote show origin | grep "HEAD branch"

通常是 main 或 master。

分析与本次 PR 相关的近期提交：

git log origin/main..HEAD --oneline --no-decorate

通过提交理解：引入了哪些变更、PR 的范围（单一功能/修复还是多项变更）、是否需要 squash 或重排提交。

查看差异：

git diff origin/main..HEAD --stat

用于显示变更文件并帮助判断变更类型。

信息收集

创建 PR 前需要以下信息，技能会尝试从提交信息、分支名（如 fix/issue-123、feature/new-login）、变更文件及其内容中推断。若关键信息缺失，会使用 ask_followup_question 向用户询问：

关联 issue 编号：在提交信息中寻找 #123、fixes #123 或 closes #123 等模式。
描述：解决了什么问题？为什么做这些变更？
变更类型：bug 修复、新功能、破坏性变更、重构、外观、文档或工作流。
测试方式：如何测试？可能破坏什么？

若未找到 issue 编号，会提出澄清问题，例如：在提交信息或分支名中未找到关联 issue 编号，本 PR 对应哪个 GitHub issue？请输入 issue 编号，如 "123"，小型修复可输入 "N/A"。

Git 最佳实践

创建 PR 前，技能会考虑以下实践：

提交整洁：

原子提交：每个提交代表单一逻辑变更
清晰的提交信息：尽量遵循约定式提交格式
无合并提交：优先 rebase 而非 merge，保持历史干净

分支管理：

按需 rebase 到最新 main：

git fetch origin
git rebase origin/main

适当 squash：如果有许多小的 WIP 提交，可考虑交互式 rebase：

git rebase -i origin/main

仅当提交看起来杂乱且用户熟悉 rebase 时才建议。

推送变更：

确保所有提交已推送：

git push origin HEAD

若分支曾 rebase，可能需要：

git push origin HEAD --force-with-lease

创建 Pull Request

重要提示：需读取并使用 .github/pull_request_template.md 处的 PR 模板。PR 正文格式必须严格匹配模板结构，不得偏离。

填写模板时：

将 #XXXX 替换为实际 issue 编号，若无 issue（小型修复）则保留为 #XXXX
用从提交和上下文收集的相关信息填写所有部分
勾选合适的 "Type of Change" 复选框
完成适用的 "Pre-flight Checklist" 项

使用 gh CLI 创建 PR：

为避免 shell 转义、换行及命令行不稳定问题，使用临时文件存放 PR 正文：

将 PR 正文写入临时文件：

/tmp/pr-body.md

使用该文件创建 PR：

gh pr create --title "PR_TITLE" --body-file /tmp/pr-body.md --base main

清理临时文件：

rm /tmp/pr-body.md

创建草稿 PR：

gh pr create --title "PR_TITLE" --body-file /tmp/pr-body.md --base main --draft

为什么用文件？直接通过 --body 传递含换行、特殊字符和复选框的复杂 markdown 容易出错，--body-file 标志能可靠处理所有内容。

创建后处理

创建 PR 后：

显示 PR URL，方便用户审阅
提醒 CI 检查：测试与 lint 会自动运行
建议后续步骤：

按需添加审阅者：

gh pr edit --add-reviewer USERNAME

按需添加标签：

gh pr edit --add-label "bug"

错误处理

常见问题：

相对 main 无提交：分支没有可提交的变更。询问用户是否本意是在其它分支工作。
分支未推送：远程没有该分支。先推送分支：git push -u origin HEAD
PR 已存在：该分支的 PR 已存在。显示现有 PR：gh pr view，并询问是否改为更新它。
合并冲突：分支与基础分支冲突。引导用户解决冲突或 rebase。

总结检查清单

最终创建前确保：

gh CLI 已安装并认证
工作目录干净
所有提交已推送
分支与基础分支同步
已识别关联 issue 编号，或使用占位符
PR 描述严格遵循模板
选择了合适的变更类型
Pre-flight 检查清单项已处理

适用场景与限制

适用场景：在为遵循特定模板与提交规范的项目创建 GitHub PR 时使用，尤其适合希望自动化上下文收集、模板填充与 gh CLI 调用的团队。

限制：该技能依赖 gh CLI 与已配置的 GitHub 远程仓库；需要项目存在 .github/pull_request_template.md 才能严格匹配模板。关于收费、价格等信息资料中暂未提供。