Fabric 模式实战：create_bd_issue 将自然语言需求自动转化为高质量 bd create 问题单命令

create_bd_issue 是 Fabric 开源项目 data/patterns/ 目录下的一款 DEVELOPMENT 类 AI 模式（system prompt），其核心能力是把一段口语化的需求描述自动翻译成一条格式规范、字段齐全的 bd create 建单命令，供 bd（Beads）问题跟踪器直接执行。阅读本文后，你将完整掌握该模式的全部旗标语义、类型/优先级判定规则、标签选择策略与输出约束，并学会在 Fabric 中调用它，让 AI 从一句话直接产出可用的 Issue 命令。

一、先认识 create_bd_issue 这个模式

该模式全文位于 data/patterns/create_bd_issue/system.md，属于 Fabric「先定义任务（Patterns）、再调用模型执行」设计范式中的系统提示词文件。模式以一个明确的身份设定开场：

You are an expert at transforming natural language issue descriptions into optimal bd create commands. You understand the bd (Beads) issue tracker deeply and always select the most appropriate flags based on the user's intent.

其目标非常收敛：产出一条经过精心设计、承载了全部有效信息且符合 bd 最佳实践的 bd create 命令，而不是一段解释或一段描述文本。

从仓库中可以交叉印证该模式的定位：

• CHANGELOG.md 记录其由 PR #1948 引入："Added create_bd_issue pattern that transforms natural language issue descriptions into optimal bd (Beads) issue tracker commands"；
• scripts/pattern_descriptions/pattern_descriptions.json 将其描述为 "Transform natural language descriptions into optimal bd create commands for issue tracking"，归类标签为 DEVELOPMENT；
• data/patterns/pattern_explanations.md 的第 58 条解释与上述描述一致。

它与另一款模式 data/patterns/extract_bd_ideas/system.md 形成上下游配合：extract_bd_ideas 负责从播客、文章等长内容中提炼出可执行的 idea，而 create_bd_issue 则把已有的一段需求文本直接压实成一条建单命令。若你在使用时有“这段需求到底是 bug、feature 还是 chore”的困惑，还可以参考 data/patterns/suggest_pattern/system.md 这类“先选模式再干活”的调度思路。

二、在 Fabric 中如何调用这个模式

Fabric 的模式存储在 data/patterns/ 目录下，每个模式目录内含 system.md（以及可选的 user.md），运行时把文件内容拼入模型上下文。加载逻辑可见 internal/tools/patterns_loader.go：默认从 Fabric 仓库的 data/patterns 目录拉取，目录名即模式名。

调用 create_bd_issue 最直接的方式是使用命令行模式选择旗标（Fabric CLI 支持 --pattern/-p，参见 internal/cli/flags_test.go）：

# 把自然语言需求作为参数传入
fabric -p create_bd_issue "login is broken on production, fix it urgently"

# 或通过标准输入管道传入
echo "We need to add dark mode to the settings page" | fabric -p create_bd_issue

也可以在 internal/cli/README.md 介绍的 YAML 配置中固化模式选择，避免每次手输旗标：

# ~/.config/fabric/config.yaml
model: gpt-4
pattern: create_bd_issue
stream: true

这样后续只需提供需求文本，Fabric 便会加载该模式将文本转换为 bd create 命令输出。注意：bd（Beads）本身是一个外部问题跟踪 CLI，并不在本仓库内；本模式的价值在于让 AI 充当“命令翻译器”，替你完成需求到建单命令的字段编排。

三、bd create 命令旗标全参考

模式内置了一份完整的 bd create 旗标参考表，理解它是读懂后续“输入 → 命令”映射规则的前提。基础旗标如下：

