PDF 处理（改编自 Nous Research pdf）

适合“合并几份 PDF”“提取报告中的文字和表格”“给文件加水印或填写表单”。先判断 PDF 是可选中文字还是扫描图片；要求编辑原文、OCR、带密码文件时分别走对应流程，不把转换/识别说成无损。默认输出新文件，覆盖原件或解密前先得到用户同意与合法访问权限。

在 WorkBuddy 中先定位当前 SKILL.md 所在文件夹，以绝对路径调用 scripts/；Windows/含空格路径加引号，命令用 python -X utf8。基础功能需 Python 3.10+ 及 pypdf reportlab pdfplumber；页图可选 pypdfium2 或 Poppler，安装排查读 @references/setup.md。生成中文 PDF 时 pdf_create.py、中文印章 pdf_stamp.py、表单中文静态标签 pdf_make_form.py 会寻找本机中文字体；找不到就明确报错，字体本身不随包分发。报告 JSON/表单 JSON 可用 font_path，印章命令可用 --font-path 指定本机字体。可填写表单的字段名、选项和预填值仍请用 ASCII；中文交互值不保证可靠，脚本会拒绝以免输出坏文件。扫描版 PDF 先读 @references/ocr-extraction.md；设计/填写表单先读 @references/forms.md；想用外部模型改现有 PDF 文字先读 @references/nano-pdf-editing.md。未安装额外依赖就说明限制，不伪称已识别或已改好。执行后读回页数、文字/字段并在视觉操作后看渲染结果。

以下保留原版操作细节。原版 terminal、write_file、read_file、vision_analyze 指 WorkBuddy 可用的命令、文本文件和图像查看能力，不要求同名工具。来源与改动见 SOURCE_AND_CHANGES.md。

Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks):

• Scanned/image-only PDFs and OCR (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): references/ocr-extraction.md
• Editing text inside an existing PDF via natural-language prompts (nano-pdf CLI): references/nano-pdf-editing.md

When to Use

• Generate a report, invoice, or multi-page document as PDF.
• Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first.
• Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF.
• Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs.
• Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments.
• Fill or flatten AcroForm forms; encrypt or decrypt with passwords.
• NOT for scanned/image-only PDFs (use references/ocr-extraction.md) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).

Prerequisites

• Python 3.10+ with pypdf, reportlab, pdfplumber:
  python -m pip install pypdf reportlab pdfplumber
• Optional, for page rasterization (pdf_page_image.py, overlay rendering): python -m pip install pypdfium2, or poppler's pdftoppm on PATH. Scripts fall back pypdfium2 → pdftoppm and report {"rendered": false, "missing": [...]} (exit 0) when neither exists.
• Each helper script checks imports lazily and prints an install hint if a dependency is missing.

How to Run

All helpers live in scripts/ and are argparse CLIs. Resolve the skill
directory and invoke scripts by quoted absolute path; every one supports
--help. They read/write JSON strictly as UTF-8, print JSON results to stdout,
and exit non-zero on failure.

python scripts/pdf_create.py spec.json -o out.pdf         # build PDF from JSON spec
python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec
python scripts/pdf_form_layout.py formspec.json           # lint form layout BEFORE building
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text                 # per-page text (JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # tables to JSON + CSV files
python scripts/pdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted/scanned flags
python scripts/pdf_read.py form.pdf --fields              # form fields: name, type, value
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_secure.py enc.pdf --decrypt -o dec.pdf --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_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
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
python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/

Quick Reference

Procedure

