create-pr

创建 PR

将当前更改发布为已验证且描述准确、可供评审的拉取请求。该请求授权执行仓库声明的门禁、相关提交、PR 元数据更新、一个普通草稿拉取请求或由当前更改持有的、已确认的原生堆栈层、所需的评审和行为测试、范围内的修复，以及转为可供评审的状态。这包括在测试更改时需要用到的项目现有 PR 预览流程。合并和集成交付属于 /deliver；根据交付设置，直接提出的交付请求会继续进入该流程；此请求不会添加无关更改。

检查、评审或 CI 运行失败时，应转入修复流程，而不是停止。仅在没有内容可发布、存在重大未解决的选择或需要新的授权，或穷尽安全替代方案后仍存在外部阻碍时才停止。 如果发布取决于某项重大选择，则须在任何推送或草稿 PR 之前停止。 只要任何必需的证据或 CI 仍缺失、待处理或失败，就保持 PR 为草稿。

条件性参考资料

• 如果分支属于原生 GitHub 堆栈，或基于尚未合并的 PR（步骤 1），请阅读 ../git-workflow/references/github-stacks.md。 此时，该请求授权提交当前更改所持有的、已确认的堆栈层，并协调其元数据；不包括无关分支。
• 如果更改有可见或可演示的行为，或者 PR 中需要包含本地截图或视频，请阅读 references/walkthroughs.md。该文档负责媒体捕获、上传和缺项报告。切勿将证据媒体提交到仓库。仅缺少媒体功能不会阻止发布或就绪；但仍须提供所需的行为证据并通过项目门禁。

仅预览草稿

如果只有在 PR 预览中才能测试所需行为，请在可用检查通过后，根据此发布请求创建或更新所需的草稿 PR，以获取预览。通过同一获准的堆栈流程，发布原生堆栈所需的草稿。测试该确切修订版本，然后继续循环，直至就绪。录制演示过程不能替代行为测试。

工作流程

1. 检查工作树、暂存区差异、近期提交、远程默认分支、适用时的堆栈拓扑，以及任何现有的远程头部。保留无关的本地工作。

   PR 的目标分支为远程默认分支。例外情况是用户指定的长存基分支，或项目说明（例如 AGENTS.md 或 CONTRIBUTING.md）中记载的长存基分支，例如用于回移植的发布分支：将其作为指定的基分支。仅作为开放 PR 功能头的分支，绝不能作为指定的基分支。除指定的基分支和堆栈参考文档中的原生堆栈操作外，绝不要手动将 PR 的基分支设为非默认分支。 选择基底前，检查此更改是否基于尚未合并的 PR。 使用以下命令列出未关闭的 PR： gh pr list --state open --limit 1000 --json number,headRefName,headRefOid,isCrossRepository,baseRefName。 如果列表行数达到上限，结果可能被截断：提高上限后重新列出，直到返回的行数少于上限，否则停止并报告。通过列表所查询的仓库远程，一次性获取各分支头： git fetch REMOTE pull/A/head pull/B/head ...。跳过当前分支自己的 PR、头部包含当前分支头的 PR，以及头分支与指定基底相同的同仓库 PR。当 PR N 来自此仓库且其头分支是预期基底，或 git rev-list HEAD ^BASE ^DEFAULT 与 git rev-list HEAD-OID ^BASE ^DEFAULT 有共同提交时，此更改即基于 PR N。DEFAULT 是已获取的远程默认分支，BASE 是已获取的指定基底或 DEFAULT，HEAD-OID 是 N 的 headRefOid。如果匹配项来自 fork（isCrossRepository），则停止并报告，因为此处不能以它为基底。如果指定了基底，若匹配项基于其他分支，也要停止并报告，避免回移植叠加在默认主干上。将其他匹配项作为原生堆栈发布，并遵循堆栈参考中的“When to start a stack”。

2. 如果没有相关更改或领先于远程基底的提交，则停止。如果工作已提交，则无需空提交，直接继续。

3. 如果当前位于基底分支，则创建一个以问题或更改命名的专用分支。

4. 发布前明确 PR 的主张和发布要求。阅读明确请求、关联问题或已确认的迷你规格、适用的项目说明、产品文档、ADR 或持久决策、最近的 DEFINITION_OF_READY.md，以及实施工作流提供的完成证据。如果没有来源说明主张，则根据提交和差异重建范围最窄且有依据的主张，并标注为推断。

5. 针对当前要求和更改执行 /code-review fix-all 和 /test-against-spec fix。仅复用内容、命令、环境和覆盖范围仍然匹配的结果；运行缺失或过时的审查和真实接口检查。如果主张是根据差异推断的，则在规格测试前明确预期行为。解决实质性歧义，不要根据实现臆造要求。

