oma-pdf

PDF 技能 - PDF 转 Markdown

调度

目标

将 PDF 文件转换为结构化 Markdown 或其他指定的提取格式，同时保留易读的文档结构，以供大模型上下文、RAG 或后续审阅使用。

意图特征

• 用户要求转换、解析、阅读、提取或处理 PDF。
• 用户需要整理 PDF 文本、标题、列表、表格或图像，以供 AI 使用。
• 用户提到“PDF 转 markdown”“解析 PDF”“阅读这个 PDF”或类似表述。

适用场景

• 将 PDF 文档转换为 Markdown，供大模型上下文或 RAG 使用
• 提取表格、标题、列表、图像、脚注或超链接等结构化内容
• 整理 PDF 数据以供 AI 使用
• 在选择 OCR 之前，检查 PDF 是否包含文本层

不适用场景

• 生成或创建 PDF -> 使用文档生成工具
• 编辑现有 PDF -> 不在此范围内
• 阅读已有文本文件 -> 使用直接文件读取
• 处理 HWP、HWPX、DOCX、XLSX 或幻灯片 -> 使用对应的文档技能

预期输入

• input_path：PDF 文件或文件夹路径
• output_dir：可选的目标目录
• format：可选的输出格式，默认为 markdown
• ocr_languages：可选的 OCR 语言列表，用于扫描版或基于图像的 PDF
• extraction_options：可选标志，用于指定标签结构、图像提取或混合转换

预期输出

• Markdown、文本、JSON、HTML 或组合提取结果
• 生成 Markdown 时进行规范化处理
• 简短报告，包含输出路径、页数和转换问题

依赖项

• uvx opendataloader-pdf 用于标准转换
• uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid 用于 OCR 或混合转换（混合服务是 [hybrid] 额外依赖中的控制台脚本，并非独立软件包）
• uvx mdformat 用于 Markdown 规范化
• 对输入和输出路径的本地文件系统访问权限
• 可选的 OCR 运行时，通过混合服务提供

控制流特征

• 根据文本层质量、标签 PDF 是否可用、扫描/OCR 需求以及用户指定的输出格式选择分支
• 通过 uvx 调用外部 CLI 工具
• 读取本地文件并写入本地提取结果
• 仅在 OCR 或复杂提取需求确有必要时使用混合服务

结构流程

入口

1. 确认输入路径存在，并且是 PDF 文件、PDF 文件夹或受支持的批处理输入。
2. 检查文件大小；如果输入可能导致转换缓慢或内存压力，则发出警告。
3. 确定 output_dir 和预期的输出文件名。

阶段

1. 准备：验证输入路径、输出目标和所请求的提取选项。
2. 获取：通过提取文本预览，评估 PDF 是否包含可读的文本层。
3. 执行：使用标准模式、标签结构模式或混合 OCR 模式进行转换。
4. 验证：对 Markdown 输出运行 mdformat，并检查结果是否具有清晰易读的结构。
5. 完成：报告输出路径、页数、格式以及任何提取质量问题。

转换条件

• 如果预览文本可读，则使用标准转换。
• 如果 PDF 带标签但标准输出乱码，则使用 --use-struct-tree 重试。
• 如果表格缺失或格式错乱，则先使用 --table-method cluster 或 --markdown-with-html 重试，再升级到混合模式。
• 如果 PDF 是扫描版或基于图像的，则启动或复用混合 OCR 服务，并使用混合模式进行转换。
• 如果转换因 PDF 加密而失败，则停止并索要密码或未锁定的副本。
• 如果转换触及内存或大小限制，则将较小的页面范围处理到不同的输出目录中（或追加 --to-stdout），以免重复运行覆盖相同的基本文件名。

失败与恢复

