pr

Pull request

让人类审阅者能够理解一项更改：问题、交付的行为、关键决策，以及评估所需的证据。

此技能负责发布和 PR 展示。commit 负责原子提交；stacked-pr 负责堆栈拓扑、提交和级联变基；pr-followup 负责反馈、CI 修复，以及从草稿转为准备好接受审阅。仅当这些工作属于当前请求或长期指令时，才使用相应负责方。返回已授权的调用方后，继续其工作流；完成此阶段不会取消外层任务。 issue-workflow 负责根据使用方项目的规范状态转换策略同步关联工单。

确定操作类型

• 创建： 发布预期提交，并在用户提出请求且不存在完全匹配的 PR 时创建 PR。除非用户偏好指定为准备好接受审阅，否则默认创建为草稿。 创建 PR 的请求在发布后还会调用 pr-followup 的 Drive 模式，即使已有完全匹配的开放 PR 足以满足创建请求也不例外。
• 更新： 在现有授权范围内更新现有开放 PR。根据最终已发布的差异重写整个正文；保留仍有效的证据和必需的模板内容。更新请求无需再次获得批准。
• 仅草拟： 提供所需文案或检查结果，不进行提交、推送或 GitHub 更改。只进行交付所需的读取操作。
• 检查上限： 仅应用共享的大小检查，并返回检查结论。调用方仍负责补救、发布和后续操作；此操作不会进入其他 PR 阶段。

完全匹配但已关闭或已合并的 PR 属于历史状态。展示其 URL 和状态；除非用户已选择相应操作，否则不要编辑、重新打开或替换它。只询问尚未解决的重要决策，绝不询问已获授权的操作。阻碍因素会暂停依赖它的工作；有帮助时，先完成独立的准备工作。

确认身份和范围

读取当前分支、状态、远程仓库、上游和 HEAD。确定以下信息：

1. 推送仓库、远程仓库和引用： 使用分支已验证的上游或用户指定的目标；将远程 URL 映射到实际的 GitHub 仓库。远程名称仅供参考。分支的上游是推送目标，绝不是 PR 基础分支。
2. 目标仓库： 优先使用提供的 PR URL 或明确指定的目标。对于从 fork 向上游仓库提交的贡献，使用已验证的父仓库，避免误用 fork。如果 fork 与父仓库仍存在重大歧义，则询问用户。
3. 完全匹配的 PR： 使用 gh pr list --repo <target> --state all --head <branch> --json number,url,state,headRefName,headRepository,headRepositoryOwner,baseRefName,isDraft 查询所有相关结果。此处的 --head 接受分支名，而不是 owner:branch；应同时按分支名和头部仓库身份筛选。查询失败或不完整不代表结果为空。直接检查用户提供的 URL。存在多个完全匹配项时，需要消除歧义。
4. 基础分支： 保留现有 PR 的实际基础分支。对于新 PR，使用明确且已验证的基础分支，或目标仓库的默认分支。检测是否存在依赖分支，并将拓扑决策交由 stacked-pr 处理。使用目标仓库的 SSH 远程仓库获取所选基础分支；验证其身份，不要轻信本地 main。
5. 修订版本： 确定实际要描述的头部版本：创建或发布时为选定的本地提交；仅更新元数据时为已发布的头部版本。记录基础分支和头部的 SHA。保留无关的工作区和暂存区更改；它们不会阻碍仅更新元数据的操作，也不应被纳入相关说明。

遵守宿主的检出所有权和 PR 关联要求。需要切换检出时，使用宿主交接机制，并由 worktrunk 负责。若宿主支持登记 PR，则登记实际的 PR。

了解变更和仓库

在作出实质性声明前，请阅读 references/claims.md。检查 <base-ref>..<head> 中的每个提交和完整的 <base-ref>...<head> 差异，然后根据当前代码、检查门槛和失败路径追踪重要行为。将生成内容、二进制文件、依赖项和迁移变更纳入考虑。不要把存在测试等同于测试已通过，也不要把问题的意图等同于实际交付。

检查相互独立的事项是否可以分开审查和回滚。如果这样做能带来实质性帮助，请建议拆分；不要重写已发布的历史记录、调整堆栈顺序，或仅仅为了缩短差异而将某项行为与其回归测试分开。必要的生成输出不应自动视为噪声。

编写正文前，请阅读：

• 仓库说明和 CONTRIBUTING.md 中的 PR 规则。
• 已解析基准版本中的模板：根目录、docs/、.github/ 及其 PULL_REQUEST_TEMPLATE/ 目录下的模板。此分支修改的模板不能作为既有惯例的依据。根据变更内容和仓库规则选择适用模板；只有在仍有重要选择未定时才询问。
• 最近合并的最多 10 个 PR；阅读其中 3 个正文，若不足 3 个则全部阅读。参考相关的近期示例了解风格，但不得将其视为高于书面规则的依据。

将无法访问的必需证据记录为未知，并注明确切的查找失败情况。根据现有证据继续处理；不要臆造缺失的惯例。

检查审查规模上限

当请求、项目规则或任务记录设定了 PR 规模上限时，使用此检查。将选定的基准版本和头版本解析为确切的 SHA，并记录适用的上限。若检查上限的请求缺少版本或上限，则结果为 unverified。

统计完整 <base-sha>...<head-sha> 差异中的新增和删除行数，包括测试、生成文本和锁文件。使用 Git 的 --shortstat 获取总数，使用 --numstat 识别二进制条目；不要使用净增长、提交数之和或排除路径后的结果。拆分提交不会缩小 PR。

