bd template 命令详解用 Beads 模板系统统一 issue 创建规范【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 的bd template命令体系用于管理 issue 模板为 bug、feature、epic 等常见 issue 类型提供预填充结构让团队能够以一致的格式快速创建规范 issue。本文以官方命令文档 template.md 为核心骨架完整讲解bd template list、show、create三个子命令、模板 YAML 文件格式、内置模板结构与自定义模板覆盖规则并结合仓库源码揭示模板系统从 YAML 文件模板到 Beads 原生模板proto/molecule的演进真相帮助读者在实战中正确选型。模板系统总览内置与自定义Templates模板为常见 issue 类型提供预填充结构加快创建格式一致、结构规范的 issue。模板分为两类内置模板Built-in由 bd 直接提供包括epic、bug、feature三种自定义模板Custom存放在项目内的.beads/templates/目录下以 YAML 文件形式存在。每个模板可以定义以下默认值字段说明Description 结构带占位符placeholder的描述骨架Issue 类型bug、feature、task、epic、chore之一优先级 Priority取值 0-4Labels创建 issue 时自动附加的标签Design notes 结构设计说明的骨架Acceptance criteria 结构验收标准的骨架命令速查bd template list # 列出全部可用模板内置 自定义 bd template show template-name # 查看某个模板的详细结构 bd template create template-name # 在 .beads/templates/ 下创建自定义模板三个子命令均支持--json标志便于脚本化、程序化调用。子命令详解list列出所有模板列出当前可用的全部模板内置与自定义bd template list bd template list --json输出示例$ bd template list Built-in Templates: epic Type: epic, Priority: P1 Labels: epic bug Type: bug, Priority: P1 Labels: bug feature Type: feature, Priority: P2 Labels: feature注意输出中显示的是文档约定的优先级记号P1/P2 等在 YAML 文件中实际以整数 0-4 存储其中 P1 对应数值 1、P2 对应数值 2详见下文模板文件格式。show查看模板详细结构查看指定模板的完整结构包括描述骨架、类型、优先级与标签bd template show template-name bd template show template-name --json输出示例$ bd template show bug Template: bug Type: bug Priority: P1 Labels: bug Description: ## Summary [Brief description of the bug] ## Steps to Reproduce ...create创建自定义模板在.beads/templates/目录下创建一个带默认结构的 YAML 模板文件之后可自由编辑定制bd template create template-name示例$ bd template create performance ✓ Created template: .beads/templates/performance.yaml Edit the file to customize your template. $ cat .beads/templates/performance.yaml name: performance description: |- [Describe the issue] ## Additional Context [Add relevant details] type: task priority: 2 labels: [] design: [Design notes] acceptance_criteria: |- - [ ] Acceptance criterion 1 - [ ] Acceptance criterion 2 # Edit the template to customize it $ vim .beads/templates/performance.yaml创建后即可用任意编辑器修改design字段是单行字符串description与acceptance_criteria使用 YAML 块标量|-/|保留多行结构与 Markdown 换行labels为空数组表示默认不附加任何标签。使用模板创建 issue通过--from-template标志文档约定用法模板最常见的用途是配合bd create快速创建格式统一的 issuebd create --from-template template-name Issue title模板中的默认值可以用显式标志覆盖# 使用 bug 模板但覆盖优先级 bd create --from-template bug Login crashes on special chars -p 0 # 使用 epic 模板并追加标签 bd create --from-template epic Q4 Infrastructure -l infrastructure,ops完整示例# 从 epic 模板创建 $ bd create --from-template epic Phase 3 Features ✓ Created issue: bd-a3f8e9 Title: Phase 3 Features Priority: P1 Status: open # 从 bug 模板创建 bug 报告 $ bd create --from-template bug Auth token validation fails ✓ Created issue: bd-42bc7a Title: Auth token validation fails Priority: P1 Status: open # 使用自定义模板 $ bd template create security-audit $ bd create --from-template security-audit Review authentication flow版本演进从 YAML 模板到 Beads 原生模板重要需要特别说明的是上文描述的 YAML 文件模板.beads/templates/*.yaml--from-template对应模板系统的早期形态。仓库内嵌的变更日志 cmd/bd/info.go 记录了 v0.30.5 的关键变化REMOVED: YAML simple template system ---from-templateflag removed frombd createREMOVED: Embedded templates (bug.yaml, epic.yaml, feature.yaml) - Use Beads templates insteadTemplates are now purely Beads-based - Create epic with template label, usebd template instantiate也就是说在当前版本中模板已全面迁移为 Beads 原生模板proto体系不再以磁盘 YAML 文件为载体而是以仓库内的 issue 图epic 子 issue 依赖关系作为模板本体通过template标签标记。v0.30.4 起引入了bd template instantiate用于从 Beads 模板实例化 issue。如果你仍在使用旧版 CLI.beads/templates/下的 YAML 模板与--from-template依然可用若使用新版本请参考下面的 Beads 模板工作流。现代用法Beads 模板proto / molecule / wisp从源码 cmd/bd/mol.go 可以看到模板在 Beads 中被称为proto原型其核心语义如下Proto未实例化的模板即一个带template标签的 epic issue定义一张可复用的工作 DAGMoleculeproto 被实例化spawn后产生的一组真实 issueWisp以临时ephemeral方式实例化的分子关闭后批量清理适合一次性任务Bond将 proto 与 proto、proto 与 molecule、molecule 与 molecule 组合成 compoundDistill从临时 epic 反向提炼出可复用的 proto。实例化命令bd mol pour proto-id --var keyvalue # 实例化 proto → 持久化 moleculeliquid 阶段 bd mol wisp proto-id --var keyvalue # 实例化 proto → 临时 wispvapor 阶段变量通过{{key}}占位符写在模板的标题、描述、设计说明、验收标准中实例化时以--var keyvalue传入并完成替换替换机制详见下文源码解析。这一体系同样具备自定义覆盖内置的能力自定义 proto 与内置模板同名时以自定义为准且自定义 proto 完全由项目内的 issue 数据承载天然可被bd的版本控制与同步能力管理。模板文件格式模板是遵循以下结构的 YAML 文件对应早期版本格式字段语义在 Beads 原生模板中一一对应到 issue 字段name: template-name description: | Multi-line description with placeholders ## Section heading [Placeholder text] type: bug|feature|task|epic|chore priority: 0-4 labels: - label1 - label2 design: | Design notes structure acceptance_criteria: | - [ ] Acceptance criterion 1 - [ ] Acceptance criterion 2字段说明字段类型说明namestring模板名称bd template show name时以此定位description多行字符串issue 描述骨架可用[占位符]标记待填写内容支持 Markdown 标题typeenum生成 issue 的类型bug、feature、task、epic、chorepriorityint优先级 0-4数值越小优先级越高0 为最高labelslist创建时自动附加的标签列表design多行字符串设计说明结构骨架acceptance_criteria多行字符串验收标准清单惯例使用- [ ]复选框在源码中这些字段与 issue 数据模型一一对应cloneSubgraphIntocmd/bd/template.go在克隆模板时逐个字段复制Title、Description、Design、AcceptanceCriteria、Notes、Priority、IssueType、Labels等属性并执行变量替换。内置模板epic面向由多个 issue 组成的大型特性。结构包含Overview and scope概览与范围Success criteria checklist成功标准清单Background and motivation背景与动机In-scope / out-of-scope sections范围内/范围外Architecture design notes架构设计说明Component breakdown组件拆分默认值TypeepicPriorityP1Labelsepic。bug面向结构统一的 bug 报告。结构包含Summary摘要Steps to reproduce复现步骤Expected vs actual behavior预期与实际行为Environment details环境详情Root cause analysis根因分析归入 designProposed fix建议修复方案Impact assessment影响评估默认值TypebugPriorityP1Labelsbug。feature面向特性请求与增强。结构包含Feature description特性描述Motivation and use cases动机与用例Proposed solution建议方案Alternatives considered备选方案Technical design技术设计API changesAPI 变更Testing strategy测试策略默认值TypefeaturePriorityP2Labelsfeature。自定义模板与覆盖规则自定义模板可以覆盖同名内置模板从而按项目需要定制内置模板的行为。优先级高到低自定义模板.beads/templates/或 Beads 原生体系中的自定义 proto内置模板覆盖 bug 模板的示例# 创建自定义 bug 模板 $ bd template create bug # 编辑以加入项目专属字段 $ cat .beads/templates/bug.yaml EOF name: bug description: | ## Bug Report **Severity:** [critical|high|medium|low] **Component:** [auth|api|frontend|backend] ## Description [Describe the bug] ## Reproduction 1. Step 1 2. Step 2 ## Impact [Who is affected? How many users?] type: bug priority: 0 labels: - bug - needs-triage design: | ## Investigation Notes [Technical details] acceptance_criteria: | - [ ] Bug fixed and verified - [ ] Tests added - [ ] Monitoring added EOF # 之后执行 bd create --from-template bug 时即使用你的自定义模板该示例展示了覆盖内置模板的典型做法保留type: bug语义但将优先级上调为 0最高追加needs-triage标签并加入 Severity/Component 等团队约定字段。JSON 输出所有模板命令支持--json标志供脚本与自动化流程调用$ bd template list --json [ { name: epic, description: ## Overview..., type: epic, priority: 1, labels: [epic], design: ## Architecture..., acceptance_criteria: - [ ] All child issues... } ] $ bd template show bug --json { name: bug, description: ## Summary..., type: bug, priority: 1, labels: [bug], design: ## Root Cause..., acceptance_criteria: - [ ] Bug no longer... }源码解析Beads 模板系统是如何工作的虽然早期 YAML 模板命令是文档层面的主要入口但当前仓库中模板系统的真实核心实现位于 cmd/bd/template.go理解它能帮助你把握模板机制的本质模板的标识template标签模板proto通过常量BeadsTemplateLabel template识别cmd/bd/template.go。任何 epic 打上template标签即成为可实例化的模板bd mol体系中的MoleculeLabel直接复用同一常量cmd/bd/mol.go印证了molecule 就是带工作流语义的模板这一设计。在测试中创建一个 proto 的惯例是bd create ... --type epic --labels template参见 cmd/bd/mol_bond_proxied_integration_test.go。子图加载TemplateSubgraph 与递归遍历loadTemplateSubgraphcmd/bd/template.go负责把模板 epic 及其全部后代加载为一个TemplateSubgraph根 issue、全部 issue、子图内依赖、ID 索引、变量定义、推荐阶段等。加载后代时采用双策略loadDescendantscmd/bd/template.go通过依赖记录查找显式的 parent-child 关系DepParentChild类型通过层级 ID 模式parentID.N如gt-abc.1兜底捕获缺失或错误依赖类型的子 issue——这意味着模板的树形结构既可由依赖关系表达也可由 ID 命名约定承载。两处都内置了环检测visited 集合GH#2719避免循环 parent-child 依赖导致无限递归。变量占位符与替换模板中的{{variable}}占位符由正则\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}匹配cmd/bd/template.goextractVariables提取文本中的变量并排除else、this、root、index、key、first、last等 Handlebars 控制关键字cmd/bd/template.goextractRequiredVariables结合公式formula的VarDefs判定哪些变量无默认值、必须由调用方提供未在 VarDefs 中声明的占位符视为面向 LLM 的文档性 Handlebars 而忽略substituteVariables将文本中的占位符替换为--var keyvalue传入的值未命中的占位符保持原样cmd/bd/template.go。从测试用例cmd/bd/template_test.go可以确认Release {{version}}配合version1.2.0会被替换为Release 1.2.0而缺失变量时占位符原样保留。这意味着你可以在描述里留下未提供值的占位符让创建后的 issue 仍保留待填标记。事务化克隆cloneSubgraph实例化的核心是cloneSubgraphcmd/bd/template.go它在单个事务内完成全部克隆第一轮遍历创建所有 issue新 issue 一律以StatusOpen开始标题、描述、设计、验收标准、Notes、AwaitID 全部做变量替换根 issue 可用--assignee覆盖负责人子 issue 保留模板原负责人RootOnly模式下仅创建根 issue第二轮遍历重建子图内的依赖关系并映射新旧 ID可选地执行原子挂载AttachToID在同一事务内把生成根挂到目标 molecule 下防止产生孤儿 issue。flattenUnregisteredIssueTypescmd/bd/template.go还负责类型白名单收敛若模板中出现未注册的自定义类型实例化时会降级为task有子节点的降级为epic并给出警告而不是悄悄扩充types.custom白名单——如需保留自定义类型应先用bd config set types.custom显式注册。模板查找按 ID 或标题解析resolveProtoIDOrTitlecmd/bd/template.go支持按 ID 或标题解析模板优先按 ID含部分 ID 前缀解析解析并校验template标签失败后按标题精确/不区分大小写/唯一部分匹配查找多命中时返回歧义错误并列出候选。这一能力让bd mol pour id的入参既可以是模板 ID 也可以是可读标题。最佳实践用模板保证一致性为团队常见 issue 类型建立统一约定杜绝每个 issue 一个格式的混乱定制内置模板覆盖内置模板以贴合团队工作流例如加入 Severity、Component 等专属字段将模板纳入版本控制提交.beads/templates/或 Beads 原生模板所在的 issue 数据以便全团队共享并与仓库同步保持模板聚焦创建特定用途模板如performance、security-audit避免大而全的通用模板善用占位符用[brackets]或TODO标记需要人工填写的章节实例化后一目了然使用复选框清单在描述与验收标准中使用- [ ]形成可勾选的动作项便于后续追踪完成度在新版本中优先使用 Beads 原生模板通过bd create --type epic --labels template构建 proto用bd mol pour/bd mol wisp实例化用--var keyvalue做参数化可获得与 issue 体系一致的版本控制、依赖管理与清理语义。参见bd create 命令 — 创建 issue 的完整参数与用法bd list 命令 — 列出 issueBeads Skill 总文档 — 主文档含 molecule/wisp 等高级主题cmd/bd/template.go — 模板子图加载、变量替换与克隆实现cmd/bd/mol.go — proto/molecule/wisp 命令体系与术语定义【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
bd template 命令详解用 Beads 模板系统统一 issue 创建规范【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 的bd template命令体系用于管理 issue 模板为 bug、feature、epic 等常见 issue 类型提供预填充结构让团队能够以一致的格式快速创建规范 issue。本文以官方命令文档 template.md 为核心骨架完整讲解bd template list、show、create三个子命令、模板 YAML 文件格式、内置模板结构与自定义模板覆盖规则并结合仓库源码揭示模板系统从 YAML 文件模板到 Beads 原生模板proto/molecule的演进真相帮助读者在实战中正确选型。模板系统总览内置与自定义Templates模板为常见 issue 类型提供预填充结构加快创建格式一致、结构规范的 issue。模板分为两类内置模板Built-in由 bd 直接提供包括epic、bug、feature三种自定义模板Custom存放在项目内的.beads/templates/目录下以 YAML 文件形式存在。每个模板可以定义以下默认值字段说明Description 结构带占位符placeholder的描述骨架Issue 类型bug、feature、task、epic、chore之一优先级 Priority取值 0-4Labels创建 issue 时自动附加的标签Design notes 结构设计说明的骨架Acceptance criteria 结构验收标准的骨架命令速查bd template list # 列出全部可用模板内置 自定义 bd template show template-name # 查看某个模板的详细结构 bd template create template-name # 在 .beads/templates/ 下创建自定义模板三个子命令均支持--json标志便于脚本化、程序化调用。子命令详解list列出所有模板列出当前可用的全部模板内置与自定义bd template list bd template list --json输出示例$ bd template list Built-in Templates: epic Type: epic, Priority: P1 Labels: epic bug Type: bug, Priority: P1 Labels: bug feature Type: feature, Priority: P2 Labels: feature注意输出中显示的是文档约定的优先级记号P1/P2 等在 YAML 文件中实际以整数 0-4 存储其中 P1 对应数值 1、P2 对应数值 2详见下文模板文件格式。show查看模板详细结构查看指定模板的完整结构包括描述骨架、类型、优先级与标签bd template show template-name bd template show template-name --json输出示例$ bd template show bug Template: bug Type: bug Priority: P1 Labels: bug Description: ## Summary [Brief description of the bug] ## Steps to Reproduce ...create创建自定义模板在.beads/templates/目录下创建一个带默认结构的 YAML 模板文件之后可自由编辑定制bd template create template-name示例$ bd template create performance ✓ Created template: .beads/templates/performance.yaml Edit the file to customize your template. $ cat .beads/templates/performance.yaml name: performance description: |- [Describe the issue] ## Additional Context [Add relevant details] type: task priority: 2 labels: [] design: [Design notes] acceptance_criteria: |- - [ ] Acceptance criterion 1 - [ ] Acceptance criterion 2 # Edit the template to customize it $ vim .beads/templates/performance.yaml创建后即可用任意编辑器修改design字段是单行字符串description与acceptance_criteria使用 YAML 块标量|-/|保留多行结构与 Markdown 换行labels为空数组表示默认不附加任何标签。使用模板创建 issue通过--from-template标志文档约定用法模板最常见的用途是配合bd create快速创建格式统一的 issuebd create --from-template template-name Issue title模板中的默认值可以用显式标志覆盖# 使用 bug 模板但覆盖优先级 bd create --from-template bug Login crashes on special chars -p 0 # 使用 epic 模板并追加标签 bd create --from-template epic Q4 Infrastructure -l infrastructure,ops完整示例# 从 epic 模板创建 $ bd create --from-template epic Phase 3 Features ✓ Created issue: bd-a3f8e9 Title: Phase 3 Features Priority: P1 Status: open # 从 bug 模板创建 bug 报告 $ bd create --from-template bug Auth token validation fails ✓ Created issue: bd-42bc7a Title: Auth token validation fails Priority: P1 Status: open # 使用自定义模板 $ bd template create security-audit $ bd create --from-template security-audit Review authentication flow版本演进从 YAML 模板到 Beads 原生模板重要需要特别说明的是上文描述的 YAML 文件模板.beads/templates/*.yaml--from-template对应模板系统的早期形态。仓库内嵌的变更日志 cmd/bd/info.go 记录了 v0.30.5 的关键变化REMOVED: YAML simple template system ---from-templateflag removed frombd createREMOVED: Embedded templates (bug.yaml, epic.yaml, feature.yaml) - Use Beads templates insteadTemplates are now purely Beads-based - Create epic with template label, usebd template instantiate也就是说在当前版本中模板已全面迁移为 Beads 原生模板proto体系不再以磁盘 YAML 文件为载体而是以仓库内的 issue 图epic 子 issue 依赖关系作为模板本体通过template标签标记。v0.30.4 起引入了bd template instantiate用于从 Beads 模板实例化 issue。如果你仍在使用旧版 CLI.beads/templates/下的 YAML 模板与--from-template依然可用若使用新版本请参考下面的 Beads 模板工作流。现代用法Beads 模板proto / molecule / wisp从源码 cmd/bd/mol.go 可以看到模板在 Beads 中被称为proto原型其核心语义如下Proto未实例化的模板即一个带template标签的 epic issue定义一张可复用的工作 DAGMoleculeproto 被实例化spawn后产生的一组真实 issueWisp以临时ephemeral方式实例化的分子关闭后批量清理适合一次性任务Bond将 proto 与 proto、proto 与 molecule、molecule 与 molecule 组合成 compoundDistill从临时 epic 反向提炼出可复用的 proto。实例化命令bd mol pour proto-id --var keyvalue # 实例化 proto → 持久化 moleculeliquid 阶段 bd mol wisp proto-id --var keyvalue # 实例化 proto → 临时 wispvapor 阶段变量通过{{key}}占位符写在模板的标题、描述、设计说明、验收标准中实例化时以--var keyvalue传入并完成替换替换机制详见下文源码解析。这一体系同样具备自定义覆盖内置的能力自定义 proto 与内置模板同名时以自定义为准且自定义 proto 完全由项目内的 issue 数据承载天然可被bd的版本控制与同步能力管理。模板文件格式模板是遵循以下结构的 YAML 文件对应早期版本格式字段语义在 Beads 原生模板中一一对应到 issue 字段name: template-name description: | Multi-line description with placeholders ## Section heading [Placeholder text] type: bug|feature|task|epic|chore priority: 0-4 labels: - label1 - label2 design: | Design notes structure acceptance_criteria: | - [ ] Acceptance criterion 1 - [ ] Acceptance criterion 2字段说明字段类型说明namestring模板名称bd template show name时以此定位description多行字符串issue 描述骨架可用[占位符]标记待填写内容支持 Markdown 标题typeenum生成 issue 的类型bug、feature、task、epic、chorepriorityint优先级 0-4数值越小优先级越高0 为最高labelslist创建时自动附加的标签列表design多行字符串设计说明结构骨架acceptance_criteria多行字符串验收标准清单惯例使用- [ ]复选框在源码中这些字段与 issue 数据模型一一对应cloneSubgraphIntocmd/bd/template.go在克隆模板时逐个字段复制Title、Description、Design、AcceptanceCriteria、Notes、Priority、IssueType、Labels等属性并执行变量替换。内置模板epic面向由多个 issue 组成的大型特性。结构包含Overview and scope概览与范围Success criteria checklist成功标准清单Background and motivation背景与动机In-scope / out-of-scope sections范围内/范围外Architecture design notes架构设计说明Component breakdown组件拆分默认值TypeepicPriorityP1Labelsepic。bug面向结构统一的 bug 报告。结构包含Summary摘要Steps to reproduce复现步骤Expected vs actual behavior预期与实际行为Environment details环境详情Root cause analysis根因分析归入 designProposed fix建议修复方案Impact assessment影响评估默认值TypebugPriorityP1Labelsbug。feature面向特性请求与增强。结构包含Feature description特性描述Motivation and use cases动机与用例Proposed solution建议方案Alternatives considered备选方案Technical design技术设计API changesAPI 变更Testing strategy测试策略默认值TypefeaturePriorityP2Labelsfeature。自定义模板与覆盖规则自定义模板可以覆盖同名内置模板从而按项目需要定制内置模板的行为。优先级高到低自定义模板.beads/templates/或 Beads 原生体系中的自定义 proto内置模板覆盖 bug 模板的示例# 创建自定义 bug 模板 $ bd template create bug # 编辑以加入项目专属字段 $ cat .beads/templates/bug.yaml EOF name: bug description: | ## Bug Report **Severity:** [critical|high|medium|low] **Component:** [auth|api|frontend|backend] ## Description [Describe the bug] ## Reproduction 1. Step 1 2. Step 2 ## Impact [Who is affected? How many users?] type: bug priority: 0 labels: - bug - needs-triage design: | ## Investigation Notes [Technical details] acceptance_criteria: | - [ ] Bug fixed and verified - [ ] Tests added - [ ] Monitoring added EOF # 之后执行 bd create --from-template bug 时即使用你的自定义模板该示例展示了覆盖内置模板的典型做法保留type: bug语义但将优先级上调为 0最高追加needs-triage标签并加入 Severity/Component 等团队约定字段。JSON 输出所有模板命令支持--json标志供脚本与自动化流程调用$ bd template list --json [ { name: epic, description: ## Overview..., type: epic, priority: 1, labels: [epic], design: ## Architecture..., acceptance_criteria: - [ ] All child issues... } ] $ bd template show bug --json { name: bug, description: ## Summary..., type: bug, priority: 1, labels: [bug], design: ## Root Cause..., acceptance_criteria: - [ ] Bug no longer... }源码解析Beads 模板系统是如何工作的虽然早期 YAML 模板命令是文档层面的主要入口但当前仓库中模板系统的真实核心实现位于 cmd/bd/template.go理解它能帮助你把握模板机制的本质模板的标识template标签模板proto通过常量BeadsTemplateLabel template识别cmd/bd/template.go。任何 epic 打上template标签即成为可实例化的模板bd mol体系中的MoleculeLabel直接复用同一常量cmd/bd/mol.go印证了molecule 就是带工作流语义的模板这一设计。在测试中创建一个 proto 的惯例是bd create ... --type epic --labels template参见 cmd/bd/mol_bond_proxied_integration_test.go。子图加载TemplateSubgraph 与递归遍历loadTemplateSubgraphcmd/bd/template.go负责把模板 epic 及其全部后代加载为一个TemplateSubgraph根 issue、全部 issue、子图内依赖、ID 索引、变量定义、推荐阶段等。加载后代时采用双策略loadDescendantscmd/bd/template.go通过依赖记录查找显式的 parent-child 关系DepParentChild类型通过层级 ID 模式parentID.N如gt-abc.1兜底捕获缺失或错误依赖类型的子 issue——这意味着模板的树形结构既可由依赖关系表达也可由 ID 命名约定承载。两处都内置了环检测visited 集合GH#2719避免循环 parent-child 依赖导致无限递归。变量占位符与替换模板中的{{variable}}占位符由正则\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}匹配cmd/bd/template.goextractVariables提取文本中的变量并排除else、this、root、index、key、first、last等 Handlebars 控制关键字cmd/bd/template.goextractRequiredVariables结合公式formula的VarDefs判定哪些变量无默认值、必须由调用方提供未在 VarDefs 中声明的占位符视为面向 LLM 的文档性 Handlebars 而忽略substituteVariables将文本中的占位符替换为--var keyvalue传入的值未命中的占位符保持原样cmd/bd/template.go。从测试用例cmd/bd/template_test.go可以确认Release {{version}}配合version1.2.0会被替换为Release 1.2.0而缺失变量时占位符原样保留。这意味着你可以在描述里留下未提供值的占位符让创建后的 issue 仍保留待填标记。事务化克隆cloneSubgraph实例化的核心是cloneSubgraphcmd/bd/template.go它在单个事务内完成全部克隆第一轮遍历创建所有 issue新 issue 一律以StatusOpen开始标题、描述、设计、验收标准、Notes、AwaitID 全部做变量替换根 issue 可用--assignee覆盖负责人子 issue 保留模板原负责人RootOnly模式下仅创建根 issue第二轮遍历重建子图内的依赖关系并映射新旧 ID可选地执行原子挂载AttachToID在同一事务内把生成根挂到目标 molecule 下防止产生孤儿 issue。flattenUnregisteredIssueTypescmd/bd/template.go还负责类型白名单收敛若模板中出现未注册的自定义类型实例化时会降级为task有子节点的降级为epic并给出警告而不是悄悄扩充types.custom白名单——如需保留自定义类型应先用bd config set types.custom显式注册。模板查找按 ID 或标题解析resolveProtoIDOrTitlecmd/bd/template.go支持按 ID 或标题解析模板优先按 ID含部分 ID 前缀解析解析并校验template标签失败后按标题精确/不区分大小写/唯一部分匹配查找多命中时返回歧义错误并列出候选。这一能力让bd mol pour id的入参既可以是模板 ID 也可以是可读标题。最佳实践用模板保证一致性为团队常见 issue 类型建立统一约定杜绝每个 issue 一个格式的混乱定制内置模板覆盖内置模板以贴合团队工作流例如加入 Severity、Component 等专属字段将模板纳入版本控制提交.beads/templates/或 Beads 原生模板所在的 issue 数据以便全团队共享并与仓库同步保持模板聚焦创建特定用途模板如performance、security-audit避免大而全的通用模板善用占位符用[brackets]或TODO标记需要人工填写的章节实例化后一目了然使用复选框清单在描述与验收标准中使用- [ ]形成可勾选的动作项便于后续追踪完成度在新版本中优先使用 Beads 原生模板通过bd create --type epic --labels template构建 proto用bd mol pour/bd mol wisp实例化用--var keyvalue做参数化可获得与 issue 体系一致的版本控制、依赖管理与清理语义。参见bd create 命令 — 创建 issue 的完整参数与用法bd list 命令 — 列出 issueBeads Skill 总文档 — 主文档含 molecule/wisp 等高级主题cmd/bd/template.go — 模板子图加载、变量替换与克隆实现cmd/bd/mol.go — proto/molecule/wisp 命令体系与术语定义【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
