← 返回 Blog

Blog

Agent 把冲突标记删干净了,两条分支的意图还在打架

冲突标记删干净了,两条分支想要的东西也未必能同时成立。我写了一个分支合并 Skill,让 Agent 先说清两边各想改什么,再动手合。

让 Agent 解代码冲突,最常见的毛病是它只解决了表面上的冲突。

冲突标记删干净了,代码能编译,测试也跑过了,它就报告合并完成。可两条分支背后各自想改变什么,它没去弄清楚。还有一种情况更隐蔽:Git 自动合并成功,一个冲突都没报,两边的改动凑到一起,行为却已经不对了。

我专门写了一个 Skill 来对付这两件事,叫 semantic-branch-merge,放在我的 ww-skills 仓库里。Skill 是写给 Agent 的一份做事说明:碰到某类任务,按什么步骤做,做到什么程度才算完。这一篇讲讲它具体让 Agent 怎么做。

写它,是因为之前做的一个项目里,好几个人带着各自的 Agent 并行开发,分支合并时冲突特别多,所以专门写了这个 Skill 来解冲突。

这个 Skill 的主线就一句话:先理解两边要改变什么,再判断这些变化能不能同时成立。

一、Git 报冲突,只说明两边改到了同一个地方

Git 说的冲突,是两条分支改到了同一块文本。代码是什么意思,它管不了。所以 Git 给的两种信号,都只能当线索看。

第一种,报了冲突,未必真有矛盾。比如两条分支都改了同一个启动函数,一边装上功能甲,一边装上功能乙。文本撞在一起,Git 只好停下来。可只要查清两个功能互不影响,两边都装上就行,用不着谁让谁。

第二种,没报冲突,也可能真有矛盾。比如一条分支在一个文件里加了凭据传递,另一条分支在另一个文件里改了任务归谁所有。两边没碰同一行,Git 顺顺当当就合了。可这两处改动,最后都要经过同一个消费者。消费者指的是真正读取、调用这些数据或接口的那段代码。它拿着传过来的凭据,去操作一个换了归属的任务,授权规则还对不对,得有人去查。

研究界早就讨论过第二种情况,叫语义合并冲突:两个各自正确的改动,合到一起出了 bug。2015 年有篇论文举过一个很干净的例子。[3] 一个日志库里,log 方法记一条消息,logAll 逐条调用 log 记一批。一条分支新加了子类 FilteredLog,只重写 log,满足条件的消息才记下来;logAll 不用动,因为它本来就会调 log。同一时间,主干改了 logAll,不再逐条调 log,改成把整批消息直接塞进集合。两边改的地方不挨着,Git 不报任何冲突。合完以后,FilteredLog 调 logAll 时一条都不过滤了。

Agent 在这里特别容易出错。人给它定的目标常常就是「把冲突解掉」,冲突标记一删,测试一过,就算交差了。没冲突的文件,它更不会多看一眼。碰到拿不准的地方,它还有一招省事的办法:两个实现都留着。这些做法在 Skill 里都写明了不行:文件数、冲突标记数、两边测试各自通过,还有「两个实现都留着」,都顶替不了语义分析。

二、先把两条分支各自想干什么说清楚

第一步是找准比较的起点。合并要拿两条分支的共同祖先当参照,看两边各自从那里改了什么。Git 里查共同祖先的命令是 git merge-base,Skill 要求带上 --all。原因在 Git 官方文档里写着:两个提交之间可能有不止一个「最好的共同祖先」,比如历史里出现过交叉合并;不带 --all 时,Git 输出其中哪一个是不确定的。[1]

起点还有一层讲究。分支开发期间要是从另一边同步过代码,这次合并真正的基线就会比最初分叉的位置晚。Skill 要求把这几样分开记:最初从哪里分叉,中间同步过哪些,这次合并实际以哪里为基线。最近的共同祖先只是这次净变化的起点,整段开发历史未必从这里开始。有人改写过历史,或者有提交从一边移植到另一边,也要先说明分析范围,免得同一份贡献算两遍。两边根本没有共同祖先,就照实说,不硬做三方比较。

Skill 的参考文件里给了一组查询命令,A、B 是两边的提交,base 是基线:

