Beads 分子化学系统完全指南用 Proto、Mol 与 Wisp 打造可复用的 Agent 工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 在 v0.34.0 中引入了灵感源自化学的工作流系统以固态 Proto模板→ 液态 Mol持久实例→ 气态 Wisp临时实例的三相隐喻为 Coding Agent 提供可复用工作模板与临时编排能力。本文以仓库中的官方参考文档 MOLECULES.md 为核心骨架结合cmd/bd与internal/molecules的源码实现完整讲解 Proto 的创建与蒸馏、Mol 的生成与键合、Wisp 的生命周期管理以及跨项目能力依赖帮助你掌握一套可落地的化学工作流实操方案。化学隐喻三相工作流模型bd 的分子化学系统用物质三态类比工作流的不同持久化阶段相态名称存储位置是否同步用途固态Proto.beads/是可复用模板带template标签的 epic液态Mol.beads/是持久实例由模板生成的真实 issue气态Wisp.beads-wisp/否临时实例操作性工作不保留审计轨迹相变路径文档明确定义的六种转换spawn/pour固态Proto→ 液态Molwisp create固态Proto→ 气态Wispsquash气态Wisp→ 摘要Digest永久性总结burn气态Wisp→ 无直接删除不留痕迹distill液态临时 epic→ 固态Proto从源码看实现mol.go 中对术语的定义与文档完全一致——Proto 是未实例化的模板Molecule 是 Proto 生成的实例Spawn 是把模板实例化为真实 issueBond 是多态的组合操作Distill 是从临时 epic 提炼可复用 Proto。命令本体还带了一个致敬《苍穹浩瀚》的彩蛋bd mol的别名是protomolecule原始分子。一个值得注意的实现细节文档将 Wisp 描述为存储在.beads-wisp/目录而从 wisp.go 的源码注释看Wisp 实际是主数据库中带Ephemeraltrue标记的 issueID 使用独立的wisp前缀bd-wisp-xxx见 types.go通过 dolt_ignore 规则排除在 git 同步之外。可以理解为物理上同库、逻辑上隔离的临时工作区。何时使用分子系统使用 Proto/Mol 的场景可重复模式——同一工作流结构被多次使用发布、评审、新人 onboarding团队知识沉淀——把隐性知识tribal knowledge编码为可执行模板需要审计轨迹——需要事后跟踪和复查的工作跨会话持久化——跨越多天/多会话的工作使用 Wisp 的场景运维循环——巡检周期、健康检查、例行监控一次性编排——不应污染历史的临时协调工作诊断运行——无归档价值的调试工作流高频临时工作——会在永久数据库中制造噪音的工作核心洞察Wisp 在保持执行期结构化的同时避免了常规操作导致数据库膨胀——这是它存在的根本理由。Proto 管理模板的创建与查看创建 ProtoProto 本质上是带template标签的 epic。可以手动创建也可以从现有工作蒸馏distill而来# 手动创建 bd create Release Workflow --type epic --label template bd create Run tests for {{component}} --type task bd dep add task-id epic-id --type parent-child # 从临时工作蒸馏模板从现有 epic 提取 bd mol distill bd-abc123 --as Release Workflow --var version1.0.0Proto 命名约定建议使用mol-前缀以示清晰如mol-release、mol-patrol。从源码看MoleculeLabel直接复用了模板标签BeadsTemplateLabelmol.go也就是说分子与模板共享同一标签体系与子图结构MoleculeSubgraph TemplateSubgraph。另外internal/molecules/molecules.go 展示了模板的另一种来源——molecules.jsonl目录文件加载优先级为内置随二进制发布 城镇级$GT_ROOT/.beads/molecules.jsonl通过GT_ROOT环境变量检测编排者 用户级~/.beads/molecules.jsonl 项目级.beads/molecules.jsonl。后加载的同 ID 模板会覆盖先加载的。这些模板以IsTemplate true标记是只读的拒绝变更默认不出现在bd list中。列出公式Formulasbd formula list # 列出所有公式protos bd formula list --json # 机器可读输出查看 Proto 结构bd mol show mol-release # 显示模板结构与变量 bd mol show mol-release --json # 机器可读输出生成分子从模板到实例基本 Spawn默认创建 Wispbd mol spawn mol-patrol # 创建 wisp临时 bd mol spawn mol-feature --pour # 创建 mol持久 bd mol spawn mol-release --var version2.0 # 带变量替换化学快捷键bd mol pour mol-feature # spawn --pour 的快捷方式 bd mol wisp mol-patrol # 显式创建 wisp生成后立即执行bd mol run mol-release --var version2.0bd mol run做三件事生成分子持久化将根 issue 指派给调用者固定pin根 issue 以便会话恢复何时用mol run启动应该能在崩溃中存活下来的持久工作时。pin 机制确保重启后bd ready仍能显示该工作。带附件生成在单条命令中附加其他 Protobd mol spawn mol-feature --attach mol-testing --var nameauth # 先 spawn mol-feature再 spawn mol-testing 并将两者键合附件类型sequential默认——附件在主工作完成后运行parallel——附件与主工作并行运行conditional——附件仅在主工作失败时运行bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional从 mol_bond.go 的实现看--attach本质上是 spawn 后的一次 bond附件通过AttachToID挂在目标分子上依赖类型由 bond 类型决定——sequential 生成DepBlocks阻塞、conditional 生成DepConditionalBlocks条件阻塞、parallel 则退化为纯组织性的DepParentChild。spawn 前还会校验所有必填变量missing required variables错误提示使用--var补齐。键合分子组合出化合物键合类型bd mol bond A B # SequentialB 在 A 之后运行 bd mol bond A B --type parallel # ParallelB 与 A 并行运行 bd mol bond A B --type conditional # ConditionalB 仅在 A 失败时运行操作数组合矩阵AB结果protoproto化合物 Proto可复用模板protomolSpawn proto附加到分子上molprotoSpawn proto附加到分子上molmol合并为化合物分子从 mol_bond.go 的源码可以确认 bond 的多态分派逻辑两个 proto 走bondProtoProto创建一个新的化合物根 epic其BondedFrom字段记录来源与键合类型一 proto 一 mol 走bondProtoMol/bondMolProtospawn 后附加两个 mol 走bondMolMol只加依赖边。mol mol键合前还会执行 BFS 环检测wouldCreateCycle防止形成传递性依赖环对应 GH#2719。键合中的相位控制默认情况下spawn 出的 proto 继承目标的相态。可用标志覆盖# 在 wisp 巡检中发现 bug持久化它 bd mol bond mol-critical-bug wisp-patrol --pour # 需要在持久功能上做临时诊断 bd mol bond mol-temp-check bd-feature --wisp实现上对应--pour强制液态Ephemeralfalse与--ephemeral强制气态Ephemeraltrue两个互斥标志——同时使用会报错cannot use both --ephemeral and --pour。默认的继承目标相态逻辑在buildAttachCloneOpts中makeEphemeral : mol.Ephemeral再被两个标志分别覆盖。自定义化合物名称bd mol bond mol-feature mol-deploy --as Feature with Deploy--as仅对 protoproto 有效用于设置化合物根 epic 的标题否则默认生成Compound: A B。进阶动态键合Christmas Ornament 模式mol_bond.go 还提供了一个文档之外的进阶能力——--ref自定义子引用与变量替换bd mol bond mol-worker-arm bd-patrol --ref arm-{{worker_name}} --var worker_nameace # 生成 bd-patrol.arm-ace及 bd-patrol.arm-ace.capture 等子项这在为一个巡检任务 spawn 多个 worker 臂的场景下能生成可读性强的 ID 而非随机哈希。Wisp 生命周期临时工作的完整管理创建 Wispbd mol wisp mol-patrol # 从 proto 创建 bd mol spawn mol-patrol # 同上spawn 默认创建 wisp bd mol spawn mol-check --var targetdb # 带变量列出 Wispbd mol wisp list # 列出所有 wisp bd mol wisp list --json # 机器可读输出从 wisp.go 的源码看wisp list展示 ID、标题、状态、优先级、类型、创建/更新时间并将超过 24 小时OldThreshold未更新的 wisp 标记为 old提示用bd mol wisp gc清理。结束 Wisp方案一Squash压缩为摘要bd mol squash wisp-abc123 # 自动生成摘要 bd mol squash wisp-abc123 --summary Completed patrol # 使用 Agent 提供的摘要 bd mol squash wisp-abc123 --keep-children # 保留子项只创建摘要 bd mol squash wisp-abc123 --dry-run # 预览Squash 会创建一个永久的 digest issue 总结 wisp 的工作然后删除 wisp 子项。从 mol_squash.go 的实现细节看squash 操作实际包含收集所有Ephemeraltrue的子项 → 用--summary提供的文本或自动拼接生成摘要generateDigest会统计完成/进行中数量并逐条列出步骤与 close reason→ 创建Ephemeralfalse的永久 digest issue → 建立 digest 与根的 parent-child 依赖 → 删除子项除非--keep-children→ 若根是 wisp 则自动关闭根并清除其 ephemeral 标记。方案二Burn无痕删除bd mol burn wisp-abc123 # 删除 wisp不创建摘要对无归档价值的例行工作使用 burn。垃圾回收bd mol wisp gc # 清理孤儿 wisp bd mol wisp gc --closed # 预览已关闭 wisp 的删除 bd mol wisp gc --closed --force # 清除所有已关闭 wispGC 的保护逻辑值得一提wisp.go被固定pinned的、阻塞在开放依赖上的、以及状态属于 WIPin_progress/blocked/hooked或冻结deferred/pinned类别的 wisp 永远不会被按年龄回收——这是为了防止 GC 误删执行中的活动分子GH#4394。年龄阈值默认 1 小时可用--age调整--exclude-type可保护特定类型的 wisp。蒸馏 Proto从临时工作提炼模板从临时工作中提取可复用模板bd mol distill bd-o5xe --as Release Workflow bd mol distill bd-abc --var feature_nameauth-refactor --var version1.0.0distill 做了什么加载现有 epic 及其所有子项将结构克隆为新的 proto添加template标签用{{variable}}占位符替换具体值变量语法两种都支持--var branchfeature-auth # variablevalue推荐 --var feature-authbranch # valuevariable自动检测从 mol_distill.go 的源码看parseDistillVar会智能检测哪一侧是具体值、哪一侧是变量名——它先在子图的所有可搜索文本标题、描述、设计、验收标准、备注见collectSubgraphText中查找哪个片段出现从而确定替换方向。输出的公式文件按第一个可写位置落盘项目级resolved-beads-dir/formulas/默认→ 仓库级checkout-root/.beads/formulas/→ 用户级~/.beads/formulas/。使用场景团队自然地发展出好的工作流希望复用它把隐性知识沉淀为可执行模板为类似的未来工作创建起点跨项目依赖能力即接口概念项目可以依赖其他项目提供的能力# 项目 A 交付一项能力 bd ship auth-api # 标记能力可用 # 项目 B 依赖它 bd dep add bd-123 external:project-a:auth-api交付能力bd ship capability # 交付能力要求 issue 已关闭 bd ship capability --force # 即使 issue 未关闭也交付 bd ship capability --dry-run # 预览工作原理找到带export:capability标签的 issue校验 issue 已关闭添加provides:capability标签依赖外部能力bd dep add issue external:project:capability当外部项目存在一个带provides:capability标签的已关闭 issue 时该依赖即被视为满足。bd ready尊重外部依赖被未满足的外部依赖阻塞的 issue 不会出现在 ready 列表中。常见实战模式模式一每周评审 Proto# 创建 proto bd create Weekly Review --type epic --label template bd create Review open issues --type task bd create Update priorities --type task bd create Archive stale work --type task # 链接为子项…… # 每周使用 bd mol spawn mol-weekly-review --pour模式二临时巡检循环# 假设巡检 proto 已存在 bd mol wisp mol-patrol # 执行巡检工作…… # 结束巡检 bd mol squash wisp-abc123 --summary Patrol complete: 3 issues found, 2 resolved模式三带回滚的功能发布bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional # 若部署失败回滚自动解除阻塞模式四沉淀隐性知识# 自然完成一个优秀工作流之后 bd mol distill bd-release-epic --as Release Process --var versionX.Y.Z # 之后团队可以bd mol spawn mol-release-process --var version2.0.0CLI 快速参考命令用途bd formula list列出可用公式/protosbd mol show id显示 proto/mol 结构bd mol spawn proto从 proto 创建 wisp默认bd mol spawn proto --pour从 proto 创建持久 molbd mol run protoSpawn 指派 固定持久执行bd mol bond A B组合 protos 或 moleculesbd mol distill epic从临时工作提取 protobd mol squash mol将 wisp 子项压缩为摘要bd mol burn wisp无痕删除 wispbd mol pour protospawn --pour的快捷方式bd mol wisp proto创建临时 wispbd mol wisp list列出所有 wispbd mol wisp gc垃圾回收孤儿 wispbd mol wisp gc --closed清除所有已关闭 wisp预览加--force执行bd ship capability发布能力供跨项目依赖故障排查Proto not found运行bd formula list检查可用公式/protosProto 需要在 epic 上有template标签Variable not substituted使用--var keyvalue语法用bd mol show检查 proto 中的{{key}}占位符Wisp commands failWisp 存储在.beads-wisp/与.beads/分离实现上对应主库中Ephemeraltrue且带bd-wisp-前缀的 issue运行bd mol wisp list查看活动 wispExternal dependency not satisfied目标项目必须有带provides:capability标签的已关闭 issue先在目标项目中运行bd ship capability以上内容基于仓库中的 MOLECULES.md 官方参考文档整理并辅以 cmd/bd/mol.go、cmd/bd/mol_bond.go、cmd/bd/wisp.go、cmd/bd/mol_squash.go、cmd/bd/mol_distill.go 与 internal/molecules/molecules.go 等源码实现佐证。感兴趣的读者可以继续深入这些文件理解分子系统的完整调用链与边界情况处理。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考