企业官网建设流程全解析

Roo Code 冲突解决技能实战指南：基于 Git 历史智能化解 PR 合并冲突

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

Roo Code 的项目级 Skills 目录中内置了roo-conflict-resolution技能，它围绕「Git 历史 + 提交上下文」设计了一套从 PR 解析、冲突暴露、意图分析到智能裁决的完整工作流。本文以 SKILL.md 为骨架，结合仓库内的 SkillsManager、SkillTool 与 merge-resolver 规则集 源码，完整讲解技能结构、初始化流程、四大工作阶段、启发式裁决规则与可复制的命令组合，让你既能读懂技能如何被 Roo Code 加载执行，也能直接复用它完成 PR 冲突的自动化化解。

技能是什么：Roo Code 如何加载与触发它

在 Roo Code 中，技能（Skill）以目录形式存在，每个技能目录内必须包含一个带 YAML frontmatter 的SKILL.md文件。SkillsManager 负责发现并解析技能元数据：它遍历全局与项目下的skills/与skills-{mode}/目录，用gray-matter解析 frontmatter，并校验name、description等必填字段。

以本技能为例，其 frontmatter 定义了三个关键字段：

name: roo-conflict-resolution description: Provides comprehensive guidelines for resolving merge conflicts intelligently using git history and commit context. Use when tasks involve merge conflicts, rebasing, PR conflicts, or git conflict resolution. This skill analyzes commit messages, git blame, and code intent to make intelligent resolution decisions.

• name必须与技能目录名一致（目录为roo-conflict-resolution），否则会被 SkillsManager 拒载；
• description是模型判断「何时启用该技能」的依据，明确声明了适用场景：合并冲突、rebase、PR 冲突、git 冲突解决；
• 未声明modeSlugs或mode，意味着该技能在所有模式下可用。

当模型决定调用技能时，会走 SkillTool 的执行链路：校验技能名 → 通过resolveSkillContentForMode从 SkillsManager 读取技能内容 → 生成审批消息 → 审批通过后把技能指令注入上下文。技能正文（即SKILL.md中 frontmatter 之后的部分）会作为 Instructions 整体提供给模型，指导其后续每一步操作。此外，仓库还提供了更轻量的 Slash 命令入口 roo-resolve-conflicts.md，支持/roo-resolve-conflicts #123或/roo-resolve-conflicts 456直接发起冲突解决任务，其 frontmatter 中mode: merge-resolver指定了配套的自定义模式。

何时使用、何时禁用

description与正文中的 "When to Use / When NOT to Use" 共同界定了技能的触发边界。应当使用的场景包括：

• 为某个具体的 PR 解决合并冲突；
• rebase 分支时与目标分支产生冲突；
• 需要理解并分析相互冲突的代码改动；
• 需要在「保留、合并、丢弃」之间做智能决策；
• 需要借助 git 历史辅助冲突裁决。

不应使用的场景同样明确：

• 当前没有需要解决的合并冲突；
• 任务只是不带冲突的常规代码评审；
• 工作在没有任何合并场景的全新代码上。

这条边界很重要：技能的整个流程都以「先通过 rebase 主动暴露冲突」为前提，没有冲突时不应空跑流程。

初始化四步：从 PR 号到冲突清单

技能接收一个 PR 号（如#123或PR #123），随后按 初始化步骤 依次执行四个步骤。

Step 1：解析 PR 号

从输入中提取数字部分，校验必须提供有效的 PR 号，否则直接终止。

Step 2：拉取 PR 信息

gh pr view [PR_NUMBER] --json title,body,headRefName,baseRefName

用 GitHub CLI 获取 PR 的标题、描述、源分支（headRefName）与目标分支（baseRefName）。这一步的价值在于拿到「为什么改」的上下文——后续所有裁决都建立在对 PR 意图的理解之上。

Step 3：检出 PR 分支并准备 rebase

gh pr checkout [PR_NUMBER] --force git fetch origin main GIT_EDITOR=true git rebase origin/main

