Umgebungsdiagnose mit NextPDF Connect ausführen

Auf einen Blick

Stellen Sie sicher, dass ein NextPDF Connect-Server funktionsfähig ist und über die Funktionen verfügt, die Ihr Workflow benötigt, bevor Sie die eigentliche Arbeit aufnehmen. Dies ist der empfohlene erste Schritt in jeder agentenbasierten Pipeline. Laut erneutem Abgleich mit der Werkzeug-Registry des Servers heißen die Werkzeuge diagnostic.doctor, diagnostic.capabilities und diagnostic.verify. Die Registry stellt sie unter punktgetrennten Protokollnamen bereit; außerdem gibt es das verwandte diagnostic.inspect. Alle gehören zu Core.

Installation

composer require nextpdf/server

Binden Sie einen Transport an. veraPDF wird nur für den optionalen Schritt der Konformitätsprüfung benötigt. Die strukturelle Prüfung benötigt kein externes Werkzeug.

Konzeptioneller Überblick

diagnostic.doctor liefert einen grundlegenden Zustandsbericht: PHP-Version, geladene Erweiterungen, Serverversion, aktive Stufe und etwaige Warnungen. Behandeln Sie status als Schranke. Fahren Sie bei ok fort, werten Sie bei warning die warnings aus und halten Sie bei error an.
diagnostic.capabilities listet die registrierten Funktionen mit ihrer Stufe und ihrem Laufzeitstatus auf (available, unavailable, degraded). Da die Anzahl der Funktionen laufzeit- und stufenabhängig ist, codieren Sie keine Gesamtzahl fest. Prüfen Sie jede Funktion, von der Ihr Workflow abhängt, einzeln.
diagnostic.verify prüft die strukturelle Integrität: den PDF-Header, die EOF-Markierung und die Querverweistabelle. Gemeint ist die Dokumentstruktur, die über den Seitenbaum erreicht wird (ISO 32000-2 §7.5). Mit compliance_flavour ruft es zusätzlich veraPDF auf.

Ein Diagnoseergebnis ist bei jedem Transport eine normale Antwort (PSR-18 §p2).

API-Oberfläche

Werkzeug	Rolle	Risikostufe
`diagnostic.doctor`	Bericht über den Umgebungszustand	Sicher
`diagnostic.capabilities`	Funktionsinventar mit Status	Sicher
`diagnostic.verify`	Struktur-/Konformitätsprüfung	Sicher
`create_pdf`, `add_text`, `output_pdf`	Einen Smoke-Test für ein Dokument durchführen	wie andernorts dokumentiert

Diese Namen sind die Protokollnamen der Registry. Der Werkzeugkatalog ist der maßgebliche Katalog. Da die vorhandenen Werkzeuge und Funktionen von der installierten Stufe abhängen, nennen Sie niemals eine feste Werkzeug- oder Funktionsanzahl.

Codebeispiel — Schnelleinstieg

diagnostic.doctor (ohne Argumente) → status lesen.
diagnostic.capabilities (ohne Argumente) → bestätigen, dass jede benötigte Funktion available ist.
create_pdf, dann add_text → ein minimales Smoke-Dokument.
diagnostic.verify mit der document_id → strukturelle Prüfungen.
Optional diagnostic.verify mit compliance_flavour: "4" → veraPDF.
output_pdf (base64) → die Smoke-Sitzung beenden.

Codebeispiel — Produktion

Geben Sie die Pipeline anhand von diagnostic.doctorstatus frei. Ordnen Sie jede Workflow-Abhängigkeit einer bestimmten Funktions-ID zu und stellen Sie sicher, dass sie available ist, bevor Sie die abhängigen Schritte ausführen. Behandeln Sie degraded als Qualitätsrisiko, das eine Stichprobenprüfung rechtfertigt. Führen Sie stets die strukturelle Variante von diagnostic.verify aus. Führen Sie die Konformitätsvariante nur dort aus, wo Konformität von Bedeutung ist, und nehmen Sie in Kauf, dass ein fehlendes veraPDF ein eindeutiges Nicht-gefunden-Ergebnis statt eines Serverfehlers zurückgibt.

Randfälle & Stolperfallen

veraPDF fehlt. Der Konformitätsaufruf gibt ein explizites Nicht-gefunden-Ergebnis zurück. Strukturelle Prüfungen funktionieren weiterhin. Wenn Sie eine Konformitätsprüfung benötigen, installieren Sie veraPDF und nehmen Sie es in den PATH des Serverprozesses auf.
veraPDF-Zeitüberschreitung. Große Dokumente können die Zeitüberschreitung der Prüfung auslösen. Verringern Sie die Dokumentgröße oder erhöhen Sie die Zeitüberschreitung in der Serverkonfiguration.
degraded-Funktion. Eine Abhängigkeit ist nur teilweise verfügbar, sodass die Ausgabequalität sinken kann. Prüfen Sie die Serverprotokolle auf den verwendeten Fallback.
Doctor-error. Eine kritische Anforderung ist nicht erfüllt. Fahren Sie nicht fort.

Performance

Die strukturelle Prüfung ist schnell. Der Konformitätspfad startet veraPDF und ist durch die Zeitüberschreitung der Prüfung begrenzt. Das großzügig bemessene Budget spiegelt diesen Unterprozess wider.

Sicherheitshinweise

Die Diagnoseausgabe gibt Umgebungsdetails preis: die PHP-Version, Erweiterungen und Stufe. Behandeln Sie sie als ausschließlich für Betreiber bestimmte Information und machen Sie sie nicht für nicht vertrauenswürdige Aufrufer zugänglich.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ein Diagnoseergebnis ist eine normale Transportantwort.	PSR-18	§p2
Die strukturelle Integrität bezieht sich auf die durch den Seitenbaum verankerte Struktur.	ISO 32000-2	§7.5

Die Konformitätsvariante führt veraPDF aus und meldet dessen Urteil. NextPDF macht selbst keine Konformitätsaussage. Der Validator entscheidet.

Kommerzieller Kontext

Nicht anwendbar — alle Diagnosewerkzeuge gehören zu Core.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Diagnoseergebnisse sind Werkzeugergebnisse.
REST	Ja	Health-Endpunkte werden auf diese Werkzeuge abgebildet.
gRPC	Ja	Unär; das Ergebnis enthält dieselben Statusfelder.

HITL-Risikostufe

Alle drei Diagnosewerkzeuge sind Sicher: schreibgeschützt und ohne Seiteneffekt. Sie lösen niemals die Bestätigungsschranke aus. Der Smoke-Test output_pdf ist im base64-Modus (Review, keine Schranke).

JSON-Umschlag der Bestätigungsschranke

Diagnosen aktivieren niemals eine Schranke.

{ "allowed": true }