PDF Toolkit（PDF 全能工具箱）

Overview

一个面向 PDF 文件处理的 CLI 工具箱，覆盖主流 PDF 工具网站的两类核心能力：格式转换（18 种互转方向）和 编辑处理（30+ 种操作）。所有操作支持单文件或批量（目录 / 通配符），失败时跳过并汇总，不中断整体任务。

核心脚本：scripts/pdf_toolkit.py（基于 PyMuPDF/fitz + pdfplumber + Pillow，可选依赖按需启用）。

When to use

触发词与场景示例：

格式转换类

• PDF → Office：「把 PDF 转成 Word」「PDF 转 Excel」「PDF 转 PPT」「图片型 PDF 转可编辑 Word」
• Office → PDF：「把 Word 转成 PDF」「Excel 导出为 PDF」「PPT 转 PDF」
• PDF → 图片：「PDF 转图片」「PDF 转 JPG/PNG」「每一页都导出成图」
• 图片 → PDF：「这些图片合成一个 PDF」「JPG 转 PDF」
• 其他格式：「PDF 转 TXT 提取文字」「PDF 转 EPUB 电子书」「OFD 转 PDF」「HTML 转 PDF」「CAD 转 PDF」
• OCR 识别：「识别这个扫描件 PDF 的文字」「PDF OCR」

编辑处理类

• 页面操作：「合并多个 PDF」「按页拆分 PDF」「抽取第 3-5 页」「删除某些页」「调整页面顺序」「旋转某一页」
• 压缩优化：「压缩这个 PDF」「把 PDF 压小一点」「PDF 太大了」
• 安全保护：「给 PDF 加密」「设置 PDF 密码」「解除 PDF 密码」「设置 PDF 权限（禁止打印/复制）」
• 水印标注：「给 PDF 加水印」「PDF 加文字/图片水印」「给每页加页眉页脚」「加页码」
• 几何变换：「裁剪 PDF 页面」「统一改页面尺寸为 A4」「PDF 页面缩放」「把这几页拼成长图」
• 内容提取：「提取 PDF 里的图片」「提取 PDF 文字内容」「把 PDF 每页转成一张图（栅格化）」
• 高级操作：「扁平化 PDF（把文字变图像）」「修改 PDF 元数据（标题/作者）」「修复损坏的 PDF 文件」

Dependencies（运行前确认）

必需依赖

pip install PyMuPDF pdfplumber Pillow

按需依赖（首次用到时提示安装）

建议在虚拟环境安装：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows
pip install PyMuPDF pdfplumber Pillow python-docx openpyxl python-pptx

Workflow

1. 确认输入：拿到 PDF 路径 / 目录 / 通配符，确认目标操作与参数。
2. 确认依赖：根据目标操作检查必需及可选依赖；缺失则先安装再执行。
3. 执行脚本：调用 scripts/pdf_toolkit.py 对应子命令。可用 --output 指定输出目录，否则默认写入 <输入文件所在目录>/output/。
4. 汇总反馈：报告成功/失败数量与输出路径；对失败的文件说明原因。

脚本统一入口：

python scripts/pdf_toolkit.py <子命令> <输入...> [选项]

Operations（子命令速查）

一、格式转换（Conversion）

convert — 通用格式转换

# PDF → 图片
python scripts/pdf_toolkit.py convert input.pdf --format jpg --dpi 200
python scripts/pdf_toolkit.py convert input.pdf --format png --pages 1-3

# PDF → 文本
python scripts/pdf_toolkit.py convert input.pdf --format txt

# 批量转换目录下所有 PDF
python scripts/pdf_toolkit.py convert "./pdfs/*.pdf" --format png --output ./images/

• --format：目标格式 jpg / png / bmp / tif / txt
• --dpi：输出图片分辨率（默认 150）
• --pages：指定页码范围，如 1-3,5,8-10（默认全部）

