pdf-to-docx
Skill0 starsChanged 40 days agoMITView on GitHub
把 PDF 高保真重建为可编辑的 .docx,覆盖文字型、图片型(扫描件/图形页)与混合型。当用户要求「PDF 转 Word」「PDF 转 docx」「保持原格式」「扫描件转 Word」「照着 PDF 重建文档」或格式被转码工具搞乱需要重做时使用。
4 other projects use a version of this.
Adopted by
Most recently taken up by
- Anpolod/claude-skillstheir own version, first seen Nov 16, 2026
- ZeroTokenClaw/agents-skillstheir own version, first seen Sep 21, 2026
- genecheung/claude-skillstheir own version, first seen Jun 9, 2026
- claude-office-skills/skillstheir own version, first seen Jan 30, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- claude-office-skills/skills★ 433same name
- ZeroTokenClaw/agents-skills★ 1same name
- Anpolod/claude-skills★ 0same name
- genecheung/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Files
PDF → Word 高保真重建
把 PDF 变成可编辑、且版式贴近原件的 .docx。整套工具链内置在 DSH 运行时里, 不调用任何外部独立程序(不依赖 pdf2zh / pandoc / 第三方转换器)。
一、先理解:为什么 Claude 在这件事上表现好
不是因为它用了某个更强的库,而是因为它在这四个机制上都不偷懒。任何一条缺失,效果都会塌:
| # | 机制 | 具体含义 |
| 1 | 用眼睛读 PDF | 把页面渲染成图直接看。版式是视觉信息——「这是浅灰底三列表格」「这是悬挂缩进的列表」,只有看图才判得准。 |
| 2 | 当重建,不当转码 | PDF 是排版结果的快照,不是结构源。它是「一堆画在坐标上的字」。「转码」思维必然丢结构;必须按语义重建出段落、标题、列表、真表格。 |
| 3 | 直写 OOXML | 用 python-docx 精确控制页面尺寸、页边距、字号、行距、段后间距、字体 eastAsia,而不是靠中间格式碰运气。 |
| 4 | 渲染-比对-迭代 | 生成后渲染回图,与原 PDF 逐页比对,测出偏差再改。这一步最常被忽略,却是「保得住格式」的分水岭。 |
本技能把这四条固化成可执行的脚本流水线。
机制 1 有个速度陷阱:把「看图」当成主要信息通道。看图很贵(每次都是多模态往返), 正确的用法是抽查而不是通读。第九节的效率纪律把这一点量化为可执行的几条规则。
二、安装与分发(换一台机器也能跑)
技能目录是自包含的,整个 pdf-to-docx/ 复制到任意机器后先自检:
python scripts/bootstrap.py # 只自检,不改环境
python scripts/bootstrap.py --install # 缺什么装什么
python scripts/bootstrap.py --install --with-ocr --mirror # 连 OCR 一起装,走国内镜像零硬编码:脚本不写死任何本机绝对路径,按 「环境变量 → 常见安装位置 → PATH」逐级探测。需要覆盖时用环境变量:
| 变量 | 作用 |
PDF2DOCX_SOFFICE | 指定 soffice / libreoffice 路径 |
PDF2DOCX_WORD | 指定 WINWORD.EXE 路径 |
PDF2DOCX_RENDERER | 强制渲染器:word / libreoffice / none |
渲染器自动降级链:
Microsoft Word (COM,Windows,保真最高)
↓ 没有
LibreOffice (headless,跨平台)
↓ 都没有
跳过视觉验收 —— 内容抽取与 docx 生成仍然可用依赖分两档,缺可选依赖不会阻断文字型流程:
| 档位 | 组件 | 缺失后果 |
| 必需 | pymupdf、Pillow、python-docx | 无法运行 |
| 可选 | pdfplumber、rapidocr-onnxruntime、opencv | 复杂表格抽取变弱;图片型/扫描件无法 OCR |
三、快速开始(一条命令)
python scripts/pdf2docx.py in.pdf out.docx它会串起 分诊 → 抽取 → 重建 → 渲染 → 验收,并把中间产物放进 _pdf2docx/,
最后打印逐页比对表和结论。常用开关:
--pages 1-3 # 只处理部分页(先小样试跑,省时间)
--workdir W # 指定中间产物目录
--no-verify # 跳过渲染验收图片型 PDF 走同一条命令会给出OCR 初稿,并在输出里明确提示质量边界。
四、工具链(已内置)
Python 侧(由 bootstrap 安装到当前运行时):
| 能力 | 组件 |
| PDF 解析 / 渲染 | PyMuPDF(pymupdf) |
| 表格抽取 | PyMuPDF find_tables + pdfplumber |
| OCR(图片型) | rapidocr-onnxruntime(onnxruntime,纯 Python,模型内置) |
| 图像分析 | OpenCV headless + Pillow |
| docx 生成 | python-docx |
渲染回图侧:本机 Word COM(render_docx.ps1)。
用 Word 本体渲染,是因为验收要回答「这份 docx 在 Word 里打开长什么样」——
换任何第三方渲染器,分页与字体回退的差异都会掩盖真实问题。
脚本清单(scripts/):
| 脚本 | 一句话 |
bootstrap.py | 自检 / 安装依赖,写出 env.json |
probe.py | 分诊:逐页判 text / mixed / image / scanned / vector |
extract.py | 文字层 span → 行 → 段落 → 块(+ 抽正文图) |
render_pages.py | 整页渲染成图(版式判读用) |
ocr.py / ocr_to_spec.py | 图片型 OCR 初稿 → 结构规格 |
verify_sheet.py | 把待确认行带拼成 1~2 张长图,一次看完 |
prespec.py | 渲染前的页面高度 / 折行预检(纯算术,不启动 Word) |
build_docx.py | 结构 → 真 OOXML(页面尺寸/字体/缩进/高度预算) |
render_docx.ps1 / render_docx.py | docx → PDF(Word COM,降级 LibreOffice) |
compare.py | 逐页数值比对 + 并排对照图 + 差异热图 |
measure_ink.py / diag_fit.py / diag_lines.py | 版面度量与高度诊断 |
五、流程
Phase 0 分诊 probe.py → 判定类型,选路线
Phase 1 取素材 render_pages.py + ocr.py → 全页图 + OCR 初稿(并行开)
Phase 2 定结构 测量脚本一次成型 + verify_sheet.py 拼版校对
Phase 3 预检 prespec.py → 渲染前拦下溢出
Phase 4 生成 build_docx.py → .docx
Phase 5 验收 render_docx.ps1 → compare.py → 按需迭代Phase 0 · 分诊
python <skill>/scripts/probe.py in.pdf --json probe.json按「文字层字符数 / 图片面积占比 / 矢量绘制数」把每页分成:
| 类型 | 特征 | 路线 |
text | 有完整文字层 | A:几何直接可读,不需要 OCR |
mixed | 有文字层 + 大图 | B:文字精确抽取 + 图片按位还原 |
image | 每页几乎 0 字符、整页位图 | C:OCR + 视觉判读双通道 |
scanned | 整页位图、有倾斜噪声 | C:先校正去噪再走 C |
vector | 文字转曲线,无文字层 | D:从 get_drawings() 反推色块,OCR 补文字 |
判断依据是实测数字,不是文件名或猜测。
Phase 1 · 取素材
路线 A/B(有文字层)——直接抽几何:
python <skill>/scripts/extract.py in.pdf --out blocks.json [--images imgs/]抽出 span 级 (text, font, size, color, bbox, flags),再聚成 行 → 段落 → 文档块。
路线 C/D(无文字层)——两条通道并行开,不要串行:
python <skill>/scripts/render_pages.py in.pdf --outdir pages/ --dpi 160 --tile # 通道一:整页图
python <skill>/scripts/ocr.py in.pdf --out ocr.json --dpi 200 # 通道二:全文 + 坐标整页图只用来看版面结构(几栏、哪里是表格、层级如何),不要用它去抠每一个词。 术语与拼写交给下面的拼版校对。
Phase 2 · 定结构(关键分工)
两条通道各有短板,必须融合,这也是整个方案的核心:
| 通道 | 强在 | 弱在 |
| 视觉判读(我自己看图) | 判层级、分栏、表格归属、阅读顺序;修正专业术语与中英混排 | 拿不到精确坐标、字号、颜色值 |
| OCR / 几何抽取 | 坐标准、字号准、能算 | 会丢字、吞空格、写错专业词 |
实测例证:OCR 把 John Ka-Kit Leung (梁嘉傑) 读成 JohnKa-Kit Leung(梁嘉)——
丢了「傑」、吞了空格;而看图能读对,却量不出它在页面的 y=75.8。
融合规则:视觉决定「是什么」,OCR/几何决定「在哪、多大」。
证词要用拼版一次取(别一行一行裁)
OCR 会写错专业词,所以必须人眼复核——但复核要一次做完。把待确认的行带
拼成一张长图,一次 read_image 看完:
python <skill>/scripts/verify_sheet.py in.pdf --auto 1,3 --outdir sh/ # 自动切行带
python <skill>/scripts/verify_sheet.py in.pdf \
--at "1:93:112:P1 caption" --at "3:675:710:P3 sub-a" --outdir sh/ # 手工给点
python <skill>/scripts/verify_sheet.py in.pdf --spec regions.json --outdir sh/ # 批量给点产出 sh/sheet_001.png(每格左侧有 #序号 标尺)与 sh/verify_map.json
(序号 → 页码 / y 区间 / 标签,看图时对照)。单张超过 --max-side 会自动分张。
反面教材:一次 5 页公文的实测里,逐行裁剪 + 逐行读图共 35 次调用, 其中为了确认一个词(
Liquidating还是Liqudating)裁了 6 次——而且最早那张 低分辨率裁剪给出的是错读。同样的事拼成一张图只需 1 次。
产出物
图片型 PDF 的推荐产出物不是 blocks.json,而是我直接写的 Markdown 重建稿,
然后把页面几何交给 build_docx.py 的 --preset:
python <skill>/scripts/build_docx.py rebuild.md out.docx --preset page.json(Markdown 里的 ## → 色块标题,- → 列表,| → 真表格。)
版面复杂到 Markdown 表达不了时(边框盒、单元格底纹、制表位对齐、域),
就写一份显式的 blocks.json,或按 build_docx.py 的 build_from_blocks 契约
自己直写 OOXML——技能不强制走引擎。
Phase 3 · 预检(渲染前,纯算术)
在启动 Word 之前先算一遍高度预算——这一步专门用来省掉最贵的往返:
python <skill>/scripts/prespec.py spec.json --preset page.json -v它按与 build_docx.py 完全相同的口径估算每一页:
每页需要高度 = Σ(各段折行数 × 行距) + (段数 − 1) × 段后间距再与「目标高度」(优先取原页实测内容高度 page_meta[].content_h_pt,
退而用页面可用高度)比对,给出 ok / tight / overflow,以及该压哪个参数:
页 判定 块 行 固定 间距 需要 目标 建议
1 overflow 20 52 882.4 136.3 1018.7 522.4 line_pt × 0.592(并置 space_after=0)
结论: ok=0 tight=0 overflow=1 共 1 页退出码 1 表示有页溢出——先改内容或版式,再渲染。-v 展开最紧张那页的逐段明细。
Phase 4 · 生成
build_docx.py 负责把结构写成真 OOXML。三个决定成败的细节:
- 页面尺寸与页边距按实测值写入,不套 Word 默认值。
- 字体同时写
w:rFonts的ascii/hAnsi(拉丁)与eastAsia(东亚)—— 只设run.font.name中文会回退乱字体。 - 高度预算:原 PDF 的某些页是「满页」,重建只要多出几磅就会把末尾几行挤到 下一页,而一旦有一页溢出,后面所有页的对应关系全部错乱。 引擎因此按页估算高度并对段后间距做等比收缩;分页用分节(section break) 而非分页符,切断级联误差。
Phase 5 · 验收(不能省)
pwsh -NoProfile -File <skill>/scripts/render_docx.ps1 -InFile out.docx -OutFile out.pdf
python <skill>/scripts/compare.py in.pdf out.pdf --outdir diff/产出三种证据:数值表 + 逐页并排对照图(左原 / 中结果 / 右差异热图)。
六、验收标准
两条指标回答的是不同问题,不要混为一谈:
| 指标 | 回答什么 | 期望 |
text_similarity | 内容有没有丢、有没有错 | ≥ 0.995 理想;≥ 0.98 合格 |
pixel_hot_ratio | 版面接近程度 | ≤ 0.20 正常 |
| 页数一致 | 分页有没有漂 | 必须相等 |
图片型 / 扫描件的
text_similarity恒为N/A:原文没有文字层,取不到基准。compare.py会把该指标标成N/A并只按版面接近度判定(≤10% pass,≤25% warn), 同时在结论下方打印一行说明。若输出里看到的是0.000而不是N/A, 说明跑的是旧版脚本——那是一个「无法评估」被误报成「内容全错」的假指标。
像素差异永远不可能为 0:换行位置、字体渲染、微调间距都会产生差异。 拿像素差当唯一标准会陷入无意义的追打;有文字层时内容相似度才是硬指标。
实测基准(一份 6 页文字型简历,612×792pt):
结论: pass=5 warn=1 fail=0
页 1 相似度 1.000 像素差 10.7%
页 2 相似度 1.000 像素差 9.7%
页 3 相似度 1.000 像素差 7.2%
页 4 相似度 0.998 像素差 7.2%
页 5 相似度 0.956 像素差 8.4%
页 6 相似度 0.992 像素差 3.7%实测基准(一份 5 页扫描件公文,552×765pt,无文字层):
页 1..5 像素差 8.3% / 8.7% / 9.0% / 8.5% / 4.1% 文本相似 N/A(原文无文字层)七、踩过的坑(都是实测出来的,别重犯)
- 页边距不能按「第一页最后一行的位置」推。内容少的页天然排不满, 那反映的是内容长度,不是页边距。实测:按单页推得底边距 136pt, 真实值 72pt——可用高度被压掉 56pt,内容直接溢出。必须跨页取极值聚合。
- 段内行距基准要取分布的小分位(p25),不能取中位数。 段落密集的页里段间距可能占多数,中位数会落在段间距上: 实测某页行距被算成 24.72pt(真实 14.88pt),重建后高度虚高 100pt+。
- 行距≠行高。用
行高 × 1.32估行距会偏大(实测 17.03 vs 真实 14.88), 足已把满页内容挤到下一页。行距应当直接量相邻行 y0 的差值。 - 段后间距属于「前一段」,不是后一段。挂反了标题后面就会贴住正文。
- 段后间距要按「行框跨度」反推,别按墨迹顶反推。墨迹顶受首字符影响 (大写/括号/无升部字母各不相同),实测同一份文件里能算出 12.8 / 14.7 / 15.7 三个值。用「折行数 × 行距 + (段数 − 1) × 段距 = 行框跨度」整体解,才收敛到 12.8。
- PDF 常把项目符号「•」单独放一行,与文字行分成两个对象。
只按行首字符判列表会得到一堆孤立的
•。要按几何关系合并: 符号行 x0 更小、文字行更深,差值就是悬挂缩进宽度。 - 扫描件各页之间常有平移错位,别拿单页去定版心。判断方法很便宜: 页码是居中的,用各页页码中心反解出每页平移量;归到同一坐标系后, 所有元素的左边界应当落在等距的缩进梯级上。实测奇偶页错位 ±23.5pt, 归位后梯级干净地落在 44/62/80/98/116(步长 18pt = 0.25″)——这才证明版式是齐的。
- Word 默认不做字距调整(kerning),源文档往往做了。差之毫厘:整行比原件宽约
0.5%,而原件里「贴边」的行(离版心右缘不足 1pt)就会提前断行、多出一行,
进而把整页挤到溢出。修法:给
w:rPr加<w:kern w:val="8"/>(docDefaults 也要加)。 仍不够时再把版心放宽几 pt——版心宽度一致比页边距好看更重要。 - 表格单元格里模板自带的那个空段落会毁掉盒子几何。
cell.paragraphs[0]带的是 Normal 样式(1.15 倍行距 + 8pt 段后),留着它, 边框盒会凭空高出一大截(实测盒子从 84pt 涨到 126pt)。填内容前先删掉它。 - 跨页的段落要按原件的断点人工切分。原 PDF 常在段落中间分页;若把整段整体 放进前一节,末几行会被顶到下一页,连带后面所有页错位。切成「前半段 + 续段」, 续段沿用原件的悬挂缩进即可。
- 用表格排双栏落款会整块跳页。Word 的行不能被拆时会把整个表推到下一页; 改成「左缩进 + 制表位」的普通段落,两栏照样对齐,还不会跳。
- 标签与取值之间是对齐到制表位,不是空格。原件用的就是 Word 默认的 0.5″
制表网格(从版心左缘起算):
Objection Deadline:落到 144pt、Responses:→ 108pt、Status:要补两个空格才够到 108pt——把三个都量出来,规律就自明,照抄即对齐。 另外下划线只给标签,不要覆盖补位的空格。 - PowerShell 参数别用
$Input——它是自动变量,会导致取到空值。 pwsh -File里不要指望ExportAsFixedFormat的参数绑定, 12 个可选参数在 PS 下不稳,用SaveAs2($path, 17)。- PyMuPDF ≥1.28 的
get_pixmap(dpi=)只接受 int,传 float 抛 TypeError。 - 控制台中文乱码:脚本开头要
sys.stdout.reconfigure(encoding="utf-8")。 bootstrap.py曾崩在report["missing_required"]:_runtime.env_report()已把这两项归约成 pip 名称字符串列表,bootstrap却按 dict 取值 ([d["pip"] for d in ...])→TypeError: string indices must be integers。 改env_report或改调用方都行,但别只改一边——这是两个文件之间的隐式契约。
八、图片型 PDF 的额外注意
- 渲染 dpi 选 160:9pt 小字能看清,又不至于让单页图太大。
- 扫描件先做倾斜校正再 OCR,否则行会被切碎。
- 装饰性背景(色块、弧线、纹理)有两条策略,按需求选:
- 要可编辑:用色块标题的段落底纹 + 边框重绘(
build_docx.py已支持shade/border_bottom)。 - 要高保真:整页底图 + 文字层,代价是背景不可编辑。
- 要可编辑:用色块标题的段落底纹 + 边框重绘(
- 正文照片要抽原图(
extract.py --images),不要截屏,否则清晰度会掉。 - 专业术语务必用视觉复核 OCR 结果:
ISO55000、FSOE、SMIEEE、CEnv这类缩写,OCR 极易写错,而错一个字符整份文档的专业度就打了折扣。 ——复核走verify_sheet.py,一次看一批。 - 合成扫描件要当心:有的 PDF 是「低分辨率整页底图 + 若干高清文字行贴片」拼出来的。
probe.py会把它判成image(确实没有文字层),但get_images()能看出结构。 这种文件的文字清晰度不均匀,别按底图的 dpi 去判断可读性。 - 页数对不上先看是不是空白页:扫描件常多出一页背面空白。若原件第 N 页零墨迹 而文档自带的页眉写着 "Page x of N−1",就按 N−1 出——并在交付时说明, 不要默默少一页。
九、效率纪律(实测:50 分钟 → 15 分钟量级)
一次 5 页扫描件公文的重建实测:50 分 18 秒、118 次工具调用、约 40 个模型轮次。 复盘后瓶颈很清楚——不是哪个脚本慢,是轮次太多:
| 阶段 | 调用数 | 占比 |
| 分诊 + 读全页 | 13 | 11% |
| 测量 + 逐行校对 | ~63(28 次裁剪 + 35 次看图) | 53% |
| 建模 | 3 | 3% |
| 渲染迭代 | ~25(7 次 Word 渲染) | 21% |
| 收尾 | 5 | 4% |
四条纪律(按收益排序):
- OCR 先出全文底稿,别靠肉眼读完整篇。 OCR 一次调用给你全文 + 坐标, 眼睛只用来裁决它读不准的那几个 token。那次装了 OCR 却全程靠肉眼,纯浪费。
- 校对走拼版,一次看完。 见 Phase 2 的
verify_sheet.py。看图调用 35 → 3。 - 测量脚本一次成型。 别写
measure→measure2→runs→lineext四个脚本 跨三个阶段取同一批数。第一个脚本就输出全量:每页行带 / 每块行数 / 行距·段距分布 / 左右极值 / 字号反推。后面只查询,不重写。 - 渲染前先跑
prespec.py。 溢出是算术问题,不是渲染问题。那次渲染了 7 次, 其中 4 次纯粹在补一个本可提前算出来的溢出。预检到位后 7 → 2。
另有两处小损耗值得防:技能自带脚本报错时先绕过、顺手记下来(那次
bootstrap.py 崩了却没第一时间处理);以及页面尺寸策略要一开始就定死
(原件实测 vs 标准 Letter),别在流程中途反复权衡。
但有一条不能省:视觉证词必须分辨率足够、一次看对。同一段文字,低分辨率
裁剪把它读成 Liqudating(错),高分辨率才读对 Liquidating。结论不是「少看」,
是「起点就看清 + 批量看」。
十、局限(诚实说明)
- 复杂多栏 + 跨栏表格的版面,段落阅读顺序仍可能判错,需要人工/视觉逐页复核。
- 数学公式会被还原为线性文本,不做公式对象重建。
- 表格跨页时的拆分逻辑依赖 Word 自身行为,与原 PDF 可能不一致。
- 图纸、海报这类以图形为主的页面,重建的可编辑版本在观感上必然与原图有差距, 此时应主动与用户确认:要「可编辑」还是「保观感」。
- 原件里贴边到亚磅级的行,其断行位置对渲染器差异极其敏感;换机器/换字体版本 可能出现一两行位移,这是排版引擎固有差异,不是重建错误。
- 页数必须自己核:
compare.py只在两端页数相等时逐页比对;原件多出空白页 或重建少一页,都会整表错位——先解决页数,再看相似度。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