git merge-base --all A B
git log --graph --oneline A B
git log --reverse --topo-order base..A
git log --reverse --topo-order base..B
git diff --find-renames base A -- relevant/paths
git diff --find-renames base B -- relevant/paths

仓库大的话,先定位到相关需求和路径,再按需展开,别一上来就输出整份大 diff。

起点定了,再按需求和行为把每条分支的改动归成几组,用不着一个提交记一条。每组要回答四个问题:

  • 原来有什么问题或限制,这条分支想达成什么,适用在什么场景、有什么前提;
  • 相对基线,哪些行为、状态、身份、权限、接口、数据或对外的副作用变了;
  • 哪些代码在产出它、哪些代码在用它,哪些旧承诺还得继续守住;
  • 后来有没有修正、撤回、替换,或者只做了一半,分支最后实际留下了什么。

最后一问很要紧。提交标题和设计稿都只能当线索,单靠它们证明不了代码真这么实现了;测试也只能证明它覆盖到的那部分行为。

Skill 还要求 Agent 把四样东西分开标:人明确提的意图,Agent 自己从代码里推断的意图,代码已经实现的行为,已经验证过的结果。这四样混在一起,Agent 很容易把自己的猜测当成需求,拿去和另一边硬比。缺证据的地方,Agent 要自己去补查,别把调查的活推给人。

三、比较两边的关系:先查交互,再说互不相干

两边的意图都还原出来以后,拿同一个基线做参照,比较「原行为变成 A」和「原行为变成 B」。重点盯两边共同的消费者和共用的约定,尤其是初始化、实际使用、错误处理、状态怎么流转、怎么清理、数据迁移和回滚这些地方。不同文件也可能通过接口、配置、数据库或状态规则互相影响。

比完以后,每组变化落进五类里的一类:

  • 正交:借来的数学说法,意思是两个改动各管各的。要有依据证明两边各自成立、凑到一起也不破坏彼此的义务。已经拿到合并授权的,直接整合,用不着人一条条批。
  • 同义重复:两边做了同一件事。先核对适用范围、外面看得到的行为和旧承诺,确实等价、又不涉及新的取舍,就收成一份实现,同时留下两边贡献的来历。
  • 有交互但相容:两边会碰上,但能同时成立。先讲清组合以后的调用顺序、约定和边界,再做工程上的整合。两边互相依赖,本身不算语义冲突。
  • 意图或语义冲突:同一个场景下,两边的要求没法同时满足,或者必须放弃一方的承诺。整理好证据,交给人裁定。
  • 关系还没查清:写明缺什么、查到什么程度算完,接着做能改变分类的核查。不能把「不知道」标成正交,也不能直接让人去猜。

Git 自动合并成功的地方,也要过这一遍。按语法树合并的工具可以帮着解掉一部分文本冲突,语法树就是编译器眼里代码的结构。可产品上该怎么做,这类工具替人拿不了主意。

四、真冲突交给人,但要把选择题出好

真碰到意图冲突,Agent 该做的是把题出清楚:共同基线是什么,两边各自要求什么、依据在哪,具体在哪个场景下撞上,哪两条义务没法同时满足,有哪几种取舍、各自什么后果。它可以给推荐,但推荐算不上裁定。

Skill 里有个短例子:A 分支要求失效的结果永远不能用,B 分支要求同一个场景下允许用。这就得明明白白摆出来交给人,Agent 不能自己挑一边,也不能把两段互相矛盾的逻辑同时留着。

有几种偷偷替人拿主意的做法,Skill 点了名:新版本优先,哪边更安全就选哪边,两边都保留。另外,ADR(架构决策记录,团队记下某个设计为什么这么定的文档)标着 accepted,或者提交时间更晚,也证明不了它已经裁定了这两条分支的冲突。

等人裁定的时候,不受影响、也已经授权的活照干。一处语义没定,不该让整个合并停工;受影响的那部分,也不能在整合结果里装作已经解决。

五、评估和动手分开,「做完」要有证据

