conflict-resolution

name	conflict-resolution
version	1.0.0
description	PR 前将 main 分支合并进当前特性分支，由 AI 代替开发者分级解决冲突，产出预合并报告并保证零冲突提交。触发词："合并主分支"、"预合并"、"merge main"、"/resolve"。

预合并主分支

版本：v1.0.0 | 状态：已落地 | 触发：/resolve、"合并主分支"、"预合并"、"merge main"

严格限制：此技能仅在用户明确说出触发词时才可执行。 AI 在任何情况下都禁止自动、主动、隐式调用此技能。 即使 AI 检测到分支落后于 main，也不得自行合并，只能提醒用户。

在提交 PR 之前，将 main 分支合并到当前特性分支，由 AI 代替人类完成合并工作。 目标：确保特性分支与主分支保持同步，PR 创建时零冲突。

触发规则

┌─────────────────────────────────────────────────────┐
│                   触发限制（铁律）                     │
│                                                     │
│  允许触发：用户明确说出以下触发词                      │
│     "合并主分支"、"拉主分支"、"同步主分支"              │
│     "merge main"、"预合并"、"pre-merge"               │
│     "/resolve"                                      │
│                                                     │
│  禁止触发：以下场景一律不得执行                        │
│     - AI 发现分支落后 main → 只提醒，不执行            │
│     - 用户说"提 PR"但没说合并 → 不执行                 │
│     - hook/自动化流程触发 → 不执行                     │
│     - AI 认为"应该先合并一下" → 不执行                 │
│     - 任何非用户显式指令 → 不执行                      │
│                                                     │
│  违反此规则 = 最高优先级事故                           │
└─────────────────────────────────────────────────────┘

使用场景

特性分支开发完成，准备提 PR
  │
  ├─ main 分支已有其他人的新提交
  │
  ├─ 直接提 PR → 可能有冲突 → 人类手动解决 → 浪费时间
  │
  └─ 用户说 "/resolve" → AI 预合并 main → 解决冲突 → 再提 PR → 零冲突

这不是每次提交时自动触发的检查，必须由用户手动调用。

核心安全原则

┌────────────────────────────────────────────────────┐
│              预合并三条铁律                           │
│                                                    │
│  1. 禁止静默丢弃  ── 任何一行被删除都需要有理由      │
│  2. 不确定就问人  ── 宁可打断人类，也不要猜错        │
│  3. 保留优先于删除 ── 当无法判断时，两边都保留        │
│                                                    │
│  违反任何一条 = 技能失败                              │
└────────────────────────────────────────────────────┘

---

执行流程

Phase 0: 前置检查

在执行合并前，必须先确认工作区状态安全：

# 1. 确认当前分支（不能在 main 上执行）
current_branch=$(git branch --show-current)
# 如果是 main/master → 拒绝执行，提示 "请切换到特性分支"

# 2. 确认工作区干净（无未提交的改动）
git status --porcelain
# 如果有未提交改动 → 拒绝执行，提示 "请先提交或暂存当前改动"

# 3. 确认当前分支的改动已推送到远端
git log origin/${current_branch}..HEAD --oneline
# 如果有未推送的 commit → 警告用户，建议先 push

# 4. 记录当前 HEAD，作为回滚锚点
merge_anchor=$(git rev-parse HEAD)
echo "回滚锚点: ${merge_anchor}"

Phase 1: 拉取主分支最新代码并尝试合并

# 1. 获取远端最新
git fetch origin main

# 2. 查看主分支领先多少 commit
git log HEAD..origin/main --oneline
# 如果为空 → 主分支无新提交，无需合并，直接结束

# 3. 预检：试探是否有冲突（不实际合并）
git merge-tree $(git merge-base HEAD origin/main) HEAD origin/main
# 或者直接尝试合并

# 4. 执行合并
git merge origin/main --no-edit

三种结果：

结果	处理
自动合并成功（无冲突）	→ Phase 4 验证
合并有冲突	→ Phase 2 分类 + Phase 3 解决
合并失败（无法开始）	→ 通知人类，输出错误信息