旗标	参数	含义与约束
--title "string" 或首个位置参数	string	Issue 标题，使用祈使语气（"Add..." / "Fix..." / "Update..."）
-d, --description "string"	string	描述：上下文、验收标准、备注
-t, --type TYPE	bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event	类型枚举，默认 task
-p, --priority P0-P4	P0|P1|P2|P3|P4	P0=严重，P1=高，P2=普通（默认），P3=低，P4=愿望清单
-l, --labels strings	逗号分隔	例如 ux,backend,docs
-a, --assignee string	string	负责该任务的人
-e, --estimate int	int	预估耗时（分钟）
--due string	日期表达式	如 +6h、+1d、+2w、tomorrow、next monday、2025-01-15
--defer string	日期表达式	在此之前隐藏，格式同 --due
--deps strings	string	依赖，如 'bd-20' 或 'blocks:bd-15'
--parent string	string	作为某个父 Issue 的层级子任务
--acceptance string	string	验收标准
--design string	string	设计说明
--notes string	string	附加备注
--external-ref string	string	外部引用，如 'gh-9'、'jira-ABC'
--ephemeral	布尔	标记为临时项（不参与导出）
--prefix string / --rig string	string	在指定 rig 中创建
--repo string	string	Issue 的目标仓库

除通用旗标外，bd 还针对特殊 Issue 类型提供类型专属旗标：

类型	专属旗标
Molecule	--mol-type swarm|patrol|work
Agent	--agent-rig string、--role-type polecat|crew|witness|refinery|mayor|deacon
Event	--event-actor string、--event-category string、--event-payload string、--event-target string
Gate	--waits-for string、--waits-for-gate all-children|any-children

四、解析输入时的信息维度

模式要求模型先「拆解输入」，而不是拿到文本就拼命令。它定义了 7 个解析维度：

1. 核心诉求：到底要做什么（核心动作 / 修复 / 新特性）；
2. 上下文背景：相关说明或前置信息；
3. 紧急程度信号：文本中出现的 URGENT、production down 等措辞；
4. 技术领域：用于推断标签归属（前端、后端、数据库等）；
5. 时间约束：due、deadline 相关的表述；
6. 依赖或阻塞：是否存在前驱任务或被阻塞关系；
7. 验收标准：如何判定完成。

这一步骤直接决定了后续类型、优先级、标签与各旗标的选择，是全流程正确性的根基。

五、Issue 类型判定：bug / feature / task / epic / chore

模式给出了一套直白的判别口径，并对“非默认类型优先显式声明”有明确要求：

• bug：某物已损坏（Something is broken）；
• feature：新的能力（New capability）；
• task：需要完成的某项工作（Work that needs doing）；
• epic：大型、多部分组成的庞大工程（Large multi-part effort）；
• chore：维护 / 清理类事务（Maintenance/cleanup）。

由于 -t 的默认值是 task，当判定结果不是 task 时，模式会要求显式写出类型旗标（见第八节的输出顺序规则），避免建单后类型失真。

六、优先级评估：P0 到 P4 的五级刻度

优先级是「紧急程度信号」的量化出口，对应 bd 的 P0–P4 五级体系：

• P0：生产环境宕机、安全漏洞、数据丢失（Production down, security breach, data loss）；
• P1：主要功能损坏、阻塞发版（Major functionality broken, blocking release）；
• P2：常规工作（Standard work，默认值）；
• P3：锦上添花、可以等待（Nice to have, can wait）；
• P4：某天或许、纯想法（Someday/maybe, ideas）。

由于默认值是 P2，模式规定仅当优先级不是 P2 时才输出 -p 旗标，与“跳过默认值”的整体原则保持一致。

七、标签选择：领域 + 类别 + 规模的组合

标签用于补充分类信息，模式要求限制在 1–4 个，避免噪音。标签体系分成三组：

• 领域 Domain：frontend、backend、api、db、infra、mobile；
• 类别 Category：ux、perf、security、docs、tech-debt；
• 规模 Size：quick-win、spike、refactor。

选择时只保留“能带来分类价值”的标签，即 -l 仅当其确实改善检索与筛选时输出。典型组合是“一个领域 + 一个类别”，如示例中的 ux,frontend、docs,api。

八、构造命令与输出格式的硬性规范

命令构造层面，模式给出两条具体准则：

• 标题：控制在 3–8 个词，使用祈使语气（imperative mood）；
• 描述：复杂时才写 1–3 句；只包含有增量价值的旗标，跳过默认值。

