bmad-shard-pro

Shard Pro

让 Agent 以后能够以低成本、安全地阅读长文档。阅读者可能会搜索，也可能不会；它可能只会看到文件的前 200 行，然后决定还要打开什么。从它看到的内容中，必须能够判断任何事实位于何处。源文档中的内容在处理过程中不得丢失或更改：由你决定在哪里切分以及如何命名，脚本负责切分。用户之后会维护处理结果，因此更新也必须简单。

约定

• {skill-root} 是此技能的文件夹；{project-root} 是最近一个包含 _bmad/ 的文件夹。
• 此技能的脚本是 uv run {skill-root}/scripts/shard_tool.py；运行 --help 或 <command> --help 查看参数。memlog 脚本是 uv run {project-root}/_bmad/scripts/memlog.py；如果没有 _bmad/，请跳过 memlog 写入，并说明一次。
• {doc_folder} 是存放处理结果的文件夹。对于拆分文档，如果输入所在文件夹以其名称命名（prd-x/prd-x.md），则使用该文件夹；否则，在输入文件旁边新建一个以文件主名命名的文件夹；主文件以文件夹命名。对于目录列表，使用文件所在的文件夹。

激活时

• 文档主文件以分片文档说明开头，或者文档包含此技能创建的目录列表（以 `` 开头）：完整阅读 references/update.md 并遵照执行。
• 如果输入是转录稿、聊天导出、邮件往来或一堆会议记录：应将其处理为决策、行动和笔记，而不是分片文档。如果已安装 bmad-ingest 技能，请说明这一点并调用该技能处理；否则告知用户需要先处理。然后停止。
• 如果输入是其他非 Markdown 或纯文本文件（.docx、PDF、HTML）：请用户先使用其常用工具转换为 Markdown，或者请你代为转换，然后继续处理转换后的文件。
• 其他文档：转到“评估”。

评估

对输入运行 outline。推荐一种处理方式，并用一行说明原因：

• 保持原样。 文档足够短，可以完整阅读，或者已有清晰的指引。
• 添加目录列表。 文件保持为单个文件，并在顶部附近添加详细目录列表。这是改动较小的方式；当读者会搜索或按行范围查找、工具或技能需要文档保持为单个文件，或者无法确定文档将如何阅读时，应选择此方式。
• 忠实拆分。 逐字切分源文档，并附上索引。适用于读者会加载整个文件，因此每次只应加载其中一部分的情况，或适用于需要逐块维护文档的情况。不会丢失任何内容，并由脚本检查。

拆分会让之后的每位读者都多一步跳转到索引，因此只有在读者本来需要付出更多成本时才建议拆分。如果用户要求了特定处理方式（“拆分这个”“添加目录”），除非大纲显示这样会降低文档的可读性，否则就推荐该方式；如有此情况，请说明原因。

如果选择“保持原样”，告诉用户原因并停止。选择其他两种方式则继续“规划”。

根据大纲制定计划

根据大纲制定计划，只阅读所需的范围。将长文档整体放入上下文，是一种代价高昂的错误。从建议的切分方案开始，并根据内容需要进行调整：

• 分片约为 3 到 14 KB，按字符数计算，因为行长差异太大，无法按行数衡量。围绕单一主题的短分片，胜过将互不相关的主题合并在一起。
• 切勿在表格、步骤列表或图表中间切分。build 会拒绝在围栏代码块、表格和编号列表中间切分；其他情况请自行留意。
• 根据每个分片涵盖的内容，用 kebab-case 命名。名称切勿以文档类型的前缀开头，否则 prd-* 这样的 glob 会将其作为另一份 PRD 加载。
• 如果标题是单独的标识符（## 3、### C-2），请根据内容命名分片（大纲会显示此类标题下的首行），并在标题中保留标识符。
• 使用源文档自带的索引或编号规则前，先对照正文核实。这些规则往往来自旧版本。
• 将汇总视图（矩阵、登记表、术语表）完整保留，因为需要统计行数的读者需要在同一处查看。较小的汇总视图可以放在同一个分片中。
• 编写每个地图摘要时，应让带着问题的读者能判断该分片是否相关。如果分片内容已被源文档中的后续内容取代，摘要中应说明这一点。
• 如果源文档对同一事项给出了两个值，包含其中一个值的每个分片摘要都应说明这一点，并指出另一个分片。即使源文档声明了优先级规则，也绝不可自行择一。
• 只有当读者会使用地图标题无法直接定位的标识符进行查找时，才设置查找模式，例如数百个需求 ID。

按照 build --help 显示的格式，以 JSON 编写计划。

确认计划

• 用户在场时：展示结果、原因、结果的存放位置以及分片列表（标题和单行摘要），然后等待确认。若要拆分，请说明输入文件将移至 .source/，而分片将成为文档。只有用户确认后才运行构建。
• 如果用户要求不间断运行，或由其他技能在用户不在场时调用此技能：继续执行，并在最后汇报。

构建

运行 build，或使用计划运行 toc 生成目录列表。之后若要更改计划，请编辑计划并再次运行 build；它会从 .source/ 读取源文件并替换旧分片。

然后，在 {doc_folder}/.memlog.md 中记录结果，以及用户作出的每项更改或决定；若已有 memlog，则予以保留：不存在时运行 memlog.py init --workspace {doc_folder}，然后运行 append --type decision|change|event。

检查，然后汇报

对结果运行 check；忠实拆分后使用 --rebuild，并在完成前修复所有失败项。

向用户汇报：

• 结果，以及主文件所在位置；
• 若进行了拆分，说明输入文件现在位于 .source/；
• 在源文档中发现的内容：存在冲突时，说明两个值分别是什么以及各自所在位置；索引错误；疑似错误；
• check 警告拆分后不再有效的链接。分片会保留源文档的原文，因此由用户决定是否修复。

发现的问题应写入报告和 memlog，绝不可写入分片。分片只陈述源文档的内容，读者无法分辨其中哪些是你的判断，哪些是作者的表述。