第 2 课

捕获并提取

提取操作面对的是"已知来源"，不是事后路径里恰好有什么就提什么。 程序只打开来源一次，把字节抓下来，再把同一份私有快照交给 Docling 和 MarkItDown。

学完这一课

你要搞懂：为什么先捕获再提取、为什么项目保留两个提取视图、 后续阶段为什么拿 DoclingDocument 当工作文档。

来源得先稳住

文件名只是个位置。你读它的时候，别的进程可能已经把它换掉、改名 或者改内容了。所以观察先做一件事：读一个常规本地文件，把字节抓下来。 记录里存好来源标识——文件名、媒体类型、大小、SHA-256。

这不能证明文件是谁写的，也不能证明它可信。但有个关键好处：后续阶段 引用的是"捕获下来的那一份"，而不是静悄悄地去读路径下可能已经不一样 的新文件。

比一比，别评胜负

两个提取器，各产出有用的视图：

• 无损的 DoclingDocument JSON —— 规范的工作表示。
• Docling Markdown —— 这份规范文档的可读版本。
• MarkItDown Markdown —— 独立的提取视图。

比较记录的是可测量的差异。差异是线索，不是分数，更不证明谁好谁差。

一份捕获来源
  -> Docling -> 规范 DoclingDocument -> 可读 Markdown
  -> MarkItDown -> 独立 Markdown

规范的 DoclingDocument 关键在哪？诊断和受控修订要的是稳定的文档引用， 不是哪个 Markdown 看起来更顺眼。Markdown 也有用——学习者读起来方便。 独立的 MarkItDown 也有用——它告诉你，换一条提取路径，从同一份来源 出来的是什么。

比较时该问什么

别问"哪个提取器赢了？"问这些：

• 两边都给出来可用结果了吗？
• 归一化之后，是一样的还是有差？
• 有差的话，在用任一结果之前，该先看什么？
• 哪个视图才是诊断和修订的规范输入？

输出一样，不等于两个视图都完整、都正确。输出不一样，也不等于谁错了。 比较是催你去看，不是替你判。

看懂观察记录

观察记录里存了来源标识、提取器结果、产物哈希和比较数据。它不诊断， 也不改文档。之后可以再验证一次，确认记录里的字节和关系还对得上。

验证只检查历史完整性，不证明作者是谁、内容是真是假，也不证明同路径 下的当前文件就是历史来源。

初学不用面面俱到。按这个顺序读：

1. 确认捕获的是哪个来源。
2. 看每个提取器有没有给出来可用结果。
3. 找到规范的 DoclingDocument 交接点。
4. 把比较状态当证据读，别当分数。
5. 需要看具体输出时，再打开产物。

这个顺序能避开一个常见坑：还不知道回答什么问题，就一头扎进大 JSON 文件里。

在工作台里试试

点添加文档，选引导示例 policy-memo.md。走完观察。在观察阶段找出： 来源元数据、两个提取视图、规范表示的交接点。

这个示例就是一次普普通通、没有异常的观察。重要的不是"通过了"， 而是工作台为一个具体来源留下了可查的证据。

再添加 whitespace-cleanup.md。观察目的相同，但后面会引出诊断发现项。 注意：观察这一步本身，不会预判也不会执行后面的修改。

常见误解

提取输出一样还是不一样，不等于谁对谁错。它只说明两条路径从同一来源 分别产出了什么。

记住

观察的意义在于：定了"我们检查的就是这份文档"。它保留来源标识，分开 保存各提取输出，指定一份规范文档供后面用。不评判，也不修改。

下一课：检查并诊断。