bmad-shard-doc

分片文档

目标： 使用 npx @kayvan/markdown-tree-parser 将大型 markdown 文档按二级标题拆分为更小、更有条理的文件。

关键规则

• 强制要求：按精确顺序执行 EXECUTION 部分中的所有步骤
• 不要跳过步骤或更改顺序
• 满足停止条件时立即停止
• 步骤中的每个操作都是完成该步骤的必需操作

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：处理原始文档

关键： 同时保留原始版本和分片版本会违背分片的目的，并可能导致混淆。

向用户提供原始文档的选项：

您想如何处理原始文档 [source-document-name]？

选项：

• [d] 删除 - 移除原始文档（推荐 - 分片始终可以重新组合）
• [m] 移动到归档 - 将原始文档移动到备份/归档位置
• [k] 保留 - 将原始文档留在原处（不推荐 - 违背分片目的）

您的选择（d/m/k）：

如果用户选择 d（删除）

• 删除原始源文档文件
• 向用户确认删除：“原始文档已删除：[source-document-path]”
• 注意：文档可以通过按顺序拼接所有章节文件从分片重建

如果用户选择 m（移动）

• 确定默认归档位置：与源文件相同的目录，在 archive 子文件夹中
  • 示例：/path/to/architecture.md --> /path/to/archive/architecture.md
• 询问：归档位置（[y] 使用默认值：[default-archive-path]，或提供自定义路径）
• 如果用户接受默认值：使用默认归档路径
• 如果用户提供自定义路径：使用自定义归档路径
• 如果归档目录不存在则创建
• 将原始文档移动到归档位置
• 向用户确认移动：“原始文档已移动到：[archive-path]”

如果用户选择 k（保留）

• 向用户显示警告：
  • 不推荐同时保留原始版本和分片版本
  • discover_inputs 协议可能加载错误的版本
  • 对其中一个的更新不会反映在另一个中
  • 重复内容占用空间
  • 考虑删除或归档原始文档
• 确认用户选择：“原始文档保留在：[source-document-path]”

停止条件

• 如果 npx 命令失败或未生成输出文件，则停止