PDF 文本与表格提取
概述
逐页抽取文本与表格，表格自动还原为二维结构。适合把发票、报表、论文中的表格变成可分析的 CSV/JSON。
何时使用
- 用户要从 PDF 抽文字或表格
- 把扫描/导出 PDF 中的表格变成结构化数据
- 为后续统计、入库准备干净文本
快速使用
# 输出 Markdown（含表格还原为标注准 Markdown 表格）
python3 scripts/extract_pdf.py 合同.pdf -o 合同.md
# 只抽第 1~3 页和第 5 页（1-based，支持 "1-3,5,8-" 这种写法）
python3 scripts/extract_pdf.py 长文档.pdf -p "1-3,5" -o 部分.md
# 只要表格 / 只要正文
python3 scripts/extract_pdf.py 报表.pdf -m tables -o 表.md
python3 scripts/extract_pdf.py 论文.pdf -m text -o 正文.md
# 输出 JSON（程序化处理），同样支持 -p / -m
python3 scripts/extract_pdf.py 报表.pdf -f json -o 报表.json
# 加密 PDF：用 -P 提供打开密码
python3 scripts/extract_pdf.py 保密.pdf -P "密码" -o 保密.md
依赖安装
# 提示：脚本用相对路径 scripts/，请先 cd 到本技能目录再运行
python3 -m pip install pdfplumber
常见错误 / 注意
- 仅对「含文本层」的 PDF 有效；图片型扫描件需先 OCR（见 pdf-ocr）
- 跨页表格可能被拆成两页，需下游拼接
- 复杂多栏排版有时顺序错乱，关键页建议用 pdf-render-extract 对照原图
实测验证（v0.1.0）
- 核心依赖：
pdfplumber - 安装体积：🟢 46.5 MB（依赖闭包实测，轻量级）
- 环境要求：无外部二进制依赖。
- 单元测试：
python3 -m unittest tests.test_...（须 cd 到本技能目录运行） - CLI 冒烟：已通过端到端实测
已验证行为
- ✅ -f md：提取正文，中文正常
- ✅ -f json：输出按页数组，含 text/表格字段
已知边界 / 坑
- ⚠️ 无文本层的扫描件提取结果为空
> 造中文测试 PDF 必须用 CJK 内置字体（china-s），默认 helv 不含中文字形。
