Quick Start（快速上手）
所有功能集中在 scripts/pdf_toolkit.py，用受管 Python 运行（依赖缺失会自动用阿里云镜像安装 pypdf/pypdfium2/pillow）。
| 操作 | 命令示例 | 说明 |
|---|---|---|
| 按页拆分 | python pdf_toolkit.py split -i a.pdf -o out/ |
每页一个 01.pdf/02.pdf... |
| 拆分+方向校正 | python pdf_toolkit.py split-orient -i a.pdf -o out/ |
逐页检测旋转角并校正后拆分（最常用） |
| 整份方向校正 | python pdf_toolkit.py orient -i a.pdf -o a_fixed.pdf |
修正整份PDF的歪斜/倒立 |
| 方向检测(不改文件) | python pdf_toolkit.py orient -i a.pdf --dry-run |
仅打印每页旋转角与置信度 |
| 合并 | python pdf_toolkit.py merge -i "out/*.pdf" -o merged.pdf |
按文件名排序合并 |
| 页码范围提取 | python pdf_toolkit.py extract -i a.pdf -p "3-5,8" -o part.pdf |
提取第3-5、8页 |
| 提取图片 | python pdf_toolkit.py images -i a.pdf -o imgs/ |
导出页面嵌入的图片 |
| 提取文本 | python pdf_toolkit.py text -i a.pdf -o a.txt |
导出纯文本 |
| 行级涂色加框 | python pdf_toolkit.py annotate -i a.pdf -o a_marked.pdf --page 1 --text "关键词" |
黄底红框、文字仍可读；扫描件用 --rect x0,y0,x1,y1 |
| 生成/水印/加密解密 | 见下方「生成 / 水印 / 加密解密」章节 | generate / watermark / crypt 三个子命令 |
| 上传就绪体检 | python pdf_toolkit.py check -i a.pdf |
头/尾/xref/strict解析/首页渲染六项体检；加密件加 --password；有问题 exit 1 |
| 敏感信息扫描 | python pdf_toolkit.py check -i a.pdf --security |
扫文本层 PII(身份证/手机/银行卡/金额)+元数据，外发/送审前脱敏自查（不阻断健康结论） |
| 规范化修复 | python pdf_toolkit.py repair -i a.pdf -o a_fixed.pdf |
修复"本地能开、系统拒收"件（垃圾头/缺%%EOF/xref断裂），保留书签元数据 |
| 压缩到上传上限 | python pdf_toolkit.py compress -i a.pdf --target-size 20M |
无损优先；超目标自动转图片；达不成给诚实提示 |
| 图片组卷 | python pdf_toolkit.py img2pdf -i p1.png p2.jpg -o album.pdf |
多图拼一册，可串 --orient 方向校正 |
| 加页码 | python pdf_toolkit.py pagenum -i a.pdf -o a_n.pdf |
页脚/页眉六方位，中文零字体依赖 |
| 批量体检 | python pdf_toolkit.py batch --dir ./inbox --report md |
目录全量体检，聚合 PASS/FAIL；--dashboard 出看板 |
| 行业规则体检 | python pdf_toolkit.py check -i a.pdf --profile unicom |
按联通/移动/电信/默认规则库卡上传红线 |
| 扁平化固化 | python pdf_toolkit.py flatten -i a_marked.pdf -o a_flat.pdf |
标注/水印栅格化为不可编辑只读PDF（送审防篡改）；--dpi 150/--quality 85 控体积；--pages 3-5 仅固化指定页 |
能力矩阵与边界（速查）
| 场景 | 命令 | 预期 |
|---|---|---|
| 单文件 | 上述任意子命令 xxx -i 文件.pdf |
秒~分钟级，收尾自动自检 |
| 批量目录 | batch --dir 资料/ [--recursive] [--report md] [--security] |
逐件隔离体检，单件坏不中断整批；聚合 PASS/FAIL |
| 大文件(>50MB) | 同上；compress 自动转图片重排达标 |
全量载入内存；超大扫描件若 OOM，先 compress --target-size 瘦身或 split 拆后再处理 |
| 海量目录(数百件) | batch --dir 资料/ --report json 喂 zfl-audit-charts 看板 |
单件失败不影响整体，报告可审计 |
边界（明确不做 / 前置条件）
- 方向校正(orient)、图片组卷(--orient) 依赖 Tesseract（自动探测 C:/Program Files/Tesseract-OCR/tesseract.exe）；未装则跳过校正仅按 /Rotate 元数据处理，不报错。
- 首次运行按需自动装 pypdf/pypdfium2/pillow/PyMuPDF/reportlab/cryptography（走阿里云镜像）；国内 PyPI 直连常超时，脚本已默认用镜像，无需手动配。
- 不做：表格提取、PDF→Word、翻译、表单填写、数字签名、自然语言编辑——这些交给 pdfkit-py（本机已有）。
- 安全扫描 --security 仅扫文本层，扫描件/图片 PDF 需先 OCR 才有文本可扫；身份证/银行卡/带单位金额为正则粗筛，命中为"疑似"，脱敏前请人工复核。另含「无单位纯大额」宽松命中（5–11 位裸数/千分位逗号数，去逗号后同样限 5–11 位）以降漏报；据实已将上限收到 11 位（超 12 位无单位金额少见、且 12 位以上裸数更易撞合同号），但可能误报合同号/序号/数量，且 PDF 文本层 元/万元 因字体乱码成 · 时会兜底标出裸数——均属预期宽松召回，须人工复核。
行级涂色加框标注（annotate）
参考腾讯文档 PDFKit（pdfkit-py）的 PyMuPDF 标注范式，实现"高亮某一行+红色边框，文字仍能看清"。
| 模式 | 命令示例 | 说明 |
|---|---|---|
| 按文本定位 | python pdf_toolkit.py annotate -i a.pdf -o out.pdf --page 1 --text "某某监理咨询有限公司" |
自动搜索文本并扩展为整行宽；仅适用于含文字层的 PDF |
| 按坐标定位 | python pdf_toolkit.py annotate -i a.pdf -o out.pdf --page 1 --rect "50,300,780,340" |
扫描件/图片 PDF 使用；坐标为视觉坐标（左上原点、y 向下），已自动适配 /Rotate |
| 自定义颜色 | --fill FFFF00 --border FF0000 --opacity 0.3 --border-width 1.5 |
填充色、边框色、填充透明度、边框粗细 |
| 取消整行扩展 | --no-full-width |
仅高亮文本自身 bbox（文本模式） |
- 实现：用
PyMuPDF添加两个矩形批注，一个是半透明填充（默认黄色 0.3 透明度），另一个是不透明红框；原文字保留。 - 依赖：
PyMuPDF按需懒加载，首次运行annotate时自动从阿里云镜像安装。
拆分命名规则
- 默认前缀空、补零宽度 2、后缀
.pdf（即01.pdf）。可用--prefix 页改成页01.pdf，--width 3改成001.pdf。 - 输出目录不存在时自动创建。
高级用法（来自 PDFPatcher 理念）
- 批量处理目录：
for f in *.pdf; do python pdf_toolkit.py split-orient -i "$f" -o "${f%.pdf}_pages/"; done - 先校正再拆分：
split-orient内部等价于"逐页检测→旋转→写出单页文件"，无需先生成整份校正版。 - 更多可扩展方向（书签、去水印、字体替换等）见
references/pdfpatcher_features.md。
依赖与运行
- 受管 Python：
~/.workbuddy/binaries/python/envs/default/Scripts/python.exe（按本机用户目录展开；已含 pypdf/pypdfium2/pillow）。 - Tesseract：方向校正需要；从 https://github.com/tesseract-ocr/tesseract 安装，中文包通常已随安装附带（Han 脚本检测不依赖中文训练数据）。
- 自动安装：脚本启动时若缺 pypdf/pypdfium2/pillow，会用
https://mirrors.aliyun.com/pypi/simple/安装（PyPI 直连在本机常超时）。
生成 / 水印 / 加密解密
| 操作 | 命令示例 | 说明 |
|---|---|---|
| 文本/Markdown 生成 PDF | python pdf_toolkit.py generate -i a.md -o a.pdf --title "标题" |
自动注册中文 CID 字体(STSong-Light)；标题/多级标题/正文分样式；内联可用 --text "..." |
| 文字水印 | python pdf_toolkit.py watermark -i a.pdf -o a_wm.pdf --text "机密" --opacity 0.2 --angle 45 |
半透明对角平铺；--color RRGGBB 改色、--font-size 改字号 |
| 图片水印 | python pdf_toolkit.py watermark -i a.pdf -o a_wm.pdf --image logo.png |
透明 PNG 铺满每页 |
| 加密 | python pdf_toolkit.py crypt -i a.pdf -o a_enc.pdf --password 123456 |
AES-256 设用户密码（--owner-password 可选）；输出 <名>_encrypted.pdf |
| 解密 | python pdf_toolkit.py crypt -i a_enc.pdf -o a_dec.pdf --decrypt --password 123456 |
去除密码；密码错误会报错退出 |
- 生成：用 reportlab 的 SimpleDocTemplate + Paragraph 排版，
#/##/###自动识别为各级标题，正文自动换行；中文字体走 CID(STSong-Light)，无需本地字体文件。 - 水印：文字水印用 reportlab 渲染旋转半透明平铺水印页，再经 PyMuPDF
show_pdf_page叠加（任意角度+真透明+中文）；图片水印直接插入整页（建议预先准备透明 PNG）。 - 加解密：用 pypdf，
clone_from整体克隆保留书签/链接/表单/元数据；加密显式AES-256；--decrypt去密码后写出无密码副本。merge 同样走append保结构。 - 安全守卫：所有写出类命令拒绝"输出路径=输入路径"的就地覆盖，防写坏原件。
- [!] 加密件上传业务系统警示：AES-256（加密字典 /V=5 /R=6）是现代标准，但很多老业务系统（ERP/OA/审核平台）的服务端预览器（老版 pdfbox/iText/pdf.js）不支持，会出现"系统预览打不开"。送审/上传系统的文件建议先上传后加密，或先与对方确认支持 AES-256；仅本地/邮件流转的文件可放心加密。
压缩 / 图片组卷 / 页码
| 操作 | 命令示例 | 说明 |
|---|---|---|
| 压缩(无损优先) | python pdf_toolkit.py compress -i a.pdf --target-size 20M |
先无损重写；超目标自动转图片重排(dpi 150→40 递减)；--keep-text 保文字层；达不成给诚实提示 |
| 图片组卷 | python pdf_toolkit.py img2pdf -i p1.png p2.jpg -o album.pdf |
多图拼一册；--orient 串方向校正(需Tesseract)；--max-dim 3000 超大图等比缩小 |
| 加页码 | python pdf_toolkit.py pagenum -i a.pdf -o a_n.pdf |
默认页脚居中 {n}；--format "{n}/{total}"、--pos top-right、--start、--color、--font-size；中文页码零字体依赖 |
- 压缩：纯文本/矢量为主的文件无损即可达标；扫描件/拍照件因已是位图，转图片重排是现实最优解，但会丢失可选文本层（用
--keep-text可保留但可能仍超限）。 - 图片组卷：每张图独立成页，非图片输入自动跳过并告警（不崩）；方向校正依赖 Tesseract，未装则跳过。
- 页码：ASCII 走内置字体精确对齐；CJK 走 PIL 渲染→
fitz.Pixmap，不依赖系统字体文件，跨机一致。
批量体检与行业规则库
| 命令 | 说明 |
|---|---|
batch --dir ./inbox --report md |
扫描目录(默认 *.pdf，--recursive 递归)，逐件 check，聚合 PASS/FAIL |
batch --dir ./inbox --dashboard |
额外输出 audit-charts 看板 JSON（默认 <dir>/pdf_health_dashboard.json） |
batch --dir ./inbox --security |
逐件叠加敏感信息(PII/元数据)扫描，外发前批量脱敏自查 |
check -i a.pdf --profile unicom |
叠加行业规则库：大小上限/PDF版本/禁加密/禁AES-256/页面尺寸容差/最少页数 |
check -i a.pdf --profile ? |
列出内置规则库；也支持 --profile /abs/path.json 自定义 |
check -i a.pdf --report json --report-out r.json |
产出 audit-charts 兼容单文件 JSON，可直接喂 zfl-audit-charts 出看板 |
- 内置规则库(
data/profiles/)：unicom.json(≤20M, A4, 禁加密/禁AES-256)、mobile.json(≤15M)、telecom.json(≤20M)、default.json(≤50M, 允许加密)。阈值均为示例，请以实际平台上传要求替换，或放自己的 JSON 到data/profiles/或传绝对路径。 - 工作流：批量
batch先摸清全量健康度 → 单件check --profile卡行业红线 → FAIL 的repair后重测，形成"体检→修复→复测"闭环。 - 脱敏自查：
check --security（或batch --security）在送审/外发前扫一遍 PII（身份证/手机/银行卡/金额）与元数据，命中为"疑似"，脱敏前请人工复核；扫描件先 OCR 才有文本可扫。
上传就绪体检与修复（check / repair）
源自真实事故的第一性原理："PDF 上传系统后预览打不开、下载下来也打不开"——根源是本地阅读器（WPS/Acrobat）是修复型解析，会静默修复缺 %%EOF、xref 断裂等问题；而业务系统服务端（老版 pdfbox/iText/pdf.js）是严格型解析。所以"本地能打开"在故障排查里是零证据。
| 命令 | 检查/动作 | 说明 |
|---|---|---|
check -i a.pdf |
①文件头 %PDF- ②文件尾 %%EOF ③startxref 指针 ④pypdf strict 解析+全页对象触达 ⑤pdfium 首页真渲染 ⑥加密标志与 /V 值 |
双引擎交叉验证；AES-256 件自动提示兼容性；全过 exit 0 |
repair -i a.pdf -o a_fixed.pdf |
PyMuPDF 全量重写（garbage=4 清孤儿对象 + clean 规范内容流 + deflate） |
修复垃圾头/截尾/xref 断裂；书签/元数据保留；写完自动 strict 复读 |
- 工作流建议：上传业务系统前先
check；FAIL 则repair后再上传——替代不可靠的"本地打开看看"。 - 写出自检钩子：orient/merge/extract/annotate/generate/watermark/crypt/flatten 八个写出命令收尾自动 strict 复读+首页渲染，自检失败 exit 1 并保留文件供排查（正常时静默零噪音）。
扁平化（flatten，固化只读）
把标注/水印/全部内容栅格化为不可编辑的只读 PDF，用于送审固化与防篡改。
| 命令 | 说明 |
|---|---|
flatten -i a_marked.pdf -o a_flat.pdf |
全文档逐页 150 DPI 栅格化，生成纯图像只读 PDF |
flatten -i a.pdf --pages 3-5 -o p.pdf |
仅固化并导出指定页（其余页不输出） |
flatten -i a.pdf --dpi 200 --quality 90 |
调高分辨率/质量（体积更大、更清晰） |
flatten -i a_enc.pdf --password 123456 |
加密件需提供密码 |
- 与 annotate/watermark 强互补：先
annotate黄底红框高亮（或watermark水印），再flatten把标注"烧录"成不可移动、不可删改的固化版本——监理送审资料防篡改的标准动作。 - 代价（须知）：栅格化会丢失可选文字层（不可搜索/复制），这与"只读固化"目标一致；如需保留文字请直接使用
annotate原文件。 - 体积控制：默认 150 DPI + JPEG q85 平衡清晰与体积；扫描件/拍照件本就是位图，flatten 后体积接近原图；矢量/文字为主的 PDF flatten 后体积可能变大（像素化），属正常。
- 安全守卫：拒绝输出路径=输入路径的就地覆盖；收尾自动 strict 复读+首页渲染自检。
常见问题 FAQ
报错含义、安装/网络、大文件 OOM、批量用法等高频问题见同目录 FAQ.md（已随技能一起发布）。
