开年回来连着做了好几个基于 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 46HTML 则有多种特征可能是!DOCTYPE html、html也可能直接是meta开头。在 OpenClaw 里我会先用python-magic或者file命令判一遍真实类型再决定走哪条解析链路。这里有个容易被忽略的点文件编码和文件类型是两回事。PDF 文件本身一般用 ASCII 头部但网页就麻烦了。同一个网页可能是 UTF-8、GBK、GB2312、甚至 Shift-JIS。OpenClaw 解析网页时如果 HTML 头里没有 charset 声明必须用 charset-normalizer 或类似的库做内容探测。我踩过最典型的坑是从国内某个政府网站抓的通知公告HTTP 响应头里写的text/html; charsetutf-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 idapp或div idroot里几乎没内容大概率是 CSR如果初始 HTML 里就有大量段落文本就是 SSR。CSR 页面必须用无头浏览器。在 OpenClaw 里我一般用 Playwright它有 Python 和 Node 两套 API可以直接接管浏览器实例等页面加载完成后抓取渲染后的 DOM。这里有个很重要的细节即使是无头浏览器也有等待的问题。有些页面要等 3 秒接口返回有些要等图片懒加载完成有些要等滚动事件触发。我通常的做法是等待networkidle事件再加一个 2 秒的安全缓冲。如果你等的页面里有持续轮询的接口networkidle可能永远不触发那就要改用等待某个关键元素出现比如文章正文的article标签的方式。3. PDF 解析链路文本抽取、版面还原与表格结构化3.1 抽取库选型pdfplumber 还是 PyMuPDFOpenClaw 里如何取舍PDF 解析库的选型直接决定后续所有步骤的上限。在 OpenClaw 里最常用的两个库是 PyMuPDFfitz和 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和streamTrue限制下载大小避免把几十 MB 的 HTML 全部拉下来。然后先用正则或者 BeautifulSoup 粗略判断页面类型决定是进入正文提取流程还是启动 Playwright。Playwright 的启动参数也值得调。默认的无头浏览器模式和正常浏览器差别很大有些网站检测无头模式会返回验证码页面。我一般设置headlessFalse用虚拟显示器的环境下或者至少指定一个真实的 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:0008: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互相之间通过标准数据格式通信调试的时候单独调用某一步非常方便。