V4TIME/V4SKILL

PDF Skill

Erstellen Sie PDFs aus strukturierten Spezifikationen, bauen und füllen Sie AcroForm-Formulare (mit Layout-Prüfung und visuellen Overlays), extrahieren Sie Text/Tabellen/Metadaten, führen Sie Seiten zusammen/teilen/drehen/wasserzeichen/stempeln Sie Seiten, exportieren Sie Seitenbilder, verwalten Sie Metadaten und Anhänge, und ver- und entschlüsseln Sie — mit pypdf, reportlab und pdfplumber. Zwei absorbierte Fähigkeiten befinden sich in references/ (lesen Sie die passende Datei vor diesen Aufgaben):

• Gescannte/reine Bild-PDFs und OCR (pymupdf schneller Pfad, marker-pdf Qualitätspfad, scripts/extract_pymupdf.py + scripts/extract_marker.py): references/ocr-extraction.md
• Text in einem vorhandenen PDF mittels natürlichsprachlicher Eingabe bearbeiten (nano-pdf CLI): references/nano-pdf-editing.md

Wann verwenden

• Erzeugen Sie einen Bericht, eine Rechnung oder ein mehrseitiges Dokument als PDF.
• Erstellen Sie ein ausfüllbares AcroForm (Textfeld/Kontrollkästchen/Option/ Dropdown) aus einer JSON-Spezifikation, mit vorheriger Layout-Prüfung.
• Extrahieren Sie Text, Tabellen (JSON/CSV), Metadaten oder Formularfeldwerte aus einer PDF.
• Führen Sie PDFs zusammen, teilen Sie sie, drehen Sie sie, extrahieren Sie Seitenauswahlen, fügen Sie Wasserzeichen hinzu, stempeln Sie Text/Bilder an Koordinaten, fügen Sie Lesezeichen hinzu oder komprimieren Sie PDFs.
• Exportieren Sie Seiten als PNGs zur visuellen Prüfung oder zur OCR-Übergabe; setzen/löschen Sie Dokumentmetadaten; fügen Sie Dateianhänge hinzu oder extrahieren Sie sie.
• Füllen oder glätten Sie AcroForm-Formulare; ver- oder entschlüsseln Sie mit Passwörtern.
• NICHT für gescannte/reine Bild-PDFs (verwenden Sie references/ocr-extraction.md) und NICHT für pixelgenaues HTML-zu-PDF-Rendering (verwenden Sie einen Headless-Browser).

Voraussetzungen

• Python 3.10+ mit pypdf, reportlab, pdfplumber: python -m pip install pypdf reportlab pdfplumber
• Optional, für Seitenrasterisierung (pdf_page_image.py, Overlay-Rendering): python -m pip install pypdfium2, oder popplers pdftoppm im PATH. Skripte fallen zurück von pypdfium2 → pdftoppm und melden {"rendered": false, "missing": [...]} (Exit 0), wenn keines existiert.
• Jedes Hilfsskript prüft Importe verzögert und gibt einen Installationshinweis aus, wenn eine Abhängigkeit fehlt.

Ausführung

Alle Helfer befinden sich in scripts/ und sind argparse-CLIs — führen Sie sie mit dem terminal-Tool aus; jedes unterstützt --help. Sie lesen/schreiben JSON streng als UTF-8, geben JSON-Ergebnisse auf stdout aus und beenden mit einem Nicht-Null-Exitcode bei Fehlschlag.

python scripts/pdf_create.py spec.json -o out.pdf         # PDF aus JSON-Spezifikation erstellen
python scripts/pdf_make_form.py formspec.json -o form.pdf # ausfüllbares AcroForm aus JSON-Spezifikation erstellen
python scripts/pdf_form_layout.py formspec.json           # Formular-Layout VOR dem Bau prüfen
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text                 # Text pro Seite (JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # Tabellen in JSON + CSV-Dateien
python scripts/pdf_read.py doc.pdf --meta                 # Metadaten, Seitengrößen, verschlüsselt/gescannt Flags
python scripts/pdf_read.py form.pdf --fields              # Formularfelder: Name, Typ, Wert
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 ihra-passwort
python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password ihr-passwort
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 "ENTWURF" --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 verzeichnis/

