resolve-conflicts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Resolve Conflicts

解决冲突

Semi-automatic merge and rebase conflict resolution.

半自动合并与变基冲突解决方案。

Compatibility

兼容性

This skill mutates git state and may rewrite branch history. Expose it to Codex only as an explicitly invoked skill.

该技能会修改Git状态，可能重写分支历史。仅当显式调用时，才将其暴露给Codex。

Asking the User

询问用户

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

本技能中的所有问题均以

AskUserQuestion

选项形式编写。如果宿主提供该工具，则使用它；若没有，则使用宿主最接近的结构化选择等效工具。如果两者都没有，则以普通聊天形式提出相同问题，列出2–5个带编号的选项——推荐选项放在首位，每个选项配一行简短描述——等待用户回复编号。

Entry Point Detection

入口检测

Determine mode from arguments:

Input	Mode
PR number, PR URL, issue number, issue URL	PR mode
No arguments + active conflicts in working tree	Local mode
Invoked by another skill during rebase/merge	Conditional mode
No arguments + no active conflicts	Error: nothing to resolve

根据参数确定模式：

输入内容	模式
PR编号、PR链接、Issue编号、Issue链接	PR模式
无参数 + 工作区存在活跃冲突	本地模式
在变基/合并过程中被其他技能调用	条件模式
无参数 + 无活跃冲突	错误：无冲突可解决

PR Mode

PR模式

Step 1: Fetch PR Info

步骤1：获取PR信息

Run

scripts/fetch-pr-info.sh $ARGUMENTS

from the skill directory.

Parse the key=value output. Handle exit codes:

Exit	Meaning	Action
0	PR found with conflicts	Continue to Step 2
1	Input parsing failed	Show error, stop
2	gh not authenticated	Show error, stop
3	PR/issue not found	Show error, stop
4	Issue has no linked PR	Show context, stop
5	PR has no conflicts	Show context, stop

Always display context header (even when stopping):

PR: <title>
Branches: <base> ← <head>
Link: <url>

从技能目录运行

scripts/fetch-pr-info.sh $ARGUMENTS

。

解析key=value格式的输出，处理退出码：

退出码	含义	操作
0	找到存在冲突的PR	继续步骤2
1	输入解析失败	显示错误，停止操作
2	gh未认证	显示错误，停止操作
3	未找到PR/Issue	显示错误，停止操作
4	Issue未关联PR	显示上下文，停止操作
5	PR无冲突	显示上下文，停止操作

始终显示上下文头部（即使停止操作时）：

PR: <标题>
Branches: <base> ← <head>
Link: <链接>

Step 2: Prepare Working Directory

步骤2：准备工作目录

Check if working tree is dirty (
```
git status --porcelain
```
)
If dirty OR user included "worktree" in the invocation → create an isolated worktree for
```
<head-branch>
```
using whatever mechanism the host provides (a built-in worktree tool, or
```
git worktree add
```
). If the host cannot continue in the new worktree automatically, show the resulting
```
cd <path>
```
command and stop so the user can resume there.
If clean → work in current repo

检查工作区是否有未提交修改（
```
git status --porcelain
```
）
如果工作区有未提交修改，或用户在调用时包含"worktree" → 使用宿主提供的机制（内置工作区工具或
```
git worktree add
```
）为
```
<head-branch>
```
创建独立工作区。如果宿主无法自动在新工作区继续操作，显示生成的
```
cd <路径>
```
命令并停止，以便用户在该路径恢复操作。
如果工作区干净 → 在当前仓库操作

Step 3: Fetch and Rebase

步骤3：拉取与变基

bash

git fetch origin <base>
git fetch origin <head>
before=$(git rev-parse "origin/<head>")
git checkout <head>
git reset --hard origin/<head>
git rebase origin/<base>

Keep

$before

for Step 5. It is the remote tip this rebase started from, and the only value a force-push may safely lease against.

If rebase produces conflicts → proceed to Resolution Pipeline. If rebase completes cleanly → show "No conflicts after rebase" and stop.

bash

