pdf-toolkit — 本地免费 PDF 工具箱
替代 WPS 付费 PDF 功能的本地工具集。全部离线处理，无次数限制，无隐私上传风险。
环境要求
- Python 3.10+
- 必需依赖（PDF转Word 功能）：
pip install pymupdf pdf2docx python-docx - 基础命令（合并/拆分/水印等）仅需：
pip install pymupdf - OCR 可选：
pip install easyocr - 渲染校准 / 字体渲染层诊断（可选，仅 Windows）：
pip install pywin32，需本机装有 WPS 或 MS Word
首次使用时，把下面命令中的 "$PY" 替换为你环境里的 Python 解释器（如 python），"$TK" 替换为本技能 scripts 目录下的 pdf_toolkit.py。
命令速查
| 需求 | 命令 |
|---|---|
| 改 PDF 里的错字/日期/名称 | "$PY" "$TK" replace 输入.pdf -o 输出.pdf --old 旧字 --new 新字 |
| 合并 | "$PY" "$TK" merge a.pdf b.pdf -o 合并.pdf |
| 拆成一页一个 | "$PY" "$TK" split 输入.pdf -o 目录/ |
| 只要第 X~Y 页 | "$PY" "$TK" extract 输入.pdf 1-3 -o 部分.pdf |
| 删掉某些页 | "$PY" "$TK" delete 输入.pdf 2,5 -o 输出.pdf |
| 旋转 | "$PY" "$TK" rotate 输入.pdf 90 -o 输出.pdf |
| 加密/去密码 | "$PY" "$TK" encrypt 输入.pdf -o 加密.pdf --pwd 密码 / decrypt |
| 中文水印（支持角度） | "$PY" "$TK" watermark 输入.pdf -o 输出.pdf --text 内部资料 |
| 转图片 | "$PY" "$TK" toimg 输入.pdf -o 目录/ --fmt png --dpi 200 |
| 图片合成 PDF | "$PY" "$TK" img2pdf 目录/ -o 相册.pdf |
| 提取全部文字 | "$PY" "$TK" text 输入.pdf |
| 文件信息 | "$PY" "$TK" info 输入.pdf |
| PDF 转 Word（推荐） | "$PY" "$TK" toword 输入.pdf -o 输出.docx（转换后自动执行六步版式修复+验收） |
| PDF 转 Word（目录批量） | "$PY" "$TK" toword 目录/ -o 输出目录/ |
| 扫描件 OCR 可搜索化 | "$PY" .../scripts/pdf_ocr.py 扫描件.pdf -o 可搜索.pdf --txt 文本.txt |
PDF 转 Word：六步版式修复管线
toword 转换后自动以源 PDF 为基准执行（也可单独跑 fix_docx_layout.py）：
- 机制 A：拆解 pdf2docx 的「1行2列隐形表格」（红头文件并排版式），转为段落+制表位+段落底边框——WPS 编辑视图虚线彻底消失
- 机制 B：内容对账——修复误合并行、恢复引擎丢弃的内容、span 重叠伪影防护（三级模糊容错）
- 机制 C：分节与页脚治理——消除无故多页、多页表格页序错位、页码归位页脚 PAGE 域；拆分节数量以 PDF 页数封顶
- 机制 D：边框线几何对齐——公文体红线/黑线的端点、长度、颜色自动对齐原稿
- 机制 E：表格列宽重建——修复 tblGrid 均分导致的列宽变形（窄列撑宽/宽列压窄/右缘超边距）
- 机制 F：字体名规范化——修复 PostScript 名导致的 WPS 静默替换（雅黑变宋体等）
- 验收对账：PDF 每行文本 vs docx 双向核对，输出 ✓/✗ 报告
转换差异诊断（用户报告"和原稿不一样"时）
"$PY" .../scripts/diagnose.py 原稿.pdf 转换.docx [--wps]
一条命令跑完三层诊断（结构速览/列宽 grid-vs-tcW/字体声明层+渲染层），病症输出直接标注对应修复机制。
段落间距渲染校准（可选，追求坐标级还原）
"$PY" .../scripts/calibrate_spacing.py 文档.docx --pdf 原版.pdf [--tol 6]
WPS/Word COM 渲染闭环：渲染→量坐标→自动补 spacing →迭代收敛。仅 Windows。
排障方法论：分层定位
「转出来的 Word 和原稿不一样」可能坏在三层之一：声明层（docx XML 写了什么）→ 解析层（WPS 按 OOXML 优先级取哪套数据）→ 渲染层（实际画成什么）。声明正确 ≠ 显示正确；根因常是「正确数据被另一套规则压制」（tcW 被 tblGrid 压制、族名被 PostScript 名压制），修复思路是让对的数据生效而非重造数据。
诊断口诀：
- 列宽：原稿竖线做标尺（get_drawings x 聚类）、docx tcW 做探针——tcW 对而 grid 错 = pdf2docx 典型病症，修 grid 不动 tcW
- 字体：必须查渲染层——WPS 查不到族名就无提示替换；用 span 聚合对比（(font,size,bold)×字数）快速定性，字号先量化到 0.5pt 消除取整假差异
- 竖线检测须含短段：WPS 会把表格竖线按逐行 ~20pt 短段绘制，长线过滤会漏检
- Windows 字体实装以注册表为准：写进 docx 的字体名必须能被注册表族名匹配，否则静默替换
已知限制
- 渲染校准与字体渲染层诊断仅支持 Windows（依赖 COM 自动化）
- 扫描件转 Word 需先 OCR（
pdf_ocr.py），否则转出的是图片页 - 纯图片型 PDF 的字体/列宽诊断不适用（无文字层）
