Output berkas dengan keterlibatan manusia melalui NextPDF Connect

Sekilas

Gerbang konfirmasi dengan keterlibatan manusia (human-in-the-loop, HITL) membantu mencegah penulisan ke sistem berkas yang tidak disengaja. Ketika Anda memanggil output_pdf dengan sebuah file_path, gerbang menjeda panggilan tersebut dan mengembalikan tantangan sekali pakai alih-alih langsung menulis berkas. Setelah manusia menyetujuinya, agen memanggil lagi dengan token tersebut, dan baru saat itu berkas ditulis. Output Base64 (tanpa file_path) tidak dikenai gerbang.

Pemasangan

composer require nextpdf/server

Ikat salah satu transport. Secara default, output_pdf menggunakan tingkat risiko Approval Required.

Tinjauan konseptual

Gerbang mengevaluasi tingkat risiko efektif: tingkat yang berlaku setelah semua penggantian (override) dari konfigurasi atau identitas pemanggil diterapkan. Untuk alat berjenis Approval Required:

• mode base64 — output_pdf tanpa file_path diturunkan ke Review dan diizinkan tanpa konfirmasi. Mode ini tidak memiliki efek samping pada sistem berkas.
• mode berkas — output_pdf dengan sebuah file_path tetap berada pada Approval Required. Gerbang menyimpan token sekali pakai yang terikat pada nama alat, lalu mengembalikan sebuah tantangan. Jika berkas target sudah ada, teks tantangan memuat peringatan penimpaan. Token kedaluwarsa setelah jangka waktu tetap.

Di setiap transport, hasil gerbang adalah respons biasa. Persetujuan yang tertunda merupakan jeda alur kerja, bukan kegagalan transport (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

Permukaan API

Alat	Peran	Tingkat risiko
create_pdf	Membuka sesi	Safe
set_font, add_text	Membangun konten	Caution
output_pdf (base64)	Mengembalikan hasil inline; tanpa gerbang	Review
output_pdf (berkas)	Menulis ke disk; dikenai gerbang	Approval Required

Katalog alat adalah sumber rujukan, dan alat yang tersedia bergantung pada tingkatan yang diinstal. Rujukan tingkatan risiko HITL mendefinisikan tangga risiko dan gerbangnya.

Contoh kode — Mulai cepat

1. create_pdf → susun konten dengan set_font/add_text.
2. output_pdf dengan sebuah file_path → gerbang mengembalikan amplop tantangan (berkas tidak ditulis).
3. Teruskan tantangan tersebut kepada manusia.
4. Setelah disetujui, panggil output_pdf lagi dengan argumen yang sama, ditambah _confirmation_token yang disetel ke token dari tantangan → berkas ditulis dan sesi dihancurkan.

Contoh kode — Produksi

• Selalu perlakukan tantangan sebagai jeda. Jangan mencoba ulang dalam loop, dan jangan memalsukan token.
• Token bersifat sekali pakai dan terikat pada nama alat. Token yang diterbitkan untuk output_pdf tidak dapat mengotorisasi alat lain.
• Jika manusia menolak, jangan panggil ulang. Untuk mendapatkan byte tanpa menulis berkas, panggil output_pdf dalam mode base64 sebagai gantinya. Ini mengharuskan sesi masih ada; karena itu, gunakan destroy: false pada percobaan yang dikenai gerbang jika Anda memperkirakan akan membutuhkannya.
• Jika token kedaluwarsa sebelum disetujui, gerbang menerbitkan tantangan baru. Teruskan tantangan yang baru itu.

Kasus khusus & jebakan

• Token tidak pernah disediakan. Operasi tetap tertunda. Manusia harus menyetujuinya, lalu token diteruskan dan panggilan diulang.
• Token kedaluwarsa. Tantangan baru diterbitkan. Teruskan kembali.
• Alat yang salah. Token terikat pada alat. Menggunakannya ulang untuk alat yang berbeda akan gagal, dan tantangan baru diterbitkan.
• Path bukan absolut. Ditolak sebelum mencapai gerbang sebagai path yang tidak valid.
• Tidak ada izin tulis / disk penuh. Ini adalah kegagalan penulisan berkas setelah persetujuan. Laporkan secara eksplisit. Jangan mencoba ulang secara membabi buta.
• Sesi dihancurkan sebelum pemanggilan ulang. Jika panggilan output_pdf sebelumnya menggunakan destroy: true, sesi tersebut sudah hilang. Gunakan destroy: false ketika Anda memperkirakan perlu melakukan putaran bolak-balik persetujuan.

Kinerja

Gerbang menambahkan pencarian ke penyimpanan token dan satu perjalanan bolak-balik untuk persetujuan manusia. Waktu nyata (wall time) ditentukan oleh manusia, bukan server. Profilnya adalah structural.

Catatan keamanan

Gerbang adalah batas antara agen dan sistem berkas server. Gerbang ini ada karena penulisan berkas adalah efek samping yang tidak dapat dibatalkan dan seharusnya diotorisasi oleh manusia. Token bersifat sekali pakai, terikat pada alat, dan dibatasi waktu. Argumen sengaja tidak di-hash ke dalam token karena klien mungkin melakukan serialisasi ulang JSON dengan urutan kunci yang berbeda. Oleh karena itu, pengikatannya adalah alat + nonce + TTL, bukan argumen persis. Jangan mencatat token ke log. Perlakukan token sebagai rahasia sekali pakai.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Persetujuan yang tertunda adalah respons biasa, bukan kegagalan.	PSR-18	§3
Transport mengembalikan respons terlepas dari hasilnya.	PSR-18	§p2

Resep ini menjelaskan mekanisme gerbang. Resep ini tidak menyatakan bahwa gerbang membuat operasi apa pun menjadi “aman”. Gerbang membuat suatu efek samping diotorisasi oleh manusia.

Konteks komersial

Tidak berlaku — gerbang dan output_pdf adalah Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Tantangan ditampilkan ke host sebagai hasil alat untuk dikonfirmasi oleh manusia.
REST	Ya	Tantangan dikembalikan dalam badan respons; panggil ulang dengan token.
gRPC	Ya	Unary; tantangan adalah pesan respons; panggil ulang dengan token.

Tingkatan risiko HITL

Tangga risiko adalah Safe (0) → Caution (1) → Review (2) → Approval Required (3). Hanya alat Approval Required yang memerlukan konfirmasi manusia. output_pdf bersifat Approval Required. Mode base64 menurunkannya menjadi Review dan melewati gerbang. Mode berkas mempertahankan Approval Required dan menerapkan gerbang pada panggilan. Tangga kanonis dan resolusi kebijakan dijelaskan dalam rujukan tingkatan risiko HITL.

Amplop JSON gerbang konfirmasi

Hasil gerbang memiliki tepat dua bentuk, yang diekspos oleh gerbang konfirmasi server:

Diizinkan (Safe/Caution/Review, atau token valid telah dikonsumsi):

{ "allowed": true }

Tantangan (Approval Required tanpa token valid):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Jika berkas target sudah ada, teks challenge juga memuat satu baris peringatan penimpaan. Memanggil ulang alat yang sama dengan _confirmation_token yang disetel ke nilai token akan mengembalikan { "allowed": true }, lalu operasi berlanjut. Token bersifat sekali pakai dan kedaluwarsa setelah rentang waktu yang dinyatakan dalam tantangan.

Lihat juga

• Hello world
• Penanganan kesalahan
• Tingkatan risiko HITL
• Katalog alat