การเขียนไฟล์เอาต์พุตแบบ human-in-the-loop ด้วย NextPDF Connect

ภาพรวมโดยย่อ

เกตการยืนยันแบบ human-in-the-loop (HITL) ช่วยป้องกันการเขียนไฟล์ระบบโดยไม่ตั้งใจ เมื่อเรียก output_pdf พร้อม file_path เกตจะพักการเรียกไว้ชั่วคราวและส่งคืน challenge แบบใช้ได้ครั้งเดียวแทนการเขียนไฟล์ เมื่อมนุษย์อนุมัติแล้ว เอเจนต์จึงเรียกซ้ำพร้อม token และเขียนไฟล์ได้ เอาต์พุตแบบ Base64 (ไม่มี file_path) จะไม่ถูกควบคุมด้วยเกต

การติดตั้ง

composer require nextpdf/server

ผูก transport การตั้งค่าเริ่มต้นกำหนดให้ output_pdf ใช้ระดับความเสี่ยง Approval Required

ภาพรวมเชิงแนวคิด

เกตจะประเมินระดับความเสี่ยงที่มีผลจริง ซึ่งเป็นระดับหลังนำการแทนที่จาก config หรือข้อมูลระบุตัวตนของผู้เรียกมาใช้แล้ว สำหรับเครื่องมือระดับ Approval Required:

โหมด base64 — output_pdf ที่ไม่มี file_path จะถูกลดระดับเป็น Review และได้รับอนุญาตได้โดยไม่ต้องยืนยัน โหมดนี้ไม่มีผลข้างเคียงต่อระบบไฟล์
โหมด file — output_pdf ที่มี file_path จะยังอยู่ที่ระดับ Approval Required เกตจะเก็บ token แบบใช้ได้ครั้งเดียวที่ผูกกับชื่อเครื่องมือ แล้วส่งคืน challenge หากไฟล์ปลายทางมีอยู่แล้ว ข้อความ challenge จะมีคำเตือนเรื่องการเขียนทับรวมอยู่ด้วย token จะหมดอายุหลังครบช่วงเวลาคงที่ที่กำหนดไว้

ในทุก transport ผลลัพธ์จากเกตถือเป็นการตอบสนองปกติ สถานะรอการอนุมัติคือการหยุดเวิร์กโฟลว์ชั่วคราว ไม่ใช่ความล้มเหลวของ transport (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2)

พื้นผิว API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชัน	Safe
`set_font`, `add_text`	สร้างเนื้อหา	Caution
`output_pdf` (base64)	ส่งคืนแบบ inline โดยไม่มีเกต	Review
`output_pdf` (file)	เขียนลงดิสก์ ควบคุมด้วยเกต	Approval Required

ใช้แค็ตตาล็อกเครื่องมือเป็นแหล่งข้อมูลอ้างอิงหลัก เครื่องมือที่ใช้ได้ขึ้นอยู่กับ tier ที่ติดตั้งไว้ ส่วนเอกสารอ้างอิงระดับความเสี่ยง HITLจะนิยามลำดับขั้นความเสี่ยงและเกต

ตัวอย่างโค้ด — เริ่มใช้งานอย่างรวดเร็ว

create_pdf → สร้างเนื้อหาด้วย set_font/add_text ตามลำดับ
output_pdf ที่มี file_path → เกตจะส่งคืน challenge envelope (ไฟล์จะไม่ถูกเขียน)
ส่งต่อ challenge ไปยังมนุษย์
เมื่อได้รับการอนุมัติ ให้เรียก output_pdf ซ้ำด้วยอาร์กิวเมนต์ชุดเดิม พร้อมตั้งค่า _confirmation_token เป็น token จาก challenge → ไฟล์จะถูกเขียนและเซสชันจะถูกทำลาย

ตัวอย่างโค้ด — การใช้งานจริง

ให้ถือว่า challenge เป็นการหยุดชั่วคราวเสมอ อย่าเรียกซ้ำในลูป และอย่าสร้าง token ขึ้นมาเอง
token ใช้ได้ครั้งเดียวและผูกกับชื่อเครื่องมือ token ที่ออกให้สำหรับ output_pdf จะอนุญาตเครื่องมืออื่นไม่ได้
หากมนุษย์ปฏิเสธ อย่าเรียกซ้ำ หากต้องการดึงไบต์กลับมาโดยไม่เขียนไฟล์ ให้เรียก output_pdf ในโหมด base64 แทน วิธีนี้กำหนดให้เซสชันยังคงอยู่ ดังนั้นให้ใช้ destroy: false ในการเรียกที่ถูกควบคุมด้วยเกต หากคาดว่าจะต้องใช้
หาก token หมดอายุก่อนการอนุมัติ เกตจะออก challenge ใหม่ ให้ส่งต่อ challenge ใหม่

กรณีขอบและข้อควรระวัง

