Jalankan diagnostik lingkungan di NextPDF Connect

Sekilas pandang

Pastikan server NextPDF Connect sehat dan memiliki kapabilitas yang dibutuhkan alur kerja Anda sebelum menjalankan pekerjaan sebenarnya. Gunakan langkah ini sebagai langkah pertama dalam setiap alur kerja agentik. Alat-alat tersebut, yang diverifikasi terhadap registri alat server, adalah diagnostic.doctor, diagnostic.capabilities, dan diagnostic.verify. Registri mengeksposnya dengan nama protokol bertitik, dengan diagnostic.inspect sebagai alat terkait. Semuanya adalah alat Core.

Pemasangan

composer require nextpdf/server

Ikatkan sebuah transport. Anda hanya memerlukan veraPDF untuk langkah verifikasi kepatuhan yang opsional. Verifikasi struktural tidak memerlukan alat eksternal.

Tinjauan konseptual

diagnostic.doctor mengembalikan laporan kesehatan dasar: versi PHP, ekstensi yang dimuat, versi server, tier aktif, serta setiap peringatan. Perlakukan status sebagai gerbang. Lanjutkan saat ok, baca warnings saat warning, dan berhenti saat error.
diagnostic.capabilities mencantumkan kapabilitas terdaftar beserta tier dan status runtime-nya (available, unavailable, degraded). Jumlah kapabilitas bersifat bergantung pada runtime dan tier, jadi jangan menetapkan total secara hard-code. Periksa setiap kapabilitas yang dibutuhkan alur kerja Anda.
diagnostic.verify memeriksa integritas struktural: header PDF, penanda EOF, dan tabel cross-reference. Pemeriksaan ini menyasar struktur dokumen yang dijangkau melalui pohon halaman (ISO 32000-2 §7.5). Dengan compliance_flavour, alat ini juga memanggil veraPDF.

Hasil diagnostik adalah respons normal di setiap transport (PHP Standard Recommendation 18, PSR-18 §p2).

Permukaan API

Alat	Peran	Tier risiko
`diagnostic.doctor`	Laporan kesehatan lingkungan	Aman
`diagnostic.capabilities`	Inventaris kapabilitas dengan status	Aman
`diagnostic.verify`	Verifikasi struktural / kepatuhan	Aman
`create_pdf`, `add_text`, `output_pdf`	Uji asap (smoke-test) untuk sebuah dokumen	sebagaimana didokumentasikan di tempat lain

Nama-nama ini adalah nama protokol dari registri. Katalog alat adalah katalog acuan. Tier yang terpasang menentukan alat dan kapabilitas yang tersedia, jadi jangan pernah menetapkan jumlah alat atau kapabilitas secara tetap.

Contoh kode — Mulai cepat

diagnostic.doctor (tanpa argumen) → baca status.
diagnostic.capabilities (tanpa argumen) → pastikan setiap kapabilitas yang dibutuhkan berstatus available.
create_pdf lalu add_text → dokumen uji asap minimal.
diagnostic.verify dengan document_id → pemeriksaan struktural.
Secara opsional diagnostic.verify dengan compliance_flavour: "4" → veraPDF.
output_pdf (base64) → hapus sesi uji asap.

Contoh kode — Produksi

Jadikan diagnostic.doctorstatus sebagai gerbang bagi alur. Petakan setiap dependensi alur kerja ke id kapabilitas tertentu, lalu pastikan statusnya available sebelum Anda menjalankan langkah yang bergantung padanya. Perlakukan degraded sebagai risiko kualitas yang memerlukan pemeriksaan sampel. Selalu jalankan diagnostic.verify struktural. Jalankan varian kepatuhan hanya jika konformitas memang diperlukan. Jika veraPDF tidak ada, alat ini mengembalikan hasil not-found yang jelas, bukan cacat server.

Kasus tepi & jebakan

veraPDF tidak ada. Panggilan kepatuhan mengembalikan hasil not-found yang eksplisit. Pemeriksaan struktural tetap berfungsi. Jika Anda membutuhkan verifikasi kepatuhan, pasang veraPDF dan letakkan di PATH proses server.
Batas waktu veraPDF terlampaui. Dokumen berukuran besar dapat memicu batas waktu verifikasi. Kurangi ukuran dokumen atau naikkan batas waktu pada konfigurasi server.
Kapabilitas degraded. Dependensi hanya tersedia sebagian, sehingga kualitas keluaran dapat menurun. Periksa log server untuk mengetahui fallback yang digunakan.
Doctor error. Persyaratan kritis tidak terpenuhi. Jangan lanjutkan.

Kinerja

Verifikasi struktural berlangsung cepat. Jalur kepatuhan menjalankan veraPDF sebagai subproses dan tetap berada dalam batas waktu verifikasi. Anggaran yang longgar tersebut mencerminkan subproses itu.

Catatan keamanan

Keluaran diagnostik mengungkap detail lingkungan: versi PHP, ekstensi, dan tier. Perlakukan informasi ini sebagai khusus operator, dan jangan tampilkan kepada pemanggil yang tidak tepercaya.

Konformitas

Pernyataan	Spesifikasi	Klausa	reference_id
Hasil diagnostik adalah respons transport normal.	PSR-18	§p2
Integritas struktural menyasar struktur yang bertumpu pada pohon halaman.	ISO 32000-2	§7.5

Varian kepatuhan menjalankan veraPDF dan melaporkan putusannya. NextPDF tidak menyatakan konformitas itu sendiri. Validatorlah yang memutuskan.

Konteks komersial

Tidak berlaku — semua alat diagnostik adalah Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Hasil diagnostik adalah hasil alat.
REST	Ya	Endpoint kesehatan dipetakan ke alat-alat ini.
gRPC	Ya	Unary; hasilnya membawa bidang status yang sama.

Tier risiko HITL

Ketiga alat diagnostik bersifat Aman: hanya-baca, tanpa efek samping. Alat-alat tersebut tidak pernah memicu gerbang konfirmasi. output_pdf uji asap berada dalam mode base64 (Review, tanpa gerbang).

Amplop JSON gerbang konfirmasi

Diagnostik tidak pernah menerapkan gerbang.

{ "allowed": true }