企业官网建设流程全解析

BMAD-METHOD 自定义模块安装完全指南：社区模块、Git 源与本地模块的接入实践

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

本文基于 BMAD-METHOD 仓库的官方文档 install-custom-modules.md，系统讲解如何使用 BMad 安装器（npx bmad-method install）安装三类非官方模块：来自社区注册表（marketplace）的插件、来自任意 Git 仓库（含私有/自托管服务器）的模块、以及本地开发中的模块。读完后，你将能够完成从交互式浏览社区目录、--custom-source非交互安装、理解安装器的模块发现机制（Discovery/Direct 双模式），到本地模块迭代开发与更新的完整工作流，并掌握_bmad/目录中 manifest 对模块来源的追踪方式。

适用场景与前置条件

安装器支持以下四类场景，均通过同一入口npx bmad-method install完成：

• 从 BMad 社区注册表安装社区贡献的模块；
• 从第三方 Git 仓库安装模块（GitHub、GitLab、Bitbucket 或自托管服务器均可）；
• 测试自己用 BMad Builder 在本地开发的模块；
• 从私有或自托管 Git 服务器安装模块。

前置条件：需要 Node.js v20.12+ 以及随 npm 提供的npx；若使用 Git URL 作为源，还需要本机安装 Git。自定义模块和社区模块既可以在全新安装时选择，也可以追加到已有安装上（详见 install-bmad.md）。

安装社区模块：交互式浏览目录

社区模块集中存放在 bmad-plugins-marketplace 仓库中（注册表按类别组织，且每个模块都被固定在一个经过审批的 commit 上以保证安全性）。安装流程分为四步：

1. 启动安装器

npx bmad-method install

2. 浏览社区目录

在选择完官方模块之后，安装器会提示：

Would you like to browse community modules?

选择Yes即可进入目录浏览器（catalog browser），支持：

• 按类别浏览（Browse by category）；
• 查看精选模块（Featured modules）；
• 查看全部可用模块（All modules）；
• 按关键词搜索（Search by keyword）。

3. 选择模块

可以在任意类别中选择模块。安装器会展示每个模块的描述、版本和信任级别（trust level）。已安装的模块会被预选中，以便直接升级。

4. 继续安装流程

选定社区模块后，安装器依次进入：自定义源（custom source）步骤、工具/IDE 配置，以及后续常规安装流程。

自定义源：任意 Git 仓库与本地目录

自定义模块可以来自任意 Git 仓库或本机上的任意本地目录。安装器负责解析源、分析模块结构，并将其安装到其他模块旁边。

交互式安装

在安装过程中经过社区模块步骤之后，安装器会提示：

Would you like to install from a custom source (Git URL or local path)?

选择Yes后输入源地址。官方英文版文档 add-modules.md 还补充了安全提示：对 URL 源，安装器会给出警告「UNVERIFIED MODULE: This module has not been reviewed by the BMad team. Only install modules from sources you trust.」；对本地路径，则提示改动需重新安装后生效。随后安装器列出发现的模块供你挑选——已安装的模块会预勾选为更新；在继续安装前你还可以追加其他源。

支持的输入类型：

注：@ref固定（如@v1.2.0）在英文版 add-modules.md 中有明确说明，法语版表格未列出，实践时两种行为一致。

安装器对 URL 源执行 clone，对本地路径则直接从磁盘读取，然后展示发现的模块供选择。

非交互式安装

使用--custom-source选项即可在命令行完成自定义模块安装：

npx bmad-method install \ --directory . \ --custom-source /path/to/my-module \ --tools claude-code \ --yes

关键行为约定：

• 当只提供--custom-source而不提供--modules时，仅安装 core 与自定义模块；若还要包含官方模块，需追加--modules：

npx bmad-method install \ --directory . \ --modules bmm \ --custom-source https://gitlab.com/myorg/my-module \ --tools claude-code \ --yes

• 多个源可用逗号分隔：

--custom-source /path/one,https://github.com/org/repo,/path/two

英文版文档进一步说明：无法解析的源会被报告并跳过，其余源仍正常安装，即失败不会中断整批安装。

安装器的模块发现机制：两种模式

安装器使用两种模式来在源中寻找可安装的模块，模式由源的内容自动决定：

Discovery 模式是已发布模块的典型形态；Direct 模式适合在本地开发时直接指向一个 skills 目录。

这个机制在仓库源码结构中有直接印证。BMAD-METHOD 仓库自身的 skills/ 目录就是标准的 Direct 模式布局：每个技能都是一个含SKILL.md的子目录，例如 skills/bmad-architecture/ 下的 SKILL.md 声明技能名称与描述，并附带customize.toml与 module-manifest.toml。从源码结构看，Direct 模式扫描的正是这种「子目录 + SKILL.md」约定，因此任何符合该布局的仓库或目录都能被安装器识别。

