From 90d9d880b6cd778b4ca88321e2970feb1a384f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=B1=B1=E6=B2=B3?= <392425595@qq.com> Date: Tue, 24 Mar 2026 09:20:03 +0800 Subject: [PATCH] docs(zh-cn): refine story 2.5 and 2.6 how-to guides (#2097) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(zh-cn-how-to): refine stories 2.5 and 2.6 docs 我澄清中文自定义与文档分片指南，保留命令、路径和配置键名的技术准确性，降低高级操作误解。 我同步修正 v4 到 v6 升级步骤中的旧新路径与工作流命名，帮助迁移时按当前约定执行。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor * docs(zh-cn-how-to): clarify shard output precedence 我在“你将获得”中补充完整文档与分片文档并存时的读取优先级说明。 此前“可保留”表述容易让用户误以为分片会自动生效；现在明确并存不建议且默认优先读取完整文档。 Feishu: Made-with: Cursor --------- Co-authored-by: leon Co-authored-by: Alex Verkhovsky --- docs/zh-cn/how-to/customize-bmad.md | 103 ++++++++++----------- docs/zh-cn/how-to/shard-large-documents.md | 46 +++++---- docs/zh-cn/how-to/upgrade-to-v6.md | 101 +++++++++----------- 3 files changed, 116 insertions(+), 134 deletions(-) diff --git a/docs/zh-cn/how-to/customize-bmad.md b/docs/zh-cn/how-to/customize-bmad.md index 5ed2d44c3..72afcd2bc 100644 --- a/docs/zh-cn/how-to/customize-bmad.md +++ b/docs/zh-cn/how-to/customize-bmad.md @@ -5,56 +5,56 @@ sidebar: order: 7 --- -使用 `.customize.yaml` 文件来调整智能体行为、角色和菜单，同时在更新过程中保留您的更改。 +使用 `.customize.yaml` 文件，自定义智能体（agent）的行为、角色（persona）和菜单，同时在后续更新中保留你的改动。 ## 何时使用此功能 -- 您想要更改智能体的名称、个性或沟通风格 -- 您需要智能体记住项目特定的上下文 -- 您想要添加自定义菜单项来触发您自己的工作流或提示 -- 您希望智能体在每次启动时执行特定操作 +- 你想修改智能体名称、身份设定或沟通风格 +- 你需要让智能体长期记住项目约束和背景信息 +- 你希望增加自定义菜单项，触发自己的工作流或提示 +- 你希望智能体每次启动都先执行固定动作 :::note[前置条件] -- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad.md)） +- 已在项目中安装 BMad（参见[如何安装 BMad](./install-bmad.md)） - 用于编辑 YAML 文件的文本编辑器 ::: :::caution[保护您的自定义配置] -始终使用此处描述的 `.customize.yaml` 文件，而不是直接编辑智能体文件。安装程序在更新期间会覆盖智能体文件，但会保留您的 `.customize.yaml` 更改。 +始终通过 `.customize.yaml` 自定义，不要直接改动智能体源文件。安装程序在更新时会覆盖智能体文件，但会保留 `.customize.yaml` 的内容。 ::: ## 步骤 ### 1. 定位自定义文件 -安装后，在以下位置为每个智能体找到一个 `.customize.yaml` 文件： +安装完成后，每个已安装智能体都会在下面目录生成一个 `.customize.yaml`： ```text _bmad/_config/agents/ ├── core-bmad-master.customize.yaml ├── bmm-dev.customize.yaml ├── bmm-pm.customize.yaml -└── ...（每个已安装的智能体一个文件） +└── ...（每个已安装智能体一个文件） ``` ### 2. 编辑自定义文件 -打开您想要修改的智能体的 `.customize.yaml` 文件。每个部分都是可选的——只自定义您需要的内容。 +打开目标智能体的 `.customize.yaml`。各段都可选，只改你需要的部分即可。 -| 部分 | 行为 | 用途 | +| 部分 | 作用方式 | 用途 | | ------------------ | -------- | ---------------------------------------------- | -| `agent.metadata` | 替换 | 覆盖智能体的显示名称 | -| `persona` | 替换 | 设置角色、身份、风格和原则 | -| `memories` | 追加 | 添加智能体始终会记住的持久上下文 | -| `menu` | 追加 | 为工作流或提示添加自定义菜单项 | -| `critical_actions` | 追加 | 定义智能体的启动指令 | -| `prompts` | 追加 | 创建可重复使用的提示供菜单操作使用 | +| `agent.metadata` | 覆盖 | 覆盖智能体显示名称 | +| `persona` | 覆盖 | 设置角色、身份、风格和原则 | +| `memories` | 追加 | 添加智能体长期记忆的上下文 | +| `menu` | 追加 | 增加指向工作流或提示的菜单项 | +| `critical_actions` | 追加 | 定义智能体启动时要执行的动作 | +| `prompts` | 追加 | 创建可复用提示，供菜单 `action` 引用 | -标记为 **替换** 的部分会完全覆盖智能体的默认设置。标记为 **追加** 的部分会添加到现有配置中。 +标记为 **覆盖** 的部分会完全替换默认配置；标记为 **追加** 的部分会在默认配置基础上累加。 -**智能体名称** +**智能体名称（`agent.metadata`）** -更改智能体的自我介绍方式： +修改智能体的显示名称： ```yaml agent: @@ -62,9 +62,9 @@ agent: name: 'Spongebob' # 默认值："Amelia" ``` -**角色** +**角色（`persona`）** -替换智能体的个性、角色和沟通风格： +替换智能体的人设、职责和沟通风格： ```yaml persona: @@ -76,11 +76,11 @@ persona: - 'Favor composition over inheritance' ``` -`persona` 部分会替换整个默认角色，因此如果您设置它，请包含所有四个字段。 +`persona` 会覆盖默认整段配置，所以启用时请把四个字段都填全。 -**记忆** +**记忆（`memories`）** -添加智能体将始终记住的持久上下文： +添加智能体会长期记住的上下文： ```yaml memories: @@ -89,9 +89,9 @@ memories: - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed' ``` -**菜单项** +**菜单项（`menu`）** -向智能体的显示菜单添加自定义条目。每个条目需要一个 `trigger`、一个目标（`workflow` 路径或 `action` 引用）和一个 `description`： +给智能体菜单添加自定义项。每个条目都需要 `trigger`、目标（`workflow` 路径或 `action` 引用）和 `description`： ```yaml menu: @@ -103,18 +103,18 @@ menu: description: Deploy to production ``` -**关键操作** +**启动关键动作（`critical_actions`）** -定义智能体启动时运行的指令： +定义智能体启动时执行的指令： ```yaml critical_actions: - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention' ``` -**自定义提示** +**可复用提示（`prompts`）** -创建可重复使用的提示，菜单项可以通过 `action="#id"` 引用： +创建可复用提示，菜单项可通过 `action="#id"` 调用： ```yaml prompts: @@ -126,56 +126,51 @@ prompts: 3. Execute deployment script ``` -### 3. 应用您的更改 +### 3. 应用更改 -编辑后，重新安装以应用更改： +编辑完成后，重新安装以应用配置： ```bash npx bmad-method install ``` -安装程序会检测现有安装并提供以下选项： +安装程序会识别现有安装，并给出以下选项： -| Option | What It Does | +| 选项 | 作用 | | ---------------------------- | ------------------------------------------------------------------- | -| **Quick Update** | 将所有模块更新到最新版本并应用自定义配置 | -| **Modify BMad Installation** | 用于添加或删除模块的完整安装流程 | +| **Quick Update** | 更新所有模块到最新版本，并应用你的自定义配置 | +| **Modify BMad Installation** | 进入完整安装流程，用于增删模块 | -对于仅自定义配置的更改，**Quick Update** 是最快的选项。 +如果只是调整 `.customize.yaml`，优先选 **Quick Update**。 -## 故障排除 +## 故障排查 -**更改未生效？** +**改动没有生效？** - 运行 `npx bmad-method install` 并选择 **Quick Update** 以应用更改 -- 检查您的 YAML 语法是否有效（缩进很重要） -- 验证您编辑的是该智能体正确的 `.customize.yaml` 文件 +- 检查 YAML 语法是否正确（尤其是缩进） +- 确认你编辑的是目标智能体对应的 `.customize.yaml` **智能体无法加载？** - 使用在线 YAML 验证器检查 YAML 语法错误 -- 确保在取消注释后没有留下空字段 -- 尝试恢复到原始模板并重新构建 +- 确保取消注释后没有遗留空字段 +- 可先回退到模板，再逐项恢复自定义配置 -**需要重置智能体？** +**需要重置某个智能体？** - 清空或删除智能体的 `.customize.yaml` 文件 - 运行 `npx bmad-method install` 并选择 **Quick Update** 以恢复默认设置 ## 工作流自定义 -对现有 BMad Method 工作流和技能的自定义即将推出。 +对现有 BMad Method 工作流和技能的深度自定义能力即将推出。 ## 模块自定义 关于构建扩展模块和自定义现有模块的指南即将推出。 ---- -## 术语说明 +## 后续步骤 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 -- **persona**：角色。指智能体的身份、个性、沟通风格和行为原则的集合。 -- **memory**：记忆。指智能体持久存储的上下文信息，用于在对话中保持连贯性。 -- **critical action**：关键操作。指智能体启动时必须执行的指令或任务。 -- **prompt**：提示。指发送给智能体的输入文本，用于引导其生成特定响应或执行特定操作。 +- [文档分片指南](./shard-large-documents.md) - 了解如何管理超长文档 +- [命令参考](../reference/commands.md) - 查看可用命令和工作流入口 diff --git a/docs/zh-cn/how-to/shard-large-documents.md b/docs/zh-cn/how-to/shard-large-documents.md index 759069813..0b394e502 100644 --- a/docs/zh-cn/how-to/shard-large-documents.md +++ b/docs/zh-cn/how-to/shard-large-documents.md @@ -5,19 +5,21 @@ sidebar: order: 9 --- -如果需要将大型 Markdown 文件拆分为更小、组织良好的文件以更好地管理上下文，请使用 `shard-doc` 工具。 +当单个 Markdown 文档过大、影响模型读取时，可使用 `bmad-shard-doc` 工作流把文档拆成按章节组织的小文件，降低上下文压力。 :::caution[已弃用] -不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。 +这是兼容性方案，默认不推荐。随着工作流更新，以及主流模型/工具逐步支持子进程（subprocesses），很多场景将不再需要手动分片。 ::: ## 何时使用 -仅当你发现所选工具/模型组合无法在需要时加载和读取所有文档作为输入时，才使用此方法。 +- 你确认当前工具/模型在关键步骤无法一次读入完整文档 +- 文档体量已明显影响工作流稳定性或响应质量 +- 你需要保留原文结构，但希望按 `##` 章节拆分维护 ## 什么是文档分片？ -文档分片根据二级标题（`## Heading`）将大型 Markdown 文件拆分为更小、组织良好的文件。 +文档分片会按二级标题（`## Heading`）把大型 Markdown 文件拆成多个子文件，并生成一个 `index.md` 作为入口。 ### 架构 @@ -38,16 +40,16 @@ _bmad-output/planning-artifacts/ ## 步骤 -### 1. 运行 Shard-Doc 工具 +### 1. 运行 `bmad-shard-doc` 工作流 ```bash /bmad-shard-doc ``` -### 2. 遵循交互式流程 +### 2. 按交互流程完成分片 ```text -智能体：您想要分片哪个文档？ +智能体：你想分片哪个文档？ 用户：docs/PRD.md 智能体：默认目标位置：docs/prd/ @@ -60,27 +62,21 @@ _bmad-output/planning-artifacts/ ✓ 完成！ ``` -## 工作流程发现机制 +## 工作流发现机制 -BMad 工作流程使用**双重发现系统**： +BMad 工作流使用**双重发现机制**： -1. **首先尝试完整文档** - 查找 `document-name.md` -2. **检查分片版本** - 查找 `document-name/index.md` -3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档 +1. **先查完整文档** - 查找 `document-name.md` +2. **再查分片入口** - 查找 `document-name/index.md` +3. **优先级规则** - 若两者并存，默认优先完整文档；若你要强制使用分片版本，请删除或重命名完整文档 -## 工作流程支持 +## 你将获得 -所有 BMM 工作流程都支持这两种格式： +- 原始完整文档（可保留，但不建议与分片长期并存；并存时默认优先读取完整文档） +- 分片目录（如 `document-name/index.md` + 各章节文件） +- 对工作流透明的自动识别行为（无需额外配置） -- 完整文档 -- 分片文档 -- 自动检测 -- 对用户透明 +## 后续步骤 ---- -## 术语说明 - -- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。 -- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。 -- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- [如何自定义 BMad](./customize-bmad.md) - 了解高级配置与工作流定制边界 +- [如何升级到 v6](./upgrade-to-v6.md) - 在迁移过程中处理文档与目录结构变化 diff --git a/docs/zh-cn/how-to/upgrade-to-v6.md b/docs/zh-cn/how-to/upgrade-to-v6.md index b833d360c..eb28c9c38 100644 --- a/docs/zh-cn/how-to/upgrade-to-v6.md +++ b/docs/zh-cn/how-to/upgrade-to-v6.md @@ -5,76 +5,83 @@ sidebar: order: 3 --- -使用 BMad 安装程序从 v4 升级到 v6，其中包括自动检测旧版安装和迁移辅助。 +使用 BMad 安装程序把 v4 升级到 v6。安装程序会自动识别旧安装，并提供迁移辅助，帮助你在已有项目中平滑过渡。 ## 何时使用本指南 -- 您已安装 BMad v4（`.bmad-method` 文件夹） -- 您希望迁移到新的 v6 架构 -- 您有需要保留的现有规划产物 +- 你已安装 BMad v4（目录名通常是 `.bmad-method`） +- 你准备迁移到 v6 的统一目录结构 +- 你有要保留的规划产物或进行中的开发工作 :::note[前置条件] - Node.js 20+ -- 现有的 BMad v4 安装 +- 现有 BMad v4 安装 ::: +::::caution[先备份再迁移] +如果当前仓库里仍有未提交的重要变更，先完成提交或备份，再执行升级。 +:::: + ## 步骤 ### 1. 运行安装程序 按照[安装程序说明](./install-bmad.md)操作。 -### 2. 处理旧版安装 +### 2. 处理旧版安装目录 -当检测到 v4 时，您可以： +当检测到 v4 时，你有两种处理方式： -- 允许安装程序备份并删除 `.bmad-method` -- 退出并手动处理清理 +- 允许安装程序自动备份并删除 `.bmad-method` +- 先退出安装流程，再手动清理旧目录 -如果您将 bmad method 文件夹命名为其他名称 - 您需要手动删除该文件夹。 +如果你把 BMad Method 目录改成了其他名字，需要你自己手动定位并删除。 -### 3. 清理 IDE 命令 +### 3. 清理 IDE 命令与技能目录 -手动删除旧版 v4 IDE 命令 - 例如如果您使用 claude，查找任何以 bmad 开头的嵌套文件夹并删除它们： +手动删除旧版 v4 IDE 命令/技能目录。以 Claude Code 为例，请在旧目录中删除以 `bmad` 开头的嵌套目录： -- `.claude/commands/BMad/agents` -- `.claude/commands/BMad/tasks` +- `.claude/commands/` + +v6 新技能会安装到： + +- `.claude/skills/` ### 4. 迁移规划产物 -**如果您有规划文档（Brief/PRD/UX/Architecture）：** +**如果你有规划文档（Brief/PRD/UX/Architecture）：** -将它们移动到 `_bmad-output/planning-artifacts/` 并使用描述性名称： +把它们移动到 `_bmad-output/planning-artifacts/`，并使用可读的文件名： -- 在文件名中包含 `PRD` 用于 PRD 文档 -- 相应地包含 `brief`、`architecture` 或 `ux-design` -- 分片文档可以放在命名的子文件夹中 +- PRD 文档文件名包含 `PRD` +- 其他文档按类型包含 `brief`、`architecture` 或 `ux-design` +- 分片文档可放在命名清晰的子目录中 -**如果您正在进行规划：** 考虑使用 v6 工作流重新开始。将现有文档作为输入——新的渐进式发现工作流配合网络搜索和 IDE 计划模式会产生更好的结果。 +**如果你仍在规划中：** 建议直接用 v6 工作流重启规划，把现有文档作为输入；新版渐进式发现流程配合 Web 搜索和 IDE 计划模式通常会得到更稳妥的结果。 -### 5. 迁移进行中的开发 +### 5. 迁移进行中的开发工作 -如果您已创建或实现了故事： +如果你已经创建或实现了部分用户故事（story）： 1. 完成 v6 安装 2. 将 `epics.md` 或 `epics/epic*.md` 放入 `_bmad-output/planning-artifacts/` -3. 运行 Scrum Master 的 `sprint-planning` 工作流 +3. 运行 Scrum Master 的 `bmad-sprint-planning` 工作流 4. 告诉 SM 哪些史诗/故事已经完成 -## 您将获得 +## 你将获得 **v6 统一结构：** ```text your-project/ -├── _bmad/ # 单一安装文件夹 -│ ├── _config/ # 您的自定义配置 +├── _bmad/ # 单一安装目录 +│ ├── _config/ # 你的自定义配置 │ │ └── agents/ # 智能体自定义文件 │ ├── core/ # 通用核心框架 │ ├── bmm/ # BMad Method 模块 │ ├── bmb/ # BMad Builder │ └── cis/ # Creative Intelligence Suite -└── _bmad-output/ # 输出文件夹（v4 中为 doc 文件夹） +└── _bmad-output/ # 输出目录（v4 时代常见为 doc 目录） ``` ## 模块迁移 @@ -87,34 +94,18 @@ your-project/ | `.bmad-infrastructure-devops` | 已弃用 — 新的 DevOps 智能体即将推出 | | `.bmad-creative-writing` | 未适配 — 新的 v6 模块即将推出 | -## 主要变更 +## 关键差异（旧名/新名） -| 概念 | v4 | v6 | -| ------------ | --------------------------------------- | ------------------------------------ | -| **核心** | `_bmad-core` 实际上是 BMad Method | `_bmad/core/` 是通用框架 | -| **方法** | `_bmad-method` | `_bmad/bmm/` | -| **配置** | 直接修改文件 | 每个模块使用 `config.yaml` | -| **文档** | 需要设置分片或非分片 | 完全灵活，自动扫描 | +| 概念 | v4（旧） | v6（新） | 迁移提示 | +| ------------ | --------------------------------------- | ------------------------------------ | ------------------------------------ | +| **核心框架** | `_bmad-core` 实际上承载的是 BMad Method | `_bmad/core/` 变成通用框架层 | 迁移时不要再把 `_bmad/core/` 当成 Method 本体 | +| **方法模块** | `_bmad-method` | `_bmad/bmm/` | 旧脚本、路径引用需同步更新到 `bmm` | +| **配置方式** | 直接改模块文件 | 每个模块通过 `config.yaml` 管理 | 优先改配置，不要直接改生成文件 | +| **文档读取** | 需要手动区分分片/非分片 | 自动扫描完整文档与分片入口 | 只有在兼容性场景下才建议手动分片 | ---- -## 术语说明 +## 后续建议 -- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 -- **epic**：史诗。在敏捷开发中，指大型的工作项，可分解为多个用户故事。 -- **story**：故事。在敏捷开发中，指用户故事，描述用户需求的功能单元。 -- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队流程和移除障碍。 -- **sprint-planning**：冲刺规划。Scrum 框架中的会议，用于确定下一个冲刺期间要完成的工作。 -- **sharded**：分片。将大型文档拆分为多个较小的文件以便于管理和处理。 -- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和特性的文档。 -- **Brief**：简报。概述项目目标、范围和关键信息的文档。 -- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 -- **Architecture**：架构。系统的结构设计，包括组件、模块及其相互关系。 -- **BMGD**：BMad Game Development。BMad 游戏开发模块。 -- **DevOps**：开发运维（Development Operations）。结合开发和运维的实践，旨在缩短系统开发生命周期。 -- **BMad Method**：BMad 方法。BMad 框架的核心方法论模块。 -- **BMad Builder**：BMad 构建器。BMad 框架的构建工具。 -- **Creative Intelligence Suite**：创意智能套件。BMad 框架中的创意工具集合。 -- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件开发工具。 -- **progressive discovery**：渐进式发现。逐步深入探索和理解需求的过程。 -- **web search**：网络搜索。通过互联网检索信息的能力。 -- **plan mode**：计划模式。IDE 中的一种工作模式，用于规划和设计任务。 +- 升级完成后先运行 `bmad-help`，确认可用工作流与下一步建议 +- 如果是既有项目，补充或更新 `project-context.md`，减少后续实现偏差 +- 在继续开发前，先做一次关键链路验证（安装、命令触发、文档读取） +- 继续阅读：[如何安装 BMad](./install-bmad.md)、[管理项目上下文](./project-context.md)