dx-devops-conflict-resolve

DevOps Center 冲突与部署失败处理

诊断并解决阻碍 DevOps Center 晋级工作项功能分支的问题。DevOps Center 由 Git 提供支持：每个工作项对应一个功能分支，每个流水线阶段都有一个目标分支。晋级可能因两种原因失败——Git 合并冲突（两个工作项修改了相同的元数据）或部署失败（部署本身报错，通常是因为缺少依赖项）。不存在 sf devops conflict CLI 命令；这两种情况都通过对已连接的代码仓库使用标准 git 进行诊断和解决。此技能在该仓库的本地克隆中运行。

范围

• 范围内：(a) 以非破坏性方式检测工作项的功能分支与目标阶段分支之间的合并冲突；解决冲突文件（选择一方或手动合并冲突标记）；提交更改，并推送 DevOps Center 跟踪的功能分支；(b) 诊断晋级部署失败——判断是合并冲突还是部署错误，解析缺少的依赖项，并确定能否通过完整晋级修复（组件存在于功能分支上），还是必须先添加该组件
• 范围外：运行晋级、完整晋级或组合（使用 dx-devops-promote）；创建/更新工作项或其状态（使用 dx-devops-work-item-manage）；直接向组织部署元数据；流水线或项目设置（使用单独的技能）

---

必需输入

继续之前，请收集或推断以下信息：

• 本地克隆：DevOps Center 已连接的 Git 仓库的本地克隆（Agent 在此处运行 git 命令）。开始前确认工作区干净。
• 功能分支名称——工作项对应的分支。如果用户提供的是工作项 ID/主题而不是分支，请将其解析为对应分支（查阅 Reference File Index，了解 sf devops work-item 查询方法）。
• 目标阶段分支名称——工作项将晋级到的流水线阶段的分支（例如集成/UAT 分支）。
• 远程名称——默认为 origin。
• 部署错误文本（仅用于部署失败处理流程）——晋级的错误输出/摘要。需要此文本来判断失败原因并解析缺少的依赖项。将其保存到文件，或通过管道传入诊断脚本。

除非另有说明，否则默认值如下：

• 远程：origin
• 合并方向：将目标阶段分支合并到功能分支（让工作项与其目标状态保持一致）

如果用户同时指定两个分支（“针对 uat 解决 feature/WI-101 上的冲突”），请继续操作。如果用户提供的是工作项，请先解析其分支。

---

工作流

DevOps Center 晋级阻碍属于 Git 层面的问题。检测和诊断是确定性的（通过脚本完成）；解决每个冲突文件则需要判断（通过文字说明）。必须先在干净的工作区中检测，之后才能解决冲突。

先确定处理路径。 根据用户的情况选择处理路径：

• 合并冲突处理路径——用户想在晋级前检查冲突，或晋级失败的原因是（或疑似是）合并冲突 → 以下阶段 1–4。
• 部署失败处理路径——晋级的部署因错误消息而失败，用户想了解原因和修复方法 → 阶段 D。如果阶段 D 判断失败原因为合并冲突，则转入合并冲突处理路径。

阶段 1 — 身份验证与确认环境

1. 确认本地仓库和干净工作区。 在仓库克隆中运行：

   git rev-parse --is-inside-work-tree && git status --porcelain
   

   • 如果 git status --porcelain 输出任何内容，则工作区不干净——请告知用户先提交更改或暂存更改。对不干净的工作区进行试合并并不安全。
2. 将工作项解析为对应分支（仅当用户提供的是工作项而非分支时）。 通过 sf org display --json 验证组织身份验证；如果失败，请告知用户运行 sf org login web --set-default --alias <alias>。然后查询分支——请参阅 references/git-conflict-resolution.md。

阶段 2 — 检测（不做更改）

3. 运行检测脚本。 该脚本会获取目标分支，将其试合并到功能分支但不提交，列出冲突文件，然后中止试合并，确保工作树保持原样：

   scripts/detect-conflicts.sh <feature-branch> <target-branch> [remote]
   

   • 退出码 0 = 合并干净（无冲突）→ 报告“可以安全晋级”并停止。
   • 退出码 2 = 发现冲突 → 脚本会打印冲突文件列表；继续执行阶段 3。
   • 退出码 1 = 出错（工作树不干净、分支未知、获取失败）→ 报告错误并停止；不要将错误视为“无冲突”。

阶段 3 — 解决冲突

4. 开始实际合并，将冲突标记引入工作树：

   git checkout <feature-branch>
   git merge --no-ff <remote>/<target-branch>
   

   按确定顺序列出冲突文件：

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