• --force强制检出 PR 分支，确保工作区处于干净状态；
• git fetch origin main拉取最新的目标分支；
• GIT_EDITOR=true git rebase origin/main尝试把 PR 分支变基到 main 之上，以暴露冲突；环境变量GIT_EDITOR=true是关键，它把编辑器替换为 no-op 命令，确保 rebase 全程非交互，不会因等待输入而卡死自动化流程。

Step 4：检查冲突文件

git status --porcelain git diff --name-only --diff-filter=U

--porcelain输出机器可读状态，冲突文件以UU标记；--diff-filter=U精确列出所有 unmerged 文件，形成待解决清单。若此步为空，说明 rebase 干净通过，按错误处理约定直接告知用户「该 PR 无需解决冲突即可合并」。

四大工作阶段：从分析到验证

初始化之后，技能进入 主工作流 的四个阶段。

Phase 1：冲突分析

对每个冲突文件依次执行：

1. 读取冲突文件，定位<<<<<<<、=======、>>>>>>>冲突标记；
2. 提取标记之间的冲突区块；
3. 对冲突两侧分别运行git blame，定位产生改动的提交；
4. 获取相关提交的 commit message 与 diff；
5. 分析每个改动背后的意图。

Phase 2：解析策略

在理解意图后为每个冲突制定策略：

1. 按意图对改动分类（bugfix、feature、refactor 等）；
2. 评估改动的新旧程度与相关性；
3. 判断是结构性重叠还是纯格式差异；
4. 判断改动能否合并，还是必须有一方覆盖另一方；
5. 把测试更新与相关改动纳入考量。

Phase 3：冲突解决

按策略落地修改：

1. 对每个冲突应用选定的解决方案；
2. 在 diff 中对冲突标记做正确转义（详见下文「apply_diff 实战」）；
3. 校验解决后的代码语法正确；
4. 用git add暂存已解决文件。

Phase 4：验证

提交前最终确认：

1. git status确认所有冲突已解决；
2. 检查编译/语法错误；
3. 复查最终 diff，确保解决方案合理；
4. 汇总每个冲突的裁决理由。

Git 命令参考：可复制的最小命令集

技能内置了完整的命令速查表，覆盖从拉取信息到收尾 rebase 的每一步：

工具使用规则（见 3_tool_usage.xml）还补充了几条实操经验：所有 git/gh 操作统一走execute_command而非 MCP 工具；命令用&&链式组合提高效率；--format输出结构化结果便于解析。对于非交互场景，还有三个通用技巧：GIT_SEQUENCE_EDITOR=true跳过交互式 rebase 的 todo 编辑、git commit --no-edit/git merge --no-edit/git cherry-pick --no-edit跳过提交信息编辑。

意图优先：三条最高优先级最佳实践

最佳实践规则集 为冲突裁决定义了四档原则，其中三条为 High 优先级。

意图驱动裁决（High）

永远优先理解改动背后的意图，而非只看代码差异。commit message、PR 描述、issue 引用提供了关键上下文。规则集给出了典型示例：当冲突发生在bugfix 与 refactor之间时，正确做法是把 bugfix 的逻辑移植进 refactor 后的结构里，而不是简单二选一——因为 bugfix 修复的是现有问题，refactor 改变的是代码结构，二者本应共存。

保留所有有价值的改动（High）

只要可能，就把两侧非冲突的部分合并进来，而不是整侧丢弃。冲突双方往往都包含能共存的有价值改动，粗暴舍弃一侧极易引入回归。

转义冲突标记（High）

使用apply_diff时，必须用反斜杠转义冲突标记，否则工具会把它们误判为 diff 语法导致解析失败：

• 正确：\<<<<<<< HEAD
• 错误：<<<<<<< HEAD

考虑相关改动（Medium）

跳出冲突本身，考察测试、文档、依赖代码中的关联改动。一个看似孤立的改动可能是跨多文件的大功能或大修复的一部分，忽略它会破坏整体一致性。

启发式裁决规则表

当两侧意图都清晰时，技能给出四条可套用的裁决启发式：

这些规则服务于同一个目标：在意图无法同时满足时，优先保住功能正确性与安全性，再考虑代码风格。

常见陷阱与规避方法

技能明确列出四个高频错误及对策：

