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 創建規范
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），僅供參考