pull-request git:20260919.361331bA

Immutable. This exact content never changes and is served at /api/v1/blob/921c786add9dc978.

---
name: pull-request
description: 创建 GitHub PR、更新标题或正文、填写 PR 模板，或准备人工发布内容时使用；不用于代码审查和 CI 修复。
compatibility: 需要 git。远程创建或更新需要网络访问，以及可用的 GitHub 连接器或已认证的 gh CLI。
---

# 创建或更新拉取请求

依据真实分支、差异、提交、验证结果、关联工作和仓库模板，准备准确且便于评审的 PR。不依赖特定 AI 客户端或插件。

## 能力路由

检查当前客户端实际可用的工具，不预设后端：

1. 可用的 GitHub 连接器支持所需读写操作时，使用连接器。
2. 否则使用已认证的 `gh` CLI。
3. 两者均无法执行远程写入时，生成完整标题、正文、基准分支和来源分支信息，以及准确的人工后续步骤。不要声称 PR 已修改。

回退取决于工具能力，不意味着降低内容检查要求。不要仅为了使用本技能就要求用户安装特定插件。

## 范围

适用于：

- 创建普通 PR 或草稿 PR；
- 更新现有 PR 的标题或正文；
- 填写或修复仓库 PR 模板；
- 无法远程写入时，生成可直接发布的 PR 内容。

不用于创建提交、代码审查、修复 CI 或实现代码改动。

## 收集证据

始终先检查本地仓库：

```bash
git rev-parse --git-dir
git status --short
git branch --show-current
git remote -v
git log --oneline -10
```

然后使用选定的 GitHub 工具，确认当前分支是否已有 PR，并读取编号、URL、基准分支、来源分支、标题、正文和状态。远程元数据不可用时，说明限制，不推测任何影响发布的信息。

根据现有 PR、用户明确输入或目标仓库默认分支确定基准分支，不要硬编码 `main`。条件允许时获取选定基准分支，再检查：

```bash
git log <base-remote>/<base-branch>..HEAD --oneline --no-decorate
git diff <base-remote>/<base-branch>...HEAD --stat
git diff <base-remote>/<base-branch>...HEAD
```

起草或修改标题和正文前，阅读 [PR 内容规则](references/pr-content.md)。

## 可评审性

准备 PR 时检查：

- TL;DR、风险、验证入口和 reviewer 关注点是否与实际 diff 一致；不要用泛化描述掩盖未验证的行为。
- 将核心逻辑、机械重命名、生成文件和格式化变更分开说明；如果改动过大，优先拆分而不是靠正文解释降低评审成本。
- 说明迁移顺序、rollout/回滚条件、兼容性影响和未覆盖场景；每个关键结论都指向 commit、测试、日志或运行面证据。
- 只有用户明确授权时才改写历史或 force-push。改写前记录原始 tree，改写后确认目标 tree 未发生意外变化。

## 流程

### 创建

1. 确认存在有意义的已提交差异，并确定基准分支和来源分支。
2. 来源分支已有 PR 时复用该 PR，不重复创建；先核验其 head 是否包含本次目标提交，不能把旧的远端状态直接当作本次交付结果。
3. 根据证据编写标题和正文，并保留仓库模板。
4. 当前会话已有对目标分支的明确推送授权时，核对远端差异并推送所需提交，远端分支已存在不阻止已授权的更新。没有明确推送授权时，仅保留“用户请求创建 PR 且远程尚无该分支”这一首次发布例外；不得据此更新已有远端分支。缺少必要授权时先准备完整内容，只暂停依赖该推送的步骤。
5. 通过选定工具创建 PR；已有 PR 则按更新流程处理当前授权范围内的内容。只有用户要求草稿或改动明确尚未准备好评审时，才使用草稿状态。
6. 重新读取创建或复用的 PR，验证编号、URL、基准分支、来源分支、标题、正文和草稿状态，并确认 head 是否包含本次目标提交；未发布的提交须明确报告。

### 更新

1. 读取现有 PR 和当前差异，不根据过期的本地假设重写。
2. 保留仍有效的上下文、模板章节、问题链接、迁移说明和评审指引。
3. 只修改用户要求或有证据表明已过期的内容。
4. 通过选定工具更新，再重新读取 PR，验证最终标题和正文。

### 无远程写入能力

返回：

- 已确认或明确标记为未验证的基准分支和来源分支；
- 最终标题；
- 完整正文，而非摘要；
- 是否使用了模板；
- 若 `gh` 可用于人工操作，提供准确的 `gh pr create` 或 `gh pr edit` 命令；否则提供简洁的 GitHub 界面操作说明；
- “远程更新：未执行”。

## 安全与准确性

- 不编造测试、问题链接、迁移状态、评审者或部署结果。
- 不隐瞒破坏性变更、配置变化、已知风险或无关差异。
- 不重复创建 PR，也不悄悄更改基准分支。
- 不用 PR 措辞掩盖过大或不自洽的改动；评审难度受到明显影响时，建议拆分。
- 生成标题和正文不代表远程已经更新。报告实际使用的后端和重新读取的结果。

## 输出

```text
操作：已创建 / 已更新 / 仅准备内容
PR：#<number> <url> / 未创建
基准分支：<base>
来源分支：<来源分支版本>
后端：连接器 / gh / 无
模板：已使用 / 未找到
验证：<重新读取的结果或限制>
```