Kurzreferenz

Aufgabe	Tool	Befehl / API
Dokument erstellen (Überschriften, Tabellen, Bilder)	reportlab platypus	pdf_create.py spec.json -o out.pdf
Ausfüllbares Formular erstellen	reportlab acroForm	pdf_make_form.py formspec.json -o form.pdf
Formular-Layout prüfen / Overlay-Bild	pure python + PIL	pdf_form_layout.py formspec.json [--render-overlay o.png]
Text pro Seite	pdfplumber	pdf_read.py f.pdf --text
Tabellen → JSON/CSV	pdfplumber	pdf_read.py f.pdf --tables
Metadaten / Größen / verschlüsselt / gescannt	pypdf + pdfplumber	pdf_read.py f.pdf --meta
Zusammenführen (+ Gliederung)	pypdf	pdf_merge.py a.pdf b.pdf -o m.pdf
Teilen / extrahieren / drehen	pypdf	pdf_split.py f.pdf --pages 2-5 --rotate 90
Formular auflisten / füllen / glätten	pypdf	pdf_read.py --fields, pdf_fill_form.py
Ver-/Entschlüsseln (AES-256)	pypdf	pdf_secure.py --encrypt/--decrypt
Wasserzeichen / Stempel auf PDF-Seite	pypdf	pdf_watermark.py f.pdf --stamp w.pdf
Text/Bild an Koordinaten stempeln	reportlab + pypdf	pdf_stamp.py f.pdf --text "Hier unterschreiben" --x 400 --y 60
Seiten → PNG (Prüfung / OCR-Übergabe)	pypdfium2 oder pdftoppm	pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/
Metadaten setzen/löschen, Anhänge	pypdf	pdf_meta.py --set-meta / --attach / --extract-attachments
Inhaltsströme komprimieren	pypdf	pdf_split.py f.pdf --pages 1-N --compress

Vorgehen

1. Zuerst prüfen. Führen Sie pdf_read.py datei.pdf --meta aus. Prüfen Sie encrypted (falls wahr, zuerst mit pdf_secure.py --decrypt entschlüsseln) und likely_scanned_pages. Wenn Seiten nur Bilder enthalten, exportieren Sie sie mit pdf_page_image.py --pages <gescannt> --dpi 300 --out-dir imgs/ und übergeben Sie die PNGs an den Skill references/ocr-extraction.md — melden Sie keinen leeren Text als "kein Inhalt".
2. Erstellen. Schreiben Sie eine JSON-Spezifikation mit write_file (Elemente: heading, paragraph, table, image, pagebreak; optionale Metadaten title/author; Seitenzahlen werden automatisch hinzugefügt), führen Sie dann pdf_create.py aus. Überprüfen Sie visuell mit vision_analyze auf einem gerenderten Seitenbild, wenn das Layout wichtig ist.
3. Extrahieren. --text liefert eine JSON-Liste von Zeichenketten pro Seite; --tables liefert Zeilen-Arrays pro Seite und kann auch CSV-Dateien ausgeben. Lesen Sie Ergebnisse mit read_file; betrachten Sie niemals eine binäre PDF direkt.
4. Manipulieren. pdf_merge.py verkettet und kann ein Lesezeichen pro Quelldatei hinzufügen; pdf_split.py verarbeitet Seitenbereiche (1-basiert, z.B. 1-3,5,9-), Drehung in 90°-Schritten und --compress. Wasserzeichen durch Vorbereiten eines einseitigen Stempel-PDFs (z.B. via pdf_create.py) und Überlagern mit pdf_watermark.py; für Einzeiler-Stempel ("Hier unterschreiben", diagonaler ENTWURF, Ecketiketten) verwenden Sie pdf_stamp.py mit Text oder einem Bild an expliziten Koordinaten.
5. Formulare bauen. Schreiben Sie eine JSON-Formularspezifikation (Felder mit label_box/entry_box in PDF-Punkten — siehe references/forms.md), prüfen Sie sie mit pdf_form_layout.py und beheben Sie jeden gemeldeten Fehler, überprüfen Sie optional das --render-overlay PNG mit vision_analyze, bauen Sie dann mit pdf_make_form.py und bestätigen Sie mit pdf_read.py --fields.
6. Formulare füllen. Listen Sie Felder auf (--fields), um genaue Namen und Typen zu erfahren, schreiben Sie ein UTF-8-JSON mit {"Feldname": "wert"} mit write_file (Kontrollkästchen akzeptieren true/false; Options-/Auswahlwerte müssen den Exportoptionen des Feldes entsprechen), dann pdf_fill_form.py. Lesen Sie erneut mit --fields, um zu bestätigen, dass die Werte angenommen wurden.
7. Metadaten & Anhänge. pdf_meta.py --set-meta schreibt Titel/Autor/Betreff/Schlagwörter (DocInfo); --clear-meta löscht sie; --attach/--list-attachments/--extract-attachments verarbeiten eingebettete Dateien.
8. Sicherheit. Verschlüsseln Sie mit unterschiedlichen Benutzer-/Besitzer-Passwörtern und AES-256. Um ein bekanntes Passwort zu entfernen, schreibt --decrypt eine unverschlüsselte Kopie.
9. Verifizieren (siehe unten), bevor Sie Erfolg melden.

