BMAD-METHOD配置迁移工具：从v3平滑升级到v4的完整指南
项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD BMAD-METHOD（Breakthrough Method for Agile Ai Driven Development）作为敏捷AI驱动开发的突破性方法，其v4版本带来了架构与工作流的重大改进。本文档将详细介绍如何使用官方提供的v3-to-v4-upgrader.js工具实现配置平滑迁移，确保开发项目无缝过渡到新版本环境。
迁移工具核心功能解析
v3到v4的升级工具采用模块化设计，主要实现五大核心功能：
- 项目结构自动验证与兼容性检测
- 全量备份机制确保数据安全
- 新架构文件系统部署
- 文档智能迁移与格式转换
- IDE开发环境自动配置
工具实现类V3ToV4Upgrader封装了完整迁移逻辑，通过upgrade()方法启动迁移流程，该方法位于文件第20-112行，包含从环境初始化到完成报告的全生命周期管理。
迁移前准备工作
环境要求
- Node.js 14.0+运行环境
- npm/yarn包管理器
- Git版本控制工具（建议）
项目验证
在执行迁移前，工具会自动验证当前项目是否为有效的v3结构，关键检测点包括：
// 代码片段来自validateV3Project方法（131-163行）
const bmadAgentPath = path.join(projectPath, "bmad-agent");
const docsPath = path.join(projectPath, "docs");
const hasBmadAgent = await this.pathExists(bmadAgentPath);
const hasDocs = await this.pathExists(docsPath);
const isValid = hasBmadAgent && hasDocs;
只有同时存在bmad-agent/和docs/目录的项目才会被判定为有效v3项目，验证失败将终止迁移流程。
迁移操作全流程
1. 执行迁移命令
通过npx直接调用项目内工具：
npx node tools/upgraders/v3-to-v4-upgrader.js
工具支持以下参数：
--projectPath: 指定项目路径（默认当前目录）--dryRun: 执行预演不实际修改文件--no-backup: 跳过备份步骤（不推荐）--ides: 指定IDE配置（如"cursor,claude-code"）
2. 项目分析与预检查
工具会自动扫描文档结构并生成迁移报告，关键分析代码位于analyzeProject()方法（165-268行），主要检测内容包括：
- PRD文档识别（支持prd.md、product-requirements.md等格式）
- 架构文档检测（architecture.md及变体）
- 故事文件统计（docs/stories/目录下的.md文件）
- Epic文件识别（epic*.md命名模式）
预检查结果示例：
Project Analysis:
- PRD found: docs/prd.md
- Architecture found: docs/architecture.md
- Front-end Architecture found: docs/front-end-architecture.md
- UX/UI Spec found: Not found
- UX/Design Prompt found: docs/ux-prompt.md
- Epic files found: 3 files (epic*.md)
- Stories found: 12 files in docs/stories/
- Custom files in bmad-agent/: 8
3. 安全备份机制
工具强制开启备份功能（除非显式禁用），将v3关键目录迁移至.bmad-v3-backup/：
// 备份实现代码（333-376行）
const backupPath = path.join(projectPath, ".bmad-v3-backup");
await fs.mkdir(backupPath, { recursive: true });
await fs.rename(bmadAgentSrc, bmadAgentDest); // 迁移bmad-agent目录
await fs.rename(docsSrc, docsDest); // 迁移docs目录
注意：若检测到已存在备份目录，工具将终止执行并提示手动处理，防止数据覆盖风险。
4. v4架构部署
工具从项目内置的bmad-core/目录复制全新v4结构至目标项目：
// 架构部署代码（378-418行）
const sourcePath = path.join(__dirname, "..", "..", "bmad-core");
const destPath = path.join(projectPath, ".bmad-core");
await this.copyDirectory(sourcePath, destPath);
新架构采用.bmad-core/隐藏目录设计，包含：
- 标准化agent定义（agents/目录）
- 模块化工作流配置（workflows/目录）
- 模板化文档生成系统（templates/目录）
- 团队协作配置（agent-teams/目录）
文档迁移策略详解
文件类型映射规则
工具根据文档类型自动执行不同迁移策略：
| v3文档类型 | v4存储路径 | 处理方式 |
|---|---|---|
| PRD文档 | docs/ | 直接复制保留原始内容 |
| 架构文档 | docs/ | 复制后需通过doc-migration-task转换格式 |
| 故事文件 | docs/stories/ | 批量迁移保持目录结构 |
| Epic文件 | docs/prd/ | 迁移并生成索引文件 |
| UX设计文件 | docs/ | 原样保留，兼容v4新工作流 |
特殊处理：Epic文件索引生成
当检测到epic文件时，工具会自动创建docs/prd/index.md索引：
// 索引生成代码（716-736行）
indexContent += "## Sections\n\n";
const sortedEpics = [...analysis.epicFiles].sort();
for (const epicFile of sortedEpics) {
const epicName = epicFile.replace(/\.md$/, "").replace(/^epic-?/i, "").replace(/-/g, " ").trim();
const displayName = epicName.charAt(0).toUpperCase() + epicName.slice(1);
indexContent += `- ${displayName || epicFile.replace(".md", "")}\n`;
}
生成的索引文件会自动提取PRD文档标题和介绍内容，为Epic文件创建结构化导航。
迁移后验证与配置
完成状态检查
迁移完成后，工具会输出详细报告，包含：
Summary:
- V3 files backed up to: .bmad-v3-backup/
- V4 structure installed: .bmad-core/ (fresh from V4)
- Documents migrated: 15 files + 3 epics
必要后续操作
-
文档格式标准化 通过@bmad-master agent执行：
@bmad-master run doc-migration-task该任务会将v3文档转换为v4模板格式，特别是架构文档需要更新为yaml配置格式。
-
如无Epic文件需执行PRD分片
@bmad-master run shard-doc --input docs/prd.md --output docs/prd/ -
IDE环境验证 工具自动配置的IDE规则位于：
- VSCode: .vscode/settings.json
- Cursor: .cursor/rules/
- Claude Code: .claude/commands/BMad/
故障排除与回滚机制
常见问题解决
- 备份失败：检查磁盘空间和文件权限，删除残留的
.bmad-v3-backup/目录后重试。 - 文档迁移冲突：手动删除目标路径下的冲突文件，或使用
--dryRun参数预演检测冲突。 - IDE配置不生效：删除IDE配置目录后重新执行
setupIDE步骤。
回滚操作流程
若迁移后需要恢复v3环境，执行：
# 恢复备份
mv .bmad-v3-backup/bmad-agent/ ./
mv .bmad-v3-backup/docs/ ./
# 删除v4文件
rm -rf .bmad-core/
最佳实践与注意事项
-
版本控制建议 迁移前提交所有更改，创建专门的升级分支：
git checkout -b upgrade-to-v4 -
大型项目迁移策略 对于超过100个故事文件的项目，建议使用
--dryRun先验证迁移效果，分段执行文档转换任务。 -
自定义Agent处理 v3自定义Agent无法直接迁移，需参考bmad-core/agents/目录下的新Agent定义格式重新实现。
-
工作流迁移 v3工作流需手动转换为v4的yaml格式，可参考greenfield-fullstack.yaml模板进行重构。
通过本文档介绍的迁移流程，开发团队可以安全高效地将项目升级至BMAD-METHOD v4版本，充分利用新架构带来的模块化、标准化开发体验。迁移工具源代码完全开源，可通过bmad-core/目录查看完整实现细节，如有定制需求可基于官方工具进行二次开发。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
