mergekit

mergekit

拉取请求生命周期的另一半。无论是你、Agent 还是队友发起了拉取请求，轮到你评审时，就运行 mergekit；自己的拉取请求被退回并需要修改时，也运行它。它会将拉取请求放入 git worktree，如果该分支已有对应的 worktree，就复用它；然后运行项目，并输出一份包含你形成判断所需全部信息的评审包。接着它会等待。你说合并，它就合并；需要修改时，它会在你已经打开的 worktree 中修复。

mergekit 是唯一获准合并拉取请求的技能，这是对其余拉取请求工具链遵循的“未经明确要求，绝不合并”规则的有意例外。要获得这项权限，必须满足一个严格的前提，详见绝不自动合并：每次都由人确认具体的那个拉取请求。未经确认，mergekit 的权限与其他技能无异。

它不会对代码作出判断。评审代码是代码评审的工作；mergekit 负责准备评审，并执行你作出的决定。

何时使用

拉取请求已经存在，而你正在评审它，或者你是作者，且它被退回并需要修改：

• list。“有哪些拉取请求正在等我处理”“显示等待评审的拉取请求”“mergekit list”。
• start <n>。“把拉取请求 #34 拉下来让我测试”“为评审设置 #34”“检出这个拉取请求做 QA”。“Start #34 and sync”会额外将其同步到最新的基准分支。在此处的所有模式中，<n> 默认都是拉取请求编号。
• close [<n>]。“合并 #34”“关闭这个拉取请求”“这个没问题，合并吧”“#34 需要修改：”。如果未提供编号，close 会使用当前分支对应的拉取请求。
• **fix <n>。**作者侧操作：“我的拉取请求 CI 没通过，修复它”“处理 #34 的评审意见”“回复我拉取请求上的反馈”。它会先对反馈进行分类，再采取行动；不会看到评论就逐条照做。

如果提到了拉取请求，却没说明要执行什么操作，就默认使用 start，因为设置拉取请求是安全且可撤销的，而合并不是。

**不属于此技能：**从你的分支创建拉取请求，或判断代码质量。这些分别属于创建拉取请求的技能和代码评审技能。mergekit 从已打开的拉取请求开始，到拉取请求已合并或更新为止。

绝不自动合并

每次合并都必须由刚刚审查过该 PR 的人工明确逐个确认。直接指示合并或关闭某个 PR，即视为确认。“合并 #34”、“关闭这个 PR”，以及在分支有一个未关闭 PR 的工作树中执行 mergekit close 都算确认，因此 mergekit 无需再次询问就会合并。只有当指示存在疑问，或状态显示异常时才会询问，具体情况见关闭模式中的说明。具体来说：

• 绝不批量处理。“把它们全合并”不算对任何单个 PR 的确认。每个 PR 都要询问一次，并说明编号和标题。
• **堆栈级联是一项操作，因此只需一次确认，但确认中必须列出其中的每个 PR。**只提到最顶层 PR 的指示并未提及下方各层，因此级联时总会显示下方列出的逐项确认提示。合并堆栈中的一个 PR，会自底向上合并其下方所有尚未合并的 PR；因此，审核者同意合并顶层 PR，就表示同意合并所有这些 PR。这并非上述规则的例外，而是对规则的如实执行。提示会按合并顺序列出级联将合并的每个 PR，并附上编号和标题，确保不会合并任何未明确列出的 PR。未逐项列出的级联，正是本规则禁止的批量处理。
• **确认仅适用于已审核的 head。**确认只涵盖一个 head SHA：即记录在 start 中的 head，或指示到达时读取的 head。确认后若有推送，就产生了新变更，必须重新审核并重新确认；合并调用会携带 --match-head-commit，由 GitHub 强制执行此要求。
• **绝不推断确认。**CI 全绿、审核已批准、没有未解决的讨论串，以及本地门禁通过，都是供人工决策参考的输入，其中任何一项都不等同于决策。PR 即使完全通过所有检查，也必须等待确认。
• **绝不默认同意。**如果 mergekit 确实询问，不要将提示写成沉默即视为合并。没有答复就不合并。
• 绝不作为副作用执行。start 绝不合并。修复轮次绝不合并。只有 close 会合并，而且只能在确认之后。

同样的“预览并确认”规则适用于所有其他对外变更：推送同步、发表评论、关闭问题。先说明将要执行的操作，然后等待确认。

