PR 生命流程

review：会话开的 PR 从开出来起由流程 pull-request 跟着走，一个 PR 一条运行，到合并或关闭才结束。 它只用 Coda 流程的公开原语（PR 事件、Agent 步骤、人工任务、调用其他流程），也是写 PR 流程的样例：要不一样的流程，照着它改一份（见文末「改成自己的」）。 它依赖内置的 GitHub 插件（extensionDependencies）：PR 事件由 GitHub 插件的「PR 观察」发布；装 review 时先装 GitHub 插件，卸载 GitHub 插件时 review 一起卸载。 运行的标题是「PR #号 标题」（手动发起的是参数 pr，评审查出 PR 后是「PR #号（地址）」），卡片上有「检查」「评审」「合并」三段；草稿、叠放的 PR 另有「草稿」「叠放」，选了部署或发布的，合并后再有「部署与发布」。 流程通过 coda:key 声明 PR 地址为主键：在同一项目中，自动、手动发起共享一条未结束的运行，包括排队、等答复和取消收尾。地址不区分大小写。结束后新请求可再发起；旧请求重试仍返回原运行。 也可以 workflow_run pull-request 手动发起（必填 pr：GitHub 返回的完整 PR 地址，可选 focus）。已有运行时返回它，沿用原进度、关注点和结果接收会话；草稿中的运行也照旧等标记为可评审。没有运行时只评审一次、不计次数、不进入合并；如果随后 PR 观察发来事件，在同一条运行里接上完整流程。是否接入完整流程按 github.event.coda.heard 判断：手动运行尚未收到事件时为空。 pr 须在创建运行前明确。编号、旧仓库地址或带后缀的链接先用 gh pr view <编号或链接> --json url --jq .url 取得 GitHub 返回的地址，再传入；流程不从 origin 猜仓库身份。需要查最近开的 PR 时先用 GitHub 插件的 github-reported-pr 找到它，再用 gh pr view 确认当前地址。输入不接受编号、末尾斜线、查询参数或片段，避免不同拼写创建不同主键。此版本需要支持 coda:key 的 Coda 流程引擎。

.coda/workflows/pull-request.bpmn   流程本身
scripts/checks.mjs                  等 GitHub 检查
scripts/review.mjs                  交叉评审：选评审方、开会话、读结论、写 PR 评论
scripts/base.mjs                    看 base（叠放）
scripts/approval.mjs                记下批准：时刻与合并后要做的事
scripts/merge.mjs                   合并
scripts/delete-branch.mjs           合并确认后删除远程源分支
scripts/notes.mjs                   发布流程的参数（更新说明与 publish）
scripts/step.mjs                    各脚本共用：读参数、写输出与摘要、读 PR 的 base
prompts/review.md                   评审方收到的提示词
prompts/rules.md                    评审的规则：评审方照它评审，开 PR 的会话照它判断意见成不成立
prompts/principles/                 评审重点，一项一段，按设置取用

插件设置列出全部合并选项；目录设置继承插件的选择，也可整组覆盖或恢复继承。目录里只显示该目录有的部署、发布类别。默认值在运行开始时读取，已经打开的卡片保持原来的选择。需要支持勾选项 default 与设置选项 workflowKind 的 Coda。

项目提供的部分

插件管流程，项目在自己的仓库里提供四样，跟着代码走：

• 评审准则：.coda/review.md，从 PR 的 base 提交读取，交给评审方，也写进「处理评审意见」交给开 PR 的会话。PR 改它只从合并后的评审起生效；文件不存在就省略，读不出 base 提交时这次评审失败。
• 检查：仓库里声明为 coda:kind="check" 的流程（第 2 步），每个版本都跑。
• 合并前检查：声明为 coda:kind="premerge" 的流程（第 5 步），你批准后在要合并的提交上只跑一次；每个版本都跑嫌贵的验证（如整套回归）放这里。
• 部署与发布：声明为 coda:kind="deploy"、preview、release 的流程（第 6 步）。

流程

1. 草稿：PR 是草稿就等作者标记为可评审（pull_request.ready_for_review）；有新提交时按它带来的草稿状态重新判断，关闭则结束。 推送和标记为可评审落在 Coda 的同一次查看之间时，只有新提交这一个事件，它说已不是草稿就去评审。
2. 检查：机器检查便宜，先过了它们再请 Agent 评审。
   • 「跑项目的检查」在 PR 的提交上调用项目声明的检查（coda:kind="check"）并等它们结束；没通过的检查让自己的运行失败，有一个失败就交给开 PR 的会话。 检查可以同时往提交上写一条 GitHub 状态，一句话结论在描述里。项目没有检查就直接过去。
   • 「等 GitHub 检查」（checks.mjs）再每隔几秒读一次 gh pr checks，等这个提交在 GitHub 上的检查（commit status 与 check run，包括 GitHub Actions）都有了结果， 一小时没等到这一步失败。都通过就去评审，各项的一句话结论交给评审方、写在批准卡上；有没通过的同样交给开 PR 的会话。
   • 「检查没通过：处理后答复」：是改动导致的就推送新提交，从头再来；检查本身出了问题就处理好后答复，项目的检查再跑一遍（GitHub 上的其他检查由它自己重跑）。 它做不了交给你「检查没通过：等你处理」。有新提交就打断，从「草稿吗」重来。手动发起的评审不跑检查。
