mergekit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mergekit

The other half of a pull request's life. Something else opened it, whether you, an agent, or a teammate; mergekit is what you run when it is your turn to judge it, and what you run when your own PR comes back needing changes. It gets the PR into a git worktree, reusing the one the branch already lives in when there is one, syncs it with the base branch, gets the project running, and prints a review pack of everything you need to form an opinion. Then it waits. When you say merge, it merges; when it needs changes, it fixes them in the worktree you already have open.

mergekit is the one skill permitted to merge a pull request, a deliberate exception to the "never merge without an explicit ask" rule the rest of a PR toolchain holds. That permission is earned by a single hard precondition, stated in Never merge automatically: a human confirms that specific PR, every time. Without the confirmation, mergekit has no more authority than any other skill.

It forms no opinion about the code. Judging the source is a code-review job; mergekit sets the review up and executes the decision you reach.

Pull Request（PR）生命周期的后半段。PR可能由你、Agent或队友创建；当轮到你评审PR，或者你自己提交的PR收到修改反馈时，就可以运行mergekit。它会将PR导入到git worktree中（如果该分支已有对应的worktree则直接复用），同步基础分支，启动项目，并生成一份包含所有你需要的评审信息的评审包。之后它会等待你的指令：当你要求合并时，它执行合并操作；当PR需要修改时，它会在你已打开的worktree中进行修复。

mergekit是唯一被允许合并PR的skill，这是对PR工具链中“无明确请求绝不合并”规则的刻意例外。这种权限源于一个严格的前提条件，在禁止自动合并中说明：每次都必须由人工确认该特定PR。没有确认的话，mergekit的权限和其他skill并无区别。

它不会对代码发表任何意见。判断代码质量是代码评审的工作；mergekit仅负责搭建评审环境并执行你做出的决策。

When this fires

触发场景

The PR already exists, and you are either reviewing it, or you authored it and it has come back needing changes:

list. "What PRs are waiting on me", "show me the ready-for-review PRs", "mergekit list".
start
<n>
. "Pull PR #34 down so I can test it", "set up #34 for review", "check out this PR for QA", "get #34 merge-ready".
finish
<n>
. "Merge #34", "this one's good, land it", "#34 needs changes: <findings>".
fix
<n>
. The author's side: "my PR is red, fix the CI", "address the review comments on #34", "respond to the feedback on my PR". It triages the feedback before acting on it; it does not apply every comment on sight.

If a PR is named but the action isn't, assume

start

, because setting a PR up is safe and reversible while merging is not.

Not this skill: opening a PR from your branch, or judging whether the code is any good. Those belong to a PR-authoring skill and a code-review skill respectively. mergekit begins at an open PR and ends at a merged or updated one.

PR已存在，且你要么正在评审它，要么你是PR作者且收到了修改反馈：

list. “哪些PR在等待我处理”、“显示已准备好评审的PR”、“mergekit list”。
start
<n>
. “拉取PR #34到本地以便测试”、“为评审搭建#34的环境”、“检出这个PR用于QA测试”、“将#34准备好合并”。
finish
<n>
. “合并#34”、“这个没问题，合并它”、“#34需要修改：<修改意见>”。
fix
<n>
. 作者视角：“我的PR CI失败了，修复CI”、“处理#34上的评审意见”、“回复我的PR收到的反馈”。它会先分类处理反馈，不会盲目应用所有评论。

如果只指定了PR编号但未说明操作，则默认执行

start

，因为搭建PR环境是安全且可逆的，而合并操作不可逆。

不属于该skill的场景： 从你的分支创建PR，或者判断代码质量。这些分别属于PR创建skill和代码评审skill的职责。mergekit从已打开的PR开始，到PR被合并或更新结束。

Never merge automatically

禁止自动合并

Every merge requires an explicit, per-PR confirmation from a human who has just reviewed that PR. Concretely:

Never a batch. "Merge them all" is not a confirmation for any individual PR. Ask once per PR, naming the number and title.
Never inferred. Green CI, an approving review, zero unresolved threads, and a passing local gate are inputs to the human's decision, and none of them is the decision. A perfectly green PR still waits.
Never default-yes. Don't phrase the prompt so silence merges. No answer means no merge.
Never as a side effect.
```
start
```
never merges. A fix round never merges. Only
```
finish
```
merges, and only after the confirmation.

The same preview-and-confirm rule covers every other outward-facing mutation: pushing a sync, commenting, relabeling, closing an issue. Show what will happen, wait for the OK.

每次合并都必须由刚刚评审过该PR的人工明确确认。具体规则：

绝不批量合并。 “全部合并”不能作为任何单个PR的确认指令。需针对每个PR单独请求，说明PR编号和标题。
绝不推断合并。 CI通过、评审通过、无未解决线程、本地检查通过只是人工决策的参考因素，而非决策本身。即使PR状态完全正常，仍需等待人工确认。
绝不默认同意。 不要设置沉默即同意的提示。无回复意味着不合并。
绝不作为副作用执行。
```
start
```
操作绝不会触发合并。修复环节也不会触发合并。只有
```
finish
```
操作会执行合并，且必须在确认之后。

同样的“预览-确认”规则适用于所有对外的变更操作：推送同步、评论、重新标记、关闭Issue等。先展示将要执行的操作，等待确认后再执行。

Preflight

预检

Every mode starts here:

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

If
```
gh
```
is missing or unauthenticated, say so and point to
```
https://cli.github.com
```
/
```
gh auth login
```
. Don't work around it.
Get the base branch from gitkit. Never assume
```
main
```
, and don't re-derive it here; repos that default to
```
develop
```
or
```
trunk
```
are real. Everything below written as
```
origin/<base>
```
means whatever gitkit returns.
For
```
start
```
and
```
finish
```
, confirm the PR exists and is open before touching the filesystem.

所有模式都从以下步骤开始：

gh --version && gh auth status              # GitHub CLI已安装并认证
gh repo view --json nameWithOwner           # 当前处于仓库目录中

