GIT冲突智能合并

技能文档

---
name: git-merger
description: 智能分析和解决 Git 合并/变基冲突。先预检分支关系选择最优策略（merge一次性解决 vs rebase逐提交），逐文件审查两边内容后做出合理决策并自动循环处理直到完成。当用户遇到 git merge/rebase 冲突、要求合并代码、解决冲突、或继续 rebase 时触发。
title: GIT冲突智能合并
category: 开发工具
---

# Git 冲突智能合并

分析 Git 合并/变基中的冲突，**先预检分支关系选择最优策略**（直接 push / merge 一次性解决 / rebase 逐提交），基于内容语义和业务上下文做出合理决策（而非盲目选择某一方），自动循环处理直到完成。

## 技能工作流

调用 `todo_write` 工具创建待办任务：

**预检分支关系** → 检测状态 → 分析冲突 → 决策判断 → 执行解决 → 验证/继续 → 全局扫描

### 步骤 0：预检分支关系（最关键的一步）

**在做任何 merge/rebase 之前，必须先分析分支关系，选择最优策略。**

```bash
# 1. fetch 最新远端
git fetch origin <branch>

# 2. 检查分支关系
echo "本地领先: $(git rev-list --count origin/<branch>..HEAD)"
echo "远端领先: $(git rev-list --count HEAD..origin/<branch>)"
echo "merge-base: $(git merge-base HEAD origin/<branch>)"
echo "远端HEAD: $(git rev-parse origin/<branch>)"
```

**分支关系决策树**：

```
本地 vs 远端
  ├── 本地领先 N，远端领先 0
  │   └── ✅ 直接 git push，不需要 merge 也不需要 rebase
  │
  ├── 本地领先 0，远端领先 N
  │   └── git pull (fast-forward)，无冲突
  │
  ├── 两边都有领先（分叉了）
  │   ├── 本地领先 ≤3 个提交 → rebase 可接受（逐提交重放）
  │   └── 本地领先 >3 个提交 → 优先 merge（一次性解决冲突）
  │       └── 如果用户坚持 rebase → 建议先 squash 再 rebase
  │
  └── 已在 rebase 中且剩余提交 >10
      └── 建议 abort rebase → 改用 merge（一次性解决）
```

**核心教训**：rebase 是逐提交重放，如果本地有 40+ 个提交要 rebase，每个提交改的文件可能互相冲突，导致 N 轮冲突。而 merge 只对比两边最终状态，**只冲突一次**。

### 步骤 1：检测状态

确定当前处于 merge 还是 rebase，列出所有冲突文件：

```bash
# 检测操作类型
git status | head -5

# 列出冲突文件
git status --short | grep "^UU\|^AA\|^DD\|^U \|^ U"

# 统计冲突数量
git diff --name-only --diff-filter=U | wc -l

# 如果是 rebase，查看已完成和剩余提交数
cat .git/rebase-merge/done 2>/dev/null | wc -l
cat .git/rebase-merge/git-rebase-todo 2>/dev/null | wc -l
```

根据冲突数量和剩余提交数选择模式：
- ≤5 个文件 → 逐个审查模式
- >5 个文件且用户要求自动 → 自动循环模式
- >5 个文件但用户未明确 → 先询问用户
- **rebase 剩余 >10 个提交 → 主动建议 abort 改用 merge**

### 步骤 2：分析冲突

对每个冲突文件，提取冲突标记位置并读取两边内容：

```bash
grep -n "<<<<<<< HEAD\|=======\|>>>>>>>" <file>
```

**必须分析的内容**：
1. HEAD（ours）侧的实际内容
2. 传入（theirs）侧的实际内容
3. 传入侧的 commit message（揭示改动意图）

### 步骤 3：决策判断

**核心原则：以内容正确性为准，不盲目选择某一方。**

**决策树**：

```
冲突两边内容
  ├── 一边有内容，一边为空
  │   ├── 有内容侧是必要配置（数据库、Redis、密钥等）→ 保留有内容侧
  │   ├── 有内容侧是功能代码/测试用例 → 保留有内容侧
  │   └── 传入侧明确删除（commit message 说明要删除）→ 保留空侧
  │
  ├── 两边都有内容，内容不同
  │   ├── 架构/配置类文件
  │   │   ├── 生产配置 → 保留连接生产环境的版本
  │   │   ├── CI/CD 配置 → 保留与项目架构一致的版本
  │   │   └── 环境配置 → 保留对应环境的正确连接值
  │   ├── 代码文件
  │   │   ├── 一边是新架构重构，一边是旧代码 → 保留新架构
  │   │   ├── 一边功能更完整 → 保留更完整的版本
  │   │   └── 两边改了不同功能 → 手动合并两边
  │   └── 测试/文档资产
  │       ├── 一边覆盖更多用例 → 保留更完整的版本
  │       └── 两边有独立内容 → 手动合并两边
  │
  └── 文件路径变更（重命名/移动）
      └── 保留目标路径下的正确内容
```

