AI编程实战之PDF转Word的四种实现方式
以python-office的PDF转Word能力为核心，分别实现Python脚本、GUI程序、CLI工具和AI Skill，并说明各自的适用场景与技术边界。
学习目标
这篇笔记是《AI编程实战之Python-office自动化办公》的延伸，围绕 PDF 转 Word 这一项具体功能，学习四种不同的使用方式：
- Python 脚本：直接运行代码完成转换。
- GUI 程序：通过图形界面选择文件并执行转换。
- CLI 工具：在终端中通过命令和参数调用。
- AI Skill：把功能和使用说明整理成可供 AI 识别的工具。
这四种方式不是四套不同的 PDF 转换算法，而是同一个转换核心的四种入口。底层转换效果基本取决于所使用的 PDF 解析库、原始文件质量和文档结构，换一个界面并不会自动提高转换质量。
本文根据 2026 年 6 月的项目结构整理。
python-office仍在更新，函数路径和参数可能变化，运行前应查看当前版本的SKILL.md、官方示例或源码。
一、先认识PDF转Word的技术边界
PDF 更接近固定版面的最终输出格式，Word 则是可以继续编辑的流式文档。把 PDF 转为 Word，不是简单修改扩展名，而是重新识别文字、图片、表格和版面位置，再生成 DOCX。
1. 文本型PDF
文本型 PDF 中保存了真实文字，一般可以复制和搜索。此类文件比较适合直接转换，但仍可能出现：
- 字体被替换。
- 段落和换行位置变化。
- 分栏顺序识别错误。
- 表格边框或合并单元格发生变化。
- 公式、脚注和页眉页脚还原不完整。
2. 扫描型PDF
扫描型 PDF 的每一页通常是一张图片，没有可直接提取的文字。此类文件需要先进行 OCR，再把识别结果写入 Word。
OCR 结果受分辨率、倾斜、阴影、印章、手写内容和表格复杂度影响，必须人工校对。不要把 OCR 生成的文本直接作为合同、财务或档案材料的最终结果。
3. 加密或受限PDF
如果 PDF 设置了打开密码或权限限制，转换前需要合法取得密码和处理授权。本文只讨论对自己有权处理的文件进行格式转换，不涉及绕过访问控制。
二、准备项目环境
建议在新的练习目录中创建虚拟环境：
mkdir pdf-to-word-demo
cd pdf-to-word-demo
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -U python-office
检查安装结果：
python -m pip show python-office
python -c "import office; print('python-office 导入成功')"
如果准备开发 GUI，再安装 PySide6：
python -m pip install PySide6
PySide6 提供社区版和商业版。社区版涉及 LGPLv3/GPLv3 等许可证要求；如果要分发闭源软件或用于商业项目，应根据实际使用的 Qt 组件核对许可证义务，必要时选择商业授权，不能简单理解为“安装后可无条件商用”。
三、先封装统一的转换核心
无论后面采用哪种入口，都不应该复制四份转换代码。先建立一个统一的 converter.py，其他程序只负责接收参数、调用函数和显示结果。
from pathlib import Path
from office.skills.pdf import pdf2docx
def convert_pdf_to_word(input_file: str, output_file: str) -> Path:
pdf_path = Path(input_file).expanduser().resolve()
docx_path = Path(output_file).expanduser().resolve()
if not pdf_path.is_file():
raise FileNotFoundError(f"PDF文件不存在：{pdf_path}")
if pdf_path.suffix.lower() != ".pdf":
raise ValueError(f"输入文件不是PDF：{pdf_path.name}")
if docx_path.suffix.lower() != ".docx":
raise ValueError("输出文件必须使用.docx扩展名")
if pdf_path == docx_path:
raise ValueError("输入文件和输出文件不能相同")
docx_path.parent.mkdir(parents=True, exist_ok=True)
pdf2docx(input_file=str(pdf_path), output_file=str(docx_path))
if not docx_path.is_file():
raise RuntimeError("转换程序未生成Word文件")
return docx_path
当前项目文档将 PDF 转 Word Skill 记为 pdf2docx。如果实际安装版本无法按上述路径导入，应先查看该版本的官方说明，不要让 AI 凭空修改函数名。
四、方式一：Python脚本
Python 脚本是最直接的实现方式，适合个人使用、调试转换功能和学习接口。
新建 run_convert.py：
from converter import convert_pdf_to_word
result = convert_pdf_to_word(
input_file=r"D:\PDF测试\示例.pdf",
output_file=r"D:\PDF测试\输出\示例.docx",
)
print(f"转换完成：{result}")
运行：
python run_convert.py
适用场景
- 只在自己的电脑上使用。
- 正在调试参数和转换效果。
- 需要快速接入其他 Python 处理流程。
- 暂时不需要图形界面或命令安装。
注意事项
路径不要直接写成未经处理的单反斜杠字符串，例如 "D:\new\test.pdf" 中的 \n 可能被解释为换行。Windows 路径可以使用原始字符串 r"..."，也可以使用 pathlib.Path。
五、方式二：GUI图形界面
GUI 适合不熟悉命令行的使用者。它通常提供“选择 PDF”“选择输出目录”“开始转换”和“查看结果”等控件。
1. GUI只负责交互
一个清晰的 GUI 流程应是：
选择PDF -> 选择输出位置 -> 点击转换
-> 调用converter.py -> 显示成功或错误信息
界面不应重新实现 PDF 解析逻辑，而应调用前面封装好的 convert_pdf_to_word()。
2. 最小PySide6示例
新建 gui.py：
import sys
from pathlib import Path
from PySide6.QtWidgets import (
QApplication,
QFileDialog,
QLabel,
QMessageBox,
QPushButton,
QVBoxLayout,
QWidget,
)
from converter import convert_pdf_to_word
class PdfToWordWindow(QWidget):
def __init__(self):
super().__init__()
self.pdf_file = None
self.setWindowTitle("PDF转Word")
self.resize(420, 180)
self.status = QLabel("请选择一个PDF文件")
choose_button = QPushButton("选择PDF")
convert_button = QPushButton("开始转换")
choose_button.clicked.connect(self.choose_pdf)
convert_button.clicked.connect(self.convert)
layout = QVBoxLayout(self)
layout.addWidget(self.status)
layout.addWidget(choose_button)
layout.addWidget(convert_button)
def choose_pdf(self):
file_name, _ = QFileDialog.getOpenFileName(
self,
"选择PDF",
"",
"PDF Files (*.pdf)",
)
if file_name:
self.pdf_file = Path(file_name)
self.status.setText(str(self.pdf_file))
def convert(self):
if not self.pdf_file:
QMessageBox.warning(self, "提示", "请先选择PDF文件")
return
output_file, _ = QFileDialog.getSaveFileName(
self,
"保存Word文件",
str(self.pdf_file.with_suffix(".docx")),
"Word Files (*.docx)",
)
if not output_file:
return
try:
result = convert_pdf_to_word(
str(self.pdf_file),
output_file,
)
except Exception as exc:
QMessageBox.critical(self, "转换失败", str(exc))
return
QMessageBox.information(self, "转换完成", str(result))
app = QApplication(sys.argv)
window = PdfToWordWindow()
window.show()
sys.exit(app.exec())
运行：
python gui.py
3. GUI还需要继续完善
上面的代码只适合入门练习。正式使用时还应增加：
- 批量文件列表。
- 输出目录选择。
- 转换进度和取消按钮。
- 运行日志与失败清单。
- 防止界面在转换时失去响应的后台任务。
- 同名文件覆盖确认。
耗时转换不应长期运行在 GUI 主线程中，否则界面会卡住。可以在后续学习中使用 QThread、线程池或任务队列处理。
六、方式三：CLI命令行工具
CLI 是 Command-Line Interface 的缩写，即命令行界面。它适合批处理、脚本调用、定时任务和 AI 工具调用。
新建 cli.py：
import argparse
from converter import convert_pdf_to_word
def main():
parser = argparse.ArgumentParser(
description="将文本型PDF转换为Word文档"
)
parser.add_argument(
"-i",
"--input",
required=True,
help="输入PDF路径",
)
parser.add_argument(
"-o",
"--output",
required=True,
help="输出DOCX路径",
)
args = parser.parse_args()
result = convert_pdf_to_word(args.input, args.output)
print(f"转换完成：{result}")
if __name__ == "__main__":
main()
运行：
python cli.py -i "D:\PDF测试\示例.pdf" -o "D:\PDF测试\示例.docx"
查看帮助：
python cli.py --help
CLI的优势
- 参数明确，便于重复执行。
- 容易放入批处理脚本和计划任务。
- 可以被其他程序调用。
- 报错信息和退出状态更容易记录。
- AI 编程工具通常能够直接执行命令并读取输出。
CLI 并不会天然提高 PDF 的转换质量，也不能简单认为它一定比 GUI 更省模型 Token。CLI 的主要价值是接口清晰、自动化方便、容易组合；具体 Token 消耗取决于 AI 是否参与、传入了多少上下文以及调用流程如何设计。
七、把CLI安装成真正的命令
如果希望使用下面这种形式：
pdf-to-word -i "输入.pdf" -o "输出.docx"
需要把项目打包并声明命令入口。可以使用 pyproject.toml：
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "pdf-to-word-tool"
version = "0.1.0"
dependencies = [
"python-office"
]
[project.scripts]
pdf-to-word = "cli:main"
在项目目录中执行：
python -m pip install -e .
安装成功后测试：
pdf-to-word --help
项目名称、模块目录和打包配置应保持一致。正式分发前还要测试全新环境安装，不能只在开发电脑上验证。
八、方式四：AI Skill
AI Skill 可以理解为“功能代码 + 使用说明 + 调用约束”。它的目标是让支持 Skill 的 AI 工具知道：
- 这个工具能做什么。
- 什么时候应该使用。
- 需要提供哪些参数。
- 应该执行哪条命令或调用哪个函数。
- 成功和失败后如何反馈。
不同 AI 工具的 Skill 规范可能不同，并不存在一套对所有平台都完全通用的目录格式。创建 Skill 前，应先阅读目标工具当前版本的官方规范。
以一个简化的学习目录为例：
pdf-to-word-skill/
├── SKILL.md
├── cli.py
└── converter.py
SKILL.md 可以说明：
---
name: pdf-to-word
description: 将用户有权处理的文本型PDF转换为DOCX文件。
---
# PDF转Word
## 适用场景
- 用户明确要求把PDF转换为可编辑Word。
- 输入文件是本地PDF，输出文件使用.docx扩展名。
## 执行方式
运行：
`pdf-to-word -i "<输入PDF>" -o "<输出DOCX>"`
## 限制
- 扫描件需要先进行OCR。
- 不绕过密码或权限限制。
- 不覆盖原始PDF。
- 转换后提醒用户检查排版、表格和公式。
Skill 的说明要写清能力边界，不能只写“帮我转 PDF”。说明越准确，AI 越不容易在扫描件、受限文件或错误路径上盲目执行。
九、四种方式如何选择
| 实现方式 | 主要使用者 | 优点 | 需要注意 |
|---|---|---|---|
| Python脚本 | 开发者、学习者 | 最简单，便于调试 | 路径通常写在代码或配置中 |
| GUI程序 | 普通办公用户 | 直观，容易分发给同事 | 开发和打包较复杂，耗时任务会卡界面 |
| CLI工具 | 运维、开发者、自动化流程 | 参数清晰，容易批处理和组合 | 需要理解基本命令和错误输出 |
| AI Skill | 支持Skill的AI工具 | AI可根据说明选择并调用工具 | 规范与平台有关，必须明确权限和边界 |
推荐的学习顺序是：
先跑通Python脚本
-> 抽出统一转换函数
-> 封装CLI
-> 根据使用对象选择GUI或Skill
CLI 和 GUI 都应该调用同一个核心函数，Skill 则优先调用已经测试稳定的 CLI。这样修复转换逻辑时只需要修改一处。
十、怎样向AI描述开发需求
不要只说“帮我做一个 PDF 转 Word 软件”。可以使用下面的需求模板：
请基于当前安装版本的python-office开发PDF转Word工具。
运行环境：
- Windows 11
- Python 3.12
- python-office版本：填写pip show结果
输入：
- 单个文本型PDF文件
输出：
- 用户指定路径的DOCX文件
要求：
1. 转换核心单独放在converter.py中。
2. 检查输入文件、扩展名和输出目录。
3. 不修改或删除原PDF。
4. 输出文件已存在时先提示，不直接覆盖。
5. 错误信息使用中文并保留完整异常日志。
6. 先生成CLI版本，测试通过后再生成GUI。
资料：
- 附上当前版本pdf2docx的SKILL.md或官方示例。
AI 生成代码后，要逐个文件阅读，确认没有自动删除、覆盖、上传文件或写死敏感路径等行为。
十一、转换结果怎样验收
程序显示“转换成功”只代表生成了 DOCX，不代表内容完全正确。至少应检查：
- 输出文件能否正常打开。
- 页数和主要段落是否完整。
- 中文、英文和数字是否出现乱码。
- 图片是否缺失、错位或变形。
- 表格行列、合并单元格和边框是否正确。
- 公式、脚注、页眉页脚是否保留。
- 分栏文档的阅读顺序是否正确。
- 输出目录中是否出现意外临时文件。
测试时应准备几种不同类型的脱敏样例，包括纯文本、图文混排、表格、扫描件和加密文件。对扫描件应明确提示需要 OCR，不要静默生成空白或内容残缺的 Word。
十二、开源许可证与分发
开发和分发工具前，应分别检查：
python-office当前版本附带的许可证。- 底层 PDF 转换库当前版本的许可证。
- PySide6 及所用 Qt 模块的许可证。
- 打包工具和其他依赖的许可证。
许可证可能随版本变化。例如 pdf2docx 的历史版本和当前版本曾采用不同许可证，因此不能只看旧教程中的结论。项目仓库、已安装包和发布文件中的许可证应一起核对。
如果只是自己本地学习，风险通常较低；如果要把 GUI 打包给他人、收费销售或嵌入公司产品，就应认真履行许可证中的署名、源码、动态链接或商业授权要求。
十三、本篇小结
PDF 转 Word 的四种实现方式，本质上是同一转换能力面向不同使用者的四层封装：
- Python 脚本负责快速验证功能。
- GUI 为普通用户提供可视化操作入口。
- CLI 为批处理、系统任务和程序调用提供稳定接口。
- AI Skill 告诉 AI 何时以及怎样调用已经验证的工具。
正确的开发顺序不是让 AI 一次生成四套互不相关的代码，而是先封装并测试统一转换核心，再逐层增加入口。无论采用哪一种方式，都要承认 PDF 转 Word 的技术边界，并在转换后检查文字、图片、表格和排版。
技术指导来自：Python4Office