bmad-distillator

Distillator：文档蒸馏引擎

概述

本技能可从任意一组源文档中生成高度压缩、token 高效的文档（蒸馏物）。蒸馏物保留源文档中的每项事实、决策、约束和关系，同时剥离人类需要而大模型不需要的全部冗余。请以信息抽取与压缩专家的身份执行。输出是一份单一的高密度文档（或按语义拆分的一组文档），下游大模型工作流可将其作为唯一上下文输入使用，且不丢失信息。

这是压缩任务，不是摘要任务。摘要有损。蒸馏物是为大模型消费而优化的无损压缩。

激活时

1. 校验输入。 调用方必须提供：

   • source_documents（必填）—— 一个或多个要蒸馏的文件路径、文件夹路径或 glob 模式
   • downstream_consumer（可选）—— 消费此蒸馏物的工作流/Agent（例如 "PRD creation"、"architecture design"）。提供时，用它判断信号与噪声。省略时，保留一切。
   • token_budget（可选）—— 近似目标大小。提供时，若蒸馏物将超出该值，则触发语义拆分。
   • output_path（可选）—— 保存位置。省略时，保存到主源文档旁边，并加上 -distillate.md 后缀。
   • --validate（标志）—— 生成蒸馏物后运行往返重建测试。

2. 路由 —— 进入阶段 1。

阶段

#	阶段	目的
1	分析	运行分析脚本，确定路由和拆分
2	压缩	启动压缩器 Agent，生成蒸馏物
3	校验与输出	完整性检查、格式检查、保存输出
4	往返验证	（仅 --validate）重建并与原始文档进行 diff

阶段 1：分析

运行 scripts/analyze_sources.py --help，然后带源路径运行它。使用其路由建议和分组输出来驱动阶段 2。不要自行阅读源文档。

阶段 2：压缩

单路模式（routing = "single"，≤3 个文件，≤15K 估算 token）：

使用 agents/distillate-compressor.md 启动一个子 Agent，传入所有源文件路径。

扇出模式（routing = "fan-out"）：

1. 根据分析输出，为每个分组启动一个压缩器子 Agent。每个压缩器只接收其分组的文件路径，并生成一份中间蒸馏物。

2. 所有压缩器返回后，使用 agents/distillate-compressor.md 启动一个最终的合并压缩器子 Agent。将中间蒸馏物的内容作为输入传给它（不是原始文件）。其职责是跨分组去重、按主题重新分组并进行最终压缩。

3. 清理中间蒸馏物内容（它只存在于内存中，不会保存到磁盘）。

优雅降级： 如果无法启动子 Agent，则阅读源文档，并使用 agents/distillate-compressor.md 中的相同说明直接执行压缩工作。对于扇出模式，按顺序处理各分组，然后合并。

压缩器返回结构化 JSON 结果，其中包含蒸馏物内容、源标题、命名实体和 token 估算。

阶段 3：验证与输出

在压缩器（或合并压缩器）返回后：

1. 完整性检查。 使用压缩器返回的标题和命名实体列表，验证每一项都出现在提炼内容中。如果发现缺失，将其送回压缩器进行针对性修复，而非完整重新压缩。最多限制 2 次修复。

2. 格式检查。 验证输出符合提炼格式规则：

   • 无散文段落（仅项目符号）
   • 无装饰性格式
   • 无重复信息
   • 每个项目符号均自包含
   • 主题用 ## 标题清晰划分

