企业官网建设流程全解析

BMAD-METHOD 安装实战指南：npx 一键安装、验证、更新与无头 CI 部署

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

BMAD（Breakthrough Method for Agile AI Driven Development）是一套面向 AI 编码工具的敏捷开发方法论技能包。本文以仓库中的韩文版安装文档 docs/ko-kr/start/install-bmad.md 为核心骨架，完整讲解如何通过npx bmad-method install在项目内安装 BMad、与受支持的 AI 编码工具完成集成、在后期更新或重新配置安装，以及如何在 CI 环境中执行无头（headless）安装。读完本文，你将掌握 BMad 的完整安装生命周期，并理解安装背后_bmad运行时目录、配置文件模板与模块清单的底层工作方式。

何时需要安装 BMad

npx bmad-method install是 BMad 的安装入口，它完成两件事：把 BMad 技能安装进项目，并把技能与你的 AI 编码工具关联起来。以下场景都应使用这条命令：

• 在新项目或已有项目中首次安装 BMad；
• 把 BMad 技能连接到某个受支持的 AI 编码工具；
• 更新已有的 BMad 安装（更新时同样使用这条命令）；
• 添加或移除模块、更换工具、修改安装配置。

也就是说，安装命令承担了「首次安装」「增量更新」「重新配置」三种职责，安装程序会根据检测到的现状自动分流（详见下文「更新或重新配置 BMad」）。

安装前置条件

在运行安装程序之前，请确认环境满足以下要求：

其中uv的警告不会中断安装——安装程序会照常结束，但依赖uv的技能（典型如bmad-build、bmad-build-auto）在补齐uv之前无法工作。这一点在安装摘要中也会再次提示。

查询当前受支持的工具列表

受支持工具的清单会随版本演进，不要在文档中假设固定值，直接让安装程序告诉你：

npx bmad-method install --list-tools

该命令输出当前可用的工具 ID，这些 ID 将用于后面的无头 CI 安装（--tools参数）。

安装并验证 BMad

1. 打开目标项目

在终端中进入要安装 BMad 的项目目录。安装程序默认把 BMad 安装到当前目录，除非你另行指定目标位置：

cd your-project

2. 运行安装程序

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用户层配置会被保留，不会被覆盖。

更新或重新配置 BMad

1. 重新运行安装程序

在包含_bmad目录的项目中执行：

npx bmad-method install

2. 选择检测到的路径

安装程序会检测到已有安装，并根据当前状态给出适用的更新或修改路径：

• 选择更新（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-method@next 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