5. 解决每个冲突文件——这是需要判断的步骤：
   • 当一方明确正确时，采用该方：git checkout --ours -- <file>（保留功能分支的版本）或 git checkout --theirs -- <file>（采用目标分支的版本）。对于 DevOps Center，“ours”指功能分支，“theirs”指目标阶段分支。
   • 当双方都包含必要更改（对同一组件进行了不同修改）时，打开文件并手动合并——将 <<<<<<< / ======= / >>>>>>> 区域协调为一个正确版本，同时保留双方的意图。尤其要注意 XML 元数据（.xml、.object-meta.xml、.field-meta.xml）：确保文件格式正确，且不要重复元素。
   • 暂存每个已解决的文件：git add <file>。
6. 提交前确认没有剩余标记：

   git diff --check
   git diff --name-only --diff-filter=U
   

   • git diff --check 必须没有任何报告，未合并文件列表也必须为空。如果任一项仍有残留，继续解决冲突——不要提交。

阶段 4 — 完成并报告

7. 提交并推送冲突解决结果到受跟踪的功能分支，以便 DevOps Center 获取：

   git commit --no-edit          # completes the merge with the default merge message
   git push <remote> <feature-branch>
   

8. 报告结果：
   • 无冲突：“<feature> 与 <target> 之间没有合并冲突。可以安全晋级。”
   • 已解决：列出已解决的文件及解决方式（采用一方或手动合并），并说明已推送功能分支。然后交接：“通过 dx-devops-promote 重新验证并晋级。”

阶段 D — 诊断部署失败

当某次提升的 deploy 因错误而失败，且用户想知道原因和修复方法时，使用此流程。诊断结果是确定的（通过脚本得出）；不要凭直觉判断错误。

D1. 将 deploy 错误文本保存到文件中，或直接将其通过管道传入诊断脚本。

D2. 从仓库克隆目录运行诊断脚本。脚本会对失败进行分类、解析缺失的依赖项，并检查该组件是否存在于功能分支上（通过 git show）：

scripts/diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]
# or:  <deploy command> 2>&1 | scripts/diagnose-deploy-failure.sh - <feature-branch> <target-branch>

根据退出代码以及打印出的 REASON / RECOMMENDATION 采取相应措施：

• 退出代码 0（dependency_in_feature_branch）→ 功能分支上存在缺失组件，但它被遗漏在已部署集合之外。完整提升应该可以解决问题。报告这一结果，向用户确认，并交由 dx-devops-promote 执行完整提升。此技能不会执行提升。
• 退出代码 2（merge_conflict）→ 失败原因为合并冲突，而非 deploy 错误。转入合并冲突流程（从阶段 1 开始）。
• 退出代码 3（dependency_not_in_feature_branch）→ 缺失组件不在功能分支上，因此提升无法提供该组件。报告必须先将该组件添加并提交到功能分支（或纳入其所属工作项），然后才能执行提升。
• 退出代码 4（no_dependency_parsed）→ 该错误不是可识别的缺失依赖项。报告原始错误，并建议修复根本问题（例如测试覆盖率或元数据无效）；完整提升无法解决问题。
• 退出代码 1 → 环境／用法错误（不在 git 仓库中、错误文件无法读取）→ 报告后停止。

D3. 报告诊断结果，包括 REASON、完整提升能否解决问题、缺失组件（如有）及其所在位置，以及明确的后续步骤。切勿盲目重新提升——只有诊断结果为 dependency_in_feature_branch 时，才建议执行完整提升。

---

规则／约束

约束	原因
切勿在工作区有未提交更改时试合并或执行合并	在未提交的更改上进行中的合并可能会无法挽回地覆盖用户的工作
始终先检测（阶段 2），再解决（阶段 3）	检测不会造成破坏；不了解冲突集合就直接进行实际合并，可能导致合并状态混乱或只完成一半
使用脚本检测冲突，不要凭直觉判断	scripts/detect-conflicts.sh 会生成确定且可复现的冲突列表，并始终清理试合并
非零检测错误不等于“没有冲突”	只有退出代码 0（干净）才表示可以安全提升；退出代码 1 表示检查失败，必须报告
将目标阶段分支合并到功能分支中	这会使工作项与其目标分支协调一致；DevOps Center 会提升功能分支，因此解决结果必须留在该分支上
提交前确认没有残留冲突标记（git diff --check）	提交未解决的冲突标记会损坏元数据并导致提升失败
手动合并元数据时保持 XML 格式良好	格式错误的 -meta.xml 会导致部署失败；切勿留下重复或截断的元素
只推送工作项的功能分支	解决结果属于工作项分支；切勿直接推送到阶段／集成分支
此技能不会执行提升或部署	解决流程到推送无冲突的分支或完成诊断为止；提升（包括完整提升）由 dx-devops-promote 执行
使用脚本诊断 deploy 失败，不要凭直觉判断	scripts/diagnose-deploy-failure.sh 会确定性地对失败进行分类，并通过 git show 验证分支中是否存在该组件
只有当缺失组件存在于功能分支上时，才建议完整提升	如果组件不存在，提升分支无法提供它——重新提升只会再次失败

