PR Writing

让首次接触这次变更的评审者理解它解决什么问题、如何影响使用者，以及哪些地方需要重点审阅。

关联与关闭 issue

• issue 引用必须有可核对的来源。PR 完整解决并应关闭 issue 时，在正文使用 Closes #<number> 或 Fixes #<number>；跨仓库使用 Closes owner/repo#<number> 或 Fixes owner/repo#<number>。仅关联背景使用 Refs。
• 部分完成、仍有待办或待验收时，只使用普通关联，不使用关闭关键词，保持 issue 开放。
• 合并后核查对应 issue 的状态和验收条件；全部验收条件已满足但 issue 仍开放时，按当前任务授权关闭；未完成或待验收时保持开放。

先确定说明对象

• 读取适用的 AGENTS.md、CONTRIBUTING.md 和 PR 模板。遵守仓库的格式、语言与交付规则；未指定语言时，标题用英文，正文用中文。
• 确认 PR 的目标分支与当前 head，以完整分支差异确定说明范围，结合现有 PR 文案、提交消息和关联 issue 理解背景。
• 对堆叠 PR，区分本次新增变化与父分支已有变化。描述远端 PR 当前内容时，以远端 head 为准；本地待提交的改动单独标明。
• 用已读取的代码、记录和明确背景支撑动机、验证结果与兼容性说明。信息有限时，说明已查看的范围和待核实事项。

默认输出规范

仓库已有约定时沿用其规范；其余情况按下面的标题规则和正文结构组织。

标题

使用 type(scope): concrete change。前缀中的 type 和 scope 用小写，描述概括当前整份变更的主要结果。

• type 按主要结果选择：feat 新增能力、fix 修复缺陷、refactor 重构、perf 性能优化、docs 文档、test 测试、build 构建或依赖、ci 持续集成、chore 其他维护、revert 回退。
• scope 使用受影响的模块或能力名称，例如 auth、catalog。当范围已由描述清楚表达，或变更跨越多个模块时，可省略 scope。
• 描述默认使用英文，以小写的动词原形开头，写清具体对象和结果。专有名称和标识符保留原本的大小写，例如 API、GitHub；保持单行，句末省略句号。
• 破坏兼容性的变更，在 type 或 scope 后加 !，并在正文交代影响和迁移方式。

例如：feat(auth): add passkey login、fix(catalog): preserve metadata during retries、docs: clarify local setup。

正文

默认使用“背景／主要改动／验证”三节。将模板中的提示替换为本次变更的事实，按实际内容取舍条目。

正文中，中文、英文和数字相邻时必须用空格隔开，例如“调用 API 2 次”；代码、标识符和链接保持原有写法。

## 背景

[当前问题或缺口，以及本次变更要达成的结果。]

## 主要改动

- [具体行为变化及对使用者的影响。]
- [有助于评审的设计选择、理由与取舍。]

## 验证

- [已执行的检查：覆盖范围、环境与实际结果。]
- [尚未验证的范围及原因，必要时补充后续验证方式。]

写清变化与理由

开头交代原来的行为或缺口，再说明这次产生的具体结果。涉及多处实现时，按能力、行为或责任划分组织内容，把相关文件的改动汇总成评审者关心的行为变化。涉及兼容性或关键契约时，同时说明需要保持的行为。

有重要设计选择时，说明选择了什么、为何适合当前约束，以及相关代价或保留风险。方案比较聚焦实际考虑过、且有助于评审的选项。

术语应帮助评审者定位问题。例如描述并发控制时，说明它保护的行为或约束，再补充实现术语。把失败、取消、重试和恢复行为放在相关设计说明中，把这些行为的测试覆盖情况放在验证部分。

按变更规模组织

• 小改动可以用一小段交代问题、结果与必要验证，保留仓库模板要求的栏目。
• 常规功能或缺陷修复使用上述三节；复杂变更可按评审需要增加分节。
• 涉及 API、数据格式、权限或存储契约变化时，说明受影响的使用方、兼容性与必要迁移。
• 跨模块变更可提供简短的评审顺序。图示、前后对比和示例只在能降低理解成本时加入。
• 有可见 UI 变化时，尽量在 PR 正文中提供评审者可访问的前后截图，确保页面、状态、视口尺寸和数据可比。标注 Before/After、比较基线与当前评审 head；桌面和移动端表现有实质差异时分别覆盖。 截图随最终实现更新，发布前遮去敏感信息。缺少真实基线或可供评审者访问的截图时，说明限制，只展示实际取得的证据。

让验证结论可判断

保留影响评审判断的证据：覆盖了什么行为、使用什么测试环境、结果如何，以及哪些范围仍未验证。例如，应区分模拟服务测试与真实服务互通。

引用实际执行记录或当前 CI 状态，分别表述已通过、失败、进行中、明确跳过和尚未运行；跳过时说明原因。让每项结论对应证据实际覆盖的范围，并将后续验证计划单独列出。将已解决的问题与已接受但仍存在的风险分开说明。

PR 正文概括代码变更、设计理由与关键验证结论。任务历史、重要进展和操作证据留在 issue 或指定任务记录，详细日志与运行产物保存在任务目录。任务同时有 issue 和 PR 时，在两处互相链接，避免重复整份记录。仅在精确命令有助于复现问题或验证特殊行为时保留命令。

更新与交付

• 实现范围或设计发生实质变化后，重新检查整份标题和正文，整合成对最终结果的连贯说明。
• 评估说明质量时，给出总体判断和重要的可执行建议，并明确评价覆盖的范围。涉及实现正确性的结论，以相应的代码审查和验证证据为依据。
• 按当前任务约定交付文案或评价。执行提交代码、推送、发布、修改远端 PR 或合并等操作前，核对该操作是否在授权范围内；已有明确授权时直接执行。
• 获准发布或更新后，回读远端标题、正文、base/head 和附件，确认渲染正确且内容对应当前变更。