bmad-shard-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shard Pro

You make a long document cheap and safe for an agent to read later. That reader may or may not search, and may see only the first 200 lines of a file before deciding what else to open. From what it sees there, it must be able to tell where any fact lives. Nothing in the source may be lost or changed on the way: you choose where to cut and what to call things, and the script does the cutting. The user maintains the result afterwards, so it must also be easy to update.

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

Conventions

约定

```
{skill-root}
```
is this skill's folder;
```
{project-root}
```
is the nearest folder containing
```
_bmad/
```
.
This skill's script is
```
uv run {skill-root}/scripts/shard_tool.py
```
; run it with
```
--help
```
, or
```
<command> --help
```
, for arguments. The memlog script is
```
uv run {project-root}/_bmad/scripts/memlog.py
```
; without
```
_bmad/
```
, skip memlog writes and say so once.
```
{doc_folder}
```
is the folder that holds the result. For a split, it is the input's own folder when that folder is named after it (
```
prd-x/prd-x.md
```
), otherwise a new folder beside the input, named after its stem; the main file is named after the folder. For a contents list, it is the file's own folder.

```
{skill-root}
```
是此 skill 的文件夹；
```
{project-root}
```
是包含
```
_bmad/
```
的最近文件夹。
此 skill 的脚本是
```
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
```
），则使用该文件夹；否则在输入文件旁新建一个文件夹，以去掉扩展名的文件名命名；主文件以该文件夹命名。对于目录列表，使用文件自身所在的文件夹。

On activation

激活时

The document's main file opens with the sharded-document note, or the document has a contents list this skill made (it starts with
```

```
): read
```
references/update.md
```
fully and follow it.
A transcript, chat export, email thread or pile of meeting notes: this is input to process into decisions, actions and notes, not a document to shard. Say so and invoke the
```
bmad-ingest
```
skill on it when it is installed; otherwise tell the user it needs processing first. Then stop.
Any other file that is not markdown or plain text (.docx, PDF, HTML): ask the user to convert it to markdown first, with a tool they use or by asking you to, then go on from the converted file.
Any other document: go to Assess.

如果文档的主文件以分片文档提示开头，或文档包含由此 skill 创建的目录列表（开头为
```

```
），则完整阅读
```
references/update.md
```
并遵循其中的说明。
转录稿、聊天导出、电子邮件线程或一堆会议记录：这是需要整理为决策、行动项和笔记的输入，而不是待分片的文档。向用户说明这一点；如果已安装
```
bmad-ingest
```
skill，则调用它进行处理；否则告知用户需要先进行处理。随后停止。
任何其他非 Markdown 或纯文本的文件（.docx、PDF、HTML）：请用户先使用其工具转换为 Markdown，或请助手代为转换，然后从转换后的文件继续。
任何其他文档：进入评估阶段。

Assess

评估

Run

outline

on the input. Recommend one outcome with one line on why:

Leave it as it is. It is short enough to read whole, or already well signposted.
Contents list. The file stays one file and gains a detailed contents list near the top. It is the smaller change, and the one to choose when readers search or follow line ranges, when tools or skills expect the document as one file, or when you cannot tell how it will be read.
Faithful split. The source is cut word for word into shards with a map. Choose it when readers load whole files, so each one should load only a part, or when the document will be maintained piece by piece. It loses nothing and is checked by script.

Splitting costs every later reader a hop through the map, so recommend it only when a reader would otherwise pay more. When the user asked for a particular outcome ("shard this", "add a table of contents"), recommend that one unless the outline shows it would make the document worse to read, and then say why.

For Leave it as it is, tell the user why and stop. The other two go on to Plan.

在输入文件上运行

outline

。推荐一种处理结果，并用一行说明理由：

保持原样。 文档足够短，可以整篇阅读，或者已经有清晰的结构指引。
目录列表。 文件仍保持为单个文件，并在顶部附近添加详细目录列表。这是改动较小的方案；当读者会搜索或按行范围查看、工具或 skill 预期文档为单个文件，或无法确定阅读方式时，应选择此方案。
忠实分片。 将源文档逐字切分为多个分片，并生成映射。当读者会加载完整文件、因此每个文件只应加载一部分时，或文档将逐块维护时，选择此方案。该方案不会丢失任何内容，并由脚本进行检查。

分片会让之后每位读者都需要通过映射跳转，因此只有在读者原本会承担更高成本时，才推荐分片。当用户明确要求某种结果（“分片此文档”“添加目录”）时，推荐该方案；除非提纲显示该方案会让文档更难阅读，此时说明原因。

对于保持原样，向用户说明原因并停止。另外两种方案进入计划阶段。

Plan from the outline

根据提纲制定计划

Plan from the outline and read only the ranges you need. Holding a long document whole in your context is the expensive mistake. Start from the proposed cut and change it where the content asks:

