bmad-loop-setup

模块设置

概述

在项目中安装、配置并升级 bmad-loop 模块。

这个模块比较特殊：除了自动化技能，它还依赖 bmad-loop 编排工具——真正驱动循环的 Python 程序。该工具作为 bmad-loop 软件包从其公开 Git 仓库安装。这些技能本身无法独立运行。

BMAD 安装程序负责注册 _bmad/；此技能不负责。 通过 BMAD 安装程序（npx bmad-method install）安装 bmad-loop 时，安装程序会将技能放置在 _bmad/bmad-loop/ 下，写入该模块自己的配置和帮助文件，将模块记录到 _bmad/_config/ 中（清单、技能清单、文件清单），并重建 /bmad-help 目录。安装程序每次运行都会重新生成中央 _bmad/config.toml，因此安装程序之外的任何内容都不应写入该文件。

因此，此技能负责安装程序在结构上无法完成的部分：

1. 安装或升级编排工具（安装程序只复制技能目录，无法携带 Python 软件包）。
2. 运行 bmad-loop init，注册各 CLI 的钩子、部署捆绑的技能，并写入 .bmad-loop/policy.toml 和 gitignore 条目。
3. 执行预检 bmad-loop validate，并告知用户各角色的适配器配置。

它还会刷新一个文件——_bmad/bmad-loop/module-help.csv——以确保模块的帮助条目存在，即使项目是直接安装工具而不是通过 BMAD 安装程序安装的。不会写入或删除 _bmad/ 下的任何其他内容。

模块身份信息（名称、代码、版本）来自 ./assets/module.yaml。

{project-root} 在 BMAD 配置的_值_中是一个字面标记——切勿替换。但这不适用于下方命令中的文件系统路径_参数_：这些是真实路径，因此运行前应将 {project-root} 解析为实际项目根目录。

激活时

1. 读取 ./assets/module.yaml，获取模块元数据（code 字段是模块标识符）。
2. 检查 {project-root}/_bmad/ 是否存在。如果不存在，则说明此项目未安装 BMAD——请告知用户，并说明自动化技能需要 BMAD。设置流程仍可安装编排工具。
3. 检查 {project-root}/_bmad/bmad-loop/ 是否存在。如果存在，则说明该模块由 BMAD 安装程序安装，且已完成注册。如果不存在，请告知用户该模块尚未在 BMAD 中注册，并说明通过 npx bmad-method install 安装（选择 bmad-loop）即可将其添加到 /bmad-help。不要因此阻止设置流程——无论是否存在，都要继续。在 BMAD v7 中，应改用 bmad setup bmad-loop 安装该模块（参见 bmad-loop 的 docs/setup-guide.md 中的“Installing on BMAD v7”），而不是使用 v6 安装程序。

判断是全新安装还是升级。 这决定是否升级工具以及是否刷新项目中的技能。符合以下任一条件时，按升级处理：

• 用户在参数中提出了升级要求——例如 upgrade、update、upgrade tool and skills 或类似表述。
• 已通过 uv 安装编排工具：运行 uv tool list 并查找 bmad-loop 条目。（仅凭 bmad-loop --version 不足以判断——源码检出目录或不相关的虚拟环境也可能提供此命令；请参见下方第 1 步。）

否则按全新安装处理。继续操作前先向用户说明判断结果，例如：“检测到已有 bmad-loop 安装——正在运行升级：工具 + 技能”或“未检测到已有安装——正在运行全新设置”。

如果用户提供了参数（例如 accept all defaults、--headless、upgrade），则使用这些参数并跳过交互式提示。仍需在最后显示完整的确认摘要。

注册帮助条目

刷新模块的帮助条目。这是此技能在 _bmad/ 下写入的唯一文件，且内容与 BMAD 安装程序本身放置在此处的内容完全一致——因此，对于通过安装程序安装的项目，此操作不会产生任何变化；每次重新运行也都是幂等的。

mkdir -p "{project-root}/_bmad/bmad-loop"
cp ./assets/module-help.csv "{project-root}/_bmad/bmad-loop/module-help.csv"

/bmad-help 会读取汇总后的目录 _bmad/_config/bmad-help.csv，该目录由 BMAD 安装程序根据每个 _bmad/<module>/module-help.csv 重新生成。因此，对于从未运行过 BMAD 安装程序的项目，这些条目要等到下次运行安装程序时才会显示，而不是立即显示。请在 Confirm 步骤中如实说明这一点，不要声称帮助系统已经更新。

如果 {project-root}/_bmad/ 不存在，则完全跳过此步骤。

安装编排器工具

编排器会通过所选适配器启动全新的编码 CLI 会话，以调用 bmad-build-auto（上游开发基础工具；在更名前的版本中为 bmad-dev-auto）执行开发阶段，然后在 done 规格上再次调用它执行后续审查阶段，并调用 bmad-loop-sweep，监视它们的钩子信号并验证其产物。因此，安装它属于设置步骤，而非可选附加项。

为什么从 Git 安装？ BMAD 安装程序只会将技能目录复制到项目中，不会复制同级文件，因此该工具无法随技能文件夹一同安装。规范来源是 https://github.com/bmad-code-org/bmad-loop。（不过反过来则可以：该工具的 wheel 包含这些技能，因此 bmad-loop init 可以自行将它们放入项目的技能目录中——见第 3 步。）

除非用户明确要求跳过（例如 skills only / --no-tool），否则现在就安装或升级并进行引导设置。运行前，将 {project-root} 解析为实际项目路径。

1. **检查 PATH 中已有的内容：**运行 bmad-loop --version。这里能显示版本，并不意味着此项目已完成设置——这只表示当前环境中有某个 bmad-loop 可以导入。在信任它之前，运行 uv tool list 并查找 bmad-loop：如果未找到（PATH 中的副本来自源码检出或无关的虚拟环境），请提醒用户当前环境中的副本正在遮蔽干净安装，且项目将依赖该检出。除非用户明确拒绝，否则请从下方的规范来源安装或升级，以免项目依赖偶然存在的开发环境。

2. 从 Git 仓库安装或升级（[tui] extra 会安装 Textual 仪表板，以便 bmad-loop tui 正常工作）。uv tool install 会将 bmad-loop 安装到 uv 自己管理的环境中，因此不会遇到 PEP 668 的外部管理环境冲突，也不需要使用 --user、激活虚拟环境或 --break-system-packages。

   • 全新安装（uv 未管理 bmad-loop）：

     uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
     

     如需固定到某个发行版标签以确保可复现，可在 Git URL 后追加 @v<X.Y.Z>。

   • 升级（bmad-loop 已由 uv 管理）：

     1. 先记录当前版本，以便报告版本变化：bmad-loop --version。

     2. 默认方式——跟随 main（或当前固定的标签）：

        uv tool upgrade bmad-loop --reinstall
        

        对于 Git 源，必须使用 --reinstall：普通的 uv tool upgrade 会复用缓存的提交，不会拉取新代码。然后询问用户是否要固定到发行版标签以确保可复现——如果用户想要特定版本，请使用以下命令切换：

        uv tool install --force "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git@v<X.Y.Z>"
        

     3. 再次运行 bmad-loop --version，并记录升级前后的版本，以便在确认步骤中说明。

3. 引导设置项目——安装编码 CLI 钩子、随附的 bmad-loop-* 技能、.bmad-loop/policy.toml 模板和 gitignore 条目（幂等）。 首先，决定编排器应驱动哪些编码 CLI。支持的适配器有 claude（默认）、codex、gemini、copilot 和 antigravity（Google 的 agy）。钩子按 CLI 注册，因此这个选择很重要——注册你打算用于开发、审查和分类处理的所有 CLI。询问用户（除非他们已在设置参数中指定，例如 cli: claude, codex，或接受了默认值——此时仅使用默认的 claude）：

   "编排器应驱动哪些编码 CLI？可选 claude、codex、gemini、copilot 和／或 antigravity。你可以选择多个。[claude]"

   对每个选中的 CLI 添加一个 --cli <name>，构建命令（该标志可重复使用）。升级时，追加 --force-skills，以便实际刷新各项目中的技能副本——不加此标志时，init 会跳过所有已存在的技能目录，导致项目使用的技能仍是旧版，而工具已升级。全新安装时，不要加此标志。

   # fresh install, claude only (default)
   bmad-loop init --project "{project-root}" --cli claude
   
   # fresh install, multiple, e.g. claude + codex + gemini
   bmad-loop init --project "{project-root}" --cli claude --cli codex --cli gemini
   
   # upgrade — refresh the bundled skills in place
   bmad-loop init --project "{project-root}" --cli claude --force-skills
   

   名称必须严格为 claude、codex、gemini、copilot 或 antigravity——如果配置文件名称未知，init 会报错并列出有效选项。init 会输出每个 CLI 的一次性首次运行说明（例如，先在项目中启动一次 claude，并接受工作区信任和钩子批准对话框，然后再运行 bmad-loop run——启动的会话无法响应首次运行对话框）。请将这些说明转达给用户。

   技能会自动安装：init 会将捆绑的 bmad-loop-* 技能放入每个选定 CLI 对应的目录——claude 使用 .claude/skills/，codex／gemini／copilot／antigravity 使用 .agents/skills/。全新安装时，不会改动现有技能目录；升级时，--force-skills 会用升级后的工具所捆绑的副本覆盖这些目录（使用 --no-skills 可跳过此步骤并自行管理技能）。

   注意：--force-skills 也会覆盖 bmad-loop-setup 本身（它包含在同一捆绑包中）。这是预期行为，且安全无虞——刚安装的 setup 技能会在下一次调用时生效，而你的 _bmad/custom/*.toml 覆盖项（按技能目录名称匹配）不会受到影响。

4. 预检——验证配置、sprint-status、git、tmux 和编码 CLI：

   bmad-loop validate --project "{project-root}"
   

   如果项目尚未完全就绪（例如，还没有 sprint-status.yaml，或尚未运行 bmad-sprint-planning），validate 会以非零状态码退出。对于全新项目，这是预期情况——将检查结果作为就绪情况清单告知用户，而不是报告安装失败。

5. **告知用户各角色的适配器配置位置。**第 3 步中的 --cli 只会为每个 CLI 注册_钩子_。实际由哪个 CLI 运行各阶段，取决于 {project-root}/.bmad-loop/policy.toml；该文件由 init 根据模板生成。[adapter] name（默认值为 claude）适用于所有阶段；可选的 [adapter.dev]、[adapter.review] 和 [adapter.triage] 表则可覆盖各个阶段（每个阶段都可单独设置 name、model、effort 和 extra_args）。因此，混合配置（例如开发阶段使用 claude、审查阶段使用 codex）既需要注册钩子（第 3 步），也需要在 policy.toml 中将对应角色指向该 CLI：

   [adapter]
   name = "claude"        # default for all stages
   
   [adapter.review]
   name = "codex"         # review runs on codex instead
   

   告知用户该文件的位置，并说明 policy.toml 中指定的任何 CLI 都必须已在第 3 步通过 --cli 注册（之后可运行 bmad-loop init --cli <name> 来添加）。如果用户只使用一个 CLI，则不要修改 policy.toml——默认设置是正确的。

确认

报告：

• **全新安装：**已安装的 bmad-loop --version 版本；bmad-loop init 已注册钩子、安装 bmad-loop-* 技能，并为选定的编码 CLI 写入策略和 gitignore（逐一列出名称，例如“已为 claude、codex 安装钩子和技能”）。
• **升级：**升级前 → 升级后的 bmad-loop --version（例如“已从 0.3.1 升级到 0.3.2”，或“已是最新版本 0.3.2”），并说明在每个 CLI 目录树中使用 --force-skills 刷新了（而非跳过）bmad-loop-* 技能。

另外还要报告：

• bmad-loop validate 预检结果（通过，或列出尚缺内容的就绪检查清单）。
• 已刷新 _bmad/bmad-loop/module-help.csv。如果本次运行前 _bmad/bmad-loop/ 不存在（即 BMAD 安装程序从未安装该模块），请说明 BMAD 安装程序下次运行后，帮助条目会出现在 /bmad-help 中；通过 npx bmad-method install 安装该模块可正确注册（BMAD v7 则改用 bmad setup bmad-loop）。
• 此技能未在 _bmad/ 下写入其他内容——模块注册、config.toml 和帮助目录均由 BMAD 安装程序管理。

然后向用户显示 ./assets/module.yaml 中的 module_greeting。

结果

在本次会话的其余部分使用用户配置的姓名和语言。通过 BMAD 自带的解析器从其中央配置中读取这些信息（四层 TOML 合并；需要 BMAD v6.10+ 和 Python 3.11+）：

uv run "{project-root}/_bmad/scripts/resolve_config.py" --project-root "{project-root}" --key core

从 core 表中获取 user_name 和 communication_language。如果脚本不存在或退出状态非零，则改用英文中性称呼用户——不要写入或修复任何配置文件。