kscz0000 PDF 转换路由
每次 PDF 转换都先经过简短的分析步骤，再选择工具或 CLI 参数。
目标不是"提取最多的文本"。目标是：
- 保留结构
- 保留标签与值的对应关系
- 选择最忠实于原文的输出形式
- 当存在更优路径时，避免使用嘈杂的默认设置
使用时机
- 用户希望将 PDF 转换为另一种格式。
- 请求的输出格式是
.md、.html、.txt、.json、.docx或结构化笔记。 - PDF 可能是扫描文档、OCR 内容为主、表格为主、幻灯片、医疗文档、学术论文或多栏布局。
核心规则
切勿以固定默认流程开始。
始终：
- 分类 PDF
- 分类目标输出
- 为该组合选择最强路径
- 在代表性段落上验证结果
- 若需要，在交付前用更优设置重试
启发式规则是起点，而非保证。
切勿将某种参数组合推广为通用默认，只因它在某份 PDF 上效果良好。 优先使用文档特定的证据，而非习惯。
主引擎规则
默认将 opendataloader-pdf 作为每次 PDF 转换任务的主转换引擎。
本技能应假定：
opendataloader-pdf始终是首次转换尝试- 其他工具用于分类、验证、OCR、检查或支持清理
- 其他提取器不是主转换路径的默认替代
仅在以下情况使用其他工具：
- 快速分类 PDF
- 转换前 OCR 预处理
- 对保留布局的文本进行验证
- 生成输出仍有噪声时的手动修复
- 仅当
opendataloader-pdf无法产生可用结果时作为后备
第一步：分类源 PDF
尽快识别文档类别：
- 含可选文本的原生数字 PDF
- 含噪声文本的 OCR PDF
- 纯图像/扫描 PDF
- 幻灯片/演示文稿导出
- 医疗或实验室报告
- 表格为主的商业/财务文档
- 叙事性报告/信函/文章
- 含图表、表格和正文的混合布局文档
快速检查方法：
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
默认路径：
opendataloader-pdf -f markdown-with-html --table-method cluster --image-output off
然后验证：
- 主表格标题
- 值、单位和参考范围的对应关系
- 图例/注释与结果行分离
若临床表格被压平，在接受输出前与 pdftotext -layout 对比。
幻灯片
优先：
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 后备
切勿盲目多次重试变体。基于失败模式选择下一次尝试。
优先此重试顺序：
- 同引擎，更优参数
- 同引擎，不同输出形式
- 同引擎加 hybrid/full 模式（若可用）
- 同引擎加清理/修复
- OCR 预处理加同引擎
- 仅当真正受阻时才考虑非 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尽可能紧密切合原始视觉布局
优先优化文档保真度。
切勿仅为视觉模仿原页而牺牲语义正确性。
对大多数转换，结构正确且可读的输出优于视觉相似但语义破损的输出。
推荐最终答案格式
回报时优先说明：
- 所选路径
- 是否需要重试
- 是否应用清理或修复
- 推荐输出文件
- 残留局限（若有）
交付规则
保真度重要时，切勿未经清理和验证门控交付原始提取器输出。
若文档复杂，说明所选路径及原因。