toword — PDF 转 Word

# 普通 PDF → Word（保留文本和排版）
python scripts/pdf_toolkit.py toword input.pdf --output ./doc/

# 图片型/扫描件 PDF → Word（先 OCR 再生成）
python scripts/pdf_toolkit.py toword scanned.pdf --ocr --lang chi_sim+eng

• --ocr：启用 OCR 模式（用于扫描件/图片型 PDF）
• --lang：OCR 语言（默认 chi_sim+eng）

toexcel — PDF 转 Excel

python scripts/pdf_toolkit.py toexcel table.pdf --output ./xlsx/
# 自动检测表格区域，每个表格输出为一个 sheet

toppt — PDF 转 PPT

python scripts/pdf_toolkit.py toppt slides.pdf --output ./pptx/
# 每页 PDF 生成一页幻灯片

topdf — 其他格式转 PDF

# 图片 → PDF
python scripts/pdf_toolkit.py topdf *.jpg --output result.pdf

# Word → PDF（需要 Word 或 LibreOffice）
python scripts/pdf_toolkit.py topdf document.docx --output result.pdf

# HTML → PDF
python scripts/pdf_toolkit.py topdf page.html --output result.pdf

ocr — PDF OCR 文字识别

python scripts/pdf_toolkit.py ocr input.pdf --lang chi_sim+eng --output ./ocr_result/

• 输出：带文字层的新 PDF（可选择同时输出纯文本 .txt）
• --lang：识别语言（默认 chi_sim+eng）

二、页面操作（Page Operations）

merge — 合并 PDF

python scripts/pdf_toolkit.py merge part1.pdf part2.pdf part3.pdf -o merged.pdf
python scripts/pdf_toolkit.py merge "./chapters/*.pdf" -o book.pdf

• 按传入顺序拼接，支持通配符批量合并

split — 拆分 PDF

# 拆分为单页
python scripts/pdf_toolkit.py split input.pdf --mode single --output ./pages/

# 按页码范围拆分
python scripts/pdf_toolkit.py split input.pdf --mode range --ranges 1-5,6-10,11-

# 按指定页码提取
python scripts/pdf_toolkit.py split input.pdf --mode extract --pages 1,3,5-8

delete-pages — 删除页面

python scripts/pdf_toolkit.py delete-pages input.pdf --pages 2,4,7-9 -o trimmed.pdf

reorder — 调整页面顺序

python scripts/pdf_toolkit.py reorder input.pdf --order 3,1,2,5,4 -o reordered.pdf

rotate — 旋转页面

# 统一旋转所有页
python scripts/pdf_toolkit.py rotate input.pdf --angle 90 -o rotated.pdf

# 指定页旋转
python scripts/pdf_toolkit.py rotate input.pdf --angle 270 --pages 1,3,5 -o rotated.pdf

• --angle：旋转角度 90 / 180 / 270

extract-images — 提取图片

python scripts/pdf_toolkit.py extract-images input.pdf --output ./images/
# 提取 PDF 中嵌入的所有图片资源

extract-text — 提取文字

python scripts/pdf_toolkit.py extract-text input.pdf --output text.txt
# 提取全部文本内容，保留段落结构

rasterize — 栅格化（PDF 页面转图片再封装回 PDF）

python scripts/pdf_toolkit.py rasterize input.pdf --dpi 200 -o flattened.pdf
# 将矢量内容转为图像，常用于"扁平化"或去除可编辑层

三、优化与保护（Optimize & Security）

compress — 压缩 PDF

python scripts/pdf_toolkit.py compress input.pdf -o compressed.pdf
# 自动压缩图片、移除重复对象、优化交叉引用
python scripts/pdf_toolkit.py compress input.pdf --quality medium -o out.pdf
# --quality: low / medium / high（默认 medium）

• 输出压缩前后体积对比与节省比例

encrypt — 加密 PDF

