bmad-method 6.0.4 → 6.0.5-next.0

package/docs/zh-cn/how-to/install-bmad.md

@@ -0,0 +1,105 @@
+---
+title: "如何安装 BMad"
+description: 在项目中安装 BMad 的分步指南
+sidebar:
+  order: 1
+---
+
+使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。
+
+如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。
+
+## 何时使用
+
+- 使用 BMad 启动新项目
+- 将 BMad 添加到现有代码库
+- 更新现有的 BMad 安装
+
+:::note[前置条件]
+- **Node.js** 20+（安装程序必需）
+- **Git**（推荐）
+- **AI 工具**（Claude Code、Cursor 或类似工具）
+:::
+
+## 步骤
+
+### 1. 运行安装程序
+
+```bash
+npx bmad-method install
+```
+
+:::tip[最新版本]
+要从主分支安装最新版本（可能不稳定）：
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+:::
+
+### 2. 选择安装位置
+
+安装程序会询问在哪里安装 BMad 文件：
+
+- 当前目录（如果你自己创建了目录并从该目录运行，推荐用于新项目）
+- 自定义路径
+
+### 3. 选择你的 AI 工具
+
+选择你使用的 AI 工具：
+
+- Claude Code
+- Cursor
+- 其他
+
+每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。
+
+### 4. 选择模块
+
+安装程序会显示可用的模块。选择你需要的模块——大多数用户只需要 **BMad Method**（软件开发模块）。
+
+### 5. 按照提示操作
+
+安装程序会引导你完成剩余步骤——自定义内容、设置等。
+
+## 你将获得
+
+```text
+your-project/
+├── _bmad/
+│   ├── bmm/            # 你选择的模块
+│   │   └── config.yaml # 模块设置（如果你需要更改它们）
+│   ├── core/           # 必需的核心模块
+│   └── ...
+├── _bmad-output/       # 生成的工件
+├── .claude/            # Claude Code 命令（如果使用 Claude Code）
+└── .kiro/              # Kiro 引导文件（如果使用 Kiro）
+```
+
+## 验证安装
+
+运行 `/bmad-help` 来验证一切正常并查看下一步操作。
+
+**BMad-Help 是你的智能向导**，它会：
+- 确认你的安装正常工作
+- 根据你安装的模块显示可用内容
+- 推荐你的第一步
+
+你也可以向它提问：
+```
+/bmad-help 我刚安装完成，应该先做什么？
+/bmad-help 对于 SaaS 项目我有哪些选项？
+```
+
+## 故障排除
+
+**安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。
+
+**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。
+
+---
+## 术语说明
+
+- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
+- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。
+- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。

package/docs/zh-cn/how-to/non-interactive-installation.md

