delivery-wait

等待交付

每当工作流必须等待外部 GitHub 状态时，都运行 scripts/delivery_wait.py。执行环境会被动等待命令结束；不得用模型心跳模拟等待。

执行等待

主机限制了单条命令的最长运行时间，而交付状态变更可能需要更久。遵循以下规则，确保等待持续运行到状态变更完成：

• 如果主机支持在后台运行命令，并在命令退出时恢复会话，就以这种方式运行等待。然后结束本轮，或只继续处理不依赖所等待状态的工作。如果没有此功能，请使用下方的后备方案；切勿通过阻塞式等待让本轮一直挂起。
• 将每次调用的 --deadline 设在主机单条命令的时限以内，并单独记录调用方愿意等待状态变更的时限。如果在该时限之前返回 timed-out，就使用相同的 --state 再次运行等待。这是恢复同一次等待，不是心跳。
• 将辅助程序作为完整命令运行，不要在其后通过管道或链式调用其他命令，这样主机报告的退出状态才是辅助程序自身的状态。主机提示命令已结束，仅表示命令已退出；实际结果以结果封装为准。
• 每个状态文件只能有一个正在运行的等待进程。切勿让等待进程脱离主机运行，例如使用 setsid、nohup 或 &；脱离主机的进程无法恢复会话。
• 等待运行期间，不要检查它所覆盖的状态。根据等待结果采取行动。

address-feedback CodeRabbit 适配器的 run 也遵循相同规则。它不会保留状态文件：使用相同参数再次运行，它会从 GitHub 重新读取最新提交的状态。

长时间运行的命令和委派任务通道

无论是在协调者还是工作者中，都对长时间构建、测试和其他命令采用相同的本轮处理原则。预计运行时间超过短暂检查的命令，应通过主机可追踪的后台执行方式启动。交接时应记录任务或会话 ID、输出位置、确切修订版本、完成条件和恢复操作。启动确认表示工作仍在进行，绝不代表已通过。短命令和耗时有限的诊断检查可以在前台运行。

确认命令会在所属任务通道结束本轮后继续运行，并且完成后能够恢复该通道或其协调者。有些主机会在前台工作者返回时停止其命令；此时应由仍在运行的所属者启动命令。遵守后台命令和监控的时限。监控只能在出现有意义的变化或终态时发送通知；持续发送未变化的状态会像轮询一样唤醒模型。每个状态变更只能有一个所属者和一个活动等待进程。

如果只剩下命令、工作者或外部状态变更尚未完成，请记录待处理状态并结束本轮。任务运行期间继续处理无关工作；之后检查返回的退出状态和结果，再恢复依赖该状态的工作。不要使用前台 gh pr checks --watch、休眠循环、反复执行 gh pr view，或反复读取输出／状态来让任务通道保持运行。仍有待处理工作的工作者应向协调者返回句柄和下一步状态变更，而不是声称已完成；不要为了轮询它而再创建一个工作者。

如果主机无法通知或恢复所属者，请进行一次有时限的状态检查，记录此功能缺失，并明确注明下一次检查的时间或触发事件，然后返回待处理状态。若调用方指定了检查频率，则按其要求执行；否则，至少五分钟后再检查，并设置状态变更的截止时间。每次恢复本轮时只检查一次；如果状态未变，就再次挂起。这只是后备方案：不要用定时轮询取代有效的通知路径。如果命令根本无法跨本轮继续运行，请向调用方说明所需的执行能力，不要启动不可追踪的进程，也不要谎称检查已运行。

输入

调用方提供仓库、预期身份、绝对截止时间，以及可选的状态路径。该命令会将任何已保存的状态与最新的 GitHub 状态进行核对，在没有相关变化时持续等待，并以一个结果退出。在工作流技能中使用 --json；面向人工的输出则用于直接在终端中使用。 技能默认将状态文件保存在 .agent/waits/ 下，使用该技能的仓库必须将其加入 gitignore；其他运行框架可通过 --state 指定任意私有状态路径。

调用

wait <kind> --repo <owner/repo> --deadline <ISO 8601> [--interval <seconds>] [--state <path>] [--json] 执行等待；inspect <kind> 接受相同的身份标志，但不接受 --deadline、--interval 或 --state。每种类型 都需要自己的身份标志：