如果
```
gh
```
未安装或未认证，需告知用户并指向
```
https://cli.github.com
```
/
```
gh auth login
```
。不得绕过此步骤。
从gitkit获取基础分支。 绝不默认使用
```
main
```
，也不要在此重新推导；有些仓库默认分支是
```
develop
```
或
```
trunk
```
是真实存在的。下文所有写为
```
origin/<base>
```
的地方，均指gitkit返回的基础分支。
对于
```
start
```
和
```
finish
```
操作，在修改文件系统之前，需确认PR存在且处于打开状态。

What gitkit owns

gitkit的职责范围

mergekit does not implement worktrees, base-ref detection, or the rebase-versus-merge rule, because gitkit does, and mergekit calls it for all three. What mergekit owns is the policy about when: that a PR is worth pulling down, that a sync should happen before a human reads the diff, that a merge needs a confirmation. If you find a worktree path convention, a base-ref ladder, or a sync rule restated below as mergekit's own, that is a bug.

When gitkit isn't installed, fall back to the plain git commands named inline, but keep the same convention, and don't invent a different one.

mergekit不实现worktree、基础分支检测或变基/合并规则，因为这些都是gitkit的职责，mergekit会调用gitkit来处理这三项任务。mergekit的职责是策略层面的时机控制：判断PR是否值得拉取到本地、在人工查看diff前执行同步、合并需要确认等。如果发现下文将worktree路径约定、基础分支优先级或同步规则列为mergekit的职责，那就是一个bug。

如果未安装gitkit，则回退到文中提到的原生git命令，但需遵循相同的约定，不得自行发明新规则。

Mode

list

: the morning dashboard

Mode

list

：晨间仪表盘

What is actually waiting on you, in one table:

gh pr list --state open --json number,title,headRefName,isDraft,statusCheckRollup,reviewDecision,author,updatedAt

Three facts that command cannot give you matter more than the ones it can, so gather them per PR:

Unresolved review threads. REST does not expose thread resolution state at all; only GraphQL does, via a
```
reviewThreads
```
connection carrying
```
isResolved
```
and
```
isOutdated
```
. Query it with
```
gh api graphql
```
; if the shape has moved, check the current GraphQL API docs rather than guessing. A PR with a bot review sitting unanswered is not ready for your time.
Behind the base branch. Run
```
git fetch origin
```
once, then compare each head against
```
origin/<base>
```
, because a PR that is behind is one you would be reviewing in a state that will never exist.
A QA plan and proof. Look for the artifacts your repo's conventions produce (a QA plan doc, a proof bundle, whatever the PR body links). Absence is a fact worth printing, not a silence.

Print one table, most-ready first, with drafts and PRs authored by others clearly marked. Do not crown a "next" PR, because ranking work is a project-status job, and a reviewer's queue is theirs to order.

以表格形式展示所有等待你处理的PR：

gh pr list --state open --json number,title,headRefName,isDraft,statusCheckRollup,reviewDecision,author,updatedAt

有三个该命令无法获取的信息比它能获取的更重要，因此需要为每个PR收集这些信息：

未解决的评审线程。 REST API完全不暴露线程的解决状态；只有GraphQL API可以通过
```
reviewThreads
```
连接获取
```
isResolved
```
和
```
isOutdated
```
字段。使用
```
gh api graphql
```
进行查询；如果字段结构发生变化，请查看当前的GraphQL API文档，不要猜测。如果PR存在未回复的机器人评审，则尚未准备好让你处理。
落后于基础分支。 先执行
```
git fetch origin
```
，然后将每个PR的头部与
```
origin/<base>
```
进行比较，因为落后于基础分支的PR，你评审的状态是永远不会上线的。
QA计划和验证材料。 查找仓库约定生成的工件（如QA计划文档、验证包、PR正文中链接的任何内容）。如果缺失，需明确说明，而非保持沉默。

打印一个表格，按可处理优先级排序，草稿和他人提交的PR需明确标记。不要指定“下一个”PR，因为工作排序是项目状态管理的职责，评审者的队列应由他们自己排序。

Mode

start <n>

: make it merge-ready

Mode

start <n>

：准备好合并

1. Resolve the head

1. 解析PR头部信息

gh pr view <n> --json headRefName,headRepositoryOwner,isCrossRepository,author,title,body,url

A cross-repository (fork) PR is read-only from here: you can review and merge it, but you cannot push fixes to the contributor's branch. Say that plainly at setup time rather than letting it surface as a confusing push failure later.

gh pr view <n> --json headRefName,headRepositoryOwner,isCrossRepository,author,title,body,url

跨仓库（分叉）PR是只读的：你可以评审并合并它，但无法向贡献者的分支推送修复。在设置阶段需明确告知用户，避免后续出现令人困惑的推送失败。

2. Get a worktree, adopting first and creating only if needed

2. 获取worktree，优先复用已有worktree，仅在需要时创建

Hand this to gitkit, keyed on the PR's head branch. The key point, and the reason this step is not "create a worktree": a PR's branch very often already has one, because the branch was implemented in a worktree on this same machine, and that worktree is still sitting there. Git allows a branch to be checked out in exactly one worktree, so creating a second one for the review does not merely duplicate work, it hard-fails:

fatal: 'feature-x' is already used by worktree at '.../wt-a'

So: resolve the head branch, look it up, and reuse the worktree that already holds it. Create one only when the branch has none.

Same-repo PR. Fetch the head branch (
```
git fetch origin <head>:<head>
```
or
```
git fetch origin
```
plus a local checkout), then ask gitkit for that branch's worktree. Pushes from it go back to the PR.
Fork PR. There is no local branch yet, so one must be invented:
```
git fetch origin "pull/<n>/head:pr-<n>-<slug>"
```
, where
```
<slug>
```
is the head branch name kebab-cased and capped at roughly 40 characters. Then the worktree is created on that branch, and takes its name.
Already have one. Adopt it and say so. Re-running
```
start
```
is a normal thing a reviewer does; it must never error, and must never blow away work in progress. If the adopted worktree is dirty, report what's uncommitted before doing anything else and let the reviewer decide whether to continue, because you are standing in someone's live workspace, possibly mid-change, not a scratch checkout.

