尧图网站建设 
Beads 高级功能实战指南Issue 重命名、去重合并、数据库压缩与多工作区管理【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本篇技术指南围绕 Beads 官方文档 docs/reference/advanced.md 展开系统讲解 Beads面向编码 Agent 的记忆增强型 Issue 管理工具的进阶运维能力单条与批量 ID 重命名、重复 Issue 的检测与自动合并、旧 Issue 压缩与历史恢复、跨 git clone 的数据库重定向以及针对大数据库、多并发 Agent 与 CI/CD 场景的性能调优。阅读本文后你将掌握每条高级命令的完整参数、底层行为边界与可验证的源码依据能够安全地在生产数据库上执行这些低频但高风险的维护操作。重命名 Issue保留引用关系的安全改名bd rename当需要把晦涩的哈希 ID 换成可读、好记的 ID 时例如把bd-w382l改为bd-dolt使用bd rename。命令支持--dry-run预演且重命名是全库一致的——不仅仅是改主键本身bd rename bd-42 bd-new-id bd rename bd-42 bd-new-id --dry-run # 预览将发生的改动根据 cmd/bd/rename.go 的实现一次bd rename会完整更新该 Issue 的主 ID通过存储层的UpdateIssueID原子改写指向旧 ID 的全部依赖关系dependency edges其他 Issue 文本字段中的引用——updateReferencesInAllIssues会遍历全库用\b旧ID\b词边界正则逐一替换 title、description、design、notes、acceptance_criteria 五个文本字段见 rename.go#L104-L152标签、评论与事件记录。需要留意两个硬性校验源码 rename.go#L56-L84新旧 ID 不能相同新 ID 必须匹配^[a-z]-[a-zA-Z0-9._-]$即合法前缀-后缀格式且新 ID 不得已存在于库中。单条改名的完整用法可参考 docs/cli-reference/rename.md。前缀重命名与损坏库修复bd rename-prefixbd rename-prefix把数据库中每一个 Issue的前缀统一替换典型场景是把冗长的knowledge-work-缩短为kw-bd rename-prefix kw- --dry-run # 预览而不实际应用 bd rename-prefix kw- # 所有 knowledge-work-* ID 变为 kw-*该命令会同时更新所有 Issue ID 以及全部字段中的文本引用。--dry-run会打印每条旧ID - 新ID的样本改动与剩余条数非 dry-run 时源码renamePrefixInDB用\b旧前缀-(\d)\b正则对所有文本字段做整体替换最后把配置项issue_prefix写为新值见 cmd/bd/rename_prefix.go#L422-L469。前缀合法性规则源码validatePrefixrename_prefix.go#L223-L240规则说明允许字符仅小写字母、数字、连字符^[a-z][a-z0-9-]*$首字符必须以字母开头尾字符必须以连字符结尾如kw-、work-禁止情形不能为空不能只是-不能以-开头或出现--多前缀损坏库的修复如果数据库因异常如半迁移混入了多个前缀bd rename-prefix会先通过detectPrefixes统计每个前缀下的 Issue 数一旦检测到多于一个前缀就必须用--repair收敛bd rename-prefix mtg- --repair # 将多个前缀合并为 mtg- bd rename-prefix team- --dry-run # 先预览再动手repairPrefixes的实现细节rename_prefix.go#L261-L398前缀已正确等于目标前缀的 Issue 保持不变前缀错误的 Issue 会基于内容哈希重新生成 8 位十六进制 IDgenerateRepairHashID使用 SHA-256 对 title/description/actor/createdAt 取前 4 字节并在批内通过usedIDs防碰撞、失败时用 nonce 重试随后对所有文本字段做引用替换并调用UpdateIssueID落库。值得一提的是从源码注释GH#4827、GH#5135 相关可以看出实现还处理了一种特殊情形配置里的issue_prefix与行上实际前缀不一致半迁移库时命令会只修复配置单元、不重写任何 ID避免产生atlas-atlas-*这样的双重前缀。完整命令文档见 docs/cli-reference/rename-prefix.md。重复检测与合并去重不再手工核对bd duplicates / bd duplicate内容完全相同的 Issuetitle、description、design、acceptance criteria 全部一致会随着多 Agent 协作不断累积。bd duplicates负责发现并收敛它们bd duplicates # 报告重复组与建议动作 bd duplicates --dry-run # 预览 --auto-merge 将执行的操作 bd duplicates --auto-merge # 自动合并每一组重复分组原理源码 cmd/bd/duplicates.go#L194-L224findDuplicateGroups以contentKey{title, description, design, acceptanceCriteria, status}为分组键——也就是说状态必须一致才会进入同一组开 Issue 配开 Issue、关 Issue 配关 Issue从实现看当前版本只把未关闭非closed的 Issue 纳入建组openIssuesOf并以status字段保证组内状态一致。合并目标选择每组中应该留下谁由chooseMergeTarget按三级优先级裁决duplicates.go#L273-L330结构权重最高dependentCount*3 dependsOnCount。子 Issuedependents权重 ×3因为丢弃带子 Issue 的父 Issue 会让子节点孤立灾难性而丢失 depends-on 链接是可恢复的文本引用数其他 Issue 描述/备注中提到的次数countReferences字典序最小 ID作为稳定的最终平局裁决。--auto-merge对每组执行三步performMergeduplicates.go#L375-L452把重复 Issue 的子 Issue 重新挂到合并目标下先RemoveDependency旧父子链再AddDependency新父子链避免子节点孤儿化以原因Duplicate of target关闭重复 Issue为每个重复 Issue 与目标之间建立related类型的依赖链接。若只想手动标记单个已知重复用bd duplicate bd-42 --of bd-41 # 把 bd-42 作为 bd-41 的重复关闭关闭是永久的但 Beads 基于 Dolt 的版本历史会保留原始状态合并后建议用bd show bd-41与bd dep tree bd-41复核结果。文本输出与 JSON 输出含suggested_action、merge_results都能用于脚本化审计详见 docs/cli-reference/duplicates.md 与 docs/cli-reference/duplicate.md。数据库压缩给老 Issue 做语义瘦身bd admin compact数据库体积膨胀主要来自长期未关闭、内容冗长的历史 Issue。Beads 提供了四类压缩模式源码 cmd/bd/compact.go# 查看压缩统计 bd admin compact --stats # 导出候选清单30 天关闭的 Issue供 Agent 人工审核 bd admin compact --analyze --json # 应用 Agent 生成的摘要 bd admin compact --apply --id bd-42 --summary summary.txt # 立即删除高危 bd admin cleanup --force各模式行为与参数约束均可加--json输出机器可读结果模式作用关键约束--stats输出 Tier 1/Tier 2 候选数与总体积只读无需 API Key--analyze导出候选 Issue 的完整内容含--id单条模式与--limit只读无需 API Key--apply接受 Agent 编写的摘要并落库必须同时指定--id与--summary--summary -从 stdin 读取--autoAI 自动压缩需ANTHROPIC_API_KEY、MINIMAX_API_KEY或配置中的ai.api_key--dolt对.beads/dolt目录执行 Dolt GC 回收磁盘需本机 PATH 中存在doltTier 分级Tier 1 为关闭满 30 天、目标压缩率约 70%的语义压缩也是当前唯一实现的层级Tier 2关闭满 90 天且已 Tier 1 压缩过的超压缩在源码中明确标注not yet implemented--tier传非 1 会在入口直接报错compact.go#L134-L138。安全护栏--apply模式默认做双重校验——通过CheckEligibility检查资格并要求摘要必须比原文更短否则报错两处均可用--force绕过--force仅配合--id使用。压缩完成后原文会被归档为压缩快照compaction snapshotdescription 替换为摘要、design/notes/acceptance_criteria 清空并追加一条审计评论记录原体积 → 新体积。值得注意压缩属于写操作嵌入式模式下会被拦截需先启动 Dolt 服务模式见下文性能调优。何时压缩官方建议数据库超过 10MB 且积压大量已关闭老 Issue 时重大里程碑结束之后归档项目阶段之前。命令详情见 docs/cli-reference/compact.md。从历史恢复找回压缩前的内容bd restore压缩是优雅的不可逆衰减原文被丢弃因此 Beads 提供bd restore找回压缩前的原文bd restore bd-42 # 展示归档的压缩前内容只读 bd restore bd-42 --apply # 把原文写回该 Issue并把压缩层级回退源码 cmd/bd/restore.go 说明了完整决策链若 Issue 未压缩CompactionLevel 0直接报错提示只有压缩过的 Issue 才需要恢复优先读取归档快照GetCompactionSnapshot——这是权威的压缩前副本也是唯一可以安全写回的来源--apply通过RestoreFromSnapshot写回并递减压缩层级输出会显示compaction level N → M若无快照例如由旧版 bd 压缩、尚未引入快照归档回退到从 Dolt 版本历史尽力重构扫描全部历史提交选取内容总量最大的那个版本展示且只能展示、不能--apply提示语明确说明。因此能恢复的前提是数据库采用 Dolt 后端并保留了版本历史。详见 docs/cli-reference/restore.md。数据库检查schema 一览与原始 SQLbd info / bd sql# Schema 信息 bd info --schema --json # 原始数据库查询仅服务模式可用 bd sql SELECT * FROM issues LIMIT 5官方文档明确限定bd sql依赖 Dolt 服务模式bd dolt start见下文性能调优对默认的嵌入式数据库不可用——这是 Beads 有意为之的边界SQL 直查属于运维诊断手段日常读写一律走 CLI 语义接口。相关文档见 docs/cli-reference/sql.md 与 docs/cli-reference/info.md。数据库重定向多个 git clone 共享一个数据库.beads/redirect当多个 Agent 或 checkout 目录需要处理同一批 Issue 时与其复制数据库不如让次要 clone 通过重定向指向主 clone 的.beads# 在次要 clone 中执行 mkdir -p .beads echo ../main-clone/.beads .beads/redirect重定向文件里只允许写一行路径相对或绝对指向目标.beads目录。查看当前实际生效的数据库bd where # 输出实际使用的 .beads 位置含重定向来源信息 bd where --json源码层面的行为边界internal/beads/beads.goRedirectFileName redirect为约定文件名不跟随重定向链只支持单层跳转FollowRedirect只解析一级重定向必须直接指向真实的.beads目录目标目录必须存在且包含有效数据库重定向时保留来源目录的数据库身份dolt_database元数据在跳转前捕获。bd where的 JSON 输出源码 cmd/bd/where.go包含path生效的 .beads 目录、redirected_from如经由重定向则回填原始目录、prefixissue 前缀从 workspace YAML 或存储配置读取、database_path四个字段非常适合脚本排查到底连到了哪个库。官方给出的边界建议独立项目与长期维护的 fork 应当各自持有数据库而不是使用重定向git worktree 则完全不需要重定向——linked worktree 会自动发现仓库自身的.beads工作区详见 docs/reference/worktrees.md。可扩展数据库以 CLI 为稳定的集成边界对于 Dolt 后端项目Beads 推荐的扩展方式是把扩展状态放在 beads 数据库之外通过稳定的 CLI 接口连接# 为集成工作流查询 Issue bd list --json bd query statusopen AND priority2 --json # 直接 SQL 检查仅服务模式 bd sql SELECT id, title, status FROM issues LIMIT 5官方文档明确通过直接存储访问自建自定义表是遗留的 SQLite-only 模式只有仍在维护 SQLite 后端扩展的读者才需要参考仓库内的 examples/bd-example-extension-go/README.md 示例。审计数据生命周期事件的历史记录Beads 会在数据库中记录 Issue 生命周期事件供审计与恢复工作流使用。这是面向人的历史视图面向机器的已提交变更流则见 Events Journal。# 查看 Issue 当前状态 bd show bd-a1b2 --json # 查询单个 Issue 的近期事件仅服务模式 bd sql SELECT event_type, actor, created_at FROM events WHERE issue_id bd-a1b2 ORDER BY created_at DESC LIMIT 20典型事件类型包括issue.createdissue.updatedissue.closeddependency.addedsync.completed批量操作批量创建、批量更新、批量关闭批量创建从 JSONL 引导新库# 在源项目中 bd export -o issues.jsonl # 在新项目中把导出文件放到 .beads/issues.jsonl # 或配置的 import.path然后初始化 bd init --from-jsonl这里有一个值得理解的设计哈希 ID 由内容派生且稳定因此导入时已存在的 ID 走的是原地更新而非冲突——ID 相同即视为同一条 Issue 的更新。批量更新bd list --status open --priority 4 --json | \ jq -r .[].id | \ xargs -I {} bd update {} --priority 3批量关闭bd list --label sprint-1 --status open --json | \ jq -r .[].id | \ xargs -I {} bd close {} --reason Sprint complete两个批量管道都遵循同一模式bd list --json负责按筛选条件产出机器可读 ID 流jq提取 IDxargs逐条驱动bd update/bd close——把 CLI 当作幂等批处理执行器使用。集成访问MCP 服务器与边界约定Beads 推荐以 CLI 作为官方集成边界# 机器可读的 Issue 数据 bd show bd-a1b2 --json # 供自动化消费的 ready 工作队列 bd ready --json # 对活动 Dolt 数据库的直接 SQL 检查仅服务模式 bd sql SELECT id, priority, status FROM issues WHERE status ! closed两点明确的工程约束与 docs/reference/advanced.md 一致internal/下的存储包不是公开 Go API外部不得直接 importMCP 服务器 是同一边界之上的无状态适配器它把 MCP 调用翻译为bdCLI 调用并按工作目录把每次调用路由到正确的.beads工作区自身从不缓存或存储 Issue 数据。性能调优大数据库、多 Agent 与 CI/CD大数据库瘦身# 汇总老关闭 Issue见上文数据库压缩 bd admin compact --stats # 用 Dolt 垃圾回收回收磁盘空间 bd admin compact --dolt # 压缩 30 天前的 Dolt 提交先预览 bd compact --dry-run bd compact --force源码说明cmd/bd/compact.go#L743-L871--dolt会对.beads/dolt目录执行dolt gc --archive-level 0若外部dolt二进制过旧、不识别--archive-level会检测到 unknown-flag 错误并自动降级为纯dolt gc随后报告GC 前体积 → GC 后体积释放字节数--dry-run只做体积预览。关于提交压缩squash 旧提交当前实现的正确姿势是与压缩模式组合预览例如bd compact --auto --dry-run——因为compact命令要求--analyze、--apply、--auto三种模式中恰好指定一种源码 compact.go#L114-L132。多 Agent 并发Beads 通过 Dolt 服务模式承载多 Agent 并发访问事务隔离由服务端自动管理# 启动 Dolt 服务 bd dolt start # 检查服务健康 bd doctorCI/CD 优化在 CI/CD 环境中 Beads 默认使用嵌入式模式无需服务进程# 直接执行命令即可无需任何特殊参数 bd list嵌入式模式省去了服务进程的启动与连接开销适合一次性、串行的流水线任务需要跨进程并发或 SQL 直查时再切换 Dolt 服务模式。小结本文覆盖的每一项高级能力都有清晰的适用前提bd rename/bd rename-prefix解决 ID 可读性与损坏库收敛bd duplicates --auto-merge用结构权重 引用数 最小 ID的优先级自动选择合并目标bd admin compact的四种模式与bd restore的快照/历史两级恢复构成压缩—回退闭环.beads/redirect与bd where支撑多 clone 共享库bd sql、bd list --json等则以 CLI 为稳定边界对外开放数据。执行任何写操作前建议先用--dry-run与--json输出做完整预演再在 Dolt 版本历史的保护下放心落地。进一步阅读docs/cli-reference/compact.md · docs/cli-reference/restore.md · docs/cli-reference/rename-prefix.md · docs/cli-reference/where.md · docs/reference/worktrees.md · docs/reference/events-journal.md · docs/integrations/mcp-server.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 高级功能实战指南：Issue 重命名、去重合并、数据库压缩与多工作区管理
Beads 高级功能实战指南Issue 重命名、去重合并、数据库压缩与多工作区管理【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本篇技术指南围绕 Beads 官方文档 docs/reference/advanced.md 展开系统讲解 Beads面向编码 Agent 的记忆增强型 Issue 管理工具的进阶运维能力单条与批量 ID 重命名、重复 Issue 的检测与自动合并、旧 Issue 压缩与历史恢复、跨 git clone 的数据库重定向以及针对大数据库、多并发 Agent 与 CI/CD 场景的性能调优。阅读本文后你将掌握每条高级命令的完整参数、底层行为边界与可验证的源码依据能够安全地在生产数据库上执行这些低频但高风险的维护操作。重命名 Issue保留引用关系的安全改名bd rename当需要把晦涩的哈希 ID 换成可读、好记的 ID 时例如把bd-w382l改为bd-dolt使用bd rename。命令支持--dry-run预演且重命名是全库一致的——不仅仅是改主键本身bd rename bd-42 bd-new-id bd rename bd-42 bd-new-id --dry-run # 预览将发生的改动根据 cmd/bd/rename.go 的实现一次bd rename会完整更新该 Issue 的主 ID通过存储层的UpdateIssueID原子改写指向旧 ID 的全部依赖关系dependency edges其他 Issue 文本字段中的引用——updateReferencesInAllIssues会遍历全库用\b旧ID\b词边界正则逐一替换 title、description、design、notes、acceptance_criteria 五个文本字段见 rename.go#L104-L152标签、评论与事件记录。需要留意两个硬性校验源码 rename.go#L56-L84新旧 ID 不能相同新 ID 必须匹配^[a-z]-[a-zA-Z0-9._-]$即合法前缀-后缀格式且新 ID 不得已存在于库中。单条改名的完整用法可参考 docs/cli-reference/rename.md。前缀重命名与损坏库修复bd rename-prefixbd rename-prefix把数据库中每一个 Issue的前缀统一替换典型场景是把冗长的knowledge-work-缩短为kw-bd rename-prefix kw- --dry-run # 预览而不实际应用 bd rename-prefix kw- # 所有 knowledge-work-* ID 变为 kw-*该命令会同时更新所有 Issue ID 以及全部字段中的文本引用。--dry-run会打印每条旧ID - 新ID的样本改动与剩余条数非 dry-run 时源码renamePrefixInDB用\b旧前缀-(\d)\b正则对所有文本字段做整体替换最后把配置项issue_prefix写为新值见 cmd/bd/rename_prefix.go#L422-L469。前缀合法性规则源码validatePrefixrename_prefix.go#L223-L240规则说明允许字符仅小写字母、数字、连字符^[a-z][a-z0-9-]*$首字符必须以字母开头尾字符必须以连字符结尾如kw-、work-禁止情形不能为空不能只是-不能以-开头或出现--多前缀损坏库的修复如果数据库因异常如半迁移混入了多个前缀bd rename-prefix会先通过detectPrefixes统计每个前缀下的 Issue 数一旦检测到多于一个前缀就必须用--repair收敛bd rename-prefix mtg- --repair # 将多个前缀合并为 mtg- bd rename-prefix team- --dry-run # 先预览再动手repairPrefixes的实现细节rename_prefix.go#L261-L398前缀已正确等于目标前缀的 Issue 保持不变前缀错误的 Issue 会基于内容哈希重新生成 8 位十六进制 IDgenerateRepairHashID使用 SHA-256 对 title/description/actor/createdAt 取前 4 字节并在批内通过usedIDs防碰撞、失败时用 nonce 重试随后对所有文本字段做引用替换并调用UpdateIssueID落库。值得一提的是从源码注释GH#4827、GH#5135 相关可以看出实现还处理了一种特殊情形配置里的issue_prefix与行上实际前缀不一致半迁移库时命令会只修复配置单元、不重写任何 ID避免产生atlas-atlas-*这样的双重前缀。完整命令文档见 docs/cli-reference/rename-prefix.md。重复检测与合并去重不再手工核对bd duplicates / bd duplicate内容完全相同的 Issuetitle、description、design、acceptance criteria 全部一致会随着多 Agent 协作不断累积。bd duplicates负责发现并收敛它们bd duplicates # 报告重复组与建议动作 bd duplicates --dry-run # 预览 --auto-merge 将执行的操作 bd duplicates --auto-merge # 自动合并每一组重复分组原理源码 cmd/bd/duplicates.go#L194-L224findDuplicateGroups以contentKey{title, description, design, acceptanceCriteria, status}为分组键——也就是说状态必须一致才会进入同一组开 Issue 配开 Issue、关 Issue 配关 Issue从实现看当前版本只把未关闭非closed的 Issue 纳入建组openIssuesOf并以status字段保证组内状态一致。合并目标选择每组中应该留下谁由chooseMergeTarget按三级优先级裁决duplicates.go#L273-L330结构权重最高dependentCount*3 dependsOnCount。子 Issuedependents权重 ×3因为丢弃带子 Issue 的父 Issue 会让子节点孤立灾难性而丢失 depends-on 链接是可恢复的文本引用数其他 Issue 描述/备注中提到的次数countReferences字典序最小 ID作为稳定的最终平局裁决。--auto-merge对每组执行三步performMergeduplicates.go#L375-L452把重复 Issue 的子 Issue 重新挂到合并目标下先RemoveDependency旧父子链再AddDependency新父子链避免子节点孤儿化以原因Duplicate of target关闭重复 Issue为每个重复 Issue 与目标之间建立related类型的依赖链接。若只想手动标记单个已知重复用bd duplicate bd-42 --of bd-41 # 把 bd-42 作为 bd-41 的重复关闭关闭是永久的但 Beads 基于 Dolt 的版本历史会保留原始状态合并后建议用bd show bd-41与bd dep tree bd-41复核结果。文本输出与 JSON 输出含suggested_action、merge_results都能用于脚本化审计详见 docs/cli-reference/duplicates.md 与 docs/cli-reference/duplicate.md。数据库压缩给老 Issue 做语义瘦身bd admin compact数据库体积膨胀主要来自长期未关闭、内容冗长的历史 Issue。Beads 提供了四类压缩模式源码 cmd/bd/compact.go# 查看压缩统计 bd admin compact --stats # 导出候选清单30 天关闭的 Issue供 Agent 人工审核 bd admin compact --analyze --json # 应用 Agent 生成的摘要 bd admin compact --apply --id bd-42 --summary summary.txt # 立即删除高危 bd admin cleanup --force各模式行为与参数约束均可加--json输出机器可读结果模式作用关键约束--stats输出 Tier 1/Tier 2 候选数与总体积只读无需 API Key--analyze导出候选 Issue 的完整内容含--id单条模式与--limit只读无需 API Key--apply接受 Agent 编写的摘要并落库必须同时指定--id与--summary--summary -从 stdin 读取--autoAI 自动压缩需ANTHROPIC_API_KEY、MINIMAX_API_KEY或配置中的ai.api_key--dolt对.beads/dolt目录执行 Dolt GC 回收磁盘需本机 PATH 中存在doltTier 分级Tier 1 为关闭满 30 天、目标压缩率约 70%的语义压缩也是当前唯一实现的层级Tier 2关闭满 90 天且已 Tier 1 压缩过的超压缩在源码中明确标注not yet implemented--tier传非 1 会在入口直接报错compact.go#L134-L138。安全护栏--apply模式默认做双重校验——通过CheckEligibility检查资格并要求摘要必须比原文更短否则报错两处均可用--force绕过--force仅配合--id使用。压缩完成后原文会被归档为压缩快照compaction snapshotdescription 替换为摘要、design/notes/acceptance_criteria 清空并追加一条审计评论记录原体积 → 新体积。值得注意压缩属于写操作嵌入式模式下会被拦截需先启动 Dolt 服务模式见下文性能调优。何时压缩官方建议数据库超过 10MB 且积压大量已关闭老 Issue 时重大里程碑结束之后归档项目阶段之前。命令详情见 docs/cli-reference/compact.md。从历史恢复找回压缩前的内容bd restore压缩是优雅的不可逆衰减原文被丢弃因此 Beads 提供bd restore找回压缩前的原文bd restore bd-42 # 展示归档的压缩前内容只读 bd restore bd-42 --apply # 把原文写回该 Issue并把压缩层级回退源码 cmd/bd/restore.go 说明了完整决策链若 Issue 未压缩CompactionLevel 0直接报错提示只有压缩过的 Issue 才需要恢复优先读取归档快照GetCompactionSnapshot——这是权威的压缩前副本也是唯一可以安全写回的来源--apply通过RestoreFromSnapshot写回并递减压缩层级输出会显示compaction level N → M若无快照例如由旧版 bd 压缩、尚未引入快照归档回退到从 Dolt 版本历史尽力重构扫描全部历史提交选取内容总量最大的那个版本展示且只能展示、不能--apply提示语明确说明。因此能恢复的前提是数据库采用 Dolt 后端并保留了版本历史。详见 docs/cli-reference/restore.md。数据库检查schema 一览与原始 SQLbd info / bd sql# Schema 信息 bd info --schema --json # 原始数据库查询仅服务模式可用 bd sql SELECT * FROM issues LIMIT 5官方文档明确限定bd sql依赖 Dolt 服务模式bd dolt start见下文性能调优对默认的嵌入式数据库不可用——这是 Beads 有意为之的边界SQL 直查属于运维诊断手段日常读写一律走 CLI 语义接口。相关文档见 docs/cli-reference/sql.md 与 docs/cli-reference/info.md。数据库重定向多个 git clone 共享一个数据库.beads/redirect当多个 Agent 或 checkout 目录需要处理同一批 Issue 时与其复制数据库不如让次要 clone 通过重定向指向主 clone 的.beads# 在次要 clone 中执行 mkdir -p .beads echo ../main-clone/.beads .beads/redirect重定向文件里只允许写一行路径相对或绝对指向目标.beads目录。查看当前实际生效的数据库bd where # 输出实际使用的 .beads 位置含重定向来源信息 bd where --json源码层面的行为边界internal/beads/beads.goRedirectFileName redirect为约定文件名不跟随重定向链只支持单层跳转FollowRedirect只解析一级重定向必须直接指向真实的.beads目录目标目录必须存在且包含有效数据库重定向时保留来源目录的数据库身份dolt_database元数据在跳转前捕获。bd where的 JSON 输出源码 cmd/bd/where.go包含path生效的 .beads 目录、redirected_from如经由重定向则回填原始目录、prefixissue 前缀从 workspace YAML 或存储配置读取、database_path四个字段非常适合脚本排查到底连到了哪个库。官方给出的边界建议独立项目与长期维护的 fork 应当各自持有数据库而不是使用重定向git worktree 则完全不需要重定向——linked worktree 会自动发现仓库自身的.beads工作区详见 docs/reference/worktrees.md。可扩展数据库以 CLI 为稳定的集成边界对于 Dolt 后端项目Beads 推荐的扩展方式是把扩展状态放在 beads 数据库之外通过稳定的 CLI 接口连接# 为集成工作流查询 Issue bd list --json bd query statusopen AND priority2 --json # 直接 SQL 检查仅服务模式 bd sql SELECT id, title, status FROM issues LIMIT 5官方文档明确通过直接存储访问自建自定义表是遗留的 SQLite-only 模式只有仍在维护 SQLite 后端扩展的读者才需要参考仓库内的 examples/bd-example-extension-go/README.md 示例。审计数据生命周期事件的历史记录Beads 会在数据库中记录 Issue 生命周期事件供审计与恢复工作流使用。这是面向人的历史视图面向机器的已提交变更流则见 Events Journal。# 查看 Issue 当前状态 bd show bd-a1b2 --json # 查询单个 Issue 的近期事件仅服务模式 bd sql SELECT event_type, actor, created_at FROM events WHERE issue_id bd-a1b2 ORDER BY created_at DESC LIMIT 20典型事件类型包括issue.createdissue.updatedissue.closeddependency.addedsync.completed批量操作批量创建、批量更新、批量关闭批量创建从 JSONL 引导新库# 在源项目中 bd export -o issues.jsonl # 在新项目中把导出文件放到 .beads/issues.jsonl # 或配置的 import.path然后初始化 bd init --from-jsonl这里有一个值得理解的设计哈希 ID 由内容派生且稳定因此导入时已存在的 ID 走的是原地更新而非冲突——ID 相同即视为同一条 Issue 的更新。批量更新bd list --status open --priority 4 --json | \ jq -r .[].id | \ xargs -I {} bd update {} --priority 3批量关闭bd list --label sprint-1 --status open --json | \ jq -r .[].id | \ xargs -I {} bd close {} --reason Sprint complete两个批量管道都遵循同一模式bd list --json负责按筛选条件产出机器可读 ID 流jq提取 IDxargs逐条驱动bd update/bd close——把 CLI 当作幂等批处理执行器使用。集成访问MCP 服务器与边界约定Beads 推荐以 CLI 作为官方集成边界# 机器可读的 Issue 数据 bd show bd-a1b2 --json # 供自动化消费的 ready 工作队列 bd ready --json # 对活动 Dolt 数据库的直接 SQL 检查仅服务模式 bd sql SELECT id, priority, status FROM issues WHERE status ! closed两点明确的工程约束与 docs/reference/advanced.md 一致internal/下的存储包不是公开 Go API外部不得直接 importMCP 服务器 是同一边界之上的无状态适配器它把 MCP 调用翻译为bdCLI 调用并按工作目录把每次调用路由到正确的.beads工作区自身从不缓存或存储 Issue 数据。性能调优大数据库、多 Agent 与 CI/CD大数据库瘦身# 汇总老关闭 Issue见上文数据库压缩 bd admin compact --stats # 用 Dolt 垃圾回收回收磁盘空间 bd admin compact --dolt # 压缩 30 天前的 Dolt 提交先预览 bd compact --dry-run bd compact --force源码说明cmd/bd/compact.go#L743-L871--dolt会对.beads/dolt目录执行dolt gc --archive-level 0若外部dolt二进制过旧、不识别--archive-level会检测到 unknown-flag 错误并自动降级为纯dolt gc随后报告GC 前体积 → GC 后体积释放字节数--dry-run只做体积预览。关于提交压缩squash 旧提交当前实现的正确姿势是与压缩模式组合预览例如bd compact --auto --dry-run——因为compact命令要求--analyze、--apply、--auto三种模式中恰好指定一种源码 compact.go#L114-L132。多 Agent 并发Beads 通过 Dolt 服务模式承载多 Agent 并发访问事务隔离由服务端自动管理# 启动 Dolt 服务 bd dolt start # 检查服务健康 bd doctorCI/CD 优化在 CI/CD 环境中 Beads 默认使用嵌入式模式无需服务进程# 直接执行命令即可无需任何特殊参数 bd list嵌入式模式省去了服务进程的启动与连接开销适合一次性、串行的流水线任务需要跨进程并发或 SQL 直查时再切换 Dolt 服务模式。小结本文覆盖的每一项高级能力都有清晰的适用前提bd rename/bd rename-prefix解决 ID 可读性与损坏库收敛bd duplicates --auto-merge用结构权重 引用数 最小 ID的优先级自动选择合并目标bd admin compact的四种模式与bd restore的快照/历史两级恢复构成压缩—回退闭环.beads/redirect与bd where支撑多 clone 共享库bd sql、bd list --json等则以 CLI 为稳定边界对外开放数据。执行任何写操作前建议先用--dry-run与--json输出做完整预演再在 Dolt 版本历史的保护下放心落地。进一步阅读docs/cli-reference/compact.md · docs/cli-reference/restore.md · docs/cli-reference/rename-prefix.md · docs/cli-reference/where.md · docs/reference/worktrees.md · docs/reference/events-journal.md · docs/integrations/mcp-server.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考