7.8 KiB

Raw Blame History

BMad 文档模板规范

概述

BMad 文档模板以 YAML 格式定义，以驱动交互式文档生成和代理交互。模板将结构定义与内容生成分开，使其对人类和 LLM 代理都友好。

模板结构

template:
  id: template-identifier
  name: 人类可读的模板名称
  version: 1.0
  output:
    format: markdown
    filename: default-path/to/{{filename}}.md
    title: '{{variable}} 文档标题'

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: section-id
    title: 部分标题
    instruction: |
      关于 LLM 如何处理此部分的详细说明      
    # ... 其他部分属性

核心字段

模板元数据

id: 模板的唯一标识符
name: UI 中显示的人类可读名称
version: 用于跟踪更改的模板版本
output.format: 文档模板的默认值为 "markdown"
output.filename: 默认输出文件路径（可包含变量）
output.title: 文档标题（在 markdown 中成为 H1）

工作流程配置

workflow.mode: 默认交互模式 ("interactive" 或 "yolo")
workflow.elicitation: 要使用的引导任务 ("advanced-elicitation")

部分属性

必填字段

id: 部分的唯一标识符
title: 部分标题文本
instruction: 关于 LLM 如何处理此部分的详细指南

可选字段

内容控制

type: 结构化部分的内容类型提示
template: 部分内容的固定模板文本
item_template: 部分内可重复项目的模板
prefix: 编号项的前缀 (例如, "FR", "NFR")

行为标志

elicit: 布尔值 - 在部分呈现后应用引导
repeatable: 布尔值 - 部分可以重复多次
condition: 字符串 - 包含该部分的条件 (例如, "has ui requirements")

代理权限

owner: 字符串 - 最初创建/填充此部分的代理角色
editors: 数组 - 允许修改此部分的代理角色列表
readonly: 布尔值 - 部分在初次创建后无法修改

内容指南

examples: 示例内容数组（不包含在输出中）
choices: 包含常见决策选项的对象
placeholder: 默认占位符文本

结构

sections: 嵌套子部分的数组

支持的类型

内容类型

bullet-list: 无序列表项
numbered-list: 带可选前缀的有序列表
paragraphs: 自由格式的段落文本
table: 结构化表格数据
code-block: 代码或配置块
template-text: 带变量替换的固定模板文本
mermaid: 带有指定类型和详细信息的 Mermaid 图

特殊类型

repeatable-container: 用于多个实例的容器
conditional-block: 根据条件显示的内容
choice-selector:向用户呈现选项

高级功能

变量替换

在标题、模板和内容中使用 {{variable_name}}：

title: '史诗 {{epic_number}} {{epic_title}}'
template: '作为一名 {{user_type}}，我想要 {{action}}，以便 {{benefit}}。'

条件部分

- id: ui-section
  title: 用户界面设计
  condition: 项目具有 UX/UI 需求
  instruction: 仅当项目具有 UI 组件时才包含

选项集成

choices:
  architecture: [单体, 微服务, 无服务器]
  testing: [仅单元测试, 单元测试 + 集成测试, 完整金字塔]

Mermaid 图表

- id: system-architecture
  title: 系统架构图
  type: mermaid
  instruction: 创建一个显示关键组件和数据流的系统架构图
  mermaid_type: flowchart
  details: |
    显示以下组件：
    - 用户界面层
    - API 网关
    - 核心服务
    - 数据库层
    - 外部集成

支持的 mermaid_type 值:

核心图表类型:

flowchart - 流程图和过程图
sequenceDiagram - 用于交互的序列图
classDiagram - 类关系图 (UML)
stateDiagram - 状态转换图
erDiagram - 实体关系图
gantt - 用于时间轴的甘特图
pie - 用于数据可视化的饼图

高级图表类型:

journey - 用户旅程图
mindmap - 用于头脑风暴的思维导图
timeline - 用于按时间顺序排列事件的时间轴图
quadrantChart - 用于数据分类的象限图
xyChart - XY 图 (条形图, 折线图)
sankey - 用于流量可视化的桑基图

专业类型:

c4Context - C4 上下文图 (实验性)
requirement - 需求图
packet - 网络数据包图
block - 框图
kanban - 看板

代理权限示例

- id: story-details
  title: 故事
  owner: scrum-master
  editors: [scrum-master]
  readonly: false
  sections:
    - id: dev-notes
      title: 开发人员说明
      owner: dev-agent
      editors: [dev-agent]
      readonly: false
      instruction: 实现说明和技术细节
    - id: qa-results
      title: QA 结果
      owner: qa-agent
      editors: [qa-agent]
      readonly: true
      instruction: 质量保证测试结果

可重复部分

- id: epic-details
  title: 史诗 {{epic_number}} {{epic_title}}
  repeatable: true
  sections:
    - id: story
      title: 故事 {{epic_number}}.{{story_number}} {{story_title}}
      repeatable: true
      sections:
        - id: criteria
          title: 验收标准
          type: numbered-list
          item_template: '{{criterion_number}}: {{criteria}}'
          repeatable: true

带代码块的示例

examples:
  - 'FR6: 系统必须在 2 秒内验证用户身份'
  - |
    ```mermaid
    sequenceDiagram
        participant User
        participant API
        participant DB
        User->>API: POST /login
        API->>DB: 验证凭据
        DB-->>API: 用户数据
        API-->>User: JWT 令牌
    ```    
  - |
    **架构决策记录**

    **决策**: 使用 PostgreSQL 作为主数据库
    **理由**: 需要 ACID 合规性和 JSON 支持
    **后果**: 需要数据库管理专业知识

部分层次结构

模板从第一个 H2 开始定义完整的文档结构 - 每个级别都是下一个 H#：

sections:
  - id: overview
    title: 项目概述
    sections:
      - id: goals
        title: 目标
      - id: scope
        title: 范围
        sections:
          - id: in-scope
            title: 范围内
          - id: out-scope
            title: 范围外

处理流程

解析模板: 加载并验证 YAML 结构
初始化工作流程: 设置交互模式和引导
处理部分: 按顺序处理每个部分：
- 检查条件
- 应用说明
- 生成内容
- 处理选项和变量
- 如果指定，则应用引导
- 处理嵌套部分
生成输出: 创建干净的 markdown 文档

最佳实践

模板设计

保持说明清晰具体
对复杂内容使用示例
合乎逻辑地组织部分
包含所有必要的 LLM 指南

内容说明

明确说明预期的格式
包括决策的理由
指定交互模式
需要时引用其他文档

变量命名

使用描述性的变量名
遵循一致的命名约定
记录预期的变量值

示例用法

为复杂部分提供具体示例
包括简单和复杂的案例
使用真实的项目场景
在有帮助时包括代码块和图表

验证

模板应进行以下验证：

有效的 YAML 语法
必填字段存在
一致的部分 ID
正确的嵌套结构
有效的变量引用

从旧版迁移

从 markdown+frontmatter 模板转换时：

将嵌入的 [[LLM:]] 说明提取到 instruction 字段
将 <<REPEAT>> 块转换为 repeatable: true 部分
将 ^^CONDITIONS^^ 提取到 condition 字段
将 @{examples} 移动到 examples 数组
将 {{placeholders}} 转换为正确的变量语法

本规范确保模板既人类可读又机器可处理，同时保持复杂文档生成所需的灵活性。

7.8 KiB Raw Blame History Unescape Escape