Fallstricke

• Gescannte PDFs: leeres extract_text() plus Seitenbilder bedeutet, dass keine Textebene vorhanden ist. Leiten Sie an references/ocr-extraction.md weiter; erfinden Sie keinen Text.
• Grenzen der Glättung: pdf_fill_form.py --flatten verwendet pypdfs Glättungsunterstützung, die Widget-Erscheinungsbilder in Seiteninhalt umwandelt. Es ist zuverlässig für einfache Textfelder und Kontrollkästchen, kann aber exotische Widgets (Rich-Text, benutzerdefinierte Erscheinungsbildströme, einige Optionsgruppen) fallen lassen oder falsch darstellen. Überprüfen Sie die geglättete Ausgabe visuell mit vision_analyze; für eine absolut zuverlässige Glättung verwenden Sie einen externen Renderer (z.B. Ghostscript oder pdftoppm+Wiederzusammenbau) als Fallback.
• NeedAppearances: Nach dem Ausfüllen rendern Betrachter Werte nur, wenn Erscheinungsbildströme existieren. Das Füllskript setzt das AcroForm-Flag NeedAppearances, sodass konforme Betrachter sie neu generieren; einige minimale Betrachter ignorieren es — glätten Sie, wenn die Anzeigetreue wichtig ist.
• Nicht-lateinische Formularwerte: Werte werden korrekt gespeichert (UTF-16), aber die Standardschriftart des Feldes kann Glyphen fehlen, sodass ein Betrachter leere Felder anzeigen kann, obwohl die Daten korrekt zirkulieren. Überprüfen Sie mit --fields, nicht nur visuell.
• Komprimierungserwartungen: --compress deflationiert nur Inhaltsströme. Typische Einsparungen liegen bei 0–20%; es tut nichts für PDFs, die von Bildern oder bereits komprimierten Strömen dominiert werden. Es ist kein Ersatz für Bild-Downsampling (Ghostscript-Territorium).
• Berechtigungsflags erzwingen nichts: Besitzer-Passwort-Berechtigungsbits (kein Drucken, kein Kopieren) sind höfliche Anfragen, die Betrachter möglicherweise berücksichtigen; jede Bibliothek (einschließlich pypdf) kann sie lesen und entfernen. Nur das Benutzer-Passwort sperrt tatsächlich den Inhalt durch Verschlüsselung. Stellen Sie Berechtigungsflags niemals als Sicherheit dar.
• Tabellenextraktion ist heuristisch: pdfplumber erkennt Tabellen anhand von Linien/Wortausrichtung; tabellenlose oder zusammengeführte Zellen erfordern möglicherweise eine table_settings-Anpassung oder manuelle Bereinigung.
• Seitenindizierung: Hilfs-CLIs verwenden 1-basierte Seiten; pypdf-APIs sind 0-basiert. Die Skripte konvertieren — doppelt konvertieren nicht.
• Extrahierter gedrehter Stempeltext: pdfplumbers Zeilengruppierung bringt gedrehte Glyphen durcheinander (ein 45°-"ENTWURF" extrahiert als einzelne Buchstaben); überprüfen Sie gedrehte Stempel stattdessen mit pypdfs extract_text() oder einem gerenderten Bild.
• Optionsgruppen: reportlab benötigt ≥2 radio()-Widgets pro Gruppe, Füllungen benötigen den durchgestrichenen Exportwert ("/red"), und die Glättungstreue ist bei Optionsschaltflächen am schlechtesten — siehe references/forms.md.
• Metadatenbereich: pdf_meta.py schreibt nur das klassische DocInfo-Wörterbuch; eingebettete XMP-Metadaten (falls vorhanden) bleiben unberührt und können in einigen Betrachtern andere Werte anzeigen.
• PDF/A ist außerhalb des Rahmens: pypdf/reportlab können kein konformes PDF/A erzeugen oder validieren. Wenn Archivkonformität erforderlich ist, führen Sie Ghostscript über das terminal-Tool aus (z.B. gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf mit einem geeigneten ICC-Profil) und validieren Sie mit veraPDF — beides sind externe Installationen, und das Ergebnis muss dennoch validiert werden, nicht angenommen.
• Die Drehung muss ein Vielfaches von 90 sein; verschlüsselte Eingaben müssen vor jeder anderen Operation entschlüsselt werden.

