pr-babysitter

PR 保姆

• **是：**持续推动一个未关闭的 PR：处理冲突、GitHub Actions/Buildkite/Vercel/Fly.io 上的 CI、收到的审查评论和合并就绪状态，然后通过仓库的合并后监控跟进合并情况；既可以作为后台监控器运行，也可以一次性修复问题。
• **不是：**创建或编辑 PR（pr-creator）、审查或修复差异本身（tidy），或处理 npm 发布 PR（autoship 会监控自己的发布 CI；绝不要照看它发起的发布 PR 或 Version Packages PR）。

模式选择

调用方式	模式
“照看”、“监控这个 PR”、“监视”、“保持绿灯”	监控：先运行一次阶段 1，然后在状态变化时运行受影响的阶段
“修复 CI”、“CI 为什么是红的”、“循环处理 CI”	一次性阶段 3 循环
“解决冲突”、“变基到 main”、“更新分支”	一次性阶段 2
“处理评论”、“回复审查者”、“分类审查评论”	一次性评论分类工作流
“准备好了吗”、“是什么阻碍了合并”	一次性阶段 5 报告

所有模式均适用的常规规则：

• 监控或修复代码本身并不授权你发布回复。只有在用户授权沟通时，才能发布回复、解决讨论串或请求审查；否则应准备回复并汇报。

• 相对于已安装的 SKILL.md 定位 scripts/fetch-comments.sh。下文的 ${CLAUDE_SKILL_DIR} 是 Claude Code 适配器变量，不是可移植的环境变量。

• 不要询问设置问题。自动检测 PR、CI 平台和默认设置（每 2 分钟轮询、自动解决无关噪声、不自动合并），然后开始运行。覆盖设置可直接在请求中指定：“每 5 分钟轮询”、“启用自动合并”。

