Beads 分子工作流Molecules完全指南用依赖有序的 Epic 编排编码 Agent 的多会话任务【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsMolecules分子是 Beads 中一类特殊的工作图它们是带有执行语义的 epic其子任务作为依赖有序的步骤依次通过bd ready流动由编码 Agent 并行或串行地消费直至全部关闭。本文以 docs/workflows/molecules.md 为核心骨架结合仓库源码cmd/bd/mol.go、cmd/bd/pour.go、cmd/bd/mol_bond.go 等系统讲解分子的创建、执行、生命周期、bonding键合组合与常见 Agent 陷阱读完你即可用分子工作流编排横跨多会话、多人协作的复合任务。什么是 MoleculeMolecule 是 proto一份被 cook 过的 formula即模板的持久化实例具备三个核心特征包含带依赖的步骤子任务之间通过依赖边形成有向无环图DAG持久化存储在 issue 数据库中与任何普通 bead 一样可通过bd dolt push / pull同步步骤映射为具有父子关系的 issue父 issue 是分子根如bd-xyz子 issue 是步骤如bd-xyz.1、bd-xyz.2。从底层看分子本质上就是一个 epic——一个带子项的父 issue——外加工作流语义。仓库源码 cmd/bd/mol.go 中MoleculeLabel BeadsTemplateLabel这一常量直接印证了分子与模板共享同一标签体系的设计模板即带template标签的 epic分子即被实例化的模板。术语含义使用时机Epic带子项的父 issue分层工作的通用称谓Molecule带有执行意图的 Epic讨论工作流遍历bd ready的推进时Proto带template标签的 Epic可复用的工作模式可选需要强调的是proto 与 formula 只是可复用模式与复杂组合的可选抽象层——绝大多数工作只需要 epic 加依赖即可完成不必为了使用分子而强行引入模板。创建 Molecules从 Formula 创建推荐# 先把 formula 烹饪成 proto再把 proto 倒入分子 bd cook release.formula.toml bd mol pour release --var version1.0.0这一步会创建父 issuebd-xyz分子根子 issuebd-xyz.1、bd-xyz.2等各步骤pour命令在源码 cmd/bd/pour.go 中被定义为相变操作Proto (solid) - pour - Mol (liquid)即把模板实例化为持久化、可审计的工作写入.beads/并随其他 bead 一起同步。它支持以下常用参数参数说明默认值--var keyvalue变量替换可重复传参无--dry-run预览将创建哪些 issue不真正写入false--assignee agent创建时直接把分子根指派给某个 Agent无--attach proto浇注后以指定 bond 类型附加其他 proto可重复无--attach-type type附加时的 bond 类型sequential/parallel/conditionalsequential源码中的checkPourVarscmd/bd/pour.go会在浇注前校验所有必填变量是否已通过--var提供缺失时给出类似missing required variables: name (use --var namevalue)的报错提示。不使用 Formula 创建直接创建 epic 并手工接线依赖bd create Feature X -t epic bd create Design -t task --parent epic-id bd create Implement -t task --parent epic-id bd create Test -t task --parent epic-id bd dep add implement-id design-id # implement 需要 design bd dep add test-id implement-id # test 需要 implement如果 epic 带有 size/effort 标签参考 Labels 核心概念 了解如何避免该标签被继承到子步骤上。如果某个临时拼凑的 epic 被证明值得复用可以用bd mol distill epic-id formula-name从中提炼出可复用的 formula源码注释中将 distill 定义为从临时 epic 提取可复用 proto见 cmd/bd/mol.go。查找与查看 Moleculesbd mol current # 你正在哪个分子中工作、处于哪一步 bd mol stale # 已完成但尚未关闭的分子 bd mol wisp list # 临时分子wisps bd mol show molecule-id # 查看结构与变量 bd mol show molecule-id --parallel # 高亮可并行的步骤 bd dep tree molecule-id # 查看完整层级bd mol stale的实现cmd/bd/mol_stale.go对stale 分子给出了精确定义所有子项均已关闭Completed Total但根 issue 仍处于 open 状态。它还支持--blocking仅显示阻塞了其他工作的分子、--unassigned仅显示未指派给任何人的分子、--all包含 0 子项的分子三个过滤参数。使用 Molecules执行模型Agent 拾取一个分子后会并行执行所有 ready就绪的子步骤直到全部关闭epic-root (指派给 agent) ├── child.1 (无依赖 → ready) ← 并行执行 ├── child.2 (无依赖 → ready) ← 并行执行 ├── child.3 (依赖 child.1) → 阻塞直到 child.1 关闭 └── child.4 (依赖 child.2、child.3) → 阻塞直到两者都关闭子步骤默认并行。只有显式声明的依赖才会产生顺序。这就是多会话循环的推进方式获取 ready 工作bd ready --mol molecule-id认领它bd update id --claim执行工作关闭它bd close id重复直到分子全部完成依赖类型并非所有依赖类型都会阻塞执行。internal/types/types.go中定义了完整的依赖类型枚举见 types.go类型语义用途blocksB 在 A 关闭前不能开始串行化工作parent-child父被阻塞则子也被阻塞层级结构子步骤默认并行conditional-blocks仅当 A 失败时 B 才运行错误处理路径waits-forB 等待 A 的全部动态子项扇入闸门fan-in gates见 Gates 工作流非阻塞类型related、discovered-from、replies-to只建立 issue 之间的关联不影响执行。源码中IsBlocking系列函数types.go精确圈定了会阻塞执行的集合blocks、conditional-blocks、waits-for以及父子结构中的parent-child。步骤依赖在 formula 中步骤通过needs声明依赖[[steps]] id implement title Implement feature needs [design] # 必须先完成 design在真实的 issue 上直接添加边即可——被依赖者在前bd dep add B-id A-id # B 依赖 AB 需要 Abd ready会尊重这些依赖bd ready --mol molecule-id # 只显示依赖已完成的步骤逐步推进# 开始一个步骤 bd update bd-xyz.1 --claim # 完成一个步骤 bd close bd-xyz.1 --reason Done # 查看下一步 ready 什么 bd ready --mol bd-xyz值得注意的实现细节在 cmd/bd/mol_current.go 的AdvanceToNextStep中当关闭某个步骤后Beads 会通过findParentMolecule向上回溯找到所属分子并自动计算下一个 ready 步骤若开启自动认领autoClaim它会用乐观并发控制ClaimStepIfOpen逐个尝试 ready 步骤从而避免多个 Agent 同时认领同一步骤的 TOCTOU 竞争。查看进度# 查看被阻塞的步骤 bd blocked # 逐步状态 [done] / [current] / [ready] / [blocked] / [pending] bd mol current molecule-id # 进度汇总 已完成/总数、速率、ETA bd mol progress molecule-idbd mol current的状态机在 mol_current.go 中一目了然closed→done、in_progress→current并标记为YOU ARE HERE、blocked→blocked、其余按依赖分析判定为ready或pending。它还有两个面向巨型分子的防护特性阈值摘要LargeMoleculeThreshold 100mol_current.go超过 100 步默认只显示汇总可用--limit 50或--range 1-50按需查看多 Agent 视角bd mol current --for agent可查看指定 Agent 当前处于哪个分子未指定分子 ID 时会根据指派给当前 Agent 的in_progressissue 自动推断。bd mol progressmol_progress.go使用索引查询统计进度无需加载全部步骤并根据首末关闭时间计算Rate: ~N steps/hour与ETA可支撑超大规模分子JSON 输出模式会附带rate_per_hour与eta_hours字段便于程序化消费。Molecule 生命周期Formula (模板来源) ↓ bd cook Proto (模板 epic) ↓ bd mol pour Molecule (实例) ↓ 执行各步骤 Completed Molecule (已完成的分子) ↓ 可选清理 Closed / Squashed / Burned (关闭 / 压扁 / 烧毁)关闭最后一个子步骤并不会自动关闭分子根——epic 会一直保持 open作为可关闭工作直到被显式关闭bd epic close-eligible可批量清扫这些可关闭的 epic。这正是bd mol stale存在的原因帮助你发现子项全部完成但根还开着的残留分子。针对分子自身 beads 的清理有两个命令bd mol squash id把分子的临时子项压缩成一条永久的摘要 issuedigest。源码 cmd/bd/mol_squash.go 显示squash 会在同一事务内创建摘要 issueTypeTask、Ephemeralfalse、状态closed、建立摘要与根的父子依赖并默认删除临时子项--keep-children可保留。它还支持--summary ...直接传入 Agent 生成的智能摘要源码注释明确说明bd 保持纯工具定位智能摘要由调用方 Agent 负责生成以及--dry-run预览。若根自身是 wispsquash 完成时还会自动关闭根并清除其 ephemeral 标记。bd mol burn id直接删除分子不产生任何摘要——适用于废弃或测试运行。源码 cmd/bd/mol_burn.go 指出 burn 按分子相区分处理wisp临时直接删除持久化 mol 走级联删除并同步到远端。该命令是破坏性操作默认需要交互确认可用--force或隐藏别名--yes跳过确认支持--dry-run预览、也支持一次传入多个 ID 批量烧毁。这两个命令通常服务于 wisps 的临时生命周期参见 Wisps 工作流。Bonding连接工作图Bond键合意为在两个工作图之间创建依赖。当分子 A 阻塞分子 B 时A 的完成会解锁 BAgent 可以从 A 无缝继续到 B——形成一个可以横跨数天的复合工作流。bd mol bond A B # B 依赖 A默认 sequential bd mol bond A B --type parallel # B 与 A 并行 bd mol bond A B --type conditional # 仅当 A 失败时 B 才运行Bond 类型在internal/types/types.go中定义为枚举常量见 types.gosequentialB 在 A 完成后运行、parallelB 与 A 并行、conditionalB 仅在 A 失败时运行。命令本身在 cmd/bd/mol_bond.go 中实现其中runMolBond会先分别解析两个操作数issue 或 formula再按组合分发gatherMolBondInput会校验--ephemeral与--pour不能同时使用且 bond 类型必须合法。该命令对其操作数是多态的操作数行为proto proto生成复合 proto可复用模板见 bondProtoProtoproto molecule把 proto 实例化为新 issue 并附加到分子上molecule molecule合并为复合分子formula 任意先把 formula 内联 cook 成 proto源码中的resolveOrCookToSubgraphcmd/bd/mol_bond.go展示了 formula 的 inline cook 机制formula 名称会被直接烹饪为内存中的临时 proto 子图参与键合无需预先在数据库中存放 proto bead。另外bondMolMol在合并两个分子前会调用wouldCreateCyclecmd/bd/mol_bond.go做 BFS 环检测若新边会形成传递性依赖环则拒绝键合并给出环路径。被生成spawn的 issue 默认跟随目标对象的相持久化或临时。可用--pour强制持久化或--ephemeral强制临时经dolt_ignore排除在 Dolt 同步之外覆盖——详见 Wisps 工作流。动态 Bonding当子项数量在运行时才能确定时可以在循环中结合--ref键合获得可读的子 ID 而非随机哈希# 为每个发现的 worker 生成一条臂arm bd mol bond mol-worker-arm bd-patrol --ref arm-{{name}} --var nameace # 生成: bd-patrol.arm-ace (以及 bd-patrol.arm-ace.capture 等子项)--ref支持{{var}}变量替换如arm-{{polecat_name}}源码注释称此为圣诞树装饰模式Christmas Ornament pattern见 cmd/bd/mol_bond.go每个键合循环迭代都生成一个带语义名字的子图分支方便事后定位是哪条臂、哪个 worker 产出了哪些 issue。高级特性Bond Points键合点Formula 可以声明键合点——供组合使用的具名附着位。每个键合点指定一个步骤在before_step或after_step处附着可选parallel true[[compose.bond_points]] id entry description Attach setup work here before_step designHooks步骤完成钩子目前尚未作为可运行的 formula 动作暴露。历史上on_complete.run的示例是无效的run不是 formula 字段on_complete的运行时展开也在单独跟踪中直到端到端接通。在使用 formula 时请勿依赖该能力。指派分子可以在浇注时把分子根指派给某个 Agent然后随时追踪每个 Agent 所处的位置bd mol pour mol-feature --assignee agent # 创建时指派 bd mol current --for agent # 该 Agent 现在在哪Agent 陷阱时间语言会颠倒依赖方向。Phase 1 在 Phase 2 之前容易诱导写出bd dep add phase1 phase2——这是反的。请使用需求语言Phase 2 需要 Phase 1对应bd dep add phase2 phase1。用bd blocked验证。编号步骤不会产生顺序。命名为 Step 1/2/3 的步骤在没有显式依赖时依然并行运行。命名是给人看的依赖边才是给执行引擎看的。忘记关闭工作。被阻塞的 issue 会永远保持 blocked——除非它的阻塞项被关闭bd close id --reason Done。这也是bd mol stale存在的根本原因。示例工作流# 1. 从 formula 创建分子 bd cook feature-workflow.formula.toml bd mol pour feature-workflow --var namedark-mode # 2. 查看结构 bd dep tree bd-xyz # 3. 开始第一步 bd update bd-xyz.1 --claim # 4. 完成并推进 bd close bd-xyz.1 bd ready --mol bd-xyz # 显示下一步 # 5. 重复直到全部完成源码层面的支撑与延伸阅读Molecules 功能在仓库中是一套完整自洽的实现除上述命令外还值得关注模板目录加载internal/molecules/molecules.go 实现了分子目录molecules.jsonl的四级分层加载内置随二进制发布→ 城镇级$GT_ROOT/.beads/molecules.jsonl→ 用户级~/.beads/molecules.jsonl→ 项目级.beads/molecules.jsonl后者覆盖前者所有模板以is_template: true标记、只读变更被拒绝、默认从bd list排除。子图克隆spawnMolecule/spawnMoleculeWithOptionscmd/bd/mol.go包装cloneSubgraph负责变量替换、指派、ephemeral 相与自定义前缀IDPrefixMol下的实例化。进度统计与并发认领GetMoleculeProgress存储层、AdvanceToNextStepClaimStepIfOpencmd/bd/mol_current.go共同支撑多会话推进与多 Agent 安全认领findParentMoleculesmol_current.go用批量逐层回溯O(depth) 轮询替代了 N1 查询模式。相关文档Formulas 工作流 - 创建模板Gates 工作流 - 异步协调Wisps 工作流 - 临时工作流核心概念Dependencies - 依赖类型的完整语义【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考