babysit-pr

PR 生命周期运维

目标

从创建到合并后验证，全程负责拉取请求，尽可能减少人工盯守。

最终状态：

• PR 已合并，且部署运行正常。
• PR 可安全合并，正在等待人工处理。
• 遇到阻塞，需要用户协助：产品意图不明确、权限不足、工作树中存在无关的未提交更改、仅外部服务发生故障，或缺少部署可见性。

不要在“PR 已创建”或“CI 只绿过一次”时就停止。持续跟进 PR，直到满足上述某个最终状态。

常见故障模式

实际 PR 自动化过程中会遇到以下问题，需要主动处理：

监视脚本静默退出（模板解析） 如果 PR 模板解析在预检期间失败，监视脚本可能会意外退出。根本原因：resolve_pr_template.py 可能无法解析自定义模板语法，或者模板文件不可读。缓解措施：启动监视脚本前，始终先以 --json 模式运行解析器，以验证模板。如果解析失败，则改用内置默认模板 assets/default_pr_template.md。

同一 PR 启动多个监视脚本（重复评论） 针对同一 PR 运行多个 gh_pr_watch.py 实例，会导致重复处理评论，进而产生重复的机器人评论或相互冲突的重试操作。这通常发生在重启监视脚本时，没有正确停止之前的会话。缓解措施：每个 PR 只使用一个监视会话。启动前确认没有遗留的监视进程：ps aux | grep gh_pr_watch。恢复操作前，终止所有过时的会话。

CI 重试逻辑触发非偶发故障（浪费配额） 对于实际并非暂时性的故障（例如由分支特定问题导致的真实测试失败），重试逻辑可能会消耗 CI 重试额度。这会浪费配额，还可能阻碍正常问题的解决。缓解措施：重试前，务必使用 gh run view <run-id> --log-failed 检查 CI 日志。确认故障确实是偶发的，或与分支更改无关。调用 --retry-failed-now 前，严格按照 references/heuristics.md 中的启发式规则进行判断。

Markdown 格式导致评审分数提取失败 评审者在分数表述中使用 Markdown 格式时（例如 **4/5** stars 或 `4 out of 5`），评审分数提取正则表达式可能无法匹配。这会导致监视脚本遗漏明确的分数，并可能在评审者反馈尚未完成时过早合并 PR。缓解措施：分数提取器会查找 5/5 和 5 out of 5 等模式。如果评审者在分数周围使用了 Markdown 格式，请手动提取数字评分，并在继续操作前将其记录在 PR 讨论串中。

有关预防策略，请参阅下文各工作流章节中的参考资料。

默认设置

• 每 60 秒轮询一次开放 PR 的状态。
• 每个 PR 只使用一个监视会话。
• 优先修复有效的评审反馈，再重试偶发的 CI 故障。
• 如果评审者明确提出评分要求，则将其视为实际要求。
• 优先使用仓库原生模板和信号，再回退到内置默认值。

预检

1. 确认当前位于 PR 分支，而非默认分支。
2. 确认 gh auth status 可以正常运行。
3. 编辑前，检查是否存在无关的未提交更改。
4. 创建或重写 PR 正文前，先解析 PR 模板。

PR 模板处理

首先使用解析脚本：

python3 skills/babysit-pr/scripts/resolve_pr_template.py --json

⚠️ 相关注意事项： 请参阅常见故障模式中的“监视脚本静默退出（模板解析）”。启动监视脚本前，务必验证模板解析是否成功。

规则：

• 如果仓库有 PR 模板，请保留其章节结构并认真填写。
• 如果仓库没有模板，请使用随附的备用模板 assets/default_pr_template.md。
• 优先使用 gh pr create --body-file 或 gh pr edit --body-file，并准备好与解析出的模板一致的正文。
• 除非清单项明显不相关，且留空会造成误导，否则不要删除清单项。

创建工作流

1. 解析模板。
2. 编写简洁的 PR 标题。
3. 编写 PR 正文，包含摘要、测试和发布说明。
4. 推送分支。
5. 创建或更新 PR。
6. 推送成功后立即启动监视脚本。

有用的命令：

gh pr create --base <default-branch> --title "<title>" --body-file <body-file>
gh pr edit <pr-number> --title "<title>" --body-file <body-file>
python3 skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

监视脚本工作流

