Human-in-the-Loop-Dateiausgabe mit NextPDF Connect

Auf einen Blick

Das Human-in-the-Loop-Bestätigungs-Gate (HITL) schützt vor unbeabsichtigten Schreibvorgängen im Dateisystem. Wird output_pdf mit einem file_path aufgerufen, fängt das Gate den Aufruf ab und gibt eine einmalig verwendbare Challenge zurück, anstatt die Datei zu schreiben. Nach der Genehmigung durch einen Menschen ruft der Agent das Tool mit dem Token erneut auf; erst dann wird die Datei geschrieben. Die base64-Ausgabe (ohne file_path) läuft nicht über das Gate.

Installation

composer require nextpdf/server

Binden Sie einen Transport ein. Standardmäßig ist output_pdf mit der Risikostufe „Genehmigung erforderlich“ eingestuft.

Konzeptioneller Überblick

Das Gate bewertet die effektive Risikostufe: die Stufe, die nach einem etwaigen Konfigurations- oder Aufruferidentitäts-Override verbleibt. Für ein Tool mit „Genehmigung erforderlich“ gilt:

base64-Modus — output_pdf ohne file_path wird auf Review herabgestuft und ohne Bestätigung zugelassen. Es entsteht kein Seiteneffekt im Dateisystem.
file-Modus — output_pdf mit einem file_path bleibt in der Risikostufe „Genehmigung erforderlich“. Das Gate speichert ein einmalig verwendbares, an den Toolnamen gebundenes Token und gibt eine Challenge zurück. Existiert die Zieldatei bereits, enthält der Challenge-Text eine Überschreibwarnung. Das Token läuft nach einem festen Zeitfenster ab.

Bei jedem Transport ist das Gate-Ergebnis eine normale Antwort. Eine anstehende Genehmigung ist eine Workflow-Pause, kein Transportfehler (PSR-18 §3; PSR-18 §p2).

API-Oberfläche

Tool	Rolle	Risikostufe
`create_pdf`	Sitzung öffnen	Sicher
`set_font`, `add_text`	Inhalt aufbauen	Vorsicht
`output_pdf` (base64)	Inline zurückgeben; kein Gate	Review
`output_pdf` (file)	Auf die Festplatte schreiben; Gate greift	Genehmigung erforderlich

Der Tool-Katalog ist maßgeblich; die verfügbaren Tools hängen von der installierten Stufe ab. Die Risikoleiter und das Gate sind in der Referenz zu den HITL-Risikostufen definiert.

Codebeispiel — Schnellstart

create_pdf → Inhalt mit set_font/add_text aufbauen.
output_pdf mit einem file_path → das Gate gibt einen Challenge-Envelope zurück (die Datei wird nicht geschrieben).
Geben Sie die Challenge an den Menschen weiter.
Bei Genehmigung rufen Sie output_pdf mit denselben Argumenten erneut auf und ergänzen _confirmation_token, gesetzt auf das Token aus der Challenge → die Datei wird geschrieben und die Sitzung wird zerstört.

Codebeispiel — Produktion

Behandeln Sie die Challenge immer als Pause. Wiederholen Sie den Aufruf nicht in einer Schleife und erfinden Sie kein Token.
Das Token ist einmalig verwendbar und an den Toolnamen gebunden. Ein für output_pdf ausgegebenes Token kann kein anderes Tool autorisieren.
Wenn der Mensch ablehnt, rufen Sie nicht erneut auf. Um die Bytes ohne Dateischreibvorgang zurückzuerhalten, rufen Sie output_pdf stattdessen im base64-Modus auf. Dafür muss die Sitzung noch existieren; verwenden Sie daher destroy: false beim durch das Gate angehaltenen Versuch, wenn Sie sie voraussichtlich noch benötigen.
Läuft das Token vor der Genehmigung ab, gibt das Gate eine frische Challenge aus. Geben Sie die neue Challenge weiter.

Grenzfälle & Fallstricke