这个 Skill 先把两种任务分开。用户只要影响分析或成本评估,Agent 就只交分析,不 merge、不 rebase、不解冲突、不提交、不推送、不部署。拿到合并授权以后,才在独立的分支和工作目录里动手,原分支和没提交的改动都要保住。合并授权只管合并,推送、合入和部署都得另外批。

评估时常想先试合一下,看看会冲突多少。新版 Git 的 git merge-tree --write-tree A B 能做这件事:它按真实 merge 的规则合并,不碰工作目录和暂存区,也不生成提交。[2] 但合并结束时,它会往 Git 的对象库里写新对象。所以 Skill 提醒,「不改工作目录」说成「完全只读」是错的;只读评估时,共享的对象库不能未经授权就拿来跑。老的三参数写法 --trivial-merge 官方已经弃用,它处理不了文件内容合并、重命名这些情况,数出来的冲突标记不能当正式的冲突数。[2]

成本也不能从冲突文件数直接推。Skill 要求按意图组、共用约定的交互、待裁定项、迁移和验证要求拆工作量;工程工时、机器跑测试和观察业务的时间、等人裁定的时间分开报。提交数、改动行数、冲突数只当辅助信息。

真动手合并时,要一处一处解冲突,不许整个文件直接选 ours 或 theirs,也就是整份照搬某一边的版本。解完以后,分别以两边合并前的父提交为基准,回查双方最后留下的成果还在不在,再验证共同消费者和组合后新出现的交互,确认以前修掉的问题没有复活。锁文件这类生成出来的东西,按合并后的源码重新生成,不拿两边的结果拼。

验证要集中在两边改动相遇的地方。约定变了,原来测试保护的意思得留住,不能靠删断言、跳过失败的测试、放宽约定来放行。也不能拿两条旧分支各自的通过结果,拼成一个「组合后也通过」。

最后是「完成」的标准。merge commit 生成了、冲突解完了、定向测试过了,在这个 Skill 里都只算阶段进度。要说合并任务完成,得同时满足:两边有效的成果都还在;合并引入的回归和交互问题修好了;受影响的业务流程有组合以后能用的证据;稳定下来的候选版本做完了该做的最终检查;也没有还悬着、会改变结论的事。交付报告还要把「源码已整合」「合并任务完成」「已部署」分开写,各给证据。

拿去用

Skill 在这里:wangwu-30/ww-skills/skills/semantic-branch-merge,MIT 协议。一共三份文件:SKILL.md 是主流程;references/methodology-and-tools.md 放查询命令、工具的边界和几个用来自查的短案例;agents/openai.yaml 写了它在界面上的名字、简介和默认提示词,还允许 Agent 自己判断该用时就调用,用不着你点名。

它适合合并前的评估、长期分叉的分支合并和复杂的解冲突;普通的单分支代码审阅用不着它。

参考文件里还提到两项研究,我借的是思路:SafeMerge 验证合并后的程序有没有多出不想要的新行为[4];DeltaImpactFinder 比较同一个改动放在原分支和目标分支上,影响有什么不同[3]。Skill 里也写明了,这些只是工程判断上的借鉴,没有做到形式化的无冲突证明。

实话实说,这个 Skill 还没解决全部问题。我实测过一次分叉了 500 多个提交的合并,它还是会漏掉一些细节。这种极端场景还得接着优化,比如让 Agent 一边分析一边定合并计划,把计划落到文件里,别全靠上下文记着。

Git 能告诉你两边有没有改到同一行。两边想要的东西能不能一起成立,得有人把意图读出来;真成立不了,该放下哪一边,还是人来定。


参考资料

网页引用核对于 2026 年 10 月 18 日。

  1. Git. git-merge-base Documentation.
  2. Git. git-merge-tree Documentation.
  3. Martín Dias, Guillermo Polito, Damien Cassou, Stéphane Ducasse. DeltaImpactFinder: Assessing Semantic Merge Conflicts with Dependency Analysis. IWST’15. arXiv:1509.04207.
  4. Marcelo Sousa, Isil Dillig, Shuvendu Lahiri. Verified Three-Way Program Merge. OOPSLA 2018.
  5. wangwu-30/ww-skills:semantic-branch-merge.

讨论

评论

直接在本站留言交流。

评论正在加载…