---

注意事项

问题	解决方案
不存在 sf devops conflict CLI 命令	DevOps Center 冲突是 Git 冲突——应使用 git 解决，而不是使用 sf devops 子命令。此技能按设计基于 Git
工作树不干净	git status --porcelain 必须无输出；检测或解决冲突前，指导用户先提交或暂存更改
用户提供的是工作项，而不是分支	先通过 sf devops work-item 将工作项解析为其功能分支——请参阅 references/git-conflict-resolution.md
将非零脚本退出码视为干净	退出码 2 = 存在冲突，退出码 1 = 错误。只有退出码 0 才表示“可以安全提升”
仍有冲突标记时提交	在 git commit 前运行 git diff --check，并确认 --diff-filter=U 列表为空；遗留的 <<<<<<</>>>>>>> 标记会破坏元数据
--ours / --theirs 颠倒	将目标分支合并到功能分支时，--ours = 功能分支，--theirs = 目标阶段分支
手动合并的 XML 格式错误	确保 -meta.xml 格式正确；不要重复元素。暂存前重新检查文件是否能解析
分离的 HEAD / 过期分支	先运行 git fetch；合并前将功能分支检出为跟踪分支（脚本会替你获取更新）
解决冲突后重新提升仍然失败	目标分支已发生变化；针对当前目标分支重新检测并再次解决
未诊断就重新提升部署失败项	先运行 scripts/diagnose-deploy-failure.sh：退出码 0 = 组件位于分支上，完整提升即可修复；退出码 2 = 这是合并冲突（切换跟踪项）；退出码 3 = 组件不存在，提升前先添加并提交该组件（或纳入所属工作项）——仅靠提升无法提供该组件

---

输出预期

此技能生成的是无冲突的功能分支或部署失败诊断，不会更改组织：

• 无冲突：确认功能分支可干净地合并到目标阶段分支——可以安全提升
• 已解决冲突：在工作项的功能分支上创建合并提交，使其与目标阶段分支协调一致，并推送到远程服务；同时报告已解决的文件及解决方式（采用某一侧或手动合并）
• 部署失败诊断：报告失败原因（合并冲突 / 分支内缺少依赖项 / 分支外缺少依赖项 / 未识别），完整提升能否修复、缺少的组件及其所在位置，以及具体的后续步骤

不会部署任何元数据，也不会更改任何组织状态。交付内容是已推送的无冲突分支，或诊断结果和建议的后续步骤。

---

跨技能集成

适用情况	操作
分支无冲突（或冲突已解决并推送），可以继续推进	委托给 dx-devops-promote 进行验证和提升
需要将工作项名称/ID 解析为其功能分支，或列出候选工作项	使用 dx-devops-work-item-manage
多个工作项共享元数据，合并后可作为一个单元提升，而不必分别解决	考虑通过 dx-devops-promote 的合并步骤组合工作项，而不是手动合并
提升部署已因冲突失败	针对当前目标分支重新检测，解决冲突并推送，然后通过 dx-devops-promote 重新提升
诊断结果表明完整提升可以修复失败（dependency_in_feature_branch）	交由 dx-devops-promote 执行完整提升——此技能不执行提升
提升前必须将缺少的组件添加到功能分支	编写并提交该组件（或纳入所属工作项）——生成元数据时使用相关领域技能，然后通过 dx-devops-promote 重新提升

---

参考文件索引

文件	何时阅读
scripts/detect-conflicts.sh	阶段 2 — 运行此脚本，以非破坏性方式检测功能分支与目标阶段分支之间的合并冲突
scripts/diagnose-deploy-failure.sh	阶段 D — 运行此脚本，对晋级部署失败进行分类，并判断完整晋级（或修复缺失依赖）是否能解决问题
references/git-conflict-resolution.md	需要完整的 Git 命令参考、sf devops work-item 到分支的查找方法，或 --ours/--theirs 和 XML 合并指南时
references/deploy-failure-resolution.md	阶段 D — 需要部署失败决策树、错误解析模式，或诊断脚本中完整晋级判定依据时
examples/conflict-workflows.md	用户的请求符合常见模式时（晋级前冲突检查、选择一方进行解决、手动合并 XML、排查晋级失败或诊断部署失败）