监视脚本会输出快照和建议操作。首先运行：

python3 skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

⚠️ 相关注意事项： 请参阅常见故障模式中的“同一 PR 启动多个监视脚本”和“监视脚本静默退出”。启动前确保没有仍在运行的过期监视进程，并确认模板解析已顺利完成。

关键操作：

• process_review_comment：检查新评论或评审，并判断其对当前分支是否有效、相关且可执行。
• improve_review_score：可信评审者给出了低于最高分的明确评分；此时不要将工作视为已完成。
• diagnose_ci_failure：检查失败日志，并判断失败是否与分支有关。
• retry_failed_checks：仅当失败看起来是偶发的或无关的，才重新运行失败的检查。
• stop_ready_to_merge：CI 全部通过，没有待处理的可信评审意见，且合并状态正常。
• stop_pr_closed：PR 已合并或关闭；如果已合并，则转入部署监控。
• stop_exhausted_retries：偶发失败的重试额度已用尽；请提供证据并向用户寻求帮助。

CI 失败处理策略

使用 references/heuristics.md 中的分类检查清单。

⚠️ 相关注意事项： 请参阅常见故障模式中的“CI 重试逻辑会因非偶发故障而触发”。重试前务必检查日志，避免将配额浪费在实际故障上。

默认命令：

gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
gh run view <run-id> --log-failed
python3 skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now

规则：

• 与分支有关的失败：修复问题，运行最有针对性的有效验证，提交、推送，然后重新启动监视脚本。
• 偶发或无关的失败：检查一次日志并确认其可能是暂时性问题后，才重新运行。
• 仅限基础设施的故障、身份验证问题或缺少权限：说明阻碍并停止。

评论和评审处理

对于可信人士和经批准的 Bot 提出的反馈，只要技术上正确、可执行且符合用户意图，就应予以采纳。

出现新反馈时：

1. 验证反馈是否与当前 PR 相关。
2. 如果需要采取行动，则实施最小且正确的修复。
3. 进行有针对性的验证。
4. 提交并推送。
5. 立即重新启动监视脚本。

以下反馈应忽略或上报：

• 已解决
• 明显是噪声
• 含糊不清
• 与用户的明确指示相矛盾
• 受无关的未提交更改或更广泛的产品决策阻碍

评审评分

监控器现在会从可信的评论和评审中提取 5/5 和 5 out of 5 等明确的评分表述。

⚠️ 相关注意事项： 请参阅常见失败模式中的“因 Markdown 格式导致评审评分提取失败”。如果评审者在评分周围使用 Markdown 格式，请在继续之前手动提取评分。

规则：

• 如果评审者给出的明确评分低于满分，即使 PR 在技术上已可合并，也应视为工作尚未完成。
• 在将 PR 标记为完成之前，应争取获得最高评分。
• 做出改进后，应等待评审者更新反馈，不要假定评分已经提高。

Git 安全

• 仅在 PR 头部分支上工作。
• 避免执行具有破坏性的 Git 操作。
• 不要为同一个 PR 运行多个监控进程。（请参阅常见失败模式中的“同一 PR 上运行多个监控器”。）
• 如果发现与当前任务无关的未提交工作树更改，请停止并在编辑前询问用户。

合并后的部署监控

合并后，启动部署监控器：

python3 skills/babysit-pr/scripts/gh_deploy_watch.py --pr auto --watch

部署监控器会使用与合并提交关联的 GitHub 部署记录和类似部署的工作流运行。监控器会以以下某种操作停止：

• wait_deployment：存在部署信号，且部署仍在运行。
• wait_for_deployment_signal：PR 最近刚合并，宽限期尚未结束。
• alert_deployment_failure：部署信号失败；请检查日志并决定是否发布修复。
• validate_production：部署信号看起来成功；请运行范围最小且有用的生产验证。
• no_deployment_signal：宽限期结束后，仍未找到机器可读的部署信号。
• stop_pr_not_merged：PR 尚未合并。

有关特定提供商的后续处理、冒烟测试、日志和指标指南，请使用 references/deployment-monitoring.md。

输出预期

• 在稳定监控期间，保持进度更新简洁。
• 推送修复时，概述根本原因和更改内容。
• 停止时，报告终止状态及其依据。

参考资料

• references/heuristics.md
• references/github-api-notes.md
• references/deployment-monitoring.md