Metadata

name: pdf2word-review
slug: pdf2word-review
version: 0.1.0
displayName: PDF转Word质量复核
author: hectorlee
description: PDF 转 Word 并自动质量复核。将 PDF 转为可编辑的 Word 文档（自动检测文字层、空段落清理、排版优化），并对转换结果做四项对账（字符数/表格数/图片数/表格单元格数）+ 页数参考，自动发现内容丢失或冗余，输出中文质量报告。当用户要求「PDF 转 Word」「PDF 转 docx」「转换质量检查」「转换后对账」，或担心 PDF 转 Word 会丢内容、需要验证转换结果是否完整时使用。
tags: ["pdf","word","docx","conversion","quality-review","ocr","转换","质量复核","对账"]
agent_created: true

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

PDF to Word Review

安装技能