Beads 架构解析：基于 Dolt 版本化存储的工作图数据库设计与同步机制

Beads 架构解析基于 Dolt 版本化存储的工作图数据库设计与同步机制【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 是一款为编码 Agent 提供持久记忆的依赖感知型问题跟踪系统其全部数据都存放在Dolt——一个原生提供 git 语义分支、合并、diff、push、pull的版本化 SQL 数据库中。本文以 docs/architecture/index.md 为骨架结合 docs/architecture/dolt.md 及仓库源码internal/storage、internal/types、cmd/bd系统讲解 Beads 的存储布局、数据模型、读写与同步路径、两种部署模式嵌入式/服务器模式、目录结构、恢复模型与设计取舍帮助读者完整理解 Beads 如何用版本化 SQL为多 Agent 协作提供离线优先、冲突友好的持久工作记忆。总体架构Dolt 作为唯一存储后端Beads 的架构核心是一句话Dolt 是唯一存储后端sole storage backend。Dolt 是一个版本受控的 SQL 数据库在数据库层面原生提供类 git 语义branch、merge、diff、push、pull。Beads 不自己实现数据文件格式而是把全部 issue 数据放进 Dolt从而免费获得完整版本历史、字段级合并与原生分支能力。从 docs/architecture/index.md 中的架构图可见两个核心组成部分Dolt 数据库本地默认以嵌入式模式运行进程内无独立服务数据落在.beads/embeddeddolt/多写入者场景多 Agent、编排器切换为服务器模式连接一个运行中的dolt sql-server数据落在.beads/dolt/。Dolt 远程仓库远程通过bd dolt push/bd dolt pull与 DoltHub、S3、GCS 等远程进行同步与备份支持离线开发、异地恢复。交互链路很简单用户通过bd create/bd update写入数据库通过bd list/bd show读取。每一次写入都会自动提交到 Dolt 历史形成数据库层面的完整版本控制恢复也简单——用bd dolt pull从远程拉取或用bd backup restore从 Dolt 原生备份恢复。为什么选择 Dolt原文档列出六条核心理由可直接作为选型依据版本化 SQL完整 SQL 查询 原生版本控制单元格级合并Cell-level merge并发修改在字段层面自动合并而非整文件覆盖多写入者服务器模式支持并发 Agent 同时写入原生分支Dolt 分支独立于 git 分支离线可用所有查询都在本地数据库执行可移植bd export生成 JSONL 用于迁移与互操作。在 docs/architecture/index.md 的Design Decisions一节中原文档进一步对比了替代方案相比普通 SQLite二进制级合并冲突和 JSONL查询慢Dolt 同时提供快速 SQL 查询与正确的合并语义。从源码看这一选型贯穿整个存储层。backend/backend.go中将存储引擎接口显式命名为DoltStoragetype DoltStorage storage.DoltStorage并注明该名称是历史性的——Dolt 存储是其首批实现——但契约本身与后端无关说明整个引擎接口是为 Dolt 语义设计的且对外暴露了可插拔的后端注册机制backend.Register(name, backend)注册名dolt被保留。仓库内internal/storage/下约 980 个 Go 文件、150 个 SQL 文件全部服务于这套存储实现。数据模型五类记录与内容派生 ID数据库存储五类记录Issues——即 beads 本身一个可跟踪的工作单元Dependencies——类型化边如blocks、parent-child、related、discovered-fromLabels——标签Comments——评论Events——审计追踪audit trail。bd ready正是基于这些记录尤其是依赖关系计算可认领工作前沿claimable frontier打开且没有打开状态阻塞者的 beads。概念模型beads、dependencies、ready work、molecules详见 docs/core-concepts/index.md。哈希 ID并发写入者永不冲突Issue ID 是内容派生的哈希如bd-a1b2而非自增序号。这样并发写入者不会产生 ID 冲突也无需中央 ID 协调。设计细节见 docs/core-concepts/hash-ids.md。源码印证了这一机制。internal/types/id_generator.go中的GenerateHashID从以下输入计算 SHA-256// internal/types/id_generator.go func GenerateHashID(prefix, title, description string, created time.Time, workspaceID string) string { h : sha256.New() h.Write([]byte(title)) h.Write([]byte(description)) h.Write([]byte(created.Format(time.RFC3339Nano))) h.Write([]byte(workspaceID)) hash : hex.EncodeToString(h.Sum(nil)) return hash }标题主标识符、描述、创建时间戳RFC3339Nano 精度、工作区 ID 共同参与哈希其中工作区 ID 用于防止跨工作区冲突默认取 6 字符短哈希如bd-a3f2dd碰撞时渐进扩展到 7、8 字符bd-a3f2dda、bd-a3f2dda8代码注释给出了碰撞概率估算6 字符24 位下 1000 个 issue 约 2.94% 概率触发扩展10000 个 issue 约 94.9% 概率扩展到 7–8 字符该渐进策略优化了常见场景约 97% 停留在 6 字符。层级 ID 由GenerateChildID(parentID, childNumber)生成格式为parent.N如bd-a3f8e9.1、bd-a3f8e9.1.2最大嵌套深度 3 层。对碰撞概率的生日悖论分析可参考仓库中的 engdocs/COLLISION_MATH.md。Issue Schema核心字段与工作流字段组原文档给出了bd exportJSONL 中每条 issue 的核心字段表现完整保留并补充说明字段类型说明idstring唯一哈希 ID如bd-a1b2titlestring标题必填descriptionstring详细描述可选designstring设计说明可选acceptance_criteriastring验收标准可选notesstring附加说明可选statusstringopen、in_progress、blocked、deferred、closed、pinned、hooked默认open可通过status.custom配置键扩展priorityint0–40 关键critical4 积压backlogissue_typestringbug、feature、task、epic、chore、decision、message、molecule、gate、spike、story、milestone默认taskassigneestring指派的用户/Agent可选estimated_minutesint预估耗时分钟可选created_at/updated_atRFC3339创建与最后修改时间created_bystring创建者可选closed_at/close_reasonRFC3339 / string关闭时设置可选external_refstring外部引用如gh-9、jira-ABC可选metadataJSON任意扩展数据见 docs/core-concepts/metadata.mdlabels[]string附加标签可选dependencies[]Dependency指向其他 issue 的类型化边可选comments[]Comment讨论线程可选Issue 还携带若干工作流层字段组调度类due_at、defer_until、认领租约类lease_expires_at、heartbeat_at、门控类await_type、await_id、timeout、molecule/wisp 类ephemeral、mol_type、bonded_from。internal/types/types.go中的Issue结构体与上述字段一一对应并揭示了几个导出字段表未展开的实现细节ContentHash string \json:-——对 issue 规范内容的 SHA-256用于变更检测永不出现在导出中SourceRepo、IDPrefixjson:-——内部路由字段不随 git 同步RowVersion int64 \json:-——不透明乐观并发令牌封装 issue/wisp 行的row_lock 单元格每次状态/归属变更写入时被引擎重写供 Go 调用方做等值比较仅可比较、不可排序或解释内部字段content_hash、source_repo、id_prefix均不进入导出json:-与文档Internal fields never appear in exports一致。Schema 默认保持稳定集成方、编排器或团队专属数据应优先使用metadata字段任意合法 JSON 均可存放而不是提议新增一等字段。这一边界在仓库 engdocs/PROJECT_CHARTER.mdschema boundary 一节中有明确约束。状态与类型的合法取值集合也可以在 backend/types.go 中看到完整枚举StatusOpen/InProgress/Blocked/Deferred/Closed/Hooked/Pinned以及TypeBug/Chore/Decision/Epic/Event/Feature/Gate/Message/Milestone/Molecule/Spike/Story/Task。数据流写入、读取与同步三条路径原文档给出了三条核心数据流这里完整保留写入路径Write PathUser runs bd create → Dolt database updated → Auto-committed to Dolt history读取路径Read PathUser runs bd list → Dolt SQL query → Results returned immediately同步路径Sync PathUser runs bd dolt push → Commits pushed to Dolt remote User runs bd dolt pull → Remote commits fetched and mergedDolt 远程可以位于 DoltHub、S3、GCS、文件系统路径甚至是你现有的 git 远程——issue 历史挂在refs/dolt/data下与代码分支相互独立。这意味着同一个 git 仓库可以同时承载源码与 issue 历史。跨仓库场景还可以通过**联邦federation**在 peer 之间直接交换 beads详见 docs/multi-agent/federation.md临时的wisps挥发性 molecule默认被排除在联邦推送之外因此执行痕迹不会进入共享历史详见 docs/workflows/wisps.md。跨机器同步注意事项在多个机器/克隆之间工作时原文档给出三条黄金规则切换机器前务必先同步bd dolt push # 离开前推送变更在新机器上创建 issue 前先拉取bd dolt pull # 先在新机器上拉取变更 bd create New issue避免并行编辑——如果两台机器在未同步的情况下同时创建 issueDolt 的单元格级合并会自动处理大多数冲突。多机器工作流中防数据丢失的完整预案Pattern A5/C3见 docs/recovery/sync-failures.md。该 runbook 给出了标准修复序列bd dolt stop→ 检查/清理锁文件 →cp -r .beads .beads.backup备份 →bd doctor --dry-run预览 →bd doctor --fix修复 → 重启服务器 →bd dolt push/bd doctor验证。需要特别澄清的一点来自 docs/core-concepts/sync-concepts.md.beads/issues.jsonl只是一个被动导出供查看器、互换、迁移和备份使用它不是数据库、不是同步协议、更不是备份。不要用常规的bd import .beads/issues.jsonl替代bd dolt pull——JSONL 导入是 upsert-only 语义无法推断导出中缺失的记录是被删除、修剪还是从未导出过。部署模式嵌入式 vs 服务器模式Beads 提供两种 Dolt 部署模式选择依据是写入者数量模式初始化命令数据位置写入者嵌入式默认bd init.beads/embeddeddolt/单写入者文件锁服务器模式bd init --server.beads/dolt/多写入者并发嵌入式模式无需服务器嵌入式模式是默认行为bd init不带任何 flagDolt 以进程内方式运行单写入者数据在.beads/embeddeddolt/——没有独立服务器进程也不需要单独安装 Dolt。模式选择持久化在.beads/metadata.json中。bd create CI-generated issue bd dolt push原文档特别指出除了单人使用外嵌入式模式天然适合CI/CD 管道Jenkins、GitHub ActionsDocker 容器临时环境ephemeral environments不应残留后台进程的脚本。从 docs/architecture/dolt.md 可以确认bd二进制内嵌了 Dolt 引擎版本由go.mod决定当前对应上游 v2.2.0 tag因此嵌入式模式零运维无服务器、无端口、无 PID 文件。嵌入式模式通过文件锁强制单写入者——若出现 database is locked 错误说明有并发访问需求应切换到服务器模式。服务器模式多写入者 / 编排器服务器模式连接一个运行中的dolt sql-server支持多客户端并发访问# 启动服务器编排器侧 gt dolt start # 或手动启动 cd ~/.dolt-data/beads dolt sql-server --port 3307# 以服务器模式初始化 bd init --server # 或通过环境变量切换 export BEADS_DOLT_SERVER_MODE1# .beads/config.yaml (server mode settings) dolt: mode: server host: 127.0.0.1 port: 3307 user: root连接参数可通过 flag 或环境变量配置完整对照见 docs/architecture/dolt.mdFlag环境变量默认值--server-hostBEADS_DOLT_SERVER_HOST127.0.0.1--server-portBEADS_DOLT_SERVER_PORT3307--server-socketBEADS_DOLT_SERVER_SOCKET无默认走 TCP--server-userBEADS_DOLT_SERVER_USERrootBEADS_DOLT_PASSWORD无Unix 域套接字使用--server-socket可通过 Unix socket 而非 TCP 连接。这能避免并发项目之间的端口冲突在沙箱环境如 Claude Code中尤其有用——文件级访问控制比网络白名单更简单。注意 Dolt 服务器必须以dolt sql-server --socket path方式启动且 socket 模式不支持自动启动。何时切换到服务器模式多个 Agent 同时写入编排器多机架multi-rig部署与远程 peer 进行联邦federation。共享服务器模式Shared Server可选的高级部署形态在所有项目之上运行单个Dolt 服务器~/.beads/shared-server/各项目通过前缀隔离的独立数据库共享它。启用方式# 通过 config.yaml 键为本项目启用 bd config set dolt.shared-server true # 或通过环境变量机器级启用 export BEADS_DOLT_SHARED_SERVER1 # 或在 init 时启用 bd init --prefix myproject --shared-server共享模式的好处项目间无端口冲突单一服务器跑在 3308 端口避开编排器的 3307、资源占用低一个进程替代多个、数据库自动隔离每个项目使用自己的数据库名。关键约束共享服务器上的每个项目必须使用唯一前缀数据库名——若两个项目恰好同前缀项目身份检查会检测到不匹配并拒绝连接防止静默数据损坏。配置键dolt.shared-server的合法性校验仅接受true/false可在 internal/config/yaml_config.go 中找到。完整机制见 docs/architecture/dolt.md 的 Shared Server Mode 一节。多克隆场景的竞态风险原文档以警告形式强调了一个关键坑同一仓库的多个 git 克隆同时执行同步操作时push/pull 期间可能发生竞态条件。这在以下场景尤其常见多 Agent AI 工作流多个 Claude/GPT 实例拥有多个 checkout 的开发者工作站基于 worktree 的开发工作流。预防措施在克隆之间切换前停止 Dolt 服务器bd dolt stop服务器模式下 Dolt 原生支持 worktree自动化工作流使用嵌入式模式。竞态问题的专项排查Pattern B2见 docs/recovery/sync-failures.md。目录布局.beads/里有什么原文档给出了完整的目录布局数据位置随模式而异.beads/ ├── embeddeddolt/ # Dolt 数据库嵌入式模式默认— gitignored ├── dolt/ # Dolt 数据库服务器模式— gitignored ├── dolt-server.pid # 服务器模式运行时文件.pid、.log、.port— gitignored ├── issues.jsonl # 被动 JSONL 导出供查看器与数据互换使用 ├── metadata.json # 后端配置 — 受 git 跟踪 └── config.yaml # 项目配置可选— 受 git 跟踪要点解读只有数据库目录随模式二选一真正持有 issue 数据其余都是配置、运行时状态或派生导出bd init会写入.beads/.gitignore把数据库和运行时文件排除在 git 之外服务器模式运行时文件直接位于.beads/下dolt-server.pid、dolt-server.log、dolt-server.portcmd/bd的测试与 doctor 修复逻辑中对这些文件名有直接引用例如 cmd/bd/doctor/fix/remotes.go 处理 stale 的dolt-server.portissues.jsonl是导出而非数据库本体详见前文同步路径一节的澄清metadata.json记录后端类型与模式选择bd init --server的选择就持久化在这里。恢复模型版本控制让恢复变简单Dolt 的版本控制使数据恢复路径异常直接原文档的三条主恢复路径完整保留数据库丢了→ 从 Dolt 远程拉取bd dolt pull有备份→ 恢复它bd backup restore [path] --force合并冲突→ Dolt 原生处理单元格级合并备份用bd backup init目标可为文件系统路径或 DoltHub创建、bd backup sync推送。Dolt 原生备份保留完整提交历史JSONL 导出不保留。bd export不能替代这一流程——JSONL 只含 issues 表记录不含 Dolt 分支、完整提交历史、工作集状态或其他表。通用恢复序列以下序列可解决大多数已报告问题详细流程见 docs/recovery/index.mdbd dolt stop # 停止 Dolt 服务器防止竞态条件 git worktree prune # 清理孤儿 worktree bd dolt pull # 从 Dolt 远程拉取 bd dolt start # 重启服务器谨慎使用bd doctor --fixbd doctor --fix是强力工具使用前务必先备份与预览先备份cp -r .beads .beads.backup预览变更bd doctor --dry-run—— 显示将要修复的内容而不实际修改查看诊断bd doctor不带 flag—— 仅诊断不做任何修改然后修复bd doctor --fix—— 或bd doctor --fix -i逐条确认每个修复为何需要谨慎--fix可能会删除它判定为环形的依赖包括合法的父子关系。只有当你确信被标记的依赖确实无效时才使用--fix-child-parent。其他诊断工具bd blocked—— 检查哪些 issue 被阻塞及原因bd show issue-id—— 检查某个 issue 的具体状态。bd doctor的功能面比这里展示的更广。从 docs/cli-reference/doctor.md 可见其检查项包括.beads/目录存在性、数据库版本与迁移状态、Schema 兼容性必需的表和列齐全、哈希 ID 与顺序 ID、CLI 版本、git hooks、.gitignore状态等并支持--perf性能诊断、--deep全图完整性验证如父子依赖指向存在的 issue、依赖引用有效、epic 完整性、molecule 结构等、--server服务器模式健康检查等多种模式。专项恢复 runbook 还包括数据库损坏docs/recovery/database-corruption.md症状命令报错、database is locked、issue 缺失、状态不一致预防让 Dolt 服务器统一处理同步、系统关机前bd dolt stop、定期bd doctor合并冲突docs/recovery/merge-conflicts.md症状bd dolt pull报冲突、克隆间 issue 状态不一致修复备份 →bd doctor→bd doctor --fix→bd list/bd stats验证 →bd dolt push预防工作会话前后用bd dolt pull/bd dolt push同步避免无服务器时多克隆并发修改。存储空间回收与维护数据库增长到一定程度后需要维护见 docs/architecture/dolt.md 与 docs/cli-reference/flatten.mdbd prune—— 永久删除已关闭的非临时 beads 以回收存储、缩小自动导出体积bd purge对临时 beadswisps、瞬时 molecule做同样的事两者都需要--force才真正执行bd prune --older-than 30d # 预览 30 天的已关闭 beads bd prune --older-than 30d --force # 删除它们 bd prune --older-than 90d --dry-run # 带统计的详细预览 bd purge --force # 删除所有已关闭的临时 beads引用感知保护bd prune自动跳过 ID 出现在任何 open/in-progress bead 的 description、notes 或 comments 中的已关闭 beads防止误删仍被下游引用的 ADR、decision、verification beads--ignore-references可覆盖此行为bd flatten—— 历史压扁squash把全部 Dolt 提交历史合并为单个提交用于.beads/dolt目录过大、不需要提交级历史时间旅行的场景bd flatten --dry-run # 预览显示提交数与磁盘占用 bd flatten --force # 真正压扁全部历史bd admin—— 管理命令集cleanup删除已关闭 issue、compact压缩历史、reset完全重置针对数据库的定向操作见 docs/cli-reference/admin.md。版本锁定为什么固定 Dolt 2.2.0值得单独说明的一个运维细节来自 docs/architecture/dolt.mdBeads 将 Dolt 固定为 2.2.0。Dolt 2.3.02026-08-13 发布存在CALL DOLT_RESET(--hard)回归——约百分之几的新建数据库该存储过程不可用任何会话任何连接都报Error 1105 (HY000): context canceled且其余一切看似正常SELECT 1、DOLT_CLEAN()、DOLT_CHECKOUT(.)、DOLT_COMMIT()均正常损坏直到需要硬重置时才暴露。实测数据新建库后立即调用该过程Dolt 版本硬重置损坏的新建库比例2.1.80 / 402.2.00 / 602.3.03 / 602.3.13 / 100由于bd flatten、bd admin compact的 Dolt 历史压缩都以把main硬重置到临时分支收尾bd dolt pull/bd sync的 merge-settle 路径在放弃合并时也会回退到硬重置因此该回归会直接影响这些维护操作。判定某数据库是否受影响可在干净工作集上依次执行dolt sql -q SELECT * FROM dolt_status # 1. 确认工作集干净 dolt sql -q SELECT 1 # 2. 对照组必须成功 dolt sql -q CALL DOLT_RESET(--hard) # 3. 健康库上应为 no-op第 2 步成功而第 3 步报Error 1105 (HY000): context canceled即为受影响。该损坏驻留在运行中的服务器进程而非磁盘上重启dolt sql-server可暂时清除但可靠修复仍是迁移到固定版本。此外上游releases/latestURL 解析的是最近创建的 release 而非最高版本可能倒退因此钉版而非跟踪 latest 是双重理由下的工程决策。设计决策与取舍为什么用 Dolt 而非云服务器Beads 面向offline-first、local-first开发设计Dolt 服务器运行在本地——无云依赖、无停机、无厂商锁定在飞机上或受限网络内功能完整。这一取向与编码 Agent 的记忆定位完全一致工作记忆应随身携带而不是依赖外部可达性。取舍清单原文档给出的 Benefit/Trade-off 对照收益代价离线可用无实时协作版本化数据库并发写入者需要服务器模式单元格级合并需要初始配置本地优先的速度手动同步到远程SQL 查询依赖 Dolt 存储引擎何时不适合用 Beads大型团队10 人—— 基于 git 的同步在高频并发编辑下扩展性不佳非开发者—— 需要 git 与命令行熟练度实时协作—— 无实时更新需要显式同步富媒体附件—— 面向文本型 issue 跟踪设计。这类场景可考虑 GitHub Issues、Linear 或 Jira。这些边界也在仓库 engdocs/PROJECT_CHARTER.md 中有正式声明。相关文档导航继续深入阅读的入口全部为仓库内路径docs/core-concepts/index.md —— 概念模型beads、依赖、ready work、moleculesdocs/core-concepts/sync-concepts.md —— 跨机器同步、线格式与反模式docs/architecture/dolt.md —— 嵌入式与服务器模式的深度对比、共享服务器、迁移、版本钉选docs/recovery/index.md —— 常见问题的分步恢复 runbookdocs/cli-reference/index.md —— 全部 108 个bd命令的完整参考docs/cli-reference/dolt.md ——bd dolt子命令start/stop/status/show/commit/push/pull/remote 管理docs/getting-started/quickstart.md —— 安装与起步docs/multi-agent/federation.md —— 跨仓库 peer-to-peer 联邦同步docs/workflows/wisps.md —— 临时分子wisp生命周期engdocs/INTERNALS.md —— 实现细节贡献者文档engdocs/COLLISION_MATH.md —— 哈希长度与碰撞概率的生日悖论分析。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考