codex-pr-review

Codex PR 评审

职责

协调者：

• 负责 watcher 运行、PR 正文状态解读、修复者委派、工作树管理以及最终报告。
• 在专用 Git 工作树中进行 PR 评审和修复。可复用调用方提供的工作树，例如来自 handle-tickets 的工作树，但须先核实 PR 分支和当前提交；否则，应在编辑或检查前创建或核实工作树。
• 按 head SHA、文件、主题、子系统、已接受或拒绝的发现、已推送的修复及检查跟踪各轮处理，以识别重复模式。
• 向修复者提供任务包：PR URL/编号、分支、工作树、当前 headRefOid、已知的当前评审周期新鲜度边界、由 watcher 刷新的 feedbackItems 和 activeCodexThreads、解析后的优先级、watcher 快照计数、必要时 P0/P1 安全检查结果、评审规范范围基线、与重复模式相关的先前 Codex 评论、先前的 code-review 或 review-fix 结果、检查以及推送策略。提供足够的规格背景以便对发现分类；除非某项发现确实需要，否则不要要求重新进行完整的 code-review。
• 使用 gh pr view、远程 head SHA、共享工作树时的本地状态以及 verdict/reaction 结果，核实修复者的交接情况。不要分析、修复、提交或推送委派的评论变更。
• 如果无法生成修复者子 Agent，则由父级使用评审规范和严重性处理规则处理有效评论、运行检查并报告此回退方案。

修复者子 Agent：

• 直接完成收到的任务，不再委派。刷新 PR 状态，阅读每项指定内容或线程的完整正文，遵循评审规范和严重性处理规则，修复有效且在范围内的阻塞问题，运行检查、提交并推送。
• 收到重复模式任务包时，应先调查共同根因，再修补其他单独症状。
• 返回 PR URL、起始/结束 SHA、verdict、reaction、无需修复的理由、相关的根因说明、文件、检查、提交、推送结果、确认远程 head 已推送后立即记录的 UTC 时间戳以及阻塞事项。

评审规范

• 将 Codex 反馈视为建议。根据实际代码路径、相邻文件，以及依赖项文档/源码/类型核实每项发现；涉及外部行为时尤其如此。
• 在交接或修补前，冻结范围基线：PR 意图、目标分支/基准分支、当前 headRefOid、所有者边界、声明的评审单元/拓扑、关联文档/工单、变更文件以及非测试代码行数。
• 不要让当前差异新增或强化的文档扩大任务约定。如果某项发现仅依赖差异中新增加的更强承诺，应收窄文档，而不是扩大实现范围。
• 开始处理前，对当前 head 上的每项发现进行分类：
  • in-scope blocker：由当前差异引入，影响同一所有者边界，且无需改变任务约定即可修复。
  • follow-up：相邻的 bug 类别、同类功能面、清理工作或更广泛的加固事项。
  • blocked：需要新的协议/配置/存储/公共 API 约定、不同的所有者边界、发布流程变更或产品决策。
• 拒绝不切实际的边缘情况、推测性风险、大范围重写和过度复杂的修复。在正确的所有者边界内优先采用小幅修复；只有确实能改善 bug 类别时才进行重构。
• 如果已接受的发现暴露了某类 bug 或重复模式，应检查当前 PR 范围内是否存在同类问题，并在可行时一次性修复范围内的该类 bug。应止步于已触及的功能面、所有者边界和明确属于后续处理的事项。
• 仅当变更造成具体、可采取行动的风险，或移除了重要的安全检查时，才报告安全问题。
• 在范围分类或针对性验证尚未解决前，不要累积或推送由评审触发的修复提交。

发布冻结

• 对于发布、beta、稳定版、热修复、签名、公证、appcast、package-publish 或 release-check 工作，只修复发布阻碍、发布基础设施故障、精确回移植、安装/升级故障、数据丢失、崩溃或明确的安全风险。
• 将不阻碍发布的 Codex 发现视为 main 的后续事项，而非扩大发布分支范围的理由。

严重程度处理

