Beadsbd formula命令完全指南从工作流模板到 molecule 的源层【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd formula是 Beads 中管理“工作流公式formula”的命令族——formula 是 molecule 模板的源层以 TOML/JSON 文件描述带组合规则的工作流经cook烹调成 proto 后再由pour液态、持久 molecule或wisp气态、临时任务实例化为实际工作。阅读本文后你将掌握公式的搜索路径与优先级、list/show/convert/schema四个子命令的完整用法并能够结合源码与仓库内置示例编写出含变量、依赖、门禁与组合规则的生产级.formula.toml文件。Formula 是什么molecule 模板的源层在 Beads 的工作流体系中formula 处于最顶层是一条清晰的流水线formula源层模板→ cook烹调为 proto→ pour / wisp实例化为工作正如 cmd/bd/formula.go 中命令的 Long 描述所言“Formulas are TOML/JSON files that define workflows with composition rules. Define formulas, cook them into protos, then pour or wisp them into work.” 公式负责描述工作流有哪些步骤、步骤间如何依赖、如何被组合真正落地执行时公式会被编译为 proto再由bd mol pour创建持久化 molecule或bd mol wisp创建一次性临时任务转换为实际工作项。Formula 文件支持两种格式.formula.toml推荐支持多行字符串、可读性强的 diff、内联注释.formula.json旧格式为向后兼容保留可通过bd formula convert迁移为 TOML。文件扩展名常量定义在 internal/formula/parser.goFormulaExtTOML .formula.toml、FormulaExtJSON .formula.json解析器会依据扩展名自动选择 TOML 或 JSON 解析器。四种公式类型公式的type字段决定了它的用途类型常量定义在 internal/formula/types.go类型用途典型场景workflow标准工作流模板有序步骤序列功能开发、发布流程expansion展开为多个步骤的宏“测试 静态检查 构建”这类公共模式aspect可施加到其他公式上的横切关注点追加日志步骤、追加审批门禁convoy协调并行 worker 的多智能体工作流多人代码评审、设计评审会话FormulaType.IsValid()internal/formula/types.go会在解析时校验类型合法性未知类型会在Validate()阶段报错。顶层字段一个公式文件的骨架根结构Formulainternal/formula/types.go定义了公式的顶层字段formula公式唯一标识/名称约定mol-name用于 molecule、exp-name用于 expansiondescription公式说明versionschema 版本当前为 1缺省时解析器自动补 1type上述四种类型之一缺省为workflowextends父公式列表继承机制见下文vars模板变量默认值 校验规则steps要创建的工作项templateexpansion 公式的模板步骤compose组合/绑定规则advice步骤变换规则before/after/aroundpointcutsaspect 公式的目标匹配模式phase推荐的实例化阶段liquid对应 pour、vapor对应 wisp若为vaporbd pour会提示改用bd mol wisppour是否将步骤物化为独立的子 issue 行依赖追踪/断点恢复pourtrue仅建议用于关键且低频的工作如发布patrol 类公式不应设置intent可选的调用方提示对 bd 不透明供下游工具消费。搜索路径公式从哪里来公式存放在固定的搜索路径中按优先级从高到低排列见 internal/formula/parser.go 的DefaultSearchPaths()实现resolved-beads-dir/formulas/当前项目优先级最高checkout-root/.beads/formulas/仓库本地公式~/.beads/formulas/用户级公式$GT_ROOT/.beads/formulas/共享工作区根仅在设置了GT_ROOT环境变量时生效路径解析有几个值得注意的实现细节项目级路径优先使用resolved beads 目录这样 worktree 与共享主仓库的.beads状态共用同一套公式注册表若尚未解析出 beads 项目则回退到cwd/.beads保证项目初始化前也能使用公式注册表仓库本地公式即使在活动 beads 数据库解析到父级/共享目录时也保持可发现这允许仓库直接随.beads/formulas/分发工作流无需每个维护者手动拷贝到~/.beads同一目录会被去重避免重复路径被重复搜索。Shadow 规则靠前路径中的同名公式会遮蔽shadow靠后路径中的公式。bd formula list的实现cmd/bd/formula.go使用seenmap 记录已出现的公式名靠前的路径优先进入结果列表同名的后续公式被跳过。bd formula list盘点所有可用公式list子命令遍历全部搜索路径列出所有可用公式。bd formula list [flags]参数与示例参数/标志说明--type string按类型过滤workflow、expansion、aspect、convoy--json以 JSON 格式输出全局标志bd formula list # 列出全部公式 bd formula list --json # JSON 格式输出 bd formula list --type workflow # 仅列 workflow 类型 bd formula list --type convoy # 仅列 convoy 类型输出与实现细节文本输出会先打印 Formulas (N found)然后按固定顺序workflow → expansion → aspect → convoy分组展示cmd/bd/formula.go。每个条目显示名称、截断到 60 字符的描述truncateDescription只取首行以及变量数量(N vars)。JSON 输出使用FormulaListEntry结构cmd/bd/formula.go包含name、type、description、source来源文件绝对路径、steps含子步骤的递归总数和vars字段便于脚本化处理。条目按名称字典序排序保证输出稳定。如果搜索路径下没有任何公式命令会打印No formulas found.并展示完整的搜索路径清单方便排查放置位置是否正确。bd formula show查看公式详情show子命令展示单个公式的完整结构是编写和调试公式时最常用的检视工具。bd formula show formula-name [flags]bd formula show shiny # 显示 shiny 公式详情 bd formula show rule-of-five # 显示 rule-of-five bd formula show security-audit --json # JSON 格式输出命令要求恰好一个位置参数cobra.ExactArgs(1)按名称通过parser.LoadByName(name)加载TOML 优先、JSON 回退。若加载失败会输出错误并在 stderr 打印全部搜索路径后以静默退出码结束cmd/bd/formula.go。展示内容show的文本输出依次呈现cmd/bd/formula.go元信息类型图标 名称、Type、Description、Source绝对路径Extends前缀的继承父公式列表Variables前缀按名称排序每个变量显示{{name}}、描述以及属性标注——required红色、default...、enum[a,b]、pattern...Steps前缀的步骤树使用├──/└──树形连接符递归打印依赖信息以[depends: ..., needs: ..., waits_for: ...]后缀标注非task类型的步骤会额外标注(type)printFormulaStepsTreeTemplate前缀expansion 公式的模板步骤树Advice前缀的 advice 规则格式为目标 → before: xxx, after: xxx, aroundComposition前缀依次展示 Bond Points含after step/before step定位、Expansionstarget → with、Mapsselect → with、AspectsPointcuts前缀aspect 公式的目标匹配规则glob、type、label。JSON 模式--json直接输出解析后的完整Formula对象适合与其他工具链集成。bd formula convertJSON 迁移到 TOMLconvert子命令把.formula.json公式转换为.formula.toml解决旧 JSON 格式的三大痛点多行字符串无需\n转义人类可读的 diff允许写注释。bd formula convert formula-name|path [--all] [flags]完整示例bd formula convert shiny # 转换 shiny.formula.json → .toml bd formula convert ./my.formula.json # 转换指定文件 bd formula convert --all # 转换全部 JSON 公式 bd formula convert shiny --delete # 转换并删除 JSON 源文件 bd formula convert shiny --stdout # 将 TOML 打印到 stdout不写文件标志一览标志说明--all转换所有搜索路径中的 JSON 公式--delete转换成功后删除 JSON 文件--stdout将 TOML 输出到 stdout 而非写入文件转换行为细节参数可传公式名如shiny通过findFormulaJSON在搜索路径中定位或直接的文件路径若参数已以.formula.toml结尾会直接报错提示“已经是 TOML 文件”转换过程并非简单的结构重排formulaToTOML它重新读取原始 JSON 为map[string]interface{}以保留结构并通过fixIntegerFieldscmd/bd/formula.go把 JSON 反序列化产生的float64数字修正为 TOML 需要的整数类型version、priority、count、max四个已知整数字段输出前还会做后处理convertToMultiLineStringscmd/bd/formula.go将description字段中带\n转义的字符串转换为 TOML 的多行字符串语法提升可读性--all模式会遍历全部搜索路径已存在.toml的文件会跳过⏭ Skipped (TOML exists)转换与删除进度逐条打印最后汇总Converted N formulas (M errors)转换生成的文件权限为0600原始 JSON 默认保留除非加--delete。bd formula schema可发现性索引bd formula schema别名bd formula primitives是公式作者发现“可在.formula.toml中声明哪些结构”的入口。它列出internal/formula包中所有导出的结构体“primitive”并展示字段名、类型与标签。bd formula schema [primitive] [flags] bd formula primitives name # 同义别名bd formula schema # 列出所有声明的公式结构 bd formula schema loop # 展示 LoopSpec 的字段、类型、标签 bd formula primitives gate # 别名展示 Gate 字段 bd formula schema --json # 机器可读索引该索引由 internal/formula/types.go 经go:generate生成到schema_gen.go结构定义即事实来源因此“列表不可能漂移”。从源码结构看PrimitiveByNameinternal/formula/schema.go支持大小写不敏感、忽略下划线/连字符的匹配并对Spec/Rules/Rule后缀做剥离回退所以bd formula schema loop能命中LoopSpec、gate能命中Gate。cmd/bd/formula_schema.go中明确说明schema 输出是结构性参考真正经过冒烟测试的可靠创作面是 examples/formulas/primitives/ 下的固化示例。编写你的第一个 formula变量、步骤与依赖仓库内置了大量可直接参考的示例examples/formulas/。以最简单的 examples/formulas/feature-workflow.formula.toml 为例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.变量vars定义与校验VarDefinternal/formula/types.go支持五个约束字段字段说明description变量用途说明default默认值为nil表示无默认被引用时必须提供required必须提供与 default 互斥Validate()会校验二者不能同时存在enum允许值列表pattern必须匹配的正则表达式type期望类型string默认、int、boolTOML 语法上变量有两种写法见VarDef.UnmarshalTOMLinternal/formula/types.go# 写法一简单字符串直接作为默认值 [vars] wisp_type patrol # 等价于 Default patrol # 写法二完整表格 [vars.component] description Component name required true变量在步骤标题/描述中以{{variable}}占位符引用正则\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}见 internal/formula/parser.go。实例化时ValidateVars校验必填变量与约束internal/formula/parser.go未提供必填值会返回包装了ErrVarValidation的错误ValidateProvidedVars只校验已提供值的 enum/pattern不把“完全缺席”当错误——调用方已对缺失变量给出更具体的提示时使用ApplyDefaults把未提供但有默认值的变量补全校验通过后由Substituteinternal/formula/parser.go完成占位符替换未解析的占位符原样保留。release.formula.toml展示了 pattern 校验的实战用法examples/formulas/release.formula.toml[vars.version] description Release version (e.g. 1.2.0) required true pattern ^\\d\\.\\d\\.\\d$步骤steps与依赖关系Stepinternal/formula/types.go是公式的基本工作单元除id、title、description、notes外关键字段包括typeissue 类型缺省为task支持bug、feature、epic、chore、decision、spike、story、milestone等内置类型或已注册的自定义类型未注册类型在 cook/pour 时被扁平化为task并给出警告priority优先级 0–4越界会在Validate()报错labels、metadata应用到创建 issue 的标签与元数据metadata 以 JSON 形式随 issue 携带供下游工具投影使用needs/depends_on步骤依赖二者等价cook 时合并引用不存在的步骤 ID 会触发校验错误waits_for扇出门类型——all-children等待全部动态子项、any-children等待第一个完成、children-of(step-id)等待指定步骤的子项cook 后对应 issue 会获得gate:value标签解析逻辑见 ParseWaitsForassignee默认指派对象支持变量替换condition基于变量的可选步骤条件支持{{var}}真值、!{{var}}取反、{{var}} value、{{var}} ! value四种格式在 cook/pour 时通过FilterStepsByCondition求值children嵌套子步骤用于构建 epic 层级expand/expand_vars在此内联展开某个 expansion 公式gate异步等待条件见下文loop迭代展开容器on_complete步骤完成时触发的运行时展开for-each 构造。quick-check示例展示了“并行依赖 汇总”的写法examples/formulas/quick-check.formula.toml前三个步骤互不依赖默认并行可执行最后的report步骤通过needs [lint, test, build]聚合三者结果。异步门禁Gate与循环LoopGateinternal/formula/types.go让步骤等待外部条件type支持gh:run、gh:pr、timer、human、mailawait_id是运行时条件标识直接映射到Issue.AwaitID作者推荐优先使用timeout指定等待时长如1h、24h用于升级处理repo可选指定 GitHub 仓库OWNER/REPO或HOST/OWNER/REPO为空默认当前 Git 仓库。设置 gate 后bd cook会创建一个阻塞该步骤的 gate issue关闭它bd close bd-xxx.gate-stepid才能解除阻塞。LoopSpecinternal/formula/types.go定义步骤体迭代count、until、range三者必选其一count固定迭代次数until结束条件如step.status complete需配合max防止无限循环range计算区间格式start..end端点可为整数1..10、表达式1..2^{disks}支持 - * / ^与括号cook 时求值或变量{start}..{count}var暴露给 body 步骤的当前迭代值例如var: move_numrange: 1..7会把{move_num}依次设为 1..7。组合规则extends、aspects 与 bond points公式支持多层组合extends继承Resolveinternal/formula/parser.go会递归解析父公式并合并——父级 vars 先继承子级同名覆盖、父级 steps 在前子级按 ID 覆盖替换、保持位置、compose 规则合并bond points 按 ID 覆盖hooks/expand/map 追加。解析器带环检测resolvingSet循环继承会报circular extends detected: a - b - a。aspects横切面compose.aspects列出要施加到本公式的 aspect 公式名如[security-audit, logging]。aspect 通过pointcutsglob/type/label 匹配目标步骤与advice规则before/after/around插入步骤支持{step.id}替换在其他公式的匹配步骤周围插入步骤在 expansion 之后应用。bond points绑定点compose.bond_points定义外部公式可以挂载的命名位置每个绑定点通过after_step互斥于before_step或before_step定位锚点步骤parallel: true让附加步骤与锚点步骤并行。另有两种自动挂载方式expand将 expansion 模板应用于单个目标步骤map用 glob如*.implement批量应用于所有匹配步骤hooks则按触发条件label:security、type:bug、priority:0-1自动附加公式。从公式到工作cook、pour 与 wisp编写好的公式不会直接执行而是经由bd的实例化命令落地bd cook把公式“烹调”为 proto编译产物进行变量求值、expansion 内联、aspect 应用、依赖图构建bd mol pour formula --var keyvalue按公式创建持久化 molecule——每个步骤物化为带依赖追踪的 issue 层级checkpoint 恢复能力适合 feature-workflow、release 这类长期跟踪的工作流bd mol wisp formula创建一次性临时任务适合 quick-check 这类短生命周期操作。以仓库内置公式为例examples/formulas/README.md# 安装公式到用户级所有项目可用 cp *.formula.toml ~/.beads/formulas/ # 或项目级仅当前项目可用 cp *.formula.toml /path/to/project/.beads/formulas/ bd formula list # 查看可用公式 bd mol pour release --var version1.2.0 # 以指定变量值浇铸 molecule其中gh-issue-to-pr、gh-pr-review这类高级 GitHub 工作流首次使用前需要按项目定制repo、remotes、base branch 变量与质量门禁命令。release公式建议配合phase vapor语义使用发布属操作性任务更贴合 wisp 的气态生命周期。小结bd formula命令族提供了公式生命周期的完整管理面list按优先级盘点搜索路径上的全部公式支持--type过滤与--json输出、show以树形结构呈现步骤与组合规则是编写/调试公式的核心工具、convert将遗留 JSON 公式无损迁移为更可读的 TOML保留原文件、支持--delete/--stdout/--all、schema别名primitives给出所有可声明结构的可发现性索引。配合 internal/formula/types.go 中定义的类型体系与 examples/formulas/ 下的五套示例模板你可以快速编写出具备变量校验、依赖编排、异步门禁、循环展开与横切组合能力的工作流公式再通过cook → pour/wisp将其转化为真实的生产工作流。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads `bd formula` 命令完全指南：从工作流模板到 molecule 的源层
Beadsbd formula命令完全指南从工作流模板到 molecule 的源层【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd formula是 Beads 中管理“工作流公式formula”的命令族——formula 是 molecule 模板的源层以 TOML/JSON 文件描述带组合规则的工作流经cook烹调成 proto 后再由pour液态、持久 molecule或wisp气态、临时任务实例化为实际工作。阅读本文后你将掌握公式的搜索路径与优先级、list/show/convert/schema四个子命令的完整用法并能够结合源码与仓库内置示例编写出含变量、依赖、门禁与组合规则的生产级.formula.toml文件。Formula 是什么molecule 模板的源层在 Beads 的工作流体系中formula 处于最顶层是一条清晰的流水线formula源层模板→ cook烹调为 proto→ pour / wisp实例化为工作正如 cmd/bd/formula.go 中命令的 Long 描述所言“Formulas are TOML/JSON files that define workflows with composition rules. Define formulas, cook them into protos, then pour or wisp them into work.” 公式负责描述工作流有哪些步骤、步骤间如何依赖、如何被组合真正落地执行时公式会被编译为 proto再由bd mol pour创建持久化 molecule或bd mol wisp创建一次性临时任务转换为实际工作项。Formula 文件支持两种格式.formula.toml推荐支持多行字符串、可读性强的 diff、内联注释.formula.json旧格式为向后兼容保留可通过bd formula convert迁移为 TOML。文件扩展名常量定义在 internal/formula/parser.goFormulaExtTOML .formula.toml、FormulaExtJSON .formula.json解析器会依据扩展名自动选择 TOML 或 JSON 解析器。四种公式类型公式的type字段决定了它的用途类型常量定义在 internal/formula/types.go类型用途典型场景workflow标准工作流模板有序步骤序列功能开发、发布流程expansion展开为多个步骤的宏“测试 静态检查 构建”这类公共模式aspect可施加到其他公式上的横切关注点追加日志步骤、追加审批门禁convoy协调并行 worker 的多智能体工作流多人代码评审、设计评审会话FormulaType.IsValid()internal/formula/types.go会在解析时校验类型合法性未知类型会在Validate()阶段报错。顶层字段一个公式文件的骨架根结构Formulainternal/formula/types.go定义了公式的顶层字段formula公式唯一标识/名称约定mol-name用于 molecule、exp-name用于 expansiondescription公式说明versionschema 版本当前为 1缺省时解析器自动补 1type上述四种类型之一缺省为workflowextends父公式列表继承机制见下文vars模板变量默认值 校验规则steps要创建的工作项templateexpansion 公式的模板步骤compose组合/绑定规则advice步骤变换规则before/after/aroundpointcutsaspect 公式的目标匹配模式phase推荐的实例化阶段liquid对应 pour、vapor对应 wisp若为vaporbd pour会提示改用bd mol wisppour是否将步骤物化为独立的子 issue 行依赖追踪/断点恢复pourtrue仅建议用于关键且低频的工作如发布patrol 类公式不应设置intent可选的调用方提示对 bd 不透明供下游工具消费。搜索路径公式从哪里来公式存放在固定的搜索路径中按优先级从高到低排列见 internal/formula/parser.go 的DefaultSearchPaths()实现resolved-beads-dir/formulas/当前项目优先级最高checkout-root/.beads/formulas/仓库本地公式~/.beads/formulas/用户级公式$GT_ROOT/.beads/formulas/共享工作区根仅在设置了GT_ROOT环境变量时生效路径解析有几个值得注意的实现细节项目级路径优先使用resolved beads 目录这样 worktree 与共享主仓库的.beads状态共用同一套公式注册表若尚未解析出 beads 项目则回退到cwd/.beads保证项目初始化前也能使用公式注册表仓库本地公式即使在活动 beads 数据库解析到父级/共享目录时也保持可发现这允许仓库直接随.beads/formulas/分发工作流无需每个维护者手动拷贝到~/.beads同一目录会被去重避免重复路径被重复搜索。Shadow 规则靠前路径中的同名公式会遮蔽shadow靠后路径中的公式。bd formula list的实现cmd/bd/formula.go使用seenmap 记录已出现的公式名靠前的路径优先进入结果列表同名的后续公式被跳过。bd formula list盘点所有可用公式list子命令遍历全部搜索路径列出所有可用公式。bd formula list [flags]参数与示例参数/标志说明--type string按类型过滤workflow、expansion、aspect、convoy--json以 JSON 格式输出全局标志bd formula list # 列出全部公式 bd formula list --json # JSON 格式输出 bd formula list --type workflow # 仅列 workflow 类型 bd formula list --type convoy # 仅列 convoy 类型输出与实现细节文本输出会先打印 Formulas (N found)然后按固定顺序workflow → expansion → aspect → convoy分组展示cmd/bd/formula.go。每个条目显示名称、截断到 60 字符的描述truncateDescription只取首行以及变量数量(N vars)。JSON 输出使用FormulaListEntry结构cmd/bd/formula.go包含name、type、description、source来源文件绝对路径、steps含子步骤的递归总数和vars字段便于脚本化处理。条目按名称字典序排序保证输出稳定。如果搜索路径下没有任何公式命令会打印No formulas found.并展示完整的搜索路径清单方便排查放置位置是否正确。bd formula show查看公式详情show子命令展示单个公式的完整结构是编写和调试公式时最常用的检视工具。bd formula show formula-name [flags]bd formula show shiny # 显示 shiny 公式详情 bd formula show rule-of-five # 显示 rule-of-five bd formula show security-audit --json # JSON 格式输出命令要求恰好一个位置参数cobra.ExactArgs(1)按名称通过parser.LoadByName(name)加载TOML 优先、JSON 回退。若加载失败会输出错误并在 stderr 打印全部搜索路径后以静默退出码结束cmd/bd/formula.go。展示内容show的文本输出依次呈现cmd/bd/formula.go元信息类型图标 名称、Type、Description、Source绝对路径Extends前缀的继承父公式列表Variables前缀按名称排序每个变量显示{{name}}、描述以及属性标注——required红色、default...、enum[a,b]、pattern...Steps前缀的步骤树使用├──/└──树形连接符递归打印依赖信息以[depends: ..., needs: ..., waits_for: ...]后缀标注非task类型的步骤会额外标注(type)printFormulaStepsTreeTemplate前缀expansion 公式的模板步骤树Advice前缀的 advice 规则格式为目标 → before: xxx, after: xxx, aroundComposition前缀依次展示 Bond Points含after step/before step定位、Expansionstarget → with、Mapsselect → with、AspectsPointcuts前缀aspect 公式的目标匹配规则glob、type、label。JSON 模式--json直接输出解析后的完整Formula对象适合与其他工具链集成。bd formula convertJSON 迁移到 TOMLconvert子命令把.formula.json公式转换为.formula.toml解决旧 JSON 格式的三大痛点多行字符串无需\n转义人类可读的 diff允许写注释。bd formula convert formula-name|path [--all] [flags]完整示例bd formula convert shiny # 转换 shiny.formula.json → .toml bd formula convert ./my.formula.json # 转换指定文件 bd formula convert --all # 转换全部 JSON 公式 bd formula convert shiny --delete # 转换并删除 JSON 源文件 bd formula convert shiny --stdout # 将 TOML 打印到 stdout不写文件标志一览标志说明--all转换所有搜索路径中的 JSON 公式--delete转换成功后删除 JSON 文件--stdout将 TOML 输出到 stdout 而非写入文件转换行为细节参数可传公式名如shiny通过findFormulaJSON在搜索路径中定位或直接的文件路径若参数已以.formula.toml结尾会直接报错提示“已经是 TOML 文件”转换过程并非简单的结构重排formulaToTOML它重新读取原始 JSON 为map[string]interface{}以保留结构并通过fixIntegerFieldscmd/bd/formula.go把 JSON 反序列化产生的float64数字修正为 TOML 需要的整数类型version、priority、count、max四个已知整数字段输出前还会做后处理convertToMultiLineStringscmd/bd/formula.go将description字段中带\n转义的字符串转换为 TOML 的多行字符串语法提升可读性--all模式会遍历全部搜索路径已存在.toml的文件会跳过⏭ Skipped (TOML exists)转换与删除进度逐条打印最后汇总Converted N formulas (M errors)转换生成的文件权限为0600原始 JSON 默认保留除非加--delete。bd formula schema可发现性索引bd formula schema别名bd formula primitives是公式作者发现“可在.formula.toml中声明哪些结构”的入口。它列出internal/formula包中所有导出的结构体“primitive”并展示字段名、类型与标签。bd formula schema [primitive] [flags] bd formula primitives name # 同义别名bd formula schema # 列出所有声明的公式结构 bd formula schema loop # 展示 LoopSpec 的字段、类型、标签 bd formula primitives gate # 别名展示 Gate 字段 bd formula schema --json # 机器可读索引该索引由 internal/formula/types.go 经go:generate生成到schema_gen.go结构定义即事实来源因此“列表不可能漂移”。从源码结构看PrimitiveByNameinternal/formula/schema.go支持大小写不敏感、忽略下划线/连字符的匹配并对Spec/Rules/Rule后缀做剥离回退所以bd formula schema loop能命中LoopSpec、gate能命中Gate。cmd/bd/formula_schema.go中明确说明schema 输出是结构性参考真正经过冒烟测试的可靠创作面是 examples/formulas/primitives/ 下的固化示例。编写你的第一个 formula变量、步骤与依赖仓库内置了大量可直接参考的示例examples/formulas/。以最简单的 examples/formulas/feature-workflow.formula.toml 为例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.变量vars定义与校验VarDefinternal/formula/types.go支持五个约束字段字段说明description变量用途说明default默认值为nil表示无默认被引用时必须提供required必须提供与 default 互斥Validate()会校验二者不能同时存在enum允许值列表pattern必须匹配的正则表达式type期望类型string默认、int、boolTOML 语法上变量有两种写法见VarDef.UnmarshalTOMLinternal/formula/types.go# 写法一简单字符串直接作为默认值 [vars] wisp_type patrol # 等价于 Default patrol # 写法二完整表格 [vars.component] description Component name required true变量在步骤标题/描述中以{{variable}}占位符引用正则\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}见 internal/formula/parser.go。实例化时ValidateVars校验必填变量与约束internal/formula/parser.go未提供必填值会返回包装了ErrVarValidation的错误ValidateProvidedVars只校验已提供值的 enum/pattern不把“完全缺席”当错误——调用方已对缺失变量给出更具体的提示时使用ApplyDefaults把未提供但有默认值的变量补全校验通过后由Substituteinternal/formula/parser.go完成占位符替换未解析的占位符原样保留。release.formula.toml展示了 pattern 校验的实战用法examples/formulas/release.formula.toml[vars.version] description Release version (e.g. 1.2.0) required true pattern ^\\d\\.\\d\\.\\d$步骤steps与依赖关系Stepinternal/formula/types.go是公式的基本工作单元除id、title、description、notes外关键字段包括typeissue 类型缺省为task支持bug、feature、epic、chore、decision、spike、story、milestone等内置类型或已注册的自定义类型未注册类型在 cook/pour 时被扁平化为task并给出警告priority优先级 0–4越界会在Validate()报错labels、metadata应用到创建 issue 的标签与元数据metadata 以 JSON 形式随 issue 携带供下游工具投影使用needs/depends_on步骤依赖二者等价cook 时合并引用不存在的步骤 ID 会触发校验错误waits_for扇出门类型——all-children等待全部动态子项、any-children等待第一个完成、children-of(step-id)等待指定步骤的子项cook 后对应 issue 会获得gate:value标签解析逻辑见 ParseWaitsForassignee默认指派对象支持变量替换condition基于变量的可选步骤条件支持{{var}}真值、!{{var}}取反、{{var}} value、{{var}} ! value四种格式在 cook/pour 时通过FilterStepsByCondition求值children嵌套子步骤用于构建 epic 层级expand/expand_vars在此内联展开某个 expansion 公式gate异步等待条件见下文loop迭代展开容器on_complete步骤完成时触发的运行时展开for-each 构造。quick-check示例展示了“并行依赖 汇总”的写法examples/formulas/quick-check.formula.toml前三个步骤互不依赖默认并行可执行最后的report步骤通过needs [lint, test, build]聚合三者结果。异步门禁Gate与循环LoopGateinternal/formula/types.go让步骤等待外部条件type支持gh:run、gh:pr、timer、human、mailawait_id是运行时条件标识直接映射到Issue.AwaitID作者推荐优先使用timeout指定等待时长如1h、24h用于升级处理repo可选指定 GitHub 仓库OWNER/REPO或HOST/OWNER/REPO为空默认当前 Git 仓库。设置 gate 后bd cook会创建一个阻塞该步骤的 gate issue关闭它bd close bd-xxx.gate-stepid才能解除阻塞。LoopSpecinternal/formula/types.go定义步骤体迭代count、until、range三者必选其一count固定迭代次数until结束条件如step.status complete需配合max防止无限循环range计算区间格式start..end端点可为整数1..10、表达式1..2^{disks}支持 - * / ^与括号cook 时求值或变量{start}..{count}var暴露给 body 步骤的当前迭代值例如var: move_numrange: 1..7会把{move_num}依次设为 1..7。组合规则extends、aspects 与 bond points公式支持多层组合extends继承Resolveinternal/formula/parser.go会递归解析父公式并合并——父级 vars 先继承子级同名覆盖、父级 steps 在前子级按 ID 覆盖替换、保持位置、compose 规则合并bond points 按 ID 覆盖hooks/expand/map 追加。解析器带环检测resolvingSet循环继承会报circular extends detected: a - b - a。aspects横切面compose.aspects列出要施加到本公式的 aspect 公式名如[security-audit, logging]。aspect 通过pointcutsglob/type/label 匹配目标步骤与advice规则before/after/around插入步骤支持{step.id}替换在其他公式的匹配步骤周围插入步骤在 expansion 之后应用。bond points绑定点compose.bond_points定义外部公式可以挂载的命名位置每个绑定点通过after_step互斥于before_step或before_step定位锚点步骤parallel: true让附加步骤与锚点步骤并行。另有两种自动挂载方式expand将 expansion 模板应用于单个目标步骤map用 glob如*.implement批量应用于所有匹配步骤hooks则按触发条件label:security、type:bug、priority:0-1自动附加公式。从公式到工作cook、pour 与 wisp编写好的公式不会直接执行而是经由bd的实例化命令落地bd cook把公式“烹调”为 proto编译产物进行变量求值、expansion 内联、aspect 应用、依赖图构建bd mol pour formula --var keyvalue按公式创建持久化 molecule——每个步骤物化为带依赖追踪的 issue 层级checkpoint 恢复能力适合 feature-workflow、release 这类长期跟踪的工作流bd mol wisp formula创建一次性临时任务适合 quick-check 这类短生命周期操作。以仓库内置公式为例examples/formulas/README.md# 安装公式到用户级所有项目可用 cp *.formula.toml ~/.beads/formulas/ # 或项目级仅当前项目可用 cp *.formula.toml /path/to/project/.beads/formulas/ bd formula list # 查看可用公式 bd mol pour release --var version1.2.0 # 以指定变量值浇铸 molecule其中gh-issue-to-pr、gh-pr-review这类高级 GitHub 工作流首次使用前需要按项目定制repo、remotes、base branch 变量与质量门禁命令。release公式建议配合phase vapor语义使用发布属操作性任务更贴合 wisp 的气态生命周期。小结bd formula命令族提供了公式生命周期的完整管理面list按优先级盘点搜索路径上的全部公式支持--type过滤与--json输出、show以树形结构呈现步骤与组合规则是编写/调试公式的核心工具、convert将遗留 JSON 公式无损迁移为更可读的 TOML保留原文件、支持--delete/--stdout/--all、schema别名primitives给出所有可声明结构的可发现性索引。配合 internal/formula/types.go 中定义的类型体系与 examples/formulas/ 下的五套示例模板你可以快速编写出具备变量校验、依赖编排、异步门禁、循环展开与横切组合能力的工作流公式再通过cook → pour/wisp将其转化为真实的生产工作流。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
