开年回来连着做了好几个基于 OpenClaw 的自动化任务，发现一个特别有意思的现象：大家问得最多的不是怎么调模型、怎么写 skill，而是"PDF 和网页这种东西，OpenClaw 到底是怎么吃进去的"。这个问题看着基础，但真上手就会发现，PDF 有扫描版、双层版、表格版、双栏版，网页有静态的、有 JS 动态渲染的、有正文藏在"展开阅读全文"后面的——每一类都有一套完全不同的处理逻辑。如果只在 OpenClaw 里丢一句"帮我读一下这个 PDF"，十次有八次拿回来的是一堆乱序文本或者把页眉页脚都当成正文的垃圾内容。
这篇文章我打算把 OpenClaw 处理非结构化数据（重点说 PDF 和网页）的完整解析与预处理流程拆开讲一遍，从源文件识别、格式判定，到文本抽取、版面还原、网页清洗，再到文本切分和元数据注入，尽量把每个步骤背后"为什么这么做"也讲清楚。无论你是拿 OpenClaw 做个人知识库、做自动化简报，还是给它接一个文档问答机器人，这条管线都是绕不开的地基。
1. 先从"为什么这么麻烦"说起：OpenClaw 处理非结构化数据前必须想明白的三件事
1.1 PDF 和网页看起来是文件，实际是不同格式的堆叠
先说一个最容易被忽略的事实：PDF 压根儿不是一种"格式"，它是多种格式的容器。同一个.pdf后缀的文件，里面可能是纯文本流、内嵌字体的文本流、扫描图片、矢量图形、甚至嵌着网页一样的注释层。我在 OpenClaw 里试过一份从银行系统导出的电子回单，PDF 打开后文字能选中，但复制出来全是乱码，原因就是字体子集把字符映射表给改了。这种问题不是靠"换个解析库"就能解决的，必须在预处理阶段就识别出来。
网页也一样。你用requests拿到的 HTML 和浏览器里看到的网页，经常是两码事。页面正文可能是 JS 动态渲染出来的，初始 HTML 里只有个 loading 骨架；也可能是服务端渲染好的，但正文被埋在几十层嵌套的<div>里。OpenClaw 如果直接拿原始 HTML 去喂模型，且不说 token 浪费，光是<script>里的 JS 代码和<style>里的 CSS 规则就够模型喝一壶的。
所以我习惯把非结构化数据的预处理理解成"三个还原"：还原结构、还原顺序、还原语义。结构是标题/段落/表格/列表这些元素的边界，顺序是阅读顺序而不是代码里的 DOM 顺序，语义是每个元素在文档中承担的角色。OpenClaw 的解析流程本质上就是围着这三件事转的。
1.2 OpenClaw 的数据管线到底在解决什么问题
OpenClaw 作为一个智能体框架，它处理文档和传统的 RAG 管道有一个明显区别：它不只是为"检索"服务，更多时候是为"理解后执行动作"服务。比如你让它读一份 PDF 合同然后提取关键条款，或者读一篇文章然后写总结，这时候文本的顺序、表格的完整性、引用位置的保留，都会直接影响最终回复质量。
如果只是做个向量检索，段落顺序乱一点问题不大，反正 top-k 召回只关心相似度。但 OpenClaw 的 skill 经常要把整个文档作为上下文交给大模型，这时候阅读顺序错了，模型读出来的逻辑就全乱了。我实测过一份双栏排版的技术白皮书，用默认参数解析，结果左栏读完跳到右栏，再跳回第二页左栏，模型总结出来的架构图和解说文字完全对不上号。
这是 OpenClaw 数据管线要解决的核心问题：在进入大模型之前，把非结构化原始文件转换成"有结构的、有序的、可引用的"中间表示。这个中间表示可以是 Markdown、JSON、或者带坐标信息的文本块，具体形式取决于下游任务。但无论如何，解析和预处理的目标是一致的——降低大模型的理解成本，同时保留足够多的原始信息用于溯源。
1.3 预处理质量的衡量标准
做解析流程不能凭感觉调参，得有几个硬指标。我在 OpenClaw 里跑完一批文档后，至少会检查这四项：
- 文本召回率：原始文件里的正文有多少被成功抽取出来了。100 页的 PDF 如果只抽出来 60 页的内容，后面做得再花哨也没用。
- 顺序正确率：抽出的文本顺序和人类阅读顺序是否一致。双栏、多栏、页眉页脚穿插都会影响这个指标。
- 结构保真度：标题层级、表格行列、代码块、列表这些结构有没有被拍平成普通文本。
- 清洗彻底度：正文里还残留多少页眉页脚、导航链接、广告噪声。
这四个指标相互独立，而且经常此消彼长。比如你为了提升文本召回率，把 OCR 和文本抽取结果强行合并，结果反而把同一段落的内容复制了两遍，顺序正确率就下来了。所以 OpenClaw 的解析流程里每加一步操作，都要想清楚这一步是在优化哪个指标，会牺牲哪个指标。
2. 源头判定：格式识别、扫描件检测与编码探测
2.1 文件扩展名不可信，要用内容签名说话
OpenClaw 拿到一个输入文件时，第一件事不是直接调解析库，而是做类型嗅探（sniffing）。扩展名.pdf有可能是伪造的，更麻烦的是有些文件是"伪 PDF"——头几百个字节看着像 PDF，实际是 RTF 或者其他格式。
正规做法是读文件的 magic bytes。PDF 的文件头固定是%PDF-（十六进制 25 50 44 46），HTML 则有多种特征，可能是<!DOCTYPE html>、<html>，也可能直接是<meta开头。在 OpenClaw 里我会先用python-magic或者file命令判一遍真实类型，再决定走哪条解析链路。
这里有个容易被忽略的点：文件编码和文件类型是两回事。PDF 文件本身一般用 ASCII 头部，但网页就麻烦了。同一个网页可能是 UTF-8、GBK、GB2312、甚至 Shift-JIS。OpenClaw 解析网页时，如果 HTML 头里没有 charset 声明，必须用 charset-normalizer 或类似的库做内容探测。我踩过最典型的坑是，从国内某个政府网站抓的通知公告，HTTP 响应头里写的text/html; charset=utf-8，但实际正文是 GBK 编码，直接用 UTF-8 解码，整篇文章全是乱码加替换符。
2.2 文本型 PDF 和扫描型 PDF 的区分：后续流程的分岔口
PDF 解析流程里最重要的一次分叉，就是判断它是文本型 PDF 还是扫描型 PDF（也叫图片型 PDF）。文本型 PDF 里包含文本对象和字体映射，可以直接抽取；扫描型 PDF 本质是一堆图片，必须走 OCR。
判断方法很简单：把 PDF 打开后尝试用文本抽取库读取第一页的文本内容，如果提取结果为空或只有极少数能匹配到字体映射的字符，基本可以判定为扫描件。但这个判断不能只看第一页，有些 PDF 是混合的——前 10 页是文字版，后面扫描件插入进来，或者文字层被图片完全遮盖。所以我会逐页统计"有文字的页数"，小于总页数的百分之三十，才整体走 OCR 管线；如果只是少数几页没有文字层，可以单独对这几页做 OCR，然后按页码拼回去。
我在 OpenClaw 里专门写过一个判定函数，核心逻辑很朴素：用 PyMuPDF 读取每一页，计算文本块数量和总字符数。如果连续三页字符数小于 50，就标记为扫描页。这个阈值可以根据文档类型调整，但作为一个通用默认参数，准确率已经够用了。
2.3 网页的动态渲染判定与抓取策略
网页的预处理起点比 PDF 更靠前——你得先拿到 HTML。但"拿到 HTML"这个动作本身就有讲究。OpenClaw 抓取网页前，我会先做一个快速判定：这个页面是服务端渲染（SSR）还是客户端渲染（CSR）。
SSR 页面直接用 HTTP 请求就能拿到正文，CSR 页面拿到的是一个空壳，正文在浏览器里通过 JS 调接口渲染出来的。判定的土办法是看初始 HTML 里的文本量和 script 标签比例：如果<div id="app">或<div id="root">里几乎没内容，大概率是 CSR；如果初始 HTML 里就有大量段落文本，就是 SSR。
CSR 页面必须用无头浏览器。在 OpenClaw 里我一般用 Playwright，它有 Python 和 Node 两套 API，可以直接接管浏览器实例，等页面加载完成后抓取渲染后的 DOM。这里有个很重要的细节：即使是无头浏览器，也有"等待"的问题。有些页面要等 3 秒接口返回，有些要等图片懒加载完成，有些要等滚动事件触发。我通常的做法是等待networkidle事件，再加一个 2 秒的安全缓冲。如果你等的页面里有持续轮询的接口，networkidle可能永远不触发，那就要改用等待某个关键元素出现（比如文章正文的<article>标签）的方式。
3. PDF 解析链路：文本抽取、版面还原与表格结构化
3.1 抽取库选型：pdfplumber 还是 PyMuPDF，OpenClaw 里如何取舍
PDF 解析库的选型直接决定后续所有步骤的上限。在 OpenClaw 里，最常用的两个库是 PyMuPDF（fitz）和 pdfplumber。它们不是二选一的关系，而是各有适用场景。
PyMuPDF 的优势是快。它底层用的是 MuPDF 引擎，解析一个几十页的 PDF 只要几十毫秒到几百毫秒，而且对损坏文件的容错能力很强。我用它做全文档的快速扫描、文本预抽取、页面元数据读取，这些场景追求的是速度和覆盖率。
pdfplumber 的优势是细。它对每个文本块的坐标、字体、大小、颜色都有精确记录，处理表格时可以和每条线的位置对上。它的速度大概是 PyMuPDF 的十分之一，但换来的精度在表格场景完全值得。
我的默认策略是：先用 PyMuPDF 做快速抽取和页面判定，遇到需要精确坐标的场景（表格还原、双栏排序）再切换到 pdfplumber 做局部精处理。这个"粗筛后精读"的混合策略，在 OpenClaw 处理大批量文档时能明显降低整体延迟。
3.2 阅读顺序还原：双栏论文和页眉页脚是怎么被读乱的
PDF 解析除了抽取文字，还要解决一个隐蔽但致命的问题：文字的顺序。PDF 文件内部的对象存储顺序经常和视觉阅读顺序不一致，尤其是双栏排版、复杂页眉页脚、图文混排的文档。
直接按 PDF 内部对象顺序抽取文本的后果是什么？我用一份 IEEE 双栏论文实测过，抽取结果先是把左栏第一行、右栏第一行拼在一起，然后才是左栏第二行。大模型拿到这种文本，读起来就像在看报纸上被剪碎又粘错位的句子，信息量再大也白搭。
解决思路是用坐标排序。pdfplumber 提供了每个词的x0, top, x1, bottom坐标，可以按这些值做分栏和排序。具体做法是：先统计页面所有文本块的 x0 坐标分布，判断出当前页是单栏还是双栏（甚至三栏），然后对每一栏单独按 y 坐标从上到下排序，最后按栏顺序拼接。
这个逻辑看着简单，实际操作中会有很多边界情况。比如有些页面的标题是跨栏居中的，它的 x 坐标横跨左右两栏，直接分栏会把标题切成两半。OpenClaw 里我写的排序函数会先识别"跨栏块"（x0 接近页左边距、x1 接近页右边距的文本块），把它们单独提取出来放到最前面，再对剩下的文本块做分栏排序。
页眉页脚的过滤也是这一步做的。一般的规则是：页眉页脚的 y 坐标固定（顶部、底部），字体大小比正文小，而且很容易在整份文档中反复出现。我会统计每个文本块的坐标和内容，如果同一个文本块在超过 50% 的页面中重复出现，直接过滤掉。这个规则对学术论文和商务报告特别有效，但对排版混乱的网页打印版 PDF 会误伤，需要根据文档类型调整阈值。
3.3 表格结构化：坐标、规则、模型三层兜底
表格是 PDF 解析里最让人头疼的部分。文本型 PDF 的表格视觉上是一格一格的，但抽出来就是一堆散布的文本块，它们之间没有行和列的概念。
OpenClaw 里做表格还原，我按难度分了三条路线：
- 有明确表格线的 PDF：页面里有完整的水平线和垂直线，pdfplumber 可以根据线的坐标推断表格区域，用
extract_table()方法按行列抽取。这是最简单的情况，准确率最高。 - 无表格线但格式对齐的表格：文本块的 x 坐标形成明显的列对齐关系，根据 x0 坐标聚类成列，再根据 y 坐标分行。这种需要一些启发式规则，但实现起来不难。
- 复杂表格：合并单元格、跨行表头、嵌套表格，规则法直接失效。这种情况我会把页面转成图片，交给多模态大模型做表格结构化，输出 Markdown 格式的表格。代价是慢，但这是目前解决复杂表格最可靠的手段。
在 OpenClaw 的实际使用中，我见过太多的 PDF 报告把表格转成图片后嵌进去，文字层完全不存在。这种表格只能走 OCR 或多模态模型，没有捷径。所以我在流程设计里会留一个表格兜底模块，当文本规则法检测到表格区域但抽取结果可疑时，自动把该区域渲染成图片，调用视觉模型识别。
3.4 扫描件的 OCR：图像处理不是可选项
扫描型 PDF 必须走 OCR，而 OCR 之前还有一层图像预处理，这层不做和做了差别极大。
先说选型。Tesseract 是老牌开源 OCR，支持中文，但遇到复杂版面、低分辨率扫描件就力不从心。PaddleOCR 的中文识别效果比 Tesseract 好一个档次，而且自带版面分析模型，能检测文本框的位置和阅读顺序。在 OpenClaw 里我默认用 PaddleOCR，只有在纯英文、高清晰度文档上才切回 Tesseract，因为 Tesseract 的部署更轻量。
图像预处理的具体动作包括：灰度化、二值化、去噪、倾斜矫正、分辨率增强。特别是分辨率，手机拍的照片转成的 PDF，字迹模糊，直接 OCR 的正确率很低。我会先用 OpenCV 做一次放大（比如放大到 300 DPI 对应的像素尺寸）和锐化，再做 OCR。实测下来，这一步能把准确率从 70% 拉到 90% 以上。
还要说的是 OCR 的坐标问题。OCR 识别出的文字自带坐标框，这些坐标可以用来做版面还原和阅读顺序恢复。PaddleOCR 的ocr()接口返回的每个文本框包含位置和内容，可以按框的坐标排序，用类似 3.2 节的算法处理多栏和页眉页脚。也就是说，扫描件走 OCR 后，也能进入和文本型 PDF 相同的版面分析流程，这是 OpenClaw 统一 pdf 处理链路的底层逻辑。
4. 网页抓取与正文清洗：HTML 到干净文本的完整链路
4.1 抓取策略：requests 和 Playwright 怎么配合
网页抓取在 OpenClaw 里通常不是单一方案，而是分层配合。第一层用 requests 直接请求，速度快、资源消耗低，配合自定义的 User-Agent 和 Cookie；如果第一层发现页面是 CSR 渲染或者需要登录才能看到正文，再升级到 Playwright 无头浏览器。
这里有一个很多人忽略的细节：即使用 requests 成功拿到了 SSR 页面的 HTML，页面里往往带着一堆和正文无关的东西，比如viewport、og:title、canonical这些 meta 标签，还有上百行的 script 和 style。如果直接拿整个 HTML 去解析，效率极低。
我的做法是，在 requests 阶段就设置timeout和stream=True，限制下载大小，避免把几十 MB 的 HTML 全部拉下来。然后先用正则或者 BeautifulSoup 粗略判断页面类型，决定是进入正文提取流程还是启动 Playwright。
Playwright 的启动参数也值得调。默认的无头浏览器模式和正常浏览器差别很大，有些网站检测无头模式会返回验证码页面。我一般设置headless=False（用虚拟显示器的环境下），或者至少指定一个真实的 UA 和 viewport。另外page.goto()的wait_until参数我一般设成domcontentloaded，比load快很多，因为load要等待所有图片和脚本加载完，在页面里有懒加载图片时会卡很久。
4.2 正文提取：trafilatura 和 Readability 的原理对比
拿到 HTML 后，正文提取是核心步骤。这里推荐的工具是 trafilatura，它专门用于从网页中提取正文，支持多语言，内部实现了一套结构分析和打分逻辑：计算出每个节点包含的文本密度、链接密度、标点符号分布，然后用启发式规则判断哪些节点是正文，哪些是导航、广告、评论。
Readability 是另一个常见选择，Mozilla 出品的算法，最早用在 Firefox 阅读模式上。它的思路是基于 DOM 树的文本密度打分，找到最可能的正文容器，然后递归过滤噪声节点。两者对比的话，trafilatura 在学术场景、带注释的文本、导航复杂的页面表现更好；Readability 对简单文章页效果也不错，但在某些网站的特定结构下会失效。
在 OpenClaw 里我把它们做成可切换的后端：默认 trafilatura，遇到抽取结果为空或字数低于阈值的情况，自动用 Readability 再试一次。两条路都失败，才考虑上 Playwright 等动态渲染后重新走一遍。
不管用哪个工具，抽取出来的正文最好统一转成 Markdown 格式。Markdown 保留了标题层级、列表、链接、加粗这些轻量结构，不会像 HTML 那样有一大堆标签，但也不会像纯文本那样丢失所有格式。OpenClaw 的 skill 在消费网页内容时，Markdown 是最好用的中间格式。
4.3 结构化信息的保留：标题、日期、作者和链接不能丢
正文抽取只是第一步，网页里还有大量"副产品"信息，在 OpenClaw 的很多任务里反而很有价值。
比如文章的发布时间。你让它整理"上个月行业新闻"，光有正文没有日期，模型就分不清时间范围。发布日期一般在 meta 标签article:published_time里，或者藏在页面的 time 标签里。作者信息通常在authormeta 标签或者页面底部的署名区域。这些信息在抽取阶段就要单独提取并保存，不能混在正文里让模型自己猜。
链接的处理也是一个矛盾点。一方面，导航链接、广告链接全是噪声，必须过滤；另一方面，正文里的引用链接、脚注链接是溯源的重要依据。我的做法是：保留正文范围内 Markdown 链接的 URL 和锚文本，把它们放进元数据字段；页眉页脚、侧边栏区域的链接全部丢弃。
还有一个值得做的事：URL 规范化。同一篇文章可能在不同路径下有多个 URL（带utm_source参数的、带#comments锚点的、http和https混用的）。OpenClaw 的记忆和引用机制里，URL 是去重和溯源的关键字段，所以我会在进入管线前用urllib对 URL 做一次标准化，去掉无意义的查询参数和锚点。
4.4 清洗规则的边界：做太多和做太少都危险
网页正文清洗容易走两个极端。一个极端是清洗不足，返回的内容还带着"点击展开""相关推荐""上一篇：XXX"这些尾巴；另一个极端是清洗过度，用一堆正则把正文里的代码块、列表符号、特殊字符全部误删。我见过有人的清洗规则把 Python 代码里的#注释当成标题符号给处理掉了，整段代码面目全非。
我的清洗原则是：规则只处理明显的非正文噪声，对正文内部的格式保持敬畏。具体来说，保留的规则包括：
- 删除空行和多余空白字符，但保留段落间的空行
- 保留代码块（用 Markdown 围栏包裹），但移除代码块里的行号
- 保留有序列表和无序列表的符号结构，但去掉只含一个字符的列表项
- 对全角/半角做归一化，但不对内容做语义层面的改写
清洗步骤结束后，我会做一次"内容完整性检查"：对比清洗前后的字符数差异，如果清洗率超过 70%，说明清洗规则可能过于激进，需要人工抽查。这个阈值在 OpenClaw 里可以配置，我的默认值是 0.7，超过这个值就触发警告。
5. 切分、元数据与内容组装：给大模型投喂前的最后一步
5.1 文本切分策略：固定长度切分在智能体场景里为什么不够用
解析 PDF 和网页得到的文本，最终要进入大模型的上下文窗口。OpenClaw 的 skill 需要决定这些文本怎么切分、怎么组织。
常规 RAG 里的做法是固定 token 数切分（比如每段 512 token，加 128 token 重叠），这种策略在纯检索场景够用，但 OpenClaw 面临的场景更复杂。它可能要把一份合同的完整条款作为上下文让模型审查，这时候如果固定长度切分把"甲方义务"切开成两半，模型的判断就会出偏差。
我用的切分策略是"结构感知切分"：优先以文档本身的标题、段落、表格为单位切分，只有超过模型窗口限制时才做二次切分。具体实现不复杂——解析阶段已经拿到了文本块的层级信息，Markdown 的#、##、###就是天然的切分边界。每个切分块的主题由最近的标题决定，这个信息直接进入元数据，供后续引用。
固定长度切分不是完全不用。当文档里出现超大段落（比如一个表格转成的 Markdown 有几十行）时，结构感知切分会造出一个超过上下文限制的块。这时候我会对该块单独做固定长度切分，并在每个子块里重复注入父级标题信息，保证即使切碎了，每一片都知道自己属于哪个章节。
5.2 元数据注入：来源、页码、URL、时间，一个都不能少
预处理流程的最后一个关键步骤是元数据注入。这一步在 OpenClaw 中的数据链路里经常被忽略，但我认为是决定系统可用性的核心。
元数据至少应该包含：来源类型（PDF/网页）、来源标识（文件路径或 URL）、文件标题、抽取时间、页码或章节位置、语言、以及内容块的层级路径。这些字段的作用在 AI Agent 场景里非常明确——当模型引用某个段落做出回答时，OpenClaw 需要知道这段内容来自哪个文件哪一页，才能给出带引用的回复。
我在项目里的做法是：解析阶段就把这些字段写进每个文本块的 header 区域，格式用 JSON 或者 YAML。比如一个从 PDF 第 12 页抽取的文本块，它的元数据长这样：
{ "source_type": "pdf", "source_path": "/data/reports/2025-q1.pdf", "page": 12, "title": "2025年第一季度经营分析", "chapter": "3.2 财务指标解读", "extracted_at": "2025-02-16T10:30:00+08:00", "language": "zh-CN" }这些元数据在后续阶段有巨大价值。如果 OpenClaw 要做去重，可以按source_path + page + chapter做哈希；如果要过滤过期文档，可以按extracted_at排序；如果要给模型提供引用来源，直接把source_path和page拼进提示词即可。没有元数据的解析结果就像一本没有目录和页码的书，内容再详实也没法定位。
5.3 上下文组装：控制 token 量，别把整本书塞进提示词
预处理完成后的上下文组装，是容易被忽略的一步。文件解析完、切分完、元数据也标好了，但 OpenClaw 调用大模型时不能把所有的块都塞进去，上下文窗口有限，而且内容太多会稀释模型对关键信息的注意力。
我一般建议采用"分层浏览"的组装方式。第一轮先给模型文档的标题、章节列表、每个章节的长度和摘要，让模型判断哪些章节和当前任务相关；模型选定章节后，第二轮再注入对应章节的详细内容。这个策略对长文档特别有效，实测能把 token 消耗降低 60% 以上，同时回答质量不降反升。
如果确实需要一次性提交大量文本，那么要给文本块加上足够清楚的分隔符和编号。比如用COMMENT [1/15]这种格式标记每个块的序号，模型能更清楚地感知上下文边界。我在 OpenClaw 的 skill 里就保留了一个long_context模板，专门处理这种"全文投喂"场景，实测效果比直接拼接文本块要稳定很多。
6. 实测高频问题与调优记录：OpenClaw 跑非结构化数据的排错手记
6.1 双栏论文读成一行的问题
症状：学术 PDF 解析出来后，正文像被剪碎的报纸，两栏文字交错排在一起。排查链路：先确认文本抽取阶段用的是哪个库，如果输出顺序是乱序，把 pdfplumber 的坐标输出打出来，看每个文本块的 x0 坐标，会发现左栏的 x0 是 50~250，右栏是 300~550。这时候问题定位在"没做分栏排序"。
解法：写一个坐标排序函数，统计页面文本块的 x0 中位数，如果文本块 x0 明显分成两组，就按两栏分别排序。注意处理标题跨栏的情况，我一般把 x0 < 50 且 x1 > 550 的块单独提出来。这个修复几乎对所有双栏论文都有效，但对真正三栏排版（部分会议论文）需要扩展为三分组。
6.2 网页正文拿到一半，全文被"展开阅读全文"截断
症状：抓取一个新闻页面，正文只到第 5 段就停止了，后面是"点击展开阅读全文"按钮的文字。排查链路：开始以为是 requests 没带登录 Cookie，检查请求头后发现是 SSR 页面，初始 HTML 只响应了前几段，剩余内容要通过点击按钮触发 JS 请求。
解法：用 Playwright 重新抓取，点击"展开阅读全文"按钮后再提取正文。这里可以用page.click()定位按钮文字，等待新的 DOM 节点出现后，再走正文提取流程。更通用一点，有些页面需要模拟滚动到底部才能触发懒加载，我会用page.mouse.wheel()滚动几次，确保所有内容都渲染出来。
6.3 PDF 表格抽取后行列全乱
症状：一份带边框的财务报表，用 pdfplumber 抽取后表格行列错位，有些行缺失，有些列错算。排查链路：第一反应是库的extract_table()参数问题，但调整vertical_strategy和horizontal_strategy后仍然不稳。最后去看页面可视化，发现这个 PDF 的表格线不是标准的连续直线，而是由很多小线段拼接的虚线风格。
解法：这种情况下，先用 OpenCV 做一次"表格线补全"，把断开的线段连接起来，再让 pdfplumber 提取。代价是图像处理环节比较耗时，但对这种"机械制图风格"的表格效果极佳。如果补线也解决不了，就改用多模态模型直接识别表格区域图片。
6.4 乱码：UTF-8、GBK 和 BOM 的三国演义
症状：网页解析结果中文全是锟斤拷或用�替换。排查链路：先看 HTML 头的 charset 声明，再看 HTTP 响应头的 Content-Type。如果两者不一致，以 HTTP 头为准的解析策略就会出错。另外还有一种情况是 HTML 内容里混着 BOM 头，解码时 BOM 变成了\ufeff，像一堆不可见字符留在文本开头。
解法：用charset-normalizer做自动编码检测，不要完全信任声明。对 BOM 字符，统一在清洗阶段用正则或strip()去除，因为\ufeff在后面对文本切分和哈希计算都会造成干扰。
6.5 中文标点被吞：PDF 字体编码的地狱
症状：从某个政府公报 PDF 抽取的文本，逗号和句号全部消失，或者变成空格。排查链路：这不是解析库的 bug，而是 PDF 内部字体映射问题。部分 PDF 生成工具（尤其国产办公软件）做字体子集化时，把中文标点映射到了不常用的 Unicode 私有区。PyMuPDF 抽取时按错误映射输出，标点就成了乱码或空白。
解法：在清洗阶段用规则补齐——如果一句话末尾没有标点且下一句首字母大写（或中文语境下是明显的新句子），自动补上句号。这个方案不够优雅，但实际问题中很有效。另一个规避方法是强制用 pdfplumber 的"文本重组"模式，通过字体信息重新映射字符，虽然慢一些，但对中文标点的保护更好。
6.6 元数据丢失导致引用无法溯源
症状：OpenClaw 回答问题时引用了一个 PDF 里的内容，但答案里没带来源文件路径和页码，用户完全无法验证。排查链路：查看解析流程，发现文本块在切分后没有继承元数据，切分器只返回了纯文本，把页码、标题这些信息丢在了后面。
解法：在切分器设计时把元数据作为"不可分割的附加字段"和文本块绑定。每个文本块本质是一个{ content, metadata }的数据结构，而不是一个字符串。切分、清洗、嵌入、检索全程携带这个结构，只在最终调用模型的地方把 metadata 格式化成提示词的一部分。这个设计层面的改动，比后面再想办法补录要靠谱得多。
7. 写给自己和后来者的几条经验总结
OpenClaw 的非结构化数据解析流程做到今天，我的核心感受是：这层管线没有一劳永逸的方案，而是需要持续根据文件类型、任务场景调整参数和优先级。你面对的 PDF 可能是政府公报、学术论文、财务扫描件，面对的网页可能是新闻门户、个人博客、动态后台，每一种都需要在解析链路里微调几个开关。但整体框架是恒定的：源识别、格式判定、文本抽取、顺序还原、清洗、切分、元数据标记、上下文组装，按这个流程走下去，就不会有大的方向性错误。
最后分享一个我踩过很多次才明白的教训：不要试图一步到位做成一个"通用解析器"。更务实的做法是做一个带日志和中间产物输出的流水线，让每一步的输入输出都可以单独检验。这样出了问题只需要看中间产物，一眼就能定位是抽取环节还是清洗环节的锅。OpenClaw 的 skill 机制很适合这个设计——每个解析步骤都可以拆成一个独立的 skill，互相之间通过标准数据格式通信，调试的时候单独调用某一步，非常方便。
