Beadsbd init与bd dolt拒绝场景恢复手册退出码、销毁令牌与主键分叉PK Fork处置【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文是 Beads 项目 docs/recovery/init-safety.md 恢复手册的深度展开版覆盖bd init三类拒绝远程历史分叉、销毁令牌缺失、本地数据已存在与bd dolt push/pull的主键分叉PK fork拒绝场景。读完本文你将掌握每个拒绝场景对应的稳定退出码、逐条恢复路径、--destroy-token的格式约定以及跨版本升级时避免主键分叉的迁移纪律。背景bd init安全不变量与稳定退出码bd init是 Beads 的身份铸造mint入口负责在.beads/中建立本地数据库并决定project_id的来源。如果初始化路径选择错误例如在远程已有 Dolt 历史时强行--force下一次bd dolt push会产生一条与远端毫无共同祖先的孤儿历史轻则推送失败重则 force-push 覆盖团队数据。为了避免这类事故Beads 通过 engdocs/adr/0002-init-safety-invariants.md 固化了一组安全不变量并在 cmd/bd/init_safety.go 中定义了三个稳定的退出码供 CI 脚本直接分支判断无需 grep stderr退出码常量名含义10ExitRemoteDivergenceRefused远程已有 Dolt 历史refs/dolt/data你却选了本地历史源且未加--discard-remote11ExitLocalExistsRefused本地.beads/已有数据重初始化会永久销毁它们12ExitDestroyTokenMissing非交互模式下传了--discard-remote但缺少或提供了错误的--destroy-token四个核心不变量详见 ADR 0002单源身份解析每次bd init必须恰好从一个显式命名的来源解析project_id——铸造新身份、从远程采纳bootstrap、或本地重初始化。存在多个候选来源且没有旗标指明胜者时bd init拒绝。作用域受限的--force/--reinit-local它们只绕过本地数据安全守卫绝不授权远程历史的静默分叉。中央咽喉点所有可能与远程历史交互的旗标都必须经过 cmd/bd/init_safety.go 的CheckRemoteSafety函数裁决禁止在调用点随手加 !someFlag。错误文本不回显任何运行时错误输出不得包含完整的破坏性命令一行式令牌值DESTROY-prefix只出现在bd help init-safety与本文档中。CheckRemoteSafety是一棵纯函数决策树输入见RemoteSafetyInput旗标状态、远程是否含 Dolt 数据、是否交互式输出为RemoteSafetyDecision动作 退出码 面向用户的拒绝文本。其中动作包括ActionNoRemoteData继续普通 init、ActionBootstrap采纳远程、ActionRefuseDivergence退出码 10、ActionRequireDestroyToken退出码 12、ActionProceedWithDivergence已授权继续。Playbook 1init-force-refused退出码 10症状bd init refuses: remote origin already has Dolt history (refs/dolt/data). Why: this init mode would create or reuse local history instead of adopting the remote. ...发生原因bd init --force或其替代--reinit-local指示bd绕过本地数据安全守卫bd init --from-jsonl则把本地 JSONL 导出选为数据源。但如果远程已经有了项目历史继续执行会创建一条与 origin 无共同祖先的孤儿 Dolt 分支——下一次bd dolt push要么失败无共同祖先要么更糟force-push 直接摧毁团队数据。这正是 ADR 0002 记录的历史故障类--force旗标曾长期存在于全局作用域导致后续新增的每个安全守卫都被它隐式穿透ADR 中列举了至少八个相关提交其中一个错误提示曾让用户损失 247 个 issue。恢复路径按你的意图选择其一采纳远程历史最常见直接运行bd bootstrap该命令把远程的 Dolt 数据库克隆到全新的本地.beads/。本地状态被忽略团队历史成为你的历史。先诊断再决定bd doctor bd dolt statusbd doctor会走查本地与远程状态并指出具体问题bd dolt status展示 Dolt 层视图。两者都不会修改任何数据。有意覆盖远程历史破坏性这是影响所有协作者的跨边界操作。需要把本地源 init--reinit-local或--from-jsonl与--discard-remote配对使用。交互模式下bd会提示确认非交互模式下必须提供--destroy-token格式见 Playbook 2。执行bd init --reinit-local --discard-remote之后你的下一次bd dolt push必须是替换历史的强制推送务必先与团队协调。源码佐证CheckRemoteSafety对“远程有数据 用户显式覆盖force/reinit-local/from-jsonl/discard-remote 未授权 discard”返回ActionRefuseDivergence与退出码 10拒绝文本由refusalMessageDivergence()生成cmd/bd/init_safety.go。端到端回归测试TestInitForceRefusesWhenRemoteHasDoltData用合成refs/dolt/datagit 引用无需真实 Dolt 推送验证非零退出、拒绝文本包含bd bootstrap与bd help init-safety、且不创建.beads/目录cmd/bd/init_safety_test.go。Playbook 2init-token-missing退出码 12症状bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode.发生原因你在非交互模式下运行CI、Agent、管道输入并传了--discard-remote。破坏性跨边界操作不能被静默授权。CheckRemoteSafety在!IsInteractive且令牌缺失或不匹配时返回ActionRequireDestroyToken退出码 12cmd/bd/init_safety.go。恢复路径改为交互运行在 TTY 中重跑bd init --reinit-local --discard-remotebd会在确认时提示你输入销毁令牌。显式提供令牌CI/自动化令牌格式为DESTROY-issue-prefix。例如项目 issue 前缀是bdbd init --reinit-local --discard-remote --destroy-tokenDESTROY-bd自动化应当从项目状态模板化令牌而不是从错误输出中提取——因为按照 ADR 0002 不变量 4bd的错误信息永不回显令牌值。源码中FormatDestroyToken(prefix)即返回fmt.Sprintf(DESTROY-%s, prefix)cmd/bd/init_safety.go其格式契约由测试TestFormatDestroyToken固定cmd/bd/init_safety_test.go。TestCheckRemoteSafety_RefusalTextNoEcho则断言拒绝文本不得包含DESTROY-或--force --discard-remote --destroy-token这类可复制粘贴的破坏性一行式同时必须指明安全路径bd bootstrap与帮助主题bd help init-safetycmd/bd/init_safety_test.go。bd help init-safety是运行时权威参考cmd/bd/init_safety_help.go完整列出旗标面、DESTROY-issue-prefix令牌格式与退出码表。Playbook 3init-local-exists退出码 11症状Refusing to destroy N issues in non-interactive mode. See bd help init-safety for the required --destroy-token format.或者在交互模式下你拒绝了“destroy N issues”的键入确认。发生原因本地.beads/已有 issue 数据bd init --reinit-local会永久销毁它们。CheckRemoteSafety只裁决远程历史交互本地数据守卫由checkExistingBeadsData这类独立列负责见 cmd/bd/init_safety_test.go 矩阵注释。恢复路径先导出再继续bd export issue-export.jsonl bd init --reinit-localissue-export.jsonl允许你在需要时逐个 re-import issue。注意它不是完整数据库备份当 Dolt 数据库尚可创建可恢复备份时请优先使用bd backup。调查为何走到这一步如果你本不该在这里用bd init先跑bd doctor——你遇到的可能是服务器配置问题重初始化并不能修复它。Playbook 4pk-fork-refused——主键分叉症状$ bd dolt pull Error: ... cannot merge because table dependencies has different primary keys in its common ancestor或省略in its common ancestor的变体。bd会紧跟着输出一段精简版恢复指南由printAncestorPKMismatchGuidance生成见 cmd/bd/dolt.go。发生原因两条待合并的历史对某张表的主键集合产生分歧——不是行内容的分歧。Dolt 能对行做 cell-merge但对“主键在两侧被重塑得不同”或共同祖先的主键与两侧都不同的表直接拒绝合并。该拒绝发生在任何行冲突浮现之前因此bd dolt pull的冲突自动解析器根本没有机会运行。重试永远无效这两条历史永久不可合并。通常成因是两个克隆在两侧都有未同步修改时各自独立升级bd跨越了一次会重塑主键的 schema 迁移版本。具体案例#4259事故——跨越0041/0043/0050对dependencies表的重塑v1.0.4 → v1.0.6时若两侧都有未推送的依赖编辑首次升级后 pull 恰好命中此错误。远程迁移防护门v1.0.6的存在就是为了阻止此类问题被制造出来它拒绝自动迁移远程备份的数据库并要求你指定单一迁移者。本 playbook 用于分叉已经发生之后的恢复。恢复从一个权威克隆 bootstrap分叉的历史无法合并因此必须选定一侧为权威canonical其余克隆全部从它重新克隆。issue数据通过 JSONL 导出/导入存活被丢弃的只是不可合并的 Dolt历史。挑选权威克隆通常是数据最完整 / 最近最活跃的克隆。在每个克隆上只读对比bd stats bd dolt status在权威克隆上升级、迁移、强制推送bd version # confirm the new bd binary bd doctor # sanity-check before publishing bd dolt push --force # make the remote authoritativebd的迁移门可能会在此拦截——这正是它询问的“指定迁移者”场景遵循权威克隆上打印的指引即可。在每一个其他克隆上保存本地独有工作、重新克隆、重新应用bd export --all -o /tmp/beads-local.jsonl # safety net for un-synced work rm -rf .beads/dolt # discard the un-mergeable history bd bootstrap # re-clone from the remote bd import /tmp/beads-local.jsonl # re-apply local-only workbd import具有 upsert 语义只存在于本克隆的 issue 会被重建更新的本地编辑会被应用而比远程已有数据更旧的行会被跳过。事后用bd stats抽查。源码佐证错误分类在 cmd/bd/dolt.go——isAncestorPKMismatchErr委托给dberrors.IsAncestorPKMismatch该分类逻辑位于internal/storage/dolt的错误包便于跨升级合并测试钉住真实 Dolt 拒绝ancestorPKMismatchTable从错误中提取表名两者在 cmd/bd/dolt_test.go 有对应表驱动测试覆盖两种变体与 SQL 错误信封。printAncestorPKMismatchGuidance输出的正是上文三步恢复流程的运行时版本。预防跨主键重塑迁移的升级升级前先同步在所有克隆仍运行旧版本时对每个克隆执行bd dolt pushbd dolt pull然后停止编辑。新二进制安装后bd dolt push/pull本身也会被门控所以此步必须先行。指定单一迁移者升级一台机器让它完成迁移然后bd dolt push。其余克隆采纳而非拉取迁移者推送后其余克隆各自升级二进制并运行bd bootstrap采纳已迁移的数据库。克隆仍有待处理迁移时bd dolt pull会被拒绝不要依赖它“升级前同步”正是保全这些克隆工作的关键——因为bd bootstrap会替换本地数据库。附完整旗标面速查命令语义bd init铸造新身份若 origin 有refs/dolt/data则自动 bootstrapbd init --reinit-local在既有本地数据上重初始化不授权丢弃远程历史远程有数据时拒绝需配对--discard-remotebd init --reinit-local --discard-remote丢弃远程 Dolt 历史并用本地重初始化替换之后首次bd dolt push将是替换历史的强制推送交互确认或--destroy-token二选一bd init --from-jsonl从配置的import.path导入origin 有 Dolt 数据时拒绝除非--discard-remote授权替换bd init --force--reinit-local的弃用别名至少保留两个发布周期运行时输出DeprecationWarning见 cmd/bd/init.gobd bootstrap采纳远程——init 拒绝时会提示此路径该旗标面由 cmd/bd/init.go 的 cobra 定义固化与bd help init-safety的文档文本保持同步。恢复手册、ADR、帮助文本三方共同遵守“错误文本不回显”契约因此实际排障时请把bd help init-safety作为运行时权威入口把本文档与 ADR 0002 作为完整参考。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads `bd init` 与 `bd dolt` 拒绝场景恢复手册：退出码、销毁令牌与主键分叉（PK Fork）处置
Beadsbd init与bd dolt拒绝场景恢复手册退出码、销毁令牌与主键分叉PK Fork处置【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文是 Beads 项目 docs/recovery/init-safety.md 恢复手册的深度展开版覆盖bd init三类拒绝远程历史分叉、销毁令牌缺失、本地数据已存在与bd dolt push/pull的主键分叉PK fork拒绝场景。读完本文你将掌握每个拒绝场景对应的稳定退出码、逐条恢复路径、--destroy-token的格式约定以及跨版本升级时避免主键分叉的迁移纪律。背景bd init安全不变量与稳定退出码bd init是 Beads 的身份铸造mint入口负责在.beads/中建立本地数据库并决定project_id的来源。如果初始化路径选择错误例如在远程已有 Dolt 历史时强行--force下一次bd dolt push会产生一条与远端毫无共同祖先的孤儿历史轻则推送失败重则 force-push 覆盖团队数据。为了避免这类事故Beads 通过 engdocs/adr/0002-init-safety-invariants.md 固化了一组安全不变量并在 cmd/bd/init_safety.go 中定义了三个稳定的退出码供 CI 脚本直接分支判断无需 grep stderr退出码常量名含义10ExitRemoteDivergenceRefused远程已有 Dolt 历史refs/dolt/data你却选了本地历史源且未加--discard-remote11ExitLocalExistsRefused本地.beads/已有数据重初始化会永久销毁它们12ExitDestroyTokenMissing非交互模式下传了--discard-remote但缺少或提供了错误的--destroy-token四个核心不变量详见 ADR 0002单源身份解析每次bd init必须恰好从一个显式命名的来源解析project_id——铸造新身份、从远程采纳bootstrap、或本地重初始化。存在多个候选来源且没有旗标指明胜者时bd init拒绝。作用域受限的--force/--reinit-local它们只绕过本地数据安全守卫绝不授权远程历史的静默分叉。中央咽喉点所有可能与远程历史交互的旗标都必须经过 cmd/bd/init_safety.go 的CheckRemoteSafety函数裁决禁止在调用点随手加 !someFlag。错误文本不回显任何运行时错误输出不得包含完整的破坏性命令一行式令牌值DESTROY-prefix只出现在bd help init-safety与本文档中。CheckRemoteSafety是一棵纯函数决策树输入见RemoteSafetyInput旗标状态、远程是否含 Dolt 数据、是否交互式输出为RemoteSafetyDecision动作 退出码 面向用户的拒绝文本。其中动作包括ActionNoRemoteData继续普通 init、ActionBootstrap采纳远程、ActionRefuseDivergence退出码 10、ActionRequireDestroyToken退出码 12、ActionProceedWithDivergence已授权继续。Playbook 1init-force-refused退出码 10症状bd init refuses: remote origin already has Dolt history (refs/dolt/data). Why: this init mode would create or reuse local history instead of adopting the remote. ...发生原因bd init --force或其替代--reinit-local指示bd绕过本地数据安全守卫bd init --from-jsonl则把本地 JSONL 导出选为数据源。但如果远程已经有了项目历史继续执行会创建一条与 origin 无共同祖先的孤儿 Dolt 分支——下一次bd dolt push要么失败无共同祖先要么更糟force-push 直接摧毁团队数据。这正是 ADR 0002 记录的历史故障类--force旗标曾长期存在于全局作用域导致后续新增的每个安全守卫都被它隐式穿透ADR 中列举了至少八个相关提交其中一个错误提示曾让用户损失 247 个 issue。恢复路径按你的意图选择其一采纳远程历史最常见直接运行bd bootstrap该命令把远程的 Dolt 数据库克隆到全新的本地.beads/。本地状态被忽略团队历史成为你的历史。先诊断再决定bd doctor bd dolt statusbd doctor会走查本地与远程状态并指出具体问题bd dolt status展示 Dolt 层视图。两者都不会修改任何数据。有意覆盖远程历史破坏性这是影响所有协作者的跨边界操作。需要把本地源 init--reinit-local或--from-jsonl与--discard-remote配对使用。交互模式下bd会提示确认非交互模式下必须提供--destroy-token格式见 Playbook 2。执行bd init --reinit-local --discard-remote之后你的下一次bd dolt push必须是替换历史的强制推送务必先与团队协调。源码佐证CheckRemoteSafety对“远程有数据 用户显式覆盖force/reinit-local/from-jsonl/discard-remote 未授权 discard”返回ActionRefuseDivergence与退出码 10拒绝文本由refusalMessageDivergence()生成cmd/bd/init_safety.go。端到端回归测试TestInitForceRefusesWhenRemoteHasDoltData用合成refs/dolt/datagit 引用无需真实 Dolt 推送验证非零退出、拒绝文本包含bd bootstrap与bd help init-safety、且不创建.beads/目录cmd/bd/init_safety_test.go。Playbook 2init-token-missing退出码 12症状bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode.发生原因你在非交互模式下运行CI、Agent、管道输入并传了--discard-remote。破坏性跨边界操作不能被静默授权。CheckRemoteSafety在!IsInteractive且令牌缺失或不匹配时返回ActionRequireDestroyToken退出码 12cmd/bd/init_safety.go。恢复路径改为交互运行在 TTY 中重跑bd init --reinit-local --discard-remotebd会在确认时提示你输入销毁令牌。显式提供令牌CI/自动化令牌格式为DESTROY-issue-prefix。例如项目 issue 前缀是bdbd init --reinit-local --discard-remote --destroy-tokenDESTROY-bd自动化应当从项目状态模板化令牌而不是从错误输出中提取——因为按照 ADR 0002 不变量 4bd的错误信息永不回显令牌值。源码中FormatDestroyToken(prefix)即返回fmt.Sprintf(DESTROY-%s, prefix)cmd/bd/init_safety.go其格式契约由测试TestFormatDestroyToken固定cmd/bd/init_safety_test.go。TestCheckRemoteSafety_RefusalTextNoEcho则断言拒绝文本不得包含DESTROY-或--force --discard-remote --destroy-token这类可复制粘贴的破坏性一行式同时必须指明安全路径bd bootstrap与帮助主题bd help init-safetycmd/bd/init_safety_test.go。bd help init-safety是运行时权威参考cmd/bd/init_safety_help.go完整列出旗标面、DESTROY-issue-prefix令牌格式与退出码表。Playbook 3init-local-exists退出码 11症状Refusing to destroy N issues in non-interactive mode. See bd help init-safety for the required --destroy-token format.或者在交互模式下你拒绝了“destroy N issues”的键入确认。发生原因本地.beads/已有 issue 数据bd init --reinit-local会永久销毁它们。CheckRemoteSafety只裁决远程历史交互本地数据守卫由checkExistingBeadsData这类独立列负责见 cmd/bd/init_safety_test.go 矩阵注释。恢复路径先导出再继续bd export issue-export.jsonl bd init --reinit-localissue-export.jsonl允许你在需要时逐个 re-import issue。注意它不是完整数据库备份当 Dolt 数据库尚可创建可恢复备份时请优先使用bd backup。调查为何走到这一步如果你本不该在这里用bd init先跑bd doctor——你遇到的可能是服务器配置问题重初始化并不能修复它。Playbook 4pk-fork-refused——主键分叉症状$ bd dolt pull Error: ... cannot merge because table dependencies has different primary keys in its common ancestor或省略in its common ancestor的变体。bd会紧跟着输出一段精简版恢复指南由printAncestorPKMismatchGuidance生成见 cmd/bd/dolt.go。发生原因两条待合并的历史对某张表的主键集合产生分歧——不是行内容的分歧。Dolt 能对行做 cell-merge但对“主键在两侧被重塑得不同”或共同祖先的主键与两侧都不同的表直接拒绝合并。该拒绝发生在任何行冲突浮现之前因此bd dolt pull的冲突自动解析器根本没有机会运行。重试永远无效这两条历史永久不可合并。通常成因是两个克隆在两侧都有未同步修改时各自独立升级bd跨越了一次会重塑主键的 schema 迁移版本。具体案例#4259事故——跨越0041/0043/0050对dependencies表的重塑v1.0.4 → v1.0.6时若两侧都有未推送的依赖编辑首次升级后 pull 恰好命中此错误。远程迁移防护门v1.0.6的存在就是为了阻止此类问题被制造出来它拒绝自动迁移远程备份的数据库并要求你指定单一迁移者。本 playbook 用于分叉已经发生之后的恢复。恢复从一个权威克隆 bootstrap分叉的历史无法合并因此必须选定一侧为权威canonical其余克隆全部从它重新克隆。issue数据通过 JSONL 导出/导入存活被丢弃的只是不可合并的 Dolt历史。挑选权威克隆通常是数据最完整 / 最近最活跃的克隆。在每个克隆上只读对比bd stats bd dolt status在权威克隆上升级、迁移、强制推送bd version # confirm the new bd binary bd doctor # sanity-check before publishing bd dolt push --force # make the remote authoritativebd的迁移门可能会在此拦截——这正是它询问的“指定迁移者”场景遵循权威克隆上打印的指引即可。在每一个其他克隆上保存本地独有工作、重新克隆、重新应用bd export --all -o /tmp/beads-local.jsonl # safety net for un-synced work rm -rf .beads/dolt # discard the un-mergeable history bd bootstrap # re-clone from the remote bd import /tmp/beads-local.jsonl # re-apply local-only workbd import具有 upsert 语义只存在于本克隆的 issue 会被重建更新的本地编辑会被应用而比远程已有数据更旧的行会被跳过。事后用bd stats抽查。源码佐证错误分类在 cmd/bd/dolt.go——isAncestorPKMismatchErr委托给dberrors.IsAncestorPKMismatch该分类逻辑位于internal/storage/dolt的错误包便于跨升级合并测试钉住真实 Dolt 拒绝ancestorPKMismatchTable从错误中提取表名两者在 cmd/bd/dolt_test.go 有对应表驱动测试覆盖两种变体与 SQL 错误信封。printAncestorPKMismatchGuidance输出的正是上文三步恢复流程的运行时版本。预防跨主键重塑迁移的升级升级前先同步在所有克隆仍运行旧版本时对每个克隆执行bd dolt pushbd dolt pull然后停止编辑。新二进制安装后bd dolt push/pull本身也会被门控所以此步必须先行。指定单一迁移者升级一台机器让它完成迁移然后bd dolt push。其余克隆采纳而非拉取迁移者推送后其余克隆各自升级二进制并运行bd bootstrap采纳已迁移的数据库。克隆仍有待处理迁移时bd dolt pull会被拒绝不要依赖它“升级前同步”正是保全这些克隆工作的关键——因为bd bootstrap会替换本地数据库。附完整旗标面速查命令语义bd init铸造新身份若 origin 有refs/dolt/data则自动 bootstrapbd init --reinit-local在既有本地数据上重初始化不授权丢弃远程历史远程有数据时拒绝需配对--discard-remotebd init --reinit-local --discard-remote丢弃远程 Dolt 历史并用本地重初始化替换之后首次bd dolt push将是替换历史的强制推送交互确认或--destroy-token二选一bd init --from-jsonl从配置的import.path导入origin 有 Dolt 数据时拒绝除非--discard-remote授权替换bd init --force--reinit-local的弃用别名至少保留两个发布周期运行时输出DeprecationWarning见 cmd/bd/init.gobd bootstrap采纳远程——init 拒绝时会提示此路径该旗标面由 cmd/bd/init.go 的 cobra 定义固化与bd help init-safety的文档文本保持同步。恢复手册、ADR、帮助文本三方共同遵守“错误文本不回显”契约因此实际排障时请把bd help init-safety作为运行时权威入口把本文档与 ADR 0002 作为完整参考。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考