The worktree lands wherever gitkit's convention puts it, outside the repository rather than in a

.worktrees/

directory inside it. An in-repo worktree gets swept into docker build contexts, bind mounts, and file watchers, and every one of those failures surfaces far from its cause. Nothing here needs a

.git/info/exclude

entry.

将此任务交给gitkit，以PR的头部分支为键。 关键在于，此步骤不是“创建一个worktree”：PR的分支通常已经有对应的worktree，因为该分支可能就是在同一台机器上的worktree中实现的，且该worktree仍然存在。Git允许一个分支仅在一个worktree中被检出，因此为评审创建第二个worktree不仅会重复工作，还会直接失败：

fatal: 'feature-x' is already used by worktree at '.../wt-a'

因此：解析头部分支，查找对应的worktree，复用已有的worktree。仅当分支没有对应的worktree时才创建新的。

同仓库PR。 拉取头部分支（
```
git fetch origin <head>:<head>
```
或
```
git fetch origin
```
加上本地检出），然后请求gitkit获取该分支的worktree。从该worktree推送的内容会回到PR。
分叉PR。 此时没有本地分支，因此需要创建一个：
```
git fetch origin "pull/<n>/head:pr-<n>-<slug>"
```
，其中
```
<slug>
```
是头部分支名称的短横线格式，长度约限制在40字符以内。然后基于该分支创建worktree，并以该分支命名。
已有worktree。 复用该worktree并告知用户。重复运行
```
start
```
是评审者的正常操作；绝不能报错，也不能清除正在进行的工作。如果复用的worktree存在未提交的内容，在执行任何操作之前先报告未提交的内容，让评审者决定是否继续，因为你进入的是他人的活跃工作区，可能正处于修改过程中，而非临时检出的环境。

worktree的位置遵循gitkit的约定，放在仓库外部，而非仓库内部的

.worktrees/

目录中。仓库内部的worktree会被纳入docker构建上下文、绑定挂载和文件监视器，这些问题的根源很难排查。此处无需添加

.git/info/exclude

条目。

3. Sync with the base branch

3. 与基础分支同步

Bring

origin/<base>

into the PR branch before the human reviews, so they review what will actually land:

git fetch origin
git rev-list --left-right --count origin/<base>...HEAD    # "<behind>\t<ahead>"; left > 0 means behind

If behind, hand the sync to gitkit, which owns the rebase-versus-merge rule in full. What mergekit owns is the when: that the sync happens before a human reads the diff, and that nothing leaves this machine without their OK.

Two things follow from gitkit's rule that matter specifically here. A PR branch is published, so the sync is in the preview-and-confirm class: one prompt covering the rebase and its

--force-with-lease

push, never a silent rewrite of a branch a reviewer may already be looking at. And this is the one place the merge exception's trigger actually fires: the review pack already queries unresolved review threads, so feed that count into the preview, because a rebase marks every one of them outdated, and the reviewer is about to spend their attention on exactly those threads. Name the number, still recommend the rebase, and let them take the merge if the threads are worth more than the history.

On conflict: stop and surface it. List the conflicted files (

git diff --name-only --diff-filter=U

), propose a resolution for each, and confirm before writing. Then, before pushing, run the repo's own test and build gate, because a conflict resolution is a code change, and it can break something CI passed on five minutes ago. Push the sync only after the gate is green and the human has OK'd it, so the PR itself becomes mergeable on GitHub. On a fork PR you cannot push; say so, and keep the sync local for review purposes only.

在人工评审之前，将

origin/<base>

同步到PR分支，确保评审的内容是最终会上线的版本：

git fetch origin
git rev-list --left-right --count origin/<base>...HEAD    # 格式为"<落后数量>\t<超前数量>"; 左侧大于0表示落后

如果落后于基础分支，将同步任务交给gitkit，它完全负责变基/合并规则。mergekit的职责是时机控制：在人工查看diff前执行同步，且任何变更在未得到人工确认前不得推送到远程。

gitkit的规则有两点在此处尤为重要。PR分支已发布，因此同步属于预览-确认类操作：需弹出一个提示，涵盖变基和

--force-with-lease

推送操作，绝不能静默重写评审者可能正在查看的分支。这也是合并例外规则的触发点：评审包已经查询了未解决的评审线程数量，因此将该数量纳入预览，因为变基会使所有未解决线程标记为过时，而评审者正关注这些线程。说明线程数量，仍建议执行变基，如果线程的重要性超过历史记录，让评审者选择合并方式。

遇到冲突时： 停止操作并提示冲突。列出冲突文件（

git diff --name-only --diff-filter=U

），为每个文件提出解决方案，确认后再修改。然后，在推送之前，运行仓库自身的测试和构建检查，因为冲突解决是代码变更，可能会破坏五分钟前CI通过的内容。只有在检查通过且人工确认后，才能推送同步，使PR在GitHub上变为可合并状态。对于无法推送的分叉PR，需告知用户，并仅在本地执行同步用于评审。

4. Set the project up

4. 搭建项目环境

Detect the manifest (

package.json

pyproject.toml

go.mod

Gemfile

Cargo.toml

, …) and run the install the repo actually uses: the lockfile tells you which package manager, the scripts tell you the dev command. Prefer a project-local run or dev skill when one exists. Never invent a command: if you cannot determine how to start the app, say so and ask, rather than guessing at a

dev

script that doesn't exist. Copy

.env.example

.env

only if that is the repo's documented setup and the file is absent.

检测项目清单文件（

package.json

、

pyproject.toml

、

go.mod

、

Gemfile

、

Cargo.toml

