用途
bmad-shard-doc 用于将大型 Markdown 文档拆分成更小、更有组织的文件，拆分依据是二级标题（level 2 sections，也是默认拆分级别）。当用户要求“perform shard document”时可使用该工具。
主要能力
- 基于 Markdown 文档的二级标题进行分片。
- 使用命令 npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder] 执行拆分。
- 拆分后在目标文件夹中生成 index.md。
- 生成完成后向用户输出完成报告，包括源文档路径与名称、目标文件夹路径、生成的章节文件数量、index.md 创建确认，以及工具输出或警告。
使用方式
执行过程必须严格按照 EXECUTION 部分的步骤顺序进行，不得跳过或更改顺序，每个步骤中的每个动作都为必需动作。
步骤 1：获取源文档
- 若用户未提供源文档路径，则向用户询问。
- 验证文件存在且可访问。
- 验证文件为 Markdown 格式（.md 扩展名）。
- 若文件不存在或不是 Markdown：中止并给出错误信息。
步骤 2：获取目标文件夹
- 默认目标位置：与源文件相同的位置，文件夹名称取源文件名去掉 .md 扩展名。示例：/path/to/architecture.md --> /path/to/architecture/
- 向用户询问目标文件夹路径（[y] 确认使用默认：[suggested-path]，否则输入新路径）。
- 若用户接受默认：使用建议的目标路径。
- 若用户提供自定义路径：使用自定义目标路径。
- 验证目标文件夹存在或可创建。
- 检查目标位置的写权限。
- 若权限被拒绝：中止并给出错误信息。
步骤 3：执行拆分
- 告知用户拆分开始。
- 执行命令：npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]
- 捕获命令输出与任何错误。
- 若命令失败：中止并向用户显示错误。
步骤 4：验证输出
- 检查目标文件夹是否包含拆分后的文件。
- 验证 index.md 已在目标文件夹中创建。
- 统计已创建的文件数量。
- 若未创建任何文件：中止并给出错误信息。
步骤 5：报告完成
- 向用户展示完成报告，包含：源文档路径与名称、目标文件夹路径、生成的章节文件数量、index.md 已创建的确认、任何工具输出或警告。
- 告知用户拆分已成功完成。
步骤 6：处理原始文档
- 关键提示：同时保留原始版本和拆分版本会违背拆分的目的，并可能造成混淆。
- 向用户提供对原始文档的选项：
- [d] 删除 - 移除原始文档（推荐，分片始终可以重新合并）。
- [m] 移动到归档 - 将原始文档移动到备份/归档位置。
- [k] 保留 - 保留原始文档在原处（不推荐，违背拆分目的）。
- 提示：Your choice (d/m/k):
- 若用户选择 d（删除）：删除原始源文档文件；向用户确认删除：“Original document deleted: [source-document-path]”；说明该文档可通过按顺序连接所有章节文件从分片重建。
- 若用户选择 m（移动）：确定默认归档位置——与源文件同目录下的 archive 子文件夹，示例：/path/to/architecture.md --> /path/to/archive/architecture.md；询问归档位置（[y] 使用默认：[default-archive-path]，或提供自定义路径）；若接受默认则使用默认归档路径，否则使用自定义归档路径；若归档目录不存在则创建；将原始文档移动到归档位置；向用户确认移动：“Original document moved to: [archive-path]”。
- 若用户选择 k（保留）：向用户显示警告——同时保留原始版本和拆分版本不被推荐；discover_inputs 协议可能加载错误的版本；对其中一个的更新不会反映到另一个；重复内容占用空间；建议考虑删除或归档原始文档；向用户确认选择：“Original document kept at: [source-document-path]”。
适用场景
适用于需要将大型 Markdown 文档按二级标题拆分为多个小文件，并生成索引文件的场景，例如将架构文档等长文档进行结构化分片管理。
限制与中止条件
- 若 npx 命令失败或未产生任何输出文件，则中止。
- 必须严格按照 EXECUTION 中的步骤顺序执行，不能跳过步骤或更改顺序。
- 遇到 halt 条件必须立即中止。
- 步骤内的每个动作都是完成该步骤所必需的。
关于收费、价格、支持平台等更多信息暂未提供。