sample-module-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 — 计划通过 gitignore 排除的个人设置：user_name、communication_language，以及 ./assets/module.yaml 中标记为 user_setting: true 的任何模块变量。这些值仅保存在此处。
• {project-root}/_bmad/module-help.csv — 为帮助系统注册模块功能。

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

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

激活时

1. 读取 ./assets/module.yaml，获取模块元数据和变量定义（code 字段是模块标识符）。
2. 检查 {project-root}/_bmad/config.yaml 是否存在；如果其中已有与该模块代码匹配的配置段，告知用户这是一次更新。
3. 检查模块专属配置 {project-root}/_bmad/sam/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 之类的内联值），则将提供的值映射到配置键，其余项使用默认值，并跳过交互式提示。完成时仍需显示完整的确认摘要。

收集配置

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

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

核心配置（仅当尚不存在核心键时）：user_name（默认值：BMad）、communication_language 和 document_output_language（默认值：English——作为一个语言问题询问，这两个键使用相同的答案）、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）——这些是文件系统路径，不是配置值。

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 sam

两个脚本都会将 JSON 结果输出到标准输出。如果任一脚本以非零状态码退出，则显示错误并停止。脚本会自动读取旧配置值作为后备默认值，并在成功合并后删除旧文件。检查输出中的 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 或等效命令创建完整路径。

清理旧目录

两个合并脚本均成功完成后，删除安装程序的包目录。这些目录中的技能和 Agent 已安装在 .claude/skills/ 中——_bmad/ 目录中应只保留配置文件。

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

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

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

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

确认

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

结果

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