# 设置打开密码
python scripts/pdf_toolkit.py encrypt input.pdf --password "123456" -o secured.pdf

# 设置权限密码（限制打印/复制/编辑）
python scripts/pdf_toolkit.py encrypt input.pdf --owner-pass "owner123" \
    --user-pass "user123" \
    --no-print --no-copy --no-edit \
    -o restricted.pdf

• 权限选项：--no-print / --no-copy / --no-edit / --no-annotate / --no-modify

decrypt — 解密 PDF

python scripts/pdf_toolkit.py decrypt input.pdf --password "123456" -o unlocked.pdf

四、水印与标注（Watermark & Annotation）

watermark — 添加水印

# 文字水印
python scripts/pdf_toolkit.py watermark input.pdf --text "机密文件" \
    --opacity 0.15 --angle 45 -o watermarked.pdf

# 图片水印
python scripts/pdf_toolkit.py watermark input.pdf --logo logo.png \
    --scale 0.2 --position center -o watermarked.pdf

• --opacity：透明度 0-1（默认 0.15）
• --angle：文字旋转角度（默认 45°）
• --scale：logo 相对页面宽度的比例（默认 0.2）
• --position：center / tile（平铺）/ diagonal（对角线排列）

header-footer — 页眉页脚 / 页码

# 添加页码
python scripts/pdf_toolkit.py header-footer input.pdf --page-number \
    --format "第 {n} 页 / 共 {total} 页" --position bottom-center -o numbered.pdf

# 添加页眉
python scripts/pdf_toolkit.py header-footer input.pdf --header "公司内部文件" \
    --font-size 10 -o headed.pdf

# 同时添加页眉页脚
python scripts/pdf_toolkit.py header-footer input.pdf \
    --header "机密文档" --footer "© 2026 公司名" --page-number -o full.pdf

五、几何变换（Geometry）

crop — 裁剪页面

python scripts/pdf_toolkit.py crop input.pdf --margin 50 -o cropped.pdf
# 四边各裁掉 50pt
python scripts/pdf_toolkit.py crop input.pdf --box "50 50 500 700" -o cropped.pdf
# 指定裁剪区域 [x0 y0 x1 y1]（单位 pt）

resize — 修改页面尺寸

python scripts/pdf_toolkit.py resize input.pdf --size A4 -o resized.pdf
python scripts/pdf_toolkit.py resize input.pdf --width 595 --height 842 -o resized.pdf
# --size: A3 / A4 / A5 / Letter / Legal，或自定义宽高（单位 pt）

• 内容自动适配（缩放/居中/拉伸，默认缩放适应）

scale-page — 缩放页面内容

python scripts/pdf_toolkit.py scale-page input.pdf --factor 0.8 -o scaled.pdf
# --factor: 缩放比例（0.1-5.0）

stitch — 拼接页面为长图/PDF

# 将多页在垂直方向拼接成一页（适合手机阅读的长图）
python scripts/pdf_toolkit.py stitch input.pdf --direction vertical -o long.pdf
# 将多页在水平方向拼接（适合对比并排）
python scripts/pdf_toolkit.py stitch input.pdf --direction horizontal -o wide.pdf

六、高级操作（Advanced）

flatten — 扁平化 PDF

python scripts/pdf_toolkit.py flatten input.pdf -o flat.pdf
# 将注释/表单域/文字层压平为不可编辑的静态内容

metadata — 修改元数据

python scripts/pdf_toolkit.py metadata input.pdf \
    --title "年度报告" --author "张三" --subject "2026 Q1" \
    --keywords "报告,财务" -o meta.pdf

• 可设字段：--title / --author / --subject / --keywords / --creator / --producer
• 不传任何字段则显示当前元数据

repair — 修复损坏的 PDF

python scripts/pdf_toolkit.py repair broken.pdf -o fixed.pdf
# 尝试恢复受损的 PDF 交叉引用和对象流

