Beads 合并冲突（Merge Conflicts）实战指南：Dolt 同步冲突的排查、恢复与预防

Beads 合并冲突Merge Conflicts实战指南Dolt 同步冲突的排查、恢复与预防【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本篇技术指南围绕 Beads 官方恢复手册 docs/recovery/merge-conflicts.md 展开系统讲解在bd dolt pull/bd dolt push/bd sync同步过程中遇到 Dolt 合并冲突时的完整处置流程从症状识别、bd doctor诊断到--fix自动修复、bd conflicts逐条裁决再到工作会话前后的同步预防策略。读完你将掌握一套可复制、可验证的冲突恢复 runbook并理解 Beads 在底层如何通过字段级三方合并与自动化解冲突机制把需要人工介入的场景压缩到最小。为什么 Dolt 同步会产生合并冲突Beads 将 issue 数据持久化在 Dolt 数据库中默认位于.beads/dolt并通过bd dolt pull/bd dolt push与远程仓库同步。当两个 clone例如两台机器上的两个 coding agent在两次同步之间修改了同一条数据Dolt 合并时就可能产生冲突bd dolt pull以 conflict errors 失败不同 clone 之间出现不一致的 issue 状态例如克隆 A 看到in_progress克隆 B 却看到open。从源码看冲突检测与自动化解是一条完整的链路internal/storage/versioncontrolops/mergesettle.go中的TryAutoResolveMergeConflicts会先尝试自动化解安全的冲突类别只有当自动化解无法收敛时合并才会中止并交还给操作者处理对应 cmd/bd/doctor/validation.go 中CheckGitConflicts对dolt_conflicts系统表的查询、以及 cmd/bd/conflicts.go 中的bd conflicts系列命令。症状Symptoms当出现以下任一现象时基本可以断定工作区处于合并冲突状态症状说明bd dolt pull失败合并远端提交时因冲突报错pull 中止不同 clone 之间 issue 状态不一致同一 issue 在两个 clone 上读到不同状态说明历史已分叉且未收敛bd sync退出码为 2bd sync遇到无法安全自动化解的冲突时会故意在推送前停止并以退出码 2 报告冲突见 cmd/bd/sync.go 中的ExitSyncConflict常量并且绝不会自动站队——避免定时同步静默丢弃某一方的编辑诊断Diagnosis诊断的核心命令是bd doctor它是 Beads 安装与数据库健康检查的入口命令定义见 cmd/bd/doctor.go# 检查数据库健康 bd doctor # 预览将要应用哪些修复不实际改动 bd doctor --dry-runbd doctor会执行数十项检查与冲突直接相关的包括Git ConflictsDolt 后端直接查询dolt_conflicts系统表按表统计num_conflicts一旦发现未解决的冲突即以 error 状态报告实现见 cmd/bd/doctor/validation.go 的checkDoltConflictsMigration Content Skew检测两 clone 因混合版本二进制导致 schema_migrations 内容哈希分叉bd-6dnrw.29/#4259Database Integrity / Schema Compatibility冲突遗留可能伴生的数据完整性问题。--dry-run模式下bd doctor只previewFixes(result)预览修复计划不写入任何存储见 cmd/bd/doctor.go 的 RunE 分支适合在动手前确认诊断结论。解决方案Solution五步恢复流程原手册给出了从备份到推送的完整恢复步骤下面结合源码逐一展开。Step 1备份当前状态cp -r .beads .beads.backup.beads/目录是 Beads 的全部本地状态含 Dolt 数据库、metadata.json、配置等。恢复操作涉及数据写入先做整目录备份确保任何一步出错都可以回滚。Step 2检查冲突bd doctor若 doctor 输出中 Git Conflicts 检查为 error并列出冲突表如issues (2)即确认存在未解决的合并冲突。doctor 输出的修复建议字段Fix会给出下一步指引。Step 3修复以达成收敛bd doctor --fixbd doctor --fix会对可自动修复的检查项应用修复需要交互确认可加-y跳过确认-i逐项确认。对于合并冲突doctor 的修复建议是使用bd conflicts resolve --ours/--theirs或 dolt 原生命令解决。更精细的冲突裁决请使用专门的bd conflicts命令族见下文冲突的精细化裁决。Step 4验证状态bd list bd stats确认 issue 列表完整、统计数字合理且不再出现冲突报错。也可再次运行bd doctor确认 Git Conflicts 检查恢复为 ok。Step 5推送已解决的状态bd dolt push将收敛后的本地历史推送到远端使所有 clone 重新对齐。推送成功后建议在其他 clone 上执行bd dolt pull完成最终同步。冲突的精细化裁决bd conflicts 命令族bd doctor --fix解决的是可自动修复的问题真正落在你面前、需要你来选择保留哪一方的冲突用 cmd/bd/conflicts.go 实现的bd conflicts命令族处理——它把 dolt 原生dolt conflicts cat/resolve的表格级操作变成按 issue 逐条、按字段对比的操作面# 列出哪些表、哪些 issue 存在冲突含 schema 冲突与约束违例等隐形阻塞项 bd conflicts list # 逐字段展示每个冲突行的 base / ours / theirs 三侧取值 bd conflicts show # 只看某一条 issue 的冲突 bd conflicts show bd-1234 # 保留我们这一侧解决单条 issue bd conflicts resolve bd-1234 --ours # 全部采用远端一侧 bd conflicts resolve --all --theirs关键行为与源码一一对应三类状态不混为一谈conflicts list会区分存在冲突行、合并已打开但已解决用--conclude收尾以及schema 冲突 / 约束违例阻塞三种情形见mergeBlockers逻辑只有全部冲突清零才提交resolve在提交前会检查totalConflicts与mergeBlockers若仍有残余冲突则保留合并状态、暂不提交shouldCommitResolution判定避免提交一个仍处于冲突的工作区--conclude收尾对已经解决完但尚未提交的合并例如--no-commit之后用bd conflicts resolve --conclude完成提交schema 冲突与约束违例无法用 ours/theirs 解决输出会明确提示需要dolt merge --abort后重新合并、或手工处理dolt_constraint_violations_table中的违例行。让合并更省心pull / merge 的 --strategy 逃生口在合并之前就指定策略可以绕过人工裁决# 合并分支时遇到冲突自动采用我们一侧 bd vc merge feature-xyz --strategy ours # 合并分支时遇到冲突自动采用他们一侧 bd vc merge feature-xyz --strategy theirs # 嵌入式存储下 pull 时指定冲突策略 bd dolt pull --strategy theirsbd vc merge --strategy的底层是MergeWithStrategy见 internal/storage/versioncontrolops/mergesettle.go它会用SET dolt_allow_commit_conflicts1等会话标志让冲突落入工作区而非直接回滚再对所有冲突表执行指定的DOLT_CONFLICTS_RESOLVE并继续修复可能遗留的外键级联违例TryRepairFKCascadeViolations需要注意bd dolt pull --strategy仅嵌入式存储支持#4992server-mode / sql-server 存储应在 pull 报告冲突后使用bd conflicts resolve。自动化解机制哪些冲突不需要你动手在冲突到达你面前之前Beads 的 pull 路径SettleMerge/TryAutoResolveMergeConflicts已经尝试自动化解被证明安全的冲突类别源码见 internal/storage/versioncontrolops/mergesettle.go 与 internal/storage/versioncontrolops/automerge.go冲突类别自动化解规则metadata表机器本地行如dolt_auto_push_*跨 clone 常规性分叉采用--theirsdependencies表同一逻辑依赖边issue_id 与目标一致、仅审计列不同采用--theirs类型不同或一方删除则留给操作者schema_migrations仅一方有 content_hash、另一方为空的 vintage 行保留有哈希的一侧两个不同非空哈希#4259schema 分叉留给操作者config表仅kv.memory.*持久记忆行收敛合并采用--theirsissue_prefix等语义键冲突留给操作者issues表字段级三方合并见 automerge.go相对 merge base 只有一侧改动的字段保留该侧值两侧都改且不同的字段按updated_at后写胜出close 相关字段status/closed_at/close_reason/closed_by_session原子移动notes/metadata等结构性字段冲突则拒绝自动化解labels/comments/events表集合/追加式并集合并两侧相同的行直接保留一侧缺失或列不一致则留给操作者此外合并还会自动修复一侧删除了 issue、另一侧插入了引用它的子行所产生的外键级联违例TryRepairFKCascadeViolations并重建被合并写入绕过的is_blocked派生列RecomputeBlockedAfterMerge见 cmd/bd/vc.go 的blockedAfterMergeRecomputer接口避免bd ready展示过期的工作项。只有自动化解无法收敛的冲突才会中止合并、恢复工作区并抛给操作者——这也正是bd doctor能检测到冲突的原因。预防Prevention工作会话前后同步每次工作开始前和结束后都执行bd dolt pull/bd dolt push把同步间隔压缩到最小从源头减少双方修改同一数据的概率避免无 Dolt server 的多 clone 并发修改在没有 Dolt server 运行的情况下多个 clone 同时写库更容易制造分叉尽量让并发写入收敛到 Dolt server 模式下使用bd sync作为常规同步循环bd sync把 pull → 冲突正向检测 →is_blocked重建 → push 封装成单条命令最多重试 3 次见 cmd/bd/sync.go冲突时以退出码 2 明确停机并拒绝自动站队适合放在定时任务中退出码 3 表示瞬时竞争可下轮重试退出码 4 表示工作区卡死需要人工介入升级注意避免在两个 clone 未同步的情况下各自独立运行 schema 迁移否则可能形成主键集分叉#4259这类重试无法收敛的硬分歧——此时需要选定一个权威 clonebd dolt push --force其余 clone 导出本地数据后重新bd bootstrap再导入详见 cmd/bd/dolt.go 中printAncestorPKMismatchGuidance给出的完整 playbook。小结Beads 的合并冲突恢复是一条先自动、再诊断、后裁决的完整链路pull 路径用字段级三方合并与类别白名单自动化解绝大多数冲突无法自动化解时bd doctor含--dry-run、--fix负责诊断与修复bd conflicts list/show/resolve提供按 issue、按字段的精细化裁决--strategy选项允许提前指定站队策略最后通过会话前后规律同步与bd sync巡检把冲突概率降到最低。按本文的五步流程操作即可安全地把分叉的历史收敛回一致状态。更多恢复主题如数据库损坏、历史压缩、初始化安全可查阅 docs/recovery/index.md 目录下的系列手册。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考