**决策输出格式**：

向用户说明每个冲突的分析结果：

```
**冲突分析**：
- **HEAD**：{描述 HEAD 侧内容}
- **传入**（commit "{message}"）：{描述传入侧内容}

**判断**：{选择哪边及理由}
```

### 步骤 4：执行解决

**单文件解决**：

```bash
# 保留 ours（HEAD）
git checkout --ours <file> && git add <file>

# 保留 theirs（传入）
git checkout --theirs <file> && git add <file>

# 手动合并：用 SearchReplace 工具编辑文件移除冲突标记后 git add
```

**批量解决**（相同决策的多文件）：

```bash
git checkout --ours file1 file2 file3 && git add file1 file2 file3
git checkout --theirs file1 file2 file3 && git add file1 file2 file3
```

### 步骤 5：验证与继续

```bash
git status --short | grep "^UU\|^AA\|^DD" || echo "No remaining conflicts"
```

- **merge 操作**：无冲突后等待用户确认再 commit
- **rebase 操作**：无冲突后自动继续 `GIT_EDITOR=true git rebase --continue`
- 如果 rebase 产生新冲突，回到步骤 2 循环处理

### 步骤 6：全局扫描残留冲突标记

rebase/merge 全部完成后，必须全局扫描确认无残留冲突标记（`<<<<<<<`、`=======`、`>>>>>>>`），否则会导致编译失败：

```bash
grep -rn "<<<<<<<" --include="*.java" --include="*.yml" --include="*.yaml" \
  --include="*.ts" --include="*.tsx" --include="*.md" --include="*.feature" \
  --include="*.sh" --include="*.conf" \
  fengqun-scm-service/ fengqun-scm-api/ fengqun-scm-admin/src/ \
  fengqun-scm-tms/src/ fengqun-scm-pda/src/ test-plan-karate/ \
  .agents/ AGENTS.md 2>/dev/null \
  | grep -v node_modules | grep -v target | grep -v dist \
  || echo "✅ 全局无残留冲突标记"
```

如果发现残留，用 Python 脚本批量清理（保留 HEAD 侧内容）：

```python
import re, os
pattern = re.compile(r'<<<<<<< HEAD[^\n]*\n(.*?)=======\n.*?>>>>>>>[^\n]*\n', re.DOTALL)
for f in <file_list>:
    content = open(f).read()
    if '<<<<<<<' in content:
        open(f, 'w').write(pattern.sub(r'\1', content))
```

## 自动循环模式

当用户明确要求自动完成或冲突全是同类型时，执行循环脚本：

```bash
bash scripts/resolve_loop.sh ours
bash scripts/resolve_loop.sh theirs
```

循环脚本自动检测冲突 → 按策略解决 → continue rebase → 重复直到完成。

**限制**：混合类型冲突（同时有配置文件、代码文件、测试文件）禁止全量自动，必须逐个审查。

## 常见冲突模式速查

| 模式 | 特征 | 典型决策 |
|------|------|----------|
| 新增 vs 空 | HEAD 新增了配置/代码，传入为空 | 保留 HEAD |
| 空 vs 新增 | HEAD 为空，传入新增了功能 | 保留传入 |
| 重构 vs 旧代码 | 一边已迁移到新包/新文件，一边改旧路径 | 保留新架构 |
| 同文件不同环境 | 数据库 URL、密钥等环境相关值不同 | 保留目标环境的值 |
| CI 配置差异 | 部署方式不同（Jenkins vs kubectl） | 保留与项目架构一致的版本 |
| 测试资产覆盖 | 同一测试文件两边版本不同 | 保留覆盖更完整的版本 |

## 使用说明

### 交互式解决（推荐）

用户说「帮我合并下代码」「又有冲突了」「看下怎么合并」时，逐个审查冲突文件并按决策树解决。

### 自动循环解决