git fetch origin <base>
git fetch origin <head>
before=$(git rev-parse "origin/<head>")
git checkout <head>
git reset --hard origin/<head>
git rebase origin/<base>

保留

$before

用于步骤5。它是变基开始时的远程分支尖端，也是强制推送时唯一安全的租赁基准值。

如果变基产生冲突 → 进入冲突解决流程。如果变基无冲突完成 → 显示"变基后无冲突"并停止操作。

Step 4: Resolution Pipeline

步骤4：冲突解决流程

Run the Resolution Pipeline (see below). This may loop multiple times during rebase — each

git rebase --continue

can produce new conflicts.

运行冲突解决流程（见下文）。变基过程中可能多次循环此步骤——每次

git rebase --continue

都可能产生新冲突。

Step 5: Completion

步骤5：完成操作

After all conflicts resolved and rebase complete:

Run verification (see Verification section)
Show final report
Ask whether to force-push
```
<head>
```
to remote, per Asking the User:
1. ```
Force push
```
  (Recommended) — update the PR branch after the resolved rebase
2. ```
Skip push
```
  — keep the rebased branch local only
- Yes →
```
git push --force-with-lease="<head>:$before" origin <head>
```
- No → skip

A bare

git push --force-with-lease

leases against the remote-tracking ref, which any

git fetch

refreshes. Resolution loops for as long as the conflicts take, so anything fetching in between would turn the lease into a no-op and let the push discard a commit someone else added to the PR branch.

$before

, captured in Step 3, is the value the rebase was actually built on. If the push is rejected, the remote moved: re-run from Step 3 rather than escalating to

--force

If unresolved conflicts remain:

Show final report with remaining files
Stop and wait for user input

所有冲突解决且变基完成后：

运行验证（见验证章节）
显示最终报告
根据询问用户规则，询问是否将
```
<head>
```
分支强制推送到远程：
1. ```
强制推送
```
  （推荐）——变基完成后更新PR分支
2. ```
跳过推送
```
  ——仅保留本地变基后的分支
- 是 →
```
git push --force-with-lease="<head>:$before" origin <head>
```
- 否 → 跳过

直接使用

git push --force-with-lease

会基于远程跟踪引用进行租赁，而任何

git fetch

操作都会刷新该引用。冲突解决可能需要多次循环，期间任何拉取操作都会使租赁失效，导致推送丢弃他人添加到PR分支的提交。步骤3中捕获的

$before

是变基实际基于的基准值。如果推送被拒绝，说明远程分支已更新：从步骤3重新运行，而非升级为

--force

。

如果仍有未解决的冲突：

显示包含剩余文件的最终报告
停止操作并等待用户输入

Local Mode

本地模式

Detect active merge/rebase state:
- ```
.git/rebase-merge/
```
  or
```
.git/rebase-apply/
```
  → rebase in progress
- ```
.git/MERGE_HEAD
```
  → merge in progress
- Neither → error "No active merge or rebase"
Run Resolution Pipeline

After resolution:

git rebase --continue

git merge --continue

Loop if new conflicts appear
Show final report when done

检测活跃的合并/变基状态：
- 存在
```
.git/rebase-merge/
```
  或
```
.git/rebase-apply/
```
  → 变基进行中
- 存在
```
.git/MERGE_HEAD
```
  → 合并进行中
- 两者都不存在 → 错误"无活跃的合并或变基操作"
运行冲突解决流程

解决完成后：执行

git rebase --continue

或

git merge --continue

如果出现新冲突则循环操作
完成后显示最终报告

Conditional Mode

条件模式

Same as Local Mode but:

No AskUserQuestion prompts
No push questions
Return control to calling skill silently after resolution

与本地模式相同，但：

不使用AskUserQuestion提示
不询问推送相关问题
解决完成后静默将控制权返回给调用技能

Resolution Pipeline

冲突解决流程

Phase 1: Classify

阶段1：分类