• 将 Codex P0/P1 视为必须优先处理的工作。每个针对当前头部的 P0/P1，都必须在任何终止结果、根因调查交接或新的审查请求之前得到最终处置。如果发现已过时、已修复、无效或超出范围，必须依据当前头部证明，并记录不修复的理由和有效性反应。
• 如果 watcher 输出受限/被截断，或可能隐藏尚未处理的当前头部反馈，则在声称没有待修复工作前，执行有针对性的 P0/P1 安全检查：使用 gh/GraphQL 检查 Codex PR 评论、审查正文、审查评论和活跃的非过时线程，或运行一次诊断性的 --full-history，然后按常规流程处理任何针对当前头部的 P0/P1。
• 每个已呈现的事项/线程都必须有最终处置：已修复并提交；有证据支持的驳回；有证明的过时/已修复；有具体不修复理由的后续处理/超出范围/延期；或通过续接说明包标记为受阻。
• 只有在处置完成后才能应用 THUMBS_UP 或 THUMBS_DOWN。按根因/主题归并重复的非 P1 发现后再作出反应，以便修复者能一次性连贯修复。
• 每个 THUMBS_DOWN 都必须附带一条简短的 GitHub 回复或评论，引用该发现并概述其处置和证据。
• 将 watcher 最新的 feedbackItems 和 activeCodexThreads 视为发现，而非状态。保留 watcher 的新鲜度筛选条件：codex_feedback_changed、当前头部的 reviewedCommitOid，以及不存在已有的有效性反应。除非旧评论作为新鲜内容呈现、与重复模式调查相关、在有针对性的 P0/P1 安全检查中发现，或在 Review Ledger Closure 期间仍对当前头部有效，否则不要交接来自先前头部的旧评论。

审查记录收尾

在针对预期头部报告验证成功之前，对尚未解决的 Codex 撰写的审查线程进行一次有界收尾检查。获取未解决的线程，而不是重放已解决的历史记录。成功的 watcher 结果（包括 THUMBS_UP）在此收尾检查完成前都只是暂定结果；在此之前，不要将 PR 描述为已获批准、PASS 或可合并。

• 如果某个线程的发现已不适用于当前头部，则记录过时或已修复的处置，应用有效性反应，在需要时回复，并将其标记为已解决，不要重新提出该发现。
• 如果缺陷在当前头部仍然存在，则按 Review Discipline 和 Severity Handling 处理。任何修复者提交都会改变预期头部，并要求在再次进行收尾检查前重新执行托管验证。
• Codex 撰写的审查线程仍未解决时，不要报告成功。已完成的收尾检查必须绑定到经过验证的确切头部。

重复模式

• 当同一 PR 意图的两轮或更多 Codex 轮次都集中在同一个文件、主题、子系统、不变量或源代码决策上时，判定为出现重复模式。此时流程并未结束。
• 对于同一 PR 意图，每完成第三轮反馈后，也要进行根因调查，即使评论没有集中在同一处。只有在 watcher 获取的新鲜反馈批次已确定最终处理结果时，才计为一轮；仅查询状态或过时／重复的反馈不计入。
• 任一触发条件出现时，停止逐条评论处理循环，并创建根因材料包：涵盖不同提交头中的相关 Codex 评论、接受／拒绝的处理结果、当前代码路径、关联的工单／PRD 意图、已添加的测试，以及持续失败的疑似不变量。
• 调查这些评论是否是同一错误方向导致的症状。如果根因仍在当前工单／PRD 约定和负责人边界内，优先在同一 PR 中进行连贯的修复。
• 根因调查期间，应深入阅读相关实现和测试，以充分证明预期行为。在实际可行时，再次请求 Codex 审查前，为该不变量添加或更新针对性测试。
• 如果连贯的修复超出 PR 约定、跨越负责人边界、需要产品决策，或需要新的公开接口／协议／存储约定，则以 blocked 状态停止，并提出范围最小且有证据支持的问题。不要将该结果改称为重新设计或拆分。

监视器与状态