3. 评审：有新提交就打断，从「草稿吗」重来。

   • 「评审吗」：同一个提交在同一个 base 上评审通过过就不再评；这条运行已自动评审 review.maxReviews 次（手动发起的不数），交给你「评审次数已到上限」：放行当前版本，或再评审一次。

   • 「交叉评审」（review.mjs）：按评审组合最具体的一行选出评审方（行键是 *、agent、agent|model、agent|model|effort，没有适用的行就失败）， 用 coda-agent 在被评审的提交上开一个新会话，交给它填好的提示词：去哪看改动、这个提交上各项检查的结论、作者写的标题与正文（夹在作者猜不到的标记之间，声明只是参考资料）、 这条运行上一次评审的发现、评审的规则（rules.md 填好的全文：项目评审准则、通用要求、开着的评审重点、严重程度的定义）、关注点。会话失败或结果未知时每隔 20 秒重试，最多 3 次；取消或参数错误不重试。 评审默认复用已有验证证据；较早提交的结果先判断后续改动是否影响其覆盖范围。只有具体疑点或影响结论的验证缺口才补跑最小检查，并先说明原因；生命周期声明的检查与合并前门禁仍由流程执行。

   • 评审方按 P0（最严重）到 P3 给每条发现定级，在回复末尾的 review 代码块里以 JSON 列出；脚本按阻塞级别得出结论：

     结论	条件	之后
     APPROVE	没有发现	通过
     COMMENT	只有低于阻塞级别的发现	通过，低优问题写在 PR 评论和批准卡上
     REQUEST_CHANGES	有阻塞级别及以上的发现	「处理评审意见」交给开 PR 的会话
     未完成	评审会话没正常结束，或没按格式给出结论（任何一条不合格式都算）	这一步失败，运行失败，唤醒开 PR 的会话

     每次评审在 PR 上留一条评论，写结论、评审方与发现；写失败只记在摘要里。GitHub 不允许给自己的 PR 批准或要求修改，所以结论不以 PR review 的形式发出。 「交叉评审」的摘要只给用户看（coda:audience="user"）：交给会话的任务只带阻塞项，完整评审在批准卡上，你点「让 Agent 处理评审意见」才交出去。

   • 「处理评审意见」：任务里有阻塞级别、阻塞的发现和评审方依据的规则（与交给评审方的原文相同），会话照规则核实，判断该不该不同意。 会话修改、推送后答复 completed，运行「等新提交」；不同意就答复 rejected 并写明理由和依据的规则，交给你「仲裁评审意见」： 放行就接着走，按评审意见修改则把「处理评审意见」再交给会话。

