BMAD-METHOD 安装实战指南npx 一键安装、验证、更新与无头 CI 部署【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHODBMADBreakthrough Method for Agile AI Driven Development是一套面向 AI 编码工具的敏捷开发方法论技能包。本文以仓库中的韩文版安装文档 docs/ko-kr/start/install-bmad.md 为核心骨架完整讲解如何通过npx bmad-method install在项目内安装 BMad、与受支持的 AI 编码工具完成集成、在后期更新或重新配置安装以及如何在 CI 环境中执行无头headless安装。读完本文你将掌握 BMad 的完整安装生命周期并理解安装背后_bmad运行时目录、配置文件模板与模块清单的底层工作方式。何时需要安装 BMadnpx bmad-method install是 BMad 的安装入口它完成两件事把 BMad 技能安装进项目并把技能与你的 AI 编码工具关联起来。以下场景都应使用这条命令在新项目或已有项目中首次安装 BMad把 BMad 技能连接到某个受支持的 AI 编码工具更新已有的 BMad 安装更新时同样使用这条命令添加或移除模块、更换工具、修改安装配置。也就是说安装命令承担了「首次安装」「增量更新」「重新配置」三种职责安装程序会根据检测到的现状自动分流详见下文「更新或重新配置 BMad」。安装前置条件在运行安装程序之前请确认环境满足以下要求依赖版本 / 说明缺失时的表现Node.js20.12 及以上安装程序无法启动受支持的 AI 编码工具以npx bmad-method install --list-tools查询当前支持列表技能无法被调用uvbmad-build、bmad-build-auto等需要以uv运行 Python 或渲染产物的技能依赖它安装可完成但会显示警告安装 uv 前这些技能不可用Git仅当从 Git 安装外部模块或自定义模块时需要仅相关安装路径受影响其中uv的警告不会中断安装——安装程序会照常结束但依赖uv的技能典型如bmad-build、bmad-build-auto在补齐uv之前无法工作。这一点在安装摘要中也会再次提示。查询当前受支持的工具列表受支持工具的清单会随版本演进不要在文档中假设固定值直接让安装程序告诉你npx bmad-method install --list-tools该命令输出当前可用的工具 ID这些 ID 将用于后面的无头 CI 安装--tools参数。安装并验证 BMad1. 打开目标项目在终端中进入要安装 BMad 的项目目录。安装程序默认把 BMad 安装到当前目录除非你另行指定目标位置cd your-project2. 运行安装程序npx bmad-method install然后跟随屏幕提示操作。可选项目会随着模块与工具集成的演进而变化但安装程序会按顺序引导你完成可用模块选择、配置项填写、受支持的 AI 编码工具选择。如果安装过程中出现错误或警告按照它给出的处理建议执行即可。uv缺失类警告不会中止安装但相关技能在补齐依赖前不可用。3. 检查完成摘要安装结束时终端会显示BMAD is ready to use!以及安装路径同时列出仍需处理的其他警告。4. 验证工具集成从项目目录打开你选中的 AI 编码工具调用bmad-help技能向它询问「下一步该做什么」。如果工具能够识别并执行该技能说明集成已经就绪。bmad-help是安装的核心验证点也是仓库中 skills/bmad/SKILL.md 定义的枢纽技能hub skill它会分析当前状态与用户问题回答关于 BMad 的疑问或推荐下一个要使用的技能。从该技能的描述可以看到它同时承担两类职责——普通帮助请求走只读流程而当用户明确要求 setup、update 或 doctor修复安装时则会加载 skills/bmad/references/setup.md 并按对应流程执行且三者是互不串路的独立命令。安装背后发生了什么_bmad运行时的组成了解安装结果需要先认识安装产物的结构。安装完成后项目根目录下会出现_bmad目录它存放所有技能共享的配置与支持脚本。从仓库源码可以还原这套运行时的主要构成1. 团队配置文件_bmad/config.toml由 skills/bmad/assets/config.template.toml 这个模板物化而来。模板展示了配置的层次结构[core]project_name默认取项目目录名占位符{directory_name}会被安装程序替换为实际目录名、output_folder默认{project-root}/_bmad-output即所有产出物的统一落盘位置[modules.bmm]模块级配置如planning_artifacts、implementation_artifacts规划与实现产物的目录、project_knowledge项目知识库路径默认{project-root}/docs[agents.*]可选的角色 Agent 人格配置分析师、产品经理、UX 设计师、架构师、开发工程师等每个 Agent 声明其所属module、团队、姓名、职位、图标与行为描述。2. 支持脚本目录_bmad/scripts包括resolve_config.py、config_utils.py、memlog.py、render_skill.py等。例如 skills/bmad/scripts/resolve_config.py 用于把 BMad 的多层 TOML 配置解析为 JSON支持--project-root、--key等参数供技能在运行时读取配置。3. 各模块的脚本目录_bmad/module/scripts来自已安装技能模块的声明式脚本。技能模块的清单文件 skills/bmad/module-manifest.toml 说明了这种声明机制每个已安装技能目录下都有module-manifest.toml其中module字段标识技能归属的模块bmad 技能本身属于toolbox模块version、update_source更新源如github:bmad-code-org/BMAD-METHOD/skills、knowledge知识文档路由都是安装与更新流程读取的关键字段。安装程序在物化_bmad时采用「暂存目录 原子替换」策略见 skills/bmad/scripts/setup.py 中的materialize_bmad与replace_dir先在项目内创建临时目录完成写入再整体替换旧的_bmad失败时回滚避免安装中断留下半成品。同时custom/目录与既有的*.user.toml用户层配置会被保留不会被覆盖。更新或重新配置 BMad1. 重新运行安装程序在包含_bmad目录的项目中执行npx bmad-method install2. 选择检测到的路径安装程序会检测到已有安装并根据当前状态给出适用的更新或修改路径选择更新update刷新现有安装到最新状态选择修改modification变更模块、工具或配置。之后按屏幕提示继续即可。若从更早的 BMad 版本升级安装程序还会警告旧版命令目录中遗留的bmad-*条目建议删除它们避免工具中显示重复命令。3. 验证更新后的集成检查完成摘要必要时重新打开 AI 编码工具再次调用bmad-help确认集成仍正常。值得注意的是「更新/修复」这类运维操作在 BMad 技能侧也有对应的独立流程。skills/bmad/references/setup.md 定义了三条互不干扰的命令bmad update纯检查模式通过uv run --no-cache {skill-root}/scripts/setup.py --project-root ... --update扫描已安装技能与各来源的module-manifest.toml版本报告每个模块的状态current、newer-available、ahead、differing-unordered、could-not-check、version-spread、source-disagreement不做任何安装、移动、修复或删除bmad doctor修复模式要求_bmad已存在否则返回setup-required它会以只读方式列出新声明的配置问题--doctor --list-config-questions修复共享脚本与所选模块的脚本树并保留既有配置答案、custom/与用户层bmad setup设置模式只提出模块清单中声明的问题二次运行时保留已有团队答案、仅询问新声明的问题同时会修复_bmad/scripts若它是符号链接或与打包版本不一致的副本会替换为普通副本且成功安装从不创建符号链接。setup.py本身skills/bmad/scripts/setup.py支持--project-root、--skill、--module-answers、--list-config-questions、--update、--doctor等参数是这套运维能力的底层实现其配套测试位于 skills/bmad/scripts/tests/如test_resolve_config.py、test_memlog.py、test_render_skill.py等可作为理解安装与配置行为的参考。安装预发布版本Prerelease如果需要安装 pre-release 版本的 core 与 BMM并对本次运行中选中的外部模块也应用预发布选择使用npx bmad-methodnext install更新预发布安装时再次执行同一条命令即可。预发布构建变更更频繁可能包含未完成的功能因此日常项目工作请使用稳定版命令不带next。仓库当前 bmad 技能的清单版本即处于预发布轨道6.13.0-next见 skills/bmad/module-manifest.toml这正是该命令所要覆盖的场景之一。无头 CI 安装Headless在全新环境中为 Claude Code 配置 BMM 的典型无头安装命令如下npx bmad-method install --yes --modules bmm --tools claude-code自动化使用时请以这两条命令获取权威参数npx bmad-method install --help查看当前版本的自动化参数如--yes、--modules、--tools等npx bmad-method install --list-tools获取合法工具 ID。如果自动化脚本使用了next或指定了具体包版本那么在查看帮助和实际安装时必须使用相同的 tag 或版本避免帮助信息与安装行为不一致。无头模式与交互模式走的是同一条安装管线只是由参数代替人工应答模块配置问题仍可通过--list-config-questions与--module-answers机制以文件方式提供答案对应setup.py中validate_module_answers的校验逻辑答案文件只允许包含[modules....]表且只能回答确实待回答的问题。安装结果与产物安装完成后你得到的东西包括技能本体BMad 技能被安装到你选择的每个 AI 工具所使用的技能目录中。例如仓库中skills/bmad/、skills/bmad-spec/、skills/bmad-build/、skills/bmad-prd/等即为这些技能的组织形态每个技能目录包含SKILL.md技能指令、module-manifest.toml模块清单部分还带customize.toml、脚本与资源共享运行时项目下的_bmad目录包含技能共享的配置config.toml与支持脚本scripts/以及各模块的脚本目录配置输出按模板默认值产出物会写入_bmad-output对应output_folder配置。安装结束时安装程序会报告已配置的工具以及仍需处理的警告。对照 docs/ko-kr/tutorials/getting-deeper.md 等进阶文档可以继续了解安装之后如何深入使用这套方法论若需多语言对照英文原版见 docs/start/install-bmad.md中文版本见 docs/zh-cn/how-to/install-bmad.md捷克语版本见 docs/cs/how-to/install-bmad.md。常见问题速查安装时提示 Node.js 版本过低升级到 Node.js 20.12 或更高版本后重试。安装完成但技能不工作确认所选 AI 编码工具在受支持列表内npx bmad-method install --list-tools并从项目目录重新打开工具后调用bmad-help。提示uv缺失安装本身不受影响但安装uv之前bmad-build、bmad-build-auto等依赖uv的技能不可用。升级后工具中出现重复命令删除旧版遗留的bmad-*命令目录条目后重开工具。CI 中需要无人值守安装使用--yes --modules ... --tools ...组合并先通过--help与--list-tools确认参数与工具 ID。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