**在所有模式下，标签写入均属例外。**为问题或 PR 添加或移除标签时，无需提示，直接执行：移除已合并 PR 的状态标签，移除已关闭问题的 in-review 或 in-progress，将其依赖项从 blocked 切换为 ready，设置优先级。标签操作成本低、可见，而且可以通过一条命令撤销；若写入被拒绝，跟踪系统就会错误地显示已合并的工作。交接时报告每次标签变更。此例外仅适用于标签，不适用于其他操作。

预检

每种模式都从这里开始：

gh --version && gh auth status              # GitHub CLI installed + authenticated
gh repo view --json nameWithOwner           # inside a repo

• 如果缺少 gh 或未通过身份验证，请说明情况，并指向 https://cli.github.com / gh auth login。不要绕过这一要求。
• **通过 gitkit 获取基础分支。**绝不假设是 main，也不要在此处重新推导；默认分支为 develop 或 trunk 的仓库确实存在。下文中写作 origin/<base> 的所有内容，均指 gitkit 返回的值。
• 对于 start 和 close，在接触文件系统之前，确认 PR 存在且处于打开状态。

gitkit 负责的内容

mergekit 不实现工作树、基础引用检测、变基与合并规则，也不负责工作树的设置；这些都由 gitkit 实现，mergekit 会在这四种情况下调用它。mergekit 负责的是何时执行的策略：某个 PR 是否值得拉取、合并是否需要确认。是否同步由审查者决定，而不是 mergekit。 start 会报告分支落后多少，并停止，除非人类在同一句指令中要求同步（“start #34 and sync”）；否则，人类会在工作树中运行 gitkit sync。fix 总是同步，因为它已经要向该分支推送。如果你发现下面把工作树路径约定、基础引用层级或同步规则重述成 mergekit 自己的规则，那就是个 bug。

如果没有安装 gitkit，则回退到行内列出的普通 git 命令，但要保持相同的约定，不要另行发明一套。

模式

各模式的正文分别存放在 modes/ 下的一个文件中。根据 When this fires 选择模式，读取对应文件并遵循其中的说明。此行以上的所有内容适用于每种模式，模式文件中不会重述。

• 模式 list → 读取 modes/list.md，然后遵循其中的说明。
• 模式 start <n> → 读取 modes/start.md，然后遵循其中的说明。
• 模式 close [<n>] → 读取 modes/close.md，然后遵循其中的说明。
• 模式 fix <n> → 读取 modes/fix.md，然后遵循其中的说明。

注意事项

• 合并例外范围很窄。 mergekit 可以执行合并，因为有人正坐在它面前。因此，绝不能在无人值守的流水线中将其作为子 Agent 分派，因为届时无人能够进行确认，而且“编排器说可以”不等于经过了人工审查。
• 不轮询、不排队、不自动合并。 mergekit 只会在你调用它时运行。它不会监视 PR，不会启用 GitHub 的自动合并，也不会按计划执行。
• fix 也需要交互。 阅读审查反馈并判断每条评论对这个项目是否正确，需要运用判断力，因此 mergekit 不会在无人值守的情况下执行；fix 也绝不会在自动化流水线中运行。它的分类步骤需要有人在场，以便推翻其判断。这是作者侧与 start 对应的模式：它会处理 PR，但和这里的所有模式一样，绝不会合并 PR。
• 只有通过安全门控时才使用带租约的强制推送。 fix 每次运行都会同步，而 start 只会在明确要求时同步；gitkit 的同步规则默认会变基，因此 PR 分支确实会被改写。使用 --force-with-lease，绝不要只用 --force，并报告有多少个审查讨论线程因此过时。绝不要为了整理历史而强制推送；mergekit 唯一会执行的强制推送发生在同步时，而要求修复 PR 或要求开始并同步 PR 已经涵盖了这一操作。
• 对 fork PR 只读。 你可以审查并合并它们，但不能向其推送修复。在设置阶段就说明这一点，不要等到失败时才说。
• 在审查者一侧，机器人审查反馈只报告、不处理。 list 和 start 会显示尚未解决的讨论线程，然后就此停止；判断并回复这些评论是作者的工作，会在 fix 中进行。机器人的发现与人类的发现权重相同：在做出任何更改之前，都要根据项目自身的惯例进行分类。
• 没有可用的 shell 或 gh（例如基于浏览器的 Agent）？那么你无法创建工作树或调用 gh。请根据用户提供的信息打印审查资料，并以代码块形式打印设置和合并命令供用户运行；绝不要声称完成了你无法执行的合并。