mcpField
P
pdf-inspector

pdf-inspector

github.com/kuberwastaken文档处理047 次安装12 周前更新
代码仓库

关于 pdf-inspector

pdf-inspector 是供编码 Agent 使用的本地 PDF 转 Markdown 技能，基于纯 Rust 解析器，完成初始化后可离线运行。它会标记文档类型和无法读取的页面，避免将 OCR 缺失内容误作已提取文本。

主要功能

  1. 01PDF 分类与文本提取
  2. 02输出 Markdown、纯文本或 JSON
  3. 03按指定页面提取
  4. 04报告需要 OCR 的页面
  5. 05Python API 获取文本位置与区域

适用场景

  1. 01从本地 PDF 提取文本和表格
  2. 02检查哪些页面需要 OCR
  3. 03处理大型 PDF 的指定页面
  4. 04检查文本位置和页面区域

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/kuberwastaken/pdf-inspector --skill pdf-inspector

安装后在 Claude Code 中输入/pdf-inspector确认已加载。

附带文件scripts/pdfmd.py

详细介绍

pdf-inspector

基于 firecrawl/pdf-inspector 构建的本地 PDF → Markdown 工具： 纯 Rust 实现，仅依赖 lopdf，在 opendataloader-bench 本地解析器的阅读顺序和表格对比中名列前茅，并可完全离线运行。

快速使用

运行随附的封装脚本（路径相对于此技能文件夹）。首次运行时，脚本会在 ~/.venvs/pdf-inspector 创建 venv（可通过 $PDF_INSPECTOR_VENV 覆盖） 并安装 pdf-inspector wheel；之后的所有操作都可离线进行。

python3 scripts/pdfmd.py document.pdf                  # Markdown on stdout, status on stderr
python3 scripts/pdfmd.py document.pdf --detect         # classification only (fast), JSON output
python3 scripts/pdfmd.py document.pdf --json           # full result (markdown + metadata) as JSON
python3 scripts/pdfmd.py document.pdf --text           # plain text, no Markdown structure
python3 scripts/pdfmd.py document.pdf --pages 1,3,5-10 # only these pages (1-indexed; not with --text)

退出代码：0 = 已提取，2 = 没有可提取的文本（扫描件／图像 PDF — 需要 OCR），1 = 出错。

阅读结果

  • pdf_type：text_based | scanned | image_based | mixed，并包含 confidence（0.0–1.0）。
  • pages_needing_ocr：从 1 开始编号的页面，其中没有可提取的文本。这些页面的内容不会出现在输出中。
  • has_encoding_issues：true 表示提取的文本可能是乱码（字体编码损坏）——应将文档视为扫描件。
  • pages_with_tables / pages_with_columns：从 1 开始编号；在抽查版面复杂的页面时很有用。

规则

  1. 切勿编造需要 OCR 的页面内容。 如果 pdf_type 为 scanned／image_based，或 pages_needing_ocr 非空，请明确说明哪些页面无法读取，并将其交由 OCR 工具处理（或询问用户）。退出代码 2 表示整份文档都需要 OCR。
  2. 对于 mixed PDF，使用文本页面提取出的 Markdown，并明确标记需要 OCR 的页面——只要说明内容缺失的位置，部分输出也可以接受。
  3. 对于大型 PDF（100 页以上），先运行 --detect（约需 10–50 毫秒），然后使用 --pages 仅提取所需页面。
  4. 如果 has_encoding_issues 为 true，即使文本看起来合理，也不要轻信。

直接使用 Python API（高级）

需要进行区域级或位置级处理时，可直接使用 venv 中的 Python （~/.venvs/pdf-inspector/bin/python）：

import pdf_inspector
r = pdf_inspector.process_pdf("doc.pdf", pages=[1, 3])      # full result; pages= is 1-indexed
c = pdf_inspector.classify_pdf("doc.pdf")                   # lightweight; pages_needing_ocr is 0-indexed here
items = pdf_inspector.extract_text_with_positions("doc.pdf")  # TextItem: text, x, y, font, page, bold/italic
per_page = pdf_inspector.extract_pages_markdown("doc.pdf", pages=[0, 2])  # 0-indexed pages arg
regions = pdf_inspector.extract_text_in_regions("doc.pdf", [(0, [[50, 50, 400, 200]])])

注意索引方式——不同函数有所差异：process_pdf(pages=) 使用从 1 开始的索引， extract_pages_markdown(pages=) 和 classify_pdf 的结果使用从 0 开始的索引，而完整结果中的 pages_needing_ocr / pages_with_tables 使用从 1 开始的索引。封装脚本会为你处理这些差异；若使用其他函数，请通过实测确认。

如果 wheel 安装失败

PyPI 提供适用于 macOS（x64/arm64）、Linux（x64/aarch64）和 Windows x64 的 wheel。在 其他平台上，请改为从源代码构建：cargo install pdf-inspector 会提供功能相当的 pdf2md 和 detect-pdf 二进制文件（纯 Rust 实现，无系统库依赖）。 npm 包 @firecrawl/pdf-inspector 仅提供 linux-x64/darwin-arm64/win-x64 预构建版本——在 Linux arm64 机器上，请优先使用 Python wheel。

致谢

所有繁重工作均由 Firecrawl 团队的 pdf-inspector 完成（MIT，© 2026 Firecrawl）。此技能 只是将其打包，供编码 Agent 使用。

评论

支持 Markdown