关于.claude-plugin/的说明：.claude-plugin/marketplace.json是多个 AI 工具安装器共同采用的标准约定，用于插件的可发现性。它不依赖 Claude、不调用 Claude API，也不影响你实际使用的 AI 工具——任何包含此文件的模块都能被遵循该约定的安装器发现。

本地开发工作流：从工作目录直接安装

如果你正在用 BMad Builder 构建模块，可以直接从工作目录安装，无需先发布：

npx bmad-method install \ --directory ~/my-project \ --custom-source ~/my-module-repo/skills \ --tools claude-code \ --yes

本地源以路径被引用，而不是被拷贝进缓存。当你更新模块源码后重新安装，安装器会拉取最新改动。

注意（源目录删除的影响）：如果在安装后删除了本地源目录，已安装在_bmad/中的模块文件会被保留，但更新操作会忽略该模块，直到源路径被恢复。英文版文档将其表述为「skipped with a warning」。

安装产物：_bmad 目录结构与 manifest 追踪

安装完成后，自定义模块与官方模块一起出现在_bmad/中：

your-project/ ├── _bmad/ │ ├── core/ # 内置核心模块 │ ├── bmm/ # 官方模块（如选中） │ ├── my-module/ # 你的自定义模块 │ │ ├── my-skill/ │ │ │ └── SKILL.md │ │ └── module-help.csv │ └── _config/ │ └── manifest.yaml # 追踪所有模块、版本与来源 └── ...

manifest 会记录每个自定义模块的来源：Git 源记录为repoUrl，本地源记录为localPath，从而让快速更新（quick update）能够重新定位源。

这一点与仓库内模块清单文件的实现相互印证：仓库中每个技能的 module-manifest.toml 均包含模块标识、版本号与来源声明，例如bmad-architecture的清单为：

module = "method" version = "6.13.0-next" update_source = "github:bmad-code-org/BMAD-METHOD/skills"

从源码结构看，update_source字段正是「模块知道自己的来源」这一机制的体现——更新器依据该字段（对应 manifest 中的repoUrl/localPath）定位原始源，重新拉取或重读。

更新自定义模块

自定义模块参与常规的更新流程：

• 快速更新（--action quick-update）：从记录的原始源刷新所有模块。Git 模块会重新下载，本地模块会重新从源路径读取。补充细节（见 add-modules.md）：源不可用的模块会被跳过并告警，其文件原样保留；Git 源无法访问时不刷新，而是使用带警告的缓存克隆。
• 完整更新：重新执行模块选择流程，方便你增删自定义模块。英文版补充：当使用--yes且未指定--action时，传入--custom-source会默认走完整更新而非快速更新。

创建并发布自己的模块

使用 BMad Builder 可以创建供他人安装的模块，标准流程为：

1. 运行bmad-module-builder生成模块骨架结构；
2. 借助 BMad Builder 的各工具添加 skills、agents 与 workflows；
3. 发布到 Git 仓库或直接分享目录；
4. 其他人通过--custom-source <你的仓库URL>安装。

若希望模块支持 Discovery 模式，需要在仓库根目录放置.claude-plugin/marketplace.json（这是跨工具的通用约定，而非 Claude 专属）。marketplace.json的格式请参阅 BMad Builder 的官方文档。

实践建议：开发阶段先用本地路径安装自己的模块进行快速迭代，验证通过后再发布到 Git 仓库——这样既利用了本地源「按路径引用、重装即最新」的特性，又能保证发布后的模块对其他安装器是可发现、可复现的。

小结

BMAD-METHOD 的模块安装体系通过一个安装器统一了三种模块来源：社区注册表（交互式目录浏览，带版本与信任级别）、任意 Git 源（含 HTTP/HTTPS/SSH/子路径/@ref固定与私有服务器）以及本地路径（--custom-source逗号分隔多源）。发现机制由源中是否存在.claude-plugin/marketplace.json自动切换 Discovery 与 Direct 两种模式；安装结果统一落在_bmad/下，由_config/manifest.yaml记录repoUrl/localPath以支撑后续的 quick-update 与完整更新。结合本仓库 skills/ 目录中「SKILL.md + customize.toml + module-manifest.toml」的实际布局，开发者可以按同一约定编写自己的技能目录，从而直接接入 BMad 的安装与更新体系。

相关文档延伸阅读：安装 BMad、添加模块（英文版）、自定义 BMad（法文）。

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