@@ -0,0 +1,181 @@
+---
+title: "非交互式安装"
+description: 使用命令行标志安装 BMad，适用于 CI/CD 流水线和自动化部署
+sidebar:
+  order: 2
+---
+
+使用命令行标志以非交互方式安装 BMad。这适用于：
+
+## 使用场景
+
+- 自动化部署和 CI/CD 流水线
+- 脚本化安装
+- 跨多个项目的批量安装
+- 使用已知配置的快速安装
+
+:::note[前置条件]
+需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。
+:::
+
+## 可用标志
+
+### 安装选项
+
+| 标志 | 描述 | 示例 |
+|------|-------------|---------|
+| `--directory <path>` | 安装目录 | `--directory ~/projects/myapp` |
+| `--modules <modules>` | 逗号分隔的模块 ID | `--modules bmm,bmb` |
+| `--tools <tools>` | 逗号分隔的工具/IDE ID（使用 `none` 跳过） | `--tools claude-code,cursor` 或 `--tools none` |
+| `--custom-content <paths>` | 逗号分隔的自定义模块路径 | `--custom-content ~/my-module,~/another-module` |
+| `--action <type>` | 对现有安装的操作：`install`（默认）、`update`、`quick-update` 或 `compile-agents` | `--action quick-update` |
+
+### 核心配置
+
+| 标志 | 描述 | 默认值 |
+|------|-------------|---------|
+| `--user-name <name>` | 智能体使用的名称 | 系统用户名 |
+| `--communication-language <lang>` | 智能体通信语言 | 英语 |
+| `--document-output-language <lang>` | 文档输出语言 | 英语 |
+| `--output-folder <path>` | 输出文件夹路径 | _bmad-output |
+
+### 其他选项
+
+| 标志 | 描述 |
+|------|-------------|
+| `-y, --yes` | 接受所有默认值并跳过提示 |
+| `-d, --debug` | 启用清单生成的调试输出 |
+
+## 模块 ID
+
+`--modules` 标志可用的模块 ID：
+
+- `bmm` — BMad Method Master
+- `bmb` — BMad Builder
+
+查看 [BMad 注册表](https://github.com/bmad-code-org) 获取可用的外部模块。
+
+## 工具/IDE ID
+
+`--tools` 标志可用的工具 ID：
+
+**推荐：** `claude-code`、`cursor`
+
+运行一次 `npx bmad-method install` 交互式安装以查看完整的当前支持工具列表，或查看 [平台代码配置](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml)。
+
+## 安装模式
+
+| 模式 | 描述 | 示例 |
+|------|-------------|---------|
+| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
+| 半交互式 | 提供部分标志；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` |
+| 仅使用默认值 | 使用 `-y` 接受所有默认值 | `npx bmad-method install --yes` |
+| 不包含工具 | 跳过工具/IDE 配置 | `npx bmad-method install --modules bmm --tools none` |
+
+## 示例
+
+### CI/CD 流水线安装
+
+```bash
+#!/bin/bash
+# install-bmad.sh
+
+npx bmad-method install \
+  --directory "${GITHUB_WORKSPACE}" \
+  --modules bmm \
+  --tools claude-code \
+  --user-name "CI Bot" \
+  --communication-language English \
+  --document-output-language English \
+  --output-folder _bmad-output \
+  --yes
+```
+
+### 更新现有安装
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action update \
+  --modules bmm,bmb,custom-module
+```
+
+### 快速更新（保留设置）
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action quick-update
+```
+
+### 使用自定义内容安装
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --modules bmm \
+  --custom-content ~/my-custom-module,~/another-module \
+  --tools claude-code
+```
+
+## 安装结果
+
+- 项目中完全配置的 `_bmad/` 目录
+- 为所选模块和工具编译的智能体和工作流
+- 用于生成产物的 `_bmad-output/` 文件夹
+
+## 验证和错误处理
+
+BMad 会验证所有提供的标志：
+
+- **目录** — 必须是具有写入权限的有效路径
+- **模块** — 对无效的模块 ID 发出警告（但不会失败）
+- **工具** — 对无效的工具 ID 发出警告（但不会失败）
+- **自定义内容** — 每个路径必须包含有效的 `module.yaml` 文件
+- **操作** — 必须是以下之一：`install`、`update`、`quick-update`、`compile-agents`
+
+无效值将：
+1. 显示错误并退出（对于目录等关键选项）
+2. 显示警告并跳过（对于自定义内容等可选项目）
+3. 回退到交互式提示（对于缺失的必需值）
+
+:::tip[最佳实践]
+- 为 `--directory` 使用绝对路径以避免歧义
+- 在 CI/CD 流水线中使用前先在本地测试标志
+- 结合 `-y` 实现真正的无人值守安装
+- 如果在安装过程中遇到问题，使用 `--debug`
+:::
+
+## 故障排除
+
+### 安装失败，提示"Invalid directory"
+
+- 目录路径必须存在（或其父目录必须存在）
+- 您需要写入权限
+- 路径必须是绝对路径或相对于当前目录的正确相对路径
+
+### 未找到模块
+
+- 验证模块 ID 是否正确
+- 外部模块必须在注册表中可用
+
+### 自定义内容路径无效
+
+确保每个自定义内容路径：
+- 指向一个目录
+- 在根目录中包含 `module.yaml` 文件
+- 在 `module.yaml` 中有 `code` 字段
+
+:::note[仍然卡住了？]
+使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 <https://github.com/bmad-code-org/BMAD-METHOD/issues> 报告。
+:::
+
+---
+## 术语说明
+
+- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。
+- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。
+- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。
+- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。
+- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。

package/docs/zh-cn/how-to/project-context.md

@@ -0,0 +1,152 @@
+---
+title: "管理项目上下文"
+description: 创建并维护 project-context.md 以指导 AI 智能体
+sidebar:
+  order: 7
+---
+
+使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。
+
+:::note[前置条件]
+- 已安装 BMad Method
+- 了解项目的技术栈和约定
+:::
+
+## 何时使用
+
+- 在开始架构设计之前有明确的技术偏好
+- 已完成架构设计并希望为实施捕获决策
+- 正在处理具有既定模式的现有代码库
+- 注意到智能体在不同用户故事中做出不一致的决策
+
+## 步骤 1：选择方法
+
+**手动创建** — 当您确切知道要记录哪些规则时最佳
+
+**架构后生成** — 最适合捕获解决方案制定过程中所做的决策
+
+**为现有项目生成** — 最适合在现有代码库中发现模式
+
+## 步骤 2：创建文件
+
+### 选项 A：手动创建
+
+在 `_bmad-output/project-context.md` 创建文件：
+
+```bash
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+添加技术栈和实现规则：
+
+```markdown
+---
+project_name: 'MyProject'
+user_name: 'YourName'
+date: '2026-02-15'
+sections_completed: ['technology_stack', 'critical_rules']
+---
+
+# AI 智能体的项目上下文
+
+## 技术栈与版本
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- 状态管理：Zustand
+- 测试：Vitest, Playwright
+- 样式：Tailwind CSS
+
+## 关键实现规则
+
+**TypeScript：**
+- 启用严格模式，不使用 `any` 类型
+- 公共 API 使用 `interface`，联合类型使用 `type`
+
+**代码组织：**
+- 组件位于 `/src/components/` 并附带同位置测试
+- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch
+
+**测试：**
+- 单元测试专注于业务逻辑
+- 集成测试使用 MSW 进行 API 模拟
+```
+
+### 选项 B：架构后生成
+
+在新的聊天中运行工作流程：
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。
+
+### 选项 C：为现有项目生成
+
+对于现有项目，运行：
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。
+
+## 步骤 3：验证内容
+
+审查生成的文件并确保它捕获了：
+
+- 正确的技术版本
+- 实际约定（而非通用最佳实践）
+- 防止常见错误的规则
+- 框架特定的模式
+
+手动编辑以添加任何缺失内容或删除不准确之处。
+
+## 您将获得
+
+一个 `project-context.md` 文件，它：
+
+- 确保所有智能体遵循相同的约定
+- 防止在不同用户故事中做出不一致的决策
+- 为实施捕获架构决策
+- 作为项目模式和规则的参考
+
+## 提示
+
+:::tip[关注非显而易见的内容]
+记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。
+:::
+
+:::tip[保持精简]
+此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。
+:::
+
+:::tip[根据需要更新]
+当模式发生变化时手动编辑，或在重大架构更改后重新生成。
+:::
+
+:::tip[适用于所有项目类型]
+对于快速流程和完整的 BMad Method 项目同样有用。
+:::
+
+## 后续步骤
+
+- [**项目上下文说明**](../explanation/project-context.md) — 了解其工作原理
+- [**工作流程图**](../reference/workflow-map.md) — 查看哪些工作流程加载项目上下文
+
+---
+## 术语说明
+
+- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- **workflow**：工作流程。指完成特定任务的一系列步骤或过程。
+- **codebase**：代码库。指项目的所有源代码和资源的集合。
+- **implementation**：实施。指将设计或架构转化为实际代码的过程。
+- **architecture**：架构。指系统的整体结构和设计。
+- **stack**：技术栈。指项目使用的技术组合，如编程语言、框架、工具等。
+- **convention**：约定。指团队或项目中遵循的编码规范和最佳实践。
+- **singleton**：单例。一种设计模式，确保类只有一个实例。
+- **co-located**：同位置。指相关文件（如测试文件）与主文件放在同一目录中。
+- **mocking**：模拟。在测试中用模拟对象替代真实对象的行为。
+- **context**：上下文。指程序运行时的环境信息或背景信息。
+- **LLM**：大语言模型。Large Language Model 的缩写，指大型语言模型。

package/docs/zh-cn/how-to/quick-fixes.md

@@ -0,0 +1,140 @@
+---
+title: "快速修复"
+description: 如何进行快速修复和临时更改
+sidebar:
+  order: 5
+---
+
+直接使用 **DEV 智能体**进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method 或 Quick Flow。
+
+## 何时使用此方法
+
+- 原因明确且已知的 bug 修复
+- 包含在少数文件中的小型重构（重命名、提取、重组）
+- 次要功能调整或配置更改
+- 探索性工作，以了解不熟悉的代码库
+
+:::note[前置条件]
+- 已安装 BMad Method（`npx bmad-method install`）
+- AI 驱动的 IDE（Claude Code、Cursor 或类似工具）
+:::
+
+## 选择你的方法
+
+| 情况 | 智能体 | 原因 |
+| --- | --- | --- |
+| 修复特定 bug 或进行小型、范围明确的更改 | **DEV agent** | 直接进入实现，无需规划开销 |
+| 更改涉及多个文件，或希望先有书面计划 | **Quick Flow Solo Dev** | 在实现前创建 quick-spec，使智能体与你的标准保持一致 |
+
+如果不确定，请从 DEV 智能体开始。如果更改范围扩大，你始终可以升级到 Quick Flow。
+
+## 步骤
+
+### 1. 加载 DEV 智能体
+
+在 AI IDE 中启动一个**新的聊天**，并使用斜杠命令加载 DEV 智能体：
+
+```text
+/bmad-agent-bmm-dev
+```
+
+这会将智能体的角色和能力加载到会话中。如果你决定需要 Quick Flow，请在新的聊天中加载 **Quick Flow Solo Dev** 智能体：
+
+```text
+/bmad-agent-bmm-quick-flow-solo-dev
+```
+
+加载 Solo Dev 智能体后，描述你的更改并要求它创建一个 **quick-spec**。智能体会起草一个轻量级规范，捕获你想要更改的内容和方式。批准 quick-spec 后，告诉智能体开始 **Quick Flow 开发周期**——它将实现更改、运行测试并执行自我审查，所有这些都由你刚刚批准的规范指导。
+
+:::tip[新聊天]
+加载智能体时始终启动新的聊天会话。重用之前工作流的会话可能导致上下文冲突。
+:::
+
+### 2. 描述更改
+
+用通俗语言告诉智能体你需要什么。具体说明问题，如果你知道相关代码的位置，也请说明。
+
+:::note[示例提示词]
+**Bug 修复** -- "修复允许空密码的登录验证 bug。验证逻辑位于 `src/auth/validate.ts`。"
+
+**重构** -- "重构 UserService 以使用 async/await 而不是回调。"
+
+**配置更改** -- "更新 CI 流水线以在运行之间缓存 node_modules。"
+
+**依赖更新** -- "将 express 依赖升级到最新的 v5 版本并修复任何破坏性更改。"
+:::
+
+你不需要提供每个细节。智能体会读取相关的源文件，并在需要时提出澄清问题。
+
+### 3. 让智能体工作
+
+智能体将：
+
+- 读取并分析相关的源文件
+- 提出解决方案并解释其推理
+- 在受影响的文件中实现更改
+- 如果存在测试套件，则运行项目的测试套件
+
+如果你的项目有测试，智能体会在进行更改后自动运行它们，并迭代直到测试通过。对于没有测试套件的项目，请手动验证更改（运行应用、访问端点、检查输出）。
+
+### 4. 审查和验证
+
+在提交之前，审查更改内容：
+
+- 通读 diff 以确认更改符合你的意图
+- 自己运行应用程序或测试以再次检查
+- 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代
+
+满意后，使用描述修复的清晰消息提交更改。
+
+:::caution[如果出现问题]
+如果提交的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动与 DEV 智能体的新聊天以尝试不同的方法。
+:::
+
+## 学习你的代码库
+
+DEV 智能体也适用于探索不熟悉的代码。在新的聊天中加载它并提出问题：
+
+:::note[示例提示词]
+"解释此代码库中的身份验证系统是如何工作的。"
+
+"向我展示 API 层中的错误处理发生在哪里。"
+
+"`ProcessOrder` 函数的作用是什么，什么调用了它？"
+:::
+
+使用智能体了解你的项目，理解组件如何连接，并在进行更改之前探索不熟悉的区域。
+
+## 你将获得
+
+- 已应用修复或重构的修改后的源文件
+- 通过的测试（如果你的项目有测试套件）
+- 描述更改的干净提交
+
+不会生成规划产物——这就是这种方法的意义所在。
+
+## 何时升级到正式规划
+
+在以下情况下考虑使用 [Quick Flow](../explanation/quick-flow.md) 或完整的 BMad Method：
+
+- 更改影响多个系统或需要在许多文件中进行协调更新
+- 你不确定范围，需要规范来理清思路
+- 修复在工作过程中变得越来越复杂
+- 你需要为团队记录文档或架构决策
+
+---
+## 术语说明
+
+- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
+- **quick-spec**：快速规范。一种轻量级的规范文档，用于快速捕获和描述更改的内容和方式。
+- **Quick Flow**：快速流程。BMad Method 中的一种工作流程，用于快速实现小型更改。
+- **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。
+- **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。
+- **test suite**：测试套件。一组用于验证软件功能的测试用例集合。
+- **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。
+- **async/await**：异步编程语法。JavaScript/TypeScript 中用于处理异步操作的语法糖。
+- **callbacks**：回调函数。作为参数传递给其他函数并在适当时候被调用的函数。
+- **endpoint**：端点。API 中可访问的特定 URL 路径。
+- **diff**：差异。文件或代码更改前后的对比。
+- **commit**：提交。将更改保存到版本控制系统的操作。
+- **git revert HEAD**：Git 命令，用于撤销最后一次提交。

package/docs/zh-cn/how-to/shard-large-documents.md

@@ -0,0 +1,86 @@
+---
+title: "文档分片指南"
+description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文
+sidebar:
+  order: 8
+---
+
+如果需要将大型 Markdown 文件拆分为更小、组织良好的文件以更好地管理上下文，请使用 `shard-doc` 工具。
+
+:::caution[已弃用]
+不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。
+:::
+
+## 何时使用
+
+仅当你发现所选工具/模型组合无法在需要时加载和读取所有文档作为输入时，才使用此方法。
+
+## 什么是文档分片？
+
+文档分片根据二级标题（`## Heading`）将大型 Markdown 文件拆分为更小、组织良好的文件。
+
+### 架构
+
+```text
+分片前：
+_bmad-output/planning-artifacts/
+└── PRD.md（大型 50k token 文件）
+
+分片后：
+_bmad-output/planning-artifacts/
+└── prd/
+    ├── index.md                    # 带有描述的目录
+    ├── overview.md                 # 第 1 节
+    ├── user-requirements.md        # 第 2 节
+    ├── technical-requirements.md   # 第 3 节
+    └── ...                         # 其他章节
+```
+
+## 步骤
+
+### 1. 运行 Shard-Doc 工具
+
+```bash
+/bmad-shard-doc
+```
+
+### 2. 遵循交互式流程
+
+```text
+智能体：您想要分片哪个文档？
+用户：docs/PRD.md
+
+智能体：默认目标位置：docs/prd/
+       接受默认值？[y/n]
+用户：y
+
+智能体：正在分片 PRD.md...
+       ✓ 已创建 12 个章节文件
+       ✓ 已生成 index.md
+       ✓ 完成！
+```
+
+## 工作流程发现机制
+
+BMad 工作流程使用**双重发现系统**：
+
+1. **首先尝试完整文档** - 查找 `document-name.md`
+2. **检查分片版本** - 查找 `document-name/index.md`
+3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档
+
+## 工作流程支持
+
+所有 BMM 工作流程都支持这两种格式：
+
+- 完整文档
+- 分片文档
+- 自动检测
+- 对用户透明
+
+---
+## 术语说明
+
+- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。
+- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。
+- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。
+- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。