企业官网建设流程全解析

如何用 Beads 把 TOML formula 实例化为 molecule 并执行工作流步骤

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

你手里有一个用 TOML 写好的工作流模板（formula），想把它变成 beads 项目里一组真实可执行的工作项，然后按依赖顺序一步步推进直到完成。这条路径在 Beads 里是固定的三步：formula 经bd cook变成 proto（模板 epic），再经bd mol pour实例化为 molecule（带父子关系和依赖边的 issue 图），最后用bd ready/bd update --claim/bd close循环执行各步骤。本文基于 Formulas 文档、Molecules 文档 和 cook 命令参考 给出完整操作路径。

前提：bd已可用，且你当前处于一个 beads 项目里（项目内存在.beads/目录，formula 搜索路径会解析到它）。

写好 TOML formula 并放入搜索目录

formula 是声明式工作流模板，推荐用 TOML 编写。最小可用结构包含：顶层formula名称、type（标准步骤序列用workflow）、[vars.*]变量定义、[[steps]]步骤定义。仓库自带的 feature-workflow 示例 可以直接作为起点：

formula = "feature-workflow" description = "Standard feature development workflow: design, implement, review, merge." version = 1 type = "workflow" [vars.feature_name] description = "Name of the feature to implement" required = true [[steps]] id = "design" title = "Design {{feature_name}}" type = "human" [[steps]] id = "implement" title = "Implement {{feature_name}}" needs = ["design"] [[steps]] id = "test" title = "Run test suite" needs = ["implement"] [[steps]] id = "review" title = "Code review" needs = ["test"] type = "human" [[steps]] id = "merge" title = "Merge to main" needs = ["review"]

几个要点：

• 步骤通过needs声明依赖；没有needs的步骤之间没有顺序关系。
• 变量支持required、default、pattern、enum约束，步骤标题里用{{变量名}}引用。
• 步骤的type决定生成的 issue 类型（默认task，可选bug、feature、epic、chore）；人工签核不用 step type 表达，而是用[steps.gate]块，见 Gates 文档。

formula 的搜索目录按顺序为：<resolved-beads-dir>/formulas/（当前项目）、<checkout-root>/.beads/formulas/、~/.beads/formulas/（用户级）、$GT_ROOT/.beads/formulas/（设置了GT_ROOT时），见 formula 命令参考。把文件放到项目级或用户级目录即可，例如：

# 把示例 formula 复制到项目级目录（在 formula 文件所在目录执行） cp feature-workflow.formula.toml .beads/formulas/ # 或放到用户级，所有项目可见 cp feature-workflow.formula.toml ~/.beads/formulas/

复制位置依据 examples/formulas/README.md 中的用法说明。

确认 formula 对 bd 可见

# 列出所有搜索路径上可见的 formula bd formula list # 查看某个 formula 的变量、步骤与依赖详情 bd formula show feature-workflow # 专门验证 formula 可访问、可 cook（做 pre-flight 检查） bd mol seed feature-workflow

bd formula list应能看到你刚放入的feature-workflow。如果 formula 里含 gate 块，pour 之前建议用bd formula show <formula> --json核对解析结果——TOML 中的未知键会被静默丢弃。

可选：先用 bd cook 预览解析结果

bd cook有两种模式（见 cook 命令参考）：

• 编译期（默认，--mode=compile）：{{variable}}占位符原样保留，适合建模、估算、交接；
• 运行期（--mode=runtime或提供了任意--var）：变量被实际替换，要求所有变量都有值（--var提供或 formula 里的默认值）。

默认情况下 cook 只把解析后的 formula 以 JSON 打印到 stdout，不写数据库：

# 编译期：保留 {{feature_name}} 占位符 bd cook feature-workflow # 运行期：替换变量，看 pour 之前每一步的确切标题 bd cook feature-workflow --var feature_name=dark-mode # 预览将要创建的内容 bd cook feature-workflow --dry-run

--persist会把 proto 写进数据库（ID 与 formula 名一致、带template标签），这是旧版行为，适合同一个 proto 反复复用；大多数工作流不需要它，因为bd mol pour可以直接接收 formula 名并内联 cook。