Phase 2: 冲突扫描与分类

# 获取所有冲突文件
git diff --name-only --diff-filter=U

对每个冲突文件，读取完整内容，识别所有冲突块（<<<<<<< ... ======= ... >>>>>>>），将每个冲突块分类：

Level 1: AI 可自动解决

冲突类型	合并策略
双方各自新增不同的 import	保留所有 import
双方各自新增不同的函数/方法（无交叉）	保留所有新增
配置文件新增不同的 key	合并所有新增项
仅格式化差异（空格/换行/尾逗号）	采用格式化后版本
CLAUDE.md / 文档类文件的非冲突新增	合并双方内容

Level 2: 需人类确认

冲突类型	原因
同一函数/方法体的不同修改	AI 无法判断业务优先级
同一配置项的不同值	需要人类判断用哪个值
API 签名 / DTO 字段变更	涉及上下游契约
数据模型结构冲突	可能影响数据迁移

Level 3: 禁止 AI 处理

冲突类型	原因
认证/授权/加密代码	安全风险
金额/计费/配额逻辑	资金风险
CI/CD 配置	部署风险
环境变量/密钥文件	泄露风险
一方删除 vs 另一方修改	必须人类判断意图

Phase 3: 分级解决冲突

Level 1 — 自动解决

对每个 Level 1 冲突块：
  1. 用 Edit 工具移除冲突标记，合并双方内容
  2. 记录决策到报告
  3. git add <file>

Level 2 — 暂停并询问

## 需要您确认的冲突

### 冲突 #1: [文件名]:[行号]

**特性分支的修改**（您的代码）:
> [代码片段]
> commit: [相关 commit message]

**main 分支的修改**（他人的代码）:
> [代码片段]
> commit: [相关 commit message]

**AI 分析**: [两边各自的意图、矛盾点]
**AI 建议**: [建议方案]

请选择: A=保留特性分支 / B=采用main / C=采用AI建议 / D=您手动改

收到人类回复后才继续解决，然后 git add <file>。

Level 3 — 强制交给人类

## 必须由您处理的冲突

### [文件名] — [安全/资金/部署] 相关

[完整展示冲突块内容]

**风险**: [说明为什么 AI 不能碰]

请您手动编辑此文件解决冲突后，告诉我"继续"。

等待人类完成，人类说"继续"后 git add <file> 并继续。

Phase 4: 验证

所有冲突解决后：

# 1. 确认无残留冲突标记
grep -rn "<<<<<<<\|=======\|>>>>>>>" --include="*.cs" --include="*.ts" --include="*.tsx" --include="*.json" --include="*.csproj"

# 2. 编译检查（按变更涉及的项目）
# 后端
cd prd-api && dotnet build --no-restore 2>&1 | grep -E "error CS" | head -20

# 前端
cd prd-admin && pnpm tsc --noEmit 2>&1 | head -20
cd prd-desktop && pnpm tsc --noEmit 2>&1 | head -20

# 3. 单元测试
cd prd-api && dotnet test PrdAgent.sln --filter "Category!=Integration" --no-build 2>&1 | tail -10

Phase 5: 提交合并结果

# 验证通过后，提交合并
git commit --no-edit

# 推送到远端特性分支
git push

---

输出模板

无冲突时

主分支已合并到当前分支，无冲突。
新增 commit: [N] 个（来自 main）
验证: 编译通过 测试通过
已推送到远端。可以提 PR 了。

有冲突时

# 预合并报告

> **操作**: origin/main → [当前分支名]
> **main 领先 commit 数**: [N]
> **冲突文件数**: [N]
> **回滚锚点**: [commit hash]（如需回滚: `git reset --hard [hash]`）

## 冲突统计

| 级别 | 数量 | 状态 |
|------|------|------|
| Level 1 (自动合并) | [N] | AI 已解决 |
| Level 2 (需确认) | [N] | 等待您确认 |
| Level 3 (人工处理) | [N] | 请您处理 |

