docs(zh-cn): refine story 2.5 and 2.6 how-to guides (#2097)

* 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: <https://www.feishu.cn/>
Made-with: Cursor

---------

Co-authored-by: leon <leon.liang@hairobotics.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
This commit is contained in:
梁山河 2026-03-24 09:20:03 +08:00 committed by GitHub
parent 0c245474c4
commit 90d9d880b6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 116 additions and 134 deletions

View File

@ -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) - 查看可用命令和工作流入口

View File

@ -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) - 在迁移过程中处理文档与目录结构变化

View File

@ -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)