Omgevingsdiagnostiek uitvoeren met NextPDF Connect

In een oogopslag

Controleer of een NextPDF Connect-server gezond is en de mogelijkheden heeft die je workflow nodig heeft voordat je echt werk uitvoert. Gebruik dit als eerste stap in elke agentische pijplijn. Volgens het toolregister van de server zijn de tools diagnostic.doctor, diagnostic.capabilities en diagnostic.verify. Het register stelt ze beschikbaar onder protocolnamen met punten; er bestaat ook een gerelateerde diagnostic.inspect. Allemaal zijn het Core-tools.

Installeren

composer require nextpdf/server

Bind een transport. Je hebt veraPDF alleen nodig voor de optionele compliance-verificatie. Voor structurele verificatie is geen externe tool nodig.

Conceptueel overzicht

diagnostic.doctor retourneert een basisrapport over de omgevingsgezondheid: PHP-versie, geladen extensies, serverversie, het actieve niveau en eventuele waarschuwingen. Behandel status als de poort. Ga verder bij ok, lees warnings bij warning en stop bij error.
diagnostic.capabilities somt de geregistreerde mogelijkheden op, met hun niveau en runtimestatus (available, unavailable, degraded). Het aantal mogelijkheden is afhankelijk van runtime en niveau, dus hardcode geen totaal. Controleer elke mogelijkheid die je workflow nodig heeft.
diagnostic.verify controleert de structurele integriteit: de PDF-header, de EOF-marker en de cross-reference-tabel. Daarbij gaat het om de documentstructuur die via de paginaboom wordt bereikt (ISO 32000-2 §7.5). Met compliance_flavour roept de tool ook veraPDF aan.

Een diagnostisch resultaat is een normaal antwoord binnen elk transport (PHP Standard Recommendation 18, PSR-18 §p2).

API-oppervlak

Tool	Rol	Risiconiveau
`diagnostic.doctor`	Rapport over omgevingsgezondheid	Safe
`diagnostic.capabilities`	Inventaris van mogelijkheden met status	Safe
`diagnostic.verify`	Structurele/compliance-verificatie	Safe
`create_pdf`, `add_text`, `output_pdf`	Een document aan een smoketest onderwerpen	zoals elders gedocumenteerd

Deze namen zijn de protocolnamen uit het register. De toolcatalogus is de gezaghebbende catalogus. Het geïnstalleerde niveau bepaalt welke tools en mogelijkheden bestaan; ga dus nooit uit van een vast aantal tools of mogelijkheden.

Codevoorbeeld — Snel aan de slag

diagnostic.doctor (geen argumenten) → lees status.
diagnostic.capabilities (geen argumenten) → bevestig dat elke benodigde mogelijkheid available is.
create_pdf en vervolgens add_text → een minimaal smoketestdocument.
diagnostic.verify met de document_id → structurele controles.
Optioneel diagnostic.verify met compliance_flavour: "4" → veraPDF.
output_pdf (base64) → vernietig de smoketestsessie.

Codevoorbeeld — Productie

Maak de pijplijn afhankelijk van diagnostic.doctorstatus. Koppel elke workflow-afhankelijkheid aan een specifieke capability-id en controleer op available voordat je de afhankelijke stappen uitvoert. Behandel degraded als een kwaliteitsrisico waarvoor een steekproef nodig is. Voer altijd de structurele diagnostic.verify uit. Voer de compliance-variant alleen uit wanneer conformiteit van belang is. Als veraPDF ontbreekt, retourneert de tool een duidelijke niet-gevonden-uitkomst in plaats van een serverdefect.

Randgevallen en valkuilen

veraPDF afwezig. De compliance-aanroep retourneert een expliciete niet-gevonden-uitkomst. Structurele controles werken nog steeds. Als je compliance-verificatie nodig hebt, installeer dan veraPDF en zorg dat het op het PATH van het serverproces staat.
veraPDF-time-out. Grote documenten kunnen de verificatietime-out overschrijden. Verklein het document of verhoog de time-out in de serverconfiguratie.
degraded mogelijkheid. Een afhankelijkheid is maar gedeeltelijk beschikbaar, waardoor de uitvoerkwaliteit kan dalen. Raadpleeg de serverlogboeken voor de gebruikte fallback.
Doctor error. Aan een kritieke vereiste wordt niet voldaan. Ga niet verder.

Prestaties

Structurele verificatie is snel. Het compliance-pad start veraPDF en blijft binnen de verificatietime-out. Het ruime budget weerspiegelt dat subproces.

Beveiligingsnotities

Diagnostische uitvoer geeft omgevingsdetails prijs: de PHP-versie, extensies en niveau. Behandel die uitvoer als uitsluitend bestemd voor operators en toon deze niet aan niet-vertrouwde aanroepers.

Conformiteit

Bewering	Spec	Clausule	reference_id
Een diagnostisch resultaat is een normaal transportantwoord.	PSR-18	§p2
Structurele integriteit richt zich op de structuur die verankerd is in de paginaboom.	ISO 32000-2	§7.5

De compliance-variant voert veraPDF uit en rapporteert het oordeel ervan. NextPDF beweert zelf geen conformiteit; de validator beslist.

Commerciële context

Niet van toepassing — alle diagnostische tools zijn Core.

Beschikbaarheid per transport

Transport	Beschikbaar	Notities
MCP (stdio)	Ja	Diagnostische resultaten zijn toolresultaten.
REST	Ja	Gezondheidseindpunten worden gekoppeld aan deze tools.
gRPC	Ja	Unary; het resultaat bevat dezelfde statusvelden.

HITL-risiconiveau

Alle drie de diagnostische tools zijn Safe: alleen-lezen en zonder neveneffecten. Ze activeren nooit de bevestigingspoort. De smoketest-output_pdf gebruikt base64-modus (Review, geen poort).

JSON-envelop van de bevestigingspoort

Diagnostiek vereist nooit een poort.

{ "allowed": true }