Ejecutar diagnósticos del entorno en NextPDF Connect

En resumen

Confirmar que un servidor NextPDF Connect esté en buen estado y disponga de las capacidades que necesita el flujo de trabajo antes de realizar el trabajo real. Este es el primer paso recomendado en cualquier flujo agéntico. Las herramientas, verificadas de nuevo contra el registro de herramientas del servidor, son diagnostic.doctor, diagnostic.capabilities y diagnostic.verify. El registro las expone con nombres de protocolo separados por puntos, y también existe una diagnostic.inspect relacionada. Todas son Core.

Instalación

composer require nextpdf/server

Vincular un transporte. veraPDF solo es necesario para el paso opcional de verificación de cumplimiento. La verificación estructural no requiere ninguna herramienta externa.

Visión conceptual

diagnostic.doctor devuelve un informe de estado básico: versión de PHP, extensiones cargadas, versión del servidor, nivel activo y cualquier advertencia. Tratar status como la puerta de control. Continuar con ok, leer warnings con warning y detenerse con error.
diagnostic.capabilities enumera las capacidades registradas con su nivel y su estado en tiempo de ejecución (available, unavailable, degraded). El número de capacidades depende del entorno de ejecución y del nivel, por lo que no se debe codificar un total fijo. Comprobar una por una cada capacidad de la que dependa el flujo de trabajo.
diagnostic.verify comprueba la integridad estructural: el encabezado del PDF, el marcador EOF y la tabla de referencias cruzadas. Esta es la estructura del documento a la que se accede a través del árbol de páginas (ISO 32000-2 §7.5). Con compliance_flavour, también invoca veraPDF.

Un resultado de diagnóstico es una respuesta normal en todos los transportes (PSR-18 §p2).

Superficie de la API

Herramienta	Rol	Nivel de riesgo
`diagnostic.doctor`	Informe de estado del entorno	Seguro
`diagnostic.capabilities`	Inventario de capacidades con estado	Seguro
`diagnostic.verify`	Verificación estructural / de cumplimiento	Seguro
`create_pdf`, `add_text`, `output_pdf`	Probar un documento con una prueba de humo	Como se documenta en otra sección

Estos nombres son los nombres de protocolo del registro. El catálogo de herramientas es el catálogo de referencia. Las herramientas y capacidades disponibles dependen del nivel instalado, así que nunca se debe afirmar un número fijo de herramientas o capacidades.

Ejemplo de código — Inicio rápido

diagnostic.doctor (sin argumentos) → leer status.
diagnostic.capabilities (sin argumentos) → confirmar que cada capacidad necesaria está available.
create_pdf y luego add_text → un documento mínimo para prueba de humo.
diagnostic.verify con el document_id → comprobaciones estructurales.
Opcionalmente diagnostic.verify con compliance_flavour: "4" → veraPDF.
output_pdf (base64) → destruir la sesión de prueba de humo.

Ejemplo de código — Producción

Controlar la canalización mediante diagnostic.doctorstatus. Asignar cada dependencia del flujo de trabajo a un id de capacidad específico y confirmar available antes de ejecutar los pasos dependientes. Tratar degraded como un riesgo de calidad que justifica una comprobación puntual. Ejecutar siempre la diagnostic.verify estructural. Ejecutar la variante de cumplimiento solo donde la conformidad sea relevante y aceptar que, si veraPDF está ausente, devuelve un resultado claro de «no encontrado» en lugar de un defecto del servidor.

Casos límite y trampas

veraPDF ausente. La llamada de cumplimiento devuelve un resultado explícito de «no encontrado». Las comprobaciones estructurales siguen funcionando. Si se necesita la verificación de cumplimiento, instalar veraPDF y ponerlo en el PATH del proceso del servidor.
Tiempo de espera de veraPDF agotado. Los documentos grandes pueden agotar el tiempo de espera de la verificación. Reducir el tamaño del documento o aumentar el tiempo de espera en la configuración del servidor.
Capacidad degraded. Una dependencia solo está parcialmente disponible, por lo que la calidad de la salida puede disminuir. Consultar los registros del servidor para ver el mecanismo de reserva en uso.
Doctor error. No se cumple un requisito crítico. No continuar.

Rendimiento

La verificación estructural es rápida. La ruta de cumplimiento invoca veraPDF y está limitada por el tiempo de espera de la verificación. El presupuesto amplio refleja ese subproceso.

Notas de seguridad

La salida de diagnóstico revela detalles del entorno: la versión de PHP, las extensiones y el nivel. Tratarla como información exclusiva del operador y no exponerla a llamantes no confiables.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Un resultado de diagnóstico es una respuesta de transporte normal.	PSR-18	§p2
La integridad estructural se centra en la estructura anclada en el árbol de páginas.	ISO 32000-2	§7.5

La variante de cumplimiento ejecuta veraPDF e informa de su veredicto. NextPDF no afirma la conformidad por sí mismo. El validador es quien decide.

Contexto comercial

No aplicable: todas las herramientas de diagnóstico son Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	Los resultados de diagnóstico son resultados de herramienta.
REST	Sí	Los puntos de conexión de estado se asignan a estas herramientas.
gRPC	Sí	Llamada unaria; el resultado contiene los mismos campos de estado.

Nivel de riesgo HITL

Las tres herramientas de diagnóstico son Seguras: de solo lectura, sin efectos secundarios. Nunca activan la puerta de confirmación. El output_pdf de la prueba de humo está en modo base64 (Revisión, sin puerta).

Envoltorio JSON de la puerta de confirmación

Los diagnósticos nunca activan la puerta.

{ "allowed": true }