Xuất tệp với phê duyệt của con người (human-in-the-loop) qua NextPDF Connect

Tổng quan nhanh

Cổng xác nhận có con người tham gia (HITL) giúp ngăn các thao tác ghi ngoài ý muốn vào hệ thống tệp. Khi bạn gọi output_pdf với một file_path, cổng sẽ tạm dừng lời gọi và trả về một thử thách dùng một lần thay vì ghi tệp. Sau khi có người phê duyệt, agent gọi lại với token, và chỉ lúc đó tệp mới được ghi. Đầu ra Base64 (không có file_path) thì không đi qua cổng kiểm soát.

Cài đặt

composer require nextpdf/server

Hãy liên kết một transport. Theo mặc định, output_pdf dùng mức rủi ro Approval Required.

Tổng quan khái niệm

Cổng đánh giá mức rủi ro có hiệu lực: mức sau khi áp dụng mọi ghi đè từ cấu hình hoặc danh tính của bên gọi. Với một công cụ Approval Required:

chế độ base64 — output_pdf không có file_path sẽ được hạ xuống Review và được phép chạy mà không cần xác nhận. Nó không tạo tác dụng phụ nào đối với hệ thống tệp.
chế độ tệp — output_pdf với một file_path vẫn giữ ở mức Approval Required. Cổng lưu một token dùng một lần gắn với tên công cụ, rồi trả về một thử thách. Nếu tệp đích đã tồn tại, nội dung thử thách sẽ kèm cảnh báo ghi đè. Token hết hạn sau một khoảng thời gian cố định.

Trong mọi transport, kết quả của cổng là một phản hồi bình thường. Một yêu cầu phê duyệt đang chờ là điểm tạm dừng quy trình, không phải lỗi transport (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

Bề mặt API

Công cụ	Vai trò	Bậc rủi ro
`create_pdf`	Mở phiên	An toàn
`set_font`, `add_text`	Dựng nội dung	Thận trọng
`output_pdf` (base64)	Trả về nội tuyến; không có cổng	Review
`output_pdf` (tệp)	Ghi ra đĩa; có cổng	Approval Required

Tài liệu tool catalog là nguồn tham chiếu chính thức; các công cụ khả dụng phụ thuộc vào bậc đã cài đặt. Tài liệu HITL risk tiers reference định nghĩa thang rủi ro và cổng.

Mẫu mã — bắt đầu nhanh

create_pdf → dựng nội dung với set_font/add_text.
output_pdf với một file_path → cổng trả về một gói thử thách (tệp không được ghi).
Chuyển tiếp thử thách cho con người.
Khi được phê duyệt, gọi lại output_pdf với cùng các đối số và thêm _confirmation_token đặt thành token từ thử thách → tệp được ghi và phiên bị hủy.

Mẫu mã — bản chạy thực tế

Luôn coi thử thách là một điểm tạm dừng. Đừng thử lại trong vòng lặp, và đừng tự tạo token.
Token chỉ dùng một lần và gắn với tên công cụ. Một token cấp cho output_pdf không thể cấp quyền cho công cụ khác.
Nếu con người từ chối, đừng gọi lại. Để lấy lại các byte mà không ghi tệp, hãy gọi output_pdf ở chế độ base64. Cách này yêu cầu phiên vẫn còn tồn tại, vì vậy hãy dùng destroy: false ở lần thử bị cổng kiểm soát nếu bạn dự kiến sẽ cần phiên đó.
Nếu token hết hạn trước khi được phê duyệt, cổng sẽ tạo thử thách mới. Chuyển tiếp thử thách mới đó.

Trường hợp biên & điểm cần lưu ý

Token không bao giờ được cung cấp. Thao tác vẫn ở trạng thái chờ. Cần có người phê duyệt, rồi chuyển tiếp và gọi lại.
Token đã hết hạn. Cổng tạo thử thách mới. Hãy chuyển tiếp lại thử thách đó.
Sai công cụ. Token gắn với từng công cụ. Việc dùng lại token cho công cụ khác sẽ thất bại, và cổng tạo thử thách mới.
Đường dẫn không tuyệt đối. Bị từ chối trước khi qua cổng vì là đường dẫn không hợp lệ.
Không có quyền ghi / đĩa đầy. Đây là lỗi ghi tệp sau khi đã phê duyệt. Hãy báo lỗi đó ra ngoài. Đừng thử lại một cách mù quáng.
Phiên bị hủy trước khi gọi lại. Nếu một output_pdf trước đó đã dùng destroy: true, phiên đã không còn nữa. Dùng destroy: false khi bạn dự kiến có lượt phê duyệt khứ hồi.

Hiệu năng

Cổng thêm một lần tra cứu kho token và một vòng khứ hồi cho bước phê duyệt của con người. Thời gian thực tế do con người chi phối, không phải server. Profile là structural.

Lưu ý bảo mật

Cổng là ranh giới giữa một agent và hệ thống tệp của server. Nó tồn tại vì việc ghi tệp là một tác dụng phụ không thể đảo ngược và nên có người cấp quyền. Token dùng một lần, gắn với công cụ và bị giới hạn thời gian. Các đối số cố ý không được băm vào token vì các client có thể tuần tự hóa lại JSON với thứ tự khóa khác. Vì vậy ràng buộc là công cụ + nonce + TTL, không phải khớp chính xác đối số. Đừng ghi log token. Hãy coi nó như một bí mật dùng một lần.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Một phê duyệt đang chờ là một phản hồi bình thường, không phải lỗi.	PSR-18	§3
Transport trả về một phản hồi bất kể kết quả ra sao.	PSR-18	§p2

Hướng dẫn này mô tả cơ chế cổng. Nó không khẳng định rằng cổng làm cho bất kỳ thao tác nào trở nên “an toàn”. Cổng khiến một tác dụng phụ được con người cấp quyền.

Bối cảnh thương mại

Không áp dụng — cổng và output_pdf thuộc Core.

Khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Thử thách được đưa lên host dưới dạng kết quả công cụ để con người xác nhận.
REST	Có	Thử thách được trả về trong nội dung phản hồi; gọi lại với token.
gRPC	Có	Đơn hướng (unary); thử thách chính là thông điệp phản hồi; gọi lại với token.

Bậc rủi ro HITL

Thang rủi ro là Safe (0) → Caution (1) → Review (2) → Approval Required (3). Chỉ các công cụ Approval Required mới yêu cầu con người xác nhận. output_pdf là Approval Required. Chế độ base64 hạ nó xuống Review và bỏ qua cổng. Chế độ tệp giữ Approval Required và đưa lời gọi qua cổng kiểm soát. Thang chuẩn và cách phân giải chính sách nằm trong tài liệu HITL risk tiers reference.

Bao JSON của cổng xác nhận

Kết quả của cổng có đúng hai dạng, do cổng xác nhận của server trả ra:

Được phép (Safe/Caution/Review, hoặc một token hợp lệ đã được tiêu thụ):

{ "allowed": true }

Thử thách (Approval Required mà không có token hợp lệ):

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

Khi tệp đích đã tồn tại, nội dung challenge cũng chứa một dòng cảnh báo ghi đè. Gọi lại cùng công cụ với _confirmation_token đặt thành giá trị token sẽ trả về { "allowed": true }, và thao tác tiếp tục. Token chỉ dùng một lần và hết hạn sau khoảng thời gian nêu trong thử thách.