Shards run about 3 to 14 KB, measured in characters, because line lengths vary too much to measure by lines. A shorter shard on one subject beats a merged one that joins unrelated subjects.
Never cut inside a table, a step list or a diagram.
```
build
```
refuses cuts inside fenced blocks, tables and numbered lists; watch for the rest yourself.
Name each shard from what it covers, in kebab-case. Never start a name with the document type's prefix, because a
```
prd-*
```
glob would load it as another PRD.
When a heading is a bare identifier (
```
## 3
```
,
```
### C-2
```
), name the shard from its content (the outline shows the first line under each such heading) and keep the identifier in the title.
Before you use the source's own index or numbering rules, check them against the body. They are often from an older edition.
Keep an aggregate view (a matrix, a register, a glossary) whole, because a reader counting rows needs it in one place. Small ones may share a shard.
Write each map summary so a reader with a question can tell this is the shard. When a shard's content is later superseded in the source, its summary says so.
When the source states two values for one thing, the summary of each shard holding one says so and names the other shard. Never pick one, even where the source declares a precedence rule.
Set a lookup pattern only when readers arrive with identifiers the map titles do not already resolve, such as hundreds of requirement IDs.

Write the plan as JSON in the shape

build --help

shows.

根据提纲制定计划，只阅读所需的范围。将整篇长文档保留在上下文中是代价高昂的错误。从建议的切分位置入手，并根据内容需要调整：

每个分片约为 3 至 14 KB，以字符数衡量，因为行长度差异过大，不适合按行数衡量。围绕单一主题的较短分片，优于把不相关主题合并在一起的分片。
绝不要在表格、步骤列表或图示内部切分。
```
build
```
会拒绝在围栏代码块、表格和编号列表内部切分；其他结构则需自行留意。
根据每个分片涵盖的内容，使用 kebab-case 命名。绝不要让名称以文档类型的前缀开头，因为
```
prd-*
```
glob 会将其作为另一个 PRD 加载。
当标题只是裸标识符（
```
## 3
```
、
```
### C-2
```
）时，根据其内容为分片命名（提纲会显示每个此类标题下的第一行），并在标题中保留该标识符。
使用源文档自身的索引或编号规则前，先与正文核对。它们通常来自旧版本。
保持聚合视图（矩阵、登记表、术语表）完整，因为需要统计行数的读者必须在一个地方查看它。较小的聚合视图可以共用一个分片。
编写每条映射摘要，使带着问题的读者能够判断该分片是否包含答案。当分片内容之后被源文档中的新内容取代时，其摘要要注明这一点。
当源文档对同一事物给出两个值时，每个包含其中一个值的分片摘要都应指出存在冲突，并注明另一个分片的位置。即使源文档声明了优先级规则，也不要自行选择其中一个。
仅当读者会使用映射标题无法直接解析的标识符查找内容时（例如数百个需求 ID），才设置查找模式。

按照

build --help

所示的格式，将计划编写为 JSON。

Agree the plan

确认计划

A user is present: show the outcome, why, where the result will go, and the shard list (titles and one-line summaries), then wait. For a split, say that the input moves into
```
.source/
```
and the shards become the document. Build only once they agree.
The user asked you to run without stopping, or another skill invoked this one with no user present: go on, and report at the end.

如果用户在场：展示处理结果、选择理由、结果存放位置以及分片列表（标题和一句话摘要），然后等待。对于分片，说明输入文件将移入
```
.source/
```
，各分片将成为文档主体。只有用户同意后才执行构建。
如果用户要求不中断地运行，或另一个 skill 在无用户在场时调用此 skill，则继续执行，并在结束时报告。

Build

构建

Run

build

, or

toc

with the plan for a contents list. To change the plan afterwards, edit it and run

build

again; it reads the source from

.source/

and replaces the old shards.

Then record the outcome and each change or decision the user made in

{doc_folder}/.memlog.md

, keeping any memlog already there:

memlog.py init --workspace {doc_folder}

when none exists, then

append --type decision|change|event

运行

build

；如果要生成目录列表，则使用该计划运行

toc

。之后如需修改计划，请编辑计划并再次运行

build

；该命令会从

.source/

读取源文档，并替换旧分片。

然后在

{doc_folder}/.memlog.md

中记录处理结果以及用户做出的每项更改或决定，并保留已有的 memlog：如果尚不存在，运行

memlog.py init --workspace {doc_folder}

，然后运行

append --type decision|change|event

。

Check, then report

检查并报告

Run

check

on the result, with

--rebuild

after a faithful split, and fix every failure before you finish.

Report to the user:

the outcome, and where the main file is;
for a split, that the input now sits in
```
.source/
```
;
what you found in the source: conflicts with both values and where each sits, index errors, suspected errors;
links
```
check
```
warns no longer resolve after the split. Shards keep the source's words, so the user decides whether to fix them.

Findings go in the report and the memlog, never into shards. A shard says what the source says, and a reader cannot tell your judgement from the author's.

对结果运行

check

；完成忠实分片后还要加上

--rebuild

，并在结束前修复所有失败项。

向用户报告：

处理结果以及主文件的位置；
对于分片，说明输入文件现在位于
```
.source/
```
；
在源文档中的发现：存在两个冲突值的事项及其各自所在位置、索引错误、疑似错误；
```
check
```
警告在分片后无法再解析的链接。分片保留源文档的原文，因此由用户决定是否修复。

发现的问题应写入报告和 memlog，绝不能写入分片。分片只陈述源文档所说的内容，读者不能把你的判断与作者的原意混淆。