• 每次运行监视器、发布评审请求评论、对反馈作出回应或回复、派发修复任务或关闭台账之前，都要检查 PR Head 的 isDraft。草稿 PR 不会产生任何托管评审副作用，并会将控制权交还给调用方；只有调用方重新激活 PR 后，托管评审才会恢复。
• 在前台运行监视器：node <skill-dir>/scripts/watch-codex-pr.mjs。将运行完成视为唤醒信号，然后使用 gh 再次检查 PR；只有在进程接入真正的线程唤醒机制时，才在后台运行。
• 监视器的默认行为：每 120 秒轮询一次，最长运行 30 分钟；当剩余配额较低时，等待 GitHub GraphQL 配额恢复；仅使用包含 PR 元数据和近期 PR 正文回应的精简 GraphQL 状态检查；将反馈快照限制为近期评论／评审／线程（--feedback-limit，默认值为 50）。一旦出现当前 Head 的反馈，就在每个间隔刷新受限的反馈快照，以便及时观察反馈处理结果和线程解决状态。
• 监视器反馈快照中的 feedbackItems 和 activeCodexThreads 仅包含监视器检测到的新工作，其中包括解析出的 priority 值，以及在没有 PR 正文回应的情况下出现的当前 Head Codex 反馈；没有标记的反馈仍需处理，但不能证明当前 Head 已完成。总数和过期数仅供诊断。报告超时之前，监视器会进行一次最终的受限快照；如果存在新的当前 Head 反馈，则改为发出 codex_feedback_changed。
• 将 codex_approved 和 codex_review_complete 视为验证成功。至少存在一条当前 Head 问题、每条此类问题都有有效性处理结果、没有仍处于活动状态的当前 Head Codex 线程，并且相关状态和反馈证据未被截断时，会发出 codex_review_complete。如果新的 PR 正文 THUMBS_UP 出现在 statusFreshAfter 当时或之后，且 headRefOid 仍等于 expectedHeadRefOid，则将其视为对预期 Head 的批准；无需另行要求 PullRequestReview。
• 工作流推送后，先确认远程完整 Head SHA，然后记录当前 UTC 时间戳。运行监视器时传入 --expected-head <sha> --status-fresh-after <timestamp>，并在恢复运行时保留这两个值。这样，在 Codex 发布新评审周期的 EYES、THUMBS_UP 或当前 Head 反馈之前，会忽略先前 Head 留存的 THUMBS_UP。
• 仅在手动诊断、针对性的 P0/P1 安全检查，或证据被截断而可能掩盖完成状态时由监视器进行的单次针对性核验中，使用 --full-history；因为该选项会分页获取 PR 的每条评论、评审、线程和回应，并可能耗尽繁忙 PR 的 GraphQL 配额。
• 将 Codex 针对当前评审周期发布的新的 PR 正文回应视为其状态：EYES 表示正在评审，THUMBS_UP 表示已批准；没有回应但有当前 Head Codex 反馈，表示评审已返回评论；没有回应且没有当前 Head Codex 反馈，表示 Codex 尚未评审该 PR。对反馈的回应仅是有效性标记。

循环