## Level 1: 已自动解决

| 文件 | 冲突块 | 合并策略 | 理由 |
|------|-------|---------|------|
| src/xxx.ts | L42: import 新增 | 保留双方 | 各自引入不同依赖 |

## Level 2: 等待确认
[逐个列出]

## Level 3: 请您处理
[逐个列出]

## 验证结果

| 检查项 | 状态 |
|--------|------|
| 冲突标记残留 | 通过/未通过 |
| 后端编译 | 通过/未通过 |
| 前端类型检查 | 通过/未通过 |
| 单元测试 | 通过/未通过 |

---

禁止行为

#	禁止	原因
1	静默丢弃任何一方代码	代码是劳动成果，不能不问就扔
2	用 git checkout --ours/--theirs 批量解决	会丢弃整个文件一方的修改
3	对不理解的代码做合并	不理解就交给人类
4	跳过编译/测试验证	合并后不验证 = 定时炸弹
5	顺手修改冲突之外的代码	只动冲突块，不做额外改动
6	在合并中引入新功能/重构	合并是手术，不是装修
7	删除"看似重复"的代码	相似代码可能服务于不同场景
8	自行处理 Level 3 冲突	高风险必须人类决策
9	在工作区不干净时开始合并	可能丢失未提交的工作
10	在 main 分支上执行此技能	方向错误，应该在特性分支上操作
11	AI 自动/主动触发此技能	必须由用户明确说出触发词才可执行，AI 不得自行判断需要合并
12	在用户未说触发词时执行 git merge/fetch 主分支	即使发现分支落后 main，也只能提醒用户，不能擅自合并

---

安全防护

回滚机制

合并前记录 merge_anchor，任何阶段出问题都可回滚：

# 合并过程中取消
git merge --abort

# 合并已提交但有问题
git reset --hard ${merge_anchor}

函数完整性检查

合并完成后自动检查：

• 特性分支新增的所有函数/类 → 合并后是否都存在？
• main 分支新增的所有函数/类 → 合并后是否都存在？
• 如有消失 → 立即通知人类，不提交

行数守恒警告

合并后如果总行数明显少于预期（双方独有行之和），发出警告：

"合并后代码减少了 [N] 行，可能有代码被意外丢弃，请确认"

---

特殊文件处理

文件类型	处理方式
pnpm-lock.yaml / packages.lock.json	接受 main 版本，重新 pnpm install 生成
*.Designer.cs / *.g.cs 自动生成文件	接受 main 版本，重新生成
二进制文件（图片/字体）	必须询问人类选择哪个版本
CLAUDE.md / doc/*.md 文档	按内容合并，保留双方新增内容

---

大量冲突时的处理

超过 10 个冲突文件时：

1. 先输出冲突概览（文件列表 + 各文件冲突块数量）
2. 询问人类：逐个处理 or 按优先级分批 or 放弃合并（git merge --abort）
3. 如果冲突文件超过 20 个，建议人类考虑是否需要重新 rebase

---

与其他技能的协作

开发完成，准备提 PR
  │
  ▼
"/resolve" → 【预合并主分支】
  │
  ├─ 无冲突 → 直接提 PR
  │
  ├─ Level 1 自动解决 + Level 2/3 人类确认
  │     │
  │     ▼
  │   "/verify" → 【人工验证】(确认合并正确性)
  │
  └─ 验证通过 → 推送 → 提 PR

---

注意事项

1. 主动执行：这是一次性操作，由开发者在准备提 PR 时主动触发
2. 方向明确：永远是 main → 特性分支，不是反过来
3. 耐心分析：读完整文件上下文 + commit message，理解双方意图后再决定
4. 保守优先：不确定的冲突，宁可保留两边代码让人类裁定
5. 透明记录：每个决策都记录理由，不偷偷操作
6. 测试兜底：合并后必须编译+测试通过，否则不算完成
7. 可回滚：始终保留回滚锚点，任何时候都能撤销