---
title: "PR 摘要工作流"
description: "用 GitHub Copilot 生成 PR 摘要草稿，再由作者补齐背景、风险、测试和回滚。"
verifiedAt: "2026-05-06"
---

PR 摘要不是给作者看的，是给 reviewer、未来排障的人和发布负责人看的。Copilot 可以生成第一版，但作者必须把业务背景、风险和验证补全——把 Copilot 摘要原样提交，等于把"用户影响 / 风险 / 测试 / 回滚"四件事甩给下一个看 PR 的人。

> [!NOTE]
> GitHub 官方说明：PR summary 可以在 description field 或 comment field 里生成；为了更好结果，最好从空白描述开始，因为 Copilot 不会把已有描述内容纳入生成依据。

## 1. 摘要结构

一份能用的 PR 摘要至少包含 5 块：

```md
## What changed
- ...

## Why
- ...

## Risk
- ...

## Tests
- ...

## Rollback
- ...
```

如果团队只允许短摘要，也至少保留 What changed、Risk、Tests。没有风险和测试说明的摘要，只是 changelog。

## 2. 工作流

```mermaid
flowchart TD
    Diff["PR diff"] --> Blank["保持 description 空白"]
    Blank --> Generate["Copilot Summary"]
    Generate --> Author["作者人工补充"]
    Author --> Verify{"对照 issue / diff / tests"}
    Verify -->|缺背景| Author
    Verify -->|缺风险| Author
    Verify -->|通过| Publish["Create PR / Update comment"]
    Publish --> Reviewer["Reviewer 快速进入上下文"]

    style Generate fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Author fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Publish fill:#dcfce7,stroke:#16a34a,stroke-width:2px
```

## 3. 生成前准备

先确认 PR 本身已经有基本卫生：

- 分支只包含本次任务相关提交。
- PR 标题说明具体行为，不写“fix”或“update”。
- diff 没有混入格式化、调试日志、临时文件。
- 测试命令已经跑过，失败项有解释。
- issue、设计说明或截图已经准备好。

Copilot summary 是压缩上下文，不是清理混乱 diff 的工具。diff 越杂，摘要越容易泛化。

## 4. 生成后人工补齐

Copilot 生成后，作者逐项补齐：

1. **What changed**：按用户可感知行为、接口、数据、UI 或配置说，不按文件流水账说。
2. **Why**：链接 issue 或说明业务原因，避免 reviewer 重新猜需求。
3. **Risk**：写可能受影响的路径、兼容性、数据迁移、权限、性能和断点。
4. **Tests**：写真实执行过的命令、手动验证和没有覆盖的项。
5. **Rollback**：说明能否 revert、是否涉及数据回滚、是否需要配置开关。

示例补充 prompt：

```txt
把这份 PR 摘要改成
reviewer 可用版本。

要求：
- 保留 Copilot 生成的事实。
- 不要编造未发生的测试。
- 按 5 段结构重排。
- 覆盖断点、权限和回滚。
- 测试只写我提供过的命令。
```

## 5. Reviewer 视角检查

提交前按 reviewer 视角读一遍：

- 我能否 30 秒内知道这次改了什么？
- 我能否知道应该重点 review 哪些风险？
- 我能否找到测试证据？
- 如果上线出问题，摘要能否帮助快速 revert 或定位？
- 摘要有没有把 Copilot 猜测当事实？

<details>
<summary>深读：什么时候用 comment field</summary>

如果 PR description 已经包含团队模板、发布说明或人工写好的完整内容，可以让 Copilot 在 comment field 生成摘要草稿，再手动摘取有价值的部分。

不要让 Copilot 覆盖已经人工确认过的发布信息。
</details>

## 本章自检

1. 是否从空白描述生成，或在 comment field 里生成草稿？
2. 是否人工补齐背景、风险、测试和回滚？
3. 是否对照 diff、issue 和测试结果核验事实？
4. 是否删除了“看起来合理但没有证据”的句子？
5. 是否让 reviewer 知道重点看哪里？

通过标准：摘要能缩短 reviewer 进入上下文的时间，同时不牺牲事实准确性。

## 官方来源

- [Creating a pull request summary with GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/create-a-pr-summary) —— GitHub 官方 PR summary 使用说明。
- [GitHub Copilot documentation](https://docs.github.com/en/copilot) —— GitHub 官方 Copilot 文档总入口。

## 接下来去哪

<Cards>
  <Card title="代码审查工作流" description="摘要完成后，用 Copilot review 预筛风险。" href="/docs/github-copilot/official/10-practical-playbooks/code-review" />
  <Card title="Cloud Agent review" description="异步任务完成后也要做 PR 摘要和 review 闭环。" href="/docs/github-copilot/official/04-cloud-agent/review-output" />
</Cards>
