Execute diagnósticos de ambiente no NextPDF Connect

Visão geral

Antes de executar o trabalho real, confirme que um servidor NextPDF Connect está íntegro e oferece os recursos de que o fluxo de trabalho precisa. Use esta verificação como a primeira etapa em qualquer pipeline baseado em agentes. As ferramentas, verificadas contra o registro de ferramentas do servidor, são diagnostic.doctor, diagnostic.capabilities e diagnostic.verify. O registro as expõe com nomes de protocolo separados por pontos, e também existe uma diagnostic.inspect relacionada. Todas são ferramentas Core.

Instalação

composer require nextpdf/server

Vincule um transporte. Você só precisa do veraPDF para a etapa opcional de verificação de conformidade. A verificação estrutural não precisa de uma ferramenta externa.

Visão conceitual

diagnostic.doctor retorna um relatório básico de integridade: versão do PHP, extensões carregadas, versão do servidor, tier ativo e eventuais avisos. Trate status como o ponto de controle. Prossiga com ok, leia warnings com warning e pare com error.
diagnostic.capabilities lista os recursos registrados com seu tier e status de runtime (available, unavailable, degraded). O número de recursos é dependente do runtime e do tier, portanto não fixe um total no código. Verifique cada recurso de que o fluxo de trabalho precisa.
diagnostic.verify verifica a integridade estrutural: o cabeçalho do PDF, o marcador EOF e a tabela de referência cruzada. O alvo é a estrutura do documento alcançada pela árvore de páginas (ISO 32000-2 §7.5). Com compliance_flavour, ela também invoca o veraPDF.

Um resultado de diagnóstico é uma resposta normal em qualquer transporte (PHP Standard Recommendation 18, PSR-18 §p2).

Superfície da API

Ferramenta	Função	Tier de risco
`diagnostic.doctor`	Relatório de integridade do ambiente	Seguro
`diagnostic.capabilities`	Inventário de recursos com status	Seguro
`diagnostic.verify`	Verificação estrutural / de conformidade	Seguro
`create_pdf`, `add_text`, `output_pdf`	Executar um teste rápido de um documento	conforme documentado em outro lugar

Esses são os nomes de protocolo registrados. O catálogo de ferramentas é o catálogo de referência. O tier instalado determina quais ferramentas e recursos existem, portanto nunca afirme uma contagem fixa de ferramentas ou recursos.

Exemplo de código — Início rápido

diagnostic.doctor (sem argumentos) → leia status.
diagnostic.capabilities (sem argumentos) → confirme que cada recurso necessário está available.
create_pdf e, em seguida, add_text → um documento de teste mínimo.
diagnostic.verify com o document_id → verificações estruturais.
Opcionalmente, diagnostic.verify com compliance_flavour: "4" → veraPDF.
output_pdf (base64) → descarte a sessão de teste.

Exemplo de código — Produção

Condicione a execução do pipeline a diagnostic.doctorstatus. Mapeie cada dependência do fluxo de trabalho para um id de recurso específico e verifique available antes de executar as etapas dependentes. Trate degraded como um risco de qualidade que exige uma verificação pontual. Sempre execute a verificação estrutural de diagnostic.verify. Execute a variante de conformidade apenas quando a conformidade for relevante. Se o veraPDF estiver ausente, a ferramenta retorna um resultado claro de não encontrado em vez de um defeito do servidor.

Casos extremos e pegadinhas

veraPDF ausente. A chamada de conformidade retorna um resultado explícito de não encontrado. As verificações estruturais continuam funcionando. Se você precisar de verificação de conformidade, instale o veraPDF e coloque-o no PATH do processo do servidor.
Tempo limite do veraPDF. Documentos grandes podem ultrapassar o tempo limite de verificação. Reduza o tamanho do documento ou aumente o tempo limite na configuração do servidor.
Recurso degraded. Uma dependência está apenas parcialmente disponível; portanto, a qualidade da saída pode cair. Consulte os logs do servidor para ver o fallback em uso.
Doctor error. Um requisito crítico não foi atendido. Não prossiga.

Desempenho

A verificação estrutural é rápida. O caminho de conformidade inicia o veraPDF e respeita o tempo limite de verificação. O orçamento amplo reflete esse subprocesso.

Notas de segurança

A saída de diagnóstico revela detalhes do ambiente: a versão do PHP, as extensões e o tier. Trate-a como restrita aos operadores e não a exiba a chamadores não confiáveis.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Um resultado de diagnóstico é uma resposta normal do transporte.	PSR-18	§p2
A integridade estrutural visa a estrutura ancorada na árvore de páginas.	ISO 32000-2	§7.5

A variante de conformidade executa o veraPDF e relata o veredito dele. O NextPDF não afirma conformidade por conta própria. O validador decide.

Contexto comercial

Não se aplica — todas as ferramentas de diagnóstico são Core.

Disponibilidade por transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	Os resultados de diagnóstico são resultados de ferramentas.
REST	Sim	Os endpoints de integridade são mapeados para essas ferramentas.
gRPC	Sim	Chamada unária; o resultado carrega os mesmos campos de status.

Tier de risco HITL

As três ferramentas de diagnóstico são Seguro: somente leitura, sem efeitos colaterais. Elas nunca acionam o ponto de controle de confirmação. O output_pdf do teste rápido está em modo base64 (Review, sem ponto de controle).

Envelope JSON do ponto de controle de confirmação

Os diagnósticos nunca aplicam um ponto de controle.

{ "allowed": true }