PDF合并与拆分(保留文件名和页码)

概述

PDF KeepName Merge Split（合并 / 拆分，保留原文件名）

把多个 PDF 顺序合并成一份，并自动记录每个源文件在结果中的页范围；之后可按记录的范围无损拆回，文件名还原为原始名。范围会内嵌进 merged.pdf 自身的元数据（自包含，拆分无需外部文件），同时额外写一份 <merged>.ranges.json 作为可读备份与兼容回退。

适用于：把扫描件/发票/报告拼成单文件、按原文件边界切回、批量合并后分发等。

何时用 / 何时不用

• ✅ 用户要「把这几个 PDF 合成一个」「合并成一份」「按顺序拼起来」→ 合并
• ✅ 用户要「把这个大 PDF 按原来的文件拆开」「还原成合并前的几个文件」→ 拆分（范围优先读 PDF 内嵌元数据，无需 .ranges.json；元数据缺失时回退 JSON）
• ✅ agent 需要在脚本里批量合并/拆分 PDF → 直接用 pdf_core.py 的 API 或 CLI
• ❌ 用户要的是「按页数均匀切」「按书签/章节切」→ 不是本技能场景（本技能只按合并时的源文件边界切）
• ❌ 用户要压缩/旋转/加水印/OCR → 走 pdf-master 或 pdf 相关技能

快速开始（agent 调用核心，推荐）

核心逻辑在 pdf_core.py，可 import 也可 CLI。Windows 用 managed venv：

C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe pdf_core.py <子命令>

子命令：

# 合并：输出 merged.pdf，范围内嵌进 PDF 元数据（自包含），并写 merged.pdf.ranges.json 作备份
python pdf_core.py merge <out.pdf> <in1.pdf> [in2.pdf ...]

# 拆分：读 <merged.pdf>.ranges.json，按原文件名还原到 out_dir
python pdf_core.py split <merged.pdf> <out_dir>

# 查页数
python pdf_core.py info <file.pdf>

作为库 import：

from pdf_core import merge_pdfs, split_pdfs, load_ranges
ranges, rp = merge_pdfs(["A.pdf","B.pdf","C.pdf"], "merged.pdf")  # [(name,start,end),...]
saved       = split_pdfs("merged.pdf", ranges, "out_dir")

桌面 GUI（给用户用）

pdf_app.py 是 tkinter 双标签页界面（合并 / 拆分），支持拖拽（需 tkinterdnd2，可选）。GUI 与核心逻辑解耦，复用 pdf_core.py。

启动：

python pdf_app.py          # 需用自带 tkinter 的 Python（如系统 Python 3.14）

说明：Windows 一键启动器（.bat）未随包发布——SkillHub 上传接口禁止 .bat 等可执行脚本类型

（报 file type not allowed）。需要一键启动时可自行在 技能根目录建一个 bat，内容为

%~dp0..python.exe pdf_app.py 形式的调用即可。

依赖

pip install PyMuPDF          # 必需
pip install tkinterdnd2      # 可选，仅 GUI 拖拽需要

• 运行 GUI 必须用自带 tkinter 的 Python（如系统 Python 3.14）；managed 3.13 缺 tkinter 跑不了 GUI，但 pdf_core.py 纯逻辑无此限制。
• Windows 若安装遇 EPERM，加前缀 CODEBUDDY_SESSION_ID= CLAUDE_SESSION_ID= 绕过 safe-delete shim。

关键实现要点（页偏移累加）

合并的核心是「边插入边累加页偏移」，每个源文件插入前的 page_count 就是它的起始页：

merged = fitz.open()
file_ranges = []
for f in source_files:
    doc = fitz.open(f)
    start = merged.page_count        # 插入前页数 = 本文件起始页
    merged.insert_pdf(doc)
    end = merged.page_count - 1      # 插入后页数-1 = 本文件结束页
    file_ranges.append((basename(f), start, end))
    doc.close()
merged.save(output_path)

拆分用 insert_pdf(merged, from_page=start, to_page=end) 按记录范围切回，文件名直接用原始 basename，所以还原出来的文件与合并前同名同页。

验证（交付前必做）

• 合并：info 校验输出页数 = 各源文件页数之和；ranges 的每段 end-start+1 等于对应源文件页数。
• 拆分：每个输出文件页数 == 对应源文件页数；文件名 == 原始名。

已知限制

• 拆分优先读取 merged.pdf 内嵌的元数据范围，因此即使 .ranges.json 丢失也能无损还原；仅当 PDF 非本技能合并（元数据中也无范围）且缺少 JSON 时，load_ranges 才报错——此时应改用通用切页逻辑或请用户指定范围。
• 合并按列表顺序拼接；同名源文件在拆分时会被后写入者覆盖（输出目录内同名冲突），调用前应确保文件名唯一或用 out_dir 隔离。
• 不处理加密/损坏 PDF；fitz.open 会抛异常，由调用方捕获。