From eb72361720d81408947fccc53a6169de6f7bb365 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:06:58 +0800 Subject: [PATCH 1/7] docs(zh-cn): refine help and quick-fixes guides (#2095) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): refine help and quick-fixes guides improve zh-cn troubleshooting guidance so users can quickly choose the right support path and self-recover from common issues. align bmad-help and quick-dev usage wording with current invocation conventions and remove glossary-style appendices to keep the pages action-oriented. Feishu: N/A Made-with: Cursor * docs(zh-cn): fix tip admonition fence syntax 我把 get-answers-about-bmad 文档中的 `::::tip` 语法改为仓库统一使用的 `:::tip`。 此前四冒号写法与项目文档约定不一致，可能导致提示块渲染异常；现在与现有 Starlight 写法保持一致。 Feishu: Made-with: Cursor --------- Co-authored-by: leon --- docs/zh-cn/how-to/get-answers-about-bmad.md | 125 +++++++++----------- docs/zh-cn/how-to/quick-fixes.md | 40 +++---- 2 files changed, 72 insertions(+), 93 deletions(-) diff --git a/docs/zh-cn/how-to/get-answers-about-bmad.md b/docs/zh-cn/how-to/get-answers-about-bmad.md index ec327aef0..8d4ed0907 100644 --- a/docs/zh-cn/how-to/get-answers-about-bmad.md +++ b/docs/zh-cn/how-to/get-answers-about-bmad.md @@ -5,108 +5,109 @@ sidebar: order: 4 --- -## 从这里开始：BMad-Help +## 先从 BMad-Help 开始 -**获取关于 BMad 答案的最快方式是 `bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。 +**获取 BMad 相关答案最快的方式是 `bmad-help` 技能。** 这个智能向导可以覆盖 80% 以上的常见问题，并且你在 IDE 里随时可用。 -BMad-Help 不仅仅是一个查询工具——它： -- **检查您的项目**以查看已完成的内容 -- **理解自然语言**——用简单的英语提问 -- **根据您安装的模块变化**——显示相关选项 -- **在工作流后自动运行**——告诉您接下来该做什么 -- **推荐第一个必需任务**——无需猜测从哪里开始 +BMad-Help 不只是查表工具，它还能： +- **检查你的项目状态**，判断哪些步骤已经完成 +- **理解自然语言问题**，直接按日常表达提问即可 +- **根据已安装模块给出选项**，只展示与你当前场景相关的内容 +- **在工作流结束后自动运行**，明确告诉你下一步做什么 +- **指出第一个必做任务**，避免猜流程起点 ### 如何使用 BMad-Help -只需使用斜杠命令运行它： +在 AI 会话里直接输入： ``` bmad-help ``` -或者结合自然语言查询： +:::tip +按平台不同，你也可以使用 `/bmad-help` 或 `$bmad-help`。但大多数情况下直接输入 `bmad-help` 就能工作。 +::: + +也可以结合自然语言问题一起调用： ``` -bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ -bmad-help 我在 UX 设计方面有哪些选择？ -bmad-help 我在 PRD 工作流上卡住了 -bmad-help 向我展示到目前为止已完成的内容 +bmad-help 我有一个 SaaS 想法并且已经知道主要功能，我该从哪里开始？ +bmad-help 我在 UX 设计方面有哪些选项？ +bmad-help 我卡在 PRD 工作流了 +bmad-help 帮我看看目前完成了什么 ``` -BMad-Help 会回应： -- 针对您情况的建议 -- 第一个必需任务是什么 -- 流程的其余部分是什么样的 +BMad-Help 通常会返回： +- 针对你当前情况的建议路径 +- 第一个必做任务 +- 后续整体流程概览 ---- +## 何时使用这篇指南 -## 何时使用本指南 - -在以下情况下使用本节： -- 您想了解 BMad 的架构或内部机制 -- 您需要 BMad-Help 提供范围之外的答案 -- 您在安装前研究 BMad -- 您想直接探索源代码 +当你遇到以下情况时，可用本指南补充： +- 想理解 BMad 的架构设计或内部机制 +- 需要超出 BMad-Help 覆盖范围的答案 +- 在安装前做技术调研 +- 想直接基于源码进行追问 ## 步骤 -### 1. 选择您的来源 +### 1. 选择信息来源 -| 来源 | 最适合用于 | 示例 | -| -------------------- | ----------------------------------------- | ---------------------------- | -| **`_bmad` 文件夹** | BMad 如何工作——智能体、工作流、提示词 | "PM 智能体做什么？" | -| **完整的 GitHub 仓库** | 历史、安装程序、架构 | "v6 中有什么变化？" | -| **`llms-full.txt`** | 来自文档的快速概述 | "解释 BMad 的四个阶段" | +| 来源 | 适合回答的问题 | 示例 | +| --- | --- | --- | +| **`_bmad` 文件夹** | 智能体、工作流、提示词如何工作 | “PM 智能体具体做什么？” | +| **完整 GitHub 仓库** | 版本历史、安装器、整体架构 | “v6 主要改了什么？” | +| **`llms-full.txt`** | 文档层面的快速全景理解 | “解释 BMad 的四个阶段” | -`_bmad` 文件夹在您安装 BMad 时创建。如果您还没有它，请改为克隆仓库。 +安装 BMad 后会生成 `_bmad` 文件夹；如果你还没有安装，可先克隆仓库。 -### 2. 将您的 AI 指向来源 +### 2. 让 AI 读取来源 -**如果您的 AI 可以读取文件（Claude Code、Cursor 等）：** +**如果你的 AI 可以直接读文件（如 Claude Code、Cursor）：** -- **已安装 BMad：** 指向 `_bmad` 文件夹并直接提问 -- **想要更深入的上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD) +- **已安装 BMad：** 直接让它读取 `_bmad` 并提问 +- **想看更深上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD) -**如果您使用 ChatGPT 或 Claude.ai：** +**如果你使用 ChatGPT 或 Claude.ai：** -将 `llms-full.txt` 获取到您的会话中： +把 `llms-full.txt` 加入会话上下文： ```text https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt ``` -### 3. 提出您的问题 +### 3. 直接提问 :::note[示例] -**问：** "告诉我用 BMad 构建某物的最快方式" +**问：** “用 BMad 做一个需求到实现的最短路径是什么？” -**答：** 使用快速流程：运行 `bmad-quick-dev` — 它在单个工作流中澄清意图、规划、实现、审查和呈现结果，跳过完整的规划阶段。 +**答：** 使用 Quick Flow，运行 `bmad-quick-dev`。它会在一个工作流里完成意图澄清、计划、实现、审查与结果呈现，跳过完整规划阶段。 ::: -## 您将获得什么 +## 你将获得什么 -关于 BMad 的直接答案——智能体如何工作、工作流做什么、为什么事物以这种方式构建——无需等待其他人回应。 +你可以快速拿到直接、可执行的答案：智能体怎么工作、工作流做什么、为什么这样设计，而不需要等待外部回复。 ## 提示 -- **验证令人惊讶的答案**——LLM 偶尔会出错。检查源文件或在 Discord 上询问。 -- **具体化**——"PRD 工作流的第 3 步做什么？"比"PRD 如何工作？"更好 +- **对“意外答案”做二次核验**：LLM 偶尔会答偏，建议回看源码或到 Discord 确认 +- **问题越具体越好**：例如“PRD 工作流第 3 步在做什么？”比“PRD 怎么用？”更高效 -## 仍然卡住了？ +## 仍然卡住？ -尝试了 LLM 方法但仍需要帮助？您现在有一个更好的问题可以问。 +如果你已经试过 LLM 方案但还需要协助，现在你通常已经能提出一个更清晰的问题。 -| 频道 | 用于 | -| ------------------------- | ------------------------------------------- | -| `#bmad-method-help` | 快速问题（实时聊天） | -| `help-requests` 论坛 | 详细问题（可搜索、持久） | -| `#suggestions-feedback` | 想法和功能请求 | -| `#report-bugs-and-issues` | 错误报告 | +| 频道 | 适用场景 | +| --- | --- | +| `#bmad-method-help` | 快速问题（实时聊天） | +| `help-requests` forum | 复杂问题（可检索、可沉淀） | +| `#suggestions-feedback` | 建议与功能诉求 | +| `#report-bugs-and-issues` | Bug 报告 | -**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) - -**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于明确的错误） +**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) +**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于可复现问题） *你！* *卡住* @@ -132,13 +133,3 @@ https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt *今天？* *—Claude* - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **LLM**：大语言模型。基于深度学习的自然语言处理模型，能够理解和生成人类语言。 -- **SaaS**：软件即服务。一种通过互联网提供软件应用的交付模式。 -- **UX**：用户体验。用户在使用产品或服务过程中建立的主观感受和评价。 -- **PRD**：产品需求文档。详细描述产品功能、特性和需求的正式文档。 -- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 diff --git a/docs/zh-cn/how-to/quick-fixes.md b/docs/zh-cn/how-to/quick-fixes.md index 4451627df..9c6c631e2 100644 --- a/docs/zh-cn/how-to/quick-fixes.md +++ b/docs/zh-cn/how-to/quick-fixes.md @@ -5,9 +5,9 @@ sidebar: order: 5 --- -使用 **Quick Dev** 进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method。 +对于 bug 修复、重构或小范围改动，使用 **Quick Dev** 即可，不必走完整的 BMad Method。 -## 何时使用此方法 +## 何时使用本指南 - 原因明确且已知的 bug 修复 - 包含在少数文件中的小型重构（重命名、提取、重组） @@ -21,13 +21,13 @@ sidebar: ## 步骤 -### 1. 启动新的聊天 +### 1. 开启新会话 -在 AI IDE 中打开一个**新的聊天会话**。重用之前工作流的会话可能导致上下文冲突。 +在 AI IDE 中开启一个**全新的聊天会话**。复用之前工作流留下的会话，容易引发上下文冲突。 ### 2. 提供你的意图 -Quick Dev 接受自由形式的意图——可以在调用之前、同时或之后提供。示例： +Quick Dev 支持自由表达意图，你可以在调用前、调用时或调用后补充说明。示例： ```text run quick-dev — 修复允许空密码的登录验证 bug。 @@ -53,20 +53,20 @@ run quick-dev 重构 UserService 以使用 async/await 而不是回调。 ``` -纯文本、文件路径、GitHub issue URL、bug 跟踪器链接——任何 LLM 能解析为具体意图的内容都可以。 +纯文本、文件路径、GitHub issue 链接、缺陷跟踪地址都可以，只要 LLM 能解析成明确意图。 ### 3. 回答问题并批准 -Quick Dev 可能会提出澄清问题，或在实现之前呈现简短的规范供你批准。回答它的问题，并在你对计划满意时批准。 +Quick Dev 可能会先问澄清问题，或在实现前给出一份简短方案供你确认。回答问题后，在你认可方案时再批准继续。 ### 4. 审查和推送 -Quick Dev 实现更改、审查自己的工作、修复问题，并在本地提交。完成后，它会在编辑器中打开受影响的文件。 +Quick Dev 会实现改动、执行自检并修补问题，然后在本地提交。完成后，它会在编辑器中打开受影响文件。 -- 浏览 diff 以确认更改符合你的意图 -- 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代 +- 快速浏览 diff，确认改动符合你的意图 +- 如果有偏差，直接告诉智能体要改什么，它可以在同一会话里继续迭代 -满意后，推送提交。Quick Dev 会提供推送和创建 PR 的选项。 +确认无误后推送提交。Quick Dev 会提供推送和创建 PR 的选项。 :::caution[如果出现问题] 如果推送的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动新聊天并再次运行 Quick Dev 以尝试不同的方法。 @@ -80,9 +80,9 @@ Quick Dev 实现更改、审查自己的工作、修复问题，并在本地提 ## 延迟工作 -Quick Dev 保持每次运行聚焦于单一目标。如果你的请求包含多个独立目标，或者审查发现了与你的更改无关的已有问题，Quick Dev 会将它们延迟到一个文件中（实现产物目录中的 `deferred-work.md`），而不是试图一次解决所有问题。 +Quick Dev 每次只聚焦一个目标。如果你的请求包含多个独立目标，或审查过程中发现与你本次改动无关的存量问题，Quick Dev 会把它们记录到 `deferred-work.md`（位于实现产物目录），而不是一次性全都处理。 -运行后检查此文件——它是你的待办事项积压。每个延迟项目都可以稍后输入到新的 Quick Dev 运行中。 +每次运行后都建议看一下这个文件，它就是你的后续待办清单。你可以把其中任何一项在后续新的 Quick Dev 会话里单独处理。 ## 何时升级到正式规划 @@ -92,16 +92,4 @@ Quick Dev 保持每次运行聚焦于单一目标。如果你的请求包含多 - 你不确定范围，需要先进行需求发现 - 你需要为团队记录文档或架构决策 -参见 [Quick Dev](../explanation/quick-dev.md) 了解 Quick Dev 如何融入 BMad Method。 - ---- -## 术语说明 - -- **Quick Dev**：快速开发。BMad Method 中的快速工作流，用于小型更改的完整实现周期。 -- **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。 -- **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。 -- **test suite**：测试套件。一组用于验证软件功能的测试用例集合。 -- **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。 -- **diff**：差异。文件或代码更改前后的对比。 -- **commit**：提交。将更改保存到版本控制系统的操作。 -- **conventional commit**：约定式提交。遵循标准格式的提交消息。 +参见 [Quick Dev](../explanation/quick-dev.md) 了解 Quick Dev 在 BMad Method 中的位置与边界。 From 347f459d5db9d690993db06c8d78580793236766 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:08:35 +0800 Subject: [PATCH 2/7] docs(zh-cn): refine entry copy and navigation (#2092) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): refine entry copy and navigation 我统一中文入口层文案语气，减少机翻腔并保持与英文语义一致， 让读者从 README、首页到 404 与界面文案都保持同一术语和导航预期。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align non-interactive install link label 我把 README_CN 中“查看完整安装选项”改为“查看非交互式安装选项”。 此前文案范围大于目标页面内容，容易让读者误以为是安装总览；现在文案与链接目标保持一致，减少理解偏差。 Feishu: Made-with: Cursor --------- Co-authored-by: leon --- README_CN.md | 59 +++++++++++------------------ docs/zh-cn/404.md | 4 +- docs/zh-cn/index.md | 53 +++++++++++--------------- website/src/content/i18n/zh-CN.json | 20 +++++----- 4 files changed, 57 insertions(+), 79 deletions(-) diff --git a/README_CN.md b/README_CN.md index 0d7af6ede..a939a0c7b 100644 --- a/README_CN.md +++ b/README_CN.md @@ -5,20 +5,20 @@ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) -**突破性敏捷 AI 驱动开发方法** — 简称 “BMAD 方法论” ，BMAD方法论是由多个模块生态构成的AI驱动敏捷开发模块系统，这是最佳且最全面的敏捷 AI 驱动开发框架，具备真正的规模自适应人工智能，可适应快速开发，适应企业规模化开发。 +**筑梦架构（Build More Architect Dreams）** —— 简称 “BMAD 方法”，面向 BMad 模块生态的 AI 驱动敏捷开发方法。它会随项目复杂度调整工作深度，从日常 bug 修复到企业级系统建设都能适配。 -**100% 免费且开源。** 无付费。无内容门槛。无封闭 Discord。我们赋能每个人，我们将为全球现在在人工智能领域发展的普通人提供公平的学习机会。 +**100% 免费且开源。** 没有付费墙，没有封闭内容，也没有封闭 Discord。我们希望每个人都能平等获得高质量的人机协作开发方法。 ## 为什么选择 BMad 方法？ -传统 AI 工具替你思考，产生平庸的结果。BMad 智能体和辅助工作流充当专家协作者，引导你通过结构化流程，与 AI 的合作发挥最佳思维，产出最有效优秀的结果。 +传统 AI 工具常常替你思考，结果往往止于“能用”。BMad 通过专业智能体和引导式工作流，让 AI 成为协作者：流程有结构，决策有依据，产出更稳定。 -- **AI 智能帮助** — 随时使用 `bmad-help` 获取下一步指导 -- **规模-领域自适应** — 根据项目复杂度自动调整规划深度 -- **结构化工作流** — 基于分析、规划、架构和实施的敏捷最佳实践 -- **专业智能体** — 12+ 领域专家（PM、架构师、开发者、UX、Scrum Master 等） -- **派对模式** — 将多个智能体角色带入一个会话进行协作和讨论 -- **完整生命周期** — 从想法开始（头脑风暴）到部署发布 +- **AI 智能引导** —— 随时调用 `bmad-help` 获取下一步建议 +- **规模与领域自适应** —— 按项目复杂度自动调整规划深度 +- **结构化工作流** —— 覆盖分析、规划、架构、实施全流程 +- **专业角色智能体** —— 提供 PM、架构师、开发者、UX、Scrum Master 等 12+ 角色 +- **派对模式** —— 多个智能体可在同一会话协作讨论 +- **完整生命周期** —— 从头脑风暴一路到交付上线 [在 **docs.bmad-method.org** 了解更多](https://docs.bmad-method.org/zh-cn/) @@ -26,7 +26,7 @@ ## 🚀 BMad 的下一步是什么？ -**V6 已到来，我们才刚刚开始！** BMad 方法正在快速发展，包括跨平台智能体团队和子智能体集成、技能架构、BMad Builder v1、开发循环自动化等优化，以及更多正在开发中的功能。 +**V6 已经上线，而这只是开始。** BMad 仍在快速演进：跨平台智能体团队与子智能体集成、Skills 架构、BMad Builder v1、Dev Loop 自动化等能力都在持续推进。 **[📍 查看完整路线图 →](https://docs.bmad-method.org/zh-cn/roadmap/)** @@ -40,7 +40,7 @@ npx bmad-method install ``` -> 想要最新的预发布版本？使用 `npx bmad-method@next install`。相比默认安装，可能会有更多变更。 +> 想体验最新预发布版本？可使用 `npx bmad-method@next install`。它比默认版本更新更快，也可能更容易发生变化。 按照安装程序提示操作，然后在项目文件夹中打开你的 AI IDE（Claude Code、Cursor 等）。 @@ -52,19 +52,19 @@ npx bmad-method install --directory /path/to/project --modules bmm --tools claud [查看非交互式安装选项](https://docs.bmad-method.org/zh-cn/how-to/non-interactive-installation/) -> **不确定该做什么？** 运行 `bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。 +> **不确定下一步？** 直接问 `bmad-help`。它会告诉你“必做什么、可选什么”，例如：`bmad-help 我刚完成架构设计，接下来做什么？` ## 模块 -BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后的任何时间使用。 +BMad 可通过官方模块扩展到不同专业场景。你可以在安装时选择，也可以后续随时补装。 -| Module | Purpose | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)** | 包含 34+ 工作流的核心框架 | -| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)** | 创建自定义 BMad 智能体和工作流 | -| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | 基于风险的测试策略和自动化 | -| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | 游戏开发工作流（Unity、Unreal、Godot） | -| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维 | +| 模块 | 用途 | +| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)** | 核心框架，内含 34+ 工作流 | +| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)** | 创建自定义 BMad 智能体与工作流 | +| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | 基于风险的测试策略与自动化 | +| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | 游戏开发工作流（Unity/Unreal/Godot） | +| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维 | ## 文档 @@ -72,10 +72,9 @@ BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后 **快速链接：** - [入门教程](https://docs.bmad-method.org/zh-cn/tutorials/getting-started/) -- [从先前版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/) +- [从旧版本升级](https://docs.bmad-method.org/zh-cn/how-to/upgrade-to-v6/) - [测试架构师文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) - ## 社区 - [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享想法、协作 @@ -85,9 +84,9 @@ BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后 ## 支持 BMad -BMad 对每个人都是免费的 — 并且永远如此。如果你想支持开发： +BMad 对所有人免费，而且会一直免费。如果你愿意支持项目发展： -- ⭐ 请点击此页面右上角附近的项目星标图标 +- ⭐ 给仓库点个 Star - ☕ [请我喝咖啡](https://buymeacoffee.com/bmad) — 为开发提供动力 - 🏢 企业赞助 — 在 Discord 上私信 - 🎤 演讲与媒体 — 可参加会议、播客、采访（在 Discord 上联系 BM） @@ -107,15 +106,3 @@ MIT 许可证 — 详见 [LICENSE](LICENSE)。 [![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors) 请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。 - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 -- **CI/CD**：持续集成/持续部署。一种自动化软件开发实践，用于频繁集成代码更改并自动部署。 -- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 -- **PM**：产品经理。负责产品规划、需求管理和团队协调的角色。 -- **UX**：用户体验。指用户在使用产品或服务过程中的整体感受和交互体验。 -- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队遵循 Scrum 流程。 -- **PRD**：产品需求文档。详细描述产品功能、需求和规格的文档。 diff --git a/docs/zh-cn/404.md b/docs/zh-cn/404.md index bb835ceea..d8d1bb9e9 100644 --- a/docs/zh-cn/404.md +++ b/docs/zh-cn/404.md @@ -4,6 +4,6 @@ template: splash --- -您查找的页面不存在或已被移动。 +你访问的页面不存在，或已被移动。 -[返回首页](./index.md) +[返回中文首页](./index.md) diff --git a/docs/zh-cn/index.md b/docs/zh-cn/index.md index 5021d18cc..86438f2eb 100644 --- a/docs/zh-cn/index.md +++ b/docs/zh-cn/index.md @@ -1,55 +1,55 @@ --- title: 欢迎使用 BMad 方法 -description: 具备专业智能体、引导式工作流和智能规划的 AI 驱动开发框架 +description: 具备专业智能体、引导式工作流与智能规划的 AI 驱动开发框架 --- -BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development，敏捷 AI 驱动开发的突破性方法）是 BMad 方法生态系统中的一个 AI 驱动开发框架模块，帮助您完成从构思和规划到智能体实现的整个软件开发过程。它提供专业的 AI 智能体、引导式工作流和智能规划，能够根据您项目的复杂度进行调整，无论是修复错误还是构建企业平台。 +BMad 方法（**B**uild **M**ore **A**rchitect **D**reams）是 BMad 方法生态中的 AI 驱动开发框架模块，覆盖从构思、规划到智能体实施的完整软件交付流程。它提供专业智能体、引导式工作流和可随项目复杂度调整的智能规划，无论是修复 bug 还是构建企业级平台都适用。 -如果您熟悉使用 Claude、Cursor 或 GitHub Copilot 等 AI 编码助手，就可以开始使用了。 +如果你已经习惯使用 Claude、Cursor 或 GitHub Copilot 这类 AI 编码助手，现在就可以开始。 :::note[🚀 V6 已发布，我们才刚刚起步！] 技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/zh-cn/roadmap/)** ::: -## 新手入门？从教程开始 +## 新手入门？先从教程开始 理解 BMad 的最快方式是亲自尝试。 -- **[BMad 入门指南](./tutorials/getting-started.md)** — 安装并了解 BMad 的工作原理 -- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流和上下文管理的可视化概览 +- **[BMad 入门教程](./tutorials/getting-started.md)** — 安装并理解 BMad 如何工作 +- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流与上下文管理的全景视图 :::tip[只想直接上手？] -安装 BMad 并运行 `bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。 +安装 BMad 后运行 `bmad-help`，它会根据你的项目状态和已安装模块给出下一步建议。 ::: -## 如何使用本文档 +## 如何使用这些文档 -本文档根据您的目标分为四个部分： +这些文档按你的目标分成四个部分： -| 部分 | 用途 | -| ----------------- | ---------------------------------------------------------------------------------------------------------- | -| **教程** | 以学习为导向。通过分步指南引导您构建内容。如果您是新手，请从这里开始。 | -| **操作指南** | 以任务为导向。解决特定问题的实用指南。"如何自定义智能体？"等内容位于此处。 | -| **说明** | 以理解为导向。深入探讨概念和架构。当您想知道*为什么*时阅读。 | -| **参考** | 以信息为导向。智能体、工作流和配置的技术规范。 | +| 部分 | 用途 | +| --- | --- | +| **教程** | 学习导向。通过分步引导带你做成一件事。第一次使用建议从这里开始。 | +| **操作指南** | 任务导向。解决具体问题的实用文档，例如“如何自定义智能体”。 | +| **说明** | 理解导向。深入讲解概念与架构，适合回答“为什么”。 | +| **参考** | 信息导向。提供智能体、工作流和配置项的技术规格。 | -## 扩展和自定义 +## 扩展与自定义 -想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。 +想用自己的智能体、工作流或模块扩展 BMad？**[BMad Builder（英文）](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展所需的框架与工具，无论是给 BMad 添加能力，还是从零构建新模块都可以。 -## 您需要什么 +## 你需要准备什么 -BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用。热门选项包括： +BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用，常见选择包括： - **[Claude Code](https://code.claude.com)** — Anthropic 的 CLI 工具（推荐） - **[Cursor](https://cursor.sh)** — AI 优先的代码编辑器 - **[Codex CLI](https://github.com/openai/codex)** — OpenAI 的终端编码智能体 -您应该熟悉版本控制、项目结构和敏捷工作流等基本软件开发概念。无需具备 BMad 风格智能体系统的先验经验——这正是本文档的作用。 +你需要了解一些基础软件工程概念，例如版本控制、项目结构和敏捷工作流。即使没有使用过 BMad 风格智能体系统，也可以从这些文档开始上手。 ## 加入社区 -获取帮助、分享您的构建内容，或为 BMad 做出贡献： +获取帮助、分享成果，或参与贡献： - **[Discord](https://discord.gg/gk8jAdXWmj)** — 与其他 BMad 用户聊天、提问、分享想法 - **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — 源代码、问题和贡献 @@ -57,13 +57,4 @@ BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码 ## 下一步 -准备开始了吗？**[BMad 入门指南](./tutorials/getting-started.md)** 并构建您的第一个项目。 - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **AI-driven**：AI 驱动。指由人工智能技术主导或驱动的系统或方法。 -- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 -- **prompt**：提示词。指输入给 AI 模型的指令或问题，用于引导其生成特定输出。 -- **context**：上下文。指在特定场景下理解信息所需的背景信息或环境。 +准备好开始了吗？**[从 BMad 入门教程开始](./tutorials/getting-started.md)**，构建你的第一个项目。 diff --git a/website/src/content/i18n/zh-CN.json b/website/src/content/i18n/zh-CN.json index 35c916a62..a37ff1505 100644 --- a/website/src/content/i18n/zh-CN.json +++ b/website/src/content/i18n/zh-CN.json @@ -1,5 +1,5 @@ { - "skipLink.label": "跳转到内容", + "skipLink.label": "跳到正文", "search.label": "搜索", "search.ctrlKey": "Ctrl", "search.cancelLabel": "取消", @@ -9,20 +9,20 @@ "themeSelect.auto": "自动", "languageSelect.accessibleLabel": "选择语言", "menuButton.accessibleLabel": "菜单", - "sidebarNav.accessibleLabel": "主导航", - "tableOfContents.onThisPage": "本页内容", - "tableOfContents.overview": "概述", - "i18n.untranslatedContent": "此内容尚未提供中文翻译。", - "page.editLink": "编辑页面", + "sidebarNav.accessibleLabel": "侧边导航", + "tableOfContents.onThisPage": "本页目录", + "tableOfContents.overview": "概览", + "i18n.untranslatedContent": "这部分内容暂未提供中文版本。", + "page.editLink": "编辑此页", "page.lastUpdated": "最后更新：", "page.previousLink": "上一页", "page.nextLink": "下一页", - "page.draft": "此内容为草稿，不会包含在正式版本中。", - "404.text": "页面未找到。请检查 URL 或尝试使用搜索。", + "page.draft": "此内容为草稿，不会出现在正式版本中。", + "404.text": "页面未找到。请检查地址，或使用站内搜索。", "aside.note": "注意", "aside.tip": "提示", "aside.caution": "警告", "aside.danger": "危险", - "fileTree.directory": "目录", - "builtWithStarlight.label": "使用 Starlight 构建" + "fileTree.directory": "文件夹", + "builtWithStarlight.label": "由 Starlight 构建" } From ba2a5cc6a063757f724939e4e3044f602131bca4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:09:23 +0800 Subject: [PATCH 3/7] docs(zh-cn): align getting-started tutorial workflows (#2093) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): align getting-started tutorial workflows 我按英文源文更新中文入门教程中的命令、工作流和智能体调用方式， 并统一步骤叙述与导航语义，减少术语漂移和旧命令误导。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix tutorial skill names 我将入门教程阶段 1 中过时或不可用的技能名替换为当前可调用的技能名。 此前 `bmad-research` 与 `bmad-create-product-brief` 可能导致新用户执行受阻；现在改为具体研究技能与 `bmad-product-brief`，提升教程可执行性。 Feishu: Made-with: Cursor --------- Co-authored-by: leon Co-authored-by: Alex Verkhovsky --- docs/zh-cn/tutorials/getting-started.md | 97 +++++++++---------------- 1 file changed, 36 insertions(+), 61 deletions(-) diff --git a/docs/zh-cn/tutorials/getting-started.md b/docs/zh-cn/tutorials/getting-started.md index 86c68203a..468ff189e 100644 --- a/docs/zh-cn/tutorials/getting-started.md +++ b/docs/zh-cn/tutorials/getting-started.md @@ -37,13 +37,13 @@ description: 安装 BMad 并构建你的第一个项目 ### 如何使用 BMad-Help -只需在 AI IDE 中使用斜杠命令运行它： +在你的 AI IDE 中直接调用技能名： ``` bmad-help ``` -或者结合问题以获得上下文感知的指导： +也可以带着问题一起调用，获得更贴合上下文的建议： ``` bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？ @@ -70,7 +70,7 @@ BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。 | ---- | -------------- | -------------------------------------------------- | | 1 | 分析 | 头脑风暴、研究、产品简报 *（可选）* | | 2 | 规划 | 创建需求（PRD 或技术规范） | -| 3 | 解决方案设计 | 设计架构 *（仅限 BMad Method/Enterprise only）* | +| 3 | 解决方案设计 | 设计架构 *（仅适用于 BMad Method/Enterprise）* | | 4 | 实现 | 逐个史诗、逐个故事地构建 | **[打开工作流地图](../reference/workflow-map.md)** 以探索阶段、工作流和上下文管理。 @@ -95,6 +95,8 @@ BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。 npx bmad-method install ``` +如果你想使用最新预发布版本（而不是默认发布通道），可以改用 `npx bmad-method@next install`。 + 当提示选择模块时，选择 **BMad Method**。 安装程序会创建两个文件夹： @@ -112,7 +114,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 ::: :::note[如何加载智能体和运行工作流] -每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `bmad-agent-bmm-pm`）。 +每个工作流都可以通过技能名直接调用（例如 `bmad-create-prd`）。你的 AI IDE 会识别 `bmad-*` 技能并执行，无需额外单独加载智能体。你也可以直接调用智能体技能进行通用对话（例如 PM 智能体用 `bmad-pm`）。 ::: :::caution[新对话] @@ -126,35 +128,35 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 :::tip[项目上下文（可选）] 在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。 -在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。 +在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。 ::: ### 阶段 1：分析（可选） 此阶段中的所有工作流都是可选的： - **头脑风暴**（`bmad-brainstorming`） — 引导式构思 -- **研究**（`bmad-bmm-research`） — 市场和技术研究 -- **创建产品简报**（`bmad-bmm-create-product-brief`） — 推荐的基础文档 +- **研究**（`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`） — 市场、领域和技术研究 +- **创建产品简报**（`bmad-product-brief`） — 推荐的基础文档 ### 阶段 2：规划（必需） **对于 BMad Method 和 Enterprise 路径：** -1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`） -2. 运行 `prd` 工作流（`bmad-bmm-create-prd`） +1. 在新对话中调用 **PM 智能体**（`bmad-pm`） +2. 运行 `bmad-create-prd` 工作流（`bmad-create-prd`） 3. 输出：`PRD.md` **对于 Quick Flow 路径：** -- 运行 `bmad-bmm-quick-dev` — 它在单个工作流中处理规划和实现，跳转到实现 +- 运行 `bmad-quick-dev` —— 它会在一个工作流里同时处理规划与实现，可直接进入实现阶段 :::note[UX 设计（可选）] -如果你的项目有用户界面，在创建 PRD 后加载 **UX-Designer 智能体**（`bmad-agent-bmm-ux-designer`）并运行 UX 设计工作流（`bmad-bmm-create-ux-design`）。 +如果你的项目有用户界面，在创建 PRD 后调用 **UX-Designer 智能体**（`bmad-ux-designer`），然后运行 UX 设计工作流（`bmad-create-ux-design`）。 ::: ### 阶段 3：解决方案设计（BMad Method/Enterprise） **创建架构** -1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`） -2. 运行 `create-architecture`（`bmad-bmm-create-architecture`） +1. 在新对话中调用 **Architect 智能体**（`bmad-architect`） +2. 运行 `bmad-create-architecture`（`bmad-create-architecture`） 3. 输出：包含技术决策的架构文档 **创建史诗和故事** @@ -163,13 +165,13 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。 ::: -1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`） -2. 运行 `create-epics-and-stories`（`bmad-bmm-create-epics-and-stories`） +1. 在新对话中调用 **PM 智能体**（`bmad-pm`） +2. 运行 `bmad-create-epics-and-stories`（`bmad-create-epics-and-stories`） 3. 工作流使用 PRD 和架构来创建技术信息丰富的故事 **实现就绪检查** *（强烈推荐）* -1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`） -2. 运行 `check-implementation-readiness`（`bmad-bmm-check-implementation-readiness`） +1. 在新对话中调用 **Architect 智能体**（`bmad-architect`） +2. 运行 `bmad-check-implementation-readiness`（`bmad-check-implementation-readiness`） 3. 验证所有规划文档之间的一致性 ## 步骤 2：构建你的项目 @@ -178,7 +180,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 ### 初始化冲刺规划 -加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `sprint-planning`（`bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 +调用 **SM 智能体**（`bmad-sm`）并运行 `bmad-sprint-planning`（`bmad-sprint-planning`）。这会创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 ### 构建周期 @@ -186,11 +188,11 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 | 步骤 | 智能体 | 工作流 | 命令 | 目的 | | ---- | ------ | ------------ | ----------------------- | ------------------------------- | -| 1 | SM | `create-story` | `bmad-bmm-create-story` | 从史诗创建故事文件 | -| 2 | DEV | `dev-story` | `bmad-bmm-dev-story` | 实现故事 | -| 3 | DEV | `code-review` | `bmad-bmm-code-review` | 质量验证 *（推荐）* | +| 1 | SM | `bmad-create-story` | `bmad-create-story` | 从史诗创建故事文件 | +| 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | 实现故事 | +| 3 | DEV | `bmad-code-review` | `bmad-code-review` | 质量验证 *（推荐）* | -完成史诗中的所有故事后，加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `retrospective`（`bmad-bmm-retrospective`）。 +完成史诗中的所有故事后，调用 **SM 智能体**（`bmad-sm`）并运行 `bmad-retrospective`（`bmad-retrospective`）。 ## 你已完成的工作 @@ -221,16 +223,16 @@ your-project/ | 工作流 | 命令 | 智能体 | 目的 | | ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- | -| **`help`** ⭐ | `bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** | -| `prd` | `bmad-bmm-create-prd` | PM | 创建产品需求文档 | -| `create-architecture` | `bmad-bmm-create-architecture` | Architect | 创建架构文档 | -| `generate-project-context` | `bmad-bmm-generate-project-context` | Analyst | 创建项目上下文文件 | -| `create-epics-and-stories` | `bmad-bmm-create-epics-and-stories` | PM | 将 PRD 分解为史诗 | -| `check-implementation-readiness` | `bmad-bmm-check-implementation-readiness` | Architect | 验证规划一致性 | -| `sprint-planning` | `bmad-bmm-sprint-planning` | SM | 初始化冲刺跟踪 | -| `create-story` | `bmad-bmm-create-story` | SM | 创建故事文件 | -| `dev-story` | `bmad-bmm-dev-story` | DEV | 实现故事 | -| `code-review` | `bmad-bmm-code-review` | DEV | 审查已实现的代码 | +| **`bmad-help`** ⭐ | `bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** | +| `bmad-create-prd` | `bmad-create-prd` | PM | 创建产品需求文档 | +| `bmad-create-architecture` | `bmad-create-architecture` | Architect | 创建架构文档 | +| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | 创建项目上下文文件 | +| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | 将 PRD 分解为史诗 | +| `bmad-check-implementation-readiness` | `bmad-check-implementation-readiness` | Architect | 验证规划一致性 | +| `bmad-sprint-planning` | `bmad-sprint-planning` | SM | 初始化冲刺跟踪 | +| `bmad-create-story` | `bmad-create-story` | SM | 创建故事文件 | +| `bmad-dev-story` | `bmad-dev-story` | DEV | 实现故事 | +| `bmad-code-review` | `bmad-code-review` | DEV | 审查已实现的代码 | ## 常见问题 @@ -238,10 +240,10 @@ your-project/ 仅对于 BMad Method 和 Enterprise 路径。Quick Flow 从技术规范跳转到实现。 **我可以稍后更改我的计划吗？** -可以。SM 智能体有一个 `correct-course` 工作流（`bmad-bmm-correct-course`）用于处理范围变更。 +可以。SM 智能体提供 `bmad-correct-course` 工作流（`bmad-correct-course`）来处理范围变化。 **如果我想先进行头脑风暴怎么办？** -在开始 PRD 之前，加载 Analyst 智能体（`bmad-agent-bmm-analyst`）并运行 `brainstorming`（`bmad-brainstorming`）。 +在开始 PRD 之前，调用 Analyst 智能体（`bmad-analyst`）并运行 `bmad-brainstorming`（`bmad-brainstorming`）。 **我需要遵循严格的顺序吗？** 不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。 @@ -271,30 +273,3 @@ BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉 ::: 准备好开始了吗？安装 BMad，运行 `bmad-help`，让你的智能向导为你引路。 - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **epic**：史诗。软件开发中用于组织和管理大型功能或用户需求的高级工作项。 -- **story**：故事。敏捷开发中的用户故事，描述用户需求的小型工作项。 -- **PRD**：产品需求文档（Product Requirements Document）。详细描述产品功能、需求和目标的文档。 -- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定目标。 -- **sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 -- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件工具。 -- **artifact**：工件。软件开发过程中产生的文档、代码或其他可交付成果。 -- **retrospective**：回顾。敏捷开发中的会议，用于反思和改进团队工作流程。 -- **tech-spec**：技术规范（Technical Specification）。描述系统技术实现细节的文档。 -- **UX**：用户体验（User Experience）。用户在使用产品过程中的整体感受和交互体验。 -- **PM**：产品经理（Product Manager）。负责产品规划、需求管理和团队协调的角色。 -- **SM**：Scrum Master。敏捷开发中的角色，负责促进 Scrum 流程和团队协作。 -- **DEV**：开发者（Developer）。负责编写代码和实现功能的角色。 -- **Architect**：架构师。负责系统架构设计和技术决策的角色。 -- **Analyst**：分析师。负责需求分析、市场研究等工作的角色。 -- **npx**：Node Package eXecute。Node.js 包执行器，用于运行 npm 包而无需安装。 -- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时环境。 -- **Git**：分布式版本控制系统。 -- **SaaS**：软件即服务（Software as a Service）。通过互联网提供软件服务的模式。 -- **DevOps**：开发运维（Development and Operations）。强调开发和运维协作的实践和方法。 -- **multi-tenant**：多租户。一种软件架构，允许单个实例为多个客户（租户）提供服务。 -- **compliance**：合规性。遵守法律、法规和行业标准的要求。 From 7e97b7e7f3d35e6f21ebe764b8f2accbad6b84a2 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 22 Mar 2026 10:22:29 -0600 Subject: [PATCH 4/7] fix(docs): correct skill names in getting-started tutorials (#2103) Agent skills referenced with shortened names (bmad-pm, bmad-architect, etc.) that don't match installed skill names. Fixed to use actual names (bmad-agent-pm, bmad-agent-architect, etc.) across EN, ZH-CN, and FR. Also fixed bmad-research to three specific research skills (EN, FR) and bmad-product-brief to bmad-create-product-brief (ZH-CN). Co-authored-by: Claude Opus 4.6 (1M context) --- docs/fr/tutorials/getting-started.md | 4 ++-- docs/tutorials/getting-started.md | 20 ++++++++++---------- docs/zh-cn/tutorials/getting-started.md | 20 ++++++++++---------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/fr/tutorials/getting-started.md b/docs/fr/tutorials/getting-started.md index 056d62029..c0502f23a 100644 --- a/docs/fr/tutorials/getting-started.md +++ b/docs/fr/tutorials/getting-started.md @@ -135,7 +135,7 @@ Créez-le manuellement dans `_bmad-output/project-context.md` ou générez-le ap Tous les workflows de cette phase sont optionnels : - **brainstorming** (`bmad-brainstorming`) — Idéation guidée -- **research** (`bmad-research`) — Recherche marché et technique +- **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Recherche marché, domaine et technique - **create-product-brief** (`bmad-create-product-brief`) — Document de base recommandé ### Phase 2 : Planification (Requis) @@ -239,7 +239,7 @@ Uniquement pour les voies méthode BMad et Enterprise. Quick Dev passe directeme Oui. Utilisez `bmad-correct-course` pour gérer les changements de périmètre. **Et si je veux d'abord faire du brainstorming ?** -Invoquez l'agent Analyst (`bmad-analyst`) et exécutez `bmad-brainstorming` (`bmad-brainstorming`) avant de commencer votre PRD. +Invoquez l'agent Analyst (`bmad-agent-analyst`) et exécutez `bmad-brainstorming` (`bmad-brainstorming`) avant de commencer votre PRD. **Dois-je suivre un ordre strict ?** Pas strictement. Une fois que vous maîtrisez le flux, vous pouvez exécuter les workflows directement en utilisant la référence rapide ci-dessus. diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index 714d13360..ee68eb6ce 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -114,7 +114,7 @@ BMad-Help will detect what you've completed and recommend exactly what to do nex ::: :::note[How to Load Agents and Run Workflows] -Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-pm` for the PM agent). +Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent). ::: :::caution[Fresh Chats] @@ -135,13 +135,13 @@ Create it manually at `_bmad-output/project-context.md` or generate it after arc All workflows in this phase are optional: - **brainstorming** (`bmad-brainstorming`) — Guided ideation -- **research** (`bmad-research`) — Market and technical research +- **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) — Market, domain, and technical research - **create-product-brief** (`bmad-create-product-brief`) — Recommended foundation document ### Phase 2: Planning (Required) **For BMad Method and Enterprise tracks:** -1. Invoke the **PM agent** (`bmad-pm`) in a new chat +1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat 2. Run the `bmad-create-prd` workflow (`bmad-create-prd`) 3. Output: `PRD.md` @@ -149,13 +149,13 @@ All workflows in this phase are optional: - Run `bmad-quick-dev` — it handles planning and implementation in a single workflow, skip to implementation :::note[UX Design (Optional)] -If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD. +If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD. ::: ### Phase 3: Solutioning (BMad Method/Enterprise) **Create Architecture** -1. Invoke the **Architect agent** (`bmad-architect`) in a new chat +1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat 2. Run `bmad-create-architecture` (`bmad-create-architecture`) 3. Output: Architecture document with technical decisions @@ -165,12 +165,12 @@ If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ux Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down. ::: -1. Invoke the **PM agent** (`bmad-pm`) in a new chat +1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat 2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`) 3. The workflow uses both PRD and Architecture to create technically-informed stories **Implementation Readiness Check** *(Highly Recommended)* -1. Invoke the **Architect agent** (`bmad-architect`) in a new chat +1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat 2. Run `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`) 3. Validates cohesion across all planning documents @@ -180,7 +180,7 @@ Once planning is complete, move to implementation. **Each workflow should run in ### Initialize Sprint Planning -Invoke the **SM agent** (`bmad-sm`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories. +Invoke the **SM agent** (`bmad-agent-sm`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories. ### The Build Cycle @@ -192,7 +192,7 @@ For each story, repeat this cycle with fresh chats: | 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | Implement the story | | 3 | DEV | `bmad-code-review` | `bmad-code-review` | Quality validation *(recommended)* | -After completing all stories in an epic, invoke the **SM agent** (`bmad-sm`) and run `bmad-retrospective` (`bmad-retrospective`). +After completing all stories in an epic, invoke the **SM agent** (`bmad-agent-sm`) and run `bmad-retrospective` (`bmad-retrospective`). ## What You've Accomplished @@ -243,7 +243,7 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to i Yes. The SM agent has a `bmad-correct-course` workflow (`bmad-correct-course`) for handling scope changes. **What if I want to brainstorm first?** -Invoke the Analyst agent (`bmad-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD. +Invoke the Analyst agent (`bmad-agent-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD. **Do I need to follow a strict order?** Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above. diff --git a/docs/zh-cn/tutorials/getting-started.md b/docs/zh-cn/tutorials/getting-started.md index 468ff189e..753a88a8f 100644 --- a/docs/zh-cn/tutorials/getting-started.md +++ b/docs/zh-cn/tutorials/getting-started.md @@ -114,7 +114,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 ::: :::note[如何加载智能体和运行工作流] -每个工作流都可以通过技能名直接调用（例如 `bmad-create-prd`）。你的 AI IDE 会识别 `bmad-*` 技能并执行，无需额外单独加载智能体。你也可以直接调用智能体技能进行通用对话（例如 PM 智能体用 `bmad-pm`）。 +每个工作流都可以通过技能名直接调用（例如 `bmad-create-prd`）。你的 AI IDE 会识别 `bmad-*` 技能并执行，无需额外单独加载智能体。你也可以直接调用智能体技能进行通用对话（例如 PM 智能体用 `bmad-agent-pm`）。 ::: :::caution[新对话] @@ -136,12 +136,12 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 此阶段中的所有工作流都是可选的： - **头脑风暴**（`bmad-brainstorming`） — 引导式构思 - **研究**（`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`） — 市场、领域和技术研究 -- **创建产品简报**（`bmad-product-brief`） — 推荐的基础文档 +- **创建产品简报**（`bmad-create-product-brief`） — 推荐的基础文档 ### 阶段 2：规划（必需） **对于 BMad Method 和 Enterprise 路径：** -1. 在新对话中调用 **PM 智能体**（`bmad-pm`） +1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`） 2. 运行 `bmad-create-prd` 工作流（`bmad-create-prd`） 3. 输出：`PRD.md` @@ -149,13 +149,13 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 - 运行 `bmad-quick-dev` —— 它会在一个工作流里同时处理规划与实现，可直接进入实现阶段 :::note[UX 设计（可选）] -如果你的项目有用户界面，在创建 PRD 后调用 **UX-Designer 智能体**（`bmad-ux-designer`），然后运行 UX 设计工作流（`bmad-create-ux-design`）。 +如果你的项目有用户界面，在创建 PRD 后调用 **UX-Designer 智能体**（`bmad-agent-ux-designer`），然后运行 UX 设计工作流（`bmad-create-ux-design`）。 ::: ### 阶段 3：解决方案设计（BMad Method/Enterprise） **创建架构** -1. 在新对话中调用 **Architect 智能体**（`bmad-architect`） +1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`） 2. 运行 `bmad-create-architecture`（`bmad-create-architecture`） 3. 输出：包含技术决策的架构文档 @@ -165,12 +165,12 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。 ::: -1. 在新对话中调用 **PM 智能体**（`bmad-pm`） +1. 在新对话中调用 **PM 智能体**（`bmad-agent-pm`） 2. 运行 `bmad-create-epics-and-stories`（`bmad-create-epics-and-stories`） 3. 工作流使用 PRD 和架构来创建技术信息丰富的故事 **实现就绪检查** *（强烈推荐）* -1. 在新对话中调用 **Architect 智能体**（`bmad-architect`） +1. 在新对话中调用 **Architect 智能体**（`bmad-agent-architect`） 2. 运行 `bmad-check-implementation-readiness`（`bmad-check-implementation-readiness`） 3. 验证所有规划文档之间的一致性 @@ -180,7 +180,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 ### 初始化冲刺规划 -调用 **SM 智能体**（`bmad-sm`）并运行 `bmad-sprint-planning`（`bmad-sprint-planning`）。这会创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 +调用 **SM 智能体**（`bmad-agent-sm`）并运行 `bmad-sprint-planning`（`bmad-sprint-planning`）。这会创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 ### 构建周期 @@ -192,7 +192,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么 | 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | 实现故事 | | 3 | DEV | `bmad-code-review` | `bmad-code-review` | 质量验证 *（推荐）* | -完成史诗中的所有故事后，调用 **SM 智能体**（`bmad-sm`）并运行 `bmad-retrospective`（`bmad-retrospective`）。 +完成史诗中的所有故事后，调用 **SM 智能体**（`bmad-agent-sm`）并运行 `bmad-retrospective`（`bmad-retrospective`）。 ## 你已完成的工作 @@ -243,7 +243,7 @@ your-project/ 可以。SM 智能体提供 `bmad-correct-course` 工作流（`bmad-correct-course`）来处理范围变化。 **如果我想先进行头脑风暴怎么办？** -在开始 PRD 之前，调用 Analyst 智能体（`bmad-analyst`）并运行 `bmad-brainstorming`（`bmad-brainstorming`）。 +在开始 PRD 之前，调用 Analyst 智能体（`bmad-agent-analyst`）并运行 `bmad-brainstorming`（`bmad-brainstorming`）。 **我需要遵循严格的顺序吗？** 不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。 From ad2eb0e127efd48daa55f432c9d89133ea347b01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:24:31 +0800 Subject: [PATCH 5/7] docs(zh-cn): refine install and non-interactive guides (#2094) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): refine install and non-interactive guides 我统一中文安装文档中的术语和参数说明，补齐预发布安装与 skills 启用提示， 并保持交互式与非交互式安装路径和英文源文一致，减少安装场景下的理解偏差。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align install guide review wording 我在安装指南中补充目录结构示例说明，明确工具相关目录会随所选平台变化，避免读者误以为 .claude/.cursor 一定同时存在。 我同时统一非交互式安装文档里残留的“标志”表述为“参数”，让术语在全文保持一致并降低理解成本。 Feishu: Made-with: Cursor --------- Co-authored-by: leon --- docs/zh-cn/how-to/install-bmad.md | 47 ++++++++++++------- .../how-to/non-interactive-installation.md | 39 ++++++--------- 2 files changed, 46 insertions(+), 40 deletions(-) diff --git a/docs/zh-cn/how-to/install-bmad.md b/docs/zh-cn/how-to/install-bmad.md index e0309d2b9..e9fc1af9a 100644 --- a/docs/zh-cn/how-to/install-bmad.md +++ b/docs/zh-cn/how-to/install-bmad.md @@ -5,9 +5,9 @@ sidebar: order: 1 --- -使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。 +使用 `npx bmad-method install` 在项目中安装 BMad，并按需选择模块和 AI 工具。 -如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。 +如果你需要在命令行里一次性传入全部安装参数（例如 CI/CD 场景），请阅读[非交互式安装指南](./non-interactive-installation.md)。 ## 何时使用 @@ -29,7 +29,16 @@ sidebar: npx bmad-method install ``` -:::tip[最新版本] +:::tip[想要最新预发布版本？] +使用 `next` 发布标签： +```bash +npx bmad-method@next install +``` + +这会更早拿到新改动，但相比默认安装通道，出现变动的概率也更高。 +::: + +:::tip[前沿版本] 要从主分支安装最新版本（可能不稳定）： ```bash npx github:bmad-code-org/BMAD-METHOD install @@ -51,7 +60,11 @@ npx github:bmad-code-org/BMAD-METHOD install - Cursor - 其他 -每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。 +每种工具都有自己的 skills 集成方式。安装程序会生成用于激活工作流和智能体的轻量提示文件，并放到该工具约定的位置。 + +:::note[启用 Skills] +某些平台需要你在设置中手动启用 skills 才会显示。如果你已经安装 BMad 但看不到 skills，请检查平台设置，或直接询问你的 AI 助手如何启用 skills。 +::: ### 4. 选择模块 @@ -63,16 +76,25 @@ npx github:bmad-code-org/BMAD-METHOD install ## 你将获得 +以下目录结构仅作示例。工具相关目录会随你选择的平台变化（例如可能是 +`.claude/skills`、`.cursor/skills` 或 `.kiro/skills`），并不一定会同时出现。 + ```text your-project/ ├── _bmad/ │ ├── bmm/ # 你选择的模块 -│ │ └── config.yaml # 模块设置（如果你需要更改它们） -│ ├── core/ # 必需的核心模块 +│ │ └── config.yaml # 模块设置（后续如需可修改） +│ ├── core/ # 必需核心模块 │ └── ... -├── _bmad-output/ # 生成的工件 -├── .claude/ # Claude Code 命令（如果使用 Claude Code） -└── .kiro/ # Kiro 引导文件（如果使用 Kiro） +├── _bmad-output/ # 生成产物 +├── .claude/ # Claude Code skills（如使用 Claude Code） +│ └── skills/ +│ ├── bmad-help/ +│ ├── bmad-persona/ +│ └── ... +└── .cursor/ # Cursor skills（如使用 Cursor） + └── skills/ + └── ... ``` ## 验证安装 @@ -96,10 +118,3 @@ bmad-help 对于 SaaS 项目我有哪些选项？ **安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。 ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 -- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。 -- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。 diff --git a/docs/zh-cn/how-to/non-interactive-installation.md b/docs/zh-cn/how-to/non-interactive-installation.md index 930bbe639..fdcfbc9fd 100644 --- a/docs/zh-cn/how-to/non-interactive-installation.md +++ b/docs/zh-cn/how-to/non-interactive-installation.md @@ -1,11 +1,11 @@ --- title: "非交互式安装" -description: 使用命令行标志安装 BMad，适用于 CI/CD 流水线和自动化部署 +description: 使用命令行参数安装 BMad，适用于 CI/CD 流水线和自动化部署 sidebar: order: 2 --- -使用命令行标志以非交互方式安装 BMad。这适用于： +使用命令行参数（flags）以非交互方式安装 BMad。适用于以下场景： ## 使用场景 @@ -18,11 +18,11 @@ sidebar: 需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。 ::: -## 可用标志 +## 可用参数（Flags） ### 安装选项 -| 标志 | 描述 | 示例 | +| 参数 | 描述 | 示例 | |------|-------------|---------| | `--directory ` | 安装目录 | `--directory ~/projects/myapp` | | `--modules ` | 逗号分隔的模块 ID | `--modules bmm,bmb` | @@ -32,7 +32,7 @@ sidebar: ### 核心配置 -| 标志 | 描述 | 默认值 | +| 参数 | 描述 | 默认值 | |------|-------------|---------| | `--user-name ` | 智能体使用的名称 | 系统用户名 | | `--communication-language ` | 智能体通信语言 | 英语 | @@ -41,14 +41,14 @@ sidebar: ### 其他选项 -| 标志 | 描述 | +| 参数 | 描述 | |------|-------------| | `-y, --yes` | 接受所有默认值并跳过提示 | | `-d, --debug` | 启用清单生成的调试输出 | ## 模块 ID -`--modules` 标志可用的模块 ID： +`--modules` 参数可用的模块 ID： - `bmm` — BMad Method Master - `bmb` — BMad Builder @@ -57,7 +57,7 @@ sidebar: ## 工具/IDE ID -`--tools` 标志可用的工具 ID： +`--tools` 参数可用的工具 ID： **推荐：** `claude-code`、`cursor` @@ -67,8 +67,8 @@ sidebar: | 模式 | 描述 | 示例 | |------|-------------|---------| -| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` | -| 半交互式 | 提供部分标志；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` | +| 完全非交互式 | 提供所有参数以跳过所有提示 | `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` | @@ -124,9 +124,9 @@ npx bmad-method install \ - 为所选模块和工具配置的智能体和工作流 - 用于生成产物的 `_bmad-output/` 文件夹 -## 验证和错误处理 +## 参数校验与错误处理 -BMad 会验证所有提供的标志： +BMad 会验证你提供的所有参数： - **目录** — 必须是具有写入权限的有效路径 - **模块** — 对无效的模块 ID 发出警告（但不会失败） @@ -141,14 +141,14 @@ BMad 会验证所有提供的标志： :::tip[最佳实践] - 为 `--directory` 使用绝对路径以避免歧义 -- 在 CI/CD 流水线中使用前先在本地测试标志 +- 在 CI/CD 流水线中使用前先在本地测试参数 - 结合 `-y` 实现真正的无人值守安装 - 如果在安装过程中遇到问题，使用 `--debug` ::: ## 故障排除 -### 安装失败，提示"Invalid directory" +### 安装失败，提示 `Invalid directory` - 目录路径必须存在（或其父目录必须存在） - 您需要写入权限 @@ -167,15 +167,6 @@ BMad 会验证所有提供的标志： - 在 `module.yaml` 中有 `code` 字段 :::note[仍然卡住了？] -使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 报告。 +使用 `--debug` 获取详细输出，尝试交互模式定位问题，或在 提交反馈。 ::: ---- -## 术语说明 - -- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。 -- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 -- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。 -- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 From 76fb7e067b5e9bea9c62e3083d2fd50a7d287bff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Mon, 23 Mar 2026 00:27:41 +0800 Subject: [PATCH 6/7] docs(zh-cn): refine established project guides (#2096) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn): refine established project guides clarify the boundary between new-project and established-project usage so zh-cn readers can choose the right workflow path. align project context terminology and command references with current conventions while keeping guidance concise and executable. Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix project-context syntax and wording 我将 project-context 文档中的提示块语法统一回项目规范的 `:::...:::` 形式，避免与文档风格约定不一致。 我同时把“在不同用户故事（story）间决策不一致”调整为“之间决策不一致”，提升中文表达的自然度与可读性。 Feishu: Made-with: Cursor --------- Co-authored-by: leon Co-authored-by: Alex Verkhovsky --- docs/zh-cn/how-to/established-projects.md | 80 ++++++--------- docs/zh-cn/how-to/project-context.md | 120 +++++++++------------- 2 files changed, 82 insertions(+), 118 deletions(-) diff --git a/docs/zh-cn/how-to/established-projects.md b/docs/zh-cn/how-to/established-projects.md index 515711862..9be085fce 100644 --- a/docs/zh-cn/how-to/established-projects.md +++ b/docs/zh-cn/how-to/established-projects.md @@ -5,9 +5,9 @@ sidebar: order: 6 --- -在现有项目和遗留代码库上工作时，有效使用 BMad Method。 +当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。 -本指南涵盖了使用 BMad Method 接入现有项目的核心工作流程。 +如果你是从零开始的新项目，建议先看[快速入门](../tutorials/getting-started.md)；本文主要面向既有项目接入场景。 :::note[前置条件] - 已安装 BMad Method（`npx bmad-method install`） @@ -23,16 +23,16 @@ sidebar: - `_bmad-output/planning-artifacts/` - `_bmad-output/implementation-artifacts/` -## 步骤 2：创建项目上下文 +## 步骤 2：创建项目上下文（project context） :::tip[推荐用于既有项目] -生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。 +生成 `project-context.md`，梳理现有代码库的模式与约定，确保 AI 智能体在实施变更时遵循你既有的工程实践。 ::: -运行生成项目上下文工作流程： +运行生成项目上下文工作流： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` 这将扫描你的代码库以识别： @@ -40,9 +40,10 @@ sidebar: - 代码组织模式 - 命名约定 - 测试方法 -- 框架特定模式 +- 框架相关模式 -你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。 +你可以先审阅并完善生成内容；如果更希望手动维护，也可以直接在 +`_bmad-output/project-context.md` 创建并编辑。 [了解更多关于项目上下文](../explanation/project-context.md) @@ -55,80 +56,63 @@ sidebar: - 架构 - 任何其他相关的项目信息 -对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。 +对于复杂项目，可考虑使用 `bmad-document-project` 工作流。它会扫描整个项目并记录当前真实状态。 -## 步骤 3：获取帮助 +## 步骤 4：获取帮助 -### BMad-Help：你的起点 +### BMad-Help：默认起点 -**随时运行 `bmad-help`，当你不确定下一步该做什么时。** 这个智能指南： +**当你不确定下一步做什么时，随时运行 `bmad-help`。** 这个智能指南会： -- 检查你的项目以查看已经完成了什么 -- 根据你安装的模块显示选项 +- 检查项目当前状态，识别哪些工作已经完成 +- 根据你安装的模块给出可行选项 - 理解自然语言查询 ``` bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？ -bmad-help quick-flow 和完整方法有什么区别？ -bmad-help 显示我有哪些可用的工作流程 +bmad-help Quick Flow 和完整方法有什么区别？ +bmad-help 显示我当前有哪些可用工作流 ``` -BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。 +BMad-Help 还会在**每个工作流结束时自动运行**，明确告诉你下一步该做什么。 ### 选择你的方法 根据变更范围，你有两个主要选项： -| 范围 | 推荐方法 | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | -| **小型更新或添加** | 运行 `bmad-quick-dev` 在单个工作流中澄清意图、规划、实现和审查。完整的四阶段 BMad Method 可能有些过度。 | -| **重大变更或添加** | 从 BMad Method 开始，根据需要应用或多或少的严谨性。 | +| 范围 | 推荐方法 | +| --- | --- | +| **小型更新或新增** | 运行 `bmad-quick-dev`，在单个工作流中完成意图澄清、规划、实现与审查。完整四阶段 BMad Method 往往过重。 | +| **重大变更或新增** | 从完整 BMad Method 开始，再按项目风险和协作需求调整流程严谨度。 | ### 在创建 PRD 期间 在创建简报或直接进入 PRD 时，确保智能体： - 查找并分析你现有的项目文档 -- 阅读关于你当前系统的适当上下文 +- 读取与你当前系统匹配的项目上下文（project context） -你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。 +你可以显式补充指令，但核心目标是让新功能与现有 architecture 和代码约束自然融合。 ### UX 考量 -UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于： +UX 工作是可选项。是否需要进入 UX 流程，不取决于“项目里有没有 UX”，而取决于： -- 你是否将处理 UX 变更 -- 是否需要重要的新 UX 设计或模式 +- 你是否真的在做 UX 层面的变更 +- 是否需要新增重要的 UX 设计或交互模式 -如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。 +如果本次只是对现有页面做小幅调整，通常不需要完整 UX 流程。 -### 架构考量 +### 架构考量（architecture） 在进行架构工作时，确保架构师： -- 使用适当的已记录文件 -- 扫描现有代码库 +- 使用正确且最新的文档输入 +- 扫描并理解现有代码库 -在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。 +这一点非常关键：可避免“重复造轮子”，也能减少与现有架构冲突的设计决策。 ## 更多信息 - **[快速修复](./quick-fixes.md)** - 错误修复和临时变更 - **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题 - ---- -## 术语说明 - -- **BMad Method**：BMad 方法。一种结构化的软件开发方法论，用于指导从分析到实施的完整流程。 -- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 -- **epic**：史诗。大型功能或用户故事的集合，通常需要较长时间完成。 -- **story**：用户故事。描述用户需求的简短陈述，通常遵循"作为...我想要...以便于..."的格式。 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试、构建等功能的软件工具。 -- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 -- **tech-spec**：技术规范（Technical Specification）。描述技术实现细节、架构设计和开发标准的文档。 -- **quick-flow**：快速流程。BMad Method 中的一种简化工作流程，适用于小型变更或快速迭代。 -- **legacy codebase**：遗留代码库。指历史遗留的、可能缺乏文档或使用过时技术的代码集合。 -- **project context**：项目上下文。描述项目技术栈、约定、模式等背景信息的文档。 -- **artifact**：产物。在开发过程中生成的文档、代码或其他输出物。 -- **runtime variant**：运行时变体。在程序运行时可选择或切换的不同实现方式或配置。 diff --git a/docs/zh-cn/how-to/project-context.md b/docs/zh-cn/how-to/project-context.md index 7693d2cb6..2025a6032 100644 --- a/docs/zh-cn/how-to/project-context.md +++ b/docs/zh-cn/how-to/project-context.md @@ -5,27 +5,30 @@ sidebar: order: 8 --- -使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。 +使用 `project-context.md`，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。 +为了保证这份上下文始终可见，你也可以在工具上下文或 always-rules 文件（如 `AGENTS.md`） +中加入这句： +`Important project context and conventions are located in [path to project context]/project-context.md` :::note[前置条件] - 已安装 BMad Method -- 了解项目的技术栈和约定 +- 了解项目的技术栈与团队约定 ::: ## 何时使用 -- 在开始架构设计之前有明确的技术偏好 -- 已完成架构设计并希望为实施捕获决策 -- 正在处理具有既定模式的现有代码库 -- 注意到智能体在不同用户故事中做出不一致的决策 +- 在开始架构（architecture）前，你已有明确的技术偏好 +- 已完成架构设计，希望把关键决策沉淀到实施阶段 +- 正在处理具有既定模式的既有代码库 +- 发现智能体在不同用户故事（story）之间决策不一致 -## 步骤 1：选择方法 +## 步骤 1：选择路径 -**手动创建** — 当您确切知道要记录哪些规则时最佳 +**手动创建** — 适合你已经明确知道要沉淀哪些规则 -**架构后生成** — 最适合捕获解决方案制定过程中所做的决策 +**架构后生成** — 适合把 solutioning 阶段形成的架构决策沉淀下来 -**为现有项目生成** — 最适合在现有代码库中发现模式 +**为既有项目生成** — 适合从现有代码库中自动发现团队约定与模式 ## 步骤 2：创建文件 @@ -38,17 +41,17 @@ mkdir -p _bmad-output touch _bmad-output/project-context.md ``` -添加技术栈和实现规则： +然后补充技术栈与实现规则： ```markdown --- -project_name: 'MyProject' -user_name: 'YourName' +project_name: '我的项目' +user_name: '你的名字' date: '2026-02-15' sections_completed: ['technology_stack', 'critical_rules'] --- -# AI 智能体的项目上下文 +# AI 智能体项目上下文 ## 技术栈与版本 @@ -60,93 +63,70 @@ sections_completed: ['technology_stack', 'critical_rules'] ## 关键实现规则 **TypeScript：** -- 启用严格模式，不使用 `any` 类型 -- 公共 API 使用 `interface`，联合类型使用 `type` +- 开启严格模式，禁止使用 `any` 类型 +- 对外 API 使用 `interface`，联合类型使用 `type` **代码组织：** -- 组件位于 `/src/components/` 并附带同位置测试 -- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch +- 组件放在 `/src/components/`，并与测试文件同目录（co-located） +- API 调用统一使用 `apiClient` 单例，不要直接使用 `fetch` **测试：** -- 单元测试专注于业务逻辑 -- 集成测试使用 MSW 进行 API 模拟 +- 单元测试聚焦业务逻辑 +- 集成测试使用 MSW 模拟 API ``` ### 选项 B：架构后生成 -在新的聊天中运行工作流程： +在新的会话中运行： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` -工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。 +该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。 -### 选项 C：为现有项目生成 +### 选项 C：为既有项目生成 -对于现有项目，运行： +对于既有项目，运行： ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` -工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。 +该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。 ## 步骤 3：验证内容 -审查生成的文件并确保它捕获了： +审查生成文件，并确认它覆盖了： - 正确的技术版本 -- 实际约定（而非通用最佳实践） -- 防止常见错误的规则 -- 框架特定的模式 +- 你的真实约定（不是通用最佳实践） +- 能预防常见错误的规则 +- 框架相关模式 -手动编辑以添加任何缺失内容或删除不准确之处。 +如果有缺漏或误判，直接手动补充和修正。 -## 您将获得 +## 你将获得 -一个 `project-context.md` 文件，它： +一个 `project-context.md` 文件，它可以： -- 确保所有智能体遵循相同的约定 -- 防止在不同用户故事中做出不一致的决策 -- 为实施捕获架构决策 -- 作为项目模式和规则的参考 +- 确保所有智能体遵循相同约定 +- 避免在不同用户故事（story）中出现不一致决策 +- 为实施阶段保留架构决策 +- 作为项目模式与规则的长期参考 ## 提示 -:::tip[关注非显而易见的内容] -记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。 -::: - -:::tip[保持精简] -此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。 -::: - -:::tip[根据需要更新] -当模式发生变化时手动编辑，或在重大架构更改后重新生成。 -::: - -:::tip[适用于所有项目类型] -对于快速流程和完整的 BMad Method 项目同样有用。 +:::tip[最佳实践] +- **聚焦“不明显但重要”的规则**：优先记录智能体容易漏掉的项目约束，而不是 + “变量要有意义”这类通用建议。 +- **保持精简**：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入 + 只适用于单一 story 的细节。 +- **按需更新**：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。 +- **适用于 Quick Flow 与完整 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 的缩写，指大型语言模型。 +- [**项目上下文说明**](../explanation/project-context.md) - 了解其工作原理 +- [**工作流程图**](../reference/workflow-map.md) - 查看哪些工作流会加载项目上下文 From 980d2904f457c8f78409a782199e302f403886ad Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 22 Mar 2026 16:46:54 -0600 Subject: [PATCH 7/7] fix(quick-dev): add self-check gate for task completion tracking (#2104) Adds a Self-Check subsection at the end of step-03 that forces the implementing agent to verify all tasks are complete and mark checkboxes before handing off to the review step. Co-authored-by: Claude Opus 4.6 (1M context) --- .../4-implementation/bmad-quick-dev/step-03-implement.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md index d080a45ff..2d827b1f3 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md @@ -28,6 +28,10 @@ Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents ar **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case. +### Self-Check + +Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding. + ## NEXT Read fully and follow `./step-04-review.md`