返回 within-cap、over-cap 或 unverified，并注明确切版本、行数、上限以及任何二进制审查负担。无法获取差异时，结果为 unverified。推送或创建 PR 前，必须确认当前结果为 within-cap；基准版本或头版本发生变化时，先前的统计即失效。若超出上限，发布负责人应将工作交给 task-breakdown，以重新划分工作单元。不要默默豁免上限或重写已发布的历史记录。仅限草稿或元数据的工作可以报告违规，但不得因此发布更多代码。

编写审查内容

当任务、分支、提交或 PR 正文提及工单时，在编写其 PR 关联信息之前，先在 Inspect 模式下使用 issue-workflow。传入提供的工单或查找提示、准确的仓库、基础分支，以及证明该关联属于已完成或有所贡献的证据。它会验证工单身份和关联；如果没有关联，则返回 not applicable。对于已验证的工单，它会返回项目允许的链接形式和事件策略；更新时保留有效链接。 这也适用于仅创建 Draft 的情况，但不会因此授权写入工单跟踪系统。若策略要求工单保持开启状态以供 QA，不要虚构工单，也不要使用关闭工单的关键词。

对于任何标题或正文，请阅读 references/review-packet.md。当更改的界面、流程或结构更适合通过视觉方式评估时，请阅读 references/visual-evidence.md。 使用最精简且实用的图表、真实截图或测量对比。

对于可见的 UI 更改，如果应用、截图工具和上传途径均可用，请捕获并附上相关应用状态。若已有经过验证的截图与当前修订版相符，则使用这些截图。按照 references/attachments.md 将其上传到 PR 正文；本地截图路径不算附件。如果某项前置条件无法访问，请说明具体是哪一项，以及保留了哪些证据。

遵循仓库要求，包括模板中的书面指引，并保留有意义的模板字段。如果某项风格惯例遗漏了有用的上下文，可以适当补充；若有重大偏离，请予以说明。除非用户明确要求覆盖，否则仍须遵循严格执行的格式。正文长度应与审查结论相称。

对于 Update，应根据完整的已发布更改起草内容，并替换过时的说法，而不是追加连续修复的历史。保留之前的内容前，请重新验证有用的链接、截图和已完成的检查清单项。如有可用的 communicate-clearly，请使用它来使表达清晰，同时不削弱技术含义。

发布和验证

对于任何 Git 或 GitHub 变更，请阅读 references/publication.md。该文档规定身份检查、 SSH 发布、非交互式命令、草稿状态和写入后验证。 对于有大小限制的工作，请使用所选的发布修订版本，在推送或创建 PR 前立即执行 共享大小检查。 在请求剩余授权前，完成可供审阅的标题和正文以及必要的验证。现有请求和长期授权 优先于要求一概确认的源工作流。

成功的阶段必须具备准确的 PR URL、预期的 head 和 base、已验证的标题和正文、 预期状态，以及仅限请求的元数据变更。随附的截图必须有已验证的上传引用，并记录 渲染和访问结果。写入失败在检查前状态未知；超时后请避免重复创建或声称成功。 对于包含关联工单的创建请求，请使用已验证的 pr-created 事件、工单 URL、准确的 PR/head/base、草稿状态和完成关系，调用 issue-workflow。包括草稿。如果项目选择的是 pr-ready，且此已验证的 PR 已非草稿， 请立即协调 pr-ready；不要等待永远不会发生的草稿转为就绪状态。否则，让已配置的 就绪事件保持待处理状态。对于已有的准确开放 PR 已满足创建请求的情况，也适用此规则， 但应使用当前状态保护条件，而非盲目重放旧转换。独立的 Update 不会合成创建事件。请单独返回同步结果；工单跟踪器转换受阻不会撤销发布，也不会阻止 独立的后续操作。如果缺少 issue-workflow，请报告这一缺口，并保留事件以便恢复处理，不要猜测状态。 对于创建请求，请在返回前继续以 Drive 模式运行 pr-followup： 传入准确的 PR URL、head/base SHA、草稿状态、验证结果和已知待处理工作。 如有相关信息，也传入已验证的工单关联、转换结果，以及 issue-workflow 中负责合并交付的负责人或尚未覆盖的事件。 该阶段负责处理反馈和 CI 修复、就绪状态及就绪后的观察，并在同一请求下持续进行；不要止步于创建摘要。遵循明确的仅创建指示，在发布后返回。将明确的保留草稿指示传给 pr-followup，该流程会在不执行就绪状态转换的情况下运行 Drive。 满足创建请求的 Update 也要继续进入 Drive。独立的 Update 和仅草稿操作不会启动 Drive； 由后续跟进调用的 Update 会返回到现有循环。绝不要将合并作为发布的副作用。如果 pr-followup 不可用，请报告已验证的 发布结果，并说明缺少该技能是继续处理的阻碍。

返回结果

报告 created、updated、draft-only 或 blocked，并在已知时提供 PR URL、 head/base、草稿状态、相关验证、剩余工作，以及未写入正文的协调说明。列出实际命令和结果，并区分当前执行与历史证据。 对于仅草稿操作，提供请求的文案，并说明未发生任何变更。 对于阻碍，请指出未满足的前提或待定决策，并保留已完成的工作。 将已验证的身份、修订版本和发布状态交还给有权调用者。

对于请求的源代码维护，请使用 agent-instructions，并提供 origin.txt 和 references/upstream-updates.md。