Beads Formula 实战指南用.formula.toml为 Coding Agent 编排可复用的自动化工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读Beads 是一个为 Coding Agent 提供记忆升级的开源项目而 Formula 是它用来把重复性研发流程需求评审、开发、测试、发版、GitHub Issue/PR 处理固化成可复用模板的核心机制。本指南以仓库 examples/formulas 下的官方 Starter Formulas 为骨架完整讲解 Formula 的存放位置、命令行用法、五种内置工作流模板的配置细节并结合cmd/bd与internal/formula源码剖析 TOML 结构、变量校验、步骤依赖与烹饪cook原理帮助你从会用模板进阶到能自己写 Formula。1. Formula 是什么Agent 工作流的可复用载体在 Beads 中Formula 是一种用 TOML 描述工作流的声明式模板后缀为.formula.toml。一个 Formula 定义了一组有依赖关系的步骤steps每个步骤会交给 Agent 执行步骤可以带变量、条件、循环、门控gate等原语烹饪cook后实例化为可跟踪的分子molecule或幽灵wisp来运行。从源码结构看Formula 的 schema 由 internal/formula/types.go 定义命令层实现在 cmd/bd/formula.go、cmd/bd/mol.goSchema 索引生成逻辑在 cmd/bd/formula_schema.go。官方把经过端到端验证的原语示例放在 examples/formulas/primitives把开箱即用的业务工作流放在 examples/formulas。两个关键概念决定 Formula 的运行形态Molecule分子液态 liquid持久化的工作流实例长期跟踪状态适合跨天、跨会话的设计—实现—评审—合并流程Wisp幽灵气态 vapor临时的一次性实例运行完即燃烧burn销毁不污染.beads/目录与 git 历史适合 lint 检查、Issue 转 PR 这类一次性任务。bd mol子命令的说明cmd/bd/mol.go直接印证了这一点pour Instantiate proto as persistent mol (liquid phase) wisp Instantiate proto as ephemeral wisp (vapor phase) burn Discard wisp2. 安装与使用三步跑通 Starter Formulas2.1 复制 Formula 到正确目录Formula 有两级作用域examples/formulas/README.md# 项目级仅当前项目可用 cp *.formula.toml /path/to/project/.beads/formulas/ # 用户级所有项目可用 cp *.formula.toml ~/.beads/formulas/2.2 列出与实例化bd formula list # 查看可用的 formulas bd mol pour release --var version1.2.0 # 以持久 molecule 实例化 release 工作流2.3 按使用场景选用正确的相phase对于gh-issue-to-pr、gh-pr-review这类 GitHub 自动化工作流官方明确建议使用临时 wisp气态相因为它们在运行结束后会被清除不会在仓库中留下跟踪数据bd mol wisp gh-issue-to-pr --var issue_number123 bd mol wisp gh-issue-to-pr --var issue_number123 --var repomyorg/myrepo bd mol wisp gh-pr-review --var pr_number123重要提示使用 GitHub 工作流前必须根据你的项目定制repo仓库名、remotes远端、base_branch基础分支以及质量门禁命令quality-gate commands并确认ghCLI 已用足够权限的 token 认证。3. 五种内置 Formula 一览官方 Starter Formulasexamples/formulas共五个覆盖了研发闭环中最常见的场景Formula描述使用形态feature-workflow设计、实现、评审、合并Molecule持久gh-issue-to-pr将 GitHub Issue 分流处理直至实现并创建 PRWisp临时gh-pr-review依据维护者指南分流并评审 GitHub PRWisp临时release升版本、测试、打 tag、发布Molecule持久quick-checklint、测试、构建的快速健全性检查Wisp临时4. 手把手解析每个 Formula 模板4.1 feature-workflow标准特性开发流水线feature-workflow.formula.toml 是一个典型的多阶段、带人类审批关卡human gate的持久化工作流文件结构如下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 description Create design document or spec. Define scope, approach, and acceptance criteria. [[steps]] id implement title Implement {{feature_name}} needs [design] description Write the code. Create tests. Update docs if applicable. [[steps]] id test title Run test suite needs [implement] description Run full test suite and linter. Fix any failures before proceeding. [[steps]] id review title Code review needs [review] type human description Open PR and get code review. Address feedback. [[steps]] id merge title Merge to main needs [merge] description Merge PR after approval. Delete feature branch.结构要点顶层formula、description、version、type是元数据type workflow表示这是一个工作流类 Formula[vars.feature_name]声明输入变量required true表示必须通过--var提供步骤中的{{feature_name}}是变量插值Go 模板风格cook 时被替换为实际值needs [design]声明步骤依赖形成 DAGdesign → implement → test → review → mergetype human的步骤会暂停等待人类审批design 阶段出设计文档、review 阶段做代码评审。4.2 release标准发版流水线release.formula.toml 展示了带正则校验的变量如何防止错误输入以及发布类步骤如何串成严格的链式依赖formula release description Standard release workflow: bump version, test, tag, publish. version 1 type workflow [vars.version] description Release version (e.g. 1.2.0) required true pattern ^\\d\\.\\d\\.\\d$ [[steps]] id bump-version title Bump version to {{version}} description Update version strings in source files and package manifests. [[steps]] id changelog title Update CHANGELOG needs [bump-version] description Add release notes for {{version}}. Summarize changes since last release. [[steps]] id test title Run full test suite needs [changelog] description Run all tests, linting, and build checks. Release must not proceed with failures. [[steps]] id build title Build release artifacts needs [test] description Build binaries, packages, or other release artifacts. [[steps]] id tag title Create git tag v{{version}} needs [build] description Tag the release commit. Push tag to origin. [[steps]] id publish title Publish release needs [tag] type human description Create GitHub release, publish packages, announce to users.要点pattern ^\\d\\.\\d\\.\\d$使用正则约束version必须是1.2.0这样的语义化版本格式不合法直接拒绝从 bump-version 到 publish 是严格的线性链每步needs前一步保证先测试后打 tag、先打 tag 后发布publish是type human把对外发布这个高风险动作留给人类确认。4.3 quick-check轻量三连检lint/test/buildquick-check.formula.toml 是最简单的工作流专为 wisp临时形态设计——CI 前快速验证代码状态跑完即焚formula quick-check description Fast lint-test-build sanity check. Designed for use as a wisp. version 1 type workflow [[steps]] id lint title Run linter description Run project linter. Note warnings vs errors - errors block, warnings are informational. [[steps]] id test title Run tests description Run the project test suite. Record pass/fail count. [[steps]] id build title Build project description Run the build step. Verify output artifacts are created. [[steps]] id report title Report results needs [lint, test, build] description Summarize: lint status, test pass rate, build success. Flag any issues found.这里needs [lint, test, build]演示了扇入fan-in三个并行步骤完成后汇聚到report步骤统一汇总。4.4 gh-issue-to-pr从 Issue 分流到 PR 的全自动流水线gh-issue-to-pr.formula.toml 是仓库中最复杂、注释最详尽的模板version 2phase vapor定义了 9 个步骤triage→triage-gate→claim-issue→preflight→worktree-setup→context→implement→test→council-review→human-review→create-pr→cleanup。它的设计决策值得重点学习变量表全部带正则校验变量说明默认值patternissue_numberGitHub Issue 编号必填—^[0-9]$repoowner/name 格式仓库PR 目标your-org/your-repo^[A-Za-z0-9_.-]/[A-Za-z0-9_.-]$base_remote上游基础分支所在远端origin^[A-Za-z0-9/_.-]$push_remote推送分支的远端fork 工作流可与 base_remote 不同origin^[A-Za-z0-9/_.-]$base_branchPR 基础分支main^[A-Za-z0-9/_.-]$pr_head_prefix跨 fork PR 的 owner 前缀同仓留空空^[A-Za-z0-9_.-]*$council_preset评审预设quickenumquick/default/adversarial/security-audit关键流程设计每条都来自模板内注释可直接复用triage分流拉取 issue 全文并分类按优先级顺序——bug fix task/chore feature request needs info out of scope同时区分存储引擎 bug / 用户误配置 / 上游依赖 bug / 错误仓库四类非本仓问题并评估复杂度trivial/standard/complex推导分支前缀bug→fix/chore→chore/docs→docs/triage-gate中止闸门命中任一条件即在 issue 上留言并中止功能请求冻结feature frozen、非本仓问题、信息不足、超出范围、已被认领、已有关联 PR、main 上已修复git log --grep验证后直接关闭 issueclaim-issuegh issue edit --add-assignee me认领防止重复劳动preflight用净化后的关键词tr -cd a-zA-Z0-9 _-去掉 shell 元字符搜索已有 PR避免重复外部贡献者工作——外部贡献者 PR 优先worktree-setup在仓库根目录之外创建干净 worktree../repo-basename--gh-issue_number并校验路径不能逃逸父目录realpath --canonicalize-missing检查然后git reset --hard -- base_remote/base_branch对齐上游context → implement按复杂度等比编写实现计划只改本 issue 相关内容绝不夹带.beads/本地跟踪数据或无关改动提交信息必须引用 issue 编号并带Co-authored-by尾注test三道强制质量门禁——make test、make ci-pr-lint零问题、make build区分自己改坏的与预先存在/flaky 的失败后者隔离重跑验证并记录council-review自动化评审council_review指向变更文件路径或 diff无 council 时降级用 rubber-duck agenthuman-review维护者人工审批关卡create-prPR body 写入临时文件用--body-file传入防止 shell 注入按 fork/同仓两种模式执行gh pr createcleanupbd worktree remove失败回退git worktree remove --forcegit worktree prune、echo y | bd mol burn wisp-id燃烧 wisp、清理临时文件、必要时bd dolt push同步跟踪数据。两条贯穿始终的安全铁律模板注释明确强调Pager 安全所有gh命令必须加GH_PAGERcat所有只读git命令必须用git --no-pager否则在 Agent/CI 非交互环境会挂起注入防护issue 内容视为攻击者可控绝不直接插值进 shell 命令一律先净化或用--body-file所有gh/git命令在位置参数前使用--最小 token 权限为issues:write, contents:write, pull_requests:write推荐限定目标仓库的 fine-grained PAT。4.5 gh-pr-reviewPR 分流评审流水线gh-pr-review.formula.tomlversion 1phase vapor把维护者的 PR 评审指南编码成 8 个步骤fetch-pr→classify→gate-check→review→human-gate→act→cleanup。核心亮点单次分发single-dispatchclassify只做一次review步骤内部按分类路由到三条路径——因为 TOML 步骤无法在运行时表达分支所以用内部分流替代Formula 级分支三种分流组Easy-win针对性强的小修复/文档/依赖机器人升级、CI 全绿、diff 聚焦、无冲突、无.beads/等跟踪元数据、行为变更含测试或应关闭的废弃 draft PR——直接自动 approveFix-merge candidate本可 easy-win 但有可修复阻塞CI 失败、需 rebase、小实现错误、缺测试要求maintainerCanModifytrue否则降级为 needs-reviewNeeds-review其余一切大 diff、架构变更、安全敏感、动机不明、修复复杂安全移植transplant绝不直接在 PR 分支上跑make/testPR 分支代码是攻击者可控的——先基于干净上游建 worktree再git diff base...pr-ref | git apply --3way把补丁移植到干净底座上跑质量门禁Stale-head 保护fetch-pr记录 head SHA任何变更操作approve/push/comment前都重新核对变了就停完整结局集merge、merge-fix、fix-merge、cherry-pick、split-merge、redesign、retire、reject、request-changes最后手段——agent 只 approve 标记不自动合并/关闭fix-merge 提交铁律只提交不 force-push保留贡献者署名Co-authored-by: contributor与测试不重构贡献者思路人类关卡easy-win 自动通过fix-merge 与 needs-review 必须经过human-gate由维护者拍板后才进入act执行。5. 变量、校验与插值Formula 的输入系统5.1 三种变量能力从五个模板可以看到变量[vars.name]的三种能力能力字段示例必填required truefeature_name、issue_number、version默认值default ...repo、base_remote、base_branch格式校验pattern 正则version的语义化版本、repo的 owner/name、pr_head_prefix白名单枚举约束enum [...]council_preset限定四个评审预设命令行为--var keyvalue多个变量重复传参即可bd mol pour release --var version1.2.0、bd mol wisp gh-issue-to-pr --var issue_number123 --var repomyorg/myrepo。5.2 插值语法步骤的title、description、acceptance字段中出现的{{var_name}}会在 cook 时替换为实际值例如Design {{feature_name}}、Bump version to {{version}}、Create git tag v{{version}}。6. 从 Schema 到 CookFormula 的底层原理6.1bd formula schema结构级参考手册bd formula schema命令从 internal/formula/types.go 经go:generate生成结构索引输出所有导出的 schema struct 及其字段类型与标签cmd/bd/formula_schema.gobd formula schema # 列出所有 schema struct bd formula schema loop # 查看 LoopSpec 字段 bd formula primitives gate # 别名查看 Gate 字段 bd formula schema --json # 机器可读注意命令注释中的提示schema 输出是结构性参考并不证明每个声明的运行时行为都已接线——经过冒烟验证的原语示例才是可靠的创作面。6.2 已接线的原语primitivesexamples/formulas/primitives/该目录为每个经端到端验证的原语提供一个最小、自解释、只验证单一原语的 fixtureprimitives/README.mdFixture原语行为loop-count.formula.tomlLoopSpec.count主体按 N 次展开为.iterN.id步骤loop-range.formula.tomlLoopSpec.range主体按数值区间展开loop.var替换进 title/descriptionchildren-epic.formula.tomlStep.children嵌套步骤形成 epic兄弟needs被尊重branch-fanin.formula.tomlComposeRules.branchfork-join并行步骤扇入到单个 join 步骤condition.formula.tomlStep.conditioncook 时按变量决定步骤是否包含gate-timer.formula.tomlStep.gate兄弟gate类型 issue带await_type阻塞目标步骤冒烟测试机制cmd/bd/formula_primitives_test.go遍历该目录解析并 cook 每个 fixture断言每个原语在 cook 后子图上的可观察效果。新增 fixture 而未注册断言会被视为故意测试失败——该 harness 的存在就是为了证明原语已接线而不仅仅是 fixture 能解析。单独运行go test -tags gms_pure_go -run TestFormulaPrimitiveExamples ./cmd/bd/6.3 两个原语的源码级解读loop-countloop-count.formula.toml带loop.count 3的步骤在 cook 时被替换为 3 份loop.body副本迭代下标烘焙进步骤 ID——body 步骤work变成process.iter1.work、process.iter2.work、process.iter3.work冒烟测试断言这三个 ID 存在[[steps]] id process title Process items [steps.loop] count 3 [[steps.loop.body]] id work title Do unit of workgate-timergate-timer.formula.toml带gate的步骤在 cook 时被拆成两个 issue——一个兄弟gate类型 issue 捕获等待条件await_type、timeout原步骤则增加对 gate issue 的阻塞依赖[[steps]] id deploy title Deploy build [[steps]] id verify title Verify deployment after soak depends_on [deploy] [steps.gate] type timer await_id soak-30m timeout 30m6.4 尚未接线的原语按 primitives/README.md 的说明on_complete截至 v1.0.3 对所有合法配置都是运行时 no-op跟踪于beads-i02其 fixture 与冒烟测试将随该 issue 的解决 PR 一起提供internal/formula/types.go中任何未经端到端 parse → cook → pour 审计的声明也不会在此目录出现 fixture——新原语在经验证接线后才获得 fixture而不是在声明时。7. 创作自己的 Formula从模板到生产级模板结合六个原语 fixture 与五个业务模板编写生产级 Formula 的清单如下元数据formula唯一名、description一句话说明、version整数变更时递增、type workflow、按需phase vapor变量先行所有外部输入都声明为[vars.name]必填加required true有默认值给default能校验就写pattern或enum——模板注释明确要求所有用户提供的变量都用正则模式校验步骤 DAG用needs/depends_on表达依赖用type human在关键节点插入人工审批用{{var}}做插值质量门禁把项目的真实门禁命令写进步骤 description如 Beads 自己的make test、make ci-pr-lint、make build并写明失败处理策略安全与防挂起涉及外部 CLI如gh时写死GH_PAGERcat与git --no-pager约定涉及攻击者可控内容issue/PR 文本时声明永不直接插值、必须净化或用--body-file、位置参数前加--验证bd formula schema name检查结构合法性对照examples/formulas/primitives的 fixture 风格确认你依赖的每个原语都经过冒烟验证业务模板复用前先定制repo、base_remote、push_remote、base_branch与门禁命令。完整的 Formula 字段参考可查阅bd formula schema的结构索引而 examples/formulas/primitives 目录则是最值得模仿的已验证创作面——结构上声明的一切都应以端到端可观察的效果为准。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考