BMAD-METHOD/shard-large-documents.md at 8b0754106d6281f0dd91956eb4741367d3d488c4

2.5 KiB

Raw Blame History

title

description

sidebar

文档分片指南

将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文

order
9

当单个 Markdown 文档过大、影响模型读取时，可使用 bmad-shard-doc 工作流把文档拆成按章节组织的小文件，降低上下文压力。

:::caution[已弃用] 这是兼容性方案，默认不推荐。随着工作流更新，以及主流模型/工具逐步支持子进程（subprocesses），很多场景将不再需要手动分片。 :::

何时使用

你确认当前工具/模型在关键步骤无法一次读入完整文档
文档体量已明显影响工作流稳定性或响应质量
你需要保留原文结构，但希望按 ## 章节拆分维护

什么是文档分片？

文档分片会按二级标题（## Heading）把大型 Markdown 文件拆成多个子文件，并生成一个 index.md 作为入口。

架构

分片前：
_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` 工作流

/bmad-shard-doc

2. 按交互流程完成分片

智能体：你想分片哪个文档？
用户：docs/PRD.md

智能体：默认目标位置：docs/prd/
       接受默认值？[y/n]
用户：y

智能体：正在分片 PRD.md...
       ✓ 已创建 12 个章节文件
       ✓ 已生成 index.md
       ✓ 完成！

工作流发现机制

BMad 工作流使用双重发现机制：

先查完整文档 - 查找 document-name.md
再查分片入口 - 查找 document-name/index.md
优先级规则 - 若两者并存，默认优先完整文档；若你要强制使用分片版本，请删除或重命名完整文档

你将获得

原始完整文档（可保留，但不建议与分片长期并存；并存时默认优先读取完整文档）
分片目录（如 document-name/index.md + 各章节文件）
对工作流透明的自动识别行为（无需额外配置）

后续步骤

如何自定义 BMad - 了解高级配置与工作流定制边界
如何升级到 v6 - 在迁移过程中处理文档与目录结构变化

2.5 KiB Raw Blame History Unescape Escape