批量处理模式

所有子命令均支持批量输入：

# 通配符
python scripts/pdf_toolkit.py convert "*.pdf" --format jpg

# 目录（递归）
python scripts/pdf_toolkit.py compress ./documents/ --recursive --output ./compressed/

# 文件列表
python scripts/pdf_toolkit.py merge $(cat file_list.txt) -o all.pdf

批量模式下：
- 每个文件独立处理，互不影响
- 单个文件失败不中断整体任务
- 最终汇总：成功 N 个 / 失败 M 个（附原因列表）
- 输出保持原有文件名（扩展名随目标格式变化）

错误处理

注意事项

1. 大文件处理：超过 100MB 的 PDF 建议先用 compress 压缩再进行其他操作
2. 加密 PDF：大部分操作需要先 decrypt；encrypt 本身不受影响
3. 扫描件 PDF：文字提取/转 Word 需要加 --ocr 参数
4. 中文支持：确保系统已安装中文字体；OCR 需要 chi_sim 语言包
5. 输出覆盖：默认不覆盖已有文件，如需强制覆盖加 --force

支付宝付费改造契约（PAYSKILL）

本技能为付费技能（PAYSKILL）。调用遵循支付宝 AI 生意画像契约，由平台调度层执行 probe → pay → complete → ack 流程：

1. probe（探测）：平台调用前先探测是否已持有本技能的支付宝有效订阅 / 付费凭证。已付费则直接放行。
2. 402 Payment-Needed：未付费时，脚本向标准输出返回 HTTP 状态 402 与 Payment-Needed 标记，提示用户通过支付宝完成付费（pay），平台据此唤起付费页。
3. complete（扣费确认）：用户在支付宝完成扣费后，平台下发 Payment-Proof（付费凭证）。
4. ack（验签放行）：平台携带 Payment-Proof 重试本次调用；scripts/payment_gate.py 验签该凭证，确认有效后放行主流程。

订阅持久化与幂等：

• 付费状态缓存在本地 .pay_cache/state.json，避免每次调用重复付费（订阅持久化）。
• 同一 Payment-Proof 在 24h 幂等窗口内仅生效一次，避免重复扣费。

现金流改造后的调用套路：

用户调用 → 平台 probe  →
   未付费：下发 402 Payment-Needed → 支付宝 pay → complete → 下发 Payment-Proof
已付费/携带 Proof：脚本 ack 验签 → 放行主流程

> 本契约由 SkillHUB 平台调度层解析，脚本本地仅处理 402 / 验签 / 持久化 三环节；付费本体交给支付宝。

支付宝 AI 按量付费（Machine Pay / A2M）改造说明

本 Skill 已按支付宝官方 A2M 协议改造为 Pay Skill，付费闸口位于 scripts/payment_gate.py，统一调用云端计费服务 https://pay.pembroli.cn/api/resource。

付费流程

1. 未付费调用时，服务端返回 HTTP 402 + Payment-Needed 头，携带金额、商户、订单号及 RSA2 签名。
2. 买家侧 payment_gate.py 收到 402 后引导用户完成支付，平台回传 Payment-Proof。
3. 客户端携带 Payment-Proof 重试资源端点。

验付调用

服务端收到 Payment-Proof 后，调用支付宝验付接口（alipay.aipay.agent.payment.verify）核验凭证有效性（trade_no、out_trade_no、active 状态），验证失败返回 400，验证通过才进入资源发放。

履约确认

资源发放成功后，服务端异步调用履约确认接口（alipay.aipay.agent.fulfillment.confirm，trade_no）回执，标记本笔订单已履约；并按 out_trade_no 做幂等，重复请求直接返回已缓存结果，杜绝重复收费。

幂等与缓存

买家侧按 slug 本地缓存 Payment-Proof（24h TTL），有效期内免重复支付；服务端按订单号幂等，保证同一笔订单只履约一次。