
Beads 存储瘦身实战bd compact 命令全解析——Dolt 提交历史压缩与空间回收指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd compact是 Beads为编码 Agent 提供记忆增强的开源工具中用于压缩 Dolt 提交历史的维护命令它把超过--days阈值默认 30 天的旧提交压成一个基础提交通过 cherry-pick 保留最近窗口内的提交并在收尾阶段执行远程引用清理与 Dolt GC 以真正回收磁盘空间。读完本文你将掌握bd compact的完整工作流、全部参数语义、与bd admin compact/bd flatten/bd prune等维护命令的边界划分以及它在嵌入式模式与服务端模式下的行为差异和已知陷阱。一、命令定位它解决什么问题Beads 使用 Dolt 作为版本化存储后端详见 Dolt 后端架构。在嵌入式模式下每一次写操作都会自动产生一个 Dolt 提交auto-commit长时间运行后提交历史会持续膨胀带来两方面的开销存储开销每个提交都是 Dolt 中的一条不可变记录旧提交占用的表文件长期得不到回收检索开销提交日志、历史查询与分支操作需要在更长的链上工作。bd compact的目标不是删除数据而是把“历史”折叠将保留窗口retention window之外的旧提交合并为一个快照式基础提交同时完整保留窗口内最近的提交及其变更语义。文档中的定位说明如下Squash Dolt commits older than N days into a single commit. Recent commits (within the retention window) are preserved via cherry-pick. This reduces Dolt storage overhead from auto-commit history while keeping recent change tracking intact.与此配套Beads 提供了一系列职责不同的维护命令使用时不要混淆命令职责数据影响bd compact根命令压缩Dolt 提交历史旧提交合并为单个基础提交保留窗口内提交不变窗口外历史折叠bd admin compact语义压缩用 AI 对已关闭 issue 做摘要替换冗长正文修改 issue 内容原始内容先归档快照bd flatten全量历史扁平化一次性压平所有 Dolt 历史丢弃完整提交历史仅保留最新状态bd prune/bd purge物理删除已关闭的普通/临时 issue 行数据删除记录需要--forcebd gcDolt 垃圾回收回收不可达对象简单记忆bd compact管历史bd admin compact管内容bd flatten管极致压平bd prune/purge管删除行bd gc管最终回收。二、工作原理六步压缩流程根据命令行入口 cmd/bd/compact_dolt.go 的Long帮助文本bd compact的完整流程为识别旧提交遍历提交日志找出日期早于--days截止线cutoff now - days的所有提交创建压缩基础提交以边界提交为起点把全部旧历史软重置后提交为一个 squashed baseCherry-pick 保留近期提交把保留窗口内的提交逐个重放到新基础之上切换 main 分支将main硬重置到压缩后的分支清理远程跟踪引用remote-tracking refs这是代码实现比 CLI 文档多出的一步——远程引用仍锚定旧链若不清理GC 在曾 push/fetch 过的工作区上什么也回收不到运行 Dolt GC回收孤儿对象真正释放磁盘。底层实现versioncontrolops.Compact真正执行历史折叠的是 internal/storage/versioncontrolops/compact.go 中的Compact函数它通过 Dolt 存储过程完成 7 个步骤// 1. Create temp branch at the boundary commit (last old commit) CALL DOLT_BRANCH(compact-tmp, boundaryHash) // 2. Checkout temp branch CALL DOLT_CHECKOUT(compact-tmp) // 3. Soft-reset to initial commit (collapses old history into working set) CALL DOLT_RESET(--soft, initialHash) // 4. Commit as single squashed base CALL DOLT_COMMIT(-Am, compact: squash N commits into base snapshot) // 5. Cherry-pick each recent commit on top CALL DOLT_CHERRY_PICK(--allow-empty, recentHash) // 6. Checkout main, hard-reset to temp branch CALL DOLT_CHECKOUT(main) CALL DOLT_RESET(--hard, compact-tmp) // 7. Delete temp branch CALL DOLT_BRANCH(-D, compact-tmp)几个关键实现细节值得注意单连接执行函数签名要求conn是单个数据库连接而非连接池因为存储过程依赖会话级状态当前分支、工作集--allow-empty参数保留窗口内可能包含空提交无表变更的 auto-commit或bd create双重提交中的空成员。若不加该标志DOLT_CHERRY_PICK会在第一个空提交处报Error 1105中止整个重放使压缩永久阻塞在活跃数据库上对应 issue #3815失败自愈函数带有defer清理逻辑一旦中途失败会尽力DOLT_CHECKOUT(main)并删除compact-tmp临时分支避免残留分支阻塞后续压缩接口化设计internal/storage/storage.go中定义了Compactor接口Compact(ctx, initialHash, boundaryHash, oldCommits, recentHashes)DoltStore服务端与EmbeddedDoltStore嵌入式分别实现命令层通过storage.UnwrapStore(store).(storage.Compactor)类型断言调用。三、参数详解与默认值bd compact的完整参数由 cmd/bd/compact_dolt.go 注册与 CLI 参考文档一致bd compact [flags]参数类型默认值说明--days intint30保留最近 N 天的提交早于 N 天的提交将被压缩--dry-runboolfalse只预览提交拆解结果不做任何修改-f, --forceboolfalse确认执行提交压缩消除二次确认--jsonboolfalse全局 flag以 JSON 结构输出结果便于脚本/Agent 解析参数行为边界源码确认--days必须非负compactDoltDays 0时直接报错--days must be non-negative见 cmd/bd/compact_dolt.go提交数 ≤ 1 时无事可做日志中只有 0 或 1 个提交时输出Only N commit(s). Nothing to compact.并正常退出旧提交 ≤ 1 时不压缩即使提交很多若截止线前只有 0~1 个旧提交同样输出Nothing to compact必须--force确认未加--force且存在可压缩提交时命令报错并给出提示would squash N old commits into 1, preserving M recent commits并提示Use --force to confirm or --dry-run to preview.只读路径免确认--dry-run模式不触发CheckReadonly与 server-mode 校验可安全预览。四、实战示例以下示例均来自命令帮助文本与源码实现可直接在已bd init的 Beads 项目中执行。1. 预览查看提交拆解bd compact --dry-run输出预览含--json时字段更全DRY RUN — Compact preview Total commits: 120 Old (30 days): 95 (would be squashed into 1) Recent: 25 (preserved) Cutoff date: 2026-08-12 Nothing to compact (0-1 old commits). # 或 Result: 120 commits → 26 commits Run with --force to proceed.JSON 模式bd --json compact --dry-run会输出结构化字段total_commits、old_commits、recent_commits、cutoff_days、cutoff_date、initial_hash、boundary_hash非常适合接入自动化巡检脚本。2. 执行压缩 30 天前的历史默认窗口bd compact --force3. 激进只保留最近 7 天bd compact --days 7 --force适合希望把历史压得更薄、且确认最近一周的变更追踪足够的场景。4. 保守只压缩 90 天前的提交bd compact --days 90 --force适合对历史追溯要求较高的场景先压最古老的部分试水。5. 完整执行结果解读成功时输出含 GC 后体积对比✓ Compacted 120 commits → 26 Squashed: 95 old commits → 1 base Preserved: 25 recent commits Store: 1.2 GiB → 380.0 MiB Time: 3.2sJSON 模式额外包含commits_before、commits_after、old_squashed、recent_kept、remote_refs_pruned、tags_anchoring、elapsed_ms及 GC 前后体积字段。五、模式差异嵌入式 vs 服务端Proxied ServerBeads 支持两种 Dolt 部署模式详见 Dolt 后端架构嵌入式embeddedDolt 引擎内嵌在bd进程中单写入者数据位于.beads/embeddeddolt/无需额外安装服务端server / proxied-server连接独立dolt sql-server多写入者并发数据位于.beads/dolt/。bd compact在两种模式下都可用嵌入式模式直接调用EmbeddedDoltStore.Compactproxied-server 模式则通过 cmd/bd/compact_proxied_server.go 路由到服务端执行同样校验--days非负。bd compact属于修改类操作会触发CheckReadonly(compact)只读保护在 proxied-server 模式下不支持的内容会得到明确报错提示。版本陷阱重要bd compact与bd flatten都以“硬重置 main 到临时分支”收尾即CALL DOLT_RESET(--hard, compact-tmp)。Beads 固定使用 Dolt2.2.0go.mod 内嵌版本因为实测 2.3.0/2.3.1 存在DOLT_RESET(--hard)随机失效回归新建数据库出现Error 1105 (HY000): context canceled会导致压缩在最后一步失败。相关检测方法与升级决策依据见 docs/architecture/dolt.md。若你手头是 2.3.x务必先按文档中的三步检查法确认数据库健康再执行压缩。六、相关命令边界何时不该用 bd compact语义压缩用bd admin compactbd compact只折叠 Dolt 提交历史不改变任何 issue 内容。若你的目标是缩小已关闭 issue 的正文体积用 AI 摘要替换冗长内容应使用bd admin compact注册于 cmd/bd/admin.go实现于 cmd/bd/compact.gobd admin compact --stats # 查看可压缩候选统计 bd admin compact --analyze --json # 导出候选供 Agent 评审无需 API key bd admin compact --apply --id bd-42 --summary summary.txt # 应用 Agent 提供的摘要 bd admin compact --auto --all # AI 自动压缩需 ANTHROPIC_API_KEY / MINIMAX_API_KEY / ai.api_keybd admin compact的机制要点来自 internal/compact/compactor.go仅实现Tier 1关闭 30 天以上目标压缩 70%Tier 290 天超压缩标注为 planned、未实现压缩前先调用SnapshotIssue归档原始内容快照压缩是可逆的——bd restore可读取该快照回滚归档失败则中止且不破坏原文摘要若不比原文短则跳过压缩并在 issue 上追加警告评论--auto的 mutating 操作要求 server 模式requireServerMode而--stats/--analyze/--dry-run是只读路径嵌入式模式可用bd admin compact --dolt对.beads/dolt目录运行外部dolt gc先尝试--archive-level 0若外部 dolt 版本不认识该 flag 则自动回退到纯dolt gc。全量扁平化用bd flatten若你希望一次性丢弃全部提交历史、只保留最新数据快照使用bd flatten同样是建临时分支后硬重置 main。bd compact则是在保留最近窗口的前提下做有界折叠。删除数据用bd prune/bd purgebd compact不删除任何 issue 记录。删除已关闭的普通 issue 用bd prune --older-than 30d --force删除临时性 issuewisps、瞬时 molecule用bd purge --force二者均有引用感知保护避免误删被开放 issue 引用的内容。七、如何验证测试与回归保障仓库用多种测试覆盖了bd compact的行为可作为理解其语义的辅助证据cmd/bd/compact_embedded_test.go嵌入式模式集成测试覆盖--dry-run预览、单提交时的Nothing to compact、缺失--force时的报错与提示、--days 0全量压缩、--daysflag 生效、JSON 输出不崩溃以及 8 并发--dry-run下的锁安全容忍one writer at a time报错cmd/bd/maintenance_commands_proxied_integration_test.goproxied-server 模式下--days 0/--days 3650的压缩与 JSON 输出验证internal/compact/compactor_test.go 与 internal/compact/git_test.goCompactor逻辑与GetCurrentCommitHashgit 命令注入 hook的单元测试。运行嵌入式集成测试需设置环境变量BEADS_TEST_EMBEDDED_DOLT1源码注释也明确给出了该前提。八、最佳实践小结先预览后执行养成bd compact --dry-run先看的习惯确认old_commits/recent_commits拆分符合预期按需调节窗口默认 30 天是平衡点对历史追溯敏感的仓库用--days 90对体积敏感的仓库用--days 7配合 GC 与引用清理命令末尾会自动清理 remote-tracking refs 并执行 Dolt GC不要在 push/fetch 后立即期待体积显著下降先让命令完整走完区分命令职责压历史用bd compact压内容用bd admin compact全量压平用bd flatten删数据用bd prune/purge关注 Dolt 版本保持 2.2.0 固定版本升级前先跑CALL DOLT_RESET(--hard)健康检查避免压缩在硬重置步骤失败善用 JSON 输出bd --json compact --dry-run可安全接入定期巡检把提交数与体积指标纳入监控。参考链接CLI 参考文档docs/cli-reference/compact.mdDolt 后端架构与版本策略docs/architecture/dolt.md命令实现cmd/bd/compact_dolt.go、cmd/bd/compact.go、cmd/bd/compact_proxied_server.go底层压缩算法internal/storage/versioncontrolops/compact.go存储接口定义internal/storage/storage.go语义压缩实现internal/compact/compactor.go相关测试cmd/bd/compact_embedded_test.go、cmd/bd/maintenance_commands_proxied_integration_test.go【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考