Verifizierung

• Nach Erstellen/Zusammenführen/Teilen: pdf_read.py ausgabe.pdf --meta — bestätigen Sie page_count und pro Seite rotation, wenn Sie gedreht haben.
• Nach Extraktion: Prüfen Sie, dass das JSON nicht leer ist, und stichprobenartig einen bekannten String oder eine Zelle.
• Formularentwurfszyklus: pdf_form_layout.py spezifikation.json muss mit Exit 0 enden; dann --render-overlay boxes.png --pdf form.pdf und das PNG mit vision_analyze überprüfen (rot = Eingabefelder mit Feldnamen, blau = Beschriftungsfelder) auf Überlappungen, Fehlausrichtungen und von ihren Feldern getrennte Beschriftungen. Iterieren Sie Spezifikation → Prüfung → Overlay, bis alles sauber ist.
• Nach dem Bau eines Formulars: pdf_read.py form.pdf --fields listet jedes Spezifikationsfeld mit dem richtigen Typ und den Optionen auf.
• Nach dem Ausfüllen eines Formulars: pdf_read.py gefuellt.pdf --fields und Werte vergleichen (exakte Übereinstimmung, einschließlich Nicht-ASCII).
• Nach dem Stempeln: Text erneut extrahieren (pypdf für gedrehte Stempel) oder die Seite mit pdf_page_image.py rendern und mit vision_analyze überprüfen.
• Nach Metadaten-/Anhangsbearbeitung: pdf_read.py --meta / pdf_meta.py --list-attachments, und einen Anhang erneut extrahieren, um Byte-für-Byte zu vergleichen.
• Nach Verschlüsselung: --meta zeigt "encrypted": true und das Öffnen ohne Passwort schlägt fehl; nach Entschlüsselung entspricht die Textextraktion dem Original.
• Für alles Visuelle (Wasserzeichen, geglättete Formulare) rendern und mit vision_analyze überprüfen.