• 跳过已关闭的 PR。除非用户提出要求，否则跳过草稿（isDraft）。已合并的 PR 应继续进行仓库的合并后监控：等待合并 SHA 上的 watch/<env> 提交状态；一旦出现 failure 或 error，立即停止并报告结果（参见 references/monitoring-setup.md 中的“合并后监控”）。如果合并到的基准提交（合并提交的第一个父提交；对于变基合并，则为 PR 变基提交之前的提交）没有 watch/* 状态，则报告“没有合并后监控”。无论哪种情况，合并进入生产环境后，都要以只读方式对其中的更改进行冒烟测试（参见同一参考文件中的“生产环境冒烟测试”），也要报告结果，然后停止。

• 评论分类会自动运行；计划文件用于审计追踪，不是审批关卡。

• 仅在状态转换时发言。轮询时若状态无变化，则保持安静。

• 同一个 PR 要复用现有监控器。指纹变化只触发受影响的阶段：有新评论时只需分类处理，不需要再次完整验证。不要在监控器旁额外添加由模型驱动的休眠/状态循环。

参考文件

文件	阅读时机
references/monitoring-setup.md	阶段 1、PR 合并后以及停止时：监控阶梯、Monitor 监控脚本、cron 后备方案、合并后监控、状态文件格式、默认设置、停止和生命周期
references/merge-conflicts.md	阶段 2：mergeStateStatus 表格、分支更新工作流、锁文件和生成文件的解决方式、中止条件
references/ci-platforms.md	阶段 3：gh pr checks 字段和退出代码、各平台的日志和重试命令、Buildkite 身份验证链、失败分类
scripts/fetch-comments.sh	评论分类：先运行 ${CLAUDE_SKILL_DIR}/scripts/fetch-comments.sh {N}。输出一份包含所有评审、讨论串和议题评论的 JSON 文档；--help 会显示输出格式
references/github-api.md	评论分类：脚本输出约定、讨论串统计、锚点阶梯、等待回复规则、回复和解决
references/bot-patterns.md	评论分类：评审者识别、严重性映射、合并门槛、噪声标记、去重、误报
references/fix-plan-template.md	评论分类：计划文件格式和允许忽略的原因
references/verification-gate.md	提交或推送之前：允许的检查时机、证据复用、残留文件清理
references/git-resilience.md	Git 命令卡住或发生临时故障时（fsmonitor 卡滞、过期的 index.lock、网络闪断）
evals/evals.json	仅在修改此技能时阅读；处理 PR 任务时绝不阅读

监控循环

阶段 1 在前台运行一次并启动监控。将每个事件或计时周期与状态文件进行比较，然后仅运行输入发生变化的阶段。宣布 PR 已就绪前，重新检查必要的就绪证据；只有发生变化时才发言。

复制此清单以跟踪进度：

PR babysit progress:
- [ ] Phase 1: Initialize (detect PR, pick watch mechanism, snapshot state)
- [ ] Phase 2: Conflict check
- [ ] Phase 3: CI check (diagnose, fix, gate, push)
- [ ] Phase 4: Comment check (triage new comments)
- [ ] Phase 5: Readiness check (report transitions, write state file)
- [ ] After merge: post-merge watch until watch/* passes, fails, or is absent, then a read-only production smoke test

阶段 1：初始化

1. 运行 gh pr view [N] --json number,url,title,state,isDraft,headRefName,baseRefName,headRefOid,mergeable,mergeStateStatus,reviewDecision。当前分支没有 PR：说明情况并停止。
2. 运行 gh repo view --json owner,name，以供需要 owner/repo 的调用使用。
3. 根据 gh pr checks --json name,link 检测 CI 平台（模式表见 references/ci-platforms.md）。
4. 选择监控机制：使用 references/monitoring-setup.md 中适用的监控阶梯第一项（harness PR 订阅、Monitor 工具、cron、无）。如果没有适用项，不要声称处于监控模式：运行相应的一次性模式，或说明此运行环境无法持续轮询。
5. 将状态快照保存到 .claude/pr-babysitter/babysit-pr-{N}.md：机制和 ID、head SHA、可合并状态、检查状态、未解决讨论串数和待回复讨论串数、评审决定。此文件夹永不暂存。
6. 用五行确认：PR、监控机制和 ID、检测到的 CI、当前状态、生效的默认设置。

阶段 2：冲突检查

运行 gh pr view --json mergeable,mergeStateStatus。DIRTY 表示需要解决冲突；BEHIND 表示需要更新；UNKNOWN 表示 GitHub 仍在计算，请在下一个计时周期重新检查；其他情况继续下一步。

git fetch origin {base} && git merge origin/{base}
git push

• 合并无冲突：通过所需检查后推送，并通知用户。
• 冲突仅涉及锁文件、生成文件或变更日志：按照参考文件重新生成，完成合并，然后通过所需检查后推送。
• 冲突涉及源代码逻辑、迁移或 API 契约：运行 git merge --abort，然后告知用户相关文件及双方各自做出的更改。这些情况需要由人决定意图。

遵循用户和代码库的分支策略。默认只做一次合并，并保留现有提交；仅在明确要求且分支由当前用户独占时才变基。绝不强制推送他人的分支，也不为继续更新而暂存共享工作区中的未提交更改。

阶段 3：CI 检查

1. 运行 gh pr checks --json name,state,bucket,link,workflow。bucket 的值为 pass、fail、pending、skipping 或 cancel；link 是详情 URL。
2. 任何检查处于 pending 状态：等待。诊断尚未完成的运行只会修错地方。
3. 对每个 fail：使用 references/ci-platforms.md 中的平台命令（GitHub Actions、Buildkite 身份验证链、Vercel、Fly.io）获取日志。
4. 根据参考文档进行分类：不稳定（重跑一次）、依赖项过时（重新安装并构建后再处理源代码）、代码错误（修复）、knip（删除无用代码或进行配置）、基础设施问题（通知；无法通过代码修复）。
5. 修复后运行验证关卡、提交并推送。标记相较先前状态的回归（之前通过、现在失败）。

单次循环（“修复 CI”）： 每次推送后运行 gh pr checks --watch --fail-fast（退出码 0 表示全部通过，1 表示有检查失败，8 表示仍有检查待处理）。检查全部通过、失败属于基础设施问题，或修复后同一检查以相同错误连续失败两次时，停止并总结。两次相同失败就是停止推送的信号，不要再尝试第三种变体。

阶段 4：评论检查

1. 统计未解决线程数，以及等待我回复的线程数（最新评论不是我发的，不论处于何种解决状态；但若某位审核者已解决自己最后一条评论，则不计入）。
2. 将这两个数量，以及审核评论和议题评论中最新的 updated_at，与状态文件中的值进行比较。原位编辑的机器人评论，以及已解决线程上的回复，都必须计入。
3. 数量有增加：运行评论分类工作流，然后通知“PR #{N} 有 N 条新审核评论”，只统计非噪声评论。如果轮询发现的新评论全是噪声（例如每次推送都会编辑的置顶 `` 评论），则本次轮询无需通知。

阶段 5：就绪检查

1. 满足以下所有条件才算就绪：mergeable == MERGEABLE；所有必需检查均为 pass；reviewDecision == APPROVED，且该审核对应的 commit_id 是 head SHA；没有未解决的阻塞线程；没有等待我回复的线程；满足所有合并关卡。
2. 合并关卡评论若写着“需要人工审核”，这是需要报告的阻塞项，并附上触发该要求的标准，而不是要修复的问题。
3. 就绪：通知“PR #{N} 已准备好合并。”合并是不可逆的操作：仅在用户选择启用后，使用仓库的合并方式运行 gh pr merge --auto。
4. 尚未就绪：指出阻塞项（“等待中：2 项检查待处理”、“等待你的答复：@reviewer 提出的 2 个问题”、“批准已过期：审核的提交为 abc1234，head 为 def5678”）。
5. 写入状态文件，供下一轮使用。

评论分类工作流

从阶段 4 或单次循环中内联执行。可自主执行：无需审批关卡，计划文件就是审计记录。

获取

运行 ${CLAUDE_SKILL_DIR}/scripts/fetch-comments.sh {N}。该脚本会翻页获取所有线程及其评论、恢复锚点、对线程分类，并根据你自己的登录名计算 owedReply。若退出码非零，会在 stderr 上打印一句原因说明；修复该原因后重新运行，不要手动编写查询。

分类前检查 reviewers[]：每个发言过的登录名都必须出现在输出中，并附有发现、结论或明确的“无内容”。有审核记录但没有评论的审核者，表示获取过程中丢失了内容。若 anchor.source == "needs-translation"，则在评估该发现前，先根据工作树完成锚点查找流程。

只有未解决线程、等待回复的线程、可采取行动的审核意见和可采取行动的议题评论全都为零时，才可提前退出。

分类

• 阅读每位作者的每条行内评论。机器人表中没有的作者属于未知作者，而非噪声；只有匹配到明确标记才算噪声。
• 按评论分类，而非按讨论串分类：机器人讨论串中的人工回复具有完整的人类权重。
• 首先根据内容判断作者类型，然后再看登录名。github-actions[bot] 既可能是审查者，也可能是噪声。
• 根据来源自身的标记判断严重程度；未知来源默认为 Major。严重程度决定队列顺序，但绝不决定是否阅读评论。
• 人类意图包括：要求修复、提问、挑错或确认。提问应得到答复，而非代码修改。绝不自动忽略人工评论：除非审查者标明为可选项，否则都要修复。
• 合并门禁判定是 Phase 5 的输入：记录下来，不修复、不回复、不解决。
• 仅对机器人评论去重（同一路径内相距不超过 3 行时，保留严重程度最高的评论）。涉及多个位置的发现视为一项。
• 每条忽略的评论都必须附上计划模板中列出的合法理由。“作者无法识别”和“讨论串已解决”不属于合法理由。

修复

1. 将计划（references/fix-plan-template.md）写入 .claude/pr-babysitter/pr-{N}-review-plan.md，打印计数，然后继续。
2. 对忽略的讨论串：回复一句话，然后解决。
3. 对问题：发布答复，并保持讨论串未解决。由审查者来解决。
4. 对已有人工回复尚未得到答复的已解决讨论串：在原处回复，不要重新打开，并在报告中注明。
5. 按逻辑分组修复，每组提交一次。遵循验证门禁的检查策略并复用有效证据；只暂存该组的文件。
6. 对每条已修复的讨论串，先回复，再解决。
7. 重新运行脚本并报告：未解决的讨论串、仍在等待我回复的讨论串、已回答但尚未得到确认的问题，以及当前 CI 状态。重新运行的结果才是证据；“所有问题都已处理”不是。

停止

收到“停止照看”或“取消监控”时，按照 references/monitoring-setup.md（Stopping、Session Lifecycle）中的说明，停止状态文件记录的机制，然后报告已处理的轮询或事件、已应用的修复、已解决的冲突、已分类的评论以及当前状态。

注意事项

• 按 isResolved == false 筛选讨论串：GitHub 会折叠已解决的讨论串，因此解决后发布的人工回复最容易被漏读。
• comments(first: 20)：讨论串评论按时间从早到晚返回，因此被截断的页面会隐藏最新评论，而最新评论决定了你是否需要回复。脚本会翻页直到读完每个讨论串。
• viewerDidAuthor 对查看者自己的评论返回 false。请将 author.login 与 gh api user --jq .login 进行比较。
• line 为 null 表示位置已过期或涉及多行，不代表 PR 级别。只有 path 为 null 才表示 PR 级别。作出判断前先找回锚点。
• 对机器人的审查正文进行分类时：正文只是计数。Codex、Devin、Copilot 和 Bugbot 都会将发现写在行内。四条正文为空的人类审查记录，实际是一次审查，其内容位于讨论串中，并非四位审查者都无话可说。
• 原地编辑单条评论的机器人（自动批准评估、DangerJS）会保留相同的 id，因此通过 id 比较状态差异时会看不到变化。请比较 updated_at。
• 将 commit_id 不是头部 SHA 的审查记录计为批准：启用“dismiss stale approvals”的分支保护规则会在下次推送时撤销该批准，在此之前 PR 会显示为就绪。
• 修复后运行 git add -A 会将钩子生成的文件（根目录下的 schema.gql）提交到 PR 中。请检查 git status --porcelain，并按路径暂存。
• 回复前就解决讨论串：审查者会看到未附回复的解决操作，并将其重新打开。
• 仅通过订阅监控无法发现冲突：基础分支出现冲突时，GitHub 不会发送 webhook。
• 如果 Monitor 可用，却仍用 Cron 运行，那么每次无活动的定时触发都会唤醒 Agent，却没有任何信号，还会消耗令牌。轮询间隔低于 2 分钟也会对 GitHub 速率限制产生同样的影响。

相关技能

• pr-creator：创建或编辑 PR；只有 PR 已存在后才开始跟进
• planning：编写计划，由新的会话执行。本技能编写的修复计划是单个 PR 的审计记录，并非 planning 的交付物
• tidy：审查并修复差异本身；本技能负责应用 GitHub 审查意见。对于监控过程中编写的修复（细小补丁除外），请运行此技能
• autoship：npm 发布流水线；它会监控自己的发布 CI，因此绝不要跟进由它驱动的发布 PR