6. 通过 /implement 的开发循环修复所有已验证且属于范围内的要求、保真度、测试和兼容性问题，不论严重程度；如果无法使用配套技能，则直接执行相同的已记录检查。编辑后，在发布或确认就绪前，针对受影响范围重新进行审查和规格验证。针对性地重新验证发现的问题，可以复用未变更的审查覆盖；修复问题本身不代表审查结果已更新。修复收敛后，运行缺失或已失效的项目门禁。

7. 按照 git-workflow 提交未提交的相关工作：仅暂存相关文件，排除机密信息和无关的本地工作，并使用简洁的 Conventional Commit 标题。绝不 amend，也绝不跳过钩子。保留已发布的历史记录，任何修正都新增提交。每次提交、推送和 PR 写入时，都运行发布保护检查。

8. 每个拉取请求的标题都使用涵盖整个更改的 Conventional Commit 标题；git-workflow 的 squash 合并会将该标题用作基底分支的提交标题。正文的章节顺序和字符限制遵循 ../agent-writing/references/pr-descriptions.md，同时保留明确的项目模板要求。每个 PR 模板标题都必须原样保留并按原顺序排列；对于没有内容可写的标题，写一行 None 或说明原因，不得将其当作可省略的套话。不要在正文各章节中写作者的验证结果；最终交接时报告这些结果，审查结果仅放在正文末尾的审查说明中。撰写前，搜索未关闭和已关闭的问题；如有条件，也搜索近期的相关会话或相邻分支，以查找相关发现和重复项。在更改摘要之后，每个关闭关键词单独占一行，写作 Closes #N，并且只放在解决该问题的层级上。使用 --kind pr --body FILE 对草稿运行 template-check，并在发布前修复报告中的所有标题问题。

9. 发布检查通过后，或遵循上述仅预览草稿规则时，正常推送普通分支，并在需要时设置其上游，然后针对远程默认分支或指定基底打开一个草稿 PR。对于已验证的原生堆栈，遵循堆栈参考：在已冻结且获批的 PR 上方新增顶层时，使用受保护推送、单独创建 PR 和原生追加；在已冻结的较低层 PR 上创建新堆栈时，使用受保护的 gh stack link；更广泛的授权提交使用 gh stack submit。每个已发布层都必须有当前有效的证据。只有受保护的官方堆栈操作可以 rebase 或使用 force-with-lease 推送。保留自下而上的拓扑结构，并使每一层都保持草稿状态。

10. 执行 PR 专项阶段。比较实际 PR 差异、正文、链接、元数据、已提交的测试和文档、提供的完成证据，以及仅在发布后才存在的事实。使用 --pr N 对当前正文运行 template-check；报告的标题问题属于纯元数据缺口。无需提交即可修正纯元数据缺口。

11. 如果 PR 专项阶段或 CI 发现范围内的仓库、行为、保真度、测试、文档或兼容性问题，则通过开发循环修复。重新验证受影响的要求，然后对同一 PR 使用 /update-pr 并核对其新头。继续处理，直到所有已验证的要求缺口都已解决。

12. 按照其运行规则，调用 delivery-wait 的 wait checks-terminal 操作，提供仓库、PR 编号、准确的头、--all-workflows、绝对截止时间和 --json。--all-workflows 会等待该头上的所有 GitHub Actions 运行和作业，包括后续阶段新增的作业。对适用的每个提交状态或其他应用的检查（例如部署预览），各添加一个 --check。不要根据等待开始时可见的检查来构建 --check 列表，因为当时显示的检查通常不完整。对于检查未显示在 PR 上的已派发运行，还需运行 wait workflow-terminal --run-id <id> --head <sha>。被动等待有意义的状态转变；不要用反复的模型轮次替代被动等待，并报告不可用的主机功能。检查失败日志，并将已确认的范围内原因返回第 11 步处理。如果预期的 PR 检查没有运行，则检查可合并性，并通过 /update-pr 解决已确认的冲突，再考虑重新触发。不可用的外部依赖仍应标记为待处理或受阻，绝不能标记为通过。只有当等待操作报告当前头已满足条件后，才能称 CI 通过，并用通俗语言说明。根据本地检查在受测内容上的实际结果，说明该检查是否通过。只有失败日志表明问题具有间歇性时，才将故障视为偶发或暂时性。将问题归咎于更改以外的原因，或不将失败纳入修复范围，都需要单独的证据；由此更改引发的偶发故障仍属于范围内问题。

13. 一旦 PR 满足发布和 PR 专项阶段的所有要求，并且已观察到所有适用 CI 对其准确头均通过，就将其标记为可供审查。返回所有受影响的 URL 和关联问题、适用时的原生堆栈顺序、最终状态、元数据更改、提供的完成证据、发布保护检查所做的改写，以及观察到的就绪和 CI 证据。即使 PR 已就绪，也要列出尚未完成的演练要求和可操作的补救措施。直接启动时，按照交付设置继续；使用 entry-points: deliver 时，已就绪的 PR 接下来进入 /address-feedback。