Back to Details

bmad-shard-doc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shard Document

文档分片

Goal: Split large markdown documents into smaller, organized files based on level 2 sections using 
npx @kayvan/markdown-tree-parser
.
目标： 使用
npx @kayvan/markdown-tree-parser
基于二级标题将大型markdown文档拆分为更小的、有序的文件。

CRITICAL RULES

关键规则

  • MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
  • DO NOT skip steps or change the sequence
  • HALT immediately when halt-conditions are met
  • Each action within a step is a REQUIRED action to complete that step
  • 强制要求：严格按照顺序执行「执行步骤」板块中的所有步骤
  • 请勿跳过步骤或调整顺序
  • 满足终止条件时立即停止操作
  • 每个步骤中的所有操作均为完成该步骤的必填操作

EXECUTION

执行步骤

Step 1: Get Source Document

步骤1：获取源文档

  • Ask user for the source document path if not provided already
  • Verify file exists and is accessible
  • Verify file is markdown format (.md extension)
  • If file not found or not markdown: HALT with error message
  • 如果用户尚未提供源文档路径，向用户询问该路径
  • 验证文件存在且可访问
  • 验证文件为markdown格式（.md后缀）
  • 如果文件不存在或不是markdown格式：终止运行并返回错误信息

Step 2: Get Destination Folder

步骤2：获取目标文件夹

  • Determine default destination: same location as source file, folder named after source file without .md extension
    • Example: 
      /path/to/architecture.md
      --> 
      /path/to/architecture/
  • Ask user for the destination folder path (
    [y]
    to confirm use of default: 
    [suggested-path]
    , else enter a new path)
  • If user accepts default: use the suggested destination path
  • If user provides custom path: use the custom destination path
  • Verify destination folder exists or can be created
  • Check write permissions for destination
  • If permission denied: HALT with error message
  • 确定默认存储路径：与源文件同目录，文件夹名称为去掉.md后缀的源文件名
    • 示例：
      /path/to/architecture.md
      --> 
      /path/to/architecture/
  • 向用户询问目标文件夹路径（输入
    [y]
    确认使用默认路径：
    [suggested-path]
    ，否则输入新路径）
  • 如果用户接受默认路径：使用推荐的目标路径
  • 如果用户提供自定义路径：使用自定义目标路径
  • 验证目标文件夹存在或可被创建
  • 检查目标路径的写入权限
  • 如果权限不足：终止运行并返回错误信息

Step 3: Execute Sharding

步骤3：执行分片

  • Inform user that sharding is beginning
  • Execute command: 
    npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]
  • Capture command output and any errors
  • If command fails: HALT and display error to user
  • 告知用户分片操作即将开始
  • 执行命令：
    npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]
  • 捕获命令输出及所有错误信息
  • 如果命令执行失败：终止运行并向用户展示错误

Step 4: Verify Output

步骤4：验证输出

  • Check that destination folder contains sharded files
  • Verify index.md was created in destination folder
  • Count the number of files created
  • If no files created: HALT with error message
  • 检查目标文件夹中是否包含分片后的文件
  • 验证目标文件夹中已生成index.md
  • 统计创建的文件数量
  • 如果未生成任何文件：终止运行并返回错误信息

Step 5: Report Completion

步骤5：上报完成状态

  • Display completion report to user including:
    • Source document path and name
    • Destination folder path
    • Number of section files created
    • Confirmation that index.md was created
    • Any tool output or warnings
  • Inform user that sharding completed successfully
  • 向用户展示完成报告，包含以下内容：
    • 源文档路径及名称
    • 目标文件夹路径
    • 已创建的分片文件数量
    • index.md已创建的确认信息
    • 所有工具输出或警告信息
  • 告知用户分片操作已成功完成

Step 6: Handle Original Document

步骤6：处理原文档

Critical: Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
Present user with options for the original document:
What would you like to do with the original document 
[source-document-name]
?
Options:
  • [d]
    Delete - Remove the original (recommended - shards can always be recombined)
  • [m]
    Move to archive - Move original to a backup/archive location
  • [k]
    Keep - Leave original in place (NOT recommended - defeats sharding purpose)
Your choice (d/m/k):
关键提示： 同时保留原文档和分片版本会违背分片的目的，还可能造成混淆。
向用户提供原文档的处理选项：
请问你想要如何处理原文档
[source-document-name]
？
选项：
  • [d]
    删除 - 移除原文件（推荐选择 - 分片文件随时可以重新合并）
  • [m]
    移动到归档 - 将原文件移动到备份/归档位置
  • [k]
    保留 - 原文件留在原位（不推荐 - 违背分片目的）
请选择（d/m/k）：

If user selects 
d
(delete)

如果用户选择
d
（删除）

  • Delete the original source document file
  • Confirm deletion to user: "Original document deleted: [source-document-path]"
  • Note: The document can be reconstructed from shards by concatenating all section files in order
  • 删除原源文档文件
  • 向用户确认删除操作："原文档已删除：[source-document-path]"
  • 注意：可以按顺序拼接所有分片文件，从分片中重建原文档

If user selects 
m
(move)

如果用户选择
m
（移动）

  • Determine default archive location: same directory as source, in an 
    archive
    subfolder
    • Example: 
      /path/to/architecture.md
      --> 
      /path/to/archive/architecture.md
  • Ask: Archive location (
    [y]
    to use default: 
    [default-archive-path]
    , or provide custom path)
  • If user accepts default: use default archive path
  • If user provides custom path: use custom archive path
  • Create archive directory if it does not exist
  • Move original document to archive location
  • Confirm move to user: "Original document moved to: [archive-path]"
  • 确定默认归档位置：与源文件同目录的
    archive
    子文件夹中
    • 示例：
      /path/to/architecture.md
      --> 
      /path/to/archive/architecture.md
  • 询问：归档位置（输入
    [y]
    使用默认路径：
    [default-archive-path]
    ，或提供自定义路径）
  • 如果用户接受默认路径：使用默认归档路径
  • 如果用户提供自定义路径：使用自定义归档路径
  • 如果归档目录不存在则创建该目录
  • 将原文档移动到归档位置
  • 向用户确认移动操作："原文档已移动到：[archive-path]"

If user selects 
k
(keep)

如果用户选择
k
（保留）

  • Display warning to user:
    • Keeping both original and sharded versions is NOT recommended
    • The discover_inputs protocol may load the wrong version
    • Updates to one will not reflect in the other
    • Duplicate content taking up space
    • Consider deleting or archiving the original document
  • Confirm user choice: "Original document kept at: [source-document-path]"
  • 向用户展示警告：
    • 不推荐同时保留原文档和分片版本
    • 输入发现协议可能加载错误版本
    • 对其中一个版本的更新不会同步到另一个版本
    • 重复内容占用存储空间
    • 建议删除或归档原文档
  • 向用户确认选择："原文档已保留在：[source-document-path]"

HALT CONDITIONS

终止条件

  • HALT if npx command fails or produces no output files
  • 如果npx命令执行失败或未生成任何输出文件，立即终止