失败情况	恢复方法
uvx 不可用	请用户先安装 uv，再进行转换
找不到 opendataloader-pdf-hybrid	通过 uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid 调用；PyPI 上不存在该裸包名
PDF 受密码保护	请用户提供密码或未锁定的 PDF
输出乱码	使用带标签的结构或混合模式重试
缺少表格	先使用 --table-method cluster 或 --markdown-with-html 重试；对于扫描版表格，使用混合模式
OCR 语言不匹配	使用明确指定的 OCR 语言重试，例如 ko,en
文件过大或内存压力过高	使用不同的输出目录或 --to-stdout 按页面范围拆分；同一基本文件名不得重复使用同一个输出目录

退出

• 成功：输出文件存在，适用时 Markdown 格式正确，且提取出的结构可读。
• 部分成功：输出文件存在，但明确报告了质量问题。
• 失败：未生成可靠的输出，并报告阻止操作的原因。

逻辑操作

操作

操作	SSL 原语	证据
验证路径和选项	VALIDATE	执行协议中的输入预检
检查文本层	READ	提取文本预览
选择转换策略	SELECT	标准、带标签或混合模式决策
运行转换器	CALL_TOOL	uvx opendataloader-pdf
启动 OCR 服务	CALL_TOOL	uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid
写入输出产物	WRITE	Markdown、文本、JSON 或 HTML 输出
规范化 Markdown	CALL_TOOL	uvx mdformat
检查提取质量	VALIDATE	结构与可读性验证
报告结果	NOTIFY	面向用户的最终摘要

工具与实用程序

• opendataloader-pdf：主要的 PDF 提取 CLI
• opendataloader-pdf-hybrid：混合 OCR 和复杂提取路径
• mdformat：Markdown 规范化
• 在可用时，可使用 file、wc 或 pdfinfo 等文件系统命令进行预检

标准命令路径

uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q   # text-layer probe (no temp files)
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
uvx mdformat "{output_path}"

对于扫描版／基于图像的 PDF，先启动 OCR，再通过混合模式进行转换：

uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"
uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}"

按需使用的标志——--sanitize（PII 遮蔽）、--pages（范围提取）、--threads（并行处理页面）、--detect-strikethrough、混合模式的 --enrich-formula／--enrich-picture-description——详见 resources/execution-protocol.md。这两个增强标志要求客户端使用 --hybrid-mode full。

资源范围

范围	资源目标
LOCAL_FS	输入 PDF 和生成的输出文件
PROCESS	uvx 子进程和可选的混合服务
MEMORY	提取的预览和验证备注
OTHER	混合模式中的 OCR 模型／运行时行为

前提条件

• 输入 PDF 路径存在且可读。
• 输出位置可写，或可创建。
• 所需 CLI 可通过 uvx 使用。
• 仅当混合模式可用或可以启动时，才会尝试 OCR。
• 默认值来自 .agents/oma-config.yaml 的 pdf: 部分；对于未设置的键，则回退到 config/pdf-config.yaml。显式用户选项会覆盖两者；output.overwrite: false 时，替换现有输出文件前必须获得确认。

影响与副作用

• 根据配置和用户意图创建或覆盖提取输出。
• 可能会在配置的端口上启动本地混合 OCR 服务。
• 处理大型或扫描版 PDF 时，可能会消耗大量 CPU、内存或时间。
• 不会有意修改源 PDF。

防护措施

1. 如果内容提取不完整，不要臆造缺失内容。
2. 始终报告乱码、表格缺失、OCR 识别不确定或提取不完整的情况。
3. 如果文本层清晰可读，优先使用标准转换。
4. 仅当 PDF 为扫描件、基于图像，或标准提取质量不足时才使用 OCR。
5. 将详细的命令序列保留在 resources/execution-protocol.md 中，不要在此处重复每种变体。

参考资料

• 执行协议：resources/execution-protocol.md
• 配置：先读取 .agents/oma-config.yaml 的 pdf: 部分，再回退到 config/pdf-config.yaml 中未设置的键。用户覆盖项应放在 .agents/oma-config.yaml 中，因为 oma update 会覆盖技能配置。
• 上下文加载：../_shared/core/context-loading.md
• 质量原则：../_shared/core/quality-principles.md