1. Inspect first. Run pdf_read.py file.pdf --meta. Check encrypted (if true, decrypt first with pdf_secure.py --decrypt) and likely_scanned_pages. If pages are image-only, export them with pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/ and hand the PNGs to the references/ocr-extraction.md skill — do not report empty text as "no content".
2. Create. Write a JSON spec with write_file (elements: heading, paragraph, table, image, pagebreak; optional title/author metadata; page numbers are added automatically), then run pdf_create.py. Verify visually with vision_analyze on a rendered page image if layout matters.
3. Extract. --text gives a JSON list of per-page strings; --tables gives row arrays per page and can also emit CSV files. Read results with read_file; never eyeball a binary PDF directly.
4. Manipulate. pdf_merge.py concatenates and can add one bookmark per source file; pdf_split.py handles page ranges (1-based, e.g. 1-3,5,9-), rotation in 90° steps, and --compress. Watermark by preparing a single-page stamp PDF (e.g. via pdf_create.py) and overlaying it with pdf_watermark.py; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use pdf_stamp.py with text or an image at explicit coordinates.
5. Build forms. Write one form-spec JSON (fields with label_box/entry_box in PDF points — see references/forms.md), lint it with pdf_form_layout.py and fix every reported problem, optionally review the --render-overlay PNG with vision_analyze, then build with pdf_make_form.py and confirm with pdf_read.py --fields.
6. Fill forms. List fields (--fields) to learn exact names and types, write a UTF-8 JSON of {"FieldName": "value"} with write_file (checkboxes accept true/false; radio/choice values must match the field's export options), then pdf_fill_form.py. Re-read with --fields to confirm values landed.
7. Metadata & attachments. pdf_meta.py --set-meta writes Title/Author/Subject/Keywords (DocInfo); --clear-meta drops them; --attach/--list-attachments/--extract-attachments round-trip embedded files.
8. Secure. Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, --decrypt writes an unencrypted copy.
9. Verify (see below) before reporting success.

Pitfalls

• Scanned PDFs: empty extract_text() plus page images means there is no text layer. Route to references/ocr-extraction.md; do not fabricate text.
• Flattening limits: pdf_fill_form.py --flatten uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with vision_analyze; for bulletproof flattening use an external renderer (e.g. Ghostscript or pdftoppm+reassembly) as a fallback.
• NeedAppearances: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm NeedAppearances flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters.
• Non-Latin form values: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with --fields, not just visually.
• Compression expectations: --compress only deflates content streams. Typical savings are 0–20%; it does nothing for PDFs dominated by images or already-compressed streams. It is not a substitute for image downsampling (Ghostscript territory).
• Permission flags don't enforce: owner-password permission bits (no-print, no-copy) are polite requests that viewers may honor; any library (including pypdf) can read and strip them. Only the user password actually gates content via encryption. Never present permission flags as security.
• Table extraction is heuristic: pdfplumber detects tables from ruling lines/word alignment; borderless or merged-cell tables may need table_settings tuning or manual cleanup.
• Page indexing: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.
• Rotated stamp text extraction: pdfplumber's line grouping scrambles rotated glyphs (a 45° "DRAFT" extracts as stray letters); verify rotated stamps with pypdf's extract_text() or a rendered image instead.
• Radio groups: reportlab needs ≥2 radio() widgets per group, fills need the slashed export value ("/red"), and flatten fidelity is worst for radios — see references/forms.md.
• Metadata scope: pdf_meta.py writes the classic DocInfo dictionary only; embedded XMP metadata (if any) is left untouched and may show different values in some viewers.
• PDF/A is out of scope: pypdf/reportlab cannot produce or validate conformant PDF/A. If archival conformance is required, run Ghostscript via the terminal tool (e.g. gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf with a suitable ICC profile) and validate with veraPDF — both are external installs, and the result still needs validation, not assumption.
• Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.

Verification

• After create/merge/split: pdf_read.py out.pdf --meta — confirm page_count, and per-page rotation when you rotated.
• After extraction: check the JSON is non-empty and spot-check a known string or cell.
• Form design loop: pdf_form_layout.py spec.json must exit 0; then --render-overlay boxes.png --pdf form.pdf and review the PNG with vision_analyze (red = entry boxes with field names, blue = label boxes) asking about overlaps, misalignment, and labels detached from their fields. Iterate spec → lint → overlay until clean.
• After building a form: pdf_read.py form.pdf --fields lists every spec field with the right type and options.
• After form fill: pdf_read.py filled.pdf --fields and compare values (exact match, including non-ASCII).
• After stamping: re-extract text (pypdf for rotated stamps) or render the page with pdf_page_image.py and inspect with vision_analyze.
• After metadata/attachment edits: pdf_read.py --meta / pdf_meta.py --list-attachments, and re-extract an attachment to byte-compare.
• After encrypt: --meta shows "encrypted": true and opening without a password fails; after decrypt, text extraction matches the original.
• For anything visual (watermarks, flattened forms), render and inspect with vision_analyze.