等），运行仓库实际使用的安装命令：锁文件会告诉你使用哪个包管理器，脚本会告诉你开发命令。如果存在项目本地的运行或开发skill，优先使用。绝不自行发明命令：如果无法确定如何启动应用，需告知用户并询问，而非猜测不存在的

dev

脚本。仅当仓库有明确文档说明且

.env

文件不存在时，才将

.env.example

复制为

.env

。

5. Print the review pack

5. 打印评审包

Everything the reviewer needs, assembled once so they don't go hunting:

PR title, number, author, URL, and the body's summary.
The linked issue and its acceptance criteria, when the PR references one.
The commits (
```
git log origin/<base>..HEAD --oneline
```
) and the file-level shape of the diff (
```
--stat
```
).
The QA plan, if the repo has one for this change, and any proof artifacts.
Unresolved review threads with
file:line
and the comment text, bot or human. This is the highest-value part of the pack: it is what the reviewer would otherwise re-derive by hand.
Any follow-up nits the PR body itself records.
CI status per check, and whether the branch is now in sync.

Name what is missing. "No QA plan in this repo's conventional location" is information; printing nothing where a QA plan would go is not.

收集评审者需要的所有信息，一次性提供，无需他们自行查找：

PR标题、编号、作者、URL和正文摘要。
如果PR引用了Issue，需包含链接的Issue及其验收标准。
提交记录（
```
git log origin/<base>..HEAD --oneline
```
）和diff的文件级统计（
```
--stat
```
）。
如果仓库对此变更有QA计划，需包含QA计划和任何验证工件。
未解决的评审线程，包含
file:line
和评论内容，无论是机器人还是人工评论。这是评审包中最有价值的部分：评审者无需手动整理这些信息。
PR正文中记录的任何后续优化点。
每个检查的CI状态，以及分支是否已同步。

明确说明缺失的内容。 “仓库约定位置未找到QA计划”是有效信息；而在QA计划位置留白则不是。

6. Hand off

6. 交接

Write every hand-off in this skill in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

What changed. Report whether the worktree was adopted or created, and whether a sync was pushed (and if so, whether it rebased or took the merge exception, and how many threads it outdated). Nothing else here mutates anything.

Where it landed. Two lines: the worktree path, and the single command that starts the app.

Next. The reviewer reads, runs, and forms an opinion; then

finish <n>

executes whichever verdict they reach, whether a merge or a fix round. Say both halves, so it's clear merging isn't the assumed outcome.

Then stop, because the human reviews and tests. mergekit does not judge the code, and does not proceed to

finish

on its own.

本skill中的所有交接内容均使用流程化表述：每句一个指令，主动语态，一般现在时，无隐喻。

变更内容。 报告worktree是复用还是创建的，以及是否推送了同步（如果是，说明是变基还是采用合并例外，以及使多少线程过时）。此步骤不会执行其他变更。

位置信息。 两行内容：worktree路径和启动应用的单个命令。

下一步操作。 评审者阅读、运行并形成意见；然后执行

finish <n>

来执行他们的决定，无论是合并还是修复。需说明两种可能，避免默认合并为预期结果。

然后停止操作，等待人工评审和测试。mergekit不会判断代码质量，也不会自动执行

finish

操作。

Mode

finish <n>

: merge or fix

Mode

finish <n>

：合并或修复

The reviewer has formed an opinion. Which fork you take depends entirely on which one they state.

评审者已形成意见。执行哪个分支完全取决于评审者的指令。

Merge path

合并流程

Confirm, per Never merge automatically. Name the PR number and title, state what you are about to do, and wait.
Approve, when it's possible. GitHub does not permit approving your own pull request, so on a self-authored PR (the common case when an agent opens PRs under your account) skip the approval, say once that it was skipped and why, and merge directly. When the author is someone else (or a machine identity), offer
```
gh pr review <n> --approve
```
first.
Merge with a merge commit and a fixed subject:
sh
```
gh pr merge <n> --merge --subject "chore(repo): merge pull request #<n>"
```
No squash, no rebase-merge. If your repo's merge-commit convention differs, that subject is the one line to change.
Hand the landing off to the tracker with
close
, then
sync
. A merge is a tracker event as much as a git one, and both halves belong to an issue-lifecycle skill rather than to mergekit. Invoke issuekit for each, in this order, rather than doing any of it here:
- close <n>
  , for the issue this PR closes. Closing the issue, ticking a parent checklist, unblocking dependents, and reclaiming the issue's worktree are one action, and
```
close
```
  gates on the merged PR you just produced, previews the whole consequence, and tears the worktree down through gitkit. Skip it only when the PR genuinely references no issue.
- sync
  , immediately after, including when there was no issue to close.
```
close
```
  lands the one issue you named;
```
sync
```
  sweeps for what the merge shook loose around it: a second issue the PR body closed, a link the PR never carried, a parent checklist still un-ticked, a dependent left
```
blocked
```
  on a prerequisite that just landed. That drift is invisible from here, because mergekit sees one PR where
```
sync
```
  reads the whole tracker, and it is cheapest to repair now, while the merge that caused it is the thing everyone is looking at.
Both modes preview before they mutate, so the pair costs a confirmation, not a surprise. Without issuekit installed, fall back to plain
```
gh issue close
```
/
```
gh issue edit
```
calls, previewed and confirmed like any other mutation, and say that the tracker-wide sweep did not happen, rather than implying the tracker is now clean.
Clean up only what you created. After the handoff, one thing may be left that no issue-lifecycle skill knows about: the fork-PR case, where mergekit invented both the
```
pr-<n>-<slug>
```
branch and its worktree. Remove that through gitkit.
Everything else stays. Get a worktree may have adopted an existing worktree, and an adopted worktree is someone else's context: the workspace the feature was implemented in, possibly with an editor and a dev server pointed at it. Never remove a worktree you adopted on your own initiative, and never delete a branch you did not create. Say what you are leaving behind instead.