ไม่ได้ให้ token การดำเนินการจะยังรออยู่ มนุษย์ต้องอนุมัติ จากนั้นจึงส่งต่อและเรียกซ้ำ
token หมดอายุ จะมีการออก challenge ใหม่ ให้ส่งต่ออีกครั้ง
ใช้กับเครื่องมือผิดรายการ token ผูกกับเครื่องมือ การนำไปใช้ซ้ำกับเครื่องมืออื่นจะล้มเหลว และจะมีการออก challenge ใหม่
พาธที่ไม่ใช่พาธสัมบูรณ์ จะถูกปฏิเสธก่อนถึงขั้นเกตในฐานะพาธที่ไม่ถูกต้อง
ไม่มีสิทธิ์การเขียน / ดิสก์เต็ม กรณีนี้คือความล้มเหลวในการเขียนไฟล์หลังการอนุมัติ ให้แสดงข้อผิดพลาดนี้ออกมา อย่าลองใหม่โดยไม่ตรวจสอบ
เซสชันถูกทำลายก่อนการเรียกซ้ำ หากการเรียก output_pdf ครั้งก่อนหน้าใช้ destroy: true เซสชันจะหายไป ใช้ destroy: false เมื่อคาดว่าจะมีรอบอนุมัติแบบไปกลับ

ประสิทธิภาพ

เกตเพิ่มการค้นหาใน token store และเพิ่มรอบไป-กลับหนึ่งครั้งสำหรับการอนุมัติจากมนุษย์ wall time ขึ้นอยู่กับมนุษย์ ไม่ใช่เซิร์ฟเวอร์ โปรไฟล์คือ structural (แบบโครงสร้าง)

หมายเหตุด้านความปลอดภัย

เกตคือเส้นแบ่งระหว่างเอเจนต์กับระบบไฟล์ของเซิร์ฟเวอร์ เกตมีอยู่เพราะการเขียนไฟล์เป็นผลข้างเคียงที่ย้อนกลับไม่ได้ ซึ่งมนุษย์ควรเป็นผู้อนุญาต token ใช้ได้ครั้งเดียว ผูกกับเครื่องมือ และมีอายุจำกัด โดยตั้งใจแล้ว อาร์กิวเมนต์จะไม่ถูกนำไปแฮชรวมไว้ใน token เพราะไคลเอนต์อาจ serialize JSON ใหม่ด้วยลำดับคีย์ที่ต่างออกไป ดังนั้นการผูกจึงเป็น tool + nonce + TTL ไม่ใช่การจับคู่แบบอาร์กิวเมนต์ตรงกันทุกประการ อย่าบันทึก token ลงใน log ให้ถือว่า token เป็นความลับแบบใช้ครั้งเดียว

ความสอดคล้อง

ข้อความระบุ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
สถานะรอการอนุมัติเป็นการตอบสนองปกติ ไม่ใช่ความล้มเหลว	PSR-18	§3
transport จะส่งคืนการตอบสนองไม่ว่าผลลัพธ์จะเป็นอย่างไร	PSR-18	§p2

แนวทางนี้อธิบายกลไกของเกต แนวทางนี้ไม่ได้ยืนยันว่าเกตทำให้การดำเนินการใดๆ “secure” เกตทำให้ผลข้างเคียงได้รับการอนุญาตจากมนุษย์

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — เกตและ output_pdf เป็น Core

ความพร้อมใช้งานของ transport

ทรานสปอร์ต (Transport)	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	challenge จะแสดงต่อโฮสต์ในรูปแบบผลลัพธ์ของเครื่องมือเพื่อให้มนุษย์ยืนยัน
REST	ใช่	challenge จะถูกส่งคืนใน response body แล้วเรียกซ้ำด้วย token
gRPC	ใช่	แบบ unary โดย challenge อยู่ในข้อความตอบกลับ แล้วเรียกซ้ำด้วย token

ระดับความเสี่ยง HITL

ลำดับขั้นความเสี่ยงคือ Safe (0) → Caution (1) → Review (2) → Approval Required (3) มีเพียงเครื่องมือระดับ Approval Required เท่านั้นที่ต้องใช้การยืนยันจากมนุษย์ output_pdf อยู่ในระดับ Approval Required โหมด base64 จะลดระดับเป็น Review และข้ามเกต โหมด file จะคงระดับ Approval Required และควบคุมการเรียกด้วยเกต ลำดับขั้นมาตรฐานและการแก้ไขนโยบายระบุไว้ในเอกสารอ้างอิงระดับความเสี่ยง HITL

JSON envelope ของเกตการยืนยัน

ผลลัพธ์ของเกตที่เกตการยืนยันของเซิร์ฟเวอร์เปิดเผยมีเพียงสองรูปแบบ:

อนุญาต (Safe/Caution/Review หรือมีการใช้ token ที่ถูกต้อง):

{ "allowed": true }

Challenge (Approval Required โดยไม่มี 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>"
}

เมื่อไฟล์ปลายทางมีอยู่แล้ว ข้อความ challenge จะมีบรรทัดคำเตือนเรื่องการเขียนทับรวมอยู่ด้วย การเรียกเครื่องมือเดิมซ้ำโดยตั้งค่า _confirmation_token เป็นค่าของ token จะส่งคืน { "allowed": true } และการดำเนินการจะทำงานต่อ token ใช้ได้ครั้งเดียวและหมดอายุหลังครบช่วงเวลาที่ระบุไว้ใน challenge