1. 使用 gh pr view --json number,url,headRefName,headRefOid,baseRefName,state,isDraft,mergeStateStatus,reactionGroups 确定 PR。
2. 在编辑或检查前，为 PR 分支创建或确认专用工作树；如果调用方已提供工作树，则复用。每份修复者任务包和最终报告中都记录工作树及当前 headRefOid。
3. 在等待 Codex 之前解决合并冲突。提交、推送，然后重新开始循环。
4. 当调用方明确指出：预期 head 未变，但本地检查点已更新时，执行一次检查点刷新周期：在添加一条内容恰好为 @codex review 的 PR 评论之前，立即记录当前 UTC 时间戳，作为新的审查周期时效边界；然后使用该预期 head 和边界运行常规监视循环。监视器会将该边界与请求时间戳结合。只通过发布这条请求来消费一次授权；普通修复者推送或正常恢复时，不要进入此分支。
5. 如果监视器报告验证成功，使用 gh pr view --json headRefOid,state,isDraft,statusCheckRollup 重新检查 PR，并要求其 headRefOid 等于监视器的 current.headRefOid，且 isDraft 为 false；如果 head 不同，则从新 head 及其审查周期边界重新开始；如果 PR 处于草稿状态，则将其交还调用方以便重新激活。针对该 head 运行 审查记录闭环。如果闭环导致 head 发生变化，则重新开始托管验证；否则重新检查 headRefOid,isDraft，要求 headRefOid 仍等于预期 head 且 isDraft 仍为 false，然后运行 git fetch --all --prune --tags，报告验证模式；不要为了措辞更简洁或征求第二意见而再次请求审查。
6. 如果 Codex 正在审查，则运行监视器并重新检查 PR。如果监视器输出包含当前 head 的 feedbackItems 或 activeCodexThreads，则通过审查规范和严重性处理流程处理。如果监视器超时，而当前状态仍为审查中，则停止并报告 Codex 卡住或超时；没有新输入时，不要对同一 head 再次运行监视器。
7. 如果 PR 正文中没有状态，则使用 --timeout 300 运行监视器，进行静默启动检查；重新检查 PR，并在决定是否请求 Codex 前处理任何当前 head 的反馈。
8. 如果这次 5 分钟的静默启动检查发现 PR 正文中没有状态，且没有来自 Codex 的当前 head 顶层 PR 评论、审查、行内评论或审查线程，则添加一条内容恰好为 @codex review 的 PR 评论，然后再次运行监视器。如果该周期超时，则报告 Codex 不可用、已禁用或卡住。
9. 每项新的反馈处理都启动一个全新的修复者子 Agent。仅在使用相互独立的工作树或修复明确互不重叠且推送顺序明确时，才使用多个全新的修复者。协调者负责委派修复；只有无法启动修复者时，父 Agent 才自行修复。
10. 修复者推送修复或报告无需更改代码后，根据范围基线对该轮进行分类并更新轮次历史。如果反馈在同一文件、主题、子系统或不变量上重复，则在再次进行范围较窄的修复者处理或请求审查前运行“重复模式”检查；或者每完成三轮反馈后运行一次。如果根因修复已推送，则从当前 PR head 重新开始，让 Codex 验证。
11. 仅当 Codex 验证成功、超时、受 GitHub 阻碍，或根因调查后仍存在实际阻碍时，才停止。

防护措施

• 除静默 5 分钟启动检查后的单次 @codex review 兜底、在预期 head 未变时针对明确更新的本地检查点发起的一次经调用方授权的刷新请求，或用户明确要求外，不要探查 Codex，也不要请求 Codex 审查。
• 在常规审查循环中不要运行 --full-history。如果有界快照被截断，请继续获取新的有界反馈，除非需要进行 P0/P1 安全检查，或用户明确要求审计旧的 Codex 历史记录。
• 只修改解决范围内阻塞项所需的文件。
• 除非仓库工作流明确要求，否则不要强制推送。
• 不要仅仅因为 Codex 在同一主题上发现了第二批问题就停止；要调查其根本原因。

终端报告

• 对于每种终止结果，都要包含 PR URL、Codex 是否验证过、验证成功时的验证模式、merge_ready、预期和观测到的 PR head SHA、已知时的审查周期新鲜度边界、当前 PR 状态、本地 git 数据是否已获取、已推送的提交、是否进行了 P0/P1 安全检查、是否进行了重复模式调查、审查台账的关闭结果及成功时的 head，以及按优先级和处置方式分类的已处理 Codex 评论：已修复/已接受、已驳回、已过时/已修复、后续跟进、受阻或已延期，并注明有效性反馈和不修复的理由。
• 对于未成功验证的任何终止结果，都要附上后续处理信息包，其中包含 merge_ready: false、PR URL、分支、基础分支、预期和观测到的 PR head SHA、已知时的审查周期新鲜度边界、关联的工单或 PRD URL、当前 PR 状态、检查和可合并性、Codex 处置情况、按文件/主题/评论聚类的证据、P0/P1 处置情况、相关时的根因调查记录、已推送的提交，以及下一步行动和负责人。
• 对于“受阻”状态，选择最小的下一步行动：回答产品/范围问题、授权修改约定、将工作交由正确的负责人负责、解决 GitHub/检查/合并阻塞，或等待 Codex/GitHub 恢复可用。如果工作仍在范围内，请在同一 PR 上继续，而不是延期。