631 lines
19 KiB
Markdown
631 lines
19 KiB
Markdown
# 02 - BMAD-METHOD 核心架构
|
||
|
||
## 1. 整体架构设计
|
||
|
||
### 1.1 三层架构模型
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 应用层 (Application Layer) │
|
||
│ │
|
||
│ 用户 ←→ IDE ←→ 代理菜单 ←→ 工作流触发 │
|
||
└─────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────┐
|
||
│ 代理层 (Agent Layer) │
|
||
│ │
|
||
│ 19+ 专业代理 (PM, Architect, Dev...) │
|
||
│ - 角色定义 (Persona) │
|
||
│ - 专业知识 (Domain Knowledge) │
|
||
│ - 工作流菜单 (Menu) │
|
||
└─────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────┐
|
||
│ 工作流层 (Workflow Layer) │
|
||
│ │
|
||
│ 63+ 结构化工作流程 │
|
||
│ - 指令文档 (Instructions) │
|
||
│ - 模板文件 (Templates) │
|
||
│ - 任务调用 (Task Invocations) │
|
||
└─────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────┐
|
||
│ 框架层 (Core Layer) │
|
||
│ │
|
||
│ BMad-CORE 基础能力 │
|
||
│ - 配置管理 │
|
||
│ - 路径解析 │
|
||
│ - 依赖解析 │
|
||
│ - Party Mode 协调 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 模块依赖关系
|
||
|
||
```
|
||
BMad-CORE (基础框架)
|
||
├── 必需：所有模块都依赖
|
||
│
|
||
├── BMad Method (BMM - 主模块)
|
||
│ ├── 依赖 CIS (用于头脑风暴)
|
||
│ └── 集成 BMGD (游戏开发扩展)
|
||
│
|
||
├── BMad Builder (BMB - 扩展工具)
|
||
│ └── 独立运行，创建新模块
|
||
│
|
||
├── Creative Intelligence Suite (CIS)
|
||
│ └── 独立或与其他模块集成
|
||
│
|
||
└── BMad Game Development (BMGD)
|
||
└── 使用 BMM 的 Sprint 工作流
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 目录结构详解
|
||
|
||
### 2.1 顶级目录结构
|
||
|
||
```
|
||
/home/user/BMAD-METHOD/
|
||
│
|
||
├── README.md # 项目主文档
|
||
├── CONTRIBUTING.md # 贡献指南
|
||
├── CHANGELOG.md # 版本更新日志
|
||
├── LICENSE # MIT 许可证
|
||
├── package.json # Node.js 项目配置
|
||
├── .nvmrc # Node 版本：22
|
||
│
|
||
├── src/ # 📦 源代码目录
|
||
│ ├── core/ # BMad-CORE 基础框架
|
||
│ ├── modules/ # 功能模块
|
||
│ │ ├── bmm/ # BMad Method (2.3 MB)
|
||
│ │ ├── bmb/ # BMad Builder (463 KB)
|
||
│ │ ├── cis/ # Creative Intelligence (154 KB)
|
||
│ │ └── bmgd/ # Game Development (556 KB)
|
||
│ └── utility/ # 共享资源
|
||
│
|
||
├── tools/ # 🛠️ 工具集
|
||
│ ├── cli/ # 安装和构建工具
|
||
│ │ ├── bmad-cli.js # CLI 入口
|
||
│ │ ├── commands/ # 命令实现
|
||
│ │ └── bundlers/ # Web 打包器
|
||
│ ├── flattener/ # 文档展平工具
|
||
│ └── validate-*.js # 验证工具
|
||
│
|
||
├── docs/ # 📚 项目级文档
|
||
│ ├── ide-info/ # 15 个 IDE 集成指南
|
||
│ ├── installers-bundlers/ # 安装系统文档
|
||
│ └── *.md # 各种指南
|
||
│
|
||
├── web-bundles/ # 🌐 Web 部署包
|
||
│ ├── bmm/ # BMM Web 版本
|
||
│ ├── bmb/ # BMB Web 版本
|
||
│ └── cis/ # CIS Web 版本
|
||
│
|
||
├── test/ # ✅ 测试套件
|
||
│ ├── test-agent-schema.js
|
||
│ └── test-installation-components.js
|
||
│
|
||
├── bmad/ # 💾 已安装实例（示例）
|
||
│ ├── core/
|
||
│ ├── bmm/
|
||
│ ├── _cfg/ # 用户配置
|
||
│ └── agents/ # 编译后的代理
|
||
│
|
||
└── .claude/ # 🤖 IDE 配置（示例）
|
||
└── commands/ # Claude Code 斜杠命令
|
||
```
|
||
|
||
### 2.2 源代码目录详解
|
||
|
||
#### src/core/ - 核心框架
|
||
|
||
```
|
||
src/core/
|
||
├── agents/
|
||
│ └── bmad-master.agent.yaml # 主协调代理
|
||
│
|
||
├── workflows/
|
||
│ ├── brainstorming/ # 头脑风暴工作流
|
||
│ │ ├── workflow.yaml
|
||
│ │ ├── instructions.md
|
||
│ │ └── brainstorming-techniques.csv
|
||
│ └── party-mode/ # 多代理协作
|
||
│ ├── workflow.yaml
|
||
│ └── instructions.md
|
||
│
|
||
├── tasks/ # 原子级任务
|
||
│ ├── workflow.xml # 工作流任务
|
||
│ ├── adv-elicit.xml # 高级引导任务
|
||
│ └── adv-elicit-methods.csv # 引导方法库
|
||
│
|
||
├── tools/ # 核心工具
|
||
│ └── shard-doc/ # 文档分片工具
|
||
│
|
||
├── config.yaml # 核心配置
|
||
└── _module-installer/ # 安装配置
|
||
└── install-config.yaml
|
||
```
|
||
|
||
#### src/modules/bmm/ - BMad Method 模块
|
||
|
||
```
|
||
src/modules/bmm/
|
||
├── README.md # 模块概述
|
||
├── config.yaml # 模块配置
|
||
│
|
||
├── agents/ # 12 个专业代理
|
||
│ ├── pm.agent.yaml # 产品经理 (John)
|
||
│ ├── analyst.agent.yaml # 分析师 (Mary)
|
||
│ ├── architect.agent.yaml # 架构师 (Winston)
|
||
│ ├── sm.agent.yaml # Scrum Master (Bob)
|
||
│ ├── dev.agent.yaml # 开发者 (Amelia)
|
||
│ ├── tea.agent.yaml # 测试架构师 (Murat)
|
||
│ ├── ux-designer.agent.yaml # UX 设计师 (Sally)
|
||
│ ├── tech-writer.agent.yaml # 技术文档师 (paige)
|
||
│ ├── game-designer.agent.yaml # 游戏设计师
|
||
│ ├── game-dev.agent.yaml # 游戏开发者
|
||
│ ├── game-architect.agent.yaml # 游戏架构师
|
||
│ └── game-sm.agent.yaml # 游戏 Scrum Master
|
||
│
|
||
├── workflows/ # 34 个工作流
|
||
│ ├── workflow-status/ # 工作流状态管理
|
||
│ ├── 1-analysis/ # Phase 1: 分析 (5个)
|
||
│ │ ├── brainstorm-project/
|
||
│ │ ├── market-research/
|
||
│ │ ├── competitive-analysis/
|
||
│ │ ├── user-research/
|
||
│ │ └── product-brief/
|
||
│ │
|
||
│ ├── 2-plan-workflows/ # Phase 2: 规划 (6个)
|
||
│ │ ├── prd/ # PRD 工作流
|
||
│ │ │ ├── workflow.yaml
|
||
│ │ │ ├── instructions.md
|
||
│ │ │ ├── prd-template.md
|
||
│ │ │ └── create-epics-and-stories/
|
||
│ │ ├── tech-spec/ # 技术规格
|
||
│ │ ├── create-ux-design/ # UX 设计
|
||
│ │ └── brownfield-document/ # 现有代码文档化
|
||
│ │
|
||
│ ├── 3-solutioning/ # Phase 3: 方案 (2个)
|
||
│ │ ├── architecture/
|
||
│ │ └── solutioning-gate-check/
|
||
│ │
|
||
│ └── 4-implementation/ # Phase 4: 实现 (10个)
|
||
│ ├── sprint-planning/
|
||
│ ├── epic-tech-context/
|
||
│ ├── create-story/
|
||
│ ├── story-context/
|
||
│ ├── dev-story/
|
||
│ ├── story-review/
|
||
│ ├── story-ready/
|
||
│ ├── correct-course/
|
||
│ └── sprint-retrospective/
|
||
│
|
||
├── docs/ # 18 个指南文档
|
||
│ ├── README.md # 文档中心
|
||
│ ├── quick-start.md # 快速开始
|
||
│ ├── agents-guide.md # 代理指南
|
||
│ ├── scale-adaptive-system.md # 3轨系统
|
||
│ ├── workflows-*.md # 工作流指南
|
||
│ ├── faq.md # 常见问题
|
||
│ └── glossary.md # 术语表
|
||
│
|
||
├── teams/ # 预配置团队
|
||
│ ├── quick-flow-team.yaml
|
||
│ ├── bmad-method-team.yaml
|
||
│ └── enterprise-team.yaml
|
||
│
|
||
└── _module-installer/
|
||
└── install-config.yaml
|
||
```
|
||
|
||
### 2.3 安装后的目录结构
|
||
|
||
用户安装后在项目中创建：
|
||
|
||
```
|
||
your-project/
|
||
├── bmad/ # BMAD 安装目录
|
||
│ ├── core/ # 核心框架
|
||
│ │ ├── agents/
|
||
│ │ ├── workflows/
|
||
│ │ ├── tasks/
|
||
│ │ └── config.yaml
|
||
│ │
|
||
│ ├── bmm/ # BMad Method
|
||
│ │ ├── agents/ # 编译后的 .md 文件
|
||
│ │ ├── workflows/
|
||
│ │ └── config.yaml
|
||
│ │
|
||
│ ├── bmb/ # BMad Builder (可选)
|
||
│ ├── cis/ # Creative Intelligence (可选)
|
||
│ ├── bmgd/ # Game Development (可选)
|
||
│ │
|
||
│ └── _cfg/ # 用户配置和清单
|
||
│ ├── agents/ # 代理定制文件
|
||
│ ├── manifest.yaml # 安装清单
|
||
│ ├── workflow-manifest.csv # 工作流目录
|
||
│ ├── agent-manifest.csv # 代理元数据
|
||
│ └── files-manifest.csv # 文件完整性
|
||
│
|
||
├── .claude/ # Claude Code 工件
|
||
│ └── commands/
|
||
│ ├── bmad-bmm-workflows-prd.md
|
||
│ └── ... (所有工作流命令)
|
||
│
|
||
├── .cursor/ # Cursor 工件
|
||
│ └── rules/
|
||
│
|
||
├── .windsurf/ # Windsurf 工件
|
||
│ └── workflows/
|
||
│
|
||
└── docs/ # 项目输出文档
|
||
├── bmm-workflow-status.yaml # 工作流状态
|
||
├── sprint-status.yaml # Sprint 状态
|
||
├── PRD.md # 产品需求文档
|
||
├── architecture.md # 架构文档
|
||
└── ... (其他输出文档)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 技术栈和依赖
|
||
|
||
### 3.1 开发环境要求
|
||
|
||
```json
|
||
{
|
||
"Node.js": ">= 20.0.0",
|
||
"推荐版本": "22.x (见 .nvmrc)",
|
||
"包管理器": "npm",
|
||
"操作系统": "跨平台 (Linux, macOS, Windows)"
|
||
}
|
||
```
|
||
|
||
### 3.2 核心依赖分析
|
||
|
||
#### 运行时依赖 (15 个)
|
||
|
||
**CLI 框架**:
|
||
```javascript
|
||
commander@14.0.0 // CLI 命令框架
|
||
inquirer@8.2.6 // 交互式问答
|
||
ora@5.4.1 // 终端加载指示器
|
||
chalk@4.1.2 // 终端着色
|
||
boxen@5.1.2 // 盒式输出
|
||
figlet@1.8.0 // ASCII 艺术字体
|
||
```
|
||
|
||
**数据处理**:
|
||
```javascript
|
||
js-yaml@4.1.0 // YAML 解析和生成
|
||
xml2js@0.6.2 // XML 处理
|
||
csv-parse@6.1.0 // CSV 解析
|
||
```
|
||
|
||
**文件系统**:
|
||
```javascript
|
||
fs-extra@11.3.0 // 增强的文件系统操作
|
||
glob@11.0.3 // 文件模式匹配
|
||
ignore@7.0.5 // .gitignore 支持
|
||
```
|
||
|
||
**工具库**:
|
||
```javascript
|
||
semver@7.6.3 // 版本管理
|
||
wrap-ansi@7.0.0 // ANSI 文本换行
|
||
@kayvan/markdown-tree-parser // Markdown 解析
|
||
```
|
||
|
||
#### 开发依赖 (13 个)
|
||
|
||
**代码质量**:
|
||
```javascript
|
||
eslint@9.33.0 // 代码检查
|
||
prettier@3.5.3 // 代码格式化
|
||
eslint-config-prettier@10.1.8 // ESLint + Prettier 集成
|
||
```
|
||
|
||
**测试工具**:
|
||
```javascript
|
||
jest@30.0.4 // 测试框架
|
||
c8@10.1.3 // 代码覆盖率
|
||
```
|
||
|
||
**Git 工具**:
|
||
```javascript
|
||
husky@9.1.7 // Git hooks
|
||
lint-staged@16.1.1 // 暂存文件 lint
|
||
```
|
||
|
||
**Schema 验证**:
|
||
```javascript
|
||
zod@4.1.12 // Schema 验证
|
||
yaml-eslint-parser@1.2.3 // YAML 解析
|
||
```
|
||
|
||
### 3.3 构建和脚本
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"install:bmad": "安装 BMAD 到项目",
|
||
"bundle": "生成 Web 部署包",
|
||
"test": "完整测试套件",
|
||
"test:schemas": "代理 Schema 验证",
|
||
"test:install": "安装组件测试",
|
||
"validate:schemas": "YAML Schema 验证",
|
||
"validate:bundles": "Web Bundle 完整性",
|
||
"lint": "ESLint 检查 (max 0 warnings)",
|
||
"format:check": "Prettier 格式检查",
|
||
"format:fix": "自动格式化"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 质量保证流程
|
||
|
||
#### Pre-commit Hook
|
||
```bash
|
||
# 自动运行 (通过 husky)
|
||
1. lint-staged
|
||
├── 自动修复 JS/YAML 文件
|
||
├── 格式化所有文件
|
||
└── 仅处理 staged 文件
|
||
|
||
2. npm test
|
||
├── Schema 验证
|
||
├── 安装测试
|
||
├── Bundle 验证
|
||
├── Lint 检查
|
||
└── 格式检查
|
||
```
|
||
|
||
#### CI/CD (GitHub Actions)
|
||
```bash
|
||
# 每个 PR 自动运行
|
||
1. 并行执行
|
||
├── npm run test:schemas
|
||
├── npm run test:install
|
||
├── npm run validate:bundles
|
||
├── npm run lint
|
||
└── npm run format:check
|
||
|
||
2. 全部通过才能合并
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置系统
|
||
|
||
### 4.1 配置层级
|
||
|
||
```
|
||
1. 核心配置 (bmad/core/config.yaml)
|
||
├── project_name
|
||
├── output_folder
|
||
├── user_name
|
||
└── communication_language
|
||
|
||
2. 模块配置 (bmad/bmm/config.yaml)
|
||
├── 继承核心配置
|
||
├── document_output_language
|
||
├── user_skill_level
|
||
└── project_track (quick-flow/bmad-method/enterprise)
|
||
|
||
3. 代理定制 (bmad/_cfg/agents/*.yaml)
|
||
├── 覆盖代理属性
|
||
├── 多语言支持
|
||
└── 更新时保留
|
||
```
|
||
|
||
### 4.2 路径占位符系统
|
||
|
||
工作流和代理使用占位符，运行时解析：
|
||
|
||
```yaml
|
||
# 编译时解析
|
||
{project-root} → /home/user/my-project
|
||
{output_folder} → /home/user/my-project/docs
|
||
{installed_path} → /home/user/my-project/bmad/bmm/workflows/prd
|
||
|
||
# 配置值解析
|
||
{user_name} → 从 config.yaml 读取
|
||
{communication_language} → 从 config.yaml 读取
|
||
{config_source}:key → 从指定配置读取键值
|
||
|
||
# 系统生成
|
||
{date} → 当前日期
|
||
{timestamp} → 当前时间戳
|
||
```
|
||
|
||
### 4.3 智能输入发现
|
||
|
||
工作流自动查找输入文档：
|
||
|
||
```yaml
|
||
input_file_patterns:
|
||
product_brief:
|
||
whole: "{output_folder}/*brief*.md" # 优先整体文档
|
||
sharded: "{output_folder}/*brief*/index.md" # 降级到分片
|
||
|
||
research:
|
||
whole: "{output_folder}/*research*.md"
|
||
sharded: "{output_folder}/*research*/index.md"
|
||
```
|
||
|
||
**处理逻辑**:
|
||
1. 尝试匹配 `whole` 模式
|
||
2. 如果找不到，尝试 `sharded` 模式
|
||
3. 加载找到的文档
|
||
4. 如果都没有，提示用户
|
||
|
||
---
|
||
|
||
## 5. 编译和安装系统
|
||
|
||
### 5.1 YAML 到 Markdown 编译
|
||
|
||
**为什么编译？**
|
||
- IDE 通常直接读取 Markdown 文件
|
||
- YAML 便于配置和维护
|
||
- 编译时注入激活块和处理器
|
||
|
||
**编译流程**:
|
||
```
|
||
src/modules/bmm/agents/pm.agent.yaml
|
||
↓
|
||
[读取 YAML]
|
||
↓
|
||
[解析元数据、角色、菜单]
|
||
↓
|
||
[注入激活步骤 XML]
|
||
↓
|
||
[应用 IDE 特定处理器]
|
||
↓
|
||
bmad/bmm/agents/pm.md (Markdown)
|
||
```
|
||
|
||
**激活步骤**:
|
||
```xml
|
||
<activation-steps>
|
||
<!-- 从 utility/models/fragments/ 注入 -->
|
||
<step>加载配置文件</step>
|
||
<step>设置运行时变量</step>
|
||
<step>显示代理菜单</step>
|
||
</activation-steps>
|
||
```
|
||
|
||
### 5.2 安装阶段
|
||
|
||
**6 阶段安装**:
|
||
|
||
```
|
||
阶段 1: 收集用户输入
|
||
├── 目标目录
|
||
├── 选择模块 (BMM, BMB, CIS, BMGD)
|
||
├── 选择 IDE
|
||
└── 自定义配置
|
||
|
||
阶段 2: 预安装检查
|
||
├── 验证目标目录
|
||
├── 检测 v4 安装（升级路径）
|
||
├── 备份现有安装
|
||
└── 4 阶段依赖解析
|
||
|
||
阶段 3: 安装核心和模块
|
||
├── 复制文件到 {target}/bmad/
|
||
├── 编译 YAML → Markdown
|
||
├── 合并 customize.yaml
|
||
└── 注入激活块
|
||
|
||
阶段 4: IDE 集成
|
||
├── 初始化 IDE 处理器
|
||
├── 生成 IDE 工件
|
||
│ ├── Claude Code: .claude/commands/
|
||
│ ├── Cursor: .cursor/rules/
|
||
│ └── 其他 13 个 IDE
|
||
└── 执行平台钩子
|
||
|
||
阶段 5: 生成清单
|
||
├── manifest.yaml (安装元数据)
|
||
├── workflow-manifest.csv
|
||
├── agent-manifest.csv
|
||
├── task-manifest.csv
|
||
└── files-manifest.csv
|
||
|
||
阶段 6: 验证和完成
|
||
├── 文件完整性检查
|
||
├── 代理编译验证
|
||
├── IDE 工件确认
|
||
└── 显示摘要和后续步骤
|
||
```
|
||
|
||
### 5.3 依赖解析
|
||
|
||
**4 阶段依赖解析系统**:
|
||
|
||
```
|
||
阶段 1: 直接依赖
|
||
└── 模块直接声明的依赖
|
||
|
||
阶段 2: 传递依赖
|
||
└── 依赖的依赖
|
||
|
||
阶段 3: 可选依赖
|
||
└── 建议但非必需
|
||
|
||
阶段 4: 冲突解决
|
||
└── 版本冲突和循环依赖检测
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Web 打包系统
|
||
|
||
### 6.1 用途和目标
|
||
|
||
**目标**: 为 Web 部署创建自包含的代理和工作流包
|
||
|
||
**特点**:
|
||
- 单个 XML 文件包含所有依赖
|
||
- 无需文件系统访问
|
||
- 适用于 Web IDE 和浏览器环境
|
||
|
||
### 6.2 打包流程
|
||
|
||
```
|
||
输入: src/modules/bmm/agents/pm.agent.yaml
|
||
↓
|
||
编译（forWebBundle: true）
|
||
├── YAML → XML
|
||
├── 使用 web-bundle-activation-steps.xml
|
||
└── 递归解析所有依赖
|
||
↓
|
||
嵌入依赖
|
||
├── 工作流 YAML
|
||
├── 指令 Markdown
|
||
├── 模板文件
|
||
├── 数据 CSV
|
||
└── 任务 XML
|
||
↓ (所有包装在 <file> 标签)
|
||
输出: web-bundles/bmm/agents/pm.xml (自包含)
|
||
```
|
||
|
||
### 6.3 Web Bundle 结构
|
||
|
||
```xml
|
||
<agent>
|
||
<metadata>...</metadata>
|
||
<persona>...</persona>
|
||
<menu>...</menu>
|
||
|
||
<embedded-files>
|
||
<file path="workflows/prd/workflow.yaml">
|
||
<!-- YAML 内容 -->
|
||
</file>
|
||
<file path="workflows/prd/instructions.md">
|
||
<!-- Markdown 内容 -->
|
||
</file>
|
||
<!-- 更多文件... -->
|
||
</embedded-files>
|
||
</agent>
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 小结
|
||
|
||
BMAD-METHOD 的架构特点：
|
||
|
||
✅ **模块化设计** - 核心 + 可选模块
|
||
✅ **配置驱动** - YAML 配置，编译时处理
|
||
✅ **IDE 无关** - 支持 15 个 IDE
|
||
✅ **可扩展** - 使用 BMB 创建新模块
|
||
✅ **更新安全** - 用户配置独立保存
|
||
✅ **质量保证** - 完整的测试和验证流程
|
||
|
||
**下一步**: 阅读 [03-模块详解.md](./03-模块详解.md) 了解各模块功能细节
|