Beads 核心机制全解依赖感知的问题图、bd ready可认领边界与 formula→molecule 工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 是一个为编码 Agent 设计的持久化工作记忆层它把单元工作bead / issue以版本化数据库的形式保存下来用依赖边把它们连接成一张图再由bd ready精确计算出此刻可以动手的工作前沿让 Agent 在会话崩溃、重启或换机后无缝接续进度。本文以 docs/core-concepts/index.md 为主线结合仓库源码完整讲解 bead 与依赖模型、ready work 的计算语义、防碰撞哈希 ID、formula→proto→molecule 流水线、Dolt 同步与两种存储模式读完即可理解 Beads 的端到端工作方式并上手bd命令行。问题背景Agent 的记忆为什么必须外置编码 Agent 每次会话结束都会丢失记忆Markdown 计划逐渐腐烂、TODO 注释散落各处、崩溃的 Agent 连上下文一起消失。Beads 用一张**持久化的、结构化的工作图**替代这一切——每个工作单元是一个bead即 issue存放在版本控制的数据库里单元之间由依赖关系相连而bd ready负责计算现在到底能做什么。create[bd createbr/new bead] -- depgraph[dependencybr/graph] depgraph -- ready[bd readybr/claimable work] ready -- claim[bd update --claimbr/agent takes it] claim -- close[bd closebr/work done] close --|blockers released| ready上图几乎是整个产品的缩影创建和关闭 bead 会重塑依赖图而决定下一步做什么的是这张图本身而不是任何人类调度者。工作数据存活于 Agent 之外下一次会话直接从上次中断的地方继续。Bead 与依赖图的基本单元一个bead是唯一追踪的工作单元具备以下字段哈希 ID如bd-a1b2内容派生而非自增序号详见下文哈希 ID小节标题人类可读的工作描述类型bug、task、feature、epic、chore等可用bd types查看完整清单参见 bd types 命令文档优先级0critical到4backlog共 5 档状态沿open→in_progress→closed流转。bead 和 issue 指的是同一事物CLI 里叫 issue产品层面叫 bead。这一点在源码中也有对应——backend/types.go 定义了完整的生命周期状态常量StatusOpen、StatusInProgress、StatusBlocked、StatusDeferred、StatusClosed可见除了主流转外还存在blocked被阻塞与deferred推迟两个中间状态它们正是下文 ready work 计算要排除的对象。依赖Dependencies把 bead 连成图四种核心边类型决定了 Agent 可做什么类型含义是否影响 ready workblocks硬排序——阻塞方必须先关闭是parent-childepic/子任务结构间接——被阻塞的父项会阻塞其子项discovered-from溯源关系——在父项工作中发现否related软关联否工作流步骤还会引入另外两种阻塞类型conditional-blocks、waits-for详见 Molecules 文档更丰富的知识图谱边relates-to、duplicates、supersedes、replies-to在 Graph Links 中介绍。Ready workbd ready计算什么Ready work是依赖图的可认领前沿处于open状态、且没有任何open阻塞方的 bead同时排除所有in_progress、blocked、deferred以及被 gate 扣留的工作。Agent 从不扫描整个任务追踪器它们只索取这条前沿并原子地认领。A[bd-a1b2 · openbr/design schema] -- C[bd-c3d4 · openbr/implement API] B[bd-b9f0 · closedbr/pick database] -- C C -- D[bd-e5f6 · openbr/write e2e tests] E[bd-77aa · openbr/update README]上图中bd ready只会返回bd-a1b2和bd-77aa——其余要么已关闭要么正等待一个 open 的阻塞方。当bd-a1b2关闭后bd-c3d4自动变为 ready无需任何人重新规划。命令形式bd ready --json # 返回可认领前沿机器可读 bd ready --claim --json # 原子地认领第一个匹配项从 cmd/bd/ready.go 的命令定义可以看出这个语义被严格实现ready命令的 Long 描述明确写着Show ready issues with no active blockers并排除in_progress、blocked、deferred和被 hook 扣留的 issue底层走GetReadyWorkAPI blocker-aware 语义。bd list --ready与bd ready共享同一套 ready-work 语义保证 CLI 输出口径一致。除了文档中的--json与--claim该命令还支持更多面向分子molecule编排与调试的参数--mol id只显示指定 molecule 内部处于 ready 的步骤不可与--claim组合--gated找出gate 已关闭、等待恢复派发的 molecule不可与--claim组合--explain解释某个候选为什么 ready / 为什么不 ready不可与--claim组合--offset N分页偏移仅在--proxied-server模式下支持--limit N/--max-rows行数上限配合--limit 0可关闭上限超出时 stderr 会提示 Showing X of Y ready issues。--claim分支走的是ReadyClaimer角色见 issueops/readyclaimer.go选择、compare-and-set 与--json所需的 hydration 全部发生在同一个事务里这正是两个 Agent 不会抢到同一个 bead的原子性来源cmd/bd/ready.go 的注释明确说明。认领成功后会自动触发 Dolt autocommit并把该 ID 记为最后触碰以便追踪。哈希 ID为什么 Agent 永远不会撞车形如bd-a1b2的 ID 是内容派生的哈希对标题、描述、创建者、创建时间求哈希并附加一个碰撞 nonce而不是自增序号。因此两个 Agent或两个分支在同一时刻创建 bead 也不可能产出相同的 ID合并时永远不会重新编号工作。哈希长度在碰撞时会自动扩展并随数据库规模自适应增长——详见 Hash IDs 与 Adaptive ID Length。internal/idgen/hash.go 给出了具体实现GenerateHashID把title|description|creator|unixNano|nonce拼成内容串经 SHA-256 摘要后按目标长度截取字节3 字符用 2 字节4~5 字符用 3~4 字节最多 5 字节支持 8 字符再用 base360-9, a-z编码最终拼上bd-前缀。选择 base36 而非十六进制是为了同样的字符数携带更多信息量nonce 的存在则保证即使两个 bead 内容完全相同也能通过递增 nonce 区分开来。工作流formula → proto → molecule可重复的多步工作只需声明一次然后按需冲印formula[formulabr/(TOML file)] --|bd cook| proto[protobr/(template epic)] proto --|bd mol pour| mol[moleculebr/(persistent beads)] proto --|bd mol wisp| wisp[wispbr/(ephemeral beads)] gate[gatebr/(async wait)] -.blocks a step.- molformula是源头一个定义步骤 DAG 的 TOML/JSON 文件参见 Formulascook把它编译成proto一个带{{variables}}占位符的模板 epic还不是真实工作pour实例化出molecule真实的 bead其步骤像其他任何工作一样流经bd ready参见 Moleculeswisp是同一套实例化的临时生命期版本——下一次bd purge即消失参见 Wispsgate把某个步骤挂起直到外部事件发生人工签核、定时器、GitHub 运行或 PR参见 Gates。这条流水线在仓库中有完整落地cmd/bd/cook.go 负责 formula→proto 的编译internal/molecules/molecules.go 承载 molecule/wisp 的运行时模型而bd ready --mol与bd ready --gated两个子能力正是为执行中的 molecule 服务的前者让 Agent 只看自己这个分子内部下一步能跑哪些步骤后者让被 gate 扣住、如今 gate 已关闭的分子恢复派发。同步工作如何在机器间流动Beads 把一切存放在Dolt一个版本控制的 SQL 数据库里。每次写入都会自动提交进 Dolt 历史同步是原生的 push/pull复用它现有的 git remote、挂在独立的 ref 之下——不需要额外运行任何服务器。subgraph you[your machine] db[(Dolt DBbr/.beads/embeddeddolt/)] end subgraph remote[git remote (origin)] ref[(refs/dolt/data)] end subgraph teammate[teammate / other clone] db2[(Dolt DB)] end db --|bd dolt push| ref ref --|bd dolt pull| db db2 --|push / pull| refbd dolt push把你的本地 Dolt 数据推送到 origin 上的refs/dolt/datarefbd dolt pull再把它拉回来队友的克隆体可以互相 push/pull 同一套数据。需要注意.beads/issues.jsonl只是面向查看器和数据交换的被动导出它既不是数据库本体也不是同步协议更不是备份。完整模型及其反模式在 Sync Concepts 中展开跨仓库、跨组织的点对点共享federation在 Federation 中说明。存储模式Embedded 与 Server模式命令数据位置写入方Embedded默认bd init.beads/embeddeddolt/单写入方文件锁保护Serverbd init --server.beads/dolt/多并发写入方Embedded 模式把 Dolt 以进程内方式运行对绝大多数使用者都是正确选择Server 模式则连接外部dolt sql-server用于多写入方场景——详见 Dolt 后端 与 架构总览。两种模式的分流判断在bd init的命令实现里完成文件锁file-lock机制保证 Embedded 模式下一个数据库同时只有一个进程写入从而在零运维的前提下保证数据一致性。下一步深入方向快速开始——安装、创建、认领并关闭你的第一批 beadsIssues Dependencies——bead 及其关系的字段级细节Workflows——molecules、formulas、gates、wisps 的深入讲解Multi-Agent——面向 Agent 集群的路由、协调与 federation。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考