PDF → JSON 转换器

为什么不直接 Read PDF

直接让模型读 PDF，工具会逐页把"文字 + 页面视觉"塞进上下文。页数一多，上下文指数膨胀，token（积分）成本很高，且字段不可控。

本技能先在本地用脚本把 PDF 压成纯文本 JSON（按页拆分 text / tables / images），再喂给模型。成本骤降，且文字、表格、图片分字段，便于精准引用。

触发场景

• "把这个 PDF 转成 JSON"
• "解析这份文档，提取文字和表格"
• "我想把 PDF 喂给你但别烧太多积分"
• 任何需要先吃透一份 PDF 再让我分析/摘要/问答的任务（finance 研报、legal 文书、标准文件等）

工作流程

第 1 步：一条命令转 JSON（数字版 / 扫描版通用）

脚本自动判断每页：有文字层 → 抽文字+表格；无文字层（扫描页）→ 整页渲染成 PNG 并自动 OCR。OCR 引擎由 --ocr-engine 控制（默认 auto）：

python3 ~/.workbuddy/skills/pdf-json-converter/scripts/pdf_to_json.py <input.pdf> -o <out.json>
# 可选:
#   --pages 1-3,7        只转指定页
#   --no-images          跳过图片抽取(纯文字/表格需求时更省)
#   --render-pages       强制整页渲染(适合含图片型表格的数字PDF)
#   --ocr-engine auto|native|js|none   OCR 引擎选择
#   --ocr-lang chi_sim+eng             OCR 语言(默认)

• auto（默认）：优先 native（pytesseract），不可用则回退 js（ocr-local 的 Tesseract.js）。
• native：需 brew install tesseract && pip install pytesseract pillow。
• js（推荐、零安装）：调用 ocr-local 技能的 Tesseract.js。前提是先在 ocr-local 目录装好：cd ~/.workbuddy/skills/ocr-local && npm install tesseract.js（本机已装）。
• none：仅把图片落盘，不做 OCR（最快，事后可单独补）。

第 2 步：读取 JSON 交付模型

输出结构：

{
  "source": "/abs/path.pdf",
  "engine": "pdfplumber",
  "ocr_engine": "auto",
  "ocr_native_available": false,
  "ocr_js_available": true,
  "page_count": 10,
  "pages": [
    {
      "page": 1,
      "text": "该页纯文本……（扫描页此字段为空）",
      "tables": [ [ ["列1","列2"], ["行1a","行1b"] ] ],
      "images": [ {"index":1,"path":"/abs/p1_full.png","ocr_text":"OCR 识别出的文字……","kind":"page_render"} ]
    }
  ]
}

转完后，把 out.json 读进上下文（或直接引用），再执行用户的分析任务。扫描页的文字就在 images[].ocr_text 里，无需额外步骤。

扫描版 PDF 说明（已内联，无需手动兜底）

旧版需把图片交给 ocr-local 单独 OCR；现版本脚本已内联 OCR 调用——扫描页会自动整页渲染并 OCR，ocr_text 直接填好。唯一前提：ocr-local 技能目录里装了 tesseract.js（见上 --ocr-engine js）。若出现 ocr_text:null 且提示无 OCR 可用，按提示二选一装引擎即可。

注意事项

• 表格保真：tables 是原始二维数组，不强行展平成文本，避免错位；需要 Markdown 表格时由模型后续转换。
• 图片：仅记录 PNG 路径 + OCR 文本，不把图片像素塞进上下文（那是烧积分的大头）。
• 大文件：先用 --pages 试转前几页，确认结构再全量。
• 依赖：pip install pdfplumber（必需）；OCR 可选二选一（brew install tesseract 走 native，或 ocr-local 目录 npm install tesseract.js 走 js）。
• OCR 质量：扫描件 OCR 偶有错字（尤其表格线、异体字），关键条款以原 PDF 复核。

资源

• scripts/pdf_to_json.py：核心转换脚本，命令行调用，详见文件内 --help。

依赖（市场用户必读）

• 必需：pip install pdfplumber。若运行时报 缺少依赖 pdfplumber，先执行该命令。
• OCR 可选：扫描件需 OCR。WorkBuddy 用户装有内置 ocr-local 技能则开箱即用；否则按脚本 --help 装 tesseract（native）或自备 tesseract.js（js）后，用 --ocr-js-path 指定。
• 详细安装见仓库 README.md。