diff --git a/docs/zh-cn/_STYLE_GUIDE.md b/docs/zh-cn/_STYLE_GUIDE.md index 93d3c2739..13cb44d02 100644 --- a/docs/zh-cn/_STYLE_GUIDE.md +++ b/docs/zh-cn/_STYLE_GUIDE.md @@ -1,25 +1,25 @@ --- title: "Documentation Style Guide" -description: Project-specific documentation conventions based on Google style and Diataxis structure +description: 基于 Google 文档风格与 Diataxis 的项目文档规范 --- -This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow. +本项目遵循 [Google Developer Documentation Style Guide](https://developers.google.com/style)，并使用 [Diataxis](https://diataxis.fr/) 组织文档。以下仅补充项目级约束。 -## Project-Specific Rules +## 项目特定规则 -| Rule | Specification | -| -------------------------------- | ---------------------------------------- | -| No horizontal rules (`---`) | Fragments reading flow | -| No `####` headers | Use bold text or admonitions instead | -| No "Related" or "Next:" sections | Sidebar handles navigation | -| No deeply nested lists | Break into sections instead | -| No code blocks for non-code | Use admonitions for dialogue examples | -| No bold paragraphs for callouts | Use admonitions instead | -| 1-2 admonitions per section max | Tutorials allow 3-4 per major section | -| Table cells / list items | 1-2 sentences max | -| Header budget | 8-12 `##` per doc; 2-3 `###` per section | +| 规则 | 规范 | +| --- | --- | +| 禁用水平分割线（`---`） | 会打断阅读流 | +| 禁用 `####` 标题 | 用加粗短句或 admonition 替代 | +| 避免 “Related/Next” 章节 | 交给侧边栏导航 | +| 避免深层嵌套列表 | 拆成新段落或新小节 | +| 非代码内容不要放代码块 | 对话/提示用 admonition | +| 不用整段粗体做提醒 | 统一用 admonition | +| 每节 1-2 个 admonition | 教程大节可放宽到 3-4 个 | +| 表格单元格/列表项 | 控制在 1-2 句 | +| 标题预算 | 每篇约 8-12 个 `##`，每节 2-3 个 `###` | -## Admonitions (Starlight Syntax) +## 提示块（Starlight 语法） ```md :::tip[Title] @@ -39,18 +39,18 @@ Critical warnings only — data loss, security issues ::: ``` -### Standard Uses +### 标准用途 -| Admonition | Use For | -| ------------------------ | ----------------------------- | -| `:::note[Prerequisites]` | Dependencies before starting | -| `:::tip[Quick Path]` | TL;DR summary at document top | -| `:::caution[Important]` | Critical caveats | -| `:::note[Example]` | Command/response examples | +| 提示块 | 适用场景 | +| --- | --- | +| `:::note[Prerequisites]` | 开始前依赖与前置条件 | +| `:::tip[Quick Path]` | 文档顶部 TL;DR | +| `:::caution[Important]` | 关键风险提醒 | +| `:::note[Example]` | 命令/响应示例说明 | -## Standard Table Formats +## 标准表格模板 -**Phases:** +**阶段（Phases）：** ```md | Phase | Name | What Happens | @@ -59,18 +59,18 @@ Critical warnings only — data loss, security issues | 2 | Planning | Requirements — PRD or spec *(required)* | ``` -**Commands:** +**技能（Skills）：** ```md -| Command | Agent | Purpose | -| ------------ | ------- | ------------------------------------ | -| `brainstorm` | Analyst | Brainstorm a new project | -| `prd` | PM | Create Product Requirements Document | +| Skill | Agent | Purpose | +| -------------------- | ------- | ------------------------------------ | +| `bmad-brainstorming` | Analyst | Brainstorm a new project | +| `bmad-create-prd` | PM | Create Product Requirements Document | ``` -## Folder Structure Blocks +## 文件结构块（Folder Structure） -Show in "What You've Accomplished" sections: +用于 “What You've Accomplished” 类章节： ````md ``` @@ -85,223 +85,223 @@ your-project/ ``` ```` -## Tutorial Structure +## 教程（Tutorial）结构 ```text -1. Title + Hook (1-2 sentences describing outcome) -2. Version/Module Notice (info or warning admonition) (optional) -3. What You'll Learn (bullet list of outcomes) -4. Prerequisites (info admonition) -5. Quick Path (tip admonition - TL;DR summary) -6. Understanding [Topic] (context before steps - tables for phases/agents) -7. Installation (optional) +1. Title + Hook（1-2 句结果导向开场） +2. Version/Module Notice（可选，信息或警告提示块） +3. What You'll Learn（结果清单） +4. Prerequisites（前置条件提示块） +5. Quick Path（TL;DR 提示块） +6. Understanding [Topic]（步骤前的背景说明，可配表格） +7. Installation（可选） 8. Step 1: [First Major Task] 9. Step 2: [Second Major Task] 10. Step 3: [Third Major Task] -11. What You've Accomplished (summary + folder structure) -12. Quick Reference (commands table) -13. Common Questions (FAQ format) -14. Getting Help (community links) -15. Key Takeaways (tip admonition) +11. What You've Accomplished（总结 + 文件结构） +12. Quick Reference（skills 表） +13. Common Questions（FAQ） +14. Getting Help（社区入口） +15. Key Takeaways（末尾 tip 提示块） ``` -### Tutorial Checklist +### 教程检查清单 -- [ ] Hook describes outcome in 1-2 sentences -- [ ] "What You'll Learn" section present -- [ ] Prerequisites in admonition -- [ ] Quick Path TL;DR admonition at top -- [ ] Tables for phases, commands, agents -- [ ] "What You've Accomplished" section present -- [ ] Quick Reference table present -- [ ] Common Questions section present -- [ ] Getting Help section present -- [ ] Key Takeaways admonition at end +- [ ] Hook 用 1-2 句明确结果 +- [ ] 包含 “What You'll Learn” +- [ ] 前置条件放在 admonition +- [ ] 顶部有 Quick Path TL;DR +- [ ] 关键信息用 phases/skills/agents 表格 +- [ ] 包含 “What You've Accomplished” +- [ ] 包含 Quick Reference 表 +- [ ] 包含 Common Questions +- [ ] 包含 Getting Help +- [ ] 末尾包含 Key Takeaways 提示块 -## How-To Structure +## How-to 结构 ```text -1. Title + Hook (one sentence: "Use the `X` workflow to...") -2. When to Use This (bullet list of scenarios) -3. When to Skip This (optional) -4. Prerequisites (note admonition) -5. Steps (numbered ### subsections) -6. What You Get (output/artifacts produced) -7. Example (optional) -8. Tips (optional) -9. Next Steps (optional) +1. Title + Hook（单句，形如 "Use the `X` workflow to..."） +2. When to Use This（3-5 条场景） +3. When to Skip This（可选） +4. Prerequisites（note 提示块） +5. Steps（编号 `###` 动词开头） +6. What You Get（产出物说明） +7. Example（可选） +8. Tips（可选） +9. Next Steps（可选） ``` -### How-To Checklist +### How-to 检查清单 -- [ ] Hook starts with "Use the `X` workflow to..." -- [ ] "When to Use This" has 3-5 bullet points -- [ ] Prerequisites listed -- [ ] Steps are numbered `###` subsections with action verbs -- [ ] "What You Get" describes output artifacts +- [ ] Hook 以 “Use the `X` workflow to...” 开头 +- [ ] “When to Use This” 有 3-5 条场景 +- [ ] 明确前置条件 +- [ ] 步骤为编号 `###` 子标题且动词开头 +- [ ] “What You Get” 明确产出物 -## Explanation Structure +## Explanation 结构 -### Types +### 类型 -| Type | Example | -| ----------------- | ----------------------------- | -| **Index/Landing** | `core-concepts/index.md` | -| **Concept** | `what-are-agents.md` | -| **Feature** | `quick-dev.md` | -| **Philosophy** | `why-solutioning-matters.md` | -| **FAQ** | `established-projects-faq.md` | +| 类型 | 示例 | +| --- | --- | +| **Index/Landing** | `core-concepts/index.md` | +| **Concept** | `what-are-agents.md` | +| **Feature** | `quick-dev.md` | +| **Philosophy** | `why-solutioning-matters.md` | +| **FAQ** | `established-projects-faq.md` | -### General Template +### 通用模板 ```text -1. Title + Hook (1-2 sentences) -2. Overview/Definition (what it is, why it matters) -3. Key Concepts (### subsections) -4. Comparison Table (optional) -5. When to Use / When Not to Use (optional) -6. Diagram (optional - mermaid, 1 per doc max) -7. Next Steps (optional) +1. Title + Hook（1-2 句） +2. Overview/Definition（是什么，为什么重要） +3. Key Concepts（`###` 小节） +4. Comparison Table（可选） +5. When to Use / When Not to Use（可选） +6. Diagram（可选，单文档最多 1 个 mermaid） +7. Next Steps（可选） ``` -### Index/Landing Pages +### Index/Landing 页面 ```text -1. Title + Hook (one sentence) -2. Content Table (links with descriptions) -3. Getting Started (numbered list) -4. Choose Your Path (optional - decision tree) +1. Title + Hook（单句） +2. Content Table（链接 + 描述） +3. Getting Started（编号步骤） +4. Choose Your Path（可选，决策树） ``` -### Concept Explainers +### 概念解释页（Concept） ```text -1. Title + Hook (what it is) -2. Types/Categories (### subsections) (optional) +1. Title + Hook（定义性开场） +2. Types/Categories（可选，`###`） 3. Key Differences Table 4. Components/Parts 5. Which Should You Use? -6. Creating/Customizing (pointer to how-to guides) +6. Creating/Customizing（指向 how-to） ``` -### Feature Explainers +### 功能解释页（Feature） ```text -1. Title + Hook (what it does) -2. Quick Facts (optional - "Perfect for:", "Time to:") +1. Title + Hook（功能作用） +2. Quick Facts（可选） 3. When to Use / When Not to Use -4. How It Works (mermaid diagram optional) +4. How It Works（可选 mermaid） 5. Key Benefits -6. Comparison Table (optional) -7. When to Graduate/Upgrade (optional) +6. Comparison Table（可选） +7. When to Graduate/Upgrade（可选） ``` -### Philosophy/Rationale Documents +### 原理/哲学页（Philosophy） ```text -1. Title + Hook (the principle) +1. Title + Hook（核心原则） 2. The Problem 3. The Solution -4. Key Principles (### subsections) +4. Key Principles（`###`） 5. Benefits 6. When This Applies ``` -### Explanation Checklist +### Explanation 检查清单 -- [ ] Hook states what document explains -- [ ] Content in scannable `##` sections -- [ ] Comparison tables for 3+ options -- [ ] Diagrams have clear labels -- [ ] Links to how-to guides for procedural questions -- [ ] 2-3 admonitions max per document +- [ ] Hook 清楚说明“本文解释什么” +- [ ] 内容分布在可扫读的 `##` 区块 +- [ ] 3 个以上选项时使用对比表 +- [ ] 图示有清晰标签 +- [ ] 程序性问题链接到 how-to +- [ ] 每篇控制在 2-3 个 admonition -## Reference Structure +## Reference 结构 -### Types +### 类型 -| Type | Example | -| ----------------- | --------------------- | -| **Index/Landing** | `workflows/index.md` | -| **Catalog** | `agents/index.md` | -| **Deep-Dive** | `document-project.md` | -| **Configuration** | `core-tasks.md` | -| **Glossary** | `glossary/index.md` | -| **Comprehensive** | `bmgd-workflows.md` | +| 类型 | 示例 | +| --- | --- | +| **Index/Landing** | `workflows/index.md` | +| **Catalog** | `agents/index.md` | +| **Deep-Dive** | `document-project.md` | +| **Configuration** | `core-tasks.md` | +| **Glossary** | `glossary/index.md` | +| **Comprehensive** | `bmgd-workflows.md` | -### Reference Index Pages +### Reference 索引页 ```text -1. Title + Hook (one sentence) -2. Content Sections (## for each category) - - Bullet list with links and descriptions +1. Title + Hook（单句） +2. Content Sections（每类一个 `##`） + - 链接 + 简短描述 ``` -### Catalog Reference +### Catalog 参考页 ```text 1. Title + Hook -2. Items (## for each item) - - Brief description (one sentence) - - **Commands:** or **Key Info:** as flat list -3. Universal/Shared (## section) (optional) +2. Items（每项一个 `##`） + - 单句说明 + - **Skills:** 或 **Key Info:** 平铺列表 +3. Universal/Shared（可选） ``` -### Item Deep-Dive Reference +### Deep-Dive 参考页 ```text -1. Title + Hook (one sentence purpose) -2. Quick Facts (optional note admonition) - - Module, Command, Input, Output as list -3. Purpose/Overview (## section) -4. How to Invoke (code block) -5. Key Sections (## for each aspect) - - Use ### for sub-options -6. Notes/Caveats (tip or caution admonition) +1. Title + Hook（单句说明用途） +2. Quick Facts（可选 note 提示块） + - Module, Skill, Input, Output +3. Purpose/Overview（`##`） +4. How to Invoke（代码块） +5. Key Sections（每个方面一个 `##`） + - 子选项使用 `###` +6. Notes/Caveats（tip/caution） ``` -### Configuration Reference +### Configuration 参考页 ```text 1. Title + Hook -2. Table of Contents (jump links if 4+ items) -3. Items (## for each config/task) - - **Bold summary** — one sentence - - **Use it when:** bullet list - - **How it works:** numbered steps (3-5 max) - - **Output:** expected result (optional) +2. Table of Contents（可选，4 项以上建议） +3. Items（每项一个 `##`） + - **Bold summary**（单句） + - **Use it when:** 场景列表 + - **How it works:** 3-5 步 + - **Output:**（可选） ``` -### Comprehensive Reference Guide +### 综合参考页（Comprehensive） ```text 1. Title + Hook -2. Overview (## section) - - Diagram or table showing organization -3. Major Sections (## for each phase/category) - - Items (### for each item) - - Standardized fields: Command, Agent, Input, Output, Description -4. Next Steps (optional) +2. Overview（`##`） + - 用图或表解释组织方式 +3. Major Sections（每个阶段/类别一个 `##`） + - Items（每项 `###`） + - 统一字段：Skill, Agent, Input, Output, Description +4. Next Steps（可选） ``` -### Reference Checklist +### Reference 检查清单 -- [ ] Hook states what document references -- [ ] Structure matches reference type -- [ ] Items use consistent structure throughout -- [ ] Tables for structured/comparative data -- [ ] Links to explanation docs for conceptual depth -- [ ] 1-2 admonitions max +- [ ] Hook 说明“本文引用什么” +- [ ] 结构匹配参考页类型 +- [ ] 条目结构前后一致 +- [ ] 结构化信息优先表格表达 +- [ ] 概念深度指向 explanation 页面 +- [ ] 每篇 1-2 个 admonition -## Glossary Structure +## Glossary 结构 -Starlight generates right-side "On this page" navigation from headers: +Starlight 右侧 “On this page” 来自标题层级： -- Categories as `##` headers — appear in right nav -- Terms in tables — compact rows, not individual headers -- No inline TOC — right sidebar handles navigation +- 分类使用 `##`（会进入右侧导航） +- 术语放在表格行中（不要给每个术语单独标题） +- 不要再写内联 TOC -### Table Format +### 表格模板 ```md ## Category Name @@ -312,17 +312,17 @@ Starlight generates right-side "On this page" navigation from headers: | **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. | ``` -### Definition Rules +### 定义规则 -| Do | Don't | -| ----------------------------- | ------------------------------------------- | -| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." | -| Keep to 1-2 sentences | Write multi-paragraph explanations | -| Bold term name in cell | Use plain text for terms | +| 推荐 | 避免 | +| --- | --- | +| 直接写“它是什么/做什么” | 以 “This is...” 或 “A [term] is...” 开头 | +| 控制在 1-2 句 | 多段长解释 | +| 术语名称加粗 | 术语用普通文本 | -### Context Markers +### 语境标记（Context Markers） -Add italic context at definition start for limited-scope terms: +在定义开头用斜体标记适用范围： - `*Quick Flow only.*` - `*BMad Method/Enterprise.*` @@ -330,16 +330,16 @@ Add italic context at definition start for limited-scope terms: - `*BMGD.*` - `*Established projects.*` -### Glossary Checklist +### Glossary 检查清单 -- [ ] Terms in tables, not individual headers -- [ ] Terms alphabetized within categories -- [ ] Definitions 1-2 sentences -- [ ] Context markers italicized -- [ ] Term names bolded in cells -- [ ] No "A [term] is..." definitions +- [ ] 术语以表格维护，不用独立标题 +- [ ] 同分类内按字母序排序 +- [ ] 定义控制在 1-2 句 +- [ ] 语境标记使用斜体 +- [ ] 术语名称在单元格中加粗 +- [ ] 避免 “A [term] is...” 句式 -## FAQ Sections +## FAQ 章节模板 ```md ## Questions @@ -353,18 +353,18 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation. ### Can I change my plan later? -Yes. The SM agent has a `correct-course` workflow for handling scope changes. +Yes. The SM agent has a `bmad-correct-course` workflow for handling scope changes. **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). ``` -## Validation Commands +## 校验命令 -Before submitting documentation changes: +提交文档改动前，建议执行： ```bash -npm run docs:fix-links # Preview link format fixes -npm run docs:fix-links -- --write # Apply fixes -npm run docs:validate-links # Check links exist -npm run docs:build # Verify no build errors +npm run docs:fix-links # 预览链接修复结果 +npm run docs:fix-links -- --write # 写回链接修复 +npm run docs:validate-links # 校验链接是否存在 +npm run docs:build # 校验站点构建 ``` diff --git a/docs/zh-cn/reference/agents.md b/docs/zh-cn/reference/agents.md index c7c53070f..803ad3d02 100644 --- a/docs/zh-cn/reference/agents.md +++ b/docs/zh-cn/reference/agents.md @@ -1,41 +1,62 @@ --- title: "智能体" -description: 默认 BMM 智能体及其菜单触发器和主要工作流 +description: 默认 BMM 智能体的 skill ID、触发器与主要 workflow 速查。 sidebar: order: 2 --- -## 默认智能体 +本页列出 BMad Method 默认提供的 BMM（Agile 套件）智能体，包括它们的 skill ID、菜单触发器和主要 workflow。 -本页列出了随 BMad Method 安装的默认 BMM（Agile 套件）智能体，以及它们的菜单触发器和主要工作流。 +## 默认智能体列表 -## 注意事项 +| 智能体 | Skill ID | 触发器 | 主要 workflow | +| --- | --- | --- | --- | +| Analyst (Mary) | `bmad-analyst` | `BP`、`RS`、`CB`、`DP` | Brainstorm、Research、Create Brief、Document Project | +| Product Manager (John) | `bmad-pm` | `CP`、`VP`、`EP`、`CE`、`IR`、`CC` | Create/Validate/Edit PRD、Create Epics and Stories、Implementation Readiness、Correct Course | +| Architect (Winston) | `bmad-architect` | `CA`、`IR` | Create Architecture、Implementation Readiness | +| Scrum Master (Bob) | `bmad-sm` | `SP`、`CS`、`ER`、`CC` | Sprint Planning、Create Story、Epic Retrospective、Correct Course | +| Developer (Amelia) | `bmad-dev` | `DS`、`CR` | Dev Story、Code Review | +| QA Engineer (Quinn) | `bmad-qa` | `QA` | Automate（为既有功能生成测试） | +| Quick Flow Solo Dev (Barry) | `bmad-master` | `QD`、`CR` | Quick Dev、Code Review | +| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design | +| Technical Writer (Paige) | `bmad-tech-writer` | `DP`、`WD`、`US`、`MG`、`VD`、`EC` | Document Project、Write Document、Update Standards、Mermaid Generate、Validate Doc、Explain Concept | -- 触发器是显示在每个智能体菜单中的简短菜单代码（例如 `CP`）和模糊匹配。 -- 斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands.md)。 -- QA（Quinn）是 BMM 中的轻量级测试自动化智能体。完整的测试架构师（TEA）位于其独立模块中。 +## 使用说明 -| 智能体 | 触发 | 主要工作流 | -| --------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------- | -| Analyst (Mary) | `BP`, `RS`, `CB`, `DP` | 头脑风暴项目、研究、创建简报、文档化项目 | -| Product Manager (John) | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | 创建/验证/编辑 PRD、创建史诗和用户故事、实施就绪、纠正方向 | -| Architect (Winston) | `CA`, `IR` | 创建架构、实施就绪 | -| Scrum Master (Bob) | `SP`, `CS`, `ER`, `CC` | 冲刺规划、创建用户故事、史诗回顾、纠正方向 | -| Developer (Amelia) | `DS`, `CR` | 开发用户故事、代码评审 | -| QA Engineer (Quinn) | `QA` | 自动化（为现有功能生成测试） | -| Quick Flow Solo Dev (Barry) | `QD`, `CR` | 快速开发、代码评审 | -| UX Designer (Sally) | `CU` | 创建 UX 设计 | -| Technical Writer (Paige) | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | 文档化项目、撰写文档、更新标准、Mermaid 生成、验证文档、解释概念 | +- `Skill ID` 是直接调用该智能体的名称（例如 `bmad-dev`） +- 触发器是进入智能体会话后可使用的菜单短码 +- QA（Quinn）是 BMM 内置轻量测试角色；完整 TEA 能力位于独立模块 ---- -## 术语说明 +## 触发器类型 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **BMM**：BMad Method 中的默认智能体套件，涵盖敏捷开发流程中的各类角色。 -- **PRD**：产品需求文档（Product Requirements Document）。 -- **Epic**：史诗。大型功能或需求集合，可拆分为多个用户故事。 -- **Story**：用户故事。描述用户需求的简短陈述。 -- **Sprint**：冲刺。敏捷开发中的固定时间周期迭代。 -- **QA**：质量保证（Quality Assurance）。 -- **TEA**：测试架构师（Test Architect）。 -- **Mermaid**：一种用于生成图表和流程图的文本语法。 +### 工作流触发器（通常不需要额外参数） + +多数触发器会直接启动结构化 workflow。你只需输入触发码，然后按流程提示提供信息。 + +示例：`CP`（Create PRD）、`DS`（Dev Story）、`CA`（Create Architecture）、`QD`（Quick Dev） + +### 会话触发器（需要附带说明） + +部分触发器进入自由对话模式，需要你在触发码后描述需求。 + +| 智能体 | 触发器 | 你需要提供的内容 | +| --- | --- | --- | +| Technical Writer (Paige) | `WD` | 要撰写的文档主题与目标 | +| Technical Writer (Paige) | `US` | 要补充到标准中的偏好/规范 | +| Technical Writer (Paige) | `MG` | 图示类型与图示内容描述 | +| Technical Writer (Paige) | `VD` | 待验证文档与关注点 | +| Technical Writer (Paige) | `EC` | 需要解释的概念名称 | + +示例： + +```text +WD 写一份 Docker 部署指南 +MG 画一个认证流程的时序图 +EC 解释模块系统如何运作 +``` + +## 相关参考 + +- [技能（Skills）参考](./commands.md) +- [工作流地图](./workflow-map.md) +- [核心工具参考](./core-tools.md) diff --git a/docs/zh-cn/reference/commands.md b/docs/zh-cn/reference/commands.md index 87336a33d..99680f32d 100644 --- a/docs/zh-cn/reference/commands.md +++ b/docs/zh-cn/reference/commands.md @@ -1,166 +1,122 @@ --- -title: "命令" -description: BMad 斜杠命令参考——它们是什么、如何工作以及在哪里找到它们。 +title: "技能（Skills）" +description: BMad 技能参考：它们是什么、如何生成以及如何调用。 sidebar: order: 3 --- -斜杠命令是预构建的提示词，用于在 IDE 中加载智能体、运行工作流或执行任务。BMad 安装程序在安装时根据已安装的模块生成这些命令。如果您后续添加、删除或更改模块，请重新运行安装程序以保持命令同步（参见[故障排除](#troubleshooting)）。 +每次运行 `npx bmad-method install`，BMad 会基于你选择的模块生成一组 **skills**。你可以直接输入 skill 名称调用 workflow、任务、工具或智能体角色。 -## 命令与智能体菜单触发器 +## Skills 与菜单触发器的区别 -BMad 提供两种开始工作的方式，它们服务于不同的目的。 - -| 机制 | 调用方式 | 发生什么 | +| 机制 | 调用方式 | 适用场景 | | --- | --- | --- | -| **斜杠命令** | 在 IDE 中输入 `bmad-...` | 直接加载智能体、运行工作流或执行任务 | -| **智能体菜单触发器** | 先加载智能体，然后输入简短代码（例如 `DS`） | 智能体解释代码并启动匹配的工作流，同时保持角色设定 | +| **Skill** | 直接输入 skill 名（如 `bmad-help`） | 你已明确要运行哪个功能 | +| **智能体菜单触发器** | 先加载智能体，再输入短触发码（如 `DS`） | 你在智能体会话内连续切换任务 | -智能体菜单触发器需要活动的智能体会话。当您知道要使用哪个工作流时，使用斜杠命令。当您已经与智能体一起工作并希望在不离开对话的情况下切换任务时，使用触发器。 +菜单触发器依赖“已激活的智能体会话”；skill 可独立运行。 -## 命令如何生成 +## Skills 如何生成 -当您运行 `npx bmad-method install` 时，安装程序会读取每个选定模块的清单，并为每个智能体、工作流、任务和工具编写一个命令文件。每个文件都是一个简短的 Markdown 提示词，指示 AI 加载相应的源文件并遵循其指令。 +安装程序会读取已选模块，为每个 agent / workflow / task / tool 生成一个 skill 目录，目录中包含 `SKILL.md` 入口文件。 -安装程序为每种命令类型使用模板： - -| 命令类型 | 生成的文件的作用 | +| Skill 类型 | 生成行为 | | --- | --- | -| **智能体启动器** | 加载智能体角色文件，激活其菜单，并保持角色设定 | -| **工作流命令** | 加载工作流引擎（`workflow.xml`）并传递工作流配置 | -| **任务命令** | 加载独立任务文件并遵循其指令 | -| **工具命令** | 加载独立工具文件并遵循其指令 | +| Agent launcher | 加载角色设定并激活菜单 | +| Workflow skill | 加载 workflow 配置并执行步骤 | +| Task skill | 执行独立任务 | +| Tool skill | 执行独立工具 | -:::note[重新运行安装程序] -如果您添加或删除模块，请再次运行安装程序。它会重新生成所有命令文件以匹配您当前的模块选择。 +:::note[模块变更后要重装] +当你新增、删除或切换模块后，请重新运行安装程序，避免 skill 列表与模块状态不一致。 ::: -## 命令文件的位置 +## Skill 文件位置 -安装程序将命令文件写入项目内 IDE 特定的目录中。确切路径取决于您在安装期间选择的 IDE。 - -| IDE / CLI | 命令目录 | +| IDE / CLI | Skills 目录 | | --- | --- | -| Claude Code | `.claude/commands/` | -| Cursor | `.cursor/commands/` | -| Windsurf | `.windsurf/workflows/` | -| 其他 IDE | 请参阅安装程序输出中的目标路径 | +| Claude Code | `.claude/skills/` | +| Cursor | `.cursor/skills/` | +| Windsurf | `.windsurf/skills/` | +| 其他 IDE | 以安装器输出路径为准 | -所有 IDE 都在其命令目录中接收一组扁平的命令文件。例如，Claude Code 安装看起来像： +示例（Claude Code）： ```text -.claude/commands/ -├── bmad-agent-bmm-dev.md -├── bmad-agent-bmm-pm.md -├── bmad-bmm-create-prd.md -├── bmad-editorial-review-prose.md -├── bmad-help.md +.claude/skills/ +├── bmad-help/ +│ └── SKILL.md +├── bmad-create-prd/ +│ └── SKILL.md +├── bmad-dev/ +│ └── SKILL.md └── ... ``` -文件名决定了 IDE 中的技能名称。例如，文件 `bmad-agent-bmm-dev.md` 注册技能 `bmad-agent-bmm-dev`。 +skill 目录名就是调用名，例如 `bmad-dev/` 对应 skill `bmad-dev`。 -## 如何发现您的命令 +## 如何发现可用 skills -在 IDE 中输入 `/bmad` 并使用自动完成功能浏览可用命令。 +- 在 IDE 中直接输入 `bmad-` 前缀查看补全候选 +- 运行 `bmad-help` 获取基于当前项目状态的下一步建议 +- 打开 skills 目录查看完整清单（这是最权威来源） -运行 `bmad-help` 获取关于下一步的上下文感知指导。 - -:::tip[快速发现] -项目中生成的命令文件夹是权威列表。在文件资源管理器中打开它们以查看每个命令及其描述。 +:::tip[快速定位] +不确定该跑哪个 workflow 时，先执行 `bmad-help`，通常比人工翻文档更快。 ::: -## 命令类别 +## Skill 分类与示例 -### 智能体命令 +### 智能体技能（Agent Skills） -智能体命令加载具有定义角色、沟通风格和工作流菜单的专业化 AI 角色。加载后，智能体保持角色设定并响应菜单触发器。 +加载一个角色化智能体，并保持其 persona 与菜单上下文。 -| 示例命令 | 智能体 | 角色 | +| 示例 skill | 角色 | 用途 | | --- | --- | --- | -| `bmad-agent-bmm-dev` | Amelia（开发者） | 严格按照规范实现故事 | -| `bmad-agent-bmm-pm` | John（产品经理） | 创建和验证 PRD | -| `bmad-agent-bmm-architect` | Winston（架构师） | 设计系统架构 | -| `bmad-agent-bmm-sm` | Bob（Scrum Master） | 管理冲刺和故事 | +| `bmad-dev` | Developer（Amelia） | 按规范实现 story | +| `bmad-pm` | Product Manager（John） | 创建与校验 PRD | +| `bmad-architect` | Architect（Winston） | 架构设计与约束定义 | +| `bmad-sm` | Scrum Master（Bob） | 冲刺与 story 流程管理 | -参见[智能体](./agents.md)获取默认智能体及其触发器的完整列表。 +完整列表见 [智能体参考](./agents.md)。 -### 工作流命令 +### Workflow Skills -工作流命令运行结构化的多步骤过程，而无需先加载智能体角色。它们加载工作流引擎并传递特定的工作流配置。 +无需先加载 agent，直接运行结构化流程。 -| 示例命令 | 目的 | +| 示例 skill | 用途 | | --- | --- | -| `bmad-bmm-create-prd` | 创建产品需求文档 | -| `bmad-bmm-create-architecture` | 设计系统架构 | -| `bmad-bmm-dev-story` | 实现故事 | -| `bmad-bmm-code-review` | 运行代码审查 | -| `bmad-bmm-quick-dev` | 统一快速流程 — 澄清意图、规划、实现、审查、呈现 | +| `bmad-create-prd` | 创建 PRD | +| `bmad-create-architecture` | 创建架构方案 | +| `bmad-create-epics-and-stories` | 拆分 epics/stories | +| `bmad-dev-story` | 实现指定 story | +| `bmad-code-review` | 代码评审 | +| `bmad-quick-dev` | 快速流程（澄清→规划→实现→审查→呈现） | -参见[工作流地图](./workflow-map.md)获取按阶段组织的完整工作流参考。 +按阶段查看见 [工作流地图](./workflow-map.md)。 -### 任务和工具命令 +### Task / Tool Skills -任务和工具是独立的操作，不需要智能体或工作流上下文。 +独立任务，不依赖特定智能体上下文。 -#### BMad-Help：您的智能向导 +**`bmad-help`** 是最常用入口：它会读取项目状态并给出“下一步建议 + 对应 skill”。 -**`bmad-help`** 是您发现下一步操作的主要界面。它不仅仅是一个查找工具——它是一个智能助手，可以： +更多核心任务和工具见 [核心工具参考](./core-tools.md)。 -- **检查您的项目**以查看已经完成的工作 -- **理解自然语言查询**——用简单的英语提问 -- **根据已安装的模块而变化**——根据您拥有的内容显示选项 -- **在工作流后自动调用**——每个工作流都以清晰的下一步结束 -- **推荐第一个必需任务**——无需猜测从哪里开始 +## 命名规则 -**示例：** +所有技能统一以 `bmad-` 开头，后接语义化名称（如 `bmad-dev`、`bmad-create-prd`、`bmad-help`）。 -``` -bmad-help -bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ -bmad-help 我在 UX 设计方面有哪些选择？ -bmad-help 我在 PRD 工作流上卡住了 -``` +## 故障排查 -#### 其他任务和工具 +**安装后看不到 skills：** 某些 IDE 需要手动启用 skills，或重启 IDE 才会刷新。 -| 示例命令 | 目的 | -| --- | --- | -| `bmad-shard-doc` | 将大型 Markdown 文件拆分为较小的部分 | -| `bmad-index-docs` | 索引项目文档 | -| `bmad-editorial-review-prose` | 审查文档散文质量 | +**缺少预期 skill：** 可能模块未安装或安装时未勾选。重新运行安装程序并确认模块选择。 -## 命名约定 +**已移除模块的 skills 仍存在：** 安装器不会自动清理历史目录。手动删除旧 skill 目录后再重装可获得干净结果。 -命令名称遵循可预测的模式。 +## 相关参考 -| 模式 | 含义 | 示例 | -| --- | --- | --- | -| `bmad-agent--` | 智能体启动器 | `bmad-agent-bmm-dev` | -| `bmad--` | 工作流命令 | `bmad-bmm-create-prd` | -| `bmad-` | 核心任务或工具 | `bmad-help` | - -模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules.md)获取描述。 - -## 故障排除 - -**安装后命令未出现。** 重启您的 IDE 或重新加载窗口。某些 IDE 会缓存命令列表，需要刷新才能获取新文件。 - -**预期的命令缺失。** 安装程序仅为您选择的模块生成命令。再次运行 `npx bmad-method install` 并验证您的模块选择。检查命令文件是否存在于预期目录中。 - -**已删除模块的命令仍然出现。** 安装程序不会自动删除旧的命令文件。从 IDE 的命令目录中删除过时的文件，或删除整个命令目录并重新运行安装程序以获取一组干净的命令。 - ---- -## 术语说明 - -- **slash command**：斜杠命令。以 `/` 开头的命令，用于在 IDE 中快速执行特定操作。 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流。一系列结构化的步骤，用于完成特定任务或流程。 -- **IDE**：集成开发环境。用于软件开发的综合应用程序，提供代码编辑、调试、构建等功能。 -- **persona**：角色设定。为智能体定义的特定角色、性格和行为方式。 -- **trigger**：触发器。用于启动特定操作或流程的机制。 -- **manifest**：清单。描述模块或组件的元数据文件。 -- **installer**：安装程序。用于安装和配置软件的工具。 -- **PRD**：产品需求文档。描述产品功能、需求和规范的文档。 -- **SaaS**：软件即服务。通过互联网提供软件服务的模式。 -- **UX**：用户体验。用户在使用产品或服务过程中的整体感受和交互体验。 +- [智能体参考](./agents.md) +- [核心工具参考](./core-tools.md) +- [模块参考](./modules.md) diff --git a/docs/zh-cn/reference/core-tools.md b/docs/zh-cn/reference/core-tools.md index c5fcd4f75..7e88db998 100644 --- a/docs/zh-cn/reference/core-tools.md +++ b/docs/zh-cn/reference/core-tools.md @@ -1,293 +1,233 @@ --- title: "核心工具" -description: 每个 BMad 安装都自带的内置任务和工作流参考。 +description: 每个 BMad 安装默认可用的任务与 workflow 参考。 sidebar: order: 2 --- -每个 BMad 安装都包含一组核心技能，可以配合你正在做的任何事情使用——跨项目、跨模块、跨阶段的独立任务和工作流。无论安装了哪些可选模块，这些工具始终可用。 +核心工具是跨模块可复用的一组通用能力：不依赖特定业务项目，也不要求先进入某个智能体角色。只要安装了 BMad，你就可以直接调用它们。 -:::tip[快速上手] -在 IDE 中输入技能名称（如 `bmad-help`）即可运行任意核心工具，无需启动智能体会话。 +:::tip[快速入口] +在 IDE 中直接输入工具 skill 名（例如 `bmad-help`）即可调用，无需先加载智能体。 ::: ## 概览 -| 工具 | 类型 | 用途 | +| 工具 | 类型 | 主要用途 | | --- | --- | --- | -| [`bmad-help`](#bmad-help) | 任务 | 根据上下文给出下一步建议 | -| [`bmad-brainstorming`](#bmad-brainstorming) | 工作流 | 引导交互式头脑风暴 | -| [`bmad-party-mode`](#bmad-party-mode) | 工作流 | 编排多智能体群组讨论 | -| [`bmad-distillator`](#bmad-distillator) | 任务 | 无损的 LLM 优化文档压缩 | -| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | 任务 | 通过迭代精炼方法提升 LLM 输出质量 | -| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | 任务 | 挑刺式审查——找出遗漏和问题 | -| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | 任务 | 穷举分支路径分析，找出未处理的边界情况 | -| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | 任务 | 临床式文案编辑，聚焦表达清晰度 | -| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | 任务 | 结构编辑——裁剪、合并与重组 | -| [`bmad-shard-doc`](#bmad-shard-doc) | 任务 | 将大型 Markdown 文件拆分为有序章节 | -| [`bmad-index-docs`](#bmad-index-docs) | 任务 | 生成或更新文件夹的文档索引 | +| [`bmad-help`](#bmad-help) | Task | 基于项目上下文推荐下一步 | +| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | 引导式头脑风暴与想法扩展 | +| [`bmad-party-mode`](#bmad-party-mode) | Workflow | 多智能体协作讨论 | +| [`bmad-distillator`](#bmad-distillator) | Task | 无损压缩文档，提升 LLM 消费效率 | +| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | 通过多轮技法增强 LLM 输出 | +| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | 对抗式问题发现审查 | +| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | 边界与分支路径穷举审查 | +| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Task | 文案可读性与表达清晰度审查 | +| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Task | 文档结构裁剪、合并与重组建议 | +| [`bmad-shard-doc`](#bmad-shard-doc) | Task | 将大文档拆分为章节文件 | +| [`bmad-index-docs`](#bmad-index-docs) | Task | 为目录生成/更新文档索引 | ## bmad-help -**你的智能向导，告诉你下一步该做什么。** — 检查项目状态，识别已完成的内容，推荐下一个必需或可选步骤。 +**定位：** 你的默认导航入口，告诉你“下一步该做什么”。 **适用场景：** +- 刚完成一个 workflow，不确定如何衔接 +- 新接触项目，需要先看当前进度 +- 变更模块后，想知道可用能力和推荐顺序 -- 完成了一个工作流，想知道接下来做什么 -- 刚接触 BMad，需要快速了解全貌 -- 卡住了，想要根据当前上下文获取建议 -- 安装了新模块，想看看有哪些可用功能 +**工作机制：** +1. 扫描已存在产物（PRD、architecture、stories 等） +2. 检测已安装模块及其可用 workflow +3. 按优先级输出“必需步骤 + 可选步骤” -**工作原理：** - -1. 扫描项目中已有的产出物（PRD、架构文档、用户故事等） -2. 检测已安装的模块及其可用工作流 -3. 按优先级推荐下一步——必需步骤优先，可选步骤其次 -4. 每条推荐都附带技能命令和简要说明 - -**输入：** 可选的自然语言查询（如 `bmad-help I have a SaaS idea, where do I start?`） - -**输出：** 按优先级排列的下一步推荐列表，附带技能命令 +**输入：** 可选自然语言问题（如 `bmad-help 我该先做 PRD 还是 architecture？`） +**输出：** 带 skill 名称的下一步建议列表 ## bmad-brainstorming -**通过交互式创意技法激发多样想法。** — 引导式头脑风暴会话，从技法库中加载经过验证的创意方法，引导你在整理之前先产出 100+ 个想法。 +**定位：** 用结构化创意技法快速扩展想法池。 **适用场景：** +- 启动新主题，想先打开问题空间 +- 团队卡在同一思路，需要外部技法打破惯性 +- 需要把“模糊方向”变成可讨论候选方案 -- 启动新项目，需要探索问题空间 -- 想法枯竭，需要结构化的创意引导 -- 想使用成熟的创意框架（SCAMPER、反向头脑风暴等） +**工作机制：** +1. 建立主题会话 +2. 从方法库选择创意技法 +3. 逐轮引导产出并记录想法 +4. 生成可追溯的会话文档 -**工作原理：** - -1. 围绕你的主题建立头脑风暴会话 -2. 从方法库中加载创意技法 -3. 逐个技法引导你产出想法 -4. 应用反偏差协议——每产出 10 个想法切换一次创意领域，防止想法扎堆 -5. 生成一份只追加的会话文档，所有想法按技法分类整理 - -**输入：** 头脑风暴主题或问题陈述，可选上下文文件 - -**输出：** `brainstorming-session-{date}.md`，包含所有产出的想法 - -:::note[数量目标] -真正的好点子往往出现在第 50-100 个想法之间。工作流鼓励在整理之前先产出 100+ 个想法。 -::: +**输入：** 主题或问题陈述（可附上下文文件） +**输出：** `brainstorming-session-{date}.md` ## bmad-party-mode -**编排多智能体群组讨论。** — 加载所有已安装的 BMad 智能体，引导一场自然对话，每个智能体从各自的专业领域和角色特征出发发言。 +**定位：** 让多个智能体围绕同一议题协作讨论。 **适用场景：** +- 决策涉及产品、架构、实现、质量等多视角 +- 希望不同角色显式冲突并暴露假设差异 +- 需要在短时间内收集多方案观点 -- 需要多个专家视角来评估一个决策 -- 希望智能体互相质疑彼此的假设 -- 正在探索一个横跨多个领域的复杂话题 +**工作机制：** +1. 读取已安装智能体清单 +2. 选取最相关的 2-3 个角色先发言 +3. 轮换角色、持续交叉讨论 +4. 使用 `goodbye` / `end party` / `quit` 结束 -**工作原理：** - -1. 加载智能体清单及所有已安装的智能体角色 -2. 分析你的话题，选出 2-3 个最相关的智能体 -3. 智能体轮流发言，自然地交叉讨论甚至争论 -4. 轮换参与的智能体，确保随时间推移覆盖多样视角 -5. 输入 `goodbye`、`end party` 或 `quit` 退出 - -**输入：** 讨论话题或问题，以及你希望参与的角色（可选） - -**输出：** 实时多智能体对话，各智能体保持各自角色特征 +**输入：** 讨论主题（可指定希望参与的角色） +**输出：** 多智能体实时对话过程 ## bmad-distillator -**无损的 LLM 优化文档压缩。** — 生成信息密度高、token 高效的精馏文档，保留全部信息供下游 LLM 消费。可通过往返重构验证无损性。 +**定位：** 在不丢失信息前提下压缩文档，降低 token 成本。 **适用场景：** +- 源文档超过上下文窗口 +- 需要把研究/规格材料转成高密度引用版本 +- 想验证压缩结果是否可逆 -- 文档太大，超出 LLM 的上下文窗口 -- 需要研究资料、规格或规划产出物的 token 高效版本 -- 想验证压缩过程中没有丢失信息 -- 智能体需要频繁引用和检索其中的信息 - -**工作原理：** - -1. **分析** — 读取源文档，识别信息密度和结构 -2. **压缩** — 将散文转为密集的要点格式，剥离装饰性排版 -3. **校验** — 检查完整性，确保原始信息全部保留 -4. **验证**（可选）— 往返重构测试，证明压缩无损 +**工作机制：** +1. 分析源文档结构与信息密度 +2. 压缩为高密度结构化表达 +3. 校验信息完整性 +4. 可选执行往返重构验证（round-trip） **输入：** +- `source_documents`（必填） +- `downstream_consumer`（可选） +- `token_budget`（可选） +- `--validate`（可选标志） -- `source_documents`（必填）— 文件路径、文件夹路径或 glob 模式 -- `downstream_consumer`（可选）— 消费方是什么（如 "PRD creation"） -- `token_budget`（可选）— 大致目标大小 -- `--validate`（标志）— 运行往返重构测试 - -**输出：** 精馏 Markdown 文件，附带压缩比报告（如 "3.2:1"） +**输出：** 精馏文档 + 压缩比报告 ## bmad-advanced-elicitation -**通过迭代精炼方法提升 LLM 输出质量。** — 从启发技法库中选取合适的方法，通过多轮迭代系统性地改进内容。 +**定位：** 对已有 LLM 输出做第二轮深挖与改写强化。 **适用场景：** +- 结果“看起来对”，但深度不够 +- 想从多个思维框架交叉审视同一内容 +- 在交付前提升论证质量与完整性 -- LLM 输出感觉浅薄或千篇一律 -- 想从多个分析角度深挖一个话题 -- 正在打磨关键文档，需要更深层的思考 +**工作机制：** +1. 加载启发技法库 +2. 选择匹配内容的候选技法 +3. 交互式选择并应用技法 +4. 多轮迭代直到你确认收敛 -**工作原理：** - -1. 加载包含 5+ 种启发技法的方法注册表 -2. 根据内容类型和复杂度选出 5 个最匹配的方法 -3. 呈现交互菜单——选一个方法、重新洗牌或列出全部 -4. 将选中的方法应用到内容上进行增强 -5. 重新呈现选项，反复迭代改进，直到你选择"继续" - -**输入：** 待增强的内容段落 - -**输出：** 应用改进后的增强版内容 +**输入：** 待增强内容片段 +**输出：** 增强后的内容版本 ## bmad-review-adversarial-general -**预设问题存在，然后去找出来的挑刺式审查。** — 以怀疑、挑剔的审查者视角，对粗糙工作零容忍。重点找遗漏，而不只是找错误。 +**定位：** 假设问题存在，主动寻找遗漏与风险。 **适用场景：** +- 文档/规格/实现即将交付前 +- 想补足“乐观审查”容易漏掉的问题 +- 需要对关键变更做压力测试 -- 在交付物定稿前需要质量保证 -- 想对规格、用户故事或文档进行压力测试 -- 想找到乐观审查容易忽略的覆盖盲区 +**工作机制：** +1. 以怀疑视角检查内容 +2. 从完整性、正确性、质量三个维度找问题 +3. 强制关注“缺失内容”，而非仅纠错 -**工作原理：** - -1. 以挑剔、批判的视角阅读内容 -2. 从完整性、正确性和质量三个维度识别问题 -3. 专门寻找遗漏的内容——不只是已有内容中的错误 -4. 至少找出 10 个问题，否则进行更深层分析 - -**输入：** - -- `content`（必填）— diff、规格、用户故事、文档或任意产出物 -- `also_consider`（可选）— 需要额外关注的领域 - -**输出：** 包含 10+ 条发现及描述的 Markdown 列表 +**输入：** `content`（必填），`also_consider`（可选） +**输出：** 结构化问题清单 ## bmad-review-edge-case-hunter -**遍历每条分支路径和边界条件，只报告未处理的情况。** — 纯路径追踪方法论，机械地推导边界类别。与对抗式审查正交——靠方法驱动，而非靠态度驱动。 +**定位：** 穷举分支路径与边界条件，只报告未覆盖情况。 **适用场景：** +- 审查核心逻辑的边界健壮性 +- 对 diff 做路径级覆盖检查 +- 与 adversarial review 形成互补 -- 想对代码或逻辑做穷举式边界覆盖 -- 需要与对抗式审查互补（不同方法论，不同发现） -- 正在审查 diff 或函数的边界条件 +**工作机制：** +1. 枚举所有分支路径 +2. 推导边界类别（missing default、off-by-one、竞态等） +3. 检查每条路径是否已有防护 +4. 仅输出未处理路径 -**工作原理：** - -1. 枚举内容中所有分支路径 -2. 机械推导边界类别：缺失的 else/default、未防护的输入、差一错误、算术溢出、隐式类型转换、竞态条件、超时间隙 -3. 逐条路径检查现有防护 -4. 只报告未处理的路径——已处理的静默丢弃 - -**输入：** - -- `content`（必填）— diff、完整文件或函数 -- `also_consider`（可选）— 需要额外关注的领域 - -**输出：** JSON 数组，每条发现包含 `location`、`trigger_condition`、`guard_snippet` 和 `potential_consequence` - -:::note[互补审查] -同时运行 `bmad-review-adversarial-general` 和 `bmad-review-edge-case-hunter` 可获得正交覆盖。对抗式审查捕捉质量和完整性问题；边界猎手捕捉未处理的路径。 -::: +**输入：** `content`（必填），`also_consider`（可选） +**输出：** JSON 发现列表（含触发条件与潜在后果） ## bmad-editorial-review-prose -**聚焦表达清晰度的临床式文案编辑。** — 审查文本中阻碍理解的问题，以 Microsoft 写作风格指南为基准，保留作者个人风格。 +**定位：** 聚焦表达清晰度的文案审查，不替你改写个人风格。 **适用场景：** +- 内容可用，但读起来费劲 +- 需要针对特定读者提升可理解性 +- 想做“表达修复”而非“立场重写” -- 写完初稿想打磨文字 -- 需要确保内容对特定受众足够清晰 -- 只想修表达问题，不想改写风格偏好 +**工作机制：** +1. 跳过 frontmatter 与代码块读取正文 +2. 标记影响理解的表达问题 +3. 去重同类问题并输出修订建议 -**工作原理：** - -1. 阅读内容，跳过代码块和 frontmatter -2. 识别表达问题（不是风格偏好） -3. 对多处出现的相同问题去重 -4. 生成三列修改表 - -**输入：** - -- `content`（必填）— Markdown、纯文本或 XML -- `style_guide`（可选）— 项目特定的写作风格指南 -- `reader_type`（可选）— `humans`（默认）注重清晰流畅，`llm` 注重精确一致 - -**输出：** 三列 Markdown 表格：原文 | 修改后 | 变更说明 +**输入：** `content`（必填），`style_guide`（可选），`reader_type`（可选） +**输出：** 三列表（原文 / 修改后 / 说明） ## bmad-editorial-review-structure -**结构编辑——提出裁剪、合并、移动和精简建议。** — 审查文档组织结构，在文案编辑之前提出实质性调整建议，以改善清晰度和阅读流畅性。 +**定位：** 处理文档结构问题：裁剪、合并、重排、精简。 **适用场景：** +- 文档是多来源拼接，结构不连贯 +- 想在不丢信息前提下降低篇幅 +- 重要信息被埋在低优先级段落 -- 文档由多个子流程产出，需要结构上的连贯性 -- 想在保持可读性的前提下缩减文档篇幅 -- 需要识别范围越界或关键信息被埋没的情况 +**工作机制：** +1. 按结构模型分析文档组织 +2. 识别冗余、越界与信息埋没 +3. 输出优先级建议与压缩预估 -**工作原理：** - -1. 将文档与 5 种结构模型对照分析（教程、参考、解释、提示词、战略） -2. 识别冗余、范围越界和被埋没的信息 -3. 生成优先级排序的建议：裁剪、合并、移动、精简、质疑、保留 -4. 估算总缩减字数和百分比 - -**输入：** - -- `content`（必填）— 待审查的文档 -- `purpose`（可选）— 预期用途（如 "quickstart tutorial"） -- `target_audience`（可选）— 目标读者 -- `reader_type`（可选）— `humans` 或 `llm` -- `length_target`（可选）— 目标缩减量（如 "30% shorter"） - -**输出：** 文档摘要、优先级排序的建议列表，以及预估缩减量 +**输入：** `content`（必填），`purpose`/`target_audience`/`reader_type`/`length_target`（可选） +**输出：** 结构建议清单 + 预计缩减量 ## bmad-shard-doc -**将大型 Markdown 文件拆分为有序的章节文件。** — 以二级标题为分割点，创建一个包含独立章节文件和索引的文件夹。 +**定位：** 把超大 Markdown 文档拆成可维护章节。 **适用场景：** +- 单文件过大（常见 500+ 行） +- 需要并行编辑或分段维护 +- 希望降低 LLM 读取成本 -- Markdown 文档过大，难以有效管理（500+ 行） -- 想把单体文档拆分成可导航的章节 -- 需要独立文件以支持并行编辑或 LLM 上下文管理 +**工作机制：** +1. 校验源文件 +2. 按 `##` 二级标题分片 +3. 生成 `index.md` 与编号章节 +4. 提示保留/归档/删除原文件 -**工作原理：** - -1. 验证源文件存在且是 Markdown 格式 -2. 按二级（`##`）标题分割为编号章节文件 -3. 创建 `index.md`，包含章节清单和链接 -4. 提示你选择删除、归档还是保留原文件 - -**输入：** 源 Markdown 文件路径，可选目标文件夹 - -**输出：** 包含 `index.md` 和 `01-{section}.md`、`02-{section}.md` 等文件的文件夹 +**输入：** 源文件路径（可选目标目录） +**输出：** 分片目录（含 `index.md`） ## bmad-index-docs -**生成或更新文件夹中所有文档的索引。** — 扫描目录，读取每个文件以理解其用途，生成一份带链接和描述的有序 `index.md`。 +**定位：** 为目录自动生成可导航文档索引。 **适用场景：** +- 文档目录持续增长，需要统一入口 +- 想给 LLM 或新人快速提供全局视图 +- 需要保持索引与目录同步 -- 需要一个轻量索引供 LLM 快速扫描可用文档 -- 文档文件夹不断增长，需要一个有序的目录 -- 想要一份自动生成、能持续保持最新的概览 +**工作机制：** +1. 扫描目录内非隐藏文件 +2. 读取文件并提炼用途 +3. 按类型/主题组织条目 +4. 生成描述简洁的 `index.md` -**工作原理：** +**输入：** 目标目录路径 +**输出：** 更新后的 `index.md` -1. 扫描目标目录中所有非隐藏文件 -2. 读取每个文件以理解其实际用途 -3. 按类型、用途或子目录分组 -4. 生成简洁描述（每条 3-10 个词） +## 相关参考 -**输入：** 目标文件夹路径 - -**输出：** `index.md`，包含有序的文件列表、相对链接和简要描述 +- [技能（Skills）参考](./commands.md) +- [智能体参考](./agents.md) +- [工作流地图](./workflow-map.md) diff --git a/docs/zh-cn/reference/modules.md b/docs/zh-cn/reference/modules.md index d8fbdf8d2..e032c4adf 100644 --- a/docs/zh-cn/reference/modules.md +++ b/docs/zh-cn/reference/modules.md @@ -1,94 +1,94 @@ --- title: "官方模块" -description: 用于构建自定义智能体、创意智能、游戏开发和测试的附加模块 +description: BMad 可选模块参考：能力边界、适用场景与外部资源 sidebar: order: 4 --- -BMad 通过您在安装期间选择的官方模块进行扩展。这些附加模块为内置核心和 BMM（敏捷套件）之外的特定领域提供专门的智能体、工作流和任务。 +BMad 通过可选模块扩展能力。你可以在安装时按需选择模块，为当前项目增加特定领域的 `agent`、`workflow` 与 `skill`。 :::tip[安装模块] -运行 `npx bmad-method install` 并选择您需要的模块。安装程序会自动处理下载、配置和 IDE 集成。 +运行 `npx bmad-method install`，在交互步骤中勾选所需模块。安装器会自动生成对应 skills 并写入当前 IDE 的 skills 目录。 ::: -## BMad Builder +## 先看总览 -在引导式协助下创建自定义智能体、工作流和特定领域的模块。BMad Builder 是用于扩展框架本身的元模块。 +| 模块 | 代码 | 最适合 | 核心能力 | +| --- | --- | --- | --- | +| BMad Builder | `bmb` | 扩展 BMad 本身 | 构建自定义 agent / workflow / module | +| Creative Intelligence Suite | `cis` | 前期创意与问题探索 | 头脑风暴、设计思维、创新策略 | +| Game Dev Studio | `gds` | 游戏方向研发 | 游戏设计文档、原型推进、叙事支持 | +| Test Architect（TEA） | `tea` | 企业级测试治理 | 测试策略、可追溯性、质量门控 | -- **代码：** `bmb` -- **npm：** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub：** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) +## BMad Builder（`bmb`） -**提供：** +用于“构建 BMad”的元模块，重点是把你的方法沉淀成可复用能力。 -- 智能体构建器 —— 创建具有自定义专业知识和工具访问权限的专用 AI 智能体 -- 工作流构建器 —— 设计包含步骤和决策点的结构化流程 -- 模块构建器 —— 将智能体和工作流打包为可共享、可发布的模块 -- 交互式设置，支持 YAML 配置和 npm 发布 +**你会得到：** +- Agent Builder：创建具备特定专业能力的 agent +- Workflow Builder：设计有步骤与决策点的 workflow +- Module Builder：将 agent/workflow 打包为可发布模块 +- 交互式配置与发布支持（YAML + npm） -## 创意智能套件 +**外部资源（英文）：** +- npm: [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) +- GitHub: [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) -用于早期开发阶段的结构化创意、构思和创新的 AI 驱动工具。该套件提供多个智能体，利用经过验证的框架促进头脑风暴、设计思维和问题解决。 +## Creative Intelligence Suite（`cis`） -- **代码：** `cis` -- **npm：** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub：** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) +用于前期探索与创意发散，帮助团队在进入规划前澄清问题与方向。 -**提供：** +**你会得到：** +- 多个创意向 agent（如创新策略、设计思维、头脑风暴） +- 问题重构与系统化思考支持 +- 常见构思框架（含 SCAMPER、逆向头脑风暴等） -- 创新策略师、设计思维教练和头脑风暴教练智能体 -- 问题解决者和创意问题解决者，用于系统性和横向思维 -- 故事讲述者和演示大师，用于叙事和推介 -- 构思框架，包括 SCAMPER、逆向头脑风暴和问题重构 +**外部资源（英文）：** +- npm: [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) +- GitHub: [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) -## 游戏开发工作室 +## Game Dev Studio（`gds`） -适用于 Unity、Unreal、Godot 和自定义引擎的结构化游戏开发工作流。通过 Quick Flow 支持快速原型制作，并通过史诗驱动的冲刺支持全面规模的生产。 +面向游戏开发场景，覆盖从概念到实现的结构化 workflow。 -- **代码：** `gds` -- **npm：** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub：** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) +**你会得到：** +- 游戏设计文档（GDD）生成流程 +- 面向快速迭代的 Quick Dev 模式 +- 叙事设计支持（角色、对话、世界观） +- 多引擎适配建议（Unity/Unreal/Godot 等） -**提供：** +**外部资源（英文）：** +- npm: [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) +- GitHub: [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) -- 游戏设计文档（GDD）生成工作流 -- 用于快速原型制作的 Quick Dev 模式 -- 针对角色、对话和世界构建的叙事设计支持 -- 覆盖 21+ 种游戏类型，并提供特定引擎的架构指导 +## Test Architect（TEA，`tea`） -## 测试架构师（TEA） +面向高要求测试场景的独立模块。与内置 QA 相比，TEA 更强调策略、追溯与发布门控。 -通过专家智能体和九个结构化工作流提供企业级测试策略、自动化指导和发布门控决策。TEA 远超内置 QA 智能体，提供基于风险的优先级排序和需求可追溯性。 +**你会得到：** +- Murat 测试架构师 agent +- 覆盖测试设计、ATDD、自动化、审查、追溯的 workflow +- NFR 评估、CI 集成与测试框架脚手架 +- P0-P3 风险优先级策略与可选工具集成 -- **代码：** `tea` -- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub：** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) +**外部资源（英文）：** +- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) +- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) +- GitHub: [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) -**提供：** +## 如何选择模块 -- Murat 智能体（主测试架构师和质量顾问） -- 用于测试设计、ATDD、自动化、测试审查和可追溯性的工作流 -- NFR 评估、CI 设置和框架脚手架 -- P0-P3 优先级排序，可选 Playwright Utils 和 MCP 集成 +- 你要“扩展框架能力”而不是只用框架：优先 `bmb` +- 你还在探索方向、需要结构化创意过程：优先 `cis` +- 你是游戏项目：优先 `gds` +- 你需要测试治理、质量门控或审计追溯：优先 `tea` -## 社区模块 +:::note[模块可以组合安装] +模块之间不是互斥关系。你可以按项目阶段增量安装，并在后续重新运行安装器同步 skills。 +::: -社区模块和模块市场即将推出。请查看 [BMad GitHub 组织](https://github.com/bmad-code-org) 获取最新更新。 +## 相关参考 ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 -- **module**：模块。指可独立开发、测试和部署的软件单元，用于扩展系统功能。 -- **meta-module**：元模块。指用于创建或扩展其他模块的模块，是模块的模块。 -- **ATDD**：验收测试驱动开发（Acceptance Test-Driven Development）。一种敏捷开发实践，在编写代码之前先编写验收测试。 -- **NFR**：非功能性需求（Non-Functional Requirement）。指系统在性能、安全性、可维护性等方面的质量属性要求。 -- **CI**：持续集成（Continuous Integration）。一种软件开发实践，频繁地将代码集成到主干分支，并进行自动化测试。 -- **MCP**：模型上下文协议（Model Context Protocol）。一种用于在 AI 模型与外部工具或服务之间进行通信的协议。 -- **SCAMPER**：一种创意思维技巧，包含替代、组合、调整、修改、其他用途、消除和重组七个维度。 -- **GDD**：游戏设计文档（Game Design Document）。用于描述游戏设计理念、玩法、机制等内容的详细文档。 -- **P0-P3**：优先级分级。P0 为最高优先级（关键），P3 为最低优先级（可选）。 -- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周，用于完成预定的工作。 -- **epic**：史诗。敏捷开发中的大型工作项，可分解为多个用户故事或任务。 -- **Quick Flow**：快速流程。一种用于快速原型开发的工作流模式。 +- [测试选项](./testing.md) +- [技能（Skills）参考](./commands.md) +- [工作流地图](./workflow-map.md) diff --git a/docs/zh-cn/reference/testing.md b/docs/zh-cn/reference/testing.md index 30b747754..a3f035ffb 100644 --- a/docs/zh-cn/reference/testing.md +++ b/docs/zh-cn/reference/testing.md @@ -1,122 +1,105 @@ --- title: "测试选项" -description: 比较内置 QA 智能体（Quinn）与测试架构师（TEA）模块的测试自动化。 +description: 内置 QA（Quinn）与 TEA 模块对比：何时用哪个、各自边界是什么 sidebar: order: 5 --- -BMad 提供两条测试路径：用于快速生成测试的内置 QA 智能体，以及用于企业级测试策略的可安装测试架构师模块。 +BMad 有两条测试路径： +- **Quinn（内置 QA）**：快速生成可运行测试 +- **TEA（可选模块）**：企业级测试策略与治理能力 -## 应该使用哪一个？ +## 该选 Quinn 还是 TEA？ -| 因素 | Quinn（内置 QA） | TEA 模块 | +| 维度 | Quinn（内置 QA） | TEA 模块 | | --- | --- | --- | -| **最适合** | 中小型项目、快速覆盖 | 大型项目、受监管或复杂领域 | -| **设置** | 无需安装——包含在 BMM 中 | 通过 `npx bmad-method install` 单独安装 | -| **方法** | 快速生成测试，稍后迭代 | 先规划，再生成并保持可追溯性 | -| **测试类型** | API 和 E2E 测试 | API、E2E、ATDD、NFR 等 | -| **策略** | 快乐路径 + 关键边界情况 | 基于风险的优先级排序（P0-P3） | -| **工作流数量** | 1（Automate） | 9（设计、ATDD、自动化、审查、可追溯性等） | +| 最适合 | 中小项目、快速补覆盖 | 大型项目、受监管或复杂业务 | +| 安装成本 | 无需额外安装（BMM 内置） | 需通过安装器单独选择 | +| 方法 | 先生成测试，再迭代 | 先定义策略，再执行并追溯 | +| 测试类型 | API + E2E | API、E2E、ATDD、NFR 等 | +| 风险策略 | 快乐路径 + 关键边界 | P0-P3 风险优先级 | +| workflow 数量 | 1（Automate） | 9（设计/自动化/审查/追溯等） | -:::tip[从 Quinn 开始] -大多数项目应从 Quinn 开始。如果后续需要测试策略、质量门控或需求可追溯性，可并行安装 TEA。 +:::tip[默认建议] +大多数项目先用 Quinn。只有当你需要质量门控、合规追溯或系统化测试治理时，再引入 TEA。 ::: -## 内置 QA 智能体（Quinn） +## 内置 QA（Quinn） -Quinn 是 BMM（敏捷套件）模块中的内置 QA 智能体。它使用项目现有的测试框架快速生成可运行的测试——无需配置或额外安装。 +Quinn 是 BMM 内置 agent，目标是用你现有测试栈快速落地测试，不要求额外配置。 -**触发方式：** `QA` 或 `bmad-bmm-qa-automate` +**触发方式：** +- 菜单触发器：`QA` +- skill：`bmad-qa-generate-e2e-tests` -### Quinn 的功能 +### Quinn 会做什么 -Quinn 运行单个工作流（Automate），包含五个步骤： +Quinn 的 Automate 流程通常包含 5 步： +1. 检测现有测试框架（如 Jest、Vitest、Playwright、Cypress） +2. 确认待测功能（手动指定或自动发现） +3. 生成 API 测试（状态码、结构、主路径与错误分支） +4. 生成 E2E 测试（语义定位器 + 可见结果断言） +5. 执行并修复基础失败项 -1. **检测测试框架**——扫描 `package.json` 和现有测试文件以识别框架（Jest、Vitest、Playwright、Cypress 或任何标准运行器）。如果不存在，则分析项目技术栈并推荐一个。 -2. **识别功能**——询问要测试的内容或自动发现代码库中的功能。 -3. **生成 API 测试**——覆盖状态码、响应结构、快乐路径和 1-2 个错误情况。 -4. **生成 E2E 测试**——使用语义定位器和可见结果断言覆盖用户工作流。 -5. **运行并验证**——执行生成的测试并立即修复失败。 +**默认风格：** +- 仅使用标准框架 API +- UI 测试优先语义定位器（角色、标签、文本） +- 测试互相独立，不依赖顺序 +- 避免硬编码等待/休眠 -Quinn 会生成测试摘要，保存到项目的实现产物文件夹中。 - -### 测试模式 - -生成的测试遵循"简单且可维护"的理念： - -- **仅使用标准框架 API**——不使用外部工具或自定义抽象 -- UI 测试使用**语义定位器**（角色、标签、文本而非 CSS 选择器） -- **独立测试**，无顺序依赖 -- **无硬编码等待或休眠** -- **清晰的描述**，可作为功能文档阅读 - -:::note[范围] -Quinn 仅生成测试。如需代码审查和故事验证，请改用代码审查工作流（`CR`）。 +:::note[范围边界] +Quinn 只负责“生成测试”。如需实现质量评审与故事验收，请配合代码审查 workflow（`CR` / `bmad-code-review`）。 ::: -### 何时使用 Quinn +### 何时用 Quinn -- 为新功能或现有功能快速实现测试覆盖 -- 无需高级设置的初学者友好型测试自动化 -- 任何开发者都能阅读和维护的标准测试模式 -- 不需要全面测试策略的中小型项目 +- 要快速补齐某个功能的测试覆盖 +- 团队希望先获得可运行基线，再逐步增强 +- 项目暂不需要完整测试治理体系 -## 测试架构师（TEA）模块 +## TEA（Test Architect）模块 -TEA 是一个独立模块，提供专家智能体（Murat）和九个结构化工作流，用于企业级测试。它超越了测试生成，涵盖测试策略、基于风险的规划、质量门控和需求可追溯性。 +TEA 提供专家测试 agent（Murat）与 9 个结构化 workflow，覆盖策略、执行、审查、追溯和发布门控。 -- **文档：** [TEA 模块文档（英文）](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) -- **安装：** `npx bmad-method install` 并选择 TEA 模块 -- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) +**外部资源（英文）：** +- 文档: [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) +- npm: [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -### TEA 提供的功能 +**安装：** `npx bmad-method install` 后选择 TEA 模块。 -| Workflow | Purpose | +### TEA 的 9 个 workflow + +| Workflow | 用途 | | --- | --- | -| Test Design | 创建与需求关联的全面测试策略 | -| ATDD | 基于干系人标准的验收测试驱动开发 | -| Automate | 使用高级模式和工具生成测试 | -| Test Review | 根据策略验证测试质量和覆盖范围 | -| Traceability | 将测试映射回需求，用于审计和合规 | -| NFR Assessment | 评估非功能性需求（性能、安全性） | -| CI Setup | 在持续集成管道中配置测试执行 | -| Framework Scaffolding | 设置测试基础设施和项目结构 | -| Release Gate | 基于数据做出发布/不发布决策 | +| Test Design | 按需求建立测试策略 | +| ATDD | 基于验收标准驱动测试设计 | +| Automate | 使用高级模式生成自动化测试 | +| Test Review | 评估测试质量与覆盖完整性 | +| Traceability | 建立“需求—测试”追溯链路 | +| NFR Assessment | 评估性能/安全等非功能需求 | +| CI Setup | 配置 CI 中的测试执行 | +| Framework Scaffolding | 搭建测试工程基础结构 | +| Release Gate | 基于数据做发布/不发布决策 | -TEA 还支持 P0-P3 基于风险的优先级排序，以及与 Playwright Utils 和 MCP 工具的可选集成。 +### 何时用 TEA -### 何时使用 TEA +- 需要合规、审计或强追溯能力 +- 需要跨功能做风险优先级管理 +- 发布前存在明确质量门控流程 +- 业务复杂，必须先建策略再写测试 -- 需要需求可追溯性或合规文档的项目 -- 需要在多个功能间进行基于风险的测试优先级排序的团队 -- 发布前具有正式质量门控的企业环境 -- 在编写测试前必须规划测试策略的复杂领域 -- 已超出 Quinn 单一工作流方法的项目 +## 测试放在流程的哪个位置 -## 测试如何融入工作流 +按 BMad workflow-map，测试位于阶段 4（实施）： -Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（实现）。典型序列： +1. epic 内逐个 story：开发（`DS` / `bmad-dev-story`）+ 代码审查（`CR` / `bmad-code-review`） +2. epic 完成后：用 Quinn 或 TEA 的 Automate 统一生成/补齐测试 +3. 最后执行复盘（`bmad-retrospective`） -1. 使用开发工作流（`DS`）实现一个故事 -2. 使用 Quinn（`QA`）或 TEA 的 Automate 工作流生成测试 -3. 使用代码审查（`CR`）验证实现 +Quinn 主要依据代码直接生成测试；TEA 可结合上游规划产物（如 PRD、architecture）实现更强追溯。 -Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。 +## 相关参考 -有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map.md)。 - ---- -## 术语说明 - -- **QA (Quality Assurance)**：质量保证。确保产品或服务满足质量要求的过程。 -- **E2E (End-to-End)**：端到端。测试整个系统从开始到结束的完整流程。 -- **ATDD (Acceptance Test-Driven Development)**：验收测试驱动开发。在编码前先编写验收测试的开发方法。 -- **NFR (Non-Functional Requirement)**：非功能性需求。描述系统如何运行而非做什么的需求，如性能、安全性等。 -- **P0-P3**：优先级级别。P0 为最高优先级，P3 为最低优先级，用于基于风险的测试排序。 -- **Happy path**：快乐路径。测试系统在理想条件下的正常工作流程。 -- **Semantic locators**：语义定位器。使用有意义的元素属性（如角色、标签、文本）而非 CSS 选择器来定位 UI 元素。 -- **Quality gates**：质量门控。在开发流程中设置的检查点，用于确保质量标准。 -- **Requirements traceability**：需求可追溯性。能够追踪需求从设计到测试再到实现的完整链路。 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **CI (Continuous Integration)**：持续集成。频繁地将代码集成到主干，并自动运行测试的实践。 -- **MCP (Model Context Protocol)**：模型上下文协议。用于在 AI 模型与外部工具之间通信的协议。 +- [官方模块](./modules.md) +- [工作流地图](./workflow-map.md) +- [智能体参考](./agents.md) diff --git a/docs/zh-cn/reference/workflow-map.md b/docs/zh-cn/reference/workflow-map.md index 7c74efe70..75c23a2b4 100644 --- a/docs/zh-cn/reference/workflow-map.md +++ b/docs/zh-cn/reference/workflow-map.md @@ -1,103 +1,86 @@ --- -title: "工作流程图" -description: BMad Method 工作流程阶段与输出的可视化参考 +title: "工作流地图" +description: BMad Method 各阶段 workflow 与产出速查 sidebar: order: 1 --- -BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下文工程与规划的最佳实践。AI 智能体在清晰、结构化的上下文中表现最佳。BMM 系统在 4 个不同阶段中逐步构建该上下文——每个阶段以及每个阶段内的多个可选工作流程都会生成文档，这些文档为下一阶段提供信息，因此智能体始终知道要构建什么以及为什么。 +BMad Method（BMM）通过分阶段 workflow 逐步构建上下文，让智能体始终知道“做什么、为什么做、如何做”。这张地图用于快速查阅阶段目标、关键 workflow 和对应产出。 -其基本原理和概念来自敏捷方法论，这些方法论在整个行业中被广泛用作思维框架，并取得了巨大成功。 - -如果您在任何时候不确定该做什么，`bmad-help` 命令将帮助您保持正轨或了解下一步该做什么。您也可以随时参考此文档以获取参考信息——但如果您已经安装了 BMad Method，`bmad-help` 是完全交互式的，速度要快得多。此外，如果您正在使用扩展了 BMad Method 或添加了其他互补非扩展模块的不同模块——`bmad-help` 会不断演进以了解所有可用内容，从而为您提供最佳即时建议。 - -最后的重要说明：以下每个工作流程都可以通过斜杠命令直接使用您选择的工具运行，或者先加载智能体，然后使用智能体菜单中的条目来运行。 +如果你不确定下一步，优先运行 `bmad-help`。它会基于你当前项目状态和已安装模块给出实时建议。

- 在新标签页中打开图表 ↗ + 在新标签页打开图表 ↗

## 阶段 1：分析（可选） -在投入规划之前探索问题空间并验证想法。 +在正式规划前，先验证问题空间与关键假设。 -| 工作流程 | 目的 | 产出 | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | -| `bmad-brainstorming` | 在头脑风暴教练的引导协助下进行项目想法头脑风暴 | `brainstorming-report.md` | -| `bmad-bmm-research` | 验证市场、技术或领域假设 | 研究发现 | -| `bmad-bmm-create-product-brief` | 捕捉战略愿景 | `product-brief.md` | +| Workflow | 目的 | 产出 | +| --- | --- | --- | +| `bmad-brainstorming` | 通过引导式创意方法扩展方案空间 | `brainstorming-report.md` | +| `bmad-domain-research`、`bmad-market-research`、`bmad-technical-research` | 验证领域、市场与技术假设 | 研究发现 | +| `bmad-create-product-brief` | 沉淀产品方向与战略愿景 | `product-brief.md` | ## 阶段 2：规划 -定义要构建什么以及为谁构建。 +定义“为谁做、做什么”。 -| 工作流程 | 目的 | 产出 | -| --------------------------- | ---------------------------------------- | ------------ | -| `bmad-bmm-create-prd` | 定义需求（FRs/NFRs） | `PRD.md` | -| `bmad-bmm-create-ux-design` | 设计用户体验（当 UX 重要时） | `ux-spec.md` | +| Workflow | 目的 | 产出 | +| --- | --- | --- | +| `bmad-create-prd` | 明确 FR/NFR 与范围边界 | `PRD.md` | +| `bmad-create-ux-design` | 在 UX 复杂场景下补齐交互与体验方案 | `ux-spec.md` | -## 阶段 3：解决方案设计 +## 阶段 3：解决方案设计（Solutioning） -决定如何构建它并将工作分解为故事。 +定义“如何实现”并拆分可交付工作单元。 -| 工作流程 | 目的 | 产出 | -| ----------------------------------------- | ------------------------------------------ | --------------------------- | -| `bmad-bmm-create-architecture` | 明确技术决策 | 包含 ADR 的 `architecture.md` | -| `bmad-bmm-create-epics-and-stories` | 将需求分解为可实施的工作 | 包含故事的 Epic 文件 | -| `bmad-bmm-check-implementation-readiness` | 实施前的关卡检查 | PASS/CONCERNS/FAIL 决策 | +| Workflow | 目的 | 产出 | +| --- | --- | --- | +| `bmad-create-architecture` | 显式记录技术决策与架构边界 | `architecture.md`（含 ADR） | +| `bmad-create-epics-and-stories` | 将需求拆分为可实施的 epics/stories | epics 文件与 story 条目 | +| `bmad-check-implementation-readiness` | 实施前 gate 检查 | PASS / CONCERNS / FAIL 结论 | ## 阶段 4：实施 -逐个故事地构建它。即将推出完整的阶段 4 自动化！ +按 story 节奏持续交付与校验。 -| 工作流程 | 目的 | 产出 | -| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | -| `bmad-bmm-sprint-planning` | 初始化跟踪（每个项目一次，以排序开发周期） | `sprint-status.yaml` | -| `bmad-bmm-create-story` | 准备下一个故事以供实施 | `story-[slug].md` | -| `bmad-bmm-dev-story` | 实施该故事 | 工作代码 + 测试 | -| `bmad-bmm-code-review` | 验证实施质量 | 批准或请求更改 | -| `bmad-bmm-correct-course` | 处理冲刺中的重大变更 | 更新的计划或重新路由 | -| `bmad-bmm-automate` | 为现有功能生成测试 - 在完整的 epic 完成后使用 | 端到端 UI 专注测试套件 | -| `bmad-bmm-retrospective` | 在 epic 完成后回顾 | 经验教训 | +| Workflow | 目的 | 产出 | +| --- | --- | --- | +| `bmad-sprint-planning` | 初始化迭代追踪（通常每项目一次） | `sprint-status.yaml` | +| `bmad-create-story` | 准备下一个可实施 story | `story-[slug].md` | +| `bmad-dev-story` | 按规范实现 story | 可运行代码与测试 | +| `bmad-code-review` | 验证实现质量 | 通过或变更请求 | +| `bmad-correct-course` | 处理中途重大方向调整 | 更新后的计划或重路由 | +| `bmad-sprint-status` | 跟踪冲刺与 story 状态 | 状态更新 | +| `bmad-retrospective` | epic 完成后复盘 | 经验与改进项 | -## 快速流程（并行轨道） +## Quick Flow（并行快线） -对于小型、易于理解的工作，跳过阶段 1-3。 +当任务范围小且目标清晰时，可跳过阶段 1-3 直接推进： -| 工作流程 | 目的 | 产出 | -| --------------------- | --------------------------------------------------------------------------- | --------------------------- | -| `bmad-bmm-quick-dev` | 统一快速流程 — 澄清意图、规划、实现、审查和呈现 | `spec-*.md` + 代码 | +| Workflow | 目的 | 产出 | +| --- | --- | --- | +| `bmad-quick-dev` | 统一快流：意图澄清、规划、实现、审查、呈现 | `spec-*.md` + 代码变更 | ## 上下文管理 -每个文档都成为下一阶段的上下文。PRD 告诉架构师哪些约束很重要。架构告诉开发智能体要遵循哪些模式。故事文件为实施提供专注、完整的上下文。没有这种结构，智能体会做出不一致的决策。 +每个阶段产出都会成为下一阶段输入：PRD 约束架构，架构约束开发，story 约束实现。没有这条链路，智能体更容易在跨 story 时出现不一致决策。 -### 项目上下文 - -:::tip[推荐] -创建 `project-context.md` 以确保 AI 智能体遵循您项目的规则和偏好。该文件就像您项目的宪法——它指导所有工作流程中的实施决策。这个可选文件可以在架构创建结束时生成，或者在现有项目中也可以生成它，以捕捉与当前约定保持一致的重要内容。 +:::tip[Project Context 建议] +创建 `project-context.md`，把项目特有约定（技术栈、命名、组织、测试策略）写成共享规则，能显著降低实现偏差。 ::: -**如何创建它：** +**创建方式：** +- **手动创建**：在 `_bmad-output/project-context.md` 记录项目规则 +- **自动生成**：运行 `bmad-generate-project-context` 从架构或代码库提取 -- **手动** — 使用您的技术栈和实施规则创建 `_bmad-output/project-context.md` -- **生成它** — 运行 `bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成 +## 相关参考 -[**了解更多关于 project-context.md**](../explanation/project-context.md) - ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **BMad Method (BMM)**：BMad 方法。BMad 生态系统中的一个模块，用于上下文工程与规划。 -- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。 -- **PRD**：产品需求文档。Product Requirements Document 的缩写。 -- **UX**：用户体验。User Experience 的缩写。 -- **ADR**：架构决策记录。Architecture Decision Record 的缩写。 -- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个冲刺才能完成。 -- **Story**：用户故事。描述用户需求的简短陈述。 -- **Sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 -- **Slug**：短标识符。URL 友好的标识符，通常用于文件命名。 -- **Context**：上下文。为 AI 智能体提供的环境信息和背景资料。 +- [命令与技能参考](./commands.md) +- [智能体参考](./agents.md) +- [核心工具参考](./core-tools.md) +- [项目上下文说明](../explanation/project-context.md) diff --git a/docs/zh-cn/roadmap.mdx b/docs/zh-cn/roadmap.mdx index 2bc89b7e2..4b5833f12 100644 --- a/docs/zh-cn/roadmap.mdx +++ b/docs/zh-cn/roadmap.mdx @@ -1,11 +1,11 @@ --- title: 路线图 -description: BMad 的下一步计划——功能、改进与社区贡献 +description: BMad 后续方向：功能演进、体验优化与社区生态 --- -# BMad 方法：公开路线图 +# BMad Method 公开路线图 -BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续演进。以下是我们正在开展的工作以及即将推出的内容。 +BMad Method、BMM（Agile 套件）与 BMad Builder 正在持续迭代。以下内容用于说明当前重点与下一阶段规划。
@@ -14,139 +14,123 @@ BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续
🧩 -

通用技能架构

-

一个技能，任意平台。一次编写，随处运行。

+

通用 Skills 架构

+

同一 skill 在不同平台复用，降低跨工具维护成本。

🏗️ -

BMad 构建器 v1

-

打造生产级 AI 智能体与工作流，内置评估、团队协作与优雅降级。

+

BMad Builder v1

+

面向生产场景的 agent/workflow 构建能力，覆盖评估、协作与优雅降级。

🧠 -

项目上下文系统

-

AI 真正理解你的项目。框架感知的上下文，随代码库共同演进。

+

Project Context 系统

+

让 AI 在项目约束内工作：上下文随代码库变化持续更新。

📦 -

集中式技能

-

一次安装，随处使用。跨项目共享技能，告别文件杂乱。

+

集中式 Skills

+

减少项目内重复拷贝，支持跨项目共享与统一管理。

🔄 -

自适应技能

-

技能懂你的工具。为 Claude、Codex、Kimi、OpenCode 等提供优化变体，以及更多。

+

自适应 Skills

+

针对 Claude、Codex、Kimi、OpenCode 等平台提供优化变体。

📝 -

BMad 团队专业博客

-

来自团队的指南、文章与见解。即将上线。

+

BMad 团队博客

+

持续发布实践文章、方法拆解与落地经验。

-

入门阶段

+

近期规划

🏪 -

技能市场

-

发现、安装与更新社区构建的技能。一条 curl 命令即可获得超能力。

+

Skill 市场

+

发现、安装、更新社区技能，缩短能力接入路径。

🎨 -

工作流定制

-

打造属于你的工作流。集成 Jira、Linear、自定义输出——你的工作流，你的规则。

+

Workflow 定制

+

支持 Jira、Linear 与自定义产出对接，构建团队专属流程。

🚀

阶段 1-3 优化

-

通过子智能体上下文收集实现闪电般快速的规划。YOLO 模式遇上引导式卓越。

+

通过子智能体上下文采集提升前期分析与规划效率。

🌐 -

企业级就绪

-

SSO、审计日志、团队工作空间。那些让企业点头同意的无聊但必要的东西。

+

企业级能力完善

+

补齐 SSO、审计日志、团队工作区等企业落地基础能力。

💎 -

社区模块爆发

-

娱乐、安全、治疗、角色扮演以及更多内容。扩展 BMad 方法平台。

+

社区模块扩展

+

覆盖更多垂直场景，持续扩展 BMad 模块生态。

⚡

开发循环自动化

-

可选的开发自动驾驶。让 AI 处理流程，同时保持质量高企。

+

在可控质量边界内提升自动化程度，减少重复人工操作。

-

社区与团队

+

社区与团队计划

🎙️ -

BMad 方法播客

-

关于 AI 原生开发的对话。2026 年 3 月 1 日上线！

+

BMad Method 播客

+

围绕 AI 原生研发方法开展持续讨论与案例分享。

🎓 -

BMad 方法大师课

-

从用户到专家。深入每个阶段、每个工作流、每个秘密。

+

BMad Method 大师课

+

面向进阶用户，系统拆解各阶段与核心 workflow。

🏗️ -

BMad 构建器大师课

-

构建你自己的智能体。当你准备好创造而不仅仅是使用时的高级技巧。

+

BMad Builder 大师课

+

聚焦自定义 agent/workflow 的高级设计与工程实践。

⚡ -

BMad 原型优先

-

一次会话从想法到可用原型。像创作艺术品一样打造你的梦想应用。

+

BMad Prototype First

+

探索“单会话从想法到原型”的端到端实践路径。

🌴 -

BMad BALM！

-

AI 原生的生活管理。任务、习惯、目标——你的 AI 副驾驶，无处不在。

+

BMad BALM

+

将 AI 原生协作模式扩展到个人任务、习惯与目标管理。

🖥️

官方 UI

-

整个 BMad 生态系统的精美界面。CLI 的强大，GUI 的精致。

+

在保留 CLI 能力的基础上提供完整图形化操作体验。

🔒 -

BMad 一体机

-

自托管、气隙隔离、企业级。你的 AI 助手、你的基础设施、你的控制。

+

BMad in a Box

+

面向自托管与气隙隔离场景的企业级部署方案。

-

想要贡献？

+

欢迎参与贡献

- 这只是计划内容的一部分。BMad 开源团队欢迎贡献者！{" "}
- 在 GitHub 上加入我们，共同塑造 AI 驱动开发的未来。 + 以上并非全部规划。BMad 开源团队欢迎贡献者加入。{" "}
+ 前往 GitHub 仓库 参与共建。

- 喜欢我们正在构建的东西？我们感谢一次性与月度{" "}支持。 + 如果你认可项目方向，也欢迎通过{" "}支持渠道 帮助我们持续迭代。

- 如需企业赞助、合作咨询、演讲邀请、培训或媒体咨询：{" "} + 企业赞助、合作咨询、培训与媒体联系：{" "} contact@bmadcode.com

- ---- -## 术语说明 - -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **SSO**：单点登录。一种用户认证机制，允许用户使用一组凭据访问多个应用程序。 -- **air-gapped**：气隙隔离。指系统与外部网络完全物理隔离的安全措施。 -- **YOLO**：You Only Live Once 的缩写，此处指快速、大胆的执行模式。 -- **evals**：评估。对 AI 模型或智能体性能的测试与评价。 -- **graceful degradation**：优雅降级。系统在部分功能失效时仍能保持基本功能的特性。 -- **sub-agent**：子智能体。在主智能体协调下执行特定任务的辅助智能体。 -- **context**：上下文。AI 理解任务所需的相关信息与环境背景。 -- **workflow**：工作流。一系列有序的任务或操作流程。 -- **skills**：技能。AI 智能体可执行的具体能力或功能模块。 -- **CLI**：命令行界面。通过文本命令与计算机交互的方式。 -- **GUI**：图形用户界面。通过图形元素与计算机交互的方式。