Teardown is idempotent: a worktree that is already gone reports "already gone" rather than erroring. A dirty worktree stops teardown, so show what would be lost instead of forcing the removal.
Hand off.
What changed. Report the PR merged (number, title, merge commit), whether the approval was skipped and why, and what each half of the issue-lifecycle handoff did:
```
close
```
's issue closed, parent ticked, dependents unblocked, and then what
```
sync
```
reconciled beyond it. A sweep that found nothing is a result worth stating in a line; it's the difference between a clean tracker and one nobody looked at.
Where it landed. Say which worktrees were removed and which were deliberately left standing, with paths. An adopted worktree that survives is someone's live workspace; naming it is how they know it's still theirs.
Next. A merge frees capacity, so point at what fills it, naming a kit only when it's installed: an issue this merge unblocked, from either the
```
close
```
or the
```
sync
```
pass, is the strongest candidate (issuekit
start <n>
), otherwise the next PR waiting on you (
```
list
```
), otherwise statuskit to re-orient. If a dependent was unblocked and another PR is waiting, the PR wins, because finishing outranks starting.

确认，遵循禁止自动合并规则。说明PR编号和标题，告知将要执行的操作，等待确认。
尽可能执行批准操作。 GitHub不允许批准自己的PR，因此对于自己提交的PR（Agent以你的账户创建PR的常见场景），跳过批准步骤，说明跳过的原因，直接合并。当作者是他人（或机器身份）时，先执行
```
gh pr review <n> --approve
```
。
合并，使用合并提交和固定的主题：
sh
```
gh pr merge <n> --merge --subject "chore(repo): merge pull request #<n>"
```
不要使用 squash 或 rebase-merge。如果仓库的合并提交约定不同，仅修改主题行即可。
将合并结果交接给跟踪工具，先执行
close
，再执行
sync
。合并既是git事件也是跟踪工具事件，这两部分都属于Issue生命周期skill的职责，而非mergekit。调用issuekit执行这两个操作，顺序如下，不要在此处自行处理：
- close <n>
  ，关闭PR关联的Issue。关闭Issue、勾选父任务清单、解除依赖项的阻塞、回收Issue对应的worktree是一个整体操作，
```
close
```
  会以你刚合并的PR为前提，预览所有结果，并通过gitkit删除worktree。仅当PR未关联任何Issue时才跳过此步骤。
- sync
  ，关闭Issue后立即执行，即使没有Issue需要关闭。
```
close
```
  仅处理你指定的Issue；
```
sync
```
  会扫描合并带来的所有相关变更：PR正文关闭的第二个Issue、PR未提及的链接、仍未勾选的父任务清单、因前置条件已完成而仍处于“阻塞”状态的依赖项。这些变更在此处不可见，因为mergekit仅关注单个PR，而
```
sync
```
  会读取整个跟踪工具，现在修复这些变更成本最低，因为所有人都在关注此次合并。
这两个模式都会在变更前预览并确认，因此只需一次确认，不会出现意外。如果未安装issuekit，则回退到原生的
```
gh issue close
```
/
```
gh issue edit
```
命令，像其他变更操作一样预览并确认，并告知用户未执行跟踪工具的全局扫描，不要暗示跟踪工具已清理完毕。
仅清理你创建的内容。 交接后，可能有一个Issue生命周期skill不知道的内容：分叉PR场景，即mergekit创建了
```
pr-<n>-<slug>
```
分支及其worktree。通过gitkit删除这些内容。
其他内容均保留。获取worktree可能复用了已有的worktree，而复用的worktree是他人的工作环境：实现功能的工作区，可能编辑器和开发服务器仍在运行。绝不能删除你主动复用的worktree，也不能删除你未创建的分支。 需说明你保留了哪些内容。

清理操作是幂等的：已删除的worktree会报告“已删除”而非报错。如果worktree存在未提交内容，停止清理操作，说明可能丢失的内容，而非强制删除。
交接
变更内容。 报告PR已合并（编号、标题、合并提交），是否跳过批准及原因，以及Issue生命周期交接的两部分操作结果：
```
close
```
关闭的Issue、勾选的父任务、解除阻塞的依赖项，以及
```
sync
```
处理的其他变更。如果扫描未发现任何变更，也需说明，这是跟踪工具已清理和未检查的区别。
位置信息。 说明哪些worktree已删除，哪些被保留并给出路径。被保留的复用worktree是他人的活跃工作区；告知用户才能让他们知道该worktree仍属于他们。
下一步操作。 合并释放了工作容量，因此指向需要处理的任务，仅当对应skill已安装时才提及：此次合并解除阻塞的Issue（来自
```
close
```
或
```
sync
```
步骤）是最佳选择（issuekit
start <n>
），否则是下一个等待你处理的PR（
```
list
```
），否则是statuskit重新梳理工作。如果既有解除阻塞的依赖项又有等待处理的PR，优先处理PR，因为完成任务的优先级高于开始新任务。

Fix path

修复流程

The reviewer wants changes. They already have the code checked out and running, so fix it right there, and do not hand the work back to whatever opened the PR.

Turn the reviewer's findings into a concrete spec and implement them in the live worktree, preferring an installed implementation skill.
Run the repo's test and build gate.
Commit in the repo's own style, preferring an installed commit skill.
Push. The PR updates in place; the reviewer stays in the same worktree with the app still running.
Hand off. Return to the review, re-printing only what changed (the commits you added, the gate result, the pushed branch), name the worktree still standing with the app still running, and give the next move: re-test the fixed behavior, then
```
finish <n>
```
again for the merge decision. Do not merge; that is a fresh decision, and it needs a fresh confirmation.

评审者要求修改。代码已在本地检出并运行，因此直接在当前环境中修复，无需将工作交还给创建PR的工具。

