--- name: pdf-conversion-router description: 当需要将 PDF 转换为 Markdown、HTML、纯文本、JSON、DOCX 或结构化笔记等其他格式，且智能体必须为最大保真度和可读性选择最佳提取路线、设置和清理策略时使用。 risk: safe source: community date_added: "2026-05-23" metadata: category: technique triggers: pdf conversion, convert pdf, pdf to markdown, pdf to html, pdf to text, pdf to json, pdf to docx, OCR pdf, slide deck pdf, medical pdf, scanned pdf --- # PDF 转换路由 在每次 PDF 转换之前，先进行简短的分析步骤，然后再选择工具或 CLI 参数。 目标不是"提取最多的文本"。目标是： - 保留结构 - 保留标签与值之间的关联 - 选择最忠实于原意的输出形态 - 在有更好路线时，避免使用有噪点的默认设置 ## 何时使用 - 用户想要将 PDF 转换为另一种格式。 - 请求的输出格式为 `.md`、`.html`、`.txt`、`.json`、`.docx` 或结构化笔记。 - 该 PDF 可能是扫描件、大量 OCR、表格密集、基于幻灯片、医学类、学术类或多栏排版。 ## 核心规则 切勿一开始就使用固定的默认管道。 始终： 1. 对 PDF 进行分类 2. 对目标输出进行分类 3. 为该组合选择最强路线 4. 在代表性章节上验证结果 5. 如有必要，在交付前使用更佳设置重试 启发式方法只是起点，而非保证。 不要因为一种参数组合在一个 PDF 上效果好，就把它推广为通用默认值。 优先使用基于特定文档的证据，而非习惯。 ## 主引擎规则 对于每项 PDF 转换任务，默认使用 `opendataloader-pdf` 作为主转换引擎。 此技能应假设： - `opendataloader-pdf` 始终是首次转换尝试 - 其他工具用于分类、验证、OCR、检查或辅助清理 - 其他提取器不是主转换路线的默认替代品 仅在以下原因之一时使用其他工具： - 快速对 PDF 进行分类 - 在转换前进行 OCR 预处理 - 根据保留布局的文本进行验证 - 当生成的输出仍有噪点时进行手动修复 - 仅在 `opendataloader-pdf` 无法产生可用结果时作为回退 ## 第一步：对源 PDF 进行分类 尽可能快速识别文档类别： - 原生数字 PDF，文本可选 - 带噪点文本的 OCR PDF - 纯图像/扫描版 PDF - 幻灯片/演示文稿导出 - 医学或实验室报告 - 表格密集的商业/财务文档 - 叙述性报告/信件/文章 - 包含图表、表格和散文的混合排版文档 有用的快速检查： ```bash pdfinfo input.pdf pdftotext -layout input.pdf - ``` 如果文本缺失或质量极差，则将 OCR 视为必要步骤。 ## 文档类型启发式规则 将这些作为默认起点： - 医学/实验室报告 `markdown-with-html + --table-method cluster + --image-output off` - 幻灯片/PPT导出 `markdown-with-html + --image-output off` 仅当默认路线对重要的表格内容结构化不足时，才添加 `--table-method cluster` 如果表格在视觉上明显存在，但缺失或严重合并，则将其视为检测问题，而非 Markdown 格式问题 如果所选路线已重构出真实表格，但在列边界处截断了前导字符，则将其视为边界分割缺陷，而非表格缺失失败 - 叙述性文档/文章/信件 从 `markdown` 或 `text` 开始 仅当结构明显重要时才使用 `markdown-with-html` - 表格密集的商业/财务 PDF 从 `markdown-with-html` 开始 当行或列被压平时，添加 `--table-method cluster` - 扫描版/图片密集的 PDF 先 OCR，再用 `opendataloader-pdf` 转换 - 混合排版 PDF 优先使用 `markdown-with-html` 在接受输出前，验证一个简单章节和一个困难章节 ## 第二步：选择输出形态 选择最能匹配文档和用户目标的输出。 - `markdown-with-html` 当用户需要 Markdown 且保真度重要时默认使用。 优先用于表格、医学报告、幻灯片、混合排版 PDF 以及任何可能在纯 Markdown 中出问题的内容。 - `markdown` 仅在纯净的普通 Markdown 比排版保真度更重要时使用。 - `html` 当视觉结构比 LLM 可读性更重要时使用。 - `text` 用于快速线性提取、叙述性文档，或当结构不重要时。 - `json` 当下游机器处理比人类可读性更重要时使用。 - `docx` 当用户需要可编辑的办公输出且排版重构很重要时使用。 ## 第三步：选择提取路线 ### 针对 OpenDataLoader CLI 使用 OpenDataLoader 作为默认路线。 推荐的默认参数： - 对于优先保真度的 Markdown 输出： `-f markdown-with-html` - 对于医学 PDF： 添加 `--table-method cluster` - 对于表格密集的 PDF： 添加 `--table-method cluster` - 对于幻灯片： 从不使用 `--table-method cluster` 开始 仅在结构检查显示有显著改善后才添加 如果伪表格已折叠在单个检测到的行内，仅更改 Markdown 风格通常无法修复 如果当前引擎版本已恢复伪表格结构，在升级到 hybrid/full 模式之前，优先修复残留的边界伪影 - 对于不需要图片的转换： 添加 `--image-output off` - 对于幻灯片、医学报告和结构敏感的 PDF： 优先同时验证命令成功和实际渲染的结构 - 对于精确值重要的报告/文档： 在转换后验证关键章节，而非仅信任初次通过的结果 ### 针对医学或实验室 PDF 默认路线： ```bash opendataloader-pdf -f markdown-with-html --table-method cluster --image-output off ``` 然后验证： - 主表表头 - 数值、单位和参考范围的关联 - 图例/注释与结果行分离 如果临床表格被压平，在接受输出前与 `pdftotext -layout` 进行对比。 ### 针对幻灯片 推荐： ```bash opendataloader-pdf -f markdown-with-html --image-output off ``` 然后检查： - 重复的页脚 - 页码 - 图表伪表格 - 孤立的符号和图表标签 如果 CLI 输出仍然较差，进行针对幻灯片优化的清理，而非假设原始提取就是最终结果。 如果幻灯片包含明显类似表格的块但完全未被检测为表格，在跳转到无关的提取器之前，优先使用更强大的路线（如 hybrid/full 模式）在同一引擎内重试。 如果幻灯片现在生成了真实表格，在假定表格完全正确之前，先验证第一列和表头边界。 ### 针对扫描版 PDF 如果文本层质量差或不存在： - 先运行 OCR - 然后用 `opendataloader-pdf` 转换 OCR 后的 PDF 优先采用保守重构，而非激进的猜测。 ## 第四步：验证关卡 在声称成功之前，检查输出中最可能出问题的模式。 对于医学 PDF： - 数值正确关联到检查项名称 - 单位和参考范围未合并到相邻内容中 - 注释未合并到行中 对于幻灯片： - 项目符号已规范化 - 页脚/页码在构成噪点时已移除 - 图表未导致崩溃 - 剩余表格可读性足以理解 - 第一列标签在推断的列边界处未丢失首字符 - 伪表格恢复未破坏行分组或将标签溢出到下一列 对于表格密集的文档： - 无灾难性的行压平 - 表头已保留 - 重复的空分隔行已最小化 - 稀疏或单列表格未意外折叠为散文 - 表体未融合为包含多条逻辑记录的单个 HTML 或 Markdown 行 对于每类文档： - 检查第一个代表性章节，而不仅仅是文件顶部 - 检查一个复杂章节，而不仅仅是简单章节 - 优先使用文档级置信度，而非仅凭第 1 页的成功 ## 危险信号 将这些视为当前输出尚未就绪的信号： - 表格行被压平成较长的散文行 - 表头看起来正确，但整个表体融合为单行多值单元格 - 标签与值分离 - 单位或参考范围漂移到相邻行 - 重复的页脚或页码 - 大部分单元格为空的伪表格 - 合法的稀疏表格被折叠为段落 - 单列表格因看起来"过于简单"而被压平 - 多余的符号、项目符号或 OCR 片段 - 命令退出码良好但结构明显较差 - 第 1 页看起来不错，但后面的复杂章节出问题 - 从 `markdown` 切换到 `markdown-with-html` 改善了换行，但未恢复缺失的行边界 - 伪表格现在已作为表格输出，但关键标签在单元格左边缘被截断 ## 永远不要信任第 1 页 不要仅仅因为文件顶部看起来不错就接受转换结果。 始终验证： - 一个靠前的章节 - 一个结构复杂的章节 - 一个可能对用户最重要的章节 对于医学 PDF，这意味着检查一个真实的实验室表格，而不仅仅是标题块。 对于幻灯片，这意味着至少检查一个密集图表或伪表格，而不仅仅是标题幻灯片。 ## 第五步：转换后修复 仅仅因为生成了文件，转换并未完成。 如果输出结构正确但仍然有噪点或难以阅读，在交付之前执行一次清理。 使用三个分类： - `cleanup`（清理） 用于降噪，不改变语义。 示例： - 重复的页脚 - 页码 - 重复的项目符号标记 - 多余的符号 - 空分隔行 - 应转为纯文本的琐碎单单元格伪表格 重要： 不要仅仅因为表格稀疏、狭窄或大部分为空就折叠它。 如果合法单列表格和稀疏表格仍具有表格含义，则保留它们。 - `structural correction`（结构修正） 用于在提取器找到了正确内容但结构错误时修复关联性和可读性。 示例： - 压平的表格 - 合并的列 - 注释混入结果行 - 图例混入测量值 - 断裂的章节边界 - `route retry`（路线重试） 用于问题源于错误提取路径而非输出清理的情况。 始终优先选择能产生忠实且可读结果的最轻量级修复。 如果输出明显可以改进，不要保留原始的噪点输出而不处理。 ## 第六步：重试规则 如果首次路线错误，进行一次有针对性的重试。 示例： - Markdown 对表格过于扁平 -> 切换到 `markdown-with-html` - 表格检测弱 -> 用 `--table-method cluster` 重试 - 表格包装存在但表体行融合 -> 视为结构性提取失败；检查 JSON 或保留结构的视图，然后重试路线而非仅清理 Markdown - 表格结构已恢复但前导字符在单元格边界处被截断 -> 视为边界分割缺陷；优先收紧同一引擎的结构逻辑，而非路由到无关的提取器 - OCR 遗漏文本 -> 先 OCR，再重新转换 - 幻灯片输出有噪点但结构可用 -> 保留提取器，改进清理 - 幻灯片伪表格未被检测 -> 在回退到非 OpenDataLoader 之前，用 hybrid/full 模式重试同一引擎 不要盲目重试许多变体。根据失败模式选择下一次尝试。 优先采用此重试顺序： 1. 同一引擎，更佳参数 2. 同一引擎，不同的输出形态 3. 同一引擎加上 hybrid/full 模式（如可用） 4. 同一引擎加上清理/修复 5. OCR 预处理加上同一引擎 6. 仅在此之后，如果确实受阻，才考虑非 OpenDataLoader 的回退 对于 `--table-method cluster`，将其视为有针对性的重试或特定文档的默认值，而非通用默认值。 它通常是医学 PDF 的最佳选择，但并非自动适用于每份幻灯片或每份商业文档。 ## 默认偏好 当用户未另行指定时： - 优先使用 `markdown-with-html` 而非纯 `markdown` - 除非用户需要，否则禁用图片 - 对于医学 PDF，优先使用 `--table-method cluster` - 对于表格密集的 PDF，当行或列被压平时考虑 `--table-method cluster` - 不要假设 `--table-method cluster` 是幻灯片的最佳默认值 - 不要假设单靠 `markdown-with-html` 就能修复已融合的表格行——如果底层表格结构本身已错误 - 如果当前引擎已足够正确地重构伪表格，不要假设 hybrid/full 模式仍然必要 - 验证实际输出，而不仅仅是命令退出码 - 保持原始 PDF 不变 - 优先将转换后的文件创建在专用输出文件夹中 - 优先告知用户最终选定的输出路径，而不仅仅是命令摘要 ## 基准测试安全规则 如果工作涉及更改 `opendataloader-pdf` 自身的行为，而不仅仅是运行转换： - 验证目标真实 PDF - 如有可能，验证至少一个困难的公开基准测试用例 - 避免那种改善了一个文档却损害了其他稀疏或边界情况表格的清理规则 - 明确检查这种失败模式：表头看似正确，但其后跟随单个融合的表体行 - 如果修复了幻灯片伪表格，也重新检查一个之前已恢复的密集表格案例，以确保新启发式不会重新引入旧的回归问题 - 区分基准测试上的成功与美容上的残留缺陷（如恢复后单元格内的左边缘字符截断） 在一个 PDF 上取得胜利是有用的，但如果没有更广泛的验证，不足以将某个启发式方法变为全局默认值。 ## 局限性 - 此技能用于路由和验证转换工作，不保证 `opendataloader-pdf`、OCR 工具或 PDF 工具在每个环境中都已安装。 - 即使最佳路线成功，复杂 PDF 仍可能需要手动结构修复。 - OCR 质量、源扫描质量和格式错误的 PDF 内部结构，无论选择哪条路线，都可能限制保真度。 - 视觉保真度次于文档保真度，因此除非用户明确要求，否则可能不会保留精确的页面布局。 ## 交付检查清单 在完成之前，确保能够说明： - 选择了哪条 `opendataloader-pdf` 路线 - 是否需要重试 - 是否应用了清理或修复 - 哪份输出文件是推荐的最终文件 - 任何仍然影响可读性或保真度的残留局限性 ## 保真度规则 区分： - `文档保真度` 内容正确，关联正确，章节结构正确 - `视觉保真度` 尽可能保留原始视觉排版 优先优化文档保真度。 不要为了模仿原始页面的视觉效果而牺牲语义正确性。 对于大多数转换，结构正确且可读的输出优于视觉相似但语义有误的输出。 ## 推荐的最终回答格式 在汇报时，优先说明： - 选择的路线 - 是否需要重试 - 是否应用了清理或修复 - 推荐的输出文件 - 残留的局限性（如有） ## 交付规则 当保真度很重要时，不要未经清理和验证就交付原始的提取器输出。 如果文档复杂，说明选择了哪条路线以及原因。