pr-description-writer

PR 描述撰写工具

读取当前分支差异，并撰写完整的 GitHub 拉取请求描述。使用一条命令创建或更新 PR。

写作风格

所有生成的 PR 描述都应遵循以下风格：

• 使用主动语态。“添加 X”，而不是“X 已添加。”
• 摘要使用现在时（“添加缓存层”），背景说明使用过去时（“旧方案导致每次渲染都发送 N 个请求”）
• 句子简短，每条项目符号只表达一个要点
• 不使用长破折号，改用逗号或句号
• 不要使用填充语：“此 PR”“此提交”“根据讨论”
• 具体描述优于泛泛而谈：“将 p95 延迟从 800ms 降至 90ms”优于“提升性能”

---

步骤 1：检查设置

确认 gh 已通过身份验证：

gh auth status

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

确认当前目录是具有活动分支的 git 仓库：

git branch --show-current

如果处于分离 HEAD 状态或没有分支，请停止并询问用户要描述哪个分支。

---

步骤 2：收集差异上下文

运行以下三条命令来收集上下文：

文件摘要（改动内容）：

git diff main...HEAD --stat

提交消息（改动原因）：

git log main...HEAD --oneline

完整差异（改动方式）：

优先使用 origin/main（始终保持最新），如果不可用，再依次使用本地 main 和 master：

if git rev-parse origin/main &>/dev/null 2>&1; then
  BASE=origin/main
elif git rev-parse main &>/dev/null 2>&1; then
  BASE=main
else
  BASE=master
fi
git diff $BASE...HEAD

如果差异很大（超过 500 行），只阅读 --stat 摘要和提交消息。同时阅读差异的前 200 行，以了解主要改动，而不处理整个输出。

还要检查是否已有 PR，并阅读其当前标题和正文：

gh pr view --json title,body,baseRefName 2>/dev/null

---

步骤 3：阅读格式指南

在撰写任何内容之前，完整阅读 references/pr-format-guide.md。熟悉以下内容：

• 必需的章节及其顺序
• 每个章节的写法
• 应包含和省略的内容
• 测试章节的格式

---

步骤 4：生成描述

使用 references/pr-format-guide.md 中的格式撰写 PR 描述。

规则：

• “改动”章节中的每条项目符号都必须有差异中的内容作为依据
• 不要编造代码改动未暗示的测试步骤
• 如果某个章节没有相关内容，请完全省略（不要写“N/A”或留空）
• 截图章节：仅在差异中存在可见的 UI 改动时才添加
• 如果提交消息说明了“原因”，请在摘要中采用相关背景

QA 检查点： 提交前确认：

• 摘要为 1 至 2 句话，使用主动语态，不含填充语
• 每条改动内容都具体且有差异作为依据
• 没有编造的指标或结果
• 测试步骤可执行（读者能够照着操作）
• 所有行都不含长破折号

---

步骤 5：创建或更新 PR

向用户展示描述，并询问：“准备创建 PR、更新现有 PR，还是仅输出内容？”

创建新 PR：

通过 stdin 传递正文，以安全处理反引号、引号和换行符：

gh pr create --title "TITLE_HERE" --body-file - << 'EOF'
BODY_HERE
EOF

根据提交消息和差异摘要建议一个标题。标题应使用祈使语气且少于 72 个字符：“为用户会话查询添加 Redis 缓存”，而不是“已添加缓存”。

更新现有 PR：

gh pr edit --body-file - << 'EOF'
BODY_HERE
EOF

仅输出： 在代码块中展示标题和正文，方便手动复制粘贴。

创建或更新后，确认：“PR 描述已更新。查看地址：[URL]”