merge-reconciler

合并协调器

作为公正的第三方，解决两个 Agent 分支之间的 Git 合并冲突。在处理与同伴工作冲突时，Agent 往往会覆盖同伴的修改或放弃自己的修改——它们不了解同伴的上下文，而且会偏向自己这一方。此技能旨在解决这个问题：由中立的协调器接收双方的差异和各自陈述的意图，并生成合并结果，类似合并队列仲裁者。

适用场景

• 并行协作期间，两个 Agent 分支／工作树发生冲突（看板工程流水线、并行 PR 批次、多工作树重构）。
• git merge 或 git rebase 遇到两个 Agent 的工作冲突而暂停，且不应由任一原始 Agent 自行裁决。
• 不要用于单个 Agent 自身工作中的冲突，或简单的锁文件／生成文件冲突（应重新生成这些文件）。

前提条件

• 一个包含暂停中合并的仓库检出，或者两个分支名称，以及自行执行合并的权限。
• 双方的意图来源：看板完成摘要（由 terminal 运行 hermes kanban show <task-id>）、PR 正文，或至少双方分支的提交消息。
• 项目的构建／测试命令（如有）。

运行方法

独立运行——由人工（或 Agent）在发生冲突的仓库中调用此技能：加载技能，然后从头到尾遵循操作步骤。

生成中立 Agent——在多 Agent 协作中优先采用此方式：

• delegate_task：生成一个子 Agent，其任务消息中包含仓库路径、两个分支名称，以及双方原文照录的意图摘要，并要求其遵循此技能。
• 看板原生方式：创建一张协调卡片，分配给第三个配置档案（而非任一工作者的配置档案），并将两个冲突卡片都设为父卡片——kanban_create(title="reconcile branch-a x branch-b", assignee="reconciler", parents=["t_a", "t_b"])。父卡片链接会自动将双方的完成摘要带入协调器的上下文；卡片正文应注明仓库路径和两个分支。

快速参考

冲突块类型	定义	解决方式
意图不同	两项修改服务于不同目标，可以共存	合并两者
同一问题、不同答案	双方对一个设计问题给出了不同答案	根据陈述的意图选定一个；明确说明此决定
已被取代	一方的前提在另一方修改后不再成立	保留仍然成立的一方；说明原因

公正性约定：绝不偏袒生成你的那一方；只改动冲突区域（不顺手修改其他内容）；每项设计问题的取舍都必须在交接摘要中明确列出。

操作步骤

1. 收集双方信息

• 通过 terminal 运行：git status（确认冲突状态并列出冲突文件）、git merge-base <A> <B>，然后对每一方运行 git log --oneline <base>..<side>，并对每个冲突文件运行 git diff <base>..<side> -- <file>。在暂停中的合并里，HEAD 是一方，MERGE_HEAD 是另一方。
• 收集双方的意图：使用 hermes kanban show <task-id> 获取完成摘要／元数据，或查看 PR 正文，或使用上述日志中的提交消息。修改任何文件之前，先分别用一句话记下双方的意图。
• 完成标准：你能够用自己的话说明双方的意图，并且已获取每个冲突文件双方的差异。

2. 对每个冲突代码块分类

• 使用 read_file 打开每个冲突文件，并找到每个 <<<<<<</=======/>>>>>>> 块。
• 根据已说明的意图，为每个代码块指定一个且仅一个「快速参考」表中的类别，而不是根据哪项更好看来判断。
• 如果单个代码块包含多个独立决策（例如，新增逻辑可以顺利合并，但双方对样式或舍入方式的选择不同），请将其拆分为多个子决策并分别分类。
• 单个文件通常会混合多种类别：一个代码块可能是设计冲突，相邻代码块则可能是互不冲突的改动。请按代码块分类，而不是按文件分类。
• 完成条件：每个代码块都有书面类别和一句话理由。

3. 根据公正原则解决冲突

• 使用 patch（或在重写整个文件时使用 write_file）编辑每个代码块：
  • 意图互不冲突 → 合并双方改动，使双方意图都得到充分满足。
  • 同一问题、答案不同 → 选择最能满足已说明意图的答案（例如，如果任务要求正确性，那么「严格验证」的意图优先于「快速默认值」）。不要折中拼出双方都没要求的混合方案。
  • 已被取代 → 保留仍然有效的一方；删除已失效的前提。
• 绝不偏袒让你参与处理的一方。如果双方意图确实不分高下，就升级处理（阻止看板卡片 / 汇报），不要自行猜测。
• 不要改动冲突标记之外的内容——不要调整格式、重命名或顺手修复。
• 使用 terminal 对每个已解决的文件执行 git add。
• 完成条件：search_files 在仓库中找不到 <<<<<<< 标记，且每个已解决的文件都已暂存。

4. 验证

• 使用 terminal 运行项目的构建和测试；至少导入或执行已修改的模块。合并后的行为必须能体现双方意图（例如，A 方的新语义和 B 方不冲突的新增内容都存在）。
• 完成合并：执行 git commit（可以使用默认合并消息，并在正文中列出代码块决策）。
• 完成条件：验证通过，且合并提交已存在。

5. 交接

• 提供完成摘要，列出每个代码块的决策： 文件:行号 — 类别 — 保留哪一方（或双方）— 理由。对于每个「同一问题、答案不同」的代码块，说明设计问题及所选答案，便于人工否决——不得隐去设计决策。
• 看板：kanban_complete(summary=...)。独立处理：打印摘要。
• 完成条件：已交付摘要，且列出了所有代码块。

易犯问题

• 偏袒自己一方：如果你是由冲突双方中的一方生成的，你在结构上就存在偏见——请说明这一点，并有意识地权衡另一方的意图。优先采用第三种方案的形态，以避免这种情况。
• 折中处理设计冲突会产生双方都没设计过的混合方案；应选择一个答案并明确说明。
• 按文件分类：文件通常混有多种代码块类别；把整个文件归为一类会悄然丢弃不冲突的改动。
• 顺手改动会让合并难以审查，也会剥夺原始贡献者的决策权。
• 忽略意图：提交说明可能不够详细；优先参考看板完成摘要或 PR 正文。如果两方意图都无法还原，应升级处理，而不是猜测。
• 重复冲突：同一文件在多轮中反复出现冲突，这是热点信号，而非例行协调工作——请标记该问题（例如，添加看板评论 hotspot: <path> — <reason>），提醒编排器拆解该文件，而不是逐轮协调其中每个新冲突。

验证

• git status 显示目标分支上的工作区干净，并且存在合并提交。
• 未残留冲突标记（search_files 搜索模式 <<<<<<<）。
• 构建和测试通过；双方意图均有明确体现，或在摘要中明确列出被舍弃的一方。
• 交接摘要列出每个代码块的类别和理由。