explain-this-pr

解释此 PR

阅读 GitHub 拉取请求，了解其中的更改，并用通俗易懂的英语进行说明。将说明作为 PR 评论发布，让审核者立即了解背景。

---

步骤 1：检查设置

确认 gh 已完成身份验证：

gh auth status

如果未完成身份验证：运行 gh auth login 并按提示操作。

确认输入。用户必须提供以下任一项：

• GitHub PR URL（例如：https://github.com/owner/repo/pull/123）
• 当前仓库中的 PR 编号（例如：#123）
• 关键词“current”，以使用当前分支对应的 PR

如果没有输入，请询问：“要我解释哪个 PR？请提供 URL、PR 编号，或输入‘current’表示当前分支对应的 PR。”

---

步骤 2：获取 PR 背景信息

获取 PR 元数据：

gh pr view PR_URL_OR_NUMBER --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft

如果 isDraft 为 true，请告知用户：“此 PR 仍处于草稿状态。说明基于其当前状态。”

获取差异：

gh pr diff PR_URL_OR_NUMBER

如果差异超过 400 行，请阅读 --stat 摘要和差异的前 200 行：

gh pr view PR_URL_OR_NUMBER --json files
gh pr diff PR_URL_OR_NUMBER | head -200

获取现有评论（避免重复已有内容）：

gh pr view PR_URL_OR_NUMBER --json comments --jq '.comments[].body' 2>/dev/null | head -20

---

步骤 3：撰写说明

撰写两段内容。写作前请阅读每条规则。

第 1 段：功能说明（技术层面）

• 每项主要更改用一句话说明
• 指明发生更改的具体文件、函数或系统
• 如果差异中信息明确，请说明更改前后的情况
• 如果差异中包含具体数字，请将其写入说明（删除的行数、移除的表、添加的端点）
• 使用主动语态和现在时

示例：

Replaces the in-memory session cache in auth.middleware.ts with a Redis-backed cache (src/cache/redis.ts). Adds get, set, and invalidate methods to the new Redis module and wraps UserService.getById() with a 5-minute TTL. Removes the Map-based cache that was limited to a single process and caused session drift across multiple instances.

第 2 段：意义说明（业务／产品影响）

• 说明哪些人会受益，以及如何受益
• 说明解决了什么问题或降低了什么风险
• 如果提交消息中说明了“原因”，请结合该背景
• 如果差异或提交中没有明确的“原因”，请省略此段，不要猜测

示例：

Users hitting the /api/me endpoint under load were getting inconsistent session data across server instances, causing intermittent 401 errors. This change makes session state consistent across all instances and reduces database load by eliminating one query per authenticated request.

两段均须遵守以下规则：

• 不要使用长破折号，改用逗号或句号
• 不要使用填充语：“此 PR”“此更改”“如你所见”
• 不要虚构结果。只陈述差异或提交消息中直接体现的影响
• 如果 PR 只是纯重构且行为没有改变，请明确说明：“将 X 重构为 Y，未改变可观察到的行为。”
• 总字数少于 150 词

---

步骤 4：自检

发布前，请检查：

• 第 1 段提到了差异中的具体文件或函数
• 没有虚构的指标或结果
• 没有使用长破折号
• 没有填充语
• 总字数少于 150 词
• 如果没有明确的“原因”，则省略第 2 段，不要猜测

如有任何不符合之处，请先修正再发布。

---

步骤 5：作为 PR 评论发布

向用户展示说明，并询问：“要现在将其作为 PR 评论发布，还是先进行编辑？”

确认后，通过标准输入传递正文，以安全处理反引号、引号和换行符：

gh pr comment PR_URL_OR_NUMBER --body-file - << 'EOF'
EXPLANATION_HERE
EOF

发布后：“评论已添加。可在此查看：[步骤 2 中的 URL]”

如果用户说“仅输出”，请将说明放在代码块中展示，方便用户手动复制粘贴，无需发布。