83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
---
|
||
title: "文档分片指南"
|
||
description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文
|
||
sidebar:
|
||
order: 9
|
||
---
|
||
|
||
当单个 Markdown 文档过大、影响模型读取时，可使用 `bmad-shard-doc` 工作流把文档拆成按章节组织的小文件，降低上下文压力。
|
||
|
||
:::caution[已弃用]
|
||
这是兼容性方案，默认不推荐。随着工作流更新，以及主流模型/工具逐步支持子进程（subprocesses），很多场景将不再需要手动分片。
|
||
:::
|
||
|
||
## 何时使用
|
||
|
||
- 你确认当前工具/模型在关键步骤无法一次读入完整文档
|
||
- 文档体量已明显影响工作流稳定性或响应质量
|
||
- 你需要保留原文结构，但希望按 `##` 章节拆分维护
|
||
|
||
## 什么是文档分片？
|
||
|
||
文档分片会按二级标题（`## Heading`）把大型 Markdown 文件拆成多个子文件，并生成一个 `index.md` 作为入口。
|
||
|
||
### 架构
|
||
|
||
```text
|
||
分片前：
|
||
_bmad-output/planning-artifacts/
|
||
└── PRD.md（大型 50k token 文件）
|
||
|
||
分片后：
|
||
_bmad-output/planning-artifacts/
|
||
└── prd/
|
||
├── index.md # 带有描述的目录
|
||
├── overview.md # 第 1 节
|
||
├── user-requirements.md # 第 2 节
|
||
├── technical-requirements.md # 第 3 节
|
||
└── ... # 其他章节
|
||
```
|
||
|
||
## 步骤
|
||
|
||
### 1. 运行 `bmad-shard-doc` 工作流
|
||
|
||
```bash
|
||
/bmad-shard-doc
|
||
```
|
||
|
||
### 2. 按交互流程完成分片
|
||
|
||
```text
|
||
智能体：你想分片哪个文档？
|
||
用户：docs/PRD.md
|
||
|
||
智能体：默认目标位置：docs/prd/
|
||
接受默认值？[y/n]
|
||
用户：y
|
||
|
||
智能体：正在分片 PRD.md...
|
||
✓ 已创建 12 个章节文件
|
||
✓ 已生成 index.md
|
||
✓ 完成！
|
||
```
|
||
|
||
## 工作流发现机制
|
||
|
||
BMad 工作流使用**双重发现机制**：
|
||
|
||
1. **先查完整文档** - 查找 `document-name.md`
|
||
2. **再查分片入口** - 查找 `document-name/index.md`
|
||
3. **优先级规则** - 若两者并存，默认优先完整文档；若你要强制使用分片版本，请删除或重命名完整文档
|
||
|
||
## 你将获得
|
||
|
||
- 原始完整文档（可保留，但不建议与分片长期并存；并存时默认优先读取完整文档）
|
||
- 分片目录（如 `document-name/index.md` + 各章节文件）
|
||
- 对工作流透明的自动识别行为（无需额外配置）
|
||
|
||
## 后续步骤
|
||
|
||
- [如何自定义 BMad](./customize-bmad.md) - 了解高级配置与工作流定制边界
|
||
- [如何升级到 v6](./upgrade-to-v6.md) - 在迁移过程中处理文档与目录结构变化
|