antfu-create-pr

创建 Pull Request

提交一份仅凭正文就能让审阅者理解的 PR。说明行为发生了哪些变化以及原因，而不是列出变更文件。正文篇幅应与变更规模相称：一行修复写几句话，跨模块功能则使用表格和图示。

工作流

1. 检查仓库：git status、当前分支、远程仓库、默认分支、.github/PULL_REQUEST_TEMPLATE*，以及 PR 规则相关的 AGENTS.md / CONTRIBUTING.md。
2. 计算与目标分支的合并基点，并记录 PR 将发布的准确 base...head 范围。如果当前分支基于另一个尚未合并的分支，则以该分支为目标，并只描述本 PR 自身的变更。
3. 阅读完整差异。将运行时代码与生成文件、锁文件和快照区分开。追踪变更代码的入口、调用方和外部边界，确保架构说明有文件路径或符号作为依据。
4. 对 PR 分类（功能、修复、重构、杂项、文档），并判断哪些可选正文部分值得保留。参见 pr-body。
5. 根据变更涉及的部分运行相应检查（针对性测试、类型检查、代码检查）。记录准确的命令和结果。
6. 如果差异改变了用户可见的 UI，请收集变更前后的证据。参见 visual-evidence。
7. 检查提交历史，并将其整理为原子化的 Conventional Commits。参见 提交。
8. 将正文写入临时文件。推送分支。使用 gh pr create --title ... --body-file ... 创建 PR（每张截图都添加 --attach）。如果检查仍在运行或变更尚未达到可供审阅的状态，则使用 --draft。
9. 打开创建的 PR，检查标题、目标分支、源分支、渲染后的表格、图示和图片。
10. 处理审阅意见：修复每个确认的问题，运行针对性检查，推送变更，附上证据回复，并解决对应讨论串。

标题

遵循 Conventional Commits 格式，并与仓库现有的提交消息风格保持一致：

feat(scope): add retry to upload client
fix(scope): avoid double submit on enter
refactor: extract diff parsing from cli
chore(deps): update vite to v8
docs: clarify worktree setup

• 使用小写、祈使语气，不加句末句号，长度不超过约 70 个字符。
• 作用域使用仓库已有的包、模块或功能名称。若变更涉及整个仓库，则省略作用域。
• 使用 Squash merge 的仓库会将标题作为提交消息；请将其写成希望留在历史记录中的提交消息。

提交

每个提交只做一件合乎逻辑的事，并使用 Conventional Commits 格式的消息。审阅者应能从 git log --oneline 中看出变更脉络，并能逐个提交进行审阅。

# Good: each commit is self-contained
feat(api): add task creation endpoint with validation
feat(ui): add task creation form component
feat(ui): connect form to api and add loading state
test(tasks): cover task creation (unit + integration)

# Bad: everything mixed together
feat: add task feature, fix sidebar, update deps, refactor utils

• 不要将无关修复、依赖升级和顺手重构放进此分支；应为它们单独提交 PR。
• 推送前检查历史，并使用 git rebase -i <base> 拆分或压缩本地提交，直到每个提交都能独立成立并通过构建。
• 不要改写已推送且正在审阅的提交；请改为添加新提交。

正文

每个 PR 都必须包含：

• ## Summary：先说明问题或能力，再说明变更内容和采用该方案的原因。如果 PR 基于另一个 PR 堆叠，还要说明这一点及其基准。
• 关联问题：使用 closes #123 / fixes #123 / refs #123，以便 GitHub 创建链接并自动关闭问题。
• ## Verification：列出运行过的准确命令及其结果，并说明任何尚未验证的内容。

仅在有助于审阅时添加以下可选部分：

• ## Change map：使用表格列出模块、变更前、变更后和原因。适用于跨多个模块或职责边界的变更。切勿只罗列文件。
• ## Architecture and behavior：如果变更涉及执行顺序、异步工作或状态转换，则使用 Mermaid 流程图、时序图或状态图。对于修复，应在同一抽象层级下配套提供 Before 和 After 图示。
• ## Boundaries and risks：使用表格列出不变量、故障模式、防护措施和证据。适用于存在实际故障模式、迁移或外部影响的变更。
• ## Visual changes：UI 变更需使用表格展示变更前后的图片。
• ## Rollout and follow-up：说明迁移、功能标志和已知缺口，并注明缺口是否会阻碍合并。

如果仓库有 PR 模板，请保留其标题并填写；仅在模板留有空间时添加上述部分。

规则

• 说明哪些内容已验证、哪些是推测、哪些尚未验证。没有证据支撑时，不要写“安全”“已修复”或“向后兼容”。
• CI 全绿只能证明 CI 运行的检查通过。针对性测试只能证明其覆盖的行为符合预期。
• 不要把从父分支继承的更改描述为此 PR 的更改。
• 使用普通连字符；绝不要使用 em dash（U+2014）或 en dash（U+2013）。
• 不要写空话（“此 PR 旨在……”“全面”“强大”）。句子直接陈述事实。
• 不要在正文中粘贴令牌、机密信息、用户记录或完整负载。
• 不要将截图或其他仅供 PR 使用的文件提交到仓库；使用 gh --attach 附加。
• 如果 PR 是在 Agent 的协助下编写的，请在正文末尾用一行说明。