pdf

PDF Skill 是一套面向 PDF 文件的处理技能，基于 pypdf、reportlab、pdfplumber 等 Python 库，通过 scripts/ 目录下的 argparse 命令行工具完成各类 PDF 操作。所有脚本以 UTF-8 严格读写 JSON，结果打印到 stdout，失败时以非零状态码退出，均支持 --help。

【用途与主要能力】

创建：从 JSON 规格生成 PDF（元素包括 heading、paragraph、table、image、pagebreak，可选 title/author 元数据，自动添加页码）。
表单：从 JSON 规格构建可填写的 AcroForm（文本/复选框/单选/下拉），构建前可先做布局 lint 并渲染叠加图检查。
读取：提取逐页文本、表格（JSON/CSV）、元数据、页面尺寸、加密/扫描标记、表单字段值。
页面操作：合并（可加书签）、拆分/提取页面子集、旋转（90° 步进）、压缩内容流、水印、按坐标盖章文字/图片、书签。
导出与元数据：页面导出为 PNG（用于视觉检查或交给 OCR）、设置/清除 DocInfo 元数据、添加/列出/提取附件。
安全：使用 AES-256 加密/解密，支持区分用户密码与所有者密码。

【使用方式】需 Python 3.10+ 并安装：python -m pip install pypdf reportlab pdfplumber。页面栅格化可选安装 pypdfium2，或使用 PATH 中的 poppler pdftoppm；脚本按 pypdfium2 → pdftoppm 回退，两者都缺失时返回 {"rendered": false, "missing": [...]}（退出码 0）。各脚本惰性检查导入，缺依赖时打印安装提示。

常用命令示例： python scripts/pdf_create.py spec.json -o out.pdf python scripts/pdf_make_form.py formspec.json -o form.pdf python scripts/pdf_form_layout.py formspec.json python scripts/pdf_read.py doc.pdf --text python scripts/pdf_read.py doc.pdf --tables --csv-dir t/ python scripts/pdf_read.py doc.pdf --meta python scripts/pdf_read.py form.pdf --fields python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks] python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90] python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten] python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under] python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3] python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/ python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf

【适用场景】生成报告、发票或多页文档；构建可填写表单；提取文本/表格/元数据/表单值；合并拆分旋转、加水印盖章、压缩；导出页面图片；管理元数据与附件；加解密。

【限制与注意事项】不适用于扫描件/纯图片 PDF（应使用 references/ocr-extraction.md），也不适用于像素级 HTML 转 PDF（应使用无头浏览器）。扫描件提取为空文本时不要伪造内容。--flatten 对普通文本字段和复选框可靠，但可能丢失或错误渲染复杂控件（富文本、自定义外观流、部分单选组），需视觉验证。填充后部分极简阅读器可能忽略 NeedAppearances。非拉丁字符值以 UTF-16 正确存储，但字段默认字体可能缺字形导致显示空白，应以 --fields 验证。--compress 仅压缩内容流，典型节省 0–20%，不能替代图像降采样。所有者密码的权限位（禁打印、禁复制）不具强制力，只有用户密码通过加密真正保护内容。表格提取为启发式，无边框或合并单元格表格可能需要调参或人工清理。CLI 页码为 1 基，pypdf API 为 0 基，脚本已转换。旋转盖章文字用 pdfplumber 提取会乱序，应改用 pypdf 或渲染图验证。单选组需每组至少 2 个 radio() 控件，填充需带斜杠的导出值。pdf_meta.py 仅写经典 DocInfo，不处理 XMP。PDF/A 不在范围内，需借助 Ghostscript 与 veraPDF 等外部工具。旋转必须为 90 的倍数；加密输入须先解密再操作。

技能介绍