Zatwierdzanie wyjścia plikowego z udziałem człowieka w pętli za pośrednictwem NextPDF Connect

W skrócie

Brama potwierdzenia z udziałem człowieka w pętli (HITL) pomaga zapobiegać niezamierzonym zapisom w systemie plików. Gdy wywołasz output_pdf z parametrem file_path, brama wstrzymuje wywołanie i zamiast zapisać plik, zwraca jednorazowe wyzwanie. Po zatwierdzeniu przez człowieka agent wywołuje narzędzie ponownie z tokenem; dopiero wtedy plik zostaje zapisany. Dane wyjściowe base64 (bez file_path) nie podlegają bramie.

Instalacja

composer require nextpdf/server

Powiąż transport. Domyślnie output_pdf korzysta z poziomu ryzyka Approval Required.

Przegląd koncepcyjny

Brama ocenia efektywny poziom ryzyka, czyli poziom po uwzględnieniu ewentualnego nadpisania wynikającego z konfiguracji lub tożsamości wywołującego. W przypadku narzędzia na poziomie Approval Required:

tryb base64 — output_pdf bez file_path zostaje obniżony do Review i dozwolony bez potwierdzenia. Nie powoduje żadnego efektu ubocznego w systemie plików.
tryb plikowy — output_pdf z file_path pozostaje na poziomie Approval Required. Brama zapisuje jednorazowy token powiązany z nazwą narzędzia, a następnie zwraca wyzwanie. Jeśli plik docelowy już istnieje, tekst wyzwania zawiera ostrzeżenie o nadpisaniu. Token wygasa po upływie ustalonego okna czasowego.

W każdym transporcie wynik bramy jest normalną odpowiedzią. Oczekujące zatwierdzenie to wstrzymanie przepływu pracy, a nie awaria transportu (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwarcie sesji	Safe
`set_font`, `add_text`	Budowanie treści	Caution
`output_pdf` (base64)	Zwrot w treści; bez bramy	Review
`output_pdf` (plik)	Zapis na dysk; z bramą	Approval Required

Katalog narzędzi jest autorytatywnym źródłem informacji, a dostępne narzędzia zależą od zainstalowanej edycji. Dokumentacja poziomów ryzyka HITL definiuje drabinę ryzyka i mechanizm bramy.

Przykład kodu — szybki start

create_pdf → zbuduj treść za pomocą set_font/add_text.
output_pdf z file_path → brama zwraca kopertę wyzwania (plik nie zostaje zapisany).
Przekaż wyzwanie do zatwierdzenia przez człowieka.
Po zatwierdzeniu wywołaj output_pdf ponownie z tymi samymi argumentami oraz _confirmation_token ustawionym na token z wyzwania → plik zostaje zapisany, a sesja zostaje zniszczona.

Przykład kodu — wersja produkcyjna

Zawsze traktuj wyzwanie jako wstrzymanie. Nie ponawiaj w pętli i nie twórz tokenu samodzielnie.
Token jest jednorazowy i powiązany z nazwą narzędzia. Token wystawiony dla output_pdf nie może autoryzować żadnego innego narzędzia.
Jeśli człowiek odrzuci wyzwanie, nie wywołuj ponownie. Aby uzyskać bajty bez zapisywania pliku, wywołaj zamiast tego output_pdf w trybie base64. Wymaga to, aby sesja nadal istniała, więc użyj destroy: false przy próbie objętej bramą, jeśli spodziewasz się, że będzie potrzebna.
Jeśli token wygaśnie przed zatwierdzeniem, brama wystawia nowe wyzwanie. Przekaż je.

Przypadki brzegowe i pułapki

Token nigdy nie został podany. Operacja pozostaje oczekująca. Najpierw człowiek musi zatwierdzić; następnie przekaż token i wywołaj ponownie.
Wygasły token. Zostaje wystawione nowe wyzwanie. Przekaż je ponownie.
Niewłaściwe narzędzie. Tokeny są powiązane z narzędziem. Ponowne użycie tokenu dla innego narzędzia kończy się niepowodzeniem i powoduje wystawienie nowego wyzwania.
Ścieżka nieabsolutna. Zostaje odrzucona przed bramą jako nieprawidłowa ścieżka.
Brak uprawnień do zapisu / pełny dysk. To błąd zapisu pliku po zatwierdzeniu. Zgłoś go. Nie ponawiaj na ślepo.
Sesja zniszczona przed ponownym wywołaniem. Jeśli wcześniejsze output_pdf użyło destroy: true, sesja jest utracona. Użyj destroy: false, gdy spodziewasz się etapu zatwierdzenia.

Wydajność

Brama dodaje wyszukiwanie w magazynie tokenów oraz etap zatwierdzenia przez człowieka. O czasie zegarowym decyduje człowiek, nie serwer. Profil to structural.

Uwagi dotyczące bezpieczeństwa

Brama jest granicą między agentem a systemem plików serwera. Istnieje, ponieważ zapis pliku jest nieodwracalnym efektem ubocznym, który powinien autoryzować człowiek. Token jest jednorazowy, powiązany z narzędziem i ograniczony czasowo. Argumenty celowo nie są haszowane do tokenu, ponieważ klienci mogą ponownie serializować JSON z inną kolejnością kluczy. Powiązanie to zatem narzędzie + nonce + TTL, a nie dokładne dopasowanie argumentów. Nie zapisuj tokenu w dziennikach. Traktuj go jak jednorazowy sekret.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Oczekujące zatwierdzenie to normalna odpowiedź, a nie awaria.	PSR-18	§3
Transport zwraca odpowiedź niezależnie od wyniku.	PSR-18	§p2

Ten przepis opisuje mechanizm bramy. Nie twierdzi, że brama czyni jakąkolwiek operację „bezpieczną”. Brama sprawia, że efekt uboczny autoryzuje człowiek.

Kontekst komercyjny

Nie dotyczy — brama oraz output_pdf należą do edycji Core.

Dostępność transportów

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Wyzwanie jest udostępniane hostowi jako wynik narzędzia, aby człowiek mógł je potwierdzić.
REST	Tak	Wyzwanie jest zwracane w treści odpowiedzi; wywołaj ponownie z tokenem.
gRPC	Tak	Wywołanie unarne; wyzwanie jest komunikatem odpowiedzi; wywołaj ponownie z tokenem.

Poziom ryzyka HITL

Drabina ryzyka to Safe (0) → Caution (1) → Review (2) → Approval Required (3). Tylko narzędzia Approval Required wymagają potwierdzenia przez człowieka. output_pdf ma poziom Approval Required. Tryb base64 obniża go do Review i pomija bramę. Tryb plikowy zachowuje Approval Required i przepuszcza wywołanie przez bramę. Kanoniczną drabinę i zasady rozstrzygania opisuje dokumentacja poziomów ryzyka HITL.

Koperta JSON bramy potwierdzenia

Wynik bramy ma dokładnie dwa kształty, udostępniane przez bramę potwierdzenia serwera:

Dozwolone (Safe/Caution/Review lub skonsumowanie ważnego tokenu):

{ "allowed": true }

Wyzwanie (Approval Required bez ważnego tokenu):

{
  "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>"
}

Gdy plik docelowy już istnieje, tekst challenge zawiera również wiersz ostrzeżenia o nadpisaniu. Ponowne wywołanie tego samego narzędzia z _confirmation_token ustawionym na wartość token zwraca { "allowed": true }, a operacja jest kontynuowana. Token jest jednorazowy i wygasa po upływie okna czasowego podanego w wyzwaniu.