1. 盲目二选一：可能丢失重要改动或引入回归。对策——总是用git blame与 commit 历史分析两侧。
2. 忽略 PR 上下文：PR 描述往往解释了改动的「为什么」。对策——解决前必须拉取并阅读 PR 信息。
3. 不验证解决结果：合并后的代码可能语法错误或引入逻辑 bug。对策——总是检查语法错误并复查最终 diff。
4. diff 中未转义冲突标记：<<<<<<、=======、>>>>>>会被当作 diff 语法。对策——出现在 SEARCH/REPLACE 内容中时一律用反斜杠转义，例如\<<<<<<< HEAD。

此外，3_tool_usage.xml 的错误处理还覆盖了几种边界情况：rebase 已在进行中时，先git status确认，再决定--continue或--abort；遇到畸形/嵌套的冲突标记时改用精确搜索块的多次定点编辑；二进制文件无法自动合并时，依据 PR 意图用git checkout --theirs或--ours选择保留版本；代码本身含字面量冲突标记字符串时更要加倍小心转义。

apply_diff 实战：冲突区块的标准替换写法

技能给出了用apply_diff解决冲突的标准模板：SEARCH 块内先声明:start_line:锚定起始行，再以转义后的冲突标记包围两侧代码；REPLACE 块内直接写入合并后的实现。

<apply_diff> <path>src/feature.ts</path> <diff> <<<<<<< SEARCH :start_line:45 ------- \<<<<<<< HEAD function oldImplementation() { return "old"; } \======= function newImplementation() { return "new"; } \>>>>>>> feature-branch ======= function mergedImplementation() { // Combining both approaches return "merged"; } >>>>>>> REPLACE </diff> </apply_diff>

要点有三：一是冲突标记前必须加\（\<<<<<<<、\=======、\>>>>>>>）；二是:start_line:45让工具精确定位到冲突起始行，减少误匹配；三是 REPLACE 区写入的既不是旧实现也不是新实现，而是融合两者思路的合并版本——这正是「保留两侧价值改动」原则在 diff 层的落地。工具规则还建议：SEARCH 块带足上下文确保唯一匹配、多个相邻冲突尽量合并进同一个 diff。

收尾：质量检查清单与沟通规范

解决前后的检查清单

解决前：拉取 PR 标题与描述；识别所有冲突文件；理解整体改动意图。

解决中：对冲突区段执行git blame；阅读 commit message 推断意图；判断两侧改动能否合并；转义 diff 中的冲突标记。

解决后：确认无残留冲突标记；检查语法/编译错误；复查完整 diff；记录每个冲突的裁决理由。

完成标准

• 所有合并冲突均已解决；
• 已解决的文件已完成git add暂存；
• 解决后的代码无语法错误；
• 每个裁决决定都有文档记录。

沟通格式

向用户汇报进度时使用结构化格式，逐文件说明 HEAD、Incoming 与 Resolution：

Conflict in [file]: - HEAD: [brief description of changes] - Incoming: [brief description of changes] - Resolution: [what was decided and why]

完成时使用标准完成消息模板：

Successfully resolved merge conflicts for PR #[number] "[title]". Resolution Summary: - [file1]: [brief description of resolution] - [file2]: [brief description of resolution] [Key decision explanation if applicable] All conflicts have been resolved and files have been staged for commit.

深入阅读

想进一步研究技能机制与本主题，可从以下仓库文件入手：

• 技能本体：.roo/skills/roo-conflict-resolution/SKILL.md
• Slash 命令入口：.roo/commands/roo-resolve-conflicts.md
• 工作流定义：.roo/rules-merge-resolver/1_workflow.xml、2_best_practices.xml、3_tool_usage.xml
• 技能加载与解析：src/services/skills/SkillsManager.ts
• 技能内容解析与结果构建：src/services/skills/skillInvocation.ts
• 技能工具执行链路：src/core/tools/SkillTool.ts

掌握了本技能后，你可以直接向 Roo Code 输入/roo-resolve-conflicts #123，让它自动完成「拉取 PR 信息 → 检出并 rebase → 逐冲突分析 → 意图裁决 → 暂存并汇报」的完整闭环；也可以参照SKILL.md的结构与本文的启发式规则，为团队定制自己的冲突解决规范。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code