Token nie bereitgestellt. Die Operation bleibt anstehend. Der Mensch muss genehmigen; anschließend muss das Token weitergegeben und der Aufruf wiederholt werden.
Abgelaufenes Token. Eine neue Challenge wird ausgegeben. Geben Sie sie erneut weiter.
Falsches Tool. Token sind tool-gebunden. Eine Wiederverwendung für ein anderes Tool schlägt fehl, und eine neue Challenge wird ausgegeben.
Nicht absoluter Pfad. Der Pfad wird vor dem Gate als ungültig abgewiesen.
Keine Schreibberechtigung / Festplatte voll. Dies ist ein Dateischreibfehler nach der Genehmigung. Zeigen Sie ihn an. Wiederholen Sie den Vorgang nicht blind.
Sitzung vor dem erneuten Aufruf zerstört. Wenn ein vorheriges output_pdf destroy: true verwendet hat, ist die Sitzung nicht mehr vorhanden. Verwenden Sie destroy: false, wenn Sie den Genehmigungs-Roundtrip erwarten.

Performance

Das Gate fügt einen Lookup im Token-Store und einen Roundtrip für die menschliche Genehmigung hinzu. Die Wartezeit wird vom Menschen bestimmt, nicht vom Server. Das Profil ist structural.

Sicherheitshinweise

Das Gate bildet die Grenze zwischen einem Agenten und dem Dateisystem des Servers. Es ist notwendig, weil ein Dateischreibvorgang ein unumkehrbarer Seiteneffekt ist, den ein Mensch autorisieren sollte. Das Token ist einmalig verwendbar, an das Tool gebunden und zeitlich begrenzt. Argumente werden bewusst nicht in das Token gehasht, weil Clients JSON mit abweichender Schlüsselreihenfolge neu serialisieren können. Die Bindung ist daher Tool + Nonce + TTL, nicht argumentgenau. Protokollieren Sie das Token nicht. Behandeln Sie es als einmaliges Geheimnis.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Eine anstehende Genehmigung ist eine normale Antwort, kein Fehlschlag.	PSR-18	§3
Der Transport gibt unabhängig vom Ergebnis eine Antwort zurück.	PSR-18	§p2

Dieses Rezept beschreibt den Gate-Mechanismus. Es behauptet nicht, dass das Gate irgendeine Operation „sicher“ macht. Das Gate sorgt dafür, dass ein Seiteneffekt durch einen Menschen autorisiert ist.

Kommerzieller Kontext

Nicht anwendbar — das Gate und output_pdf gehören zu Core.

Transport-Verfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Die Challenge wird dem Host als Tool-Ergebnis angezeigt, damit der Mensch sie bestätigen kann.
REST	Ja	Die Challenge wird im Antwort-Body zurückgegeben; führen Sie den Aufruf mit dem Token erneut aus.
gRPC	Ja	Unär; die Challenge ist die Antwortnachricht; führen Sie den Aufruf mit dem Token erneut aus.

HITL-Risikostufe

Die Risikoleiter ist Sicher (0) → Vorsicht (1) → Review (2) → Genehmigung erforderlich (3). Nur Tools mit „Genehmigung erforderlich“ verlangen eine menschliche Bestätigung. output_pdf ist als Genehmigung erforderlich eingestuft. Der base64-Modus stuft es auf Review herab und überspringt das Gate. Der file-Modus bleibt bei Genehmigung erforderlich und läuft über das Gate. Die kanonische Leiter und die Policy-Auflösung stehen in der Referenz zu den HITL-Risikostufen.

JSON-Envelope des Bestätigungs-Gates

Das Gate-Ergebnis hat genau zwei Formen, die das Bestätigungs-Gate des Servers ausgibt:

Erlaubt (Sicher/Vorsicht/Review oder nach Verbrauch eines gültigen Tokens):

{ "allowed": true }

Challenge (Genehmigung erforderlich ohne gültiges Token):

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

Existiert die Zieldatei bereits, enthält der challenge-Text zusätzlich eine Zeile mit einer Überschreibwarnung. Ein erneuter Aufruf desselben Tools mit _confirmation_token, gesetzt auf den Wert von token, gibt { "allowed": true } zurück, und die Operation wird fortgesetzt. Das Token ist einmalig verwendbar und läuft nach dem in der Challenge genannten Zeitfenster ab.