SuperAPI AI 工具集

mergepatrol

编程与开发

查看项目

更新于 11-03 17:01

技能介绍

Mergepatrol 是一个标签驱动的合并队列,用于让仓库中的拉取请求(PR)有序地进入队列并自动完成合并。仓库中的 PR 通过 Mergepatrol 落地,手动合并或直接向默认分支推送会与队列产生竞争。

用途

  • 为默认分支及 .mergepatrol/mergepatrol.yml 中 branches 列出的每个分支维护队列;PR 或来自 gh stack 的 PR 堆叠进入其目标分支的队列。
  • 合并到其他分支(例如手工堆叠在另一 PR 分支上的 PR)会被扣留。
  • 重定向已排队的 PR 会把它移到另一分支队列的末尾。

主要能力

  • 标签触发:在 .mergepatrol/mergepatrol.yml 中配置触发标签,默认 mergepatrol。给 PR 添加该标签即入队;移除则离队并取消其运行。<label>:priority 置于队首;<label>:failed 由 Mergepatrol 在弹出 PR 时设置。
  • MCP 集成:连接 mergepatrol MCP 服务器后,可用 queue_pull(支持 priority 置于队首)、dequeue_pull、pull_status、list_queue 等工具替代标签操作,它们以所连接用户或机器人的身份修改相同标签。pull_status 直接读取 PR 所处位置,无需解析评论。服务器其他工具对应 Mergepatrol 仪表盘的功能,例如审查 PR 或读取队列弹出原因。
  • 队列处理:将 PR 变基到其基线分支,可与其他排队 PR 成批测试;由代理解决冲突,运行仓库的校验命令,等待必需检查,再按仓库默认合并方式合并。必需检查失败时代理会向 PR 分支提交修复并重跑检查,最多若干次,除非 fix_ci 关闭。
  • 堆叠:一个堆叠是队列中的一个条目。给其中任一 PR 打标签即整栈入队,整栈等待所有 PR 就绪;变基时重写每一层,并一次性全部合并(全有或全无)。弹出堆叠时其中每个 PR 都会获得 <label>:failed。
  • 变基会重写 PR 分支,修复会新增提交;向已排队 PR 推送更多提交前应先 fetch 并基于远程分支变基,推送会使 Mergepatrol 重新开始该 PR。

状态读取

Mergepatrol 在每个排队 PR 上维护一条评论,内容为:

  • On hold:PR 是草稿、等待必需审查或存在要求修改;评论会说明原因,保留位置,待 GitHub 显示就绪后运行。
  • Under review:默认开启自动审查,代理在 PR 取得位置前先审查。确定应修改的内容以行内审查评论形式发回作者;所有审查线程解决后 PR 继续,无需人工批准。仅就作者无法决定的问题(范围或产品判断、访问权限、仓库外改动)询问人工。MCP 的 get_agent_review 可读取审查。
  • Ejected:变基、检查或合并失败,评论说明原因;触发标签被移除,<label>:failed 被添加。修复原因、推送后重新添加标签。
  • Merged:完成,队列标签被移除。

排队之后:处理审查

入队并非工作终点。构建 PR 者应持续跟进,直到合并、被弹出或仅剩需人工项。逐一处理每条审查评论:修复或附理由驳回,并解决线程。存在未解决线程时 PR 被扣留,全部解决后进入队列。仅对无法从代码、仓库和用户信息中决定的事项询问人工。

什么算作评论

每个未解决审查线程都算一条评论:Mergepatrol 审查发现的每条会阻塞 PR 的发现各成一线程;人类审查者或其他机器人的线程;以及请求修改的审查和提出修改请求的顶层评论。审查已清除的发现和其栏下备注无需处理。Mergepatrol 跨推送对同一发现保持一条线程:再次发现时在该线程回复并重新打开;发现已修复或回复在代码中成立时,它自行解决线程。只应基于 PR 当前 head 的审查作出处理,旧 head 的审查可能在你推送后到达并已过时。

评论状态

  • open:尚未处理。阅读并查看所指代码,然后修复、驳回或标记为 needs-human。
  • fixed:已推送的提交实现了要求。在线程回复提交短 SHA 和一行变更说明后解决;仅在推送后解决。
  • dismissed:不适用,且有代码可证明。在线程回复理由和证据(文件与行号、测试、文档),然后解决。
  • needs-human:仅人工可决定。回复所需决定和选项,@相关人员,保持未解决。

以下情况才属于 needs-human:PR 应做什么或包含什么(范围)、产品或设计判断、你没有的凭据或访问权限、本仓库之外的改动,或审查者在驳回后重新打开线程。“我不确定”不属于此类,应继续阅读代码、运行或先询问审查者。审查保持对抗性:下次推送会读取你的回复,理由在代码中不成立时会重新打开已驳回线程。

循环流程

  1. 等待当前 head 的审查;待定或运行中每隔几分钟轮询 pull_status、get_agent_review 或 Mergepatrol 评论,期间不要推送。
  2. 列出未解决线程并与台账匹配;重新打开的线程视为新一轮。
  3. 将每个 open 处理为 fixed、dismissed 或 needs-human;尽量合并较少提交。
  4. 如有修复则推送一次;先 fetch 并变基到远程分支。
  5. 在每个已处理线程中回复,并解决 fixed 与 dismissed 的线程;无回复不得解决。
  6. 更新台账。
  7. 推送后回到步骤 1;当只剩 needs-human 线程未解决,或 PR 已合并/弹出时停止。被弹出的 PR 修复原因、推送并重新添加标签。

无未解决线程且无需人工处理时,PR 自动进入队列,无需人工批准。

审查发现与限制

  • 不要对你自己构建的 PR 调用 answer_agent_review,也不要用 review_pull 批准自己的 PR。
  • 连续三次审查均退回发现后,下一次会就剩余问题询问人工,不应再以第四次修复硬碰。
  • 可用 ask_agent_about_review(提供 head_sha 和 finding id)让审查者立即判定,回复以 VERDICT: withdrawn 或 VERDICT: stands 结尾。
  • 关于未检查项的发现(如“从未在设备上运行”“没有测试覆盖”)在自己能处理时由自己关闭:运行或编写测试并在回复中说明。确实无法处理(如没有设备)才标 needs-human,并说明人工需运行什么。

台账

在 PR 上保留一条评论,列出每条评论及其状态,每轮编辑而非新发;以 <!-- mergepatrol-review-ledger --> 开头以便找回,跨轮保留每行并记录提出该评论的 head SHA。示例表格包含 Comment、Raised on、State、Note 四列。

禁止事项

  • 不要在修复提交推送前或无理由回复时解决线程。
  • 不要在人工答复前解决 needs-human 线程或 Mergepatrol 询问人工的线程。
  • 不要在属于线程或台账的内容上另发新评论。
  • 停止时不得留下未处理的评论;每条都应归于 fixed、dismissed 或 needs-human。
  • 不要为可自行处理的事项打扰人工。

停止时向用户说明 PR 状态:已合并、因何被弹出,或每条 needs-human 评论需要谁做什么。

设置

.mergepatrol/mergepatrol.yml 可设置标签、批量大小、冲突解决器、校验命令、fix_ci 和 review。Mergepatrol 从默认分支读取该文件,因此修改在对应 PR 合并后生效。

限制与暂未提供

来自 fork 的 PR 仅按打标签时的状态合并:之后向它推送会使其离队,直到维护者重新添加标签;它不进入批量、不获得代理,冲突或检查失败即被弹出。仅当作者允许维护者编辑时,Mergepatrol 才能推送其变基。资料未说明具体定价、支持平台、安装步骤或性能指标。