将评审者的修改意见转化为具体的规范，并在活跃的worktree中实现，优先使用已安装的实现skill。
运行仓库的测试和构建检查。
按照仓库自身的提交风格提交，优先使用已安装的提交skill。
推送。PR会实时更新；评审者仍在同一个worktree中，应用仍在运行。
交接。回到评审环节，仅打印变更内容（你添加的提交、检查结果、推送的分支），说明仍在运行的worktree路径，并给出下一步操作：重新测试修复后的功能，然后再次执行
```
finish <n>
```
进行合并决策。不要合并；这是新的决策，需要新的确认。

Mode

fix <n>

: service review feedback on your own PR

Mode

fix <n>

：处理自己PR的评审反馈

The mirror of

start

start

pulls down a PR for you to review;

fix

is for a PR you authored that has come back with review comments, a change request, or red CI, meaning the author's side of the same loop. It reads the feedback, judges which of it is worth acting on, drives those changes, pushes, and answers every thread. Like every mergekit mode, it stops short of merging.

It overlaps

finish

's Fix path in mechanics but differs at both ends: that path implements a verdict you just reached while reviewing someone else's PR, whereas

fix

starts from feedback someone else left on yours, so it opens by gathering that feedback and closes by answering it.

start

的镜像模式。

start

是拉取PR供你评审；

fix

是针对你提交的PR收到的评审意见、修改请求或CI失败进行处理，即同一循环的作者视角。它会读取反馈，判断哪些反馈值得处理，执行修改，推送，并回复所有线程。与mergekit的所有模式一样，它不会执行合并操作。

它在机制上与

finish

的修复流程重叠，但两端不同：修复流程是实现你评审他人PR时做出的决定，而

fix

是从他人对你的PR留下的反馈开始，因此它从收集反馈开始，以回复反馈结束。

1. Gather the feedback

1. 收集反馈

Assemble the punch list before touching code:

Unresolved review threads with
```
file:line
```
and comment text, bot or human, via the same GraphQL
```
reviewThreads
```
query
```
list
```
uses. These are the change requests.
Failing checks from
```
gh pr checks <n>
```
, with each failing job's name and, where reachable, its log tail. Red CI is feedback too.
The review decision from
```
gh pr view <n> --json reviewDecision
```
, so you know whether a re-request of review is warranted at the end.

If there is nothing to service, meaning no unresolved threads and green CI, say so and stop. There is nothing to fix.

在修改代码之前先整理任务清单：

未解决的评审线程，包含
```
file:line
```
和评论内容，无论是机器人还是人工评论，使用与list相同的GraphQL
```
reviewThreads
```
查询。这些是修改请求。
失败的检查，来自
```
gh pr checks <n>
```
，包含每个失败任务的名称，以及可访问的日志尾部。CI失败也是一种反馈。
评审决策，来自
```
gh pr view <n> --json reviewDecision
```
，以便你知道最后是否需要重新请求评审。

如果没有需要处理的内容（即无未解决线程且CI通过），告知用户并停止操作。无需修复。

2. Triage the punch list, and decide what is actually worth fixing

2. 分类任务清单，决定哪些内容值得修复

Feedback is a claim, not an instruction. A review comment, from a bot or a human, is someone's read of the code from outside the change, and a fair share of it is wrong for this project: a rule the repo has deliberately opted out of, a suggestion that contradicts the plan this PR implements, a real point that belongs in its own issue rather than this diff. Applying all of it because it was written down is how a PR grows a second unreviewed change and how a project's conventions get quietly overwritten by a linter's defaults. So every item gets a verdict before any code is touched.