3. 确定输出格式。 使用阶段 1 的拆分预测和实际提炼大小：

   单一提炼（≤~5,000 token 或未超出 token_budget）：

   保存为带 frontmatter 的单一文件：

   ---
   type: bmad-distillate
   sources:
     - "{relative path to source file 1}"
     - "{relative path to source file 2}"
   downstream_consumer: "{consumer or 'general'}"
   created: "{date}"
   token_estimate: {approximate token count}
   parts: 1
   ---
   

   拆分提炼（>~5,000 token，或 token_budget 要求）：

   创建文件夹 {base-name}-distillate/，包含：

   {base-name}-distillate/
   ├── _index.md           # Orientation, cross-cutting items, section manifest
   ├── 01-{topic-slug}.md  # Self-contained section
   ├── 02-{topic-slug}.md
   └── 03-{topic-slug}.md
   

   _index.md 包含：

   • 带来源的 Frontmatter（从提炼文件夹到原文件的相对路径）
   • 3-5 条项目符号定位（提炼了什么、来自什么）
   • 章节清单：每个章节的文件名 + 1 行描述
   • 跨多个章节的横切项

   每个章节文件自包含——可独立加载。包含 1 行上下文标题："本节涵盖 [主题]。第 N 部分，共 M 部分。"

   Frontmatter 中的来源路径必须相对于提炼文件的位置。

4. 测量提炼。 对最终提炼文件运行 scripts/analyze_sources.py 以获得准确的输出 token 计数。使用此分析中的 total_estimated_tokens 作为 distillate_total_tokens。

5. 报告结果。 始终返回结构化 JSON 输出：

   {
     "status": "complete",
     "distillate": "{path or folder path}",
     "section_distillates": ["{path1}", "{path2}"] or null,
     "source_total_tokens": N,
     "distillate_total_tokens": N,
     "compression_ratio": "X:1",
     "source_documents": ["{path1}", "{path2}"],
     "completeness_check": "pass" or "pass_with_additions"
   }
   

   其中 source_total_tokens 来自阶段 1 分析，distillate_total_tokens 来自步骤 4。compression_ratio 为 source_total_tokens / distillate_total_tokens，格式为 "X:1"（例如 "3.2:1"）。

6. 如果设置了 --validate 标志，则进入阶段 4。否则，完成。

阶段 4：往返验证（仅 --validate）

此阶段通过仅从提炼内容重建源文档来证明提炼是无损的。用于信息丢失不可接受的关键文档，或作为高风险下游工作流的质量门。不用于常规用途——它会显著增加 token 成本。

1. 生成重建器 Agent，使用 agents/round-trip-reconstructor.md。仅向其传递提炼文件路径（或拆分提炼的 _index.md 路径）——它不得访问原始源文档。

   对于拆分提炼，为每个章节并行生成一个重建器。每个接收其章节文件加上 _index.md 以获取横切上下文。

   优雅降级： 如果子 Agent 生成不可用，此阶段无法由主 Agent 执行（它已经看过原文件）。报告往返验证需要子 Agent 支持并跳过。

2. 接收重建。 重建器返回保存在提炼文件相邻位置的重建文件路径。

3. 执行语义差异。 读取原始源文档和重建内容。对于原文件的每个章节，评估：

   • 重建中是否存在核心信息？
   • 具体细节是否保留（数字、名称、决策）？
   • 关系和理由是否完好？
   • 重建是否添加了原文件中没有的内容？（表明是填补空白的幻觉）

4. 生成验证报告，保存在提炼文件相邻位置为 -validation-report.md：

   ---
   type: distillate-validation
   distillate: "{distillate path}"
   sources: ["{source paths}"]
   created: "{date}"
   ---
   
   ## Validation Summary
   - Status: PASS | PASS_WITH_WARNINGS | FAIL
   - Information preserved: {percentage estimate}
   - Gaps found: {count}
   - Hallucinations detected: {count}
   
   ## Gaps (information in originals but missing from reconstruction)
   - {gap description} — Source: {which original}, Section: {where}
   
   ## Hallucinations (information in reconstruction not traceable to originals)
   - {hallucination description} — appears to fill gap in: {section}
   
   ## Possible Gap Markers (flagged by reconstructor)
   - {marker description}
   

5. 如果发现缺失，提议对提炼内容运行针对性修复——添加缺失信息而不进行完整重新压缩。最多限制 2 次修复。

6. 清理——生成报告后删除临时重建文件。