4. 叠放：只合并进仓库的默认分支。「看 base」（base.mjs）读 PR 现在的 base 与默认分支，base 是别的分支时不请你批准，停在「叠放」等 base 变了（pull_request.edited）， 再从「草稿吗」重来：base 变了改动就变了，重新评审。在「合并」里（等你批准、等会话处理时）base 变了也一样从头再看，批准卡撤回。 仓库开了合并后删分支时，下层 PR 合并后 GitHub 自己把 base 改到默认分支；没开就由作者用 gh pr edit --base 改。
5. 合并：
   • 「批准合并」交给你，卡片写明评审结论、改动（按路径第一段分组，如 backend/ 2 · Sources/ 1）、PR 链接、各项检查和最近一次评审。 主按钮「合并」按 review.mergeOptions 的默认值提交；右侧箭头或长按打开勾选面板，选项是「合并后删除远程分支」「部署」「发布预览版」「发布正式版」「全部完成后通知 Agent」，初始按设置勾选，点面板内「合并」才提交。取消不保存本次调整，再打开恢复默认值。未设置时全部不选。 卡片之前的「看项目有哪些部署、发布」（workflow-kinds）查项目在这个提交上有哪几类流程，部署和发布选项只给项目有的那几类（coda:shown）； 比如只有部署流程的项目，面板里有「合并后删除远程分支」「部署」和「全部完成后通知 Agent」。没给的那几项按不勾算。需要 Coda 745f85c 及之后。 另有「让 Agent 处理评审意见」：连同你的备注交给开 PR 的会话「处理你交付的评审意见」，它推送后重新评审、再请你批准，它做不了就回到批准卡；以及「关闭 PR」（gh pr close）。
   • 「合并前检查」：你选了合并后，先「记下批准」（approval.mjs）：批准的时刻，和你勾的删分支、部署、发布、通知（合并后都照它做），再在评审通过的提交上调用项目声明的合并前检查（coda:kind="premerge"）并等它们结束； 项目没有就直接过去。有一个没通过就交给开 PR 的会话「合并前检查没通过：处理后答复」：改动导致的就推送新提交，照常检查、评审，通过后按你这次的选择合并，不再问； 检查本身出了问题就处理好后答复，再跑一遍。它做不了交给你「合并前检查没通过：等你处理」。合并没成功后重试合并不再跑合并前检查（同一个提交已经通过）。 需要认识 premerge 这一类的 Coda。
   • 「合并」（merge.mjs）：先读 PR 现在的 base，不是默认分支就不合（Coda 下次查看 PR 时才得知 base 变了，可能晚于你批准）； 再 gh pr merge --<合并方式> --match-head-commit <通过的提交>，只合评审通过（或你放行）的那个提交，分支动过 GitHub 就不合； 不打开 GitHub 的自动合并，它会合并之后推送、还没评审的版本。目标分支要求合并队列时，GitHub 把它放进队列。
   • 没有合并（base 不是默认分支、冲突、要先合入目标分支、草稿、检查没过等）：原因交给开 PR 的会话「合并没成功：处理后答复」。它推送新提交就照常评审， 通过后按你这次的选择直接合并，不再问；处理好别的（标记为可评审、等检查通过）就答复 completed 重试。它做不了，交给你「合并没成功：等你处理」：重试合并或关闭 PR。
   • 批准在评审再要求修改时作废：「交叉评审」逐次接力输出最近一次要求修改的时刻 changesAt，「记下批准」输出你批准的时刻 at， 「按原批准合并吗」只在 at 晚于 changesAt 时不再问你。
   • 交给 GitHub 后在「等 GitHub 确认」等关闭事件，它带来合并提交；期间有新提交（被移出了合并队列）就从头再来。 我们发起的合并、关闭命令正常收尾；它们产生的关闭事件先到时留在收件箱，不打断命令，也不把合并阶段记为取消。 合并命令结束后再读取确认，照你的勾选接着做。等待批准、合并前检查或人工处理时收到关闭，仍立即结束相应等待。 合并前，「交给 GitHub」记下要交出去的提交；合并受阻、等人处理时才收到这个提交的合并确认，仍照原批准继续。 合并前检查没过、还在等人处理时被别处合并，不算这条运行的合并。
   • 勾选「合并后删除远程分支」时，确认合并后、部署与发布前运行「删除远程分支」（delete-branch.mjs）。它从 PR 读取源仓库（包括 fork）与源分支， 只删除仍指向这次批准合并的提交的远程分支；本地分支与会话工作树保留。分支或源仓库已删除就跳过，有了其他提交、是默认分支或合并目标分支则保留，原因记在步骤摘要。 删除用 Git 的 --force-with-lease=<ref>:<sha>，推送期间分支变动也不会误删。读取或删除失败会让运行失败，处理后可从失败处继续，之后再部署与发布。 不勾选时流程不主动删分支；GitHub 仓库自身的「合并后自动删除分支」设置仍独立生效。
6. 部署与发布：合并确认后按你的勾选，在合并提交（merge_commit_sha）上调用其他流程：先 run-workflows kind=deploy， 再交给开 PR 的会话「写更新说明」（它做不了交给你写；你选「不再发布」，运行正常结束），然后按勾选调用 kind=preview、release 或 preview,release， 参数 notes（更新说明）与 publish（"true"）。没声明某个参数的流程不会拿到它；项目没有这一类的流程，这一步直接过去。 部署或发布失败时运行失败，结果交回开 PR 的会话，由它查明后手动重跑对应的流程。

• PR 在 GitHub 网页上合并或关闭（不经这条运行的「等 GitHub 确认」，也不是上面那种你批准的版本在合并时先送到的关闭），运行随之结束，交出去的任务和卡片撤回，不删除分支、不部署、不发布。
• 正常结束只更新运行与卡片、结清等待，不唤醒 Agent；勾选「全部完成后通知 Agent」则在合并及所选删除分支、部署、发布都结束后回传一次。未处理的失败照常回传；手动发起的评审交回结论。
• 流程只按检查、评审结果、PR 状态与你的批准推进，不读取作者会话的忙闲、后台任务或其他运行；合并前要先完成的验证写成检查（第 2 步）或合并前检查（第 5 步）。

改成自己的

• 只改评审的措辞：改 prompts/review.md；评审的规则在 prompts/rules.md，改了评审方和开 PR 的会话同时生效。 {{…}} 由评审脚本换成整段文字，文件开头的注释列出各个占位（注释不发出去）；只有回复末尾的 review 代码块是脚本读结论的约定，不能改。
• 改流程：把这个目录复制到你自己的仓库，在 Coda 的「设置 › 插件」里卸载内置的 review，再「从仓库添加…」装你的那份（同名替换）， 之后按你的仓库更新、回退。改了插件 ID 也要先卸载内置的，否则每个 PR 会跑两条流程。
• 改这里的 review 本身，照本仓库的规矩提 PR、升 version；Coda 再同步到合并后的提交（见仓库根的 README）。