write-pr-description

编写 PR 描述

根据当前更改准备标题和正文，使用仓库的 PR 模板或 默认模板。发布前先展示文本。

默认仅起草，无需 gh 或网络访问。用户要求打开、创建或提交 PR 时，使用创建模式；文本获批后，还包括任何必要的推送操作。

第 1 步 — 检查未提交的任务文件

读取 git status --short，包括未跟踪文件。识别属于任务的文件；不要动无关更改，并简要列出这些更改。如果范围不明确，请询问。

在创建模式下，如果任务文件尚未提交，请展示其路径并询问： “有未提交的任务文件。准备 PR 前要先提交这些文件吗？” 停止并等待。 仅批准创建 PR 并不代表也批准提交这些文件。

• 如果用户同意，只暂存并提交这些文件，包括预期提交的未跟踪文件。两项操作都使用明确路径；git commit --only 可将其他已暂存文件排除在提交之外。参见限定范围提交示例。
• 如果用户拒绝，则保留这些文件不变，并停止创建。
• 在仅起草模式下，描述预期更改，不要暂存或提交。

第 2 步 — 阅读更改

按以下顺序确定基准分支：

1. 用户或调用工作流指定的基准分支。
2. 分支现有 PR 的基准分支（如有），或当前任务上下文。
3. git symbolic-ref --short refs/remotes/origin/HEAD，否则使用 origin/master，再否则使用 origin/main。

分支基准使用 origin/<name>，并保留包含 / 的名称。 如果上游指向另一个分支，则将其作为基准提示，在回退前确认； origin/<current branch> 不是基准分支。如果回退结果指向错误的发布或维护分支，请询问基准分支。

设置 MB=$(git merge-base <base> HEAD)。在同一范围内读取文件列表和完整差异：

• 已提交的更改（包括第 1 步之后的创建模式）：git diff <base>...HEAD。
• 包含未提交任务更改的草稿：git diff $MB，并完整读取任务的未跟踪文件。

在该范围内使用 --name-status 和 --stat。必要时阅读周边代码，并从描述中排除无关的本地编辑。如果没有任务更改，请说明没有可描述的内容并停止；空差异并不意味着基准分支有误。

第 3 步 — 选择模板

在 .github/、仓库根目录或 docs/ 下查找 PULL_REQUEST_TEMPLATE.md 或其小写形式，并查找其 PULL_REQUEST_TEMPLATE/ 目录中的模板。 如果有多个同样适用的模板，请询问使用哪一个。

从工作树中读取模板。保留其标题、顺序和检查清单措辞； 用实际内容替换作者说明，并保持所有复选框未勾选。 如果没有模板，则使用默认模板： Purpose、Approach，以及可选的 Implementation details，不含检查清单。

步骤 4 — 撰写描述

根据所做更改，写一个简短的句式标题，长度大致不超过 80 个字符。 使用用户指定的 Jira 键、任务提交主题开头的 Jira 键，或作为分支片段出现的 Jira 键 （BF-1523、MODUSERSKC-12）。如果这些来源互相冲突，只询问一次。普通文本中的 UTF-8 或 HTTP-413 等字符串不是工单标识符。 如果有确定的键，使用 KEY: <summary>，并在正文中加入该键的 Jira 链接。 如果没有确定的键，使用普通标题并省略链接；无需提问。

用问题和最终行为填写所选模板。使用默认模板时，Purpose 写 1–2 句话，Approach 写 2–3 句话；如果更改包含多个重要部分，再添加简短的实现要点。技术名称和说法应有代码依据。 仅当本次会话中已观察到验证结果或用户已提供验证结果时，才提及验证。

检查正文是否符合所选模板并准确反映更改。 对于仅起草的请求，展示标题和正文后即停止。对于创建模式，继续执行步骤 5。

步骤 5 — 确认并创建 PR

调用 GitHub 前，检查目标仓库中的有效 gh auth status；本地 .envrc 可能会覆盖账号。如果认证不可用或账号与预期不符，则提交描述并说明阻碍。

通过 git branch --show-current 读取当前分支。创建 PR 需要一个与基分支不同的命名功能分支。通过 git ls-remote origin "refs/heads/<current branch>" 检查远程实际分支头，并将其与 git rev-parse HEAD 比较。 如果远程分支不存在，或本地提交领先于远程，则需要推送。 如果远程分支已发生分歧，则停止并报告，不要强制推送。

展示最终标题和正文，说明是否需要推送，并询问“创建 PR 吗？” 等待用户批准这段文本。此批准也包含推送当前分支所需的授权；不要另外询问是否允许推送。 如果完全相同的预览已获批准，则重复使用该批准。

如果在等待批准期间任务文件、HEAD、基分支或模板发生变化，则重新检查受影响的步骤并展示更新后的预览。否则，无需重复准备工作，继续执行。

仅在需要时推送，并明确指定目标：

git push origin "HEAD:refs/heads/<current branch>"

然后将已批准的正文写入仓库外部的文件，再创建 PR：

gh pr create --base <base branch name> --head <current branch> --title "<title>" --body-file <path>

从基分支名称中仅移除开头的 origin/；保留其余部分中的 /。 显式指定 --head，以避免 gh 隐式推送。 返回 PR URL。如果推送或创建失败，则停止并返回描述，同时说明阻碍。

限定操作范围

不要运行构建、测试、代码检查或生成器，也不要编辑 NEWS.md。不要切换分支、 暂存更改、重置、清理、强制推送、更改 Git 配置，或绕过被拒绝的钩子／权限。 PR 文本中绝不能包含机密信息或工具署名。