bmad-bmb-setup

模块设置

概述

将 BMad 模块安装并配置到项目中。模块标识（名称、代码、版本）来自 ./assets/module.yaml。收集用户偏好并将其写入三个文件：

• {project-root}/_bmad/config.yaml — 共享项目配置：根级别的核心设置（例如 output_folder、document_output_language），以及每个模块各自的元数据和模块专属值配置段。仅供用户使用的键（user_name、communication_language）绝不会写入此处。
• {project-root}/_bmad/config.user.yaml — 个人设置，预期会被 git 忽略：user_name、communication_language，以及 ./assets/module.yaml 中标记为 user_setting: true 的任何模块变量。这些值只存放在此处。
• {project-root}/_bmad/module-help.csv — 为帮助系统登记模块功能。

两个配置脚本都使用防僵尸模式：写入新条目之前，会先移除该模块的现有条目，因此不会保留过时的值。

{project-root} 是配置_值_（写入上述文件的数据）中的字面令牌，切勿在此处替换它。它用于告知使用该值的大模型：该值相对于项目根目录，而不是技能根目录。这不适用于传递给下方脚本的文件系统路径_参数_（--target、--config-path、--user-config-path、--legacy-dir、--bmad-dir、--skills-dir）：这些都是真实路径，因此运行脚本前必须将 {project-root} 解析为实际的项目根目录，否则脚本会在技能文件夹下写入字面路径 {project-root}/。如果令牌尚未解析，脚本会报错并拒绝执行。

激活时

1. 读取 ./assets/module.yaml，获取模块元数据和变量定义（code 字段是模块标识符）
2. 检查 {project-root}/_bmad/config.yaml 是否存在——如果其中已包含与模块代码匹配的配置段，告知用户这是一次更新
3. 检查模块配置文件 {project-root}/_bmad/bmb/config.yaml 和 {project-root}/_bmad/core/config.yaml。如果其中任一文件存在：
   • 如果 {project-root}/_bmad/config.yaml 中尚无该模块的配置段：这是一次全新安装。告知用户检测到了安装程序配置，相关值将合并到新格式中。
   • 如果 {project-root}/_bmad/config.yaml 中已有该模块的配置段：这是一次旧版迁移。告知用户发现了与现有配置并存的旧版模块配置，旧版值将作为备用默认值。
   • 两种情况下，设置完成后都会清理模块配置文件和目录。

如果用户提供了参数（例如 accept all defaults、--headless，或内联值，如 user name is BMad, I speak Swahili），将提供的值映射到配置键，其余使用默认值，并跳过交互式提示。仍须在最后显示完整的确认摘要。

收集配置

向用户询问各项值。将默认值显示在方括号中。集中展示所有值，让用户只需回复想要更改的值（例如，“将语言改为斯瓦希里语，其余不变”）。不要让用户“按 Enter”或“留空”——在聊天界面中，用户必须输入内容才能回复。

默认值优先级（优先级由高到低）：现有新配置值 > 旧配置值 > ./assets/module.yaml 中的默认值。存在旧配置时，读取其中的值，并将匹配的值用作默认值，而不是使用 module.yaml 中的默认值。只保留与当前架构匹配的键——已更改或已移除的键将被忽略。

核心配置（仅当尚无核心键时）：user_name（默认值：BMad）、communication_language 和 document_output_language（默认值：英语——作为一个语言问题询问，这两个键使用相同的答案）、output_folder（默认值：{project-root}/_bmad-output）。其中，user_name 和 communication_language 仅写入 config.user.yaml。其余配置写入根目录下的 config.yaml，并由所有模块共享。

模块配置：读取 ./assets/module.yaml 中每个带有 prompt 字段的变量。使用其提示词及默认值（如果有旧值，则使用旧值）进行询问。

写入文件

将收集到的答案写入临时 JSON 文件，结构为 {"core": {...}, "module": {...}}（如果核心配置已存在，则省略 core）。此 JSON 中的值保留字面量 {project-root} 标记。然后运行两个脚本——它们写入不同文件，因此可以并行运行。

在以下命令中，运行前将每个路径参数中的 {project-root} 替换为实际项目根目录（例如 /home/me/myapp）——这些是文件系统路径，而非配置值。保持 {temp-file} 和 bmb 不变。

uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code bmb

两个脚本都会将 JSON 结果输出到 stdout。如果任一脚本以非零状态码退出，则报告错误并停止。脚本会自动将旧配置值用作后备默认值，并在成功合并后删除旧文件。检查输出中的 legacy_configs_deleted 和 legacy_csvs_deleted，以确认清理完成。

运行 ./scripts/merge-config.py --help 或 ./scripts/merge-help-csv.py --help 查看完整用法。

创建输出目录

写入配置后，创建所有已配置的输出目录。仅对于文件系统操作（例如创建目录），将 {project-root} 标记解析为实际项目根目录，并创建 config.yaml 中尚不存在的每个路径类型值——包括 output_folder 以及值以 {project-root}/ 开头的任何模块变量。配置文件中存储的路径必须继续使用字面量 {project-root} 标记；只有磁盘上的目录使用解析后的路径。使用 mkdir -p 或等效命令创建完整路径。

清理旧目录

两个合并脚本均成功完成后，移除安装程序的包目录。这些目录中的 Skills 和 Agent 已安装到 .claude/skills/——_bmad/ 目录中应仅包含配置文件。

与合并脚本一样，运行前将 --bmad-dir 和 --skills-dir 路径参数中的 {project-root} 替换为实际项目根目录。

uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code bmb --also-remove _config --skills-dir "{project-root}/.claude/skills"

脚本会在删除任何内容之前，验证旧目录中的每项 Skill 是否都存在于 .claude/skills/。不包含 Skills 的目录（例如 _config/）会直接删除。如果脚本以非零状态码退出，则报告错误并停止。缺失目录（已在之前的运行中清理）不算错误——该脚本具有幂等性。

检查 JSON 输出中的 directories_removed 和 files_removed_count，以确认清理完成。运行 ./scripts/cleanup-legacy.py --help 查看完整用法。

确认

使用脚本的 JSON 输出显示写入的内容——设置的配置值（核心配置写入根目录的 config.yaml，模块值写入模块部分）、写入 config.user.yaml 的用户设置（结果中的 user_keys）、添加的帮助条目，以及这是全新安装还是更新。如果已删除旧版文件，请说明迁移情况。如果已移除旧版目录，请报告数量并列出目录（例如：“已从 bmb/、core/、_config/ 清理 106 个安装程序包文件 — 技能已安装到 .claude/skills/。”）。然后向用户显示 ./assets/module.yaml 中的 module_greeting。

结果

一旦知道用户的 user_name 和 communication_language（来自收集的输入、参数或现有配置），在本次会话的剩余时间内始终使用这些信息：用用户配置的姓名称呼用户，并使用其配置的 communication_language 进行交流。