```
cd "$(git rev-parse --show-toplevel)"
```
, then run
```
scripts/classify-conflicts.sh
```
. Its paths are relative to the repository root, so every resolution command below has to run from there too. Exit 3 means a conflicted path contains a newline, which a line-oriented report cannot represent — surface the message and stop; do not resolve a partial list.
Parse the output — extract counts and file lists per status code
If there are UU files, classify them by difficulty:
- Read
```
references/conflict-analyzer-prompt.md
```
  and dispatch a read-only subagent with it as the prompt body plus the UU file list. It classifies each file trivial / simple / complex and resolves nothing.
- If the host has no subagent facility, classify inline using the same prompt.
- Parse the classifier output to get the UU trivial/simple/complex subgroups
Combine bash output (DU/UD/DD/AA/AU/UA) with classifier output
Print the initial report (see
```
references/report-format.md
```
)

执行
```
cd "$(git rev-parse --show-toplevel)"
```
，然后运行
```
scripts/classify-conflicts.sh
```
。该脚本的路径相对于仓库根目录，因此以下所有解决命令也必须从仓库根目录运行。退出码3表示冲突路径包含换行符，行导向的报告无法展示——显示提示信息并停止操作；不要仅解决部分冲突文件。
解析输出——提取各状态码对应的文件数量和文件列表
如果存在UU文件，按难度分类：
- 读取
```
references/conflict-analyzer-prompt.md
```
  ，并将该文件作为提示内容加上UU文件列表，派发给只读子代理。子代理会将每个文件分类为简单/普通/复杂，不进行任何解决操作。
- 如果宿主无子代理功能，使用相同提示内容进行内部分类。
- 解析分类器输出，得到UU文件的简单/普通/复杂子分组
将bash输出（DU/UD/DD/AA/AU/UA）与分类器输出合并
打印初始报告（见
```
references/report-format.md
```
）

Phase 2: Auto-Resolve

阶段2：自动解决

Resolve groups that need no LLM analysis:

Group	Command
DU	`git rm "<file>"` for each file
UD	`git rm "<file>"` for each file
DD	`git rm "<file>"` for each file
AA	`git checkout --theirs "<file>" && git add "<file>"` — but if the classifier treated it as UU (both have meaningful content), treat as UU
AU	`git checkout --theirs "<file>" && git add "<file>"`
UA	`git checkout --theirs "<file>" && git add "<file>"`
UU trivial	`git checkout --theirs "<file>" && git add "<file>"`

classify-conflicts.sh

prints each path verbatim — unquoted and unescaped, so a name with a space or a non-ASCII character arrives intact. Two consequences: always quote it when passing it back to git, because the report does not escape it for you; and run from the repository root, because the paths are relative to it.

Batch all trivial UU files into one resolver subagent for parallel execution.

无需LLM分析的分组直接解决：

分组	命令
DU	对每个文件执行 `git rm "<file>"`
UD	对每个文件执行 `git rm "<file>"`
DD	对每个文件执行 `git rm "<file>"`
AA	`git checkout --theirs "<file>" && git add "<file>"` — 但如果分类器将其视为UU（双方都有有意义的内容），则按UU处理
AU	`git checkout --theirs "<file>" && git add "<file>"`
UA	`git checkout --theirs "<file>" && git add "<file>"`
UU trivial	`git checkout --theirs "<file>" && git add "<file>"`

classify-conflicts.sh

会原样输出每个路径——未加引号和转义，因此包含空格或非ASCII字符的名称会完整保留。由此产生两个注意事项：将路径传递给Git时必须加引号，因为报告未对其进行转义；必须从仓库根目录运行命令，因为路径是相对根目录的。

将所有简单UU文件批量交给一个解决子代理，并行执行。

Phase 3: Context-Aware Resolve

阶段3：上下文感知解决

Attempt to resolve all remaining UU files (simple and complex).

Effort thresholds:

≤3 complex files → spend significant effort on each, read surrounding code for context
4–10 complex files → attempt each, move on if stuck after reasonable effort
10+ complex files → attempt but don't over-invest; resolve what's feasible

Parallelization:

Dispatch one resolver subagent per file for parallel resolution
Cap at ~5 concurrent resolver subagents
Resolver subagents: read the conflicted file → understand both sides → write the resolved version →
```
git add
```
Resolver subagents must NOT run lint, build, typecheck, or any verification commands

