# PDF Conversion Router > 当将 PDF 转换为另一种格式（如 Markdown、HTML、文本、JSON、DOCX 或结构化笔记）时使用，智能体必须选择最佳提取路径、设置和清理策略，以实现最高保真度和可读性。 - Skill: `kscz0000/pdf-conversion-router` (Agent Skill) - Install (CLI): `npx skillmds@latest add kscz0000/pdf-conversion-router` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/pdf-conversion-router/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/pdf-conversion-router --- # PDF 转换路由 每次 PDF 转换都先经过简短的分析步骤，再选择工具或 CLI 参数。 目标不是"提取最多的文本"。目标是： - 保留结构 - 保留标签与值的对应关系 - 选择最忠实于原文的输出形式 - 当存在更优路径时，避免使用嘈杂的默认设置 ## 使用时机 - 用户希望将 PDF 转换为另一种格式。 - 请求的输出格式是 `.md`、`.html`、`.txt`、`.json`、`.docx` 或结构化笔记。 - PDF 可能是扫描文档、OCR 内容为主、表格为主、幻灯片、医疗文档、学术论文或多栏布局。 ## 核心规则 切勿以固定默认流程开始。 始终： 1. 分类 PDF 2. 分类目标输出 3. 为该组合选择最强路径 4. 在代表性段落上验证结果 5. 若需要，在交付前用更优设置重试 启发式规则是起点，而非保证。 切勿将某种参数组合推广为通用默认，只因它在某份 PDF 上效果良好。 优先使用文档特定的证据，而非习惯。 ## 主引擎规则 默认将 `opendataloader-pdf` 作为每次 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` - 幻灯片/PowerPoint 导出 `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，再重转换 - 幻灯片输出嘈杂但结构可用 -> 保持提取器，改进清理 - 幻灯片伪表格未检测 -> 用 hybrid/full 模式在同引擎重试，而非非 OpenDataLoader 后备 切勿盲目多次重试变体。基于失败模式选择下一次尝试。 优先此重试顺序： 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` 路径 - 是否需要重试 - 是否应用清理或修复 - 哪个输出文件是推荐的最终文件 - 仍影响可读性或保真度的任何残留局限 ## 保真度规则 区分： - `document fidelity` 正确内容、正确对应关系、正确段落结构 - `visual fidelity` 尽可能紧密切合原始视觉布局 优先优化文档保真度。 切勿仅为视觉模仿原页而牺牲语义正确性。 对大多数转换，结构正确且可读的输出优于视觉相似但语义破损的输出。 ## 推荐最终答案格式 回报时优先说明： - 所选路径 - 是否需要重试 - 是否应用清理或修复 - 推荐输出文件 - 残留局限（若有） ## 交付规则 保真度重要时，切勿未经清理和验证门控交付原始提取器输出。 若文档复杂，说明所选路径及原因。