Judge each item against what the project actually is, in this order: its documented conventions (the repo's agent-instructions file, its contributing guide, ADRs, lint and formatter config), the surrounding code, and the stated scope of this PR and the issue or plan it implements. Then assign one of three verdicts:

Fix. Correct, in scope, and consistent with the above. This is the default for anything that is plainly a bug, a real failure, or a convention the repo does hold.
Decline, with the reason named, because it goes in the reply. The recurring ones: it contradicts a documented convention or a settled decision; it is a bot false positive or a misreading of the code; it is already handled elsewhere in the diff; it is real but out of scope, meaning a separate change that deserves its own issue rather than a drive-by in a PR under review.
Ask. You cannot tell from the repo alone. Genuine trade-offs, anything that conflicts with the implementation plan or a direction the user has stated, anything that widens the change's blast radius, and anything where your confidence is simply low.

Rules that keep this honest:

Ask in one round, not one at a time. Batch every
```
ask
```
item into a single compact table (item, what it wants, your recommended verdict and why) and let the user rule on them together. Never grind through a thread-by-thread interrogation.
When in doubt, ask rather than decline. Declining silently is the failure mode that costs the most: the reviewer believes it was considered, and nobody finds out otherwise.
A declined item is still answered. It stays on the punch list through Answer the feedback, where it gets a reply stating the reason and stays unresolved. Declining is a position you state, not a thread you drop.
Red CI is not triaged away. A failing check is a fact about the branch, not an opinion about the code. If a job fails for a reason you consider illegitimate, surface it; don't file it under "declined" and push.
Print the triage before you start. One line per item with its verdict, so the user sees the whole shape and can overrule any of it. If most of the list came back declined, say so plainly, because a PR whose feedback is mostly wrong usually means the reviewer and the PR disagree about the change itself, and that is worth a conversation, not a fix round.

反馈是一种主张，而非指令。 评审意见（无论是机器人还是人工）是他人从外部对代码的解读，其中有一部分可能不适用于当前项目：仓库已明确不遵循的规则、与PR实现的计划相矛盾的建议、合理但应作为独立Issue的内容。盲目应用所有反馈会导致PR引入未评审的二次变更，以及项目约定被检查工具的默认设置悄悄覆盖。因此，在修改代码之前，每个反馈项都需要一个决策。

按照以下顺序，根据项目的实际情况判断每个项：文档化的约定（仓库的Agent指令文件、贡献指南、ADR、检查和格式化配置）、周边代码、PR及其关联Issue或计划的明确范围。然后分配以下三种决策之一：

修复。 正确、在范围内且符合上述要求。对于明显的bug、真实的失败或仓库确实遵循的约定，默认选择此决策。
拒绝，说明原因（用于回复）。常见的拒绝原因：与文档化的约定或已确定的决策相矛盾；机器人误报或对代码的误读；diff中已处理；合理但超出范围，即应作为独立变更而非当前PR中的顺带修改。
询问。 仅通过仓库无法判断。真正的权衡、与实现计划或用户明确的方向相冲突的内容、扩大变更影响范围的内容，以及你信心不足的内容。

确保决策公正的规则：

一次性询问，而非逐个询问。 将所有
```
询问
```
项整理成一个简洁的表格（项内容、要求、你的建议决策及原因），让用户一起决定。不要逐个线程询问。
不确定时，选择询问而非拒绝。 默默拒绝是代价最高的失败模式：评审者认为你已考虑过该意见，但无人发现实际情况。
拒绝的项仍需回复。 在回复反馈步骤中保留在任务清单中，回复说明原因并保持线程未解决。拒绝是一种立场，而非忽略线程。
CI失败不能被分类为拒绝。 任务失败是分支的事实，而非对代码的意见。如果你认为失败原因不合理，需告知用户；不要将其归为“拒绝”并推送。
开始前打印分类结果。 每个项一行，说明决策，让用户看到整体情况并可推翻任何决策。如果大部分反馈被拒绝，需明确说明，因为反馈大多不合理的PR通常意味着评审者和PR对变更本身存在分歧，这值得沟通而非直接修复。

3. Get the worktree and sync

3. 获取worktree并同步

Adopt the branch's existing worktree exactly as

start

does, because your own PR almost always still has the worktree it was built in, then sync exactly as

start

syncs, through gitkit. It is your branch, but it is published, so the sync previews and waits for an OK before anything is pushed. The thread count matters more here than anywhere else: you are about to answer those threads, and a rebase outdates the ones you have not replied to yet, so gather and triage the punch list first, and put the number in the preview. A PR you opened from a fork you don't control is the read-only case, where you cannot push; say so and stop.

完全按照

start

的方式复用分支已有的worktree，因为你自己的PR几乎总是保留着创建时的worktree，然后完全按照

start

的同步方式通过gitkit执行同步。虽然是你的分支，但它已发布，因此同步操作需要预览并等待确认后才能推送。线程数量在此处尤为重要：你即将回复这些线程，变基会使未回复的线程标记为过时，因此需先收集并分类任务清单，将线程数量纳入预览。如果你从无法控制的分叉创建PR，则为只读场景，无法推送；告知用户并停止操作。

4. Fix, gate, commit, push

4. 修复、检查、提交、推送

For each item you decided to fix, in the live worktree:

Implement the change, preferring an installed implementation skill.
Run the repo's test and build gate.
Commit in the repo's own style, preferring an installed commit skill.

Then push with a plain

git push

, and the PR updates in place. This is bounded, like any fix round: if an item turns out to be ambiguous once you are inside the code, or you can't get the gate green, stop and surface it rather than guessing at what the reviewer meant. An item can still flip to ask here, because triage judged it from the outside, and the code sometimes disagrees.

对于每个决定修复的项，在活跃的worktree中执行：

实现变更，优先使用已安装的实现skill。
运行仓库的测试和构建检查。
按照仓库自身的提交风格提交，优先使用已安装的提交skill。

然后执行

git push

推送，PR会实时更新。此操作是有边界的：如果在代码中发现项存在歧义，或无法通过检查，需停止操作并告知用户，而非猜测评审者的意图。项仍可在此处转为询问，因为分类是从外部判断的，而实际代码可能存在不同情况。

5. Answer the feedback

5. 回复反馈

Close the loop so the reviewer sees every item handled, fixed and declined, each mutation previewed and confirmed like any other:

Reply and resolve each thread you actually fixed, pointing at the commit that did it. Never resolve a thread you didn't fix.
Reply to each declined thread with the reason, and leave it open. A declined item is a position, not a silence: name what it conflicts with, whether the convention, the decision, or the PR's scope, and let the reviewer overrule you. Out-of-scope items are the exception worth going further on: offer to file the follow-up issue rather than leaving the point to evaporate.

Re-request review when the decision was

CHANGES_REQUESTED

(

gh pr edit <n> --add-reviewer <login>

, or the

requested_reviewers

REST endpoint).

Do not merge. Servicing feedback earns a fresh review, not a landing, because merging is
```
finish
```
's job, behind its human gate.

闭环处理，让评审者看到每个项都已处理，包括修复和拒绝的项，每个变更都像其他操作一样预览并确认：

回复并解决每个实际修复的线程，指向执行修复的提交。绝不能解决未修复的线程。
回复每个拒绝的线程并说明原因，保持线程未解决。 拒绝是一种立场，而非沉默：说明与什么相矛盾（约定、决策或PR范围），让评审者推翻你的决定。超出范围的项是例外：主动提出创建后续Issue，而非让该意见不了了之。

当评审决策为
CHANGES_REQUESTED
时，重新请求评审（

gh pr edit <n> --add-reviewer <login>

，或使用

requested_reviewers

REST端点）。

不要合并。 处理反馈仅能获得新的评审，而非合并，因为合并是
```
finish
```
的职责，需经过人工确认。

6. Hand off

6. 交接

What changed. Report the punch-list items you fixed and the commits that did it, the gate result, and which threads you replied to, resolved, or left open. Report the declines with their reasons, not just the fixes; the reviewer needs to see what you chose not to do more than what you did.

Where it landed. Give the branch pushed and the PR updated in place, plus the worktree path you worked in.

Next. The ball is back in the reviewer's court, so the move is theirs, not yours: the re-requested review, or CI re-running on the push. Name first what you couldn't service and what you declined, because a rejected comment, an ambiguous one, or a gate you couldn't get green is the thing standing between this PR and a merge, and it needs the reviewer, not another fix round. Once they approve,

finish <n>

lands it.

变更内容。 报告你修复的任务清单项及对应的提交、检查结果，以及你回复、解决或保持未解决的线程。报告拒绝的项及原因，而非仅报告修复的内容；评审者需要知道你选择不做的事情，比你做的事情更重要。

位置信息。 说明推送的分支和实时更新的PR，以及你使用的worktree路径。

下一步操作。 决定权回到评审者手中，因此操作由他们决定，而非你：重新请求的评审，或推送后重新运行的CI。首先说明你无法处理和拒绝的内容，因为被拒绝的意见、歧义的项或无法通过的检查是PR合并的障碍，需要评审者处理，而非再次修复。一旦他们批准，执行

finish <n>

即可合并。

Notes

注意事项

The merge exception is narrow. mergekit may merge because a human is sitting in front of it. It must therefore never be dispatched as a subagent inside an unattended pipeline, because the confirmation would have nobody to come from, and "the orchestrator said yes" is not a human review.
No polling, no queue, no auto-merge. mergekit runs when you invoke it. It does not watch for PRs, does not enable GitHub's auto-merge, and does not act on a schedule.
fix
is interactive too. Reading review feedback and judging whether each comment is right for this project is judgment work, so mergekit does not do it unattended, and
```
fix
```
never runs inside an automated pipeline. Its triage step exists to be overruled by a human, which needs one present. It is the author-side counterpart to
```
start
```
: it services the PR but, like every mode here, never merges it.
Force-push only with a lease, and only behind the gate. gitkit's sync rule rebases by default, so a PR branch does get rewritten, but always
```
--force-with-lease
```
, never bare
```
--force
```
, and never without the preview that names how many review threads it outdates. Never force-push to tidy history; the only force-push mergekit performs is the one the human just OK'd as part of a sync.
Read-only on fork PRs. You can review and merge them; you cannot push fixes to them. Say so at setup, not at failure.
Bot review feedback is reported, not resolved, on the reviewer's side.
```
list
```
and
```
start
```
surface unresolved threads and stop there; judging and answering them is the author's job, and
```
fix
```
is where it happens. A bot's finding carries no more authority than a human's: both are triaged against the project's own conventions before anything is changed.
No shell or
gh
available (e.g. a browser-based agent)? Then you can't create a worktree or call
```
gh
```
. Print the review pack from what the user provides, and print the setup and merge commands as codeblocks for them to run, and never claim a merge happened that you could not perform.

合并例外范围狭窄。 mergekit仅在人工在场时可执行合并。因此绝不能在无人值守的流水线中作为子Agent调度，因为无人提供确认，“编排器同意”不能替代人工评审。
无轮询、无队列、无自动合并。 mergekit仅在你调用时运行。它不会监听PR、不会启用GitHub的自动合并、也不会按计划执行操作。
fix
也是交互式的。读取评审反馈并判断每个意见是否适用于当前项目是需要判断的工作，因此mergekit不会无人值守执行，
```
fix
```
绝不能在自动化流水线中运行。其分类步骤的存在是为了让人工推翻决策，需要人工在场。它是
```
start
```
的作者视角对应项：处理PR，但与所有模式一样，绝不执行合并。
仅在持有租约且通过检查后强制推送。 gitkit的同步规则默认使用变基，因此PR分支会被重写，但始终使用
```
--force-with-lease
```
，而非裸
```
--force
```
，且必须在预览中说明会使多少评审线程过时。绝不能为了整理历史而强制推送；mergekit仅执行人工确认的同步操作中的强制推送。
分叉PR为只读。 你可以评审并合并，但无法推送修复。在设置阶段告知用户，而非在失败时才说明。
机器人评审反馈在评审者视角仅报告，不解决。
```
list
```
和
```
start
```
会显示未解决的线程并停止；判断和回复是作者的工作，在
```
fix
```
中执行。机器人的意见并不比人工更权威：两者都需根据项目自身的约定分类后再处理。
无shell或
gh
可用（如基于浏览器的Agent）？则无法创建worktree或调用
```
gh
```
。根据用户提供的信息打印评审包，并将设置和合并命令作为代码块打印供用户自行运行，绝不能声称执行了无法完成的合并操作。

mergekit

Original

Translation

mergekit

mergekit

When this fires

触发场景

Never merge automatically

禁止自动合并

Preflight

预检

What gitkit owns

gitkit的职责范围

Mode list: the morning dashboard

Mode list：晨间仪表盘

Mode start <n>: make it merge-ready

Mode start <n>：准备好合并

1. Resolve the head

1. 解析PR头部信息

2. Get a worktree, adopting first and creating only if needed

2. 获取worktree，优先复用已有worktree，仅在需要时创建

3. Sync with the base branch

3. 与基础分支同步

4. Set the project up

4. 搭建项目环境

5. Print the review pack

5. 打印评审包

6. Hand off

6. 交接

Mode finish <n>: merge or fix

Mode finish <n>：合并或修复

Merge path

合并流程

Fix path

修复流程

Mode fix <n>: service review feedback on your own PR

Mode fix <n>：处理自己PR的评审反馈

1. Gather the feedback

1. 收集反馈

2. Triage the punch list, and decide what is actually worth fixing

2. 分类任务清单，决定哪些内容值得修复

3. Get the worktree and sync

3. 获取worktree并同步

4. Fix, gate, commit, push

4. 修复、检查、提交、推送

5. Answer the feedback

5. 回复反馈

6. Hand off

6. 交接

Notes

注意事项

Mode
`list`
: the morning dashboard

Mode
`list`
：晨间仪表盘

Mode
`start <n>`
: make it merge-ready

Mode
`start <n>`
：准备好合并

Mode
`finish <n>`
: merge or fix

Mode
`finish <n>`
：合并或修复

Mode
`fix <n>`
: service review feedback on your own PR

Mode
`fix <n>`
：处理自己PR的评审反馈