gs-pull-request 是一个面向 GitHub 工作流的技能,用于为当前分支打开一个草稿拉取请求(draft pull request)。它的核心目标是让拉取请求的描述能够被没有参与改动的读者读懂,这些读者可能是其他工程师、评审者,或将要操作该结果的队友。
用途
该技能在用户输入 "/gs-pull-request" 或要求创建拉取请求时触发。它为当前分支创建一个草稿 PR,并撰写一份自包含的描述。
使用方式与前置检查
该技能不会提交代码。当工作区存在未提交改动(dirty tree)时,它会停止并提示用户先运行 /gs-git-commit。如果调用方明确禁止提问,则把脏工作区视为阻塞,同样不提交。
在撰写描述之前,它会分别执行以下 shell 命令:
git status --porcelain git branch --show-current git symbolic-ref --short refs/remotes/origin/HEAD git fetch origin git log --oneline origin/<base>..HEAD git diff origin/<base>...HEAD --stat
基准分支为远端的默认分支,通过 symbolic-ref 得到 origin/<base>。若该调用失败,则使用 git remote show origin;两者都失败时使用 main。比较对象是 origin/<base> 而非本地分支,因为本地分支可能落后于远端。仓库若存在 GLOSSARY.md,会读取并使用其中的名称。
描述结构
描述采用固定结构,包含以下部分:
- What changed:用两三句话说明合并后用户、操作者或系统会有何不同。
- How it works:一段简短说明,并配一张最小的示意图。示意图可选用伪代码、调用树、组件树、浅层文件树、Mermaid 序列图或流程图、diff 草图等,取决于变更重点。若安装了 gs-show-me 技能则用它来选择和绘制。描述只包含 Markdown,不写 HTML 文件。
- Evidence:展示前后对比。可见的 UI 变更适合用截图;否则展示命令、测试或输出,并指出之前失败、现在通过的具体检查。若未运行任何内容,写 Not run 并指出能验证变更的检查,不得编造输出。
- What could break:包含 Door(单向或双向,说明回滚是否足够)、Reach(若出错会影响哪些调用方、数据或人员)、Depends on(使变更安全的关键事实及 file:line,并说明验证程度)、Left open(每个剩余风险,或写 None found.)。
- How to check:给出评审者可运行的最小步骤。
写作规则
若安装了 gs-unslop 技能,则通过它撰写正文;否则遵循以下规则:标题使用句首大写、直引号、不使用长破折号或 emoji、指明行为主体、不写对任何其他变更也成立的句子。不添加 AI 署名脚注。
创建流程
当由人调用 /gs-pull-request 时,先打印标题和正文并等待批准,应用用户要求的修改后再次展示修改后的正文。当调用方表示不要提问时,直接创建 PR。若远端没有该分支则推送:
git push -u origin HEAD
不使用 force-push。若 gh pr view 已找到该分支的 PR,则用 gh pr edit 更新,而不是再开一个。否则将正文写入仓库外的文件,并通过 --body-file 传入,避免描述成为 shell 语法:
gh pr create --draft --title "<title>" --body-file <file>
标题采用约定式提交主题,格式为 type: what changed,类型包括 feat、fix、chore、docs、refactor、test、style。默认创建草稿,仅在用户要求时创建就绪 PR。最后单独一行打印 PR 的 URL。
错误处理
当 push 或 gh 失败时,说明命令和错误,在重试前检查远端分支和已有 PR,复用已存在的 PR。
适用场景与限制
适用于需要为当前分支创建结构清晰、评审友好的 GitHub 草稿 PR 的开发者。限制包括:不负责提交代码,脏工作区会被阻塞;不进行 force-push;描述中不得包含密钥、令牌、本地绝对路径和隐私细节;不得编造调用方、测试结果或 API。