用途
oma-pdf 用于将 PDF 文件转换为结构化 Markdown 或其他指定的提取格式，同时保留可读的文档结构，以便用于 LLM 上下文、RAG 或下游审阅。它专注于 PDF 解析，不负责 PDF 版式创建。
主要能力
- 将 PDF 转换为 Markdown、文本、JSON、HTML 或组合提取输出。
- 提取结构化内容，包括表格、标题、列表、图片、脚注和超链接。
- 在生成 Markdown 时进行规范化处理。
- 输出简短报告，包含输出路径、页数和转换问题。
- 支持标准转换、标签结构模式和混合 OCR 模式。
- 可先探测 PDF 是否具有文本层，再决定是否使用 OCR。
使用方式
预期输入包括：input_path（PDF 文件或文件夹路径）、output_dir（可选目标目录）、format（可选输出格式，默认 markdown）、ocr_languages（可选 OCR 语言列表，用于扫描或图片型 PDF）、extraction_options（可选标志，用于标签结构、图片提取或混合转换）。
依赖项：
- uvx opendataloader-pdf 用于标准转换
- uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid 用于 OCR 或混合转换（混合服务器是 [hybrid] extra 的控制台脚本，不是独立包）
- uvx mdformat 用于 Markdown 规范化
- 本地文件系统访问输入和输出路径
- 可选 OCR 运行时通过混合服务器提供
典型命令路径： uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q # 文本层探测（不产生临时文件） 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。
适用场景
- 将 PDF 文档转换为 Markdown，用于 LLM 上下文或 RAG。
- 提取结构化内容，如表格、标题、列表、图片、脚注或超链接。
- 为 AI 消费准备 PDF 数据。
- 在选择 OCR 之前检查 PDF 是否具有文本层。
不适用场景：
- 生成或创建 PDF -> 使用文档生成工具。
- 编辑现有 PDF -> 超出范围。
- 读取已经是文本的文件 -> 使用直接文件读取。
- 处理 HWP、HWPX、DOCX、XLSX 或幻灯片 -> 使用匹配的文档技能。
限制
- 不编造缺失内容；提取不完整时始终报告乱码文本、缺失表格、OCR 不确定性或部分提取。
- 文本层可读时优先使用标准转换；仅在 PDF 为扫描件、图片型或标准提取质量不足时使用 OCR。
- 加密 PDF 需停止并请求密码或解锁副本。
- 大文件或内存压力时，按页面范围拆分到不同输出目录（或追加 --to-stdout），避免重复运行覆盖同一基名。
- 默认值来自 .agents/oma-config.yaml 的 pdf: 部分，未设置的键回退到 config/pdf-config.yaml；显式用户选项覆盖两者，output.overwrite: false 时替换现有输出文件需确认。
- 可能启动本地混合 OCR 服务器，消耗大量 CPU、内存或时间；不会有意修改源 PDF。
- 若 uvx 不可用，需用户先安装 uv；若 opendataloader-pdf-hybrid 未找到，需通过 uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid 调用，裸包名在 PyPI 上不存在。
参考
- 执行协议：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