PDF → Word 转换 + 自动质量复核
Overview
把 PDF 转成可编辑的 Word，并且转完之后自动核对转换质量——对账字符数、表格数、图片数、表格单元格数，把「转换有没有丢内容」从感觉变成证据。这是它区别于普通 PDF 转换工具的差异点：别人只负责「转」，它转完还告诉你「哪里可能转坏了」。
底层代码是独立的开源项目 pdf2word-review（AGPL-3.0，GitHub: https://github.com/xiyanjun/pdf-to-word-review ）。本 skill 是薄包装：只负责调用和解读结果，不内嵌代码。
前置安装
先确认 CLI 是否可用：
pdf2word --help >/dev/null 2>&1 && echo "已安装" || echo "需要安装"
未安装时，按优先级装（推荐从 GitHub 直装，无需等 PyPI 发布）：
# 方式 1：PyPI（正式发布后）
pip install pdf2word-review
# 方式 2：GitHub 直装（PyPI 未发布也能用，推荐）
pip install git+https://github.com/xiyanjun/pdf-to-word-review.git
核心依赖只有 4 个轻量包（pdf2docx、PyMuPDF、python-docx、lxml），会自动带上。OCR 是可选依赖，见下方「扫描件 OCR」一节。
工作流程
Step 1：确认输入
- 检查用户给的路径是否存在、是否为
.pdf。 - 批量场景：用户可能一次给多个 PDF，支持批量转换。
Step 2：执行转换（自动分流）
pdf2word <input.pdf> -o <output.docx> --verify --html
CLI 会自动检测文字层并分流：
| 情况 | 自动行为 |
|---|---|
| 有文字层 | 走「转换 → 空段落清理 → 排版优化」常规流程 |
| 无文字层（扫描件） | 自动走 OCR 重建 |
关键参数：
| 参数 | 作用 |
|---|---|
-o <path> |
输出 docx 路径（仅单文件时有效） |
--verify |
核心：转换后执行四项对账质量复核 |
--html |
生成差异可视化 HTML 报告（<docx>.report.html） |
--report <json> |
复核报告输出到 JSON（批量时为结果数组） |
--force-ocr |
强制走 OCR 重建 |
--engine auto/vision/paddle |
OCR 后端（默认 auto：macOS 优先 Vision，否则 PaddleOCR） |
--no-clean |
跳过空段落清理 |
--no-polish |
跳过排版优化（非 macOS 环境建议加，见「注意事项」） |
Step 3：执行质量复核（核心差异化）
--verify 会自动做四项对账，每项输出 PDF 值 → Word 值 的差值，并判定状态：
| 对账项 | 说明 |
|---|---|
| 字符数 | 非空白字符数（统一 PDF/Word 口径） |
| 表格数 | 源 PDF vs 目标 Word 的表格个数 |
| 图片数 | 按 Word a:blip 引用计数（避免 media 假阳性） |
| 表格单元格数 | 表格结构行×列对账，捕捉「表格被拆散/合并」 |
页数仅作参考提示（Word 分页受排版影响，不可直接对账）。
Step 4：解读并汇报
拿到复核结果后，必须翻译成人话，不要原样丢 JSON 给用户。解读规则见下方「结果解读指南」。
结果解读指南
每项对账的 status 有四种，含义如下：
| status | 含义 | 严重程度 | 汇报口径 |
|---|---|---|---|
ok |
一致 | 无 | 正常，无需多提 |
loss |
内容丢失（Word 比 PDF 少） | 🔴 严重 | 必须明确告知用户「哪一项丢了多少」 |
extra |
冗余（Word 比 PDF 多） | 🟡 需核对 | 提示疑似冗余；字符多出 <5% 属正常增量不告警 |
converted |
图→文替换（图片减少但字符增加） | 🟢 预期 | 解释为「排版优化把横幅图换成了文字标题，非丢失」 |
汇报模板（给用户的最终结论，先结论后明细）：
✅/⚠️ 转换结论：{通过 / 发现 N 处需复核}
| 项目 | PDF | Word | 差异 | 判定 |
|------|-----|------|------|------|
| 字符数 | ... | ... | ... | ✅/❌ |
| 表格数 | ... | ... | ... | ✅/❌ |
| 图片数 | ... | ... | ... | ✅/❌ |
| 表格单元格 | ... | ... | ... | ✅/❌ |
{若有 loss/extra，逐条列出 risk 说明和整改建议}
要点：
- 只要出现 loss 或 extra，就在结论里点名，不要笼统说「可能有问题」。
- 出现 converted 时要主动向用户解释这是预期行为，避免误报。
- 若生成了 --html，把 HTML 报告路径告诉用户（差异可视化，比文字直观）。
扫描件 OCR
扫描版 PDF（无文字层）会自动走 OCR 重建。OCR 有两个后端，都是可选依赖，非默认安装：
| 后端 | 平台 | 安装 |
|---|---|---|
| macOS Vision | 仅 macOS | pip install pyobjc-framework-Vision pyobjc-framework-Quartz（轻量，用系统框架） |
| PaddleOCR | 跨平台 | pip install paddleocr paddlepaddle（较重，首次运行下载中英文模型） |
- 用户是 macOS 且要处理扫描件 → 装 Vision 后端。
- 非 macOS → 装 PaddleOCR。
- 不装 OCR 依赖时，扫描件转换会报错并给出安装提示，此时如实告知用户装哪个即可。
- OCR 重建后，字符/图片对账不适用（源 PDF 无文字层），改以 OCR 置信度报告为准：低于 0.7 置信度的文本块需提醒人工核对。
注意事项
- 排版优化（polish）依赖 macOS：徽章 OCR + 列表项修复需要系统 Vision/Quartz。非 macOS 环境应加
--no-polish跳过，避免报错。 - AGPL-3.0 边界：本 skill 是薄包装，只调用外部包、不内嵌 AGPL 代码。如需改写底层逻辑，应回到上游仓库（GitHub）提 PR，而不是在 skill 里复制代码。
- 批量转换：
pdf2word a.pdf b.pdf c.pdf --verify --report result.json，输出到各文件同目录；--report会得到结果数组。 - 字符数对账的容差：字符多出 <5% 属符号替换/格式微调的正常增量，不视为问题；超过 5% 才提示冗余。字符丢失 >2% 会单独告警。
License
本 skill 为薄包装；底层工具 pdf2word-review 采用 AGPL-3.0。详见 https://github.com/xiyanjun/pdf-to-word-review
