PDF AI全能王
一个入口处理所有 PDF 任务：scripts/pdf.py。
- 读：文字提取 / 扫描件 OCR / 转 Markdown / 表格提取 / 转 Word / 扫描件转可搜索 PDF
- 改：合并拆分 / 加密解密 / 水印 / 页码 / 压缩 / 转图 / 提图 / 旋转 / 删页 / 重排 / 统一纸张 / 书签 / 表单
- 检：文档体检 + 处理结果自检（覆盖率、漏页、可疑页）
全程本地，输出永远写新文件、不改原文件。
30 秒上手
python scripts/pdf.py doctor # 1. 环境体检
python scripts/pdf.py demo # 2. 跑一遍示例，看真实输出
python scripts/pdf.py md 报告.pdf # 3. 直接用（缺依赖会自动装）
demo 会生成 3 页示例 PDF 并跑完 体检 → 转 MD → 提表格 → 去水印 → 转 Word → 自检。
任务入口
统一入口 python scripts/pdf.py <任务> ...，参数原样透传：
| 需求 | 任务 | 典型命令 |
|---|---|---|
| 提取文字（批量/自动 OCR） | extract |
pdf.py extract 报告.pdf |
| 转 Markdown（含自检） | md |
pdf.py md 报告.pdf -o 报告.md |
| 提取表格（跨页续表合并） | table |
pdf.py table 财报.pdf --format csv |
| PDF 转 Word | toword |
pdf.py toword 报告.pdf -o 报告.docx |
| 扫描件转可搜索 PDF | searchable |
pdf.py searchable 扫描件.pdf |
| 文档体检 / 结果自检 | verify |
pdf.py verify 文件.pdf --text out.md |
| 去水印 | clean |
pdf.py clean 文件.pdf -o clean.pdf --report |
| 合并 / 拆分 | merge / split |
pdf.py merge -o 合并.pdf a.pdf b.pdf |
| 加密 / 解密 | encrypt / decrypt |
pdf.py encrypt a.pdf -o e.pdf --user-pw 123 |
| 加水印 / 加页码 | watermark / pagenum |
pdf.py watermark a.pdf -o w.pdf --text 内部 --tile |
| 压缩 / 转图片 / 提图片 | compress / topng / images |
pdf.py compress a.pdf -o s.pdf |
| 旋转 / 删页 / 重排 | rotate / drop / reorder |
pdf.py drop a.pdf -o b.pdf --pages 3,7-9 |
| 统一纸张 | resize |
pdf.py resize a.pdf -o b.pdf --paper a4 |
| 书签 / 表单 | outline / form |
pdf.py outline a.pdf --auto -o t.pdf |
| 查看信息 | info |
pdf.py info a.pdf |
默认输出与源文件同目录（报告.pdf → 报告.md），不再写到"不知道哪去了"。全量参数见 references/recipes.md。
一次做对的设计（这几处最容易出错，已内置处理）
| 常见翻车点 | 本技能的处理 |
|---|---|
| 扫描件转出来是空的 | md 检测到无文字层自动 OCR 兜底；或先 searchable 生成可搜索 PDF |
| 表格跨页被拆成两张、表头重复 | 自动判定续表并合并（列数一致 + 表头相似 + 位置相邻），重复表头只留一份 |
| 表格区域内文字又输出一遍 | 表格 bbox 内的正文自动跳过，不重复 |
| 旋转水印的字混进表格/正文 | 按字符矩阵角度 + 字号过滤，水印字不污染表格 |
| 复杂文档漏页 | 转完自动逐页比对字符量，覆盖率 <70% 直接告警并列出可疑页 |
| 第 1 次跑就卡在缺依赖 | 缺依赖自动 pip 安装（可 --no-install 关闭） |
| 输出顺序乱（表格跑到标题前） | 按页面纵坐标排序，还原真实阅读顺序 |
标准工作流
- 先体检：
pdf.py verify 文件.pdf—— 页数、加密、扫描页、空页、字体嵌入、表格数。有风险先说明再动手。 - 再处理：文字 →
extract；文档 →md；要编辑 →toword；扫描件 →searchable；只要数据 →table。 - 后自检：
md自带自检；其他任务用pdf.py verify 输出.pdf复核。 - 汇报：输出绝对路径 + 统计（页数/字数/OCR 页数/合并表数/压缩率）+ 需人工复核的点。
高频排错（完整版见 references/troubleshooting.md）
| 症状 | 首选处理 |
|---|---|
| 扫描件提取为空 | 自动装 OCR：pdf.py setup --ocr；仍差则 --ocr-dpi 400 |
| 文字乱码/方框 | 字体未嵌入：改用 extract --force-ocr |
| 提不到表格 | 无框线表格加 --text-grid；扫描件先 searchable |
| 表格被拆成两张 | 默认已合并；若误合，加 --no-merge |
| 去水印漏删/误删 | 先 --report 预演；漏删 --text "水印文字"，误删 --annots-only |
| 加密打不开 | --password 密码 或环境变量 PDF_PASSWORD |
| 转 Word 排版乱 | 多栏/图文混排属已知边界，md 或人工校对 |
| 依赖装不上 | --no-install 后手动 pip install；国内可加 -i 镜像 |
反模式
- 不对扫描件直接
md期待完美排版——先searchable或extract --force-ocr验文字质量。 - 不给文本型 PDF 无脑
--force-ocr——慢且准确率低于文字层。 - 不用自动去水印处理合同/票据后直接归档——金额、编号必须人工复核。
- 不覆盖用户原文件——输出永远写新文件。
- 不处理用户无权处理的第三方受保护文档。
能力边界（做不到就直说）
- PDF 转 Word：支持文本型 PDF 的结构化还原（标题/段落/表格/图片，表格可编辑）。多栏、图文混排、复杂页眉页脚需人工校对；扫描件请先
searchable。 - 扫描件表格：
searchable后表格工具能读到文字，但无线框的扫描表格仍可能识别不全，建议人工核对。 - 矢量水印/背景图水印：只能处理文字、图片、注释印章三类；矢量水印建议专业工具。
- 双栏/多栏严格分栏：按 block 聚段，双栏会交错；建议降级为纯文本人工编排。
- 表单 XFA / 动态表单：仅支持 AcroForm 标准字段。
资源
scripts/pdf.py— 统一入口（doctor / setup / demo / 自动装依赖 / 任务路由）scripts/extract_text.py— 文字提取 + OCR（批量、txt/md/json、空页统计、--strict、--password）scripts/pdf2md.py— 转 Markdown（段落合并、断词修复、标题推断、图片、跨页表合并、阅读顺序还原、扫描页 OCR、结果自检）scripts/extract_tables.py— 表格提取（md/csv/json、无线框兜底、跨页续表合并、重复表去重、水印字符过滤）scripts/toword.py— PDF 转 Word（真文本 + 真表格 + 图片，跨页表合并）scripts/searchable.py— 扫描件转可搜索 PDF（叠加不可见文字层，版式不变）scripts/remove_watermark.py— 去水印（文字/图片/注释印章，自动+手动，--report预演）scripts/pdf_toolkit.py— 合并/拆分/加解密/水印/页码/压缩/转图/提图/旋转/删页/重排/统一纸张/书签/表单/信息scripts/verify.py— 文档体检与结果自检references/examples.md— 真实运行输出references/troubleshooting.md— 按症状排查 + 反模式 + 参数速调references/ocr_guide.md— OCR 环境与质量调优references/recipes.md— 全量命令速查