• checks-terminal：--pr <number>、--head <sha> 和 --all-workflows、 每个预期检查上下文对应一个 --check <name>，或两者都提供。如果两者 都未提供，则会以操作错误退出，而不是等待。
  • --all-workflows 不需要检查名称。它会查找与指定 head 完全匹配的每个 GitHub Actions 工作流运行，以及每次运行最新尝试中的所有作业。如果尚无运行，或任何运行或作业处于排队、进行中、等待中、待处理或已请求状态，它会继续等待。如果某个运行或作业以失败、已取消、超时、需要执行操作 或其他非成功结论结束，它会立即报告 changed。只有当每个运行和作业都成功、已跳过 或状态为中立，并且连续两次间隔一个周期的观察结果显示相同的清单时，才会报告 satisfied。后续矩阵阶段或 needs 阶段添加的作业会使其所属运行保持进行中。某个运行在另一个运行结束后启动时，会出现在第二次观察中。inspect 无法确认清单是否稳定，因此对于全部成功的快照，它会报告 waiting 而不是 satisfied。
  • --all-workflows 不涵盖提交状态或来自其他应用的检查运行，例如 CodeRabbit 或 Vercel。对于调用方需要的每一项，请添加一个 --check；等待操作也会要求这些上下文成功。
  • 命名检查在以成功、已跳过或中立状态结束时通过。只要某项命名检查以其他任何方式结束，等待操作就会立即报告 changed，即使其他检查仍在运行。同名检查运行按来源分别计数：来源是其应用；对于 GitHub Actions，则是其工作流和触发事件。因此，同时在 push 和 pull_request 上运行的工作流需要两次运行都通过。每个来源只计入最新的检查套件，因此重新运行、被较新的运行取消的运行，或编辑后重新检查，都会取代较早的运行，无论它们的启动顺序如何。提交状态按其最新状态计数。
  • 单独使用 --check 时，只会判断命名上下文，而不考虑该 head 的其他检查是否仍在运行。仅当完整的预期集合已知时才使用它，例如仓库要求的状态检查。等待时可见的检查并不等于该集合：工作流会分阶段添加作业。
• pr-merged：--pr <number> 和 --head <sha>。如果拉取请求在未合并的情况下关闭，它会报告 changed。
• workflow-terminal：--run-id <id> 和 --head <sha>。用于已调度或其他检查不会显示在拉取请求中的运行。
• tag-target：--tag <name> 和 --head <sha>。
• release-assets：--tag <name>、--head <sha>，以及每个必需资源对应一个 --asset <name>。
• wake-at（仅限 wait）：仅使用 --deadline。它不会保留状态文件，因此 --state 不起作用。

没有 --checkpoint 标志。状态路径通过 --state 指定；如果省略该参数，命令会根据类型和身份推导默认路径。

inspect 和 wait 都接受 --rest-page-size <1..100>（默认值：100）。 如果 GitHub 无法提供较大的 REST 页面，请使用较小的值。该选项适用于工作流运行、作业，以及检查和状态的 REST 回退查询。仍会读取所有页面，并且仍需获取完整的工作流清单。 该选项不会更改 GraphQL 查询或保存的等待身份，因此可以使用不同的 REST 页面大小恢复现有等待。

结果

--json 会输出一个 state 表示结果的封装对象。只有 satisfied 才表示等待的事实已成立。changed 表示检查或工作流到达非成功的终止结果，或其他相关状态发生变化；请先检查再决定。invalidated 表示预期的 head、ref 或已保存的身份不再匹配，timed-out 表示已超过截止时间，cancelled 表示等待被中断。这些状态的退出码均为 0；operational-error 的退出码为 2。inspect 也可能报告 waiting。

使用 inspect 获取单一权威的交付快照，使用 wait 等待状态转换。支持的谓词包括精确 head 检查、拉取请求合并、工作流完成、标签目标、发布资源和绝对唤醒时间。预期 head 或 ref 发生变化时，等待会失效，而不会静默地跟随变化。GitHub 仍是权威来源；检查点包含规范化的身份和观察结果，不包含凭据、原始评论正文或原始 API 负载。

此辅助工具使用经过身份验证的 gh 传输。GraphQL 是首选。仅当 GraphQL 遭遇速率限制且 REST 能保留相同事实，或 GitHub 仅通过 REST 暴露该事实时，才会使用 REST 回退。