用户说「你来操作吧」「自动完成」或冲突数量 >10 且类型相同时，使用 `scripts/resolve_loop.sh` 批量处理。

### 示例

- `帮我合并下代码，采用传入的更改` → 分析后保留 theirs
- `又有冲突了，看下怎么合并` → 逐个分析每个冲突
- `你来操作吧，我不想手动继续了` → 自动循环解决

## 错误处理

| 错误场景 | 处理方案 |
|----------|----------|
| 存在未解决的合并状态（needs merge） | 先执行 `git merge --abort` 或 `git reset --hard HEAD` 清理 |
| 冲突文件包含二进制文件 | 提示用户手动处理，不自动选择 |
| rebase 超过最大轮次 | 停止循环，提示用户检查 `git status` |
| 手动合并后仍有冲突标记残留 | 用步骤 6 全局扫描并批量清理 |
| rebase 后编译失败（Unresolved compilation） | 全局扫描 `<<<<<<<` 标记，说明有文件在 rebase 中漏掉了冲突解决 |

## rebase 中途优化策略

当已在 rebase 中且发现剩余提交很多、每轮都有冲突时，应主动建议用户切换到更高效的策略：

```bash
# 1. 检查当前状态
echo "已完成: $(cat .git/rebase-merge/done | wc -l | tr -d ' ')"
echo "剩余: $(cat .git/rebase-merge/git-rebase-todo | wc -l | tr -d ' ')"

# 2. 如果剩余 >10，建议 abort + merge
git rebase --abort
git merge origin/<branch>
# 只需解决一次冲突，而非每轮都解决

# 3. 如果用户坚持 rebase，建议先 squash
git rebase --abort
git reset --soft $(git merge-base HEAD origin/<branch>)
git commit -m "squash: all local changes"
git rebase origin/<branch>
# 只重放一个提交，冲突只发生一次
```

**关键判断标准**：
- rebase 剩余提交 >10 且每轮都有冲突 → 强烈建议 abort + merge
- rebase 剩余提交 ≤10 且冲突可自动解决（全 ours 或全 theirs） → 可用脚本循环处理
- 本地已领先远端（无分叉） → 直接 push，不需要任何合并操作

## 禁止事项

- ❌ 不分析内容直接 `git checkout --ours` 或 `--theirs`
- ❌ 对生产配置（数据库、Redis、密钥）盲目选择
- ❌ 在用户未明确要求时全量自动解决混合类型冲突
- ❌ merge 操作完成后未经用户确认直接 commit
- ❌ 忽略 rebase 过程中的 dropped commit 信息

## 参考资料

- 决策树详解 → [references/decision-rules.md](references/decision-rules.md)

使用说明

# GIT 冲突智能合并

一句话解决 Git 合并/变基冲突——逐文件分析内容语义，智能决策，自动循环直到完成。

## 使用

```bash
# 遇到冲突时（推荐）
帮我合并下代码
又有冲突了，看下怎么合并

# 指定策略
帮我合并代码，采用传入的更改

# 自动循环（冲突多且类型相同时）
你来操作吧，自动完成
```

## 两种模式

**交互式（≤5 个文件）**：逐个审查冲突内容，基于语义和业务上下文做出判断，每步向你说明决策理由。

**自动循环（>5 个同类型文件）**：批量按策略解决，自动 continue rebase，循环直到完成。

## 决策逻辑

不是盲目选某一边，而是分析内容后决策：

| 冲突场景 | 决策 |
|----------|------|
| 一边有内容，一边为空 | 保留有内容侧（除非明确要删除） |
| 新架构 vs 旧代码 | 保留新架构 |
| 两边改了不同功能 | 手动合并两边 |
| 生产配置冲突 | 保留目标环境的正确值 |
| 测试覆盖差异 | 保留更完整的版本 |

## 工作流程

1. **检测** — 识别 merge/rebase 状态，列出所有冲突文件
2. **分析** — 读取两边内容 + commit message 理解改动意图
3. **决策** — 按决策树判断保留哪边或手动合并
4. **执行** — 解决冲突并 git add
5. **验证** — 确认无残留冲突，rebase 自动继续
6. **扫描** — 全局检查残留冲突标记，确保编译通过

## 安全机制

- Merge 完成后等待你确认才 commit，混合类型冲突不会全量自动处理
- 完成后全局扫描残留冲突标记，二进制文件冲突提示手动处理

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。