把 formula 实例化为 molecule

对持久化工作（需要审计记录、跨多个会话），用bd mol pour：

# 先预览将要创建的 root 和子步骤 bd mol pour feature-workflow --var feature_name=dark-mode --dry-run # 确认无误后正式 pour bd mol pour feature-workflow --var feature_name=dark-mode

--var的值必须匹配 formula 中[vars.*]的约束（例如 release 示例 中version要求符合^\d+\.\d+\.\d+$）。pour 成功后会创建一个 molecule root issue（如bd-xyz）和一组子步骤 issue（bd-xyz.1、bd-xyz.2等），root 与子步骤之间是父子关系，步骤之间按needs连成依赖边；结果持久化在.beads/中并随 git 同步。记下输出中的 root ID，下文以<molecule-id>指代它。

可选分支：如果工作不需要审计记录（一次性发布流程、运维循环、健康检查），用bd mol wisp <proto> --var ...创建临时 wisp 而不是 pour；formula 中声明phase:"vapor"时 pour 会给出警告，提示该公式更适合 wisp（见 mol 命令参考）。

验证 molecule 结构与 ready 前沿

# 查看 molecule 结构、变量与步骤 bd mol show <molecule-id> # 高亮当前可并行运行的步骤 bd mol show <molecule-id> --parallel # 查看完整层级 bd dep tree <molecule-id> # 只列出该 molecule 中依赖已全部完成、可以立即执行的步骤 bd ready --mol <molecule-id>

bd ready --mol只返回没有活跃 blocker 的步骤，这正是执行入口（ready 命令参考）。

按 ready → claim → close 循环执行步骤

多会话执行循环（来自 Molecules 文档）：

# 1. 拿 ready 工作 bd ready --mol <molecule-id> # 2. 认领一个步骤 bd update bd-xyz.1 --claim # 3. 完成实际工作后关闭 bd close bd-xyz.1 --reason "Done" # 4. 再查下一次 ready 的步骤，重复直到 molecule 完成 bd ready --mol <molecule-id>

三条容易踩的坑（文档明确列出）：

• 子步骤默认并行。步骤编号或名字里的 "1/2/3" 不产生顺序，只有显式依赖（formula 里的needs、线上用bd dep add <B-id> <A-id>，依赖方在前）才会串行化。
• 别忘了关闭工作。上游步骤不 close，下游会永远 blocked；用bd close <id> --reason "Done"收尾，并用bd blocked检查是谁在等谁。
• 依赖方向别写反。"Phase 2 needs Phase 1" 对应bd dep add phase2 phase1，写完用bd blocked验证。

如果 formula 步骤带[steps.gate]块，实例化时会生成 gate issue 并作为该步骤的 blocker：gate 关闭前该步骤不会进入 ready。人工 gate 用bd gate resolve <gate-id>关闭；timer 和 GitHub gate 用bd gate check评估真实世界状态后自动关闭（详见 Gates 文档）。

跟踪进度并收尾

# 逐步状态：[done] / [current] / [ready] / [blocked] / [pending] bd mol current <molecule-id> # 进度摘要：completed/total、速率、ETA bd mol progress <molecule-id>

注意一个生命周期细节：关闭最后一个子步骤不会自动关闭 molecule root，epic 会保持 open 直到显式关闭。收尾阶段可选：

• bd mol squash <molecule-id>：把临时子 issue 压缩成一个持久 digest issue；
• bd mol burn <molecule-id>：直接删除 molecule、不产生 digest——这是破坏性操作，数据会永久丢失，仅用于放弃的流程或测试运行，建议先bd mol burn <id> --dry-run预览；
• bd mol stale：列出"子步骤全部关闭但 root 仍 open"的 molecule，用于发现漏收尾的工作。

完成状态的判定依据：bd mol current <molecule-id>中所有步骤显示[done]，或bd mol progress显示 completed 等于 total。之后你得到的是一组按依赖顺序执行完毕的 issue 记录，root epic 可按需显式关闭。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads