企业官网建设流程全解析

• 开发工具
• CLI
• AI 应用

/bmad-init是 ZCF（Zero-Config Code Flow for Claude Code & Codex）预置的 BMad 敏捷工作流入口命令，用于在任意项目中对 BMad-Method V6 进行全新初始化或快速更新。本文将结合 ZCF 仓库中的 SKILL 定义文件（同源中文版见 templates/skills/zh-CN/bmad-init/SKILL.md）与 工作流安装器源码，逐段拆解该命令的完整执行逻辑、底层安装命令参数、旧版 V4 迁移策略、已知安装器 Bug 的自动修复，以及安装后的目录结构与后续操作指引，让你彻底掌握 BMad 工作流的自动化接入方式。

一、命令定位：BMad 工作流在 ZCF 中的角色

BMad（Build-Measure-Analyze-Decision）是一个面向企业级项目的 AI 驱动敏捷开发工作流。在 ZCF 中，它作为五大预置工作流之一被统一管理，配置定义在 src/config/workflows.ts：

{ id: 'bmadWorkflow', defaultSelected: true, order: 5, skills: ['bmad-init'], agents: [], autoInstallAgents: false, category: 'bmad', outputDir: 'bmad', }

从该配置可以看出几个关键事实：

• skills字段只包含bmad-init一个 skill，即本文解析的SKILL.md文件；
• defaultSelected: true，意味着zcf init时默认就会选中导入该工作流；
• autoInstallAgents: false，说明该工作流不需要随附的 agent 文件（与featPlanUx的规划代理、UX 代理机制不同）；
• 相关 i18n 文案定义于 src/i18n/locales/zh-CN/workflow.json，例如"bmadInitPrompt": "✨ 请在项目中运行 /bmad-init 命令来初始化或更新 BMAD-Method 扩展"，安装完成后安装器会输出这一提示。

值得注意的适用范围限制：ZCF 的 工作流系统文档 明确指出，Codex 目前仅支持sixStepsWorkflow与gitWorkflow，bmadWorkflow仅在 Claude Code 中提供。也就是说/bmad-init是面向 Claude Code 环境的命令。

二、命令调用方式与 Skill 元数据

在 Claude Code 中，直接在会话中输入即可触发：

/bmad-init

SKILL 文件的 frontmatter 定义了关键元数据：

--- name: bmad-init description: Initialize or update BMad-Method (V6) in your project disable-model-invocation: true ---

disable-model-invocation: true表示该命令只能由用户显式输入/bmad-init触发，模型不会在对话中被自动唤起执行，这保证了 BMad 的安装行为完全由用户掌控。安装完成后的引导输出也会提示：重启 AI IDE 以加载 BMad 扩展，随后输入/bmad-help获取引导，输入/bmad并通过自动补全浏览可用命令。

三、命令执行流程总览

当用户输入/bmad-init后，命令按以下 7 个步骤顺序执行：

1. 检查项目根目录是否存在_bmad/目录，判断 BMad V6 是否已安装；
2. 检查是否存在旧版 V4 安装（.bmad-core或.bmad-method目录）；
3. 全新安装时执行：npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes；
4. 已安装时执行：npx bmad-method install --directory . --action quick-update --yes；
5. 修复安装器 Bug：将{output_folder}重命名为_bmad-output（V6 Beta 已知问题）；
6. 自动更新.gitignore（移除 V4 旧条目，添加 V6 新条目）；
7. 显示安装结果与目录结构，并提示用户后续操作。

下文将结合完整 JavaScript 实现逐一展开。

四、安装状态检测：V6 / V4 遗留 / 未安装三分支

命令入口initBmad()首先以process.cwd()为项目根目录，检测三类标志性目录（SKILL.md）：

const cwd = process.cwd() const bmadV6Path = path.join(cwd, '_bmad') const legacyCorePath = path.join(cwd, '.bmad-core') const legacyMethodPath = path.join(cwd, '.bmad-method') const hasLegacyCore = fs.existsSync(legacyCorePath) const hasLegacyMethod = fs.existsSync(legacyMethodPath) if (hasLegacyCore || hasLegacyMethod) { console.log('⚠️ Legacy BMad V4 installation detected:') // .bmad-core/ (V4 core directory) / .bmad-method/ (V4 method directory) // V6 installer will handle legacy migration automatically } const hasV6 = fs.existsSync(bmadV6Path)

检测结果决定后续行为：

从代码结构可以推断，该命令刻意采用"非交互式参数 + 终端提示"的组合：安装动作本身通过--yes全自动执行，而 V4 迁移这类需要人工确认的场景则交给bmad-method安装器的交互提示完成，二者职责清晰。

五、安装命令构建：全新安装与快速更新

命令根据hasV6分支构建不同的npx bmad-method install命令（SKILL.md）：

let installCmd if (hasV6) { console.log('🔄 Existing BMad V6 installation detected, performing quick update...') installCmd = [ 'npx bmad-method install', '--directory .', '--action quick-update', '--yes', ].join(' ') } else { console.log('🚀 Initializing BMad-Method V6...') installCmd = [ 'npx bmad-method install', '--directory .', '--modules bmm', '--tools claude-code', '--communication-language English', '--document-output-language English', '--yes', ].join(' ') }

全新安装命令的完整参数说明：

快速更新命令则精简为三个参数：--directory .、--action quick-update、--yes，复用已有安装的模块与语言配置，只做增量更新。

命令最终通过 Node.js 的child_process.execSync同步执行，并开启stdio: 'inherit'将安装器输出实时透传到终端：

execSync(installCmd, { stdio: 'inherit', cwd: cwd, shell: true })

六、安装器 Bug 自动修复：{output_folder}→_bmad-output

BMad-Method V6.0.0-Beta.8 存在一个已知问题：安装器在创建输出目录时未将占位符{output_folder}解析为实际目录名_bmad-output，导致项目根目录出现一个字面名为{output_folder}的错误目录。/bmad-init在安装成功后自动执行修复函数fixOutputFolderBug(cwd)（SKILL.md）：

function fixOutputFolderBug(cwd) { const buggyPath = path.join(cwd, '{output_folder}') const correctPath = path.join(cwd, '_bmad-output') if (!fs.existsSync(buggyPath)) return false if (!fs.existsSync(correctPath)) { // _bmad-output doesn't exist, simply rename fs.renameSync(buggyPath, correctPath) console.log(' ✅ {output_folder} → _bmad-output/ (renamed)') } else { // _bmad-output already exists, merge subdirectories then delete const entries = fs.readdirSync(buggyPath, { withFileTypes: true }) for (const entry of entries) { const src = path.join(buggyPath, entry.name) const dest = path.join(correctPath, entry.name) if (!fs.existsSync(dest)) { fs.renameSync(src, dest) console.log(` ✅ Moved ${entry.name} → _bmad-output/`) } } fs.rmSync(buggyPath, { recursive: true, force: true }) console.log(' ✅ Removed redundant {output_folder}/') } return true }

该函数的修复逻辑分两种情况：

• _bmad-output/尚不存在：直接将{output_folder}整个重命名为_bmad-output；
• _bmad-output/已存在：遍历{output_folder}下的子目录，仅移动不冲突的条目合并进_bmad-output，最后递归删除冗余的{output_folder}目录，避免覆盖已有产物。

若修复过程抛出异常，命令会捕获错误并提示用户手动执行重命名，同时给出兜底指引：Please manually rename {output_folder}/ to _bmad-output/。

七、.gitignore自动更新：V4 清理与 V6 条目追加

安装完成后，命令自动维护.gitignore，避免 BMad 工作目录和输出目录被误提交到 Git。更新函数updateGitignore(cwd)（SKILL.md）基于两组硬编码常量工作：

// Legacy entries to clean from .gitignore const LEGACY_GITIGNORE_ENTRIES = [ '.bmad-core', '.bmad-method', '.claude/commands/BMad', '{output_folder}', // v6.0.0-Beta.8 bug artifact ] // V6 .gitignore entries const V6_GITIGNORE_ENTRIES = [ '_bmad/', '_bmad-output/', ]

处理流程为：

1. 读取：若.gitignore存在则读取全文，否则视为空文件；
2. 清理 V4 遗留：按行过滤，命中LEGACY_GITIGNORE_ENTRIES（含带/后缀或/前缀的等价写法）即删除并输出🗑️ Removing legacy entry；注意.claude/commands/BMad与 Bug 产物{output_folder}也会被一并清理；
3. 追加 V6 条目：对_bmad/与_bmad-output/做去重检查（兼容entry、entryBase、/entryBase三种写法），缺失则追加；
4. 写入：仅在有变更时写回文件，追加时先确保末尾换行，再以# BMad Method V6注释块收尾；若文件原本不存在，则会创建新的.gitignore。

若自动更新失败，命令会降级提示用户手动添加_bmad/和_bmad-output/两条规则。

八、安装结果输出与后续引导

安装成功、Bug 修复、.gitignore更新完成后，命令输出 V6 目录结构与快速开始指引：

📂 V6 Directory Structure: • _bmad/ — agents, workflows, tasks, and configuration • _bmad-output/ — generated artifact output directory 🚀 Quick Start: 1. Restart your AI IDE 2. Run /bmad-help for guidance and next step suggestions 3. Type /bmad and use autocomplete to browse available commands

V6 目录职责：_bmad/存放 agents（AI 代理）、workflows（工作流）、tasks（任务）与配置；_bmad-output/是工作流产物的输出目录。

同时输出常用 BMad 命令速查表：

此外，命令还会检查 Claude Code 遗留的 V4 命令目录.claude/commands/BMad/agents与.claude/commands/BMad/tasks，若存在则提示用户手动删除，并说明新 V6 命令已安装到.claude/commands/bmad/下。

九、ZCF 侧安装链路：从zcf init到/bmad-init可用

/bmad-init之所以能在 Claude Code 中直接输入，背后是 ZCF 工作流安装器的完整链路。入口是zcf init（或npx zcf i），用户可通过--workflows参数显式选择：

# 仅安装 BMad 工作流 npx zcf i -s -w bmadWorkflow # 安装全部工作流（bmadWorkflow 默认选中） npx zcf i -s -w all

安装器selectAndInstallWorkflows()的逻辑位于 src/utils/workflow-installer.ts：

1. 通过getOrderedWorkflows()获取按order排序的预置工作流列表，bmadWorkflow排在第 5 位（该顺序由 tests/config/workflows.test.ts 断言验证）；
2. 对每个选中的工作流调用installWorkflowWithDependencies()，其中bmadWorkflow的 skill 源文件被定位为templates/skills/{lang}/bmad-init/SKILL.md（即本文解析的英文/中文模板）；
3. 所有 skill 名汇总后交给installSkills()统一安装到 Claude Code 的~/.claude/skills/目录；
4. 若bmadWorkflow安装成功，额外输出 i18n 文案bmadInitPrompt，引导用户在项目内执行/bmad-init。

对应测试可见 tests/unit/utils/workflow-installer.test.ts，其中 mock 的bmadWorkflow配置同样声明skills: ['bmad-init']与category: 'bmad'，验证了安装器对 skill 名的解析与归类行为。zcf update在模板更新后也会重新执行工作流导入，确保SKILL.md的最新内容能同步到本地。

十、故障处理与手动安装兜底

安装器（bmad-method install）执行失败时，execSync会抛出异常，命令捕获后输出手动安装指南：

# 1. 确保已安装 Node.js 20+ node --version # 2. 非交互式安装（全新安装） npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes # 3. 快速更新已有安装 npx bmad-method install --directory . --action quick-update --yes # 4. 或直接交互式安装 npx bmad-method install

常见失败场景还包括：

• 未在项目根目录执行：先用pwd确认当前目录；
• 工作流未导入：执行npx zcf update重新导入，并检查~/.claude/skills/下是否存在bmad-init；
• 文档未正确生成：手动查看PRD.md、ARCHITECTURE.md等产物，或再次运行/bmad-init（该命令会先检测安装状态，对已有安装走快速更新合并路径，不会覆盖已有内容）。

十一、使用建议与适用边界

结合 docs/zh-CN/workflows/bmad.md 的说明，/bmad-init引入的 BMad 工作流特别适合大型项目、多角色团队协作、长期迭代与规范化开发场景；而对于快速原型、小型个人项目与一次性脚本，则建议使用 ZCF 的六阶段工作流（/workflow）或功能开发工作流（/feat）这类更轻量的方案。在企业团队中，建议全员统一执行/bmad-init，以保证工作流规范与文档格式的一致；同时可通过npx zcf的菜单配置 Context7、DeepWiki 等 MCP 服务，为 BMad 的迭代分析与决策阶段提供外部信息支撑。

综上所述，/bmad-init是一个高度自动化的"零配置"入口：它内置了安装状态检测、非交互式安装、Beta 版本 Bug 修复、.gitignore维护与遗留版本清理五重能力，将 BMad-Method V6 的企业级敏捷流程接入成本压缩到一次命令输入。

• 开发工具
• CLI
• AI 应用