PDF 工具箱

十个常用 PDF 操作，全部在本地完成，文件不出本机。

何时使用

• 用户说「把几个 PDF 合起来」「拆成单页」「只要第 3-5 页」「转成图片」「加个水印」「设个密码」「压缩一下」
• 扫描/回签文件需要合并、去页、加密码

不适用（请明确告知用户，不要勉强调用）：
- OCR / 扫描件文字提取 → 本技能不做识别
- PDF 转 Word / Excel → 不做格式重排
- 表单填写、在线传输、云同步 → 不做

环境准备（首次一次即可）

python scripts/setup.py          # 缺依赖自动安装
python scripts/setup.py --check  # 只检查

> 所有依赖均为 BSD / Apache / MIT 等宽松许可证。

十个子命令

常用示例

# 把三份合同合成一份
python scripts/pdfbox.py merge 合同1.pdf 合同2.pdf 合同3.pdf --out 合并.pdf

# 每 2 页拆一份（默认每 1 页）
python scripts/pdfbox.py split 标书.pdf --every 2

# 只要第 1-3 页和第 7 页，各出一份
python scripts/pdfbox.py split 标书.pdf --ranges "1-3;7"

# 加密后发给客户
python scripts/pdfbox.py encrypt 报价单.pdf --user-pw 8888

# 满页斜向水印，防外传
python scripts/pdfbox.py watermark 内部资料.pdf --text "机密 · 禁止外传" --opacity 0.2

# 把扫描图拼成 PDF（手机拍照存档）
python scripts/pdfbox.py from-images 第1页.jpg 第2页.jpg 第3页.jpg --name 扫描件

页码怎么写

统一格式：1-3,5,7- （第 1 到 3 页、第 5 页、第 7 页到末页）。
超出页数会明确报错并给出该文件实际页数。

行为约定

1. 不覆盖源文件：产物写到 --out（文件）或 --outdir（目录，默认 ./pdfbox_output）。
2. 加密 PDF 明确提示：未给密码时报「该 PDF 已加密，请用 --password 提供密码」；密码错报「密码错误，无法解密」。
3. 不静默失败：文件损坏、非 PDF、页码越界都会给出具体原因和修复方向。
4. 任何异常都有干净提示：不会抛出 Python 原始堆栈。
5. split 命名可读：按页拆为 原名_001-002.pdf，按范围拆为 原名_part1_p1-3.pdf。

已知限制（会明确报错，不会装作成功）

> 加水印的重要说明：为保证中文与透明度效果，水印通过「逐页栅格化 → 叠水印 → 重排 PDF」实现。原文字将不可选中、不可复制——这正是「防复制水印」想要的效果；若你需要保留可选中文字，请勿使用该命令。文件体积也会随 --dpi 变化。

安全与隐私

• 零联网：不发起任何网络请求，不上传任何文件内容。
• 零凭证留存：不保存任何密码；encrypt 只写入你提供的密码，脚本本地运行完即退出。
• 只读源文件：绝不修改或删除用户原始文件。

文件地图