PDFCompress

PDFCompress ist ein quelloffener, strukturerhaltender PDF-Kompressor für Menschen und KI-Agenten. Es verwendet unabhängig verifizierte WPS-ähnliche Bildvoreinstellungen, ruft jedoch keine WPS-DLLs auf, vertreibt sie nicht und ist nicht von einem WPS-Konto abhängig.

Seine Kernregel ist einfach:

Text und Vektoren bleiben Text und Vektoren; nur überdimensionierte gerasterte Bilder werden heruntergerechnet; das Ergebnis wird vor der Veröffentlichung verifiziert.

Funktionen

• Berechnet die Bildauflösung aus der tatsächlichen PDF-Transformationsmatrix, einschließlich Bildern, die in Form-XObjects verschachtelt sind.

• Wendet WPS-kompatible Einstellungen high, standard, medium und low an.

• Fügt ein archive-safe-Profil für Preis-, Ausschreibungs- und Archiv-Anhänge hinzu.

• Erhält die Quelldatei und schreibt atomar in einen anderen Ausgabepfad.

• Erhält standardmäßig Lesezeichen, Anhänge, Annotationen, Schriften und die sichtbare PDF-Struktur.

• Lehnt signierte PDFs ab, es sei denn, die Ungültigmachung der Signatur wird ausdrücklich akzeptiert.

• Verifiziert Seitenzahl, Seitenboxen und extrahierbaren Text nach jedem Kandidaten.

• Unterstützt eine Zielgröße, ohne das vorherige JPEG-Ergebnis wiederholt neu zu komprimieren.

• Bietet eine Python-API, CLI, gemeinsame Agent-Skill, Codex-Plugin, Claude-Code-Plugin und MCP-Server.

Related MCP server: MokuPDF

Installation

Python 3.11 oder neuer ist erforderlich.

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

Mit uv:

uv tool install --editable ".[mcp]"

Installieren Sie das getaggte GitHub-Release ohne Klonen:

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

Schnellstart

Vor dem Komprimieren analysieren:

pdfcompress analyze "input.pdf" --json

Mit dem WPS-kompatiblen High-Quality-Profil komprimieren:

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

Für einen formellen Anhang, der unter 4 MB liegen muss:

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

Ein vorhandenes Paar verifizieren:

pdfcompress verify "input.pdf" "output.pdf" --json

Voreinstellungen

Die vier WPS-kompatiblen Werte wurden aus den generateCompressArgs-Zweigen des installierten Komprimierungs-Plugins rekonstruiert und in der begleitenden Analyse-Notiz unabhängig dokumentiert. Der exakte WPS-Resampling-Kernel, die Chroma-Subsampling-Richtlinie und die vollständige Optimierer-Bitmaske werden weder kopiert noch beansprucht.

Verhalten bei Zielgröße

Wenn --target-size-mb angegeben wird, versucht PDFCompress progressiv stärkere Profile, beginnend mit der angeforderten Voreinstellung. Jeder Versuch öffnet die ursprüngliche PDF erneut:

archive-safe → high → standard → medium → low

Der erste verifizierte Kandidat unter dem Limit wird ausgewählt. Wenn kein Profil das Limit erreicht, wird der kleinste verifizierte Kandidat mit einer Warnung zurückgegeben. PDFCompress rasiert nicht stillschweigend Seiten, löscht Schriften oder entfernt Anhänge, um das Ziel zu erzwingen.

Agent-Integration

Claude Code

Installieren Sie zuerst das Python-Paket, dann laden Sie das Plugin für eine Sitzung:

cd PDFCompress
claude --plugin-dir .

Rufen Sie die Skill als /pdfcompress:pdf-compress auf oder bitten Sie Claude, eine PDF zu komprimieren. Claude Code lädt auch die .mcp.json des Plugins und startet pdfcompress-mcp über stdio.

Codex

Das Repository enthält ein validiertes .codex-plugin/plugin.json, ein gemeinsames skills/-Verzeichnis und .mcp.json. Es kann aus einem lokalen Codex-Marketplace installiert werden, oder die Skill kann in ein persönliches/Projekt-Skill-Verzeichnis kopiert werden. Das Kernpaket muss installiert sein, damit pdfcompress-mcp im PATH liegt.

Generische MCP-Clients

Verwenden Sie diese stdio-Konfiguration:

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

MCP-Werkzeuge:

• analyze_pdf(path, password?)

• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)

• verify_pdf(input_path, output_path)

Open-Source-Forschung und übernommene Ideen

Siehe THIRD_PARTY_NOTICES.md für Lizenzgrenzen.

Sicherheit und Einschränkungen

• Das Umschreiben einer PDF macht digitale Signaturen ungültig. Standardmäßig wird gestoppt.

• Verschlüsselte PDFs erfordern ein Passwort; die Verschlüsselung bleibt bei der Ausgabe erhalten.

• Version 0.1 überspringt Bildmasken, Transparenz, benutzerdefinierte Decode-Arrays, ungewöhnliche Farbräume und Nicht-8-Bit-Bilder, anstatt eine visuelle Beeinträchtigung zu riskieren.

• Textgleichheitsprüfungen verwenden extrahierbaren Text. Gescannte Seiten ohne OCR erfordern weiterhin eine visuelle Qualitätskontrolle.

• Ein Pixel-Render-Vergleich wird empfohlen, bevor das Werkzeug für rechtlich bedeutsame oder sehr komplexe Dokumente verwendet wird.

• Wenn ein Kandidat nicht kleiner als die Quelle ist, gibt PDFCompress eine bytegenaue Kopie der Quelle aus und meldet, dass keine sichere Größenreduzierung gefunden wurde.

Validierter Beispiel

Auf einer 12-seitigen, bildintensiven PDF, die während der Entwicklung verwendet wurde:

Bei einem Render-Vergleich mit 100 DPI stimmten alle Seitenabmessungen überein; das archive-safe-Ergebnis hatte eine mittlere RGB-RMS-Differenz pro Seite von 0,388 und ein Maximum von 3,002 auf einer 0–255-Kanalskala. Dies ist ein Validierungsfall, keine universelle Qualitätsgarantie.

Entwicklung

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

Tests erzeugen ihre eigene PDF mit durchsuchbarem Text und einem hochauflösenden Bild. Es sind keine privaten Dokumente im Repository enthalten.

Lizenz

PDFCompress wird unter der MIT-Lizenz veröffentlicht. Drittanbieter-Abhängigkeiten behalten ihre eigenen Lizenzen.

Siehe das Änderungsprotokoll und die GitHub-Releases für versionierte Änderungen und herunterladbare Python-Pakete.