输出层面，由于本模式面向“直接可用、可直接粘贴执行”的命令产物，约束非常严格：

• 只输出那一条 bd create 命令，别无其他内容；
• 不要 markdown 代码块，不要解释，不要警告；
• 所有字符串值使用双引号；值内部若有引号，用反斜杠转义；
• 描述短则用 -d；描述很长时，建议改用 --body-file；
• 非 task 类型优先显式标注类型；
• 优先级不是 P2 时才带上 -p；
• 标签只在有分类价值时附带；
• 旗标顺序固定为：type → priority → labels → 其余旗标。

这套顺序约定保证不同输入产出的命令风格一致，方便在终端历史、脚本与 Issue 归档中进行统一化检索。

九、六类典型输入示例拆解

模式附带 6 个“输入 → 输出”示例，可作为理解上述规则的活教材：

输入（自然语言）	输出（bd create 命令）	判读逻辑
"We need to add dark mode to the settings page"	bd create "Add dark mode to settings page" -t feature -l ux,frontend	新增能力 → feature；领域 frontend + 类别 ux
"URGENT: login is broken on production"	bd create "Fix broken login on production" -t bug -p P0 -d "Login functionality is completely broken in production environment"	broken → bug；URGENT + production → P0；描述承载上下文
"maybe someday we could add keyboard shortcuts"	bd create "Add keyboard shortcuts" -t feature -p P4 -l ux	"maybe someday" 弱愿望 → feature + P4；类别 ux
"need to update the deps before next week"	bd create "Update dependencies" -t chore --due "next week"	维护工作 → chore；时间约束 → --due
"the api docs are missing the new v2 endpoints, john should handle it"	bd create "Document v2 API endpoints" -t task -l docs,api -a john	补文档属常规工作 → task；labels=docs,api；明确负责人 → -a john
"track time spent on customer dashboard - estimate about 2 hours"	bd create "Track time spent on customer dashboard" -e 120 -l analytics	2 小时 → -e 120（分钟）；附加领域标签 analytics

对照示例可以观察到的共性规律：

• 标题均被改写成祈使语气，且压缩到 3–8 个词；
• 每个输出都严格遵循 type → priority → labels → others 的旗标顺序；
• 优先级为 P2（默认）的用例一律不带 -p；
• 依赖、assignee、estimate、due 等信号只在该信号确实出现在输入中时才被翻译成对应旗标。

十、实战要点与边界

将本模式投入日常工作流时，以下几点值得注意：

1. 输入越结构化，产出越精确：把背景、截止时间、负责人、验收标准写进一句话，模式会逐一带出对应旗标；反之模糊输入只能得到最小可用命令。
2. 对“紧急程度”的识别要人工复核：P0 意味着生产宕机/安全/数据丢失级事故，模式的 P0 判定依据的是输入文本措辞，执行前应确认真实影响面。
3. 类型可迭代：默认输出倾向 task；大型多阶段目标应显式要求 -t epic，并配合 --parent/--deps 建立任务层级。
4. bd 属于外部工具：本模式只负责生成命令文本，命令的实际执行、Issue 的落库与导出由 bd（Beads）本身完成。

十一、延伸阅读与本仓库内的相关资源

• 模式源文件：data/patterns/create_bd_issue/system.md
• 姊妹模式（内容 → idea → 建单）：data/patterns/extract_bd_ideas/system.md
• 模式速查与解释：data/patterns/pattern_explanations.md
• 模式元数据与标签归档：scripts/pattern_descriptions/pattern_descriptions.json
• 模式引入记录：CHANGELOG.md（PR #1947 extract_bd_ideas、PR #1948 create_bd_issue）
• Fabric CLI 旗标解析与 YAML 配置说明：internal/cli/flags_test.go、internal/cli/README.md
• 模式加载机制：internal/tools/patterns_loader.go

借助 create_bd_issue，团队可以把「口头提需求 → 手工填 Issue」这一高频低价值环节压缩成一条命令的耗时，让 AI 依据 bd 的字段体系替你完成类型归类、优先级打分、标签编排与命令组装，而你要做的只是把需求说清楚。