BMAD-METHOD/install-custom-modules.md at fix-arch-validation-prechecked

6.2 KiB

Raw Permalink Blame History

title

description

sidebar

安装自定义和社区模块

从社区注册表、Git 仓库或本地路径安装第三方模块

order
3

使用 BMad 安装程序从社区注册表、第三方 Git 仓库或本地文件路径添加模块。

何时使用

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

:::note[前置条件] 需要 Node.js v20+ 和 npx（npm 自带）。自定义和社区模块可以在全新安装时选择，也可以添加到现有安装中。 :::

社区模块

社区模块收录在 BMad 插件市场。它们按类别组织，并锁定在经过审核的 commit 上以确保安全。

1. 运行安装程序

npx bmad-method install

2. 浏览社区目录

选择官方模块后，安装程序会询问：

Would you like to browse community modules?

选择 Yes 进入目录浏览器。你可以：

按类别浏览
查看推荐模块
查看所有可用模块
按关键词搜索

3. 选择模块

从任意类别中选取模块。安装程序显示描述、版本和信任等级。已安装的模块会预选以便更新。

4. 继续安装

选择社区模块后，安装程序将继续到自定义来源，然后是工具/IDE 配置及其余安装流程。

自定义来源（Git URL 和本地路径）

自定义模块可以来自任何 Git 仓库或本地目录。安装程序会解析来源、分析模块结构，并将其与其他模块一起安装。

交互式安装

安装过程中，在社区模块步骤之后，安装程序会询问：

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

选择 Yes，然后提供来源：

输入类型	示例
HTTPS URL（任意主机）	`https://github.com/org/repo`
HTTP URL（任意主机）	`http://host/org/repo`
带子目录的 HTTPS URL	`https://github.com/org/repo/tree/main/my-module`
SSH URL	`git@github.com:org/repo.git`
本地路径	`/Users/me/projects/my-module`
使用 ~ 的本地路径	`~/projects/my-module`

安装程序会克隆仓库（URL 来源）或直接从磁盘读取（本地路径），然后展示发现的模块供你选择。

非交互式安装

使用 --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

模块发现机制

安装程序使用两种模式在来源中查找可安装的模块：

模式	触发条件	行为
发现模式	来源包含 `.claude-plugin/marketplace.json`	列出清单中的所有插件；你选择要安装哪些
直接模式	未找到 marketplace.json	扫描目录中的 skill（包含 `SKILL.md` 的子目录），作为单个模块解析

发现模式适用于已发布的模块。直接模式适合本地开发时指向 skills 目录。

:::note[关于 .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

本地来源通过路径引用，不会复制到缓存。当你更新模块源码并重新安装时，安装程序会获取最新变更。

:::caution[来源移除] 如果你在安装后删除了本地来源目录，_bmad/ 中已安装的模块文件会保留。在恢复来源路径之前，该模块在更新时会被跳过。 :::

安装结果

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

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

manifest 记录每个自定义模块的来源（Git 来源为 repoUrl，本地来源为 localPath），以便快速更新时能重新定位来源。

更新自定义模块

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

快速更新（--action quick-update）：从原始来源刷新所有模块。基于 Git 的模块会重新拉取；本地模块会从来源路径重新读取。
完整更新：重新运行模块选择，你可以添加或移除自定义模块。

创建自己的模块

使用 BMad Builder 创建可供他人安装的模块：

运行 bmad-module-builder 搭建模块结构
使用各种 BMad Builder 工具添加 skill、agent 和 workflow
发布到 Git 仓库或共享文件夹集合
他人使用 --custom-source <your-repo-url> 安装

要让模块支持发现模式，请在仓库根目录包含 .claude-plugin/marketplace.json（这是跨工具约定，非 Claude 专属）。格式详见 BMad Builder 文档。

:::tip[先在本地测试] 开发期间，使用本地路径安装模块以快速迭代，发布到 Git 仓库之前先确认一切正常。 :::

6.2 KiB Raw Permalink Blame History Unescape Escape