For each resolver subagent, do this:

Read the file to find all conflict markers
For each conflict block, understand what "ours" changed and what "theirs" changed
Decide how to combine both changes (or pick one side if they're truly incompatible)
Write the resolved file (no conflict markers remaining)
```
git add "<file>"
```

If a resolver subagent cannot resolve a file: Leave the conflict markers in place. Do not

git add

it. The file will appear in the final report as unresolved.

尝试解决所有剩余的UU文件（普通和复杂）。

投入阈值：

≤3个复杂文件 → 对每个文件投入较多精力，读取周边代码获取上下文
4–10个复杂文件 → 尝试解决每个文件，若合理尝试后仍卡住则跳过
10+个复杂文件 → 尝试解决但不过度投入；解决可行的部分

并行处理：

为每个文件分派一个解决子代理，并行解决
并发解决子代理上限约为5个
解决子代理流程：读取冲突文件 → 理解双方修改内容 → 编写解决后的版本 →
```
git add
```
解决子代理禁止运行lint、构建、类型检查或任何验证命令

每个解决子代理执行以下操作：

读取文件，找出所有冲突标记
对每个冲突块，理解"我方"和"对方"的修改内容
决定如何合并双方修改（如果确实不兼容，则选择其中一方）
编写解决后的文件（移除所有冲突标记）
```
git add "<file>"
```

如果解决子代理无法解决文件： 保留冲突标记，不执行

git add

。该文件会在最终报告中显示为未解决。

Phase 4: Continue Loop

阶段4：继续循环

After all resolvable conflicts are handled:

Check for remaining conflict markers:

git status --short | grep -E '^(UU|DU|UD|AU|UA|AA|DD) '

If none remain:
- For rebase:
```
git rebase --continue
```
- For merge:
```
git merge --continue
```
- If the continue produces new conflicts → go back to Phase 1
- If the continue succeeds → proceed to Verification
If conflicts remain:
- Show final report with unresolved files
- In PR/Local mode: stop and wait for user
- In Conditional mode: return with status indicating unresolved conflicts

处理完所有可解决的冲突后：

检查是否有剩余冲突标记：

git status --short | grep -E '^(UU|DU|UD|AU|UA|AA|DD) '

如果无剩余冲突标记：
- 变基场景：
```
git rebase --continue
```
- 合并场景：
```
git merge --continue
```
- 如果继续操作产生新冲突 → 返回阶段1
- 如果继续操作成功 → 进入验证环节
如果仍有冲突：
- 显示包含未解决文件的最终报告
- PR/本地模式：停止操作并等待用户输入
- 条件模式：返回包含未解决冲突状态的结果

Verification

验证

Run after all conflicts are resolved and rebase/merge is complete.

```
git status
```
— confirm clean working tree
Check for project-specific lint/typecheck commands:
- Read
```
CLAUDE.md
```
  or
```
package.json
```
  scripts for available commands
- Run fast checks only:
```
tsc --noEmit
```
  ,
```
eslint
```
  ,
```
biome check
```
  , etc.
- Do NOT run slow builds or integration tests at this stage
If issues found (broken imports, type errors from deleted files):
- Attempt to fix them
- Re-run the check to confirm
Run build only at the very end if the project has a fast build (typical for JS projects)
If issues cannot be fixed → report them alongside any unresolved conflicts

所有冲突解决且变基/合并完成后执行。

```
git status
```
— 确认工作区干净
检查项目特定的lint/类型检查命令：
- 读取
```
CLAUDE.md
```
  或
```
package.json
```
  中的脚本，获取可用命令
- 仅运行快速检查：
```
tsc --noEmit
```
  、
```
eslint
```
  、
```
biome check
```
  等
- 此阶段禁止运行缓慢的构建或集成测试
如果发现问题（导入错误、文件删除导致的类型错误）：
- 尝试修复问题
- 重新运行检查以确认修复
仅当项目有快速构建流程时（典型如JS项目），才在最后运行构建
如果问题无法修复 → 与未解决冲突一起报告