open-pr

流程

1. 确认状态

检查工作树、当前分支，以及该分支是否已有未关闭的 PR：这三项决定了你要创建分支、打开 PR，还是直接更新。

如果 PR 已存在，而且你是因为后续工作已提交而来到这里，而不是用户提出了请求，那么只有在新提交导致标题或正文过时（即它们已无法说明范围、方法或背景）时才刷新内容。

未提交的更改也属于工作内容：无论处于哪种状态，都要先按 /commit 提交，再开始撰写。完成标准：工作已提交到非默认分支，并且你已确认基础分支和 PR 是否存在。

2. 阅读分支

整体检查分支内容——git diff <base>...HEAD 和 git log <base>..HEAD——了解改了什么、为什么改，以及用户能看到哪些不同。完成标准：你已理解并掌握分支上的每个提交。

3. 撰写内容

先加载 /humanize：标题、描述和评论中的每个字都必须遵循其要求。

根据刚刚阅读的分支内容重新撰写标题和描述，无论 PR 是新建还是已打开，都遵循下方格式。如果仓库提供 PR 模板（例如 .github/pull_request_template.md），则以模板结构为准，并将此处的章节指南应用于模板中的相应部分。

更新现有 PR 时，保留用户提供的内容：沿用 Evidence 内容和 To-do 项（包括复选框状态），并合并新增内容。

也在此处拟好内联评论：这些评论应与描述基于对分支的相同理解。

接下来，在同一次 AskUserQuestion 调用中向用户提出两个问题，但只询问当前适用的问题：

• Evidence——当 Overview 描述了用户可见的内容，且本次会话中没有截图或录屏时：现在采集证据、使用用户指定的文件，或跳过。
• Annotation——当你拟好了评论时：将其随 PR 发布，还是保持 diff 不变。说明评论内容。

--capture 和 --annotate 可预先确定这两个问题的答案，带 --no- 前缀的对应选项则可预先选择另一种处理方式。使用标记会跳过提问，但不代表跳过判断：如果没有值得采集的内容，或没有值得添加的评论，就不要采集证据或添加评论。

在 PR 创建前采集证据，以便 PR 创建后内容完整；如果采集失败，继续后续流程即可。无论结果如何，都要关闭采集过程中启动的浏览器会话或应用进程。

完成标准：标题及所有当前适用的章节均已拟好，证据文件已保存到磁盘，并且已确定要发布哪些评论（如果有）。

4. 创建或更新

推送分支，然后创建 PR 或编辑现有 PR，并按 /attach-media 附加 Evidence。如果已知仍有工作会阻碍审核，就将 PR 标记为草稿；否则标记为可审核。仅在确实无法确定时才询问。完成标准：PR 已创建，并且你已报告其 URL。

5. 为 diff 添加评论

如果拟好了评论，就将其作为一次批量审核发布。gh pr review 不支持内联评论，因此应使用 gh api repos/<owner>/<repo>/pulls/<number>/reviews，设置 event: COMMENT，并传入包含 {path, line, side, body} 的 comments[] 数组。更新 PR 时，先检查现有评论（gh api repos/<owner>/<repo>/pulls/<number>/comments），只发布尚无评论的行。完成标准：所有拟好的评论均已发布。

标题格式

<type>(<scope>): <subject>，scope 可选。

• 写出整个分支的主要变更，而不是最新提交的内容。
• 用主题中的动词体现变更：写 expire sessions after 30 days，而不是 update session handling。
• 使用纯文本主题，末尾不加句号。

描述模板

1–2 sentence summary: what the PR does and why.

A reference to the issue(s) this PR closes (`Closes <id>`).

## Overview

Strictly user-facing: what someone using the app sees or experiences differently. Refactors, component restructuring, and other implementation details belong in Changes. For purely internal PRs, keep it brief ("No user-facing changes."). If there's more than one user-facing theme, add a `###` subheading per theme with short prose under each.

## Changes

Open with the **shape** of the change as a whole — the one view a reviewer reads before the diff. Then a `###` subheading per unit of work with short prose under each, carrying the _why_ the Overview leaves implicit; a one-theme PR is a single paragraph.

Reference a commit by its bare short SHA, which GitHub autolinks.

## Evidence

Captures a reviewer can look at, each referenced inline beneath the prose that says what it proves.

## To-do

What a human must do to land or operate this change: run a migration, set an env var, flip a flag, merge a dependent PR first. Short checkbox bullets (`- [ ]`). Work this PR defers or leaves out of scope belongs in the issue tracker; generic local-testing steps don't belong at all.

只有在有内容可填时，才添加 Closes 行、Evidence 和 To-do。

描述以最后一个有效章节结尾。不添加署名页脚、生成说明行，也不添加指向撰写此内容的会话的链接。

图示

图示能一目了然地传达原本需要一段文字才能说明的内容。当改动会改变控制流、引入状态机、在两个以上模块间传递数据、跨服务执行一系列操作，或大范围重组文件时，就应使用图示。单文件改动用文字说明即可。

• Mermaid，置于带围栏的 mermaid 代码块中——用于流程、状态和时序。GitHub 会在正文中渲染它。按照 /artifact-diagramming 绘制：使用真实状态、真实名称、真实分支条件，并为箭头标注其传递的内容。
• 带围栏的文本——用文件树表示职责或大范围重构的结构，用调用树表示运行时顺序，用组件树表示 UI 结构；对于分支重要而语法不重要的逻辑，则使用伪代码。

行内注释

如果审阅者停在某一行时会产生疑问，而 diff 无法解答，就应在该行添加注释：例如说明为何二次循环是安全的边界值、某个标志